Re: [Gnumed-devel] Re: Gnumed documentation

[Jim Busser]

On Mar 23, 2004, at 1:52 PM, Hilmar Berger wrote:
> 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... local [CVS] copy on 
> gnumed.org.
Tony Lembke thinks the above sounds reasonable and is willing to assist 
when he gets a chance

> 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.
How has the SGML been produced to date? Built on "plain text" 
contributions, which gets hand-coded into SGML by yourself, Hilmar, or 
sometimes Ian or others, and then uploaded into CVS? Has there been any 
special significance or reason to put it in the CVS, or has it simply 
been convenient to put the manuals on your own computer (in your local 
CVS) and then to upload?

> 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.
I await a comment from Engelbert otherwise there may be no large 
benefit of one wiki over another. None fully meets our needs at present 
but I am much more happy to work under wiki than if I need to do 
complex hand -coding which for me may be a barrier.

I have gotten familiar with TWiki in whose format we have some of our 
current wiki docs (most NB the updated roadmap) but even if we switch 
e.g. to MoinMoin the repairs may be minor as the wiki syntax largely 
overlaps. MoinMoin has table of contents and indexing features, TWiki 
has TwikiForms. Both support html and other document uploads.

> Before a public release, either find a way to extract the contents 
> from wiki
As part of a TWiki backup, David Grant had generated for me a set of 
html files and I expect he did not have to manually save each 
individual wiki page. Once the set of html pages is collected in 
preparation for an "updated public release" perhaps the following could 
help http://www.abc.se/~m9339/prog/html2sgml.html

> or manually backport the changes to SGML
Yes, so long as we record the wiki page revision at which the SGML was 
last (updated and) frozen, the wiki can easily provide the diff from 
the old revision to the current.