Re: [groff] mom manpage

[John Gardner]

> Even moderately large systems can be beautifully documented in a
> single manual page - for example, a shell

It's amazing how true this is. Even with massive man-pages, it's still
easier to find what I'm looking for in less(1) by hitting the `/` key and
typing a search string. It's quite literally faster than the time it takes
to load web-based documentation (especially on my crappy connection...)

I can't think of a documentation format more pure than a well-written
man-page. Conversely, the worst-looking man-pages I've ever seen are those
which were generated from markdown. Their source-code is actually more
readable than the formatted output... :-(

On Sat, 1 Dec 2018 at 15:52, Ingo Schwarze <address@hidden> wrote:

> Hi Peter,
>
> if you are interested in my perspective - scrap the HTML documentation
> and fix the manpage.  The reference manual - i.e. the manpage - is
> really important: when you use some software regularly, you use the
> reference manual all your life.  Catering to the experienced user
> is most important because whoever is serious about using the software
> will become experienced sooner rather than later.  So the reference
> manual (manpage) must be concise, precise, and correct.
>
> If an author has too much time on his hands and doesn't doesn't know
> what to do with it, there is nothing wrong with writing a beginner's
> tutorial, too.  But it's really not so important.  You skim through
> that once, than quickly move on to the real thing for further learning,
> often even before finishing the tutorial.  And then there is never a
> need to come back to it, so it doesn't really matter that much - "use
> once" is much less important than "use always".
>
> Besides, even beginners can easily learn from a well-written reference
> manual.
>
> Hell, *especially* when i know nothing about a software and just
> need to use it quickly for one task, i invariable go straight for
> the reference manual because the relevant bits are almost always
> less text to read in the ref docs than whatever "user manual" or
> "tutorial" there may be, so reading them takes less time there.
>
> Write the real manual in some other format than a manpage?  Bad
> idea.  it means you make it harder to access, out of the usual place
> where people look for documentation, in a gratuitiously different
> format.  You want HTML and PDF versions?  Not a problem at all with
> manpages, after all, typesetting is what Jerry Saltzer originally
> designed RUNOFF for.  You want hyperlinking?  Not a problem with
> .Xr links in modern manual pages either.  You want bells, whistles,
> and moving gifs of cute cats?  Bad idea, documentation is about
> efficiently conveying information, not about fluff and pictures
> and gimmicks.
>
> You want to exercise the language itself in documenting it?  Bad
> idea, the documentation is about concisely and simply explaining the
> syntax and semantics, and that doesn't require writing the
> explanation in the language itself.  C library manuals are not
> written in C - but they can contain concise examples of C code
> in the EXAMPLES section, near the end.  Same for mom.
>
> Even moderately large systems can be beautifully documented in a
> single manual page - for example, a shell.  If is system is too
> large and a single page would become unwieldy, yes, in the first
> step, you split it up to the next logical level - i guess for mom
> that would be macros, but you can probably judge better than i can
> what that next level is.  That gives you too many pages, most of
> them unreasonably short?  So you form logical groups of related
> macros, make one page for each group, and name the page after the
> most important or typical macro of the group.  That page can also
> - concisely! - explain the basic concepts relating to that group.
> Practically all library manuals (section 3) work exactly that way.
>
> This is not rocket science and nothing new - just do it...  ;-)
>
> Yours,
>   Ingo
>
>