benedetto-develop Mailing List for Benedetto Library Catalog System
Status: Beta
Brought to you by:
jgabler
Menu
▾
▴
benedetto-develop — Development related discussions
You can subscribe to this list here.
| 2002 |
Jan
(4) |
Feb
|
Mar
|
Apr
|
May
|
Jun
|
Jul
|
Aug
|
Sep
|
Oct
|
Nov
|
Dec
|
|---|
|
From: Joachim G. <jo...@ga...> - 2002-01-20 07:40:13
|
Hi, another note concerning documentation: I had a look at the javahelp tool. It provides means to integrate online documentation into an application, quite similar to the help agent in Staroffice or Openoffice - which I really like. It is based on HTML pages for the help content and several XML files describing the structure of the document (table of contents, index etc.). It can be used to create context sensitive help within an application. I would really like do do some effort to integrate a tool like javadoc into Benedetto - so having the user documentation available as HTML pages might be good. I finished a first draft of an overview of the german language terminology used in Benedetto with their english language equivalents - I can put it somewhere on our project page - either check it in or use the documentation tool. Regards, Joachim Joachim Gabler wrote: > 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 >>> >> > |
|
From: Joachim G. <jo...@ga...> - 2002-01-19 22:00:05
|
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 >> > |
|
From: Ernst B. <ern...@WE...> - 2002-01-19 17:09:28
|
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. 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. I would use applications like OpenOffice only for those things which can't be expressed with a documentation tool. 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 |
|
From: Joachim G. <jo...@ga...> - 2002-01-18 21:48:29
|
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 |
