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 sub usage
{ {
print <<"END_USAGE"; print <<"END_USAGE";
copy_doxygen_latex_doc version 0.8. copy_doxygen_latex_doc extracts a documentation from a doxygen-generated latex file and inserts it in a CGAL Reference Manual's latex file.
Extract documentation from a doxygen-generated latex file and insert it in a CGAL Reference Manual's latex file.
Usage: Usage:
copy_doxygen_latex_doc [options] doxygen_generated_documentation.tex template_manual.tex copy_doxygen_latex_doc [options] doxygen_generated_documentation.tex template_manual.tex
-h, --help Print this help -h, --help Print this help
-f, --force Insert missing %START-AUTO..%END-AUTO sections -f, --force Insert missing %START-AUTO..%END-AUTO sections
Tips: See generate_reference_manual usage for details.
* 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.
END_USAGE END_USAGE
exit; exit;

30
Manual_tools/scripts/generate_reference_manual/generate_reference_manual
View File

@ -1,8 +1,8 @@
#!/bin/bash #!/bin/bash
# Goal : Generate automatically (most of) the Reference Manual of a CGAL package # 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 # Usage
# ------ # ------
@ -10,41 +10,47 @@ usage ()
{ {
echo "\ 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. 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. 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: Usage:
generate_reference_manual [options] /path/to/package/root generate_reference_manual [options] /path/to/package/root
-h, --help Print this help -h, --help Print this help
-f, --force Insert missing %START-AUTO..%END-AUTO sections -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. 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. 2) Run generate_reference_manual --force to create the %START-AUTO..%END-AUTO sections.
3) Run cgal_manual. 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: 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. 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). 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. 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. 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). * 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. * generate_reference_manual generates a documentation for public and protected items only.
* A comment starting by 'Sub-concept:' will be converted to a \ccRefines paragraph. * "Words surrounded by double quotes" are emphasized. Words containing an underscore are automatically emphasized.
* A comment starting by 'Models:' will be converted to a \ccHasModels paragraph. * A comment starting by 'Concept:' is converted to a \ccIsModel paragraph.
* A comment starting by 'Design pattern:' will be converted to a \ccHeading{Design Pattern} paragraph. * A comment starting by 'Sub-concept:' is converted to a \ccRefines paragraph.
* A comment starting by 'Template parameters:' will be converted to \ccParameters paragraph. * A comment starting by 'Models:' is converted to a \ccHasModels paragraph.
* \"Words surrounded by double quotes\" will be emphasized. * 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: 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. * 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." Please contact Laurent Saboret <Laurent.Saboret@sophia.inria.fr> if you discover a bug or wish to request for an enhancement."
exit 1 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. 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. 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. 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 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_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 generate_reference_manual [options] /path/to/package/root
-h, --help Print this help -h, --help Print this help
-f, --force Insert missing %START-AUTO..%END-AUTO sections -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. 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. 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. 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. 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). * 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. * generate_reference_manual generates a documentation for public and protected items only.
* A comment starting by 'Sub-concept:' will be converted to a \ccRefines paragraph. * "Words surrounded by double quotes" are emphasized. Words containing an underscore are automatically emphasized.
* A comment starting by 'Models:' will be converted to a \ccHasModels paragraph. * A comment starting by 'Concept:' is converted to a \ccIsModel paragraph.
* A comment starting by 'Design pattern:' will be converted to a \ccHeading{Design Pattern} paragraph. * A comment starting by 'Sub-concept:' is converted to a \ccRefines paragraph.
* A comment starting by 'Template parameters:' will be converted to \ccParameters paragraph. * A comment starting by 'Models:' is converted to a \ccHasModels paragraph.
* "Words surrounded by double quotes" will be emphasized. * 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. * 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. Please contact Laurent Saboret <Laurent.Saboret@sophia.inria.fr> if you discover a bug or wish to request for an enhancement.