doc6://? syn6://? 6doc://? Not as verbose yet still more indicative that you're getting Perl 6 documentation.
(After sitting and looking at them a minute or two I like the last most out of my three. But that's just MHO, of course :)
Afterthought: Of course given that it's going to something different and has a bit different syntax than the normal doc:// perhaps it's a good thing that the prefix is more different from that.
| [reply] |
I don't like any of them. I'd expect doc6:// (or 6doc://) to go to perldoc for Perl 6 (and I hope we won't need that, being able to just use Perl documentation because I hope that site will host both Perl5 and Perl6 documentation). I don't see the Perl 6 design documents as being equivalent to the Perl 5 manuals. I expect there to be Perl 6 manuals written at some point that don't focus on the design nor the difference between Perl 5 and Perl6 but just thorough document how to use Perl 6. That documentation will likely be based on the exeg (or perhaps not since they seem to be getting quite out-of-date), but they'll be different than any of the AES.
Using syn for all of apoc, synop, and exeg doesn't work for me either. If apoc, synop, and exeg weren't all so hard to spell and so hard to consistently abbreviate (as in people natually abbreviating them the same, which I don't see happening), then they'd be good choices for what to put in front of ://, but I don't think syn6:// works, in particular.
Corion's patch used syn:// for the following code:
if (! $escsuffix) {
("http://perlcabal.org/syn/", "Perl 6 Synopses")
} elsif ($escsuffix =~ m!^(S\d\d)(?:[:/](.*))$!) {
my ($page,$esc) = $2;
my $display = $suffix;
if ($suffix =~ m!^S\d\d([:/].*)$!) {
$display = $2;
};
("http://perlcabal.org/syn/S$page.html#$esc", "$page$display")
} else {
# error in spec, just pass it through with a prefix
"http://perlcabal.org/syn/$escsuffix"
};
which suffers from ignoring the apocs and exegs (perhaps those are currently less important but as the design solidifies again, they will likely become more important again).
And I think we need more research on how anchors work. For example, I think the POD parsers use some rule for turning lots of characters into underscores and we need to encode those same rules here.
| [reply]
[d/l] |
In practice I've never felt the urge to link to the apocalypses or exegeses. If you want to explain the language to somebody, or implement it, the synopsis are by far the more important documents. So I think that's not a pressing issue.
The line anchors match #line_(\d+).
The section anchors are a bit more tricky, I tried to track how they are generated. The POD is parsed by smartlinks.pl, the HTML generated by Pod::Simple::HTML.
There the line anchors are piped through section_name_tidy, which is defined as follows:
sub section_name_tidy {
my($self, $section) = @_;
$section =~ tr/ /_/;
$section =~ tr/\x00-\x1F\x80-\x9F//d if 'A' eq chr(65); # drop crazy
+ characters
$section = $self->unicode_escape_url($section);
$section = '_' unless length $section;
return $section;
}
# and
sub unicode_escape_url {
my($self, $string) = @_;
$string =~ s/([^\x00-\xFF])/'('.ord($1).')'/eg;
# Turn char 1234 into "(1234)"
return $string;
}
I haven't found the place yet where whitespaces are substituted by underscores :(, but doing that the operations above, followed by a normal url encode should be sufficient. Hopefully.
| [reply]
[d/l]
[select] |
If apoc, synop, and exeg weren't all so hard to spell
I used exegetical in a game of Probe once. They got all but the g and then stuck for
many turns thereafter.
| [reply] |
Your proposed syntax is fine, you should just take a closer look at how the link targets look like (I can't see the patch, so I don't know if you have done it right there).
And of course you've got a point with [\w+] links being on-site, I just didn't abstract from the syntax used on IRC.
| [reply]
[d/l] |