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<>. Laszlo _______________________________________________ Libguestfs mailing list Libguestfs@redhat.com https://listman.redhat.com/mailman/listinfo/libguestfs
