[Libguestfs] [v2v PATCH 1/2] docs/*.pod: strip trailing space characters
Laszlo Ersek
lersek at redhat.com
Thu May 19 11:21:08 UTC 2022
On 05/19/22 12:14, Richard W.M. Jones wrote:
> 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.
OK, then I'll drop this one.
Thanks!
Laszlo
More information about the Libguestfs
mailing list