Re: allowing L<text|href>

"David E. Wheeler" <[email protected]> writes:

> I just wrote tests for the text output from Pod::Simple::Text. It's like
> this:

>             POD                     | Text Output
>     --------------------------------+------------------
>     L<things|crontab(5)>            | things
>     L<things|crontab(5)/foo>        | things
>     L<Perl Error Messages|perldiag> | Perl Error Message
>     L<perl.org|http://perl.org>     | perl.org

> I think it most unfortunate that the URL is lost in text output. I see
> two ways around this:

I think this output is correct for everything except the last form.
There's a long tradition of the text before the vertical bar being what
should be displayed in a text document for Pod::Text and Pod::Man for
those places where it was already supported, and I don't think we want to
break that.  Existing documents expect that behavior.

For the latter, I think the best rendering for both Pod::Text and Pod::Man
is:

    perl.org <http://perl.org>

and that's what I plan to implement.  That's a fairly natural expression
of a URL in a text document and follows the IETF recommendation.
    
> 1. Change it to output with the URL using something like Markdown format:

>             POD                     | Text Output
>     --------------------------------+--------------------------------
>     L<things|crontab(5)>            | [things](crontab(5))
>     L<things|crontab(5)/foo>        | [things](crontab(5)/foo)
>     L<Perl Error Messages|perldiag> | [.Perl Error Message](perldiag)
>     L<perl.org|http://perl.org>     | [perl.org](http://perl.org)

This isn't a very natural written English way of expressing a link.  I
think producing Markdown output is a great idea, but Markdown is another
formatting language.  It's not plain text and shouldn't be the output of a
translator to text.

-- 
Russ Allbery ([email protected])             <http://www.eyrie.org/~eagle/>