Document that U<text> is the formatting code for underline

[leonerd]

It's been so long since anyone last altered the POD spec that I don't know if we even remember what the process is any more.

https://www.nntp.perl.org/group/perl.perl5.porters/2023/09/msg267057.html
https://www.nntp.perl.org/group/perl.pod-people/2023/09/msg2146.html

I'm attempting to move things forward a bit by adding some new features; I thought I'd start with something relatively small and simple here, in the hope that if we start by accepting changes to the perlpod.pod document first, then implementors can go and create things.

Here then is a suggestion that U<...> be added alongside B<> for bold and I<> for italic, which seems about the smallest simplest change we could think of.

Most of the Pod-related infrastructure in core perl is actually CPAN-first dual-life from Pod-Simple and similar, so there isn't really any code that can yet be altered along with this. I therefore feel that simply adding it to the spec is the first step towards making it into reality, and then proceed to implement it in the CPAN modules. While I wasn't able to implement anything for core perl to support this, I have successfully added it to a CPAN distribution of mine, and thus at least confirmed it simple enough to implement.

https://metacpan.org/pod/App::sdview::Parser::Pod
https://metacpan.org/pod/App::sdview::Output::Pod

This is a test of the process. If successful, I hope to open more discussions around other ideas; such as language-tagged code fences, tables, and maybe even a way to specify images.

[iabyn]

On Fri, Sep 22, 2023 at 08:06:04AM -0700, Paul Evans wrote: Here then is a suggestion that `U<...>` be added

I'm not sure that's a good idea! In real typography, an underline is hardly ever used. Invariably, amateurs end up using it in places where italics or bold should be used instead. It only gets used now because dumb word processors make underlining easy. I recall that back in the day when I used LaTex, it made it very hard (but not impossible) to do underlining.

…

-- You're only as old as you look.

[Grinnz]

I think that we should leave the typography choices to the user :) As far as the documentation, two notes: perlpodspec would be an even more important place to document it, and there should be some indication that it is not universally recognized as of yet. There is the benefit that as a formatting code it will be ignored with a warning by Pod::Simple formatters currently.

[leonerd]

It is notable that neither nroff nor Markdown make underlining easy either. Hedgedoc's extended form uses ++underline++ but that's not a commonly-found extension. We could also document it as saying "well it's here if you want it but most formatters will ignore it and you may not want to use it anyway.." or somesuch. But it could be useful for folks wanting to use POD as a gateway to something like HTML.

Honestly, half the point here is just to try having a go at some easy extension to POD before I attempt to tackle something more substantial (e.g. tables) - I was hoping it would be a simple one. :)

[haarg]

It's probably worth checking with @khwilliamson how he sees the maintainership of Pod::Simple. While he has been the primary maintainer since 2016, I suspect he would be happy with P5P being considered the true owners of the module.

Assuming that is true, I think that proposed additions to the Pod spec should always come with an implementation in Pod::Simple.

For this particular proposal, that is less important. There are no semantic or implementation complexities in this proposal, so providing a patch to Pod::Simple will be trivial.

[rwp0]

It is notable that neither nroff nor Markdown make underlining easy either. Hedgedoc's extended form uses ++underline++ but that's not a commonly-found extension. We could also document it as saying "well it's here if you want it but most formatters will ignore it and you may not want to use it anyway.." or somesuch. But it could be useful for folks wanting to use POD as a gateway to something like HTML.

Honestly, half the point here is just to try having a go at some easy extension to POD before I attempt to tackle something more substantial (e.g. tables) - I was hoping it would be a simple one. :)

Thanks, strikethough (with S<> perhaps) would also be a good extension I think.

[mauke]

S<> already means "do not break spaces", so that syntax is out.

[leonerd]

Thanks, strikethough (with S<> perhaps) would also be a good extension I think.

And thus we already run into the trouble with these single-letter codes. S<...> already means "do not break on whitespace within this span". I considered maybe "T" for strikethrough at some point; reserving "K" for "keyboard" much like Pod6. But in the end there's only so many letters to go around...

[guest20]

A lower-case t already has a strike through it, so that's a good mnemonic

[leonerd]

Added also to perlpodspec, plus also noted that it's new this year so may not be available.

[nicomen]

I think that we should leave the typography choices to the user :) As far as the documentation, two notes: perlpodspec would be an even more important place to document it, and there should be some indication that it is not universally recognized as of yet. There is the benefit that as a formatting code it will be ignored with a warning by Pod::Simple formatters currently.

Good point. There is a reason why W3C went from <b>, <u>, <i> etc to <em>, <strong> and other non-visual-centric markup, after separating out styling with CSS..

I'm not sure all terminals support underline (or overstrike) for instance, and I'm guessing it many times can be mistaken with a hypertext link.

Documentation should probably state the semantic meaning of x<…> tags instead of doing the mistake of thinking visual appearance.

[leonerd]

I'm not sure all terminals support underline (or overstrike) for instance, and I'm guessing it many times can be confused with an hypertext link.

Prettymuch every terminal in existence ever since the DEC VT100 has supported underline, whereas italics is actually a relatively rare addition that most terms did not support. Observe that traditionally man does not render in italics on a terminal.

[leonerd]

Additionally @haarg has written an implementation for Pod-Simple: https://github.com/haarg/pod-simple/tree/underline

[leonerd]

Further research into nroff/troff and friends suggests that getting both italics and underline to be distinct in a manpage is basically impossible. I've therefore added some more wording to say that the two might not be disctinct from each other.

[leonerd]

@iabyn Does the new wording help appease your concerns?

[iabyn]

LGTM

[leonerd]

Huh I managed to entirely forget about this PR, and haven't merged it yet. I shall do so now thus giving it the official stamp.

[leonerd]

Updated to claim the correct year in the docs, and also fix the typo of "distinct". Shall merge when CI is happy.