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

generate_reference_manual version 1.3.1: 

* Fixed incompatibility with variants of grep that do not support -P option (e.g. MacOS X)
* Fixed bug when processing "&&" string
* Fixed bug when a template class nested type is declared with template keyword
* Fixed bug in @commentheading
* Fixed bug in parameters parsing
* Fixed template declaration of nested template classes in \ccParameters section
* In the \ccParameters section, template parameters are now on a unique line to workaround a bug with typedef parameters types
* Added support of `' and '''' to emphasize words (besides "")
This commit is contained in:
Laurent Saboret 2010-06-20 17:41:44 +00:00
parent cc820c185e
commit c76930c46a
2 changed files with 21 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
Manual_tools/scripts/generate_reference_manual/copy_doxygen_latex_doc
View File

@ -6,7 +6,7 @@
# Extract documentation from a doxygen-generated latex file # Extract documentation from a doxygen-generated latex file
# and insert it in a CGAL Reference Manual's latex file # and insert it in a CGAL Reference Manual's latex file
# #
# Laurent Saboret, INRIA, 2005-2008 # Laurent Saboret, INRIA, 2005-2010
################################################################ ################################################################
@ -249,11 +249,11 @@ sub doxygen_latex_to_latex
# Use a canonic style to ease parsing # Use a canonic style to ease parsing
$buf =~ s/ *, *([^\\])/, $1/g; # Use a canonic style "item1, item2" for lists. $buf =~ s/ *, *([^\\])/, $1/g; # Use a canonic style "item1, item2" for lists.
$buf =~ s/([\w\>]+) *& *([^\'])/$1& $2/g; # Use a canonic style "type& variable" for references $buf =~ s/([\w\>]+) *& *([^\'&])/$1& $2/g; # Use a canonic style "type& variable" for references
# without modifying 'type&'. # without modifying 'type&'.
$buf =~ s/(\w)=/$1 =/g; # Use a canonic style "variable = default" for default. parameters $buf =~ s/(\w)=/$1 =/g; # Use a canonic style "variable = default" for default. parameters
$buf =~ s/=(\w)/= $1/g; # "" $buf =~ s/=(\w)/= $1/g; # ""
$buf =~ s/<\s*(.*?)\s*>/<$1>/g; # Use a canonic style "type<parameters>" for template. parameters $buf =~ s/<\s*([^<]*?)\s*>/<$1>/g; # Use a canonic style "type<parameters>" for template. parameters
$buf =~ s/Constructor& Destructor/Constructor & Destructor/g; $buf =~ s/Constructor& Destructor/Constructor & Destructor/g;
$buf =~ s/\\item\[(.*?): +\]/\\item\[$1:\]/g; $buf =~ s/\\item\[(.*?): +\]/\\item\[$1:\]/g;
@ -285,7 +285,7 @@ sub latex_mangle
$buf =~ s/\\ccSubHeading\{/\\subsubsection\{/g; $buf =~ s/\\ccSubHeading\{/\\subsubsection\{/g;
# Emphasize words surrounded by double quotes using \em, by stars using \bf [L. Saboret's extension]. # Emphasize words surrounded by double quotes using \em, by stars using \bf [L. Saboret's extension].
$buf =~ s/"(.*?)"/\{\\em $1\}/g; $buf =~ s/("|\'\'|``)(.*?)("|\'\'|``)/\{\\em $2\}/g;
$buf =~ s/\*(\w*?)\*/\{\\bf $1\}/g; $buf =~ s/\*(\w*?)\*/\{\\bf $1\}/g;
# #
@ -296,7 +296,8 @@ sub latex_mangle
# #
# 1) Trust user: wrap words surrounded by simple quotes by \ccc{} [L. Saboret's extension]. # 1) Trust user: wrap words surrounded by simple quotes by \ccc{} [L. Saboret's extension].
# Note: we use a one-liner to not insert a \ccc{} call inside an another one. # Note: we make sure to not insert a \ccc{} call inside an another one.
$buf =~ s/`(.*?)\'/\\ccc\{$1\}/g;
$buf =~ s/\'(((::|\w)+(<.*?>)?)+&?\**)\'/\\ccc\{$1\}/g; $buf =~ s/\'(((::|\w)+(<.*?>)?)+&?\**)\'/\\ccc\{$1\}/g;
# Add carriage returns around \ccc{} for the line by line substitution below. # Add carriage returns around \ccc{} for the line by line substitution below.
@ -321,7 +322,7 @@ sub latex_mangle
{ {
# Wrap C++ types, including template params, by \ccc{}. # Wrap C++ types, including template params, by \ccc{}.
# Note: we use a one-liner to not insert a \ccc{} call inside an another one. # Note: we use a one-liner to not insert a \ccc{} call inside an another one.
$line =~ s/((\w*(_|::)\w*(<.*?>)?)+)/\\ccc\{$1\}/g; $line =~ s/((\w*(_|::)(template\s+)?\w*(<.*?>)?)+)/\\ccc\{$1\}/g;
# Add carriage returns around \ccc{} for the line by line substitution below. # Add carriage returns around \ccc{} for the line by line substitution below.
# Note: make sure to insert only one \n before and after each \ccc{} call. # Note: make sure to insert only one \n before and after each \ccc{} call.
@ -330,7 +331,7 @@ sub latex_mangle
$buf = $buf . $line . "\n"; # concat lines back to $buf $buf = $buf . $line . "\n"; # concat lines back to $buf
} }
# 3) Try to be smart: concepts name by \ccc{}. # 3) Try to be smart: wrap concepts name by \ccc{}.
@lines = split(/\n/, $buf); @lines = split(/\n/, $buf);
$buf = ""; $buf = "";
foreach $line (@lines) { foreach $line (@lines) {
@ -534,11 +535,11 @@ sub format_comment_headings
# Convert function parameters, enum values and return value descriptions to \ccCommentHeading to minimize length and indentation # Convert function parameters, enum values and return value descriptions to \ccCommentHeading to minimize length and indentation
$buf =~ s/\\begin\{description\}\s*\\item\[(Returns):\]\s*(.*?)\s*\\end\{description\}/\\ccCommentHeading\{$1\} $2/smg; $buf =~ s/\\begin\{description\}\s*\\item\[(Returns):\]\s*(.*?)\s*\\end\{description\}/\\ccCommentHeading\{$1\} $2/smg;
$buf =~ s/\\begin\{description\}\s*\\item\[(Parameters|Template Parameters|Values)\n*:\]\s*(\\begin\{description\}.*?\\end\{description\})\s*\\end\{description\}/\\ccCommentHeading\{$1\}\n$2/smg; $buf =~ s/\\begin\{description\}\s*\\item\[([^\]]*?)\n*:\]\s*(\\begin\{description\}.*?\\end\{description\})\s*\\end\{description\}/\\ccCommentHeading\{$1\}\n$2/smg;
# Replace list items in bold (ie with square brackets around item) by italics (using \ccc macro). # Replace list items in bold (ie with square brackets around item) by italics (using \ccc macro).
$buf =~ s/\\item\[(.*?):\s*\]/\\item $1: /smg; # regular list items (end by ':') => no italics $buf =~ s/\\item\[([^\]]*?):\s*\]/\\item $1: /smg; # regular list items (end by ':') => no italics
$buf =~ s/\\item\[(.*?)\s*\]/\\item \\ccc\{$1\}: /smg; # parameters => italics $buf =~ s/\\item\[([^\]]*?)\s*\]/\\item \\ccc\{$1\}: /smg; # parameters => italics
# Flatten lists to save space and workaround a cgal_manual bug which does not # Flatten lists to save space and workaround a cgal_manual bug which does not
# print properly lists inside the second curly braces pair of \ccXXX expressions. # print properly lists inside the second curly braces pair of \ccXXX expressions.
@ -769,11 +770,11 @@ sub format_doxygen_class_doc
my $full_template_declarations = $1; my $full_template_declarations = $1;
# Split template declaration(s) on several lines # Split template declaration(s) on several lines
$full_template_declarations =~ s/(template<|, |> )(class|struct|typename)/$1\n$2/g; # add \n before each param $full_template_declarations =~ s/>template/>\ntemplate/g; # add \n before nested templates
$full_template_declarations =~ s/(class|struct) (\w+::)*\Q$className\E.*/$1 $className;/g; $full_template_declarations =~ s/(class|struct) (\w+(<.*?>)?::)*\Q$className\E.*/\n$1 $className;/g;
# keep only class/struct/concept name on last line # keep only class/struct/concept name on last line
$full_template_declarations =~ s/\n/ \\\\\n/smg; # add \\ at the end of each line to force EOL $full_template_declarations =~ s/\n/ \\\\\n/smg; # add \\ at the end of each line to force EOL
$full_template_declarations =~ s/^ *\\\\\n//smg; # "" $full_template_declarations =~ s/^ *\\\\\n//smg; # ""
# Insert template params at the beginning of \ccParameters section # Insert template params at the beginning of \ccParameters section
$buf =~ s/\\ccParameters\n/\\ccParameters\n\n$full_template_declarations\n/; $buf =~ s/\\ccParameters\n/\\ccParameters\n\n$full_template_declarations\n/;

10
Manual_tools/scripts/generate_reference_manual/generate_reference_manual
View File

@ -2,7 +2,7 @@
# -------------------------------------------------------------------------- # --------------------------------------------------------------------------
# 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, 2005-2009 # Author : Laurent Saboret, INRIA, 2005-2010
# -------------------------------------------------------------------------- # --------------------------------------------------------------------------
@ -35,10 +35,10 @@ exit 1
# -------------------------------------------------------------------------- # --------------------------------------------------------------------------
# Turn traces on # Turn traces on
# set -x #set -x
# Version # Version
echo "generate_reference_manual version 1.3" echo "generate_reference_manual version 1.3.1"
# Global variables # Global variables
DOC_TEX_FOLDER="" # Package's doc_tex/ folder DOC_TEX_FOLDER="" # Package's doc_tex/ folder
@ -217,11 +217,11 @@ do
# Test if ${item} is a function in the global scope # Test if ${item} is a function in the global scope
[ ! -f "${doxygen_doc}" ] && \ [ ! -f "${doxygen_doc}" ] && \
doxygen_doc=`grep -l -P '\\\\paragraph.*?\\{.*\\b'${item_latex_name}'\\s*\\(' \ doxygen_doc=`grep -l -E '\\\\paragraph.*?\\{.*\\b'${item_latex_name}'\\b' \
"doc_doxygen/latex/${item_base_file_name}_8h.tex" 2>/dev/null` "doc_doxygen/latex/${item_base_file_name}_8h.tex" 2>/dev/null`
# Test if ${item} is a function in a namespace # Test if ${item} is a function in a namespace
[ ! -f "${doxygen_doc}" ] && \ [ ! -f "${doxygen_doc}" ] && \
doxygen_doc=`grep -l -P '\\\\paragraph.*?\\{.*\\b'${item_latex_name}'\\s*\\(' \ doxygen_doc=`grep -l -E '\\\\paragraph.*?\\{.*\\b'${item_latex_name}'\\b' \
"doc_doxygen/latex/${namespace_tex_file}" 2>/dev/null` "doc_doxygen/latex/${namespace_tex_file}" 2>/dev/null`
done done