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@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! :) Thanks Laszlo

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@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

On Wed, May 18, 2022 at 08:49:30AM +0200, Laszlo Ersek wrote:

On the vmfs file system, ESXi encodes guest name characters that it considers reserved with fairly unpredictable, proprietary rules. For example, the ESXi webgui forbids backslash characters (\) completely, a percent sign (%) is encoded as %25, and a dollar sign ($) is replaced with underscore (_). Therefore the user can only construct the pathname part of the ssh:// URI in two steps: (1) determine the precise absolute pathname of the VMX file by way of logging in to the ESXi server interactively, and *reading* (not guessing) whatever ESXi chose for naming directories and files, (2) given the absolute, server-local pathname, percent-encode the characters that are reserved in URIs, following the open standard(s) that cover this.

Document this procedure: reorder the paragraphs of the affected section so that they describe segments of the URI from the left to the right, and then elaborate on the pathname segment.

Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=1938954 Signed-off-by: Laszlo Ersek <lersek@redhat.com> --- docs/virt-v2v-input-vmware.pod | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/docs/virt-v2v-input-vmware.pod b/docs/virt-v2v-input-vmware.pod index 4f4af2a9d804..38a0b30cd5fc 100644 --- a/docs/virt-v2v-input-vmware.pod +++ b/docs/virt-v2v-input-vmware.pod @@ -167,14 +167,27 @@ C<ssh://...> URI pointing to the VMX file. A typical URI looks like:

ssh://root@esxi.example.com/vmfs/volumes/datastore1/my%20guest/my%20guest.vmx

-Any space must be escaped with C<%20> and other non-ASCII characters -may also need to be URI-escaped. - The username is not required if it is the same as your local username.

You may optionally supply a port number after the hostname if the SSH server is not listening on the default port (22).

+For determining the pathname component of the URI, log in to the ESXi +server via SSH interactively, and identify the absolute pathname of the +VMX file on the ESXi server, such as: + + /vmfs/volumes/datastore1/my guest/my guest.vmx + +Subsequently, on the virt-v2v command line, L<percent-encode any +reserved +characters|https://en.wikipedia.org/wiki/Percent-encoding#Reserved_characters> +that you find in the individual pathname components. For example, space +characters must be specified as C<%20>: + + /vmfs/volumes/datastore1/my%20guest/my%20guest.vmx + +Refer to L<https://bugzilla.redhat.com/1938954>. + =head2 VMX: Importing a guest

Acked-by: Richard W.M. Jones <rjones@redhat.com> 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