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