MacPorts Docs Strategy - Proposal

[markd at macports.org]

The work on the new guide is progressing steadily, but one thing has
become apparent.  We need to unify our documentation efforts.  The
manpages proceed on a separate path from the guide docs, and we on the doc
team (Maun Suang , Simon Ruderich, and I) think that the man pages should
be rewriten in DocBook and then xincluded into the guide reference
section, thereby unifying the guide with the manpages.  Simon has tested
this method of inclusion to hte new guide and it works. 

Changes proposed:

1) Change macports.conf.5 man page to portconf.5 and include info for
sources.conf and variants.conf, or create sources.conf and variants.conf
man pages for consistency.
2) Create a trunk/doc/man directory to hold the DocBook man page sources.
3) Modify the guide to xinclude the rewritten man page xml sources.
4) Modify the guide Makefile as necessary, Simon has that mapped out
already.
5) After ensuring that the guide and the wiki have within them all the
notes from various text files within trunk, delete these legacy documents.
 base/doc/INTERNALS, trunk, base/HACKING, etc.

The goal is one source for a given type of information, be it the guide or
the wiki.

I think as far as process, the major changes will be:

1) Man pages need to be rewritten
2) Man page formats will look slightly different, not exactly how we're
used to seeing them.
3) People other than those on the doc team should make trac tickets
against the documentation milestone, unless the changes are trivial. 
There are naturally exceptions, but similar rules should be followed as
with other trunk modifications.

This can all happen fairly quickly, as long as we can agree that this is
the direction we need to go.  Any objections?

Mark