Perl 6
Smart Linking: Revision 7

Smart Links refer to a special syntax used in the test suite which connect a particular part of a test script with a specific part of the Perl 6 specification.

A smart link looks like this in a test script:

 # L<S29/Math::Trig>

After submitting this to the Subversion repository, after a few minutes a cron script will update a copy of the Specification which references these links. See the Math::Trig spec for an example.

Smart links are especially valuable for a language that is in development. The help answer these important questions:

  • Has this feature been tested? If you don't see references to tests from the spec, there's a possibility the feature is not only untested, but unimplemented!
  • Are there duplicates tests for this feature? If you see more than one test script linked in one place, it's possible there are duplicate tests, and the tests suite can be simplified.
  • Is there a spec for this feature? On the other hand, if you find a test without a smart link, it may simply not have one yet, or the feature may be unspec'ed. It was discovered that the basic function "say" did not have a formal definition through this kind of review.

Smart Linking Status

As of September 11th, 2006, 263 test scripts have at least one smart link, but 349 do not.
Help wanted!

How to help with smart linking.

To help with this, you mostly just some motivation to help, and commit access
to the pugs tree. Ask for it on #perl6 if you don't have it.

perldoc util/smartlinks.pl explains the details. Here are practical tips to get started.

1. Review the complete list of files with no smart links:

grep -RL 'L<' t/* | $PAGER

2. Pick a directory that needs work. For example, in builtins/lists, 11 files need updated now.

cd builtins/lists

3. Open these files

$EDITOR `grep -L 'L<' *.t`

4. Add at least one appropriate smart link, possibly using the online specification as a reference. The nice thing about working in one directory at one time, is that all of the smart links in the directory me be similar.

5. Check your smart links

~/pugs/util/smartlinks.pl --check *.t

Hopefully, you'll get some useful debugging feedback if there is a problem. You can also specify --fast if you don't want to update your local copy of Synopses at every run.

6. Commit your work!
Usually this is svk commit or svn commit.

Ask for help on the #perl6 IRC channel if you get stuck.


Upload Files

Click "Browse" to find the file you want to upload. When you click "Upload file" your file will be uploaded and added to the list of attachments for this page.

Maximum file size: 50MB

 
 
 
File Name Author Date Uploaded Size

Save Page As

Enter a meaningful and distinctive title for your page.

Page Title:

Tip: You'll be able to find this page later by using the title you choose.

Page Already Exists

There is already a page named XXX. Would you like to:

Save with a different name:

Save the page with the name "XXX"

Append your text to the bottom of the existing page named: "XXX"

Upload Files

Click "Browse" to find the file you want to upload. When you click "Add file" this file will be added to the list of attachments for this page, and uploaded when you save the page.

 
 
 
Add Tags

Enter a tag and click "Add tag". The tag will be saved when you save the page.

Tag: 

Suggestions: