Re: [Benedetto-develop] documentation tool

[Joachim G. <jo...@ga...>]

Hi,

Ernst Bablick wrote:

>Hi,
>
>In my oppionion user documentation (UD) should exist in form of manual pages, 
>html-files and ps/pdf-files. System documentation (source code documentation) 
>(SD) should be embeded into the source code in ASCII format. Documentation 
>tools are able to produce pretty looking html/ps/pdf documents (in future 
>also xml) and manual pages automatically.
>
I agree concerning the system documentation. It should be part of the 
source code and be extracted by some documentation tool.

In case of benedetto, that is completely GUI driven, man pages are 
probably not applicable (we don't have different binaries).
User documentation should be some sort of book with a table of contents, 
an index etc.
It should be available as HTML and in a printable format like PDF.
I doubt it is possible to extract a good user documentation from the 
source code - here some typesetting program is better suited.
If we decide to use a typesetting program, it should be open source, so 
OpenOffice would be OK.

>
>Therefore I would try to use a documentation tool like doxygen to create the
>SD but also the UD! Especially terms of the libary language terminology have 
>to be known by the user and the developer. They should be part of both 
>documentations. And these terms should e. g. also be included into manual 
>pages. 
>
For java, first choice would be javadoc, as it is part of the JDK. It is 
quite easy to use, probably similar to doxygen (which I don't know very 
good).
For some database functionality we have C-Code (e.g. for sorting 
according to library rules), here we could have a look at doxygen.
As both tools can create HTML, it would probably also be possible to 
crosslink between both documentations.

For the library terminology, I agree, it can be part of the source code 
as it is in the first place interesting for the developers - I'll see 
how this can be best achieved. I could either include it into the source 
code or create an HTML file that can be referenced from the source 
documentation (you can include links in javadoc and I think also in 
doxygen).

>
>
>I would use applications like OpenOffice only for those things which can't be
>expressed with a documentation tool.
>
That's the user manual, in my opinion.

Best regards,

   Joachim

>
>Regards,
>
>Ernst
>
>On Friday 18 January 2002 23:52, Joachim Gabler wrote:
>
>>Hi,
>>
>>before I start writing some documentation (the first one will be a sort
>>of glossary describing the library language terminology with the german
>>and english terms),
>>which tools do we want to use to write documentation?
>>
>>We could use pure ASCII text (which is not really looking good) or
>>use HTML (which tool to use?) or
>>use some text processing tool like OpenOffice.
>>
>>I personally would vote for OpenOffice - it's free, can export
>>reasonably good HTML output if we want it, e.g. to be able to link from
>>some web page, and in long term, WEB browsers should also be able to
>>show the XML file format OpenOffice uses.
>>
>>Any ideas or preferences?
>>
>>  Joachim
>>
>>
>>_______________________________________________
>>Benedetto-develop mailing list
>>Ben...@li...
>>https://lists.sourceforge.net/lists/listinfo/benedetto-develop
>>
>