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
