mirror of https://github.com/CGAL/cgal
Version 1.0.2:
- The tool does not display doxygen warnings by default. Use --verbose to have them back. - \ccInclude, \ccRefine and \ccInheritsFrom commands are extracted from source code. - Fixed bug when using @related doxygen keywords. - Fixed bug in removal of cc_ref_wizard placeholder text.
This commit is contained in:
Laurent Saboret
parent
ac02b48cf3
commit
eb9eca14de
|
|
@ -14,21 +14,25 @@ use strict;
|
|||
use File::Copy;
|
||||
|
||||
|
||||
##################
|
||||
# Global variables
|
||||
##################
|
||||
###########
|
||||
# Constants
|
||||
###########
|
||||
|
||||
# List of sections in a CGAL Reference Manual latex file.
|
||||
# The list order defines the default position when a section is inserted.
|
||||
my @known_section_titles = ('\ccDefinition', '\ccParameters', '\ccInheritsFrom', '\ccRefines',
|
||||
'\ccGeneralizes', '\ccIsModel', '\ccHeading{Design Pattern}', '\ccTypes', '\ccConstants',
|
||||
'\ccHeading{Variables}', '\ccCreation', '\ccOperations', '\ccHasModels', '\ccImplementation',
|
||||
'\ccExample', '\ccSeeAlso');
|
||||
my @known_section_titles = (
|
||||
'\ccDefinition', '\ccInclude', '\ccParameters', '\ccInheritsFrom', '\ccRefines',
|
||||
'\ccGeneralizes', '\ccIsModel', '\ccHeading{Design Pattern}', '\ccTypes',
|
||||
'\ccConstants', '\ccHeading{Variables}', '\ccCreation', '\ccOperations',
|
||||
'\ccHeading{Friends And Related Functions}', '\ccHasModels', '\ccImplementation',
|
||||
# '\ccHeading{Misc}',
|
||||
'\ccSeeAlso', '\ccExample'
|
||||
);
|
||||
|
||||
# List of placeholder lines generated by cc_ref_wizard.
|
||||
# They will be replaced by the generated documentation.
|
||||
my @placeholders = (
|
||||
'The \w+ \\\\ccRefName\\\\ does this and that\.',
|
||||
'The .*? \\\\ccRefName\\\\ does this and that\.',
|
||||
'\\\\ccGlobalFunction\{void \w+\(\);\}',
|
||||
'Concept',
|
||||
'ThisConcept \\\\\\\\',
|
||||
|
|
@ -44,10 +48,7 @@ my @placeholders = (
|
|||
my %macro_names = (
|
||||
'\ccHeading{Has Models}' => '\ccHasModels',
|
||||
'\ccHeading{Is Model for the Concepts}' => '\ccIsModel',
|
||||
'\ccHeading{Refines}' => '\ccRefines',
|
||||
'\ccHeading{Design Pattern}' => '\ccHeading{Design Pattern}',
|
||||
# '\ccHeading{Parameters}' => '\ccParameters',
|
||||
'\ccHeading{Inherits From}' => '\ccInheritsFrom',
|
||||
'\ccHeading{Generalizes}' => '\ccGeneralizes',
|
||||
'\ccHeading{Requirements}' => '\ccRequirements',
|
||||
'\ccHeading{Access Functions}' => '\ccAccessFunctions',
|
||||
|
|
@ -55,6 +56,7 @@ my %macro_names = (
|
|||
'\ccHeading{Predicates}' => '\ccPredicates',
|
||||
'\ccHeading{Modifiers}' => '\ccModifiers',
|
||||
'\ccHeading{Implementation}' => '\ccImplementation',
|
||||
# '\ccHeading{Parameters}' => '\ccParameters', # processed separately
|
||||
);
|
||||
|
||||
# Warning sentence before automatically generated sections
|
||||
|
|
@ -64,10 +66,42 @@ my $warning = "% The section below is automatically generated. Do not edit!";
|
|||
my $creation_variable = '\ccCreationVariable{a} %% choose variable name for \ccMethod below';
|
||||
|
||||
|
||||
##################
|
||||
# Global variables
|
||||
##################
|
||||
|
||||
my $debug = 0; # Debug mode?
|
||||
my $verbose = 0; # Verbose mode?
|
||||
|
||||
|
||||
###########
|
||||
# Functions
|
||||
###########
|
||||
|
||||
# Print a string if Debug mode.
|
||||
sub trace
|
||||
{
|
||||
# Get parameter: string to print
|
||||
my $str = shift;
|
||||
|
||||
if ($debug) {
|
||||
print $str;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
# Print a string if Verbose mode.
|
||||
sub print_verbose
|
||||
{
|
||||
# Get parameter: string to print
|
||||
my $str = shift;
|
||||
|
||||
if ($verbose) {
|
||||
print $str;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
# Remove the placeholder text generated by cc_ref_wizard
|
||||
# before inserting the generated documentation.
|
||||
# Param: a buffer containing a CGAL Reference Manual template
|
||||
|
|
@ -86,18 +120,20 @@ sub remove_cc_ref_wizard_placeholders
|
|||
}
|
||||
|
||||
|
||||
# Construct a pattern that matches any section title
|
||||
# Construct a pattern that matches any CGAL manual section's title.
|
||||
# Note: prefixing or postfixing the pattern by ^ does not work.
|
||||
sub get_any_section_title_pattern
|
||||
{
|
||||
# Match \ccHeading{...}
|
||||
my $pattern = "(\\\\ccHeading\\\{.*?}";
|
||||
my $pattern = "(\\\\ccHeading\\\{.*?\\\}";
|
||||
|
||||
# Match any title in @known_section_titles
|
||||
foreach my $t (@known_section_titles) {
|
||||
$pattern = $pattern . "|\Q$t\E";
|
||||
}
|
||||
|
||||
$pattern = $pattern . ")";
|
||||
# Match \end{ccRef...} == end of CGAL Reference Manual template
|
||||
$pattern = $pattern . "|\\\\end\\\{ccRef.*?\\\})";
|
||||
|
||||
return $pattern;
|
||||
}
|
||||
|
|
@ -176,6 +212,7 @@ sub doxygen_latex_to_latex
|
|||
$buf =~ s/Implemented in .*//g; # Same thing with "Implemented in"
|
||||
$buf =~ s/Reimplemented in .*//g; # Same thing with "Reimplemented in"
|
||||
$buf =~ s/\[package\]//g;
|
||||
$buf =~ s/\[related\]//g;
|
||||
|
||||
# Add a \n before (parameters) descriptions to ease parsing
|
||||
$buf =~ s/\n?\\begin\{Desc\}/\n\\begin\{Desc\}/smg;
|
||||
|
|
@ -211,7 +248,7 @@ sub latex_mangle
|
|||
# We add carriage returns around \ccc{} for next line by line substitutions.
|
||||
$buf =~ s/\'(((::|\w)+(<.*?>)?)+)\'/\n\\ccc{$1\}\n/g;
|
||||
|
||||
# \ccHeading, \ccNestedType, \ccEnum, \ccConstructor, \ccMethod, \ccVariable & \ccFunction
|
||||
# \ccInclude, \ccHeading, \ccNestedType, \ccEnum, \ccConstructor, \ccMethod, \ccVariable & \ccFunction
|
||||
# first curly braces pair must contain plain C++ code.
|
||||
# \subsubsection must protect _ as \_.
|
||||
# For the other lines, we wrap C++ types by \ccc{}.
|
||||
|
|
@ -219,7 +256,7 @@ sub latex_mangle
|
|||
$buf = "";
|
||||
foreach $line (@lines) {
|
||||
# if first curly braces pair of a cgal_manual macro
|
||||
if ($line =~ /\\(ccHeading|ccSubHeading|ccNestedType|ccEnum|ccConstructor|ccMethod|ccVariable|ccFunction)/
|
||||
if ($line =~ /\\(ccInclude|ccHeading|ccSubHeading|ccNestedType|ccEnum|ccConstructor|ccMethod|ccVariable|ccFunction)/
|
||||
|| $line =~ /\\ccc/)
|
||||
{
|
||||
# nothing to do
|
||||
|
|
@ -237,7 +274,7 @@ sub latex_mangle
|
|||
$buf = $buf . $line . "\n"; # concat lines back to $buf
|
||||
}
|
||||
|
||||
# \ccHeading, \ccNestedType, \ccEnum, \ccConstructor, \ccMethod, \ccVariable & \ccFunction
|
||||
# \ccInclude, \ccHeading, \ccNestedType, \ccEnum, \ccConstructor, \ccMethod, \ccVariable & \ccFunction
|
||||
# first curly braces pair and \ccc expressions must contain plain C++ code.
|
||||
# The other lines must contain regular latex text => we mangle back
|
||||
# ~, <, >, *, &, [] characters (see latex_unmangle() above).
|
||||
|
|
@ -245,7 +282,7 @@ sub latex_mangle
|
|||
$buf = "";
|
||||
foreach $line (@lines) {
|
||||
# if first curly braces pair of a cgal_manual macro: plain C++ code
|
||||
if ($line =~ /\\(ccHeading|ccSubHeading|ccNestedType|ccEnum|ccConstructor|ccMethod|ccVariable|ccFunction)/
|
||||
if ($line =~ /\\(ccInclude|ccHeading|ccSubHeading|ccNestedType|ccEnum|ccConstructor|ccMethod|ccVariable|ccFunction)/
|
||||
|| $line =~ /\\ccc/)
|
||||
{
|
||||
# Remove extra spaces to please cgal_manual
|
||||
|
|
@ -406,7 +443,7 @@ sub extented_format_headings
|
|||
# Rename \ccNestedType, \ccEnum, \ccConstructor, \ccMethod, \ccVariable and \ccFunction expressions.
|
||||
# Params:
|
||||
# - concept/struct/class/... to document (without namespace)
|
||||
# - type of the item to document: "class/struct" or "function"
|
||||
# - type of the item to document: "class/struct/concept" or "function"
|
||||
# - buffer containing a doxygen-generated latex file
|
||||
# Return value: the formatted buffer
|
||||
sub format_curly_brace_pairs_expressions
|
||||
|
|
@ -414,15 +451,15 @@ sub format_curly_brace_pairs_expressions
|
|||
# Get parameters:
|
||||
# - concept/struct/class/... to document (without namespace)
|
||||
my $item_to_document = shift;
|
||||
# - type of the item to document: "class/struct" or "function"
|
||||
# - type of the item to document: "class/struct/concept" or "function"
|
||||
my $item_type = shift;
|
||||
# - buffer containing a doxygen-generated latex file
|
||||
my $buf = shift;
|
||||
|
||||
# Rename \ccNestedType, \ccEnum, \ccConstructor, \ccMethod, \ccVariable and \ccFunction expressions
|
||||
# and open a curly brace for the expression's comment
|
||||
# - if class/struct...
|
||||
if ($item_type =~ m/class\/struct/)
|
||||
# - if class/struct/concept...
|
||||
if ($item_type eq "class/struct/concept")
|
||||
{
|
||||
$buf =~ s/\\paragraph\{typedef.* (\w+)((\[.*\])?)\}/\\ccNestedType\{$1$2\}\n\{/g;
|
||||
$buf =~ s/\\paragraph\{enum\s(.*)\}/\\ccEnum\{enum $1\}\n\{/g;
|
||||
|
|
@ -478,20 +515,23 @@ sub format_curly_brace_pairs_expressions
|
|||
}
|
||||
|
||||
|
||||
# Format a buffer containing a doxygen-generated documentation of a class/struct,
|
||||
# Format a buffer containing a doxygen-generated documentation of a class/struct/concept,
|
||||
# in latex, to match CGAL Reference Manual's format.
|
||||
# Params:
|
||||
# - class/struct name (without namespace)
|
||||
# - class/struct/concept name (without namespace)
|
||||
# - buffer containing a doxygen-generated latex file
|
||||
# Return value: the formatted buffer
|
||||
sub format_doxygen_class_struct_doc
|
||||
sub format_doxygen_class_doc
|
||||
{
|
||||
# Get parameters:
|
||||
# - class/struct name (without namespace)
|
||||
# - class/struct/concept name (without namespace)
|
||||
my $className = shift;
|
||||
# - buffer containing a doxygen-generated latex file
|
||||
my $buf = shift;
|
||||
|
||||
# Construct a pattern that matches any section title
|
||||
my $all_titles_pattern = get_any_section_title_pattern();
|
||||
|
||||
# Local variables when parsing buffer line by lines
|
||||
my ($line, @lines);
|
||||
|
||||
|
|
@ -506,8 +546,27 @@ sub format_doxygen_class_struct_doc
|
|||
# that cgal_manual does not understand
|
||||
$buf = remove_blank_lines_in_macros($buf);
|
||||
|
||||
# Remove extra stuff and insert \ccSeeAlso title at the end of the document
|
||||
$buf =~ s/The documentation for this.*/\n\n\\ccSeeAlso\n\n\n/sm;
|
||||
# Rename (for a class/struct) or delete (for a concept) the include file
|
||||
# and insert \ccSeeAlso title at the end of the document.
|
||||
my $is_concept = 0;
|
||||
unless ($buf =~ s/^The documentation.*?include\/(.*?)\\end\{itemize\}/\n\n\\ccInclude\{$1\}\n\n\n\\ccSeeAlso\n\n\n/sm)
|
||||
{
|
||||
$is_concept = 1;
|
||||
$buf =~ s/The documentation for this.*/\n\n\\ccSeeAlso\n\n\n/sm;
|
||||
}
|
||||
|
||||
# Insert \ccInheritsFrom (for a class/struct) or \ccRefines (for a concept) section
|
||||
# before \ccSeeAlso (from detailed section).
|
||||
if ($buf =~ s/^Inherits (.*?)\.$//sm)
|
||||
{
|
||||
my $superclass = $1;
|
||||
|
||||
if ($is_concept) {
|
||||
$buf =~ s/\\ccSeeAlso/\\ccRefines\n\n$superclass\n\n\n\\ccSeeAlso/sm;
|
||||
} else {
|
||||
$buf =~ s/\\ccSeeAlso/\\ccInheritsFrom\n\n$superclass\n\n\n\\ccSeeAlso/sm;
|
||||
}
|
||||
}
|
||||
|
||||
# Rename "Heading Parameters:" comment in \ccDefinition section as \ccParameters [L. Saboret extension]
|
||||
# or insert a new section before \ccSeeAlso
|
||||
|
|
@ -525,7 +584,7 @@ sub format_doxygen_class_struct_doc
|
|||
# Split template declaration(s) on several lines
|
||||
$parameters =~ s/(template<|, |> )(class|struct|typename)/$1\n$2/g; # add \n before each param
|
||||
$parameters =~ s/(class|struct) (\w+::)*\Q$className\E.*/$1 $className;/g;
|
||||
# keep only class/struct name on last line
|
||||
# keep only class/struct/concept name on last line
|
||||
$parameters =~ s/\n/ \\\\\n/smg; # add \\ at the end of each line to force EOL
|
||||
$parameters =~ s/^ *\\\\\n//smg; # ""
|
||||
|
||||
|
|
@ -588,8 +647,18 @@ sub format_doxygen_class_struct_doc
|
|||
# Rename \ccOperations title
|
||||
$buf =~ s/\\subsubsection\{Member Function Documentation\}/\n\n\\ccOperations\n/;
|
||||
|
||||
# Rename \ccHeading{Friends And Related Functions} title
|
||||
$buf =~ s/\\subsubsection\{Friends And Related Function Documentation\}/\n\n\\ccHeading\{Friends And Related Functions\}\n/;
|
||||
|
||||
# # Fallback is \ccHeading{Misc} title
|
||||
# $buf =~ s/\\subsubsection\{.*?\}/\n\n\\ccHeading\{Misc\}\n/;
|
||||
|
||||
# Rename \ccFunction expressions
|
||||
$buf =~ s/(\\ccHeading\{Friends And Related Functions\}.*?$all_titles_pattern)/
|
||||
format_curly_brace_pairs_expressions("", "function", $1)/smge;
|
||||
|
||||
# Rename \ccNestedType, \ccEnum, \ccConstructor, \ccMethod, \ccVariable expressions
|
||||
$buf = format_curly_brace_pairs_expressions($className, "class/struct", $buf);
|
||||
$buf = format_curly_brace_pairs_expressions($className, "class/struct/concept", $buf);
|
||||
|
||||
# Remove CGAL:: prefix (implicit)
|
||||
$buf =~ s/CGAL::(\w+)/$1/g;
|
||||
|
|
@ -600,7 +669,6 @@ sub format_doxygen_class_struct_doc
|
|||
$buf = latex_mangle($buf);
|
||||
|
||||
# Remove brief documentation
|
||||
my $all_titles_pattern = get_any_section_title_pattern();
|
||||
$buf =~ s/\\subsection.*?($all_titles_pattern)/\n\n$1/sm;
|
||||
|
||||
# Return the formatted string
|
||||
|
|
@ -622,6 +690,9 @@ sub format_doxygen_function_doc
|
|||
# - buffer containing a doxygen-generated latex file
|
||||
my $buf = shift;
|
||||
|
||||
# Construct a pattern that matches any section title
|
||||
my $all_titles_pattern = get_any_section_title_pattern();
|
||||
|
||||
# Local variables when parsing buffer line by lines
|
||||
my ($line, @lines);
|
||||
|
||||
|
|
@ -680,6 +751,9 @@ sub format_doxygen_function_doc
|
|||
# Rename \ccDefinition title
|
||||
$buf =~ s/\\subsubsection\{Function Documentation\}/\\ccDefinition\n/;
|
||||
|
||||
# # Fallback is \ccHeading{Misc} title
|
||||
# $buf =~ s/\\subsubsection\{.*?\}/\n\n\\ccHeading\{Misc\}\n/;
|
||||
|
||||
# Rename \ccFunction expressions
|
||||
$buf = format_curly_brace_pairs_expressions($functionName, "function", $buf);
|
||||
|
||||
|
|
@ -692,7 +766,6 @@ sub format_doxygen_function_doc
|
|||
$buf = latex_mangle($buf);
|
||||
|
||||
# Remove brief documentation
|
||||
my $all_titles_pattern = get_any_section_title_pattern();
|
||||
$buf =~ s/\\subsection.*?($all_titles_pattern)/\n\n$1/sm;
|
||||
|
||||
# Return the formatted string
|
||||
|
|
@ -716,23 +789,34 @@ sub insert_manual_section
|
|||
my $doxy_buf = shift;
|
||||
# - section's title
|
||||
my $title = shift;
|
||||
# trace "call insert_manual_section($title)\n";
|
||||
|
||||
# Uncomment the next line to test that obsolete sections are properly *emptied*
|
||||
# $doxy_buf = "";
|
||||
|
||||
# Construct a pattern that matches any section title
|
||||
my $all_titles_pattern = get_any_section_title_pattern();
|
||||
|
||||
# Extract $title section from $doxy_buf
|
||||
# Extract $title section content from $doxy_buf
|
||||
my $section = "";
|
||||
if ($doxy_buf =~ /^\s*\Q$title\E\s(.*?)\s+$all_titles_pattern\s/sm) {
|
||||
if ($doxy_buf =~ /^\s*\Q$title\E(.*?)\s+$all_titles_pattern/sm) {
|
||||
# trace " 1: section exists in doxygen-generated latex file\n";
|
||||
$section = $1;
|
||||
$section =~ s/^\s+//s; # Remove heading & trailing spaces
|
||||
$section =~ s/\s+$//s; # and extra carriage returns
|
||||
}
|
||||
|
||||
# If $section is not empty, copy it to $cgal_buf
|
||||
# If $cgal_buf doesn't already contain $title, add it
|
||||
# If $cgal_buf doesn't already contain the %START-AUTO($title)..%END-AUTO($title) section, add it
|
||||
# If $section is not empty, copy it to $cgal_buf.
|
||||
# If $cgal_buf doesn't already contain $title, add it.
|
||||
# If $cgal_buf doesn't already contain the %START-AUTO($title)..%END-AUTO($title) section, add it.
|
||||
if ($section ne "")
|
||||
{
|
||||
# trace " 2: section is not empty\n";
|
||||
# Special case: \ccInclude section is a one-line macro
|
||||
if ($title eq '\ccInclude') {
|
||||
$section = '\ccInclude' . $section;
|
||||
}
|
||||
|
||||
# Add $warning\n%START-AUTO($title)..%END-AUTO($title) around $section
|
||||
$section = "$warning\n%START-AUTO($title)\n\n" . $section . "\n\n%END-AUTO($title)";
|
||||
|
||||
|
|
@ -740,45 +824,73 @@ sub insert_manual_section
|
|||
my $title_extra = ($title eq '\ccCreation') ? "\n$creation_variable" : "";
|
||||
|
||||
# If %START-AUTO..%END-AUTO section exists, replace it
|
||||
unless ($cgal_buf =~ s/($warning)*\s*%START-AUTO\(\Q$title\E\).*?%END-AUTO\(\Q$title\E\)/$section/sm)
|
||||
if ($cgal_buf =~ s/$warning*\s*%START-AUTO\(\Q$title\E\).*?%END-AUTO\(\Q$title\E\)/$section/sm)
|
||||
{
|
||||
# Else, insert a new %START-AUTO..%END-AUTO section
|
||||
# trace " 2.0\n";
|
||||
print_verbose " Update section $title\n";
|
||||
}
|
||||
else # Else, insert a new %START-AUTO..%END-AUTO section
|
||||
{
|
||||
# trace " 2.1\n";
|
||||
my $success = 0; # Successful insertion?
|
||||
|
||||
# If section's title exists, insert %START-AUTO..%END-AUTO section after it
|
||||
if ($cgal_buf =~ s/^(\s*\Q$title\E\b.*?)(\s+$all_titles_pattern\s)/$1\n\n$section$2/sm) {
|
||||
$success = 1;
|
||||
} else {
|
||||
# Else, insert title + %START-AUTO..%END-AUTO section before
|
||||
# the first section that appears after $title in @known_section_titles.
|
||||
my $after_title = 0; # indicate if we passed $title in @known_section_titles
|
||||
foreach my $t (@known_section_titles) {
|
||||
if ($after_title) {
|
||||
# Special case: \ccInclude section is a one-line macro
|
||||
if ($title eq '\ccInclude')
|
||||
{
|
||||
# trace " 2.1.1\n";
|
||||
# If \ccInclude{.*?} macro exists, *replace* it by %START-AUTO..%END-AUTO section
|
||||
if ($cgal_buf =~ s/^(\s*)\Q$title\E\{.*?\}/$1$section/sm) {
|
||||
# trace " 2.1.1.1: replace \ccInclude{.*?} by %START-AUTO..%END-AUTO section\n";
|
||||
$success = 1;
|
||||
}
|
||||
}
|
||||
else # if not \ccInclude
|
||||
{
|
||||
# trace " 2.1.2\n";
|
||||
# If section's title exists, *append* %START-AUTO..%END-AUTO section after it.
|
||||
if ($cgal_buf =~ s/^(\s*\Q$title\E.*?)(\s*$all_titles_pattern(\s|\b))/$1\n\n$section$2/sm) {
|
||||
# trace " 2.1.2.1: append %START-AUTO..%END-AUTO section after title\n";
|
||||
$success = 1;
|
||||
} else {
|
||||
# Else, insert title + %START-AUTO..%END-AUTO section before
|
||||
# the first section that appears after $title in @known_section_titles.
|
||||
my $after_title = 0; # indicate if we passed $title in @known_section_titles
|
||||
foreach my $t (@known_section_titles) {
|
||||
if ($after_title) {
|
||||
if ($cgal_buf =~ s/(\s+)(\Q$t\E\b)/$1$title$title_extra\n\n$section$1$2/sm) {
|
||||
$success = 1;
|
||||
last;
|
||||
}
|
||||
}
|
||||
if ($t eq $title) { $after_title = 1; }
|
||||
}
|
||||
# trace " 2.1.2.2: insert title + %START-AUTO..%END-AUTO section before $t\n";
|
||||
$success = 1;
|
||||
last;
|
||||
}
|
||||
}
|
||||
if ($t eq $title) { $after_title = 1; }
|
||||
}
|
||||
|
||||
# Else, insert title + %START-AUTO..%END-AUTO section
|
||||
# at the end of the buffer.
|
||||
unless ($success) {
|
||||
$success = ($cgal_buf =~ s/(\s+)(\\end\{ccRef)/$1$title$title_extra\n\n$section$1$2/sm);
|
||||
}
|
||||
# Else, insert title + %START-AUTO..%END-AUTO section at the end of the buffer
|
||||
unless ($success) {
|
||||
# trace " 2.1.2.3: insert title + %START-AUTO..%END-AUTO section at the end of the buffer\n";
|
||||
$success = ($cgal_buf =~ s/(\s+)(\\end\{ccRef)/$1$title$title_extra\n\n$section$1$2/sm);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Notify user
|
||||
if ($success) { print " Insert section $title\n"; }
|
||||
else { warn " Cannot insert section $title"; }
|
||||
if ($success) { print_verbose " Add section $title\n"; }
|
||||
else { warn " Cannot add section $title"; }
|
||||
}
|
||||
}
|
||||
# If $section is empty, empty %START-AUTO($title)..%END-AUTO($title) section in $cgal_buf
|
||||
else
|
||||
{
|
||||
# trace " 3\n";
|
||||
$section = "$warning\n%START-AUTO($title)\n%END-AUTO($title)";
|
||||
$cgal_buf =~ s/($warning)*\s*%START-AUTO\(\Q$title\E\).*?%END-AUTO\(\Q$title\E\)/$section/sm;
|
||||
|
||||
# If %START-AUTO..%END-AUTO section exists, empty it
|
||||
if ($cgal_buf =~ s/$warning*\s*%START-AUTO\(\Q$title\E\).*?%END-AUTO\(\Q$title\E\)/$section/sm)
|
||||
{
|
||||
# Notify user
|
||||
print_verbose " WARNING: section $title is empty!\n";
|
||||
}
|
||||
}
|
||||
|
||||
# Return updated CGAL buffer
|
||||
|
|
@ -803,8 +915,12 @@ sub merge_manuals
|
|||
# - buffer containing a doxygen-generated latex file reformated for CGAL
|
||||
my $doxy_buf = shift;
|
||||
|
||||
# Uncomment the next lines to test that obsolete sections are properly *created*
|
||||
# $cgal_buf =~ s/$warning\s%START-AUTO\(\\ccInclude\)\s*(\\ccInclude\{.*?\}\s)\s*%END-AUTO\(\\ccInclude\)\s*/$1/smg;
|
||||
# $cgal_buf =~ s/$warning\s%START-AUTO\(.*?\).*?%END-AUTO\(.*?\)\s*//smg;
|
||||
|
||||
# Extract from $cgal_buf the part about $item_to_document
|
||||
if ($cgal_buf =~ s/(.*)(^\s*\\begin\{ccRef.*?\s*\{$item_to_document[\s<\}].*?\\end\{ccRef.*?\})(.*)//sm)
|
||||
if ($cgal_buf =~ s/(.*)(^\s*\\begin\{ccRef.*?\s*\{$item_to_document[\s<\}].*?\\end\{ccRef.*?\}\s*)(.*)//sm)
|
||||
{
|
||||
my $start = $1;
|
||||
my $part_to_document = $2;
|
||||
|
|
@ -814,6 +930,9 @@ sub merge_manuals
|
|||
# before inserting the generated documentation.
|
||||
$part_to_document = remove_cc_ref_wizard_placeholders($part_to_document);
|
||||
|
||||
# Security: empty all %START-AUTO..%END-AUTO sections
|
||||
$part_to_document =~ s/($warning*\s*%START-AUTO\(.*?\)).*?(%END-AUTO\(.*?\))/$1\n$2/smg;
|
||||
|
||||
# Get list of sections present in either file
|
||||
my %actual_section_titles;
|
||||
my $all_titles_pattern = get_any_section_title_pattern();
|
||||
|
|
@ -847,6 +966,7 @@ copy_doxygen_latex_doc extracts a documentation from a doxygen-generated latex f
|
|||
Usage:
|
||||
copy_doxygen_latex_doc [options] item_to_document doxygen_generated_documentation.tex template_manual.tex
|
||||
-h, --help Print this help
|
||||
-v, --verbose Verbose mode
|
||||
-d, --debug Debug mode
|
||||
|
||||
See generate_reference_manual usage for details.
|
||||
|
|
@ -864,7 +984,6 @@ exit;
|
|||
my $item_to_document = undef; # Concept/struct/class/... to document
|
||||
my $doxygen_generated_file = undef; # Input file
|
||||
my $cgal_manual_file = undef; # Output file
|
||||
my $debug = 0; # Debug mode?
|
||||
|
||||
# Decode parameters
|
||||
if ($#ARGV == -1) { # If no parameter
|
||||
|
|
@ -877,6 +996,8 @@ foreach my $arg_num (0 .. $#ARGV)
|
|||
usage();
|
||||
} elsif ($arg =~ /^(-d|--debug)$/) {
|
||||
$debug = 1;
|
||||
} elsif ($arg =~ /^(-v|--verbose)$/) {
|
||||
$verbose = 1;
|
||||
} elsif ($arg =~ /^-/) { # If unknown option
|
||||
usage();
|
||||
} else { # Item to document or input file or output file
|
||||
|
|
@ -905,8 +1026,8 @@ close(DOXYGEN_DOC)
|
|||
my $formated_doxygen_buffer;
|
||||
if (($doxygen_generated_file =~ /.*\/class/) or ($doxygen_generated_file =~ /.*\/struct/))
|
||||
{
|
||||
$formated_doxygen_buffer = format_doxygen_class_struct_doc($item_to_document,
|
||||
$doxygen_generated_buffer);
|
||||
$formated_doxygen_buffer = format_doxygen_class_doc($item_to_document,
|
||||
$doxygen_generated_buffer);
|
||||
} else {
|
||||
$formated_doxygen_buffer = format_doxygen_function_doc($item_to_document,
|
||||
$doxygen_generated_buffer);
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ usage ()
|
|||
# set -x
|
||||
|
||||
# Version
|
||||
echo "generate_reference_manual version 1.0.1."
|
||||
echo "generate_reference_manual version 1.0.2."
|
||||
|
||||
# Global variables
|
||||
PACKAGE_ROOT_FOLDER="" # Package's root folder
|
||||
|
|
@ -38,6 +38,7 @@ INCLUDE_PATH="" # Path to CGAL include folder
|
|||
PACKAGE="" # Package name (without path)
|
||||
DOXYFILE="" # doxygen configuration file
|
||||
DEBUG=0 # Debug mode?
|
||||
VERBOSE=0 # Verbose mode?
|
||||
|
||||
# Decode parameters
|
||||
while [ "${1}" ]
|
||||
|
|
@ -52,6 +53,10 @@ do
|
|||
DEBUG=1
|
||||
COPY_DOXYGEN_LATEX_DOC_ARGS="${COPY_DOXYGEN_LATEX_DOC_ARGS} ${1}"
|
||||
;;
|
||||
-v|--verbose) # If --verbose
|
||||
VERBOSE=1
|
||||
COPY_DOXYGEN_LATEX_DOC_ARGS="${COPY_DOXYGEN_LATEX_DOC_ARGS} ${1}"
|
||||
;;
|
||||
-I|--include) # If -I
|
||||
shift
|
||||
if [ ! "${1}" ]; then # If no argument after -I
|
||||
|
|
@ -113,9 +118,19 @@ mkdir doc_doxygen
|
|||
# Run doxygen. m4 is used to search and replace in template Doxyfile.
|
||||
echo ""
|
||||
echo "Run doxygen..."
|
||||
m4 -DCGAL_PACKAGE="${PACKAGE}" -DCGAL_INCLUDE_PATH="${INCLUDE_PATH}" "${DOXYFILE}" | \
|
||||
doxygen - 2>&1 | \
|
||||
egrep -v 'BoundingBox not found|are not documented|^ parameter'
|
||||
if [[ $VERBOSE == 0 ]]; then
|
||||
WARN_IF_DOC_ERROR="NO"
|
||||
else
|
||||
WARN_IF_DOC_ERROR="YES"
|
||||
fi
|
||||
m4 -DCGAL_PACKAGE="${PACKAGE}" \
|
||||
-DCGAL_WARN_IF_DOC_ERROR="${WARN_IF_DOC_ERROR}" \
|
||||
-DCGAL_INCLUDE_PATH="${INCLUDE_PATH}" \
|
||||
"${DOXYFILE}" > generate_reference_manual_Doxyfile
|
||||
doxygen generate_reference_manual_Doxyfile 2>&1 | egrep -v 'BoundingBox not found'
|
||||
if [[ $DEBUG == 0 ]]; then
|
||||
rm -f generate_reference_manual_Doxyfile
|
||||
fi
|
||||
|
||||
# Update the Reference Manual
|
||||
echo ""
|
||||
|
|
|
|||
|
|
@ -38,6 +38,7 @@ ALIASES = "subheading=@name Subheading" \
|
|||
heading=Heading
|
||||
OPTIMIZE_OUTPUT_FOR_C = NO
|
||||
OPTIMIZE_OUTPUT_JAVA = NO
|
||||
BUILTIN_STL_SUPPORT = YES
|
||||
SUBGROUPING = YES
|
||||
#---------------------------------------------------------------------------
|
||||
# Build related configuration options
|
||||
|
|
@ -72,9 +73,9 @@ FILE_VERSION_FILTER =
|
|||
# configuration options related to warning and progress messages
|
||||
#---------------------------------------------------------------------------
|
||||
QUIET = YES
|
||||
WARNINGS = YES
|
||||
WARNINGS = NO
|
||||
WARN_IF_UNDOCUMENTED = NO
|
||||
WARN_IF_DOC_ERROR = YES
|
||||
WARN_IF_DOC_ERROR = CGAL_WARN_IF_DOC_ERROR
|
||||
WARN_NO_PARAMDOC = NO
|
||||
WARN_FORMAT = "$file:$line: $text"
|
||||
WARN_LOGFILE =
|
||||
|
|
@ -97,13 +98,8 @@ EXCLUDE = ./test \
|
|||
./demo \
|
||||
./examples
|
||||
EXCLUDE_SYMLINKS = NO
|
||||
EXCLUDE_PATTERNS = */internal/* \
|
||||
*/CGALi/*
|
||||
EXCLUDE_SYMBOLS = CGAL::CGALi \
|
||||
CGAL::internal \
|
||||
CGAL::*::internal \
|
||||
CGAL::*::CGALi \
|
||||
__pad*__
|
||||
EXCLUDE_PATTERNS =
|
||||
EXCLUDE_SYMBOLS = __pad*__
|
||||
EXAMPLE_PATH =
|
||||
EXAMPLE_PATTERNS = *
|
||||
EXAMPLE_RECURSIVE = NO
|
||||
|
|
@ -159,7 +155,7 @@ PAPER_TYPE = a4wide
|
|||
EXTRA_PACKAGES =
|
||||
LATEX_HEADER =
|
||||
PDF_HYPERLINKS = NO
|
||||
USE_PDFLATEX = YES
|
||||
USE_PDFLATEX = NO
|
||||
LATEX_BATCHMODE = YES
|
||||
LATEX_HIDE_INDICES = YES
|
||||
#---------------------------------------------------------------------------
|
||||
|
|
@ -234,7 +230,7 @@ PERL_PATH = /usr/bin/perl
|
|||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the dot tool
|
||||
#---------------------------------------------------------------------------
|
||||
CLASS_DIAGRAMS = YES
|
||||
CLASS_DIAGRAMS = NO
|
||||
HIDE_UNDOC_RELATIONS = NO
|
||||
HAVE_DOT = NO
|
||||
CLASS_GRAPH = YES
|
||||
|
|
|
|||
|
|
@ -17,6 +17,8 @@ Usage:
|
|||
|
||||
generate_reference_manual [options] -I /path/to/CGAL/include /path/to/package
|
||||
-h, --help Print this help
|
||||
-v, --verbose Verbose mode
|
||||
-d, --debug Debug mode
|
||||
|
||||
The typical usage is:
|
||||
1) Comment your code using Doxygen conventions (see below).
|
||||
|
|
|
|||
Loading…
Reference in New Issue