Re: [Gnumed-devel] Re: Gnumed documentation

[Hilmar Berger]

Hi all, 
On Tue, 23 Mar 2004 03:04:08 -0800
Jim Busser <address@hidden> wrote:

> > -possible connection between wiki and sgml ?
> >  <SNIPPED: more questions/ suggestions>
> This is a good question - see my concerns below. I understand SGML can 
> be a lot of work to have to manually maintain.
SGML is a lot of work, mainly because there is no high-level editor available. 
But every
specialized markup language will need some manual work. On the other hand every 
markup language is a structured language, so (semi-)automatic conversion should 
not be too hard. 

My thoughts on gnumed-documentation are:

- The main concern should be to enable easy access to documentation, both in 
sense of reading and adding/changing content.
- SGML was chosen because it's quite easy to create a number of different 
formats from one source, not because it is a particularly easy to handle

Maintaining my opinion that content creation is more important than the choice 
of a particular software, I would suggest the following:
a) Gnumed Programming API / source documentation: use one of the available 
tools (my favorite being epydoc) to automatically create the documentation once 
a week directly from a CVS-copy. Put the resulting pages in the CVS, set a link 
to CVS or a local copy on gnumed.org.
b) User Manual/Developer Manual: Keep the existing (SGML-based) documentation 
in CVS as long as no other way to produce an PDF/tree of static-html pages has 
been found. If we find a wiki that really suits our needs, put a note in each 
of the manuals, that now the current version of documentation is to be found in 
www.ourwiki.org. Copy the content from SGML to the wiki. Let all documentation 
work be done there.
Before a public release, either find a way to extract the contents from wiki 
automatically to SGML/lore/html/whatever or manually backport the changes to 
SGML. As public releases are rather rare events in Gnumed, this will not make 
too much trouble :).
  
I had a look at Twisted.lore. Looks good to me, although might be better suited 
for the developer manual than for the user manual, plus the created HTML lacks 
somewhat the beauty of docbook-generated html.
Engelbert's script doesn't seem to extract wiki content to any other format, 
although I remember him writing that this shouldn't be too hard, given the 
structured nature of content in both Wiki and SGML/HTML/...

Hilmar