[Libguestfs] [PATCH nbdkit 1/2] docs: Fix POD verbatim paragraphs

[Richard W.M. Jones]

On Tue, May 24, 2022 at 03:20:19PM +0200, Laszlo Ersek wrote:
> > @@ -118,7 +118,7 @@ that the filter wants to intercept.
> >     .config            = myfilter_config,
> >     /* etc */
> >   };
> > - 
> > +
> >   NBDKIT_REGISTER_FILTER(filter)
> >  
> >  The C<.name> field is the name of the filter.  This is the only field
> > @@ -501,6 +501,8 @@ from the layer below.  Without error checking it would look like this:
> >     struct nbdkit_export e;
> >     char *name, *desc;
> >  
> > +=for paragraph
> > +
> >     exports2 = nbdkit_exports_new ();
> >     next_list_exports (nxdata, readonly, exports);
> >     for (i = 0; i < nbdkit_exports_count (exports2); ++i) {
>
> The above insertion splits the myfilter_list_exports() code example,
> which is currently rendered very nicely in a single verbatim
> paragraph:
...
> into two paragraphs -- for no good reason AFAICT.

Yup, that's wrong (although it was also wrong before).

> I didn't go as far as actually applying this patch and rebuilding
> nbdkit, but I did hand-edit the rendered HTML from the website in
> the Firefox inspector:
...
> and that looks like the attachment shows -- the red bar to the left
> is broken up, and there's a white gap between the declarations and
> the code.

Yup, that's what is supposed to happen for logically separate blocks,
but not in this particular case.

> Now if we actually wanted to separate these verbatim paragraphs,
> this output would be visually pleasing, so I'm not complaing about
> that. What I'm saying is that our current use of completely empty
> lines is inconsistent; sometimes it means "split these adjacent
> verbatim paragraphs apart", sometimes it means "keep them
> fused". Therefore we shouldn't automate the "=for paragraph"
> insertion.

The alternative is going to be pretty tedious though, and I should
think more error-prone.

How about fixing this particular problem in a new, prior commit, then
applying the perl script again, which this time would change the space
to an empty line and wouldn't insert "=for paragraph"?

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
libguestfs lets you edit virtual machines.  Supports shell scripting,
bindings from many languages.  http://libguestfs.org