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" 
};
[download]

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.

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;
}
[download]

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.

---

Perl 6 in German

And the apocs and exegs don't have line number anchors. Which leans things more towards having separate synop://, apoc://, and exeg://, except that such would just add more confusion to how to use the canonical "S03" abbreviations.

So nevermind that idea. We'll just support [aes://A01:121] under the assumption that as soon as someone starts using such it probably means that the particular apoc has been updated to have line-number anchors.

I haven't found the place yet where whitespaces are substituted by underscores :(

That would be the third line you quoted: (:

  $section =~ tr/ /_/;
[download]

I could have sworn that I'd seen other punctuation marks turned into underscores, leading to sometimes fairly long runs of underscores, but the code you quoted doesn't appear to do that. Sorry, I've got to get back to my day job or I'd look for examples to dis/prove that.

But, since nobody is complaining about "aes://" at this point, we can probably produce another patch (or, I hope, Corion will just update his).

- tye        

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.