Libguestfs - Nov 2022 - [nbdkit PATCH] sh: Add exit status triggers for nbdkit_{shutdown, disconnect}

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.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

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

On Wed, Nov 09, 2022 at 01:47:15PM -0600, 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.
Oh indeed!  I had forgotten about this weirdness of pod.

$ cat test.pod
=over 4

=item 2

A

=item 3

B
=back

$ pod2text test.pod 
    2   A

test.pod around line 7: Expected text after =item, not a number
    3   B

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-p2v converts physical machines to virtual machines.  Boot with a
live CD or over the network (PXE) and turn machines into KVM guests.
http://libguestfs.org/virt-v2v