[Libguestfs] [v2v PATCH 1/2] docs/*.pod: strip trailing space characters
Richard W.M. Jones
rjones at redhat.com
Thu May 19 10:14:06 UTC 2022
On Thu, May 19, 2022 at 11:57:21AM +0200, Laszlo Ersek wrote:
> 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@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@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! :)
Well we probably need to fix this, but unfortunately (a) the fix is
going to be extremely large and tedious, (b) it'll break backports in
some cases. But most seriously (c) it loses information about which
verbatim paragraphs are supposed to be separate and which should run
together.
There is no easy solution for (c) that I could find.
Rich.
--
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-top is 'top' for virtual machines. Tiny program with many
powerful monitoring features, net stats, disk stats, logging, etc.
http://people.redhat.com/~rjones/virt-top
More information about the Libguestfs
mailing list