"Sean M. Burke" <[email protected]> writes: > 3) Point 3 is a problem in theory, and possibly in practice, but for which > the *solution* is "SO DON'T DO SCREW IT UP!".
> I had this in mind: supporting linktext could mean: > "You can just L<email me!|mailto:[email protected]> Now!" > which, outside of hypertext, *could* be rendered as > "You can just email me! Now!" > ...which makes me all frowny-face. For what it's worth, both Pod::Text and Pod::Man always display L<foo|http://foo.com/> as "foo <http://foo.com/>", which I think generally does the right thing. > A few bits of DWIM would probably cover most cases, I bet! > * Suppressing the URL if it's identical to the link text. They already do this, although it always surrounds the link text with <> in this case, following the informal standard for how to express URLs in text. > * Suppressing the URL if it says "perl.com" and the URL > (case-insensitively compared) is http://www.perl.com, http://perl.com, or > http://perl.com/ This I've not done. I'm not sure if this is a good idea or not. Hm. > * Suppressing the URL if the text has a "@" in it and the URL is just the > text with a "mailto:"; in front of it. So > "I'm at L<[email protected]|mailto:[email protected]> now!" > indeed *can* show up as > "I'm at [email protected][mailto:[email protected]] now!" > but it's so *obviously* redundant that that can just show as: > "I'm at [email protected] now!" That's a good idea. I'll add that to the to-do list. Related, I think L<mailto:[email protected]> should probably turn into just [email protected] in a text output format. > B1) You (pod-writer) could write: > "Look at my web site, L<http://stuff.com/>!" > In that case, it's not a problem for anyone or anything. > It dodges ANY problem with link text by simply not using it. > BUT a lot of people will use link text because they think of hypertext as > always having a linktext and a URL, with NO INFERENCE of one from the > other if it's missing. I mean, > <a href="http://stuff.com/";></a> > or > <a href="">http://stuff.com/</a> > don't magically turn into what the output would be of > <a href="http://stuff.com/";>http://stuff.com/</a> > So, by analogy, however technically unnecessarily it is, I find it > entirely understandable that people would just reflexively go for *even* a > totally vacuous case of linktext, namely: > L<http://stuff.com/|http://stuff.com/> I'd kind of like to produce a warning about this, though, since it looks ugly and creates the lurking potential for bugs (updating one URL and not the other). > HEY, documentation-writer! Maybe you're thinking of doing > L<my friend's web site|http://stuff.com/>! > ...but: DON'T DO THAT! > Why? > Because a lot of people are using perldoc and the default behavior of it, > which is to page thru nroff-formatted non-hypertext. > Yes, it's the lowest common denominator. > It's also a *very* common denominator. No, actually, please *do* that, as Pod::Text and Pod::Man (including perldoc) have handled this properly since forever. This will render as: my friend's web site <http://stuff.com/> which is just fine. Really, please, start using this right now. I think the tools will be fine. The core tools are already fine. -- Russ Allbery ([email protected]) <http://www.eyrie.org/~eagle/>
