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

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"?