Bug #21480 for podlators: breaking S<>

Thu Sep 14 06:58:32 2006 MARKOV [...] cpan.org - Ticket created

Subject:

breaking S<>

In my attempt to get L<> and friends resolved while creating a table, I bumped into this error. My attempt is that I generate pod pages. The same short string is once displayed in a paragraph block (and therefore can contain L<> and friends) and once in an overview table. Well, tables are not supported, and therefore need to be simulated. However, when I simulate them with a verbatim block (which is the obvious choice) then (at least Pod::Man) will not translate L<>... this looks horrible. My latest attempt is to simulate the table by formatting the lines as I would for the verbatim block, but then encapsulate each line with S<> Example: S<< Option --Defined in --Default >> S<< attributes_qualified undef >> S<< check_occurs true >> S<< check_values true >> However, although the manual says "S<text>" -- text contains non-breaking spaces This means that the words in text should not be broken across lines. Example: "S<$x ? $y : $z>". the output is Option --Defined in --Default attributes_quali‐ fied undef check_occurs true check_val‐ ues true elements_quali‐ Of course, the whole second line of my pod should move to the next line of the output. This is not according to specs. Is there a work-around, such that I can force a newline? I hope you can help me further.

Sat Oct 07 16:40:32 2006 RRA [...] cpan.org - Correspondence added

From:

RRA [...] cpan.org

On Thu Sep 14 06:58:32 2006, MARKOV wrote: Show quoted text

> In my attempt to get L<> and friends resolved while creating a table,

Well, the basic problem here is that what you're doing is simply not supported by POD at all. There have been proposals to support it, but none of them have been implemented, and as a result it's just not going to work in at least some translators. POD has no way of specifying a table, no way of specifying a verbatim paragraph that still uses formatting escapes like L<>, and no way to force a line break. Some things will work with certain translators, but may not continue to work. That's the bad news. Addressing this really requires changes to the POD specification, and I'm not willing to implement something that's specific to podlators and don't really have time to pursue such sweeping changes personally. If the specification does change to add such capabilities, I'll support the new syntax. The good news, however.... Show quoted text

> However, although the manual says > "S<text>" -- text contains non-breaking spaces > This means that the words in text should not be broken across > lines. Example: "S<$x ? $y : $z>". > > the output is > > Option --Defined in --Default attributes_quali‐ > fied undef > check_occurs true check_val‐ > ues true elements_quali‐ > > Of course, the whole second line of my pod should move to the next > line of the output. This is not according to specs.

Well, yes, it is according to the specification, since all that S<> guarantees is that lines won't be broken on whitespace. It says nothing about hyphenation. However, hyphenation is essentially always wrong for technical material like this and I think Pod::Man-generated man pages having hyphenation is a bug in general, regardless of what the specification says. This has been fixed in the current release, which now disables hyphenation for the whole man page. It had attempted to do that before but it didn't work on Linux due to a weird implementation of the -man macro set on that platform.

Sat Oct 07 16:40:32 2006 The RT System itself - Status changed from 'new' to 'open'

Sat Oct 07 16:41:31 2006 RRA [...] cpan.org - Status changed from 'open' to 'resolved'

Sat Oct 07 16:41:32 2006 RRA [...] cpan.org - Severity Important changed to Normal

Sat Oct 07 16:41:33 2006 RRA [...] cpan.org - Fixed in 2.0.5 added

Mon Oct 09 02:49:20 2006 Mark [...] Overmeer.net - Correspondence added

Subject:	Re: [rt.cpan.org #21480] breaking S<>
Date:	Mon, 9 Oct 2006 08:49:04 +0200
To:	Russ_Allbery via RT <bug-podlators [...] rt.cpan.org>
From:	Mark Overmeer <mark [...] overmeer.net>

* Russ_Allbery via RT (bug-podlators@rt.cpan.org) [061007 20:40]: Show quoted text

> > In my attempt to get L<> and friends resolved while creating a table,

> > Well, the basic problem here is that what you're doing is simply not > supported by POD at all.

Show quoted text

> That's the bad news. Addressing this really requires changes to the POD > specification,

The most important thing which is really missing is a <br> alike. In manual-pages less visual (except when faking tables), in HTML quite important though. On the other hand: adding method which strips markup from a verbatim block is not a spec change. Now, I had to write it myself (see attachment), but it is better to have it maintained in the Pod modules even if the generators are not using it (now) Show quoted text

> Well, yes, it is according to the specification, since all that S<> > guarantees is that lines won't be broken on whitespace. > This has been fixed in the current release, which now disables > hyphenation for the whole man page. It had attempted to do that before > but it didn't work on Linux due to a weird implementation of the -man > macro set on that platform.

Saw that. But then, Slavan showed me that it does not always work: pod2man some.pod.with.long.S<> | groff -Tps -man | gv - So at the end my only option was to create my own stripper. -- MarkOv ------------------------------------------------------------------------ Mark Overmeer MSc MARKOV Solutions Mark@Overmeer.net solutions@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net

Message body is not shown because sender requested not to inline it.

Mon Oct 09 02:49:21 2006 The RT System itself - Status changed from 'resolved' to 'open'

Tue Oct 10 21:09:43 2006 RRA [...] cpan.org - Correspondence added

On Mon Oct 09 02:49:20 2006, Mark@Overmeer.net wrote: Show quoted text

> > The most important thing which is really missing is a <br> alike. In > manual-pages less visual (except when faking tables), in HTML quite > important though.

I agree that it would be nice to have this. I don't have time to propose and discuss a POD specification change myself, but I encourage you to put forward this proposal and would be happy to implement such a thing in my modules. Show quoted text

> On the other hand: adding method which strips markup from a verbatim > block is not a spec change. Now, I had to write it myself (see > attachment), but it is better to have it maintained in the Pod > modules even if the generators are not using it (now)

Sure, that seems like it could be a useful function. The package on which this bug report is filed doesn't contain generic POD functions, so this isn't the place to add it, but I encourage you to submit this to the Pod::Simple maintainer for inclusion. Show quoted text

> Saw that. But then, Slavan showed me that it does not always work: > pod2man some.pod.with.long.S<> | groff -Tps -man | gv - > So at the end my only option was to create my own stripper.

Works fine for me. In groff mode, justification isn't disabled, but text surrounded with S<> is kept together and hyphenation is still disabled.

Tue Oct 10 21:09:44 2006 RRA [...] cpan.org - Status changed from 'open' to 'resolved'