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

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

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.

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.