automated example verification in the groff Texinfo manual

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 2819 bytes --]

[subject changed; steve@sk2.org dropped from CC list since he's not
quoted]

At 2022-03-20T22:55:48+0100, Alejandro Colomar (man-pages) wrote:
> On 3/20/22 22:26, Ingo Schwarze wrote:
> > Alejandro Colomar (man-pages) wrote on Sun, Mar 20, 2022 at 09:34:47PM +0100:
> > 
> >> I have ready some code to extract source code from EXAMPLES in
> >> man-pages.
> > 
> > Frankly, i don't see the point at all.
> > 
> > Manual Pages are not HOWTO documents that mindless users are
> > supposed to copy from verbatim without understanding what they see.
> > Instead, the are supposed to be read with your brain switched on and
> > the reader is supposed to *apply* what they learnt, not copy it.
> 
> This feature is not supposed to be used by manual page readers
> (users), but by manual page editors.

Indeed.  For quite a while I've had medium-term plans to do something
similar for the many examples in the groff Texinfo manual.  I want to be
sure they remain accurate.

Here's my sketch for whenever I get back around to this idea.

1. Extract examples with, e.g., 'sed -n '/^@Example/,/^@endExample/'.[1]
2. Use Texinfo comment lines within this example to:

   2a. identify the example (an invisible figure caption, if you will);

   and

   2b. specify additional transformations that should take place on the
       input and/or output--these are not necessarily just more 's' sed
       commands but possibly 'i' and 'd' commands as well.

As an example of an 'i' use case, the line length _has_ to be shortened
for many examples to fit within DVI/PDF page margins.  We note this in
the front matter of the current version of the manual[1], but I'm
uncertain of the utility of having it literally present in every case
(particularly in examples related to issues conceptually distant from
line length and/or breaking).

In some cases, either input or output is wholly elided when it sheds no
further light.

I don't envision changing the manual generation process to _populate_
the examples--that should be done carefully and by hand by someone with
a pedagogue's hat on.  The idea is to _validate_ the examples, reading
them in, performing a few invariant sed substitutions (the ones that
distinguish input, output, and error streams in the example text),
perform any further specified sed operations encoded as Texinfo
comments, and then run groff and verify that they match.

Since it would run this way, I reckon it can become just another test in
our suite.  (For those who don't follow groff development, groff 1.22.4
shipped with 3 tests.  groff 1.23 can be expected to have at least 111.)

Regards,
Branden

[1] These are custom Texinfo macros defined by the groff manual.
[2] https://git.savannah.gnu.org/cgit/groff.git/tree/doc/groff.texi#n901

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]