On 1/8/22 10:22, Stephen Kitt wrote:
Something like the above would be nice.
That would also remove the call to mktemp(1).
Yes, that’s along the lines of what I was thinking too; in particular,
something like that would be necessary to handle man pages with multiple
example files (e.g. unix.7).
The main purpose of this patch was to get the conversation started and to
show how I’d identified the problems I was fixing in the rest of the series.
I wanted to have something simple to get going, just to measure how likely it
was that there actually were problems in the example programs before
embarking on a more complex process ;-).
Okay. I tried to come up with something the last time you mentioned
this (IIRC it was you a few months ago that mentioned this plan,
right?), but didn't have good ideas. After reading this email of yours
I have the feeling that this will be simpler than I thought back then.
- This expects pages to have 'Program source' just before the source.
Few pages do have that currently.
Do you have plans to standardize some convention in the man pages?
I'd be happy to see that.
I think a good approach would be to use C comments,
one line before the code, and one line after the code,
so that there's no doubts about the limits of the code
(we should decide the format of the comment).
The comment should be something not too noisy, but very reliable.
I think I'd also first restrict to the EXAMPLES sections,
even before reading that hypothetical comment (or whatever we put),
to avoid mistakes.
At first I’d tried going with troff comments in the man page sources, but
that doesn’t work because we rely on the troff *output* being correct C, not
the troff input. So we need something that can be processed from the output,
and “Program source” was available for a first stab.
No. You had a point with that of the troff comments. I think that's
the key. See man_section(), defined in <scripts/bash_aliases>. There I
did something similar to read junks from the man pages (that was for
efficiently printing just specific sections of the manpages). We can
get something very similar for printing just specific parts that aren't
necessarily sections. Let me write some (untested) draft:
function man_example_program()
{
if (($# < 3)); then
>&2 echo "Usage: ${FUNCNAME[0]} <manpage> <begin-pattern> <end-pattern>";
return ${EX_USAGE};
fi;
local page="$1";
local begin="$2";
local end="$3";
cat \
<(<$f sed -n '/^\.TH/,/^\.SH/{/^\.SH/!p}') \
<(<$f sed -n "/$begin/,/$end/p") \
|man -P cat -l - \
|tail -n +2 \
|head -n -1;
}
We could write something based on that.
Ultimately though, as you say, we’d probably need C comments to start and
finish the code. That would fit in nicely with a Make-based approach: we
could have one target to generate the “dependencies” (C files generated from
man pages), then include that — that way we’d only update C files when the
corresponding man page changes.
Yes, an intermediate file could be the .c files. The C comment I don't
like it so much, since it's noisy for the reader (although we could
maybe use a C comment if it improves readability of the page). Let's
start with your idea of the groff comment, and if we see that C comments
might help we could change.
- Logs should go to stdout/stderr,
as in any other standard Unix command,
so just let the compiler print wherever it wants to print,
and let the user redirect them to wherever the user wants to too.
I know there was the groff-warnings test. But I don't like it.
It's there because it predates me,
and I yet have to understand how and if it works,
and then I'll rewrite it properly.
And I was basing my code on the groff-warnings test ;-). From running a
number of variants, what I liked about this is that it provides output
(including the name of the file being processed) only when an error occurs.
If we only rely on the regular output going to stderr, we also need to output
something for every file being processed, which clutters the output IMO.
That's why on the seventh day god invented >/dev/null and went to sleep :p
I'm used to having a line per file for makefiles. It goes a bit against
the Unix thing of muting until something goes wrong, but compilation is
usually slow enough to make people unhappy if there's no progress
indicator. A line per file is usually not too noisy.
But anyone serious about working on this could be expected to redirect the
output to a file!
For follow-up revisions of the patches, should I target
https://github.com/alejandro-colomar/man-pages instead of
https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git?
Normally, I'd say follow kernel.org. But now, there's too much of a
difference between them, so you'll be better following my main branch,
which has many changes that will some day be pushed to the kernel.org
repo. However, be warned that my branches aren't stable at all, and I
may rebase them against Michael's master branch when it's updated (and
branches other than my main branch are even more unstable to the point
that I may remove them). Just consider my main to be Debian's testing,
and the others sid/experimental. But kernel.org is oldoldstable at the
moment ;)
Also, I've recently started serving my own git at home, and will some
day remove the github repo, but for the moment you can still rely on it.
If you prefer, however, you could already use
<git://www.alejandro-colomar.es/src/linux/man-pages.git>. There, I've
only uploaded my main branch for the moment. There's no browsing yet,
but I plan to add it. For the moment it's just git:// (and SSH for me).
Regards,
Alex
--
Alejandro Colomar
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
