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