At 12:01 PM 2001-10-01 -0700, Russ Allbery wrote: >Jarkko Hietaniemi <[EMAIL PROTECTED]> writes: > [..the following is what perlpodspec draft 1 said...] >>> In case of LE<lt>...> codes with no "text|" part in them, older >>> formatters have exhibited great variation in actually displaying the >>> link or cross reference. For example, LE<lt>crontab(5)> would render >>> as "the C<crontab(5)> manpage", or "in the C<crontab(5)> manpage" or >>> just "C<crontab(5)>". > >> Might I suggest that in the interests of easier internationalisation and >> localisation the habit of automatically and more importantly, >> unconditionally, inserting English words be strongly discouraged, or at >> least easily overrideable? > >Getting rid of the "the ... manpage" thing is on my list of changes to >make in the next version of pod2man and pod2text. I'm not sure what to do >about things like "section" and "entry" though. Suggestions?
By popular demand, I made perlpodspec draft 2 describe the rendering with a "must" (whereas I think I previously had a "should", and vacillated on L<foo/bar> links): << In case of LE<lt>...> codes with no "text|" part in them, older formatters have exhibited great variation in actually displaying the link or cross reference. For example, LE<lt>crontab(5)> would render as "the C<crontab(5)> manpage", or "in the C<crontab(5)> manpage" or just "C<crontab(5)>". 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> >> (That's in the section "About L<...> Codes") (BTW, that holds true regardless of what variant syntaxes you use. So if you write L<name/"section">, it still means the same as L<name/section>, and so renders the same.) I chose the text string "in" because it actually means "in" in a decent number of Western European languages, and so was a passably sane default. If you're writing in language where that's no good, you just have to use explicit text|, as in: L<"Teminezon-Lin" (oubyen "Newlines") nan perlport|perlport/Newlines> I decided that this was a tiny bit of bother, but nothing compared to the various hassles of writing about Perl, in some other language. I.e., people are likely to spend rather more time worrying about how/whether they should translate "globref", than fretting over the fact that L<...> doesn't do DWIM for Polish, or whatever. (I say this as someone who actually worked as a translator at one point.) No solution for this is perfect, but that seemed the least-bad; it does the right thing for most cases, it doesn't require a Pod parser to have yet-more-convoluted logic for L resolution (including knowing how to decline Polish nouns or whatever), and the rule for how it works is simple enough to remember. I toyed briefly with mandating that L<name/section> render as if it were L<nameE<sol>section|name/section>, but that yields "Please see perlport/Newlines", which to everyone not fluent in POD guts, means "Please see perlport OR Newlines." At least, that's what slash means in English prose: "or". >In other words, L<Pod::Parser> is likely to be rendered simply as >"Pod::Parser", but I don't know what to do with L<perlfunc/die> or >L<"Theory of MIMEs">. As if they were: L<die in perlfunc|perlfunc/die> L<"Theory of MIMEs"|"Theory of MIMEs"> -- Sean M. Burke [EMAIL PROTECTED] http://www.spinn.net/~sburke/
