Hi Alex,
On Sun, 20 Mar 2022 21:34:47 +0100, "Alejandro Colomar (man-pages)"
<alx.manpages@xxxxxxxxx> wrote:
> I have ready some code to extract source code from EXAMPLES in man-pages.
> For that, I set up some convention:
>
> Enclose the code (including the enclosing .EX/.EE in a pair of comments
> with a very precise formatting:
>
> [[
> ...
> .\" SRC BEGIN (program_name.c)
> .EX
> #include <stdio.h>
>
> int main(void)
> {
> printf("Hello, world!");
> }
> .EE
> .\" SRC END
> ...
> ]]
>
> There can be multiple programs in a single page, with the only
> restriction that each of them has to have a different program_name
> (there can be collisions within different manual pages, but not within
> the same manual page)
>
> The Makefile will create a directory for each manal page, where the
> different programs will be created with the name specified in the
> comment (that's why it has to be different from others in the same page
> only).
>
> Please, check that you like what you see, and comment if not (or if yes
> too :).
I’ve been working on something similar, slightly further along (the linting
targets work). The extraction scripts could do with some improvement, but the
Makefile changes are small:
# Check that example programs include in man pages really build
Makefile.examples: $(MANPAGES)
scripts/list-example-files $^ > $@
include Makefile.examples
# Sources are listed as well as objects to ensure we update all source files
# CPPFLAGS and TARGET_ARCH are defined to avoid warnings
.PHONY: check-example-programs
check-example-programs: CFLAGS = -Wall
check-example-programs: CPPFLAGS =
check-example-programs: TARGET_ARCH =
check-example-programs: $(EXAMPLE_SRCS) $(EXAMPLE_OBJS)
.PHONY: clean-example-programs
clean-example-programs:
rm -f $(EXAMPLE_SRCS) $(EXAMPLE_OBJS)
scripts/list-example-files builds a separate Makefile to extract all the
programs, which ends up looking like
/home/steve/man-pages/man1/memusage.c: /home/steve/man-pages/man1/memusage.1
scripts/extract-example-files $<
/home/steve/man-pages/man1/prog.c /home/steve/man-pages/man1/libdemo.c: /home/steve/man-pages/man1/sprof.1
scripts/extract-example-files $<
The scripts are attached. The patterns used to identify source code are close
to those already present: .EX/.EE introduced by “Program source” (in which
case the source code is extracted to a C file named after the man page) or by
a
\." Example file
comment which can optionally name the file.
This has identified some more man pages which need fixes to their example
code, I’ll send patches tomorrow.
Regards,
Stephen
Attachment:
extract-example-files
Description: Binary data
Attachment:
list-example-files
Description: Binary data
Attachment:
pgpCqYWy8kNjn.pgp
Description: OpenPGP digital signature
