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

[Laszlo Ersek]

On 05/24/22 15:25, Richard W.M. Jones wrote:
> 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"?

Sounds OK.

Thanks!
Laszlo