Let POD editors define custom section IDs to be used in URLs

[smls]

Imagine a /language/faq-why.pod doc page with a section header defined as:

=head2 Why sigils? Couldn't you do without them?

And now consider the following two URLs:

http://doc.perl6.org/language/faq-why#Why_sigils%3F_Couldn%27t_you_do_without_them%3F

http://doc.perl6.org/language/faq-why#sigils

The first is how the section would have to be linked to, the way things are now. The second is how I would like it to be.

Obviously, this would require some kind of markup in the POD to specify the desired ID. Maybe something along the lines of:

=head2 :id<sigils> Why sigils? Couldn't you do without them?

...but I don't know enough about the POD6 format to know whether that syntax even makes sense, or what the right approach would be.

Comments / suggestions?

PS: Since p6doc simply lets Rakudo parse the .pod files, we can't just invent syntax willy-nilly. It has to somehow hook into the features that the POD6 format officially provides.

[ShimmerFairy]

I see two potential options for this: the first is that X<index> codes are taken to create anchors for the page, so your header would look something like this:

=head2 X<|sigils> Why sigils? Couldn't you do without them?

If however Pod::To::HTML isn't allowed to interpret index entry markers as usable anchors, the other choice is to define a module for M<> codes. The usage would be something like this:

=head2 M<Anchor:sigils> Why sigils? Couldn't you do without them?

To make this work, you'd need a DOC use Pod::Anchor; (assuming that's the module the functionality lives in) before the document. I'm not sure how well rakudo support this option.

[smls]

How would Pod::Anchor tell Pod::To::HTML what to do with the custom field though?

I don't just want to place additional hidden anchors to the HTML pages, I want them to actually be the official IDs of those sections so that they'll be used in the auto-generated table-of-contents and other auto-generated links. (Because how else will users discover them?)

[ab5tract]

Keep in mind also that Pod is not just about HTML. pdoc should be able to use/display/interact with these anchors as well.

On Wed, Aug 5, 2015 at 11:57 PM, Sam S [email protected] wrote:

How would Pod::Anchor tell Pod::To::HTML what to do with the custom field though?

I don't just want to place additional hidden anchors to the HTML pages, I want them to actually be the official IDs of those sections so that they'll be used in the auto-generated table-of-contents and other auto-generated links. (Because how else will users discover them?)

— Reply to this email directly or view it on GitHub https://github.com/perl6/doc/issues/111#issuecomment-128161948.

[ab5tract]

sorry, p6doc

On Thu, Aug 6, 2015 at 2:50 PM, John Haltiwanger <[email protected]

wrote:

Keep in mind also that Pod is not just about HTML. pdoc should be able to use/display/interact with these anchors as well.

On Wed, Aug 5, 2015 at 11:57 PM, Sam S [email protected] wrote:

How would Pod::Anchor tell Pod::To::HTML what to do with the custom field though?

I don't just want to place additional hidden anchors to the HTML pages, I want them to actually be the official IDs of those sections so that they'll be used in the auto-generated table-of-contents and other auto-generated links. (Because how else will users discover them?)

— Reply to this email directly or view it on GitHub https://github.com/perl6/doc/issues/111#issuecomment-128161948.

[JJ]

Not really sure about this one. Is it about definition of the Perl6 pod language?

[JJ]

@AlexDaniel this is the second-oldest issue and I see you have participated. What's the status now? Any idea?

[JJ]

OK, 14 days, nothing new here, and my impression is still that it's a suggestion for change in the POD6 language itself, which is kind of not related to this repository. So I'm closing this; if someone decides to open it back, please do so by creating an actionable (in this repo) issue and assigning it to someone, preferably him or herself.

[AlexDaniel]

Any idea?

Maybe, but I'm finding it a bit hard to follow the progress on this repo, things are moving too fast :) @JJ++, great work.

That being said, we still have the issue, and it's quite relevant. Links like https://docs.perl6.org/language/faq#Why_should_I_learn_Perl_6?_What's_so_great_about_it? are indeed unacceptable, and there's still no way to specify the id from POD so that it'd be possible to create shorter anchored links.

Ping @tbrowder, maybe you have the guts to implement this?

[tbrowder]

it’s on my TODO list (right behind my HONEYDO list)

(Note: this should be done, see my last comment below.)

[JJ]

Still looks like something unrelated to the documentation. If it's part of the POD6 specs, we should close it.

[AlexDaniel]

@JJ not exactly so. First, issues should be moved if they belong somewhere else, not just closed.

Secondly, we have this exact problem in the doc repo here, when you have to use ridiculously long anchors when linking to things. So in a way it belongs here.

[tbrowder]

I think the section config option (e.g., :id<my-desired-link-id>) is usable now as long as all the rendering tools know what is to be done with it. We would all have to agree with the actual config key name for the link (e.g., :id, :link, :ref, or something else). And what if no id key is provided or its value has already been used, do what is done now?

I just tested this, and it works. Note that configuration formation only works on a delimited pod block (UPDATE: it also works on paragraph blocks) so we must use one of those formats:

=begin pod
=begin head2 :id<my-desired-link-id>
A BigInt
=end head2
A very big integer.
=end pod
say $=pod[0].contents[0].config<id>;

Running the script yields:

my-desired-link-id

Summarizing: the language already allows for a suitable config key to identify a link (but the implementation was not available until late last year), it is now up to the community and renderer authors to agree on what that is and how to use it.

[JJ]

Anchor links are generated by htmlify.p6. So another notch for #1823, whose number I should know by heart right now.

[JJ]

I'm of two minds about this particular issue. Although it would be, a priori, a good idea to be able to do this, if we start changing anchors we will make #561 worse than it is now and we will also break external references, as #1838 indicates. It would be a good amount of work that could be used only in new links, and with lots of caveats of never, ever, use for old headers.

[AlexDaniel]

But it would be great if it was at least possible to do it for new sections.

[JJ]

@AlexDaniel we would have to take stock of old sections, also. Most links are broken anyway... It might be better to start from scratch. I really don't know. The problem with this isi that it's so convoluted, involving htmlify and .htaccess that I barely know where to start.

[coke]

@finanalyst, any input on this one?

[coke]

This feature is covered in rakudoc2 with A<> to create an alias.

Closing this request, we can consider adding individual aliases once the new spec lands.