Jan Schaumann wrote:
> Hello,
> 
> As you are probably well aware, the way that htdocs works at the moment
> is rather complex and requires significant resources.  This directly
> affects how users and developers contribute to the online documentation
> -- or rather, how often they don't!  We need to make it easier for
> anybody to contribute without having to install a large number of
> complex applications from pkgsrc or without having to learn the
> intricacies of the build process.
> 
> I'd like to start a detailed discussion about how we can make this
> happen.  I think we should first figure out what exactly our goals are
> in the documentation management framework.  Here's what I came up with:
> 
> - we want to have a consistent layout, look and feel for all pages

- including some links for easy navigation -- preferably in the header 
of each page.

> - we want to be able to make global changes without editing a lot of
>   files
> - all files should be well structured and easy to edit for people who do
>   only casual work in htdocs or who just want to make small corrections
> - we want to automate the creation of new items, new port additions,
>   hyerlinks to packages, ftp links, manual page references etc
> - the tools used should have as few prerequisites as possible

- Robust, reliable, well-working tools would be good, too.

- Some macro or &entity; to refer to other pages reliably, even if
   the physical location moves. &htdocsdir; comes to mind -- in analogy
   to ${PKGSRCDIR}.

- User-defined and system-defined macros, especially if we stay with
   XML/DocBook. It's a nuisance to type 
<varlistentry><term><varname>FOO</varname></term><listitem><para>Description</para></listitem></varlistentry> 
for sixteen times.

- Whether we stay with DocBook or not, there shall be documentation for 
end users on how to write web pages -- if at least pointers to the 
DocBook reference and the DocBook Website. I haven't found them until I 
created them myself some weeks ago. :(

Roland