songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated usage and read-me

This commit is contained in:
Laurent Saboret 2008-01-31 16:13:00 +00:00
parent 113cd5d51b
commit 1771d4abb1
3 changed files with 36 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
Manual_tools/scripts/generate_reference_manual/copy_doxygen_latex_doc
View File

@ -667,26 +667,14 @@ sub merge_manuals
sub usage
{
print <<"END_USAGE";
copy_doxygen_latex_doc version 0.8.
Extract documentation from a doxygen-generated latex file and insert it in a CGAL Reference Manual's latex file.
copy_doxygen_latex_doc extracts a documentation from a doxygen-generated latex file and inserts it in a CGAL Reference Manual's latex file.
Usage:
copy_doxygen_latex_doc [options] doxygen_generated_documentation.tex template_manual.tex
-h, --help Print this help
-f, --force Insert missing %START-AUTO..%END-AUTO sections
Tips:
* A comment starting by 'Concept:' will be converted to a \ccIsModel paragraph.
* A comment starting by 'Sub-concept:' will be converted to a \ccRefines paragraph.
* A comment starting by 'Models:' will be converted to a \ccHasModels paragraph.
* A comment starting by 'Design pattern:' will be converted to a \ccHeading{Design Pattern} paragraph.
* A comment starting by 'Template parameters:' will be converted to \ccParameters paragraph.
* \"Words surrounded by double quotes\" will be emphasized.
Known bugs:
* This tool has been tested with doxygen 1.4 and 1.5. It may *not* work with other versions of doxygen.
* So far, this tool documents only concepts, classes, structs and functions.
See generate_reference_manual usage for details.
END_USAGE
exit;

30
Manual_tools/scripts/generate_reference_manual/generate_reference_manual
View File

@ -1,8 +1,8 @@
#!/bin/bash
# Goal : Generate automatically (most of) the Reference Manual of a CGAL package
# Author : Laurent Saboret, INRIA, 09/2005
# ----------------------------------------
# Author : Laurent Saboret, INRIA, 2005-2008
# ------------------------------------------
# Usage
# ------
@ -10,41 +10,47 @@ usage ()
{
echo "\
generate_reference_manual automatically generates (most of) the Reference Manual of a CGAL package. It runs doxygen to generate a Latex documentation from C++ source code, then converts it to CGAL Manual format.
If the C++ source code is commented, this tool generates the whole Reference Manual of the package (except the introduction page). If not, it generates a raw latex documentation that you will have to complete manually.
generate_reference_manual automatically generates (most of) the Reference Manual of a CGAL package. It runs Doxygen to generate a Latex documentation from C++ source code, then converts it to CGAL Manual format.
If the C++ source code is commented, this tool generates the whole Reference Manual of the package (except the introduction page). If not, it generates a raw latex documentation that you have to complete manually.
Note that this tool adds or updates automatic documentation and does *not* remove the documentation manually written. Tags %START-AUTO and %END-AUTO clearly deliminate the automatic documentation.
Usage:
generate_reference_manual [options] /path/to/package/root
-h, --help Print this help
-f, --force Insert missing %START-AUTO..%END-AUTO sections
Typical scenario:
1) Create the package's Reference Manual as described in CGAL Developer Manual.
2) Run generate_reference_manual --force to create the %START-AUTO..%END-AUTO sections.
3) Run cgal_manual.
4) Look at the generated documentation in the Reference Manual .tex files and in the PS/PDF/HTML final Reference manual. In order to complete it, you may:
a) Comment the C++ source code using doxygen conventions.
a) Comment the C++ source code using Doxygen conventions.
b) Write extra documentation in .tex files outside of automatic sections.
c) Modify automatic sections (make sure to delete the %START-AUTO and %END-AUTO tags).
5) Run generate_reference_manual. Do not use the --force option anymore if you modified automatic sections.
6) Goto point 3) until the Reference Manual is complete.
Tips:
* To generate a concept's documentation, you may create a fake C++ class named after the concept anywhere in the package's folders tree (use the dont_submit file to ignore it in CGAL releases).
* A comment starting by 'Concept:' will be converted to a \ccIsModel paragraph.
* A comment starting by 'Sub-concept:' will be converted to a \ccRefines paragraph.
* A comment starting by 'Models:' will be converted to a \ccHasModels paragraph.
* A comment starting by 'Design pattern:' will be converted to a \ccHeading{Design Pattern} paragraph.
* A comment starting by 'Template parameters:' will be converted to \ccParameters paragraph.
* \"Words surrounded by double quotes\" will be emphasized.
* generate_reference_manual generates a documentation for public and protected items only.
* "Words surrounded by double quotes" are emphasized. Words containing an underscore are automatically emphasized.
* A comment starting by 'Concept:' is converted to a \ccIsModel paragraph.
* A comment starting by 'Sub-concept:' is converted to a \ccRefines paragraph.
* A comment starting by 'Models:' is converted to a \ccHasModels paragraph.
* A comment starting by 'Design pattern:' is converted to a \ccHeading{Design Pattern} paragraph.
* A comment starting by 'Template parameters:' is converted to \ccParameters paragraph.
* 2 comments '@cond SKIP_IN_MANUAL' and '@endcond' delimit a section ignored by generate_reference_manual.
Known bugs:
* This tool has been tested with doxygen 1.4 and 1.5. It may *not* work with other versions of doxygen.
* So far, this tool documents only concepts, classes, structs and functions.
Contact:
Please contact Laurent Saboret <Laurent.Saboret@sophia.inria.fr> if you discover a bug or wish to request for an enhancement."
exit 1
}

31
Manual_tools/scripts/generate_reference_manual/readme.txt
View File

@ -2,26 +2,26 @@ generate_reference_manual
*************************
generate_reference_manual automatically generates (most of) the Reference Manual of a CGAL package. It runs Doxygen to generate a Latex documentation from C++ source code, then converts it to CGAL Manual format.
If the C++ source code is commented, this tool generates the whole Reference Manual of the package (except the introduction page). If not, it generates a raw latex documentation that you will have to complete manually.
If the C++ source code is commented, this tool generates the whole Reference Manual of the package (except the introduction page). If not, it generates a raw latex documentation that you have to complete manually.
Note that this tool adds or updates automatic documentation and does *not* remove the documentation manually written. Tags %START-AUTO and %END-AUTO clearly deliminate the automatic documentation.
INSTALLATION
Installation:
This is a shell script, thus for Unix only.
generate_reference_manual and copy_doxygen_latex_doc must be in the PATH.
generate_reference_manual_Doxyfile must be in the same folder as generate_reference_manual.
generate_reference_manual requires Perl (any recent version) and Doxygen (Doxygen 1.4 or 1.5).
generate_reference_manual requires Perl (any recent version) and Doxygen >= 1.4.
USAGE
Usage:
generate_reference_manual [options] /path/to/package/root
-h, --help Print this help
-f, --force Insert missing %START-AUTO..%END-AUTO sections
TYPICAL SCENARIO
Typical scenario:
1) Create the package's Reference Manual as described in CGAL Developer Manual.
2) Run generate_reference_manual --force to create the %START-AUTO..%END-AUTO sections.
@ -33,21 +33,22 @@ TYPICAL SCENARIO
5) Run generate_reference_manual. Do not use the --force option anymore if you modified automatic sections.
6) Goto point 3) until the Reference Manual is complete.
TIPS
Tips:
* To generate a concept's documentation, you may create a fake C++ class named after the concept anywhere in the package's folders tree (use the dont_submit file to ignore it in CGAL releases).
* A comment starting by 'Concept:' will be converted to a \ccIsModel paragraph.
* A comment starting by 'Sub-concept:' will be converted to a \ccRefines paragraph.
* A comment starting by 'Models:' will be converted to a \ccHasModels paragraph.
* A comment starting by 'Design pattern:' will be converted to a \ccHeading{Design Pattern} paragraph.
* A comment starting by 'Template parameters:' will be converted to \ccParameters paragraph.
* "Words surrounded by double quotes" will be emphasized.
* generate_reference_manual generates a documentation for public and protected items only.
* "Words surrounded by double quotes" are emphasized. Words containing an underscore are automatically emphasized.
* A comment starting by 'Concept:' is converted to a \ccIsModel paragraph.
* A comment starting by 'Sub-concept:' is converted to a \ccRefines paragraph.
* A comment starting by 'Models:' is converted to a \ccHasModels paragraph.
* A comment starting by 'Design pattern:' is converted to a \ccHeading{Design Pattern} paragraph.
* A comment starting by 'Template parameters:' is converted to \ccParameters paragraph.
* 2 comments '@cond SKIP_IN_MANUAL' and '@endcond' delimit a section ignored by generate_reference_manual.
KNOWNS BUGS
Known bugs:
* This tool has been tested on Linux with Doxygen 1.4 and 1.5. It is likely that it will *not* work with other versions of Doxygen.
* So far, this tool documents only concepts, classes, structs and functions.
CONTACT
Contact:
Please contact Laurent Saboret <Laurent.Saboret@sophia.inria.fr> if you discover a bug or wish to request for an enhancement.