Hi, Nate! At 2018-06-27T15:28:36-0500, Nate Bargmann wrote: > I've come to this list late. I've worked on man pages as long ago as > 2007 though I didn't know much and sort of just followed what was > already in the page(s) I was working on. I suspect most developers do > the same. Early last year I became more interested and started > reading the various section 7 pages and became better educated.
Yup. I was a Unix/Linux user for literally years before I realized how
much good stuff was secreted away in section 7, and some years after
that I came to realize how much more good stuff _could_ be. I once
settled an argument with a very experienced package maintainer by citing
locale(7), of which he had not even been aware.
Man pages are a terrific and under-appreciated resource. As I noted
earlier, I was reading through the Unix v7 pages recently. One of the
things I noticed was how terrifically good some of them were as quick
primers on tools that have since grown (by necessity and/or bad
judgment) hugely in the years since.
For example, the GNU Make manual is a pretty unfriendly way to learn
Make. The Unix v7 make(1) page tells you everything you need to know to
get started with it to achieve basic ends. The syntax for pattern rules
is terse to a fault, and I'm not sure I'd teach it to kids these days,
but that's a minor complaint.
> Let me say this. With a modicum of understanding, writing man(7) pages
> is not too difficult. I would like to see man(7) enhanced in some ways
> and left well enough alone in most ways.
I have several ideas along these lines but I'm still thinking through
them, and I do have a design angel on my shoulder exhorting me not to
get too carried away. :) If and when I get my ideas to cohere, I'll
pitch them to this list first.
> Until after my initial post to this list earlier this year I wasn't even
> aware of mdoc(7). At Ingo's suggestion I took a look and opted against
> it for the project I maintain. Why? It is too complex for a hobby
> project as that which I maintain, so man(7) it is.
Yes. I find mdoc(7) too large to keep in my head, and the limitation to
two-character macro names leads to a crowded namespace.
> As I see it, man(7) should be enhanced where it makes sense. man(7) is
> good for man pages and that is really all most of us care about for the
> macro package. Acceptable PS/PDF and even reasonable HTML is a bonus.
At some point yesterday afternoon a faint bell rung in my head and I
remembered that this very issue is tackled in groff's Mission Statement.
"... The need for Unix manuals to render cleanly to multiple output
media favours structural rather than presentational markup, however the
classical man(7) macros remain almost exclusively presentational.
mdoc(7) provides a semantically superior alternative, but the use of
man(7) is deeply rooted in Unix.
Future work on manpages will entail improving the semantic clarity of
the man(7) macros, decoupling them as much as possible from low-level
presentational requests. The aim will be to ease conversion of manpages
to markup languages that do not rely on groff for display and printing,
e.g. XML, while preserving the full presentational richness of manpages
processed with groff.
Concurrent with work on man(7), mdoc(7) will be actively supported and
its use promoted.
To summarize, the goal of this two-pronged strategy is to foster manpage
markup that:
* renders cleanly to the terminal
* respects presentational markup when output to PostScript
* allows semantic analysis
* is portable ..."[1]
> Please, Branden, bring us good ideas. Discovering the .SY/.YS and .OP
> macros made my SYNOPSIS sections much more consistent. Yes, I had a
> couple of cases where .OP doesn't work and I manually formatted that
> part. I was glad to see that .SY did not interfere. From what I
> understand, these macros are relatively new.
Relative to *roff systems in general, certainly. It's not clear from
groff's changelog exactly when they were introduced, but I would guess
"on or before February 2007" given some entries by Eric Raymond
mentioning .SY and .YS's states as "canned macros now".
> The existence of legacy compilers has not kept GCC from moving
> forward. Likewise, the existence of legacy *roff should not preclude
> man(7) from doing the same.
Documentation of software systems relative to their implementations
tends to be sluggish and laggardly. I have opinions regarding why this
is the case, but they would reflect an uncharitable view of the
discipline of software engineering, and this is an upbeat discussion.
:)
Regards,
Branden
[1] https://www.gnu.org/software/groff/groff-mission-statement.html
signature.asc
Description: PGP signature
