[again replying to multiple people]

On 25 Jan 2000, Erich T. Enke wrote:

> I agree, this is a wonderful idea.  I have felt the man pages to be
> deficient in a couple areas.  One is in providing that proper
> overview/datastructures/diagrammatic view needed to understand what it is
> you are learning to use.

  I agree.

<rant>
  I think the "HOW-TO" method of teaching unix is the wrong way.  While a
HOW-TO can teach a single procedure faster then learning the design behind
the procedure, learning the design allows you to apply it to a different
similar situation with minimal effort and will very quickly become faster
and easier then learning by HOW-TOs.  IMO, HOW-TOs should be limited to
installation and essential configuration to get the system up (with most
of the real work done by the installer).  After that, a unix philosophy
page gives you an overview of the system and leads you to other pages that
describe various aspects in detail.  If you want to know how to do
something, you look at the page that describes the general design and then
look at the reference page that tells you what the command options are to
do it.  New users don't need to be told exactly what commands to type to
do X, Y, and Z, they need to be told how to interpret the man pages that
already provide that information.  Instead of spending extra effort to
enumerate all posssible uses of a command, spend the effort documenting
its theory and design. 
</rant>

  Back to documentation system design:

  On the help command issue, I still think it should be a pointer to the
man page.  Things that you need to get the system up should be part of the
install guide (or perhaps a supplemental install guide for users
unfamiliar with unix).  Something that you only need once should not be
given a general name like "help". 

  I think I got too excited about DocBook.  On further thought, it doesn't
really do what I want.  What I want is to be able to generate the
*complete* NetBSD web pages from the same source as is used to generate
the man pages (and which source should be able to be converted into a
DocBook markup of the man pages).  But we don't want the web pages to look
like man pages.  Thus we need even higher level SGML, with a three level
abstraction:
1) content: text, inlines, and short section based markup
2) structure: combine content in various ways and gives "medium-level"
markup such as combining various short sections into a man page
3) detailed style: how to convert structure into the target format

  The idea is that there is one instance of content (not all of which must
be used for each structure), multiple structures to arrange the content
and multiple styles to convert each structure into the desired target
formats.  Content can also be generated from other sources.  The content
markup would be very similar to DocBook, only at a slightly higher level.

  I believe this is a simple and powerful way to centrally organize data. 
It fully abstracts style from content so that it is possible to do things
like change the style of the entire web site without needing to edit each
page.  Those who just want to add content just need to add the content
with appropriate markup and the proper hooks.

  It turns out that this is a very good solution to another problem I was
about to start working on, so I will be working full time on implementing
the support tools it even if it is not adopted for NetBSD.  It will be
implemented in C and placed in the public domain. 

Matthew Orgass
darkstar@pgh.net