Richard W.M. Jones
2022-May-18 10:04 UTC
[Libguestfs] [v2v PATCH 1/2] docs/*.pod: strip trailing space characters
On Wed, May 18, 2022 at 08:49:29AM +0200, Laszlo Ersek wrote:> Remove any space characters that directly precede a newline character. > > Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=1938954 > Signed-off-by: Laszlo Ersek <lersek at redhat.com> > --- > > Notes: > I've verified in the rendered HTMLs that this whitespace stripping does > not break up indented blocks into smaller blocks -- the formatter keeps > runs of indented lines coalesced into indented blocks.This isn't what I expected at all, but I also checked the HTML and it seems what you're saying is correct. I wonder if this behaviour has changed in POD ..? For completeness I also looked at the roff output and that groups everything into a single .Vb/.Ve section as well. This is true at least as far back as RHEL 7 (perl-podlators-2.5.1-3.el7.noarch) I'm also wondering if there's a way to express "separate but adjacent" verbatim sections. This led me to the sources where I found that the rules for verbatim paragraphs are a lot more complicated than I thought I knew. Any paragraph that begins with a space is verbatim, even if following lines are not indented, eg: This is a verbatim paragraph And the spec (perlpodspec(1)) says that adjacent verbatim paragraphs must be run together. I cannot find a way to do "separate but adjacent". eg. this does not work: =begin verbatim Para 1 =end verbatim =begin verbatim Para 2 =end verbatim It ends up as a single verbatim section.> docs/virt-v2v-hacking.pod | 2 +- > docs/virt-v2v-input-vmware.pod | 10 ++++---- > docs/virt-v2v.pod | 24 ++++++++++---------- > 3 files changed, 18 insertions(+), 18 deletions(-) > > diff --git a/docs/virt-v2v-hacking.pod b/docs/virt-v2v-hacking.pod > index 29b73fb6c3f8..da5e640d9c92 100644 > --- a/docs/virt-v2v-hacking.pod > +++ b/docs/virt-v2v-hacking.pod > @@ -1,6 +1,6 @@ > =head1 NAME > > -virt-v2v-hacking - > +virt-v2v-hacking - > > =head1 DESCRIPTION(This man page really needs a complete rewrite.)> diff --git a/docs/virt-v2v-input-vmware.pod b/docs/virt-v2v-input-vmware.pod > index ab2d28e41ff2..4f4af2a9d804 100644 > --- a/docs/virt-v2v-input-vmware.pod > +++ b/docs/virt-v2v-input-vmware.pod > @@ -278,7 +278,7 @@ to list the guests on the server: > > $ virsh -c 'vpx://root at vcenter.example.com/Datacenter/esxi' list --all > Enter root's password for vcenter.example.com: *** > - > + > Id Name State > ---------------------------------------------------- > - Fedora 20 shut off > @@ -506,7 +506,7 @@ like this: > > $ virsh -c 'vpx://root at vcenter.example.com/Datacenter/esxi' list --all > Enter root's password for vcenter.example.com: *** > - > + > Id Name State > ---------------------------------------------------- > - Fedora 20 shut off > @@ -575,17 +575,17 @@ Enable (check) the following objects: > Datastore: > - Browse datastore > - Low level file operations > - > + > Sessions: > - Validate session > - > + > Virtual Machine: > Interaction: > - Guest operating system management by VIX API > Provisioning: > - Allow disk access > - Allow read-only disk access > - > + > Cryptographic operations: > - Decrypt > - Direct Access > diff --git a/docs/virt-v2v.pod b/docs/virt-v2v.pod > index d627734b0dc3..8849aae86394 100644 > --- a/docs/virt-v2v.pod > +++ b/docs/virt-v2v.pod > @@ -830,23 +830,23 @@ installed. For some older Linux distributions, this means installing > a kernel from the table below: > > RHEL 3 (Does not apply, as there was no Xen PV kernel) > - > + > RHEL 4 i686 with > 10GB of RAM: install 'kernel-hugemem' > i686 SMP: install 'kernel-smp' > other i686: install 'kernel' > x86-64 SMP with > 8 CPUs: install 'kernel-largesmp' > x86-64 SMP: install 'kernel-smp' > other x86-64: install 'kernel' > - > + > RHEL 5 i686: install 'kernel-PAE' > x86-64: install 'kernel' > - > + > SLES 10 i586 with > 10GB of RAM: install 'kernel-bigsmp' > i586 SMP: install 'kernel-smp' > other i586: install 'kernel-default' > x86-64 SMP: install 'kernel-smp' > other x86-64: install 'kernel-default' > - > + > SLES 11+ i586: install 'kernel-pae' > x86-64: install 'kernel-default' > > @@ -868,27 +868,27 @@ packages are installed I<before> conversion, by consulting the table > below. > > RHEL 3 No virtio drivers are available > - > + > RHEL 4 kernel >= 2.5.9-89.EL > lvm2 >= 2.02.42-5.el4 > device-mapper >= 1.02.28-2.el4 > selinux-policy-targeted >= 1.17.30-2.152.el4 > policycoreutils >= 1.18.1-4.13 > - > + > RHEL 5 kernel >= 2.6.18-128.el5 > lvm2 >= 2.02.40-6.el5 > selinux-policy-targeted >= 2.4.6-203.el5 > - > + > RHEL 6+ All versions support virtio > - > + > Fedora All versions support virtio > - > + > SLES 11+ All versions support virtio > - > + > SLES 10 kernel >= 2.6.16.60-0.85.1 > - > + > OpenSUSE 11+ All versions support virtio > - > + > OpenSUSE 10 kernel >= 2.6.25.5-1.1 > > Debian 6+ All versions support virtio > --We have this whitespace absolutely everywhere, so I wonder if we actually want to do this, even if it appears to be a correct transformation. 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
Laszlo Ersek
2022-May-19 09:57 UTC
[Libguestfs] [v2v PATCH 1/2] docs/*.pod: strip trailing space characters
On 05/18/22 12:04, Richard W.M. Jones wrote:> On Wed, May 18, 2022 at 08:49:29AM +0200, Laszlo Ersek wrote: >> Remove any space characters that directly precede a newline character. >> >> Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=1938954 >> Signed-off-by: Laszlo Ersek <lersek at redhat.com> >> --- >> >> Notes: >> I've verified in the rendered HTMLs that this whitespace stripping does >> not break up indented blocks into smaller blocks -- the formatter keeps >> runs of indented lines coalesced into indented blocks. > > This isn't what I expected at all, but I also checked the HTML and it > seems what you're saying is correct. I wonder if this behaviour has > changed in POD ..? For completeness I also looked at the roff output > and that groups everything into a single .Vb/.Ve section as well. > > This is true at least as far back as RHEL 7 > (perl-podlators-2.5.1-3.el7.noarch) > > I'm also wondering if there's a way to express "separate but adjacent" > verbatim sections. This led me to the sources where I found that the > rules for verbatim paragraphs are a lot more complicated than I > thought I knew. Any paragraph that begins with a space is verbatim, > even if following lines are not indented, eg: > > This is > a verbatim paragraph > > And the spec (perlpodspec(1)) says that adjacent verbatim paragraphs > must be run together. > > I cannot find a way to do "separate but adjacent". eg. this does not work: > > =begin verbatim > > Para 1 > > =end verbatim > > =begin verbatim > > Para 2 > > =end verbatim > > It ends up as a single verbatim section. > >> docs/virt-v2v-hacking.pod | 2 +- >> docs/virt-v2v-input-vmware.pod | 10 ++++---- >> docs/virt-v2v.pod | 24 ++++++++++---------- >> 3 files changed, 18 insertions(+), 18 deletions(-) >> >> diff --git a/docs/virt-v2v-hacking.pod b/docs/virt-v2v-hacking.pod >> index 29b73fb6c3f8..da5e640d9c92 100644 >> --- a/docs/virt-v2v-hacking.pod >> +++ b/docs/virt-v2v-hacking.pod >> @@ -1,6 +1,6 @@ >> =head1 NAME >> >> -virt-v2v-hacking - >> +virt-v2v-hacking - >> >> =head1 DESCRIPTION > > (This man page really needs a complete rewrite.) > >> diff --git a/docs/virt-v2v-input-vmware.pod b/docs/virt-v2v-input-vmware.pod >> index ab2d28e41ff2..4f4af2a9d804 100644 >> --- a/docs/virt-v2v-input-vmware.pod >> +++ b/docs/virt-v2v-input-vmware.pod >> @@ -278,7 +278,7 @@ to list the guests on the server: >> >> $ virsh -c 'vpx://root at vcenter.example.com/Datacenter/esxi' list --all >> Enter root's password for vcenter.example.com: *** >> - >> + >> Id Name State >> ---------------------------------------------------- >> - Fedora 20 shut off >> @@ -506,7 +506,7 @@ like this: >> >> $ virsh -c 'vpx://root at vcenter.example.com/Datacenter/esxi' list --all >> Enter root's password for vcenter.example.com: *** >> - >> + >> Id Name State >> ---------------------------------------------------- >> - Fedora 20 shut off >> @@ -575,17 +575,17 @@ Enable (check) the following objects: >> Datastore: >> - Browse datastore >> - Low level file operations >> - >> + >> Sessions: >> - Validate session >> - >> + >> Virtual Machine: >> Interaction: >> - Guest operating system management by VIX API >> Provisioning: >> - Allow disk access >> - Allow read-only disk access >> - >> + >> Cryptographic operations: >> - Decrypt >> - Direct Access >> diff --git a/docs/virt-v2v.pod b/docs/virt-v2v.pod >> index d627734b0dc3..8849aae86394 100644 >> --- a/docs/virt-v2v.pod >> +++ b/docs/virt-v2v.pod >> @@ -830,23 +830,23 @@ installed. For some older Linux distributions, this means installing >> a kernel from the table below: >> >> RHEL 3 (Does not apply, as there was no Xen PV kernel) >> - >> + >> RHEL 4 i686 with > 10GB of RAM: install 'kernel-hugemem' >> i686 SMP: install 'kernel-smp' >> other i686: install 'kernel' >> x86-64 SMP with > 8 CPUs: install 'kernel-largesmp' >> x86-64 SMP: install 'kernel-smp' >> other x86-64: install 'kernel' >> - >> + >> RHEL 5 i686: install 'kernel-PAE' >> x86-64: install 'kernel' >> - >> + >> SLES 10 i586 with > 10GB of RAM: install 'kernel-bigsmp' >> i586 SMP: install 'kernel-smp' >> other i586: install 'kernel-default' >> x86-64 SMP: install 'kernel-smp' >> other x86-64: install 'kernel-default' >> - >> + >> SLES 11+ i586: install 'kernel-pae' >> x86-64: install 'kernel-default' >> >> @@ -868,27 +868,27 @@ packages are installed I<before> conversion, by consulting the table >> below. >> >> RHEL 3 No virtio drivers are available >> - >> + >> RHEL 4 kernel >= 2.5.9-89.EL >> lvm2 >= 2.02.42-5.el4 >> device-mapper >= 1.02.28-2.el4 >> selinux-policy-targeted >= 1.17.30-2.152.el4 >> policycoreutils >= 1.18.1-4.13 >> - >> + >> RHEL 5 kernel >= 2.6.18-128.el5 >> lvm2 >= 2.02.40-6.el5 >> selinux-policy-targeted >= 2.4.6-203.el5 >> - >> + >> RHEL 6+ All versions support virtio >> - >> + >> Fedora All versions support virtio >> - >> + >> SLES 11+ All versions support virtio >> - >> + >> SLES 10 kernel >= 2.6.16.60-0.85.1 >> - >> + >> OpenSUSE 11+ All versions support virtio >> - >> + >> OpenSUSE 10 kernel >= 2.6.25.5-1.1 >> >> Debian 6+ All versions support virtio >> -- > > We have this whitespace absolutely everywhere, so I wonder if we > actually want to do this, even if it appears to be a correct > transformation.I'm OK to drop this patch. The reason I've submitted it is: It is now muscle-memory for me to invoke my NEdit macro for stripping space-at-EOL. Git considers space-at-EOL a source code wart, and some text editors even auto-strip space-at-EOL, so I've grown to just prevent git from complaining, and manually but routinely strip space-at-EOL before saving the file I'm editing. Now, when the file I'm editing has preexistent space-at-EOL, that turns into a second-level annoyance: "git diff" and friends think I intend to change the *old* source code like that as well. To get rid of that misunderstanding, I actually tend to collect the space-at-EOL removals for *old* code into separate patches (with "git add -p"), post and merge them, and then focus on the real stuff subsequently. The point being that unjustified space-at-EOL should not / would not be reintroduced ever after. You are right that we have space-at-EOL in very many POD files (I had noticed :) per the above); I figured I'd test the waters with this patch first! :) Thanks Laszlo