diff --git a/Manual_tools/scripts/generate_reference_manual/copy_doxygen_latex_doc b/Manual_tools/scripts/generate_reference_manual/copy_doxygen_latex_doc index c72975a9ed9..07efaa4e907 100755 --- a/Manual_tools/scripts/generate_reference_manual/copy_doxygen_latex_doc +++ b/Manual_tools/scripts/generate_reference_manual/copy_doxygen_latex_doc @@ -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; diff --git a/Manual_tools/scripts/generate_reference_manual/generate_reference_manual b/Manual_tools/scripts/generate_reference_manual/generate_reference_manual index ea008263da7..f211bf6bf85 100755 --- a/Manual_tools/scripts/generate_reference_manual/generate_reference_manual +++ b/Manual_tools/scripts/generate_reference_manual/generate_reference_manual @@ -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 if you discover a bug or wish to request for an enhancement." exit 1 } diff --git a/Manual_tools/scripts/generate_reference_manual/readme.txt b/Manual_tools/scripts/generate_reference_manual/readme.txt index cae19aa0e00..6403c54bce9 100644 --- a/Manual_tools/scripts/generate_reference_manual/readme.txt +++ b/Manual_tools/scripts/generate_reference_manual/readme.txt @@ -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 if you discover a bug or wish to request for an enhancement.