On Thu, Nov 10, 2022 at 02:23:39PM +0100, Laszlo Ersek wrote: > On 11/09/22 20:47, Eric Blake wrote: > > On Wed, Nov 02, 2022 at 01:36:26PM +0000, Richard W.M. Jones wrote: > >>>> -=item 4, 5, 6, 7 > >>>> +=item S<4> > >>> > >>> The S<> notation seems new here (so it's going to be inconsistent with > >>> the rest of this file, I think). > >> > >> I was going to mention this too. The S<> notation is used to insert > >> non-breaking spaces (for output formats that support it) in a span of > >> text so that it won't be folded over multiple lines. AFAIK it > >> shouldn't have any effect here. > > > > Ah, but it does: > > > > Pod input around line 121: Expected text after =item, not a number > > > > The use of S<> is there to keep the pod formatter happy when =item's > > sole argument would otherwise look like a number instead of arbitrary > > text. > > > > Sigh. :) > > Thanks for the reminder. I've now found that > <https://libguestfs.org/virt-v2v-output-local.1.html> > ["docs/virt-v2v-output-local.pod" in the v2v tree] is a good > demonstration for numbered lists, bullet lists, and "option" list. > > Interestingly, perlpod(1) does not recommend S<> for this kind of > escaping, it recommends Z<>: > > • And perhaps most importantly, keep the items > consistent: either use "=item *" for all of them, to > produce bullets; or use "=item 1.", "=item 2.", etc., > to produce numbered lists; or use "=item foo", "=item > bar", etc.--namely, things that look nothing like > bullets or numbers. (If you have a list that contains > both: 1) things that don't look like bullets nor > numbers, plus 2) things that do, you should preface > the bullet- or number-like items with "Z<>". See Z<> > below for an example.) > > If you start with bullets or numbers, stick with them, > as formatters use the first "=item" type to decide how > to format the list. > ... > "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>". > ... > "Z<>" -- a null (zero-effect) formatting code > ... > Another use is to indicate that stuff in "=item > Z<>stuff..." is not to be considered to be a bullet or > number. For example, without the "Z<>", the line > > =item Z<>500 Server error > > could possibly be parsed as an item in a numbered list when > it isn't meant to be. > ... > > More interestingly, *this particular use* of Z<> is not documented in > the RHEL7 manual of perlpod(1) -- the above quote is from Fedora 35! So > that lack of specific documentation on RHEL7 might be why we chose to > wrap the digits in S<>, rather than to isolate them with Z<>.
Actually the first I've heard of Z<> formatting. Could be a recent addition as you say. We do need to keep things working on RHEL 7 (as far as possible without heroics). Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com virt-builder quickly builds VMs from scratch http://libguestfs.org/virt-builder.1.html _______________________________________________ Libguestfs mailing list Libguestfs@redhat.com https://listman.redhat.com/mailman/listinfo/libguestfs
