RE: [certi-dev] New documenation generation system for CERTI

[Gotthard, Petr]

Hi Eric,
is there a way how to combine install/user documentation from various
C++ sources?

When writing the namespace/class (i.e. developer) documentation you
create "groups" and put documentation from different C++ files to
different groups. The different groups the appear as different .html
pages, but each group has a single page.
http://www.stack.nl/~dimitri/doxygen/grouping.html

Yesterday I tried (and failed) to convince doxygen to do the same for
install/user documentation. For example, environment variables. We can
write environment variables documentation into respective C++ files, but
I can only make each variable to have a separate page. It would be nice
if we could have one .html page listing all variables, but having the
doxy-source in multiple C++ files. (If you know what I mean.)

 --> If this is not the case and we can have only 1C++ file = 1HTML page
(of install/user documentation), then we would need some page naming
conventions and referencing rules.


Petr

-----Original Message-----
From: address@hidden
[mailto:address@hidden On
Behalf Of Eric Noulard
Sent: Monday, October 13, 2008 5:48 PM
To: CERTI development discussions
Subject: [certi-dev] New documenation generation system for CERTI

Hi All,

I have just commited a first try for a new Documentation generation
system for CERTI.
As explained in https://savannah.nongnu.org/bugs/?20850

The idea is to have 3 sets of documents:
- CERTI Install Documentation
- CERTI User Documentation
- CERTI Developer Documentation

in order to fullfil the differents "level of information" needs.

I have tried to use Doxygen for all this documentation in order:

0) Have "portable" documentation format
    Doxygen input is a textual "markup" format
    (see http://www.stack.nl/~dimitri/doxygen/manual.html)
    which mimics HTML and/or LaTeX with some restriction
     and extension.

1) maintain ALL documentation in the CVS subtree
    certi/doc

2) be able to generate both HTML and PDF output (at least for Install
and User)

I've put the first result online here
(Developer doc has not been uploaded [yet] because its too big):

http://www.nongnu.org/certi/certi_doc/index.html

All the content has been generated with CMake, Doxygen and pdflatex from
the content of certi/doc directory.

I'll explain in a second e-mail how it works.

Documentation contributor must only know that:

all documentation should be either:

  0) in a *.dox file located in certi/doc
  1) in the C++ source code itself

One must "learn" the Doxxygen markup but as one will see there is
nothing difficult with doxygen markup beside the fact that this is not
WYSIWYG.



--
Erk


-- 
CERTI-Devel mailing list
address@hidden
http://lists.nongnu.org/mailman/listinfo/certi-devel