Parenthesize link text

[khwilliamson]

Whenever I see something in the documentation like:

"do_close"
Close an I/O stream. This implements Perl ""close"" in perlfunc.

I go "Huh"

That in perlfunc is a non-sequitur. On the other hand, the text could have been written as

"do_close"
Close an I/O stream. See ""close"" in perlfunc.

which makes sense.

For years, I I toyed with solutions that didn't involve Pod::Simple learning to parse English (and French or whatever) to decide what text to insert that makes it clear as to what is happening. And finally, I came up with this one which makes it

"do_close"
Close an I/O stream. This implements Perl ""close"" (in perlfunc).

This isn't ideal, but it is a lot better than currently. Note that the insertion of in presumes that the pod is in English. That is bad right off the bat, and maybe we should ditch it, and make it

"do_close"
Close an I/O stream. This implements Perl ""close"" (perlfunc).

Various tests have hard-coded the precise text expected the generated pod output to be, and those fail this PR. A few are in cpan modules shipped with blead. I chose not to fix those until the final PR is nailed down

[khwilliamson]

@haarg, @Grinnz comments?

[haarg]

perlpodspec says:

Pod processors must now treat "text|"-less links as follows:

L<name>         =>  L<name|name>
L</section>     =>  L<"section"|/section>
L<name/section> =>  L<"section" in name|name/section>

So I don't think this can be changed in this way.

[Grinnz]

IMO it would be better to write your own custom link text when the default is not grammatically suitable. e.g. L<"close"|perlfunc/close>

[khwilliamson]

@haarg, thanks for finding that.

perlpodspec says that pod can be written in any language that Encode handles. It can't be the Right Thing to require the insertion of English into a document written in some other language, whose readership potentially knows nothing of English. I really doubt that this consequence of that requirement was considered when writing it.

I skimmed perlpodspec, and saw no other instance where any language-specific text is to be inserted.

I assert then that the spec is defective and therefore should be changed. Whether that is doable or not, I don't know. @allisonrandal @theory @rjbs, please weigh in.

Any change should not require parsers to change their current behavior to correspond. But I do think the current method should be listed as discouraged

[khwilliamson]

@Grinnz yes, but people won't always do that, and so there should be a reasonable default when they don't. A default that minimizes confusion to the (innocent) reader.

[Grinnz]

The current default is reasonable, as you showed an example of. It doesn't need to be reasonable in every possible case.

[Grinnz]

And further, there is a significant amount of documentation now existing which relies on the current default for its presentation, which any change could look less appealing, so would be a regression.

[haarg]

Parenthesis used in that way is also not something that is universal across languages.

I'm not sure that there is an appropriate alternate default formatting. While ideally we shouldn't prioritize english, most Pod documentation is currently written in english and much of it has been written with the assumption that these links will be formatted using "in".

A Pod::Simple subclass can change how these are formatted. Possibly we could add that as a core feature not needing a specific subclass to enable.