Hi Ingo,
On 3/20/22 22:26, Ingo Schwarze wrote:
> Hi Alex,
>
> 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.
I wanted to do this a long time ago for a few reasons:
- I know some manual pages are incorrect in some minor ways, which I'd
like to fix. For example, the includes in some examples are incorrect,
typically with more than needed. Reading 100s of pages carefully to fix
them would be impossible. And having slightly incorrect examples in the
manual pages is something I would really like to avoid. We have
received reports of programs having added headers because the manual
page said they had to add them, but they were really not needed.
- Some times, incorrect patches accidentally break the manual page
formatting (for example, "\n" instead of "\en"). If the patch is simple
enough that I may not care enough to render the manual page to check its
correctness, and I don't realize the small detail, I may apply a patch
that breaks an example program very badly. Having a magic button that
checks that the code at least compiles would greatly reduce those bugs.
- When reviewing an incoming patch, instead of me having to read through
it and after some time then replying "hey, please render your manual
pages before sending patches to see that your code doesn't produce what
you thought", I can just run `make build-src && make lint-src`, and if
it fails, I can tell the contributor: "run `make build-src && make
lint-src`, and you'll notice that your program contains some serious
problems. Rerun until you are happy with it. If you can't figure out
how to fix something, you can ask.".
It's kind of a man-pages static analyzer. Having it passing is not a
measure of how good a manual page is, but having it break is an
indicator that the manual page may actually have some problems.
>
>> .\" SRC BEGIN (program_name.c)
>
> Ugly as hell. I would very strongly object to have anything
> like that added to any manual pages i maintain. When people add
> comments in order to convey syntax and semantics to a machine,
> that is a sure sign that the design of whatever it is intended
> to achieve was totally botched.
I first thought of some way to achieve this without markers, but the
regex would be very unreliable with current manual pages. If we
standardize them a bit more, these markers might be made unnecessary,
but I'm not sure about that.
>
>> The next step will be to add targets to lint and compile the produced
>> files, to check their correctness.
>
> If any code snippet from an EXAMPLES section does compile, i would
> argue that it is severely ill-designed as it obviously contains lots
> of needless fluff that distracts from the point the example is
> actually trying to demonstrate. It ought to be stripped down to
> what really matters, to become shorter, more readable, and more
> to the point.
In this project, there are examples as the ones you point below, but
they are usually embedded in the text. In the EXAMPLES section we
usually have full programs, which are normally minimal working programs
that demonstrate the functions described. I don't think they have much
noise. I've sometimes used them myself, and I like them, because I have
something working from which I can test stuff. Sometimes it's quite
hard to translate man-pages text into a running program, and having a
working example program helps disambiguate the text (at least in my
brain it works like that).
>
> Here are a few EXAMPLES sections (in formatted form for readability)
> that demonstate how EXAMPLES sections should look like:
>
> EXAMPLES /* from chroot(2) */
> The following example changes the root directory to newroot,
> sets the current directory to the new root, and drops some
> setuid privileges. There may be other privileges which need to
> be dropped as well.
>
> #include <err.h>
> #include <unistd.h>
>
> if (chroot(newroot) != 0 || chdir("/") != 0)
> err(1, "%s", newroot);
> setresuid(getuid(), getuid(), getuid());
>
[...]
>
> Yours,
> Ingo
Cheers,
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
