Skip to content

GitLab

L
lalsuite
Commit f7eb9a04 authored by Karl Wette's avatar Karl Wette
Browse files
Options

Doxygen: build separate documentation for each LAL library 

- Doxygen build system moved to per-library doxygen/ directories.
- Minimum required Doxygen version set to 1.8.1.2 (Wheezy).
- Doxygen layout from v1.8.1.2, configuration from 1.8.5 (SL7).
- Support local MathJax installation with --with-mathjax option.
- Drop support for unwieldy PDF documentation.
- Doxygenise last vestiges of LaTeX documentation in LALApps.
- Unused documentation files moved to per-library attic/ directories.
- Fix Doxygen warnings, and enforce Doxygen builds without warnings.
Original: 7bffd0bf027b06a4b0cc044748a2ae3729739b77
parent 8f035ab4
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 14069 additions and 68112 deletions

Too many changes to show.

To preserve performance only 1000 of 1000+ files are displayed.
Plain diff Email patch
doxygen/LaTeX2doxygen.pl → attic/lal/LaTeX2doxygen.pl
View file @ f7eb9a04
......@@ -21,35 +21,55 @@ for my $texfname (@ARGV) {
# check that Doxygen file does not exist
die "File '$doxyfname' already exists!" if (-f $doxyfname);
# open files
# open input file
open TEX, "<$texfname" or die "Could not open '$texfname'!: $!";
open DOXY, ">$doxyfname" or die "Could not open '$doxyfname'!: $!";
# copy header of LaTeX file verbatim to doxygen file
# slurp the header and contents of the LaTeX document
my $header = "";
while (<TEX>) {
last if $_ =~ /^ *\\begin{document}/;
print DOXY "// $_";
$header .= $_;
}
# slurp the contents of the LaTeX document
my $latex = "";
my $contents = "";
while (<TEX>) {
last if $_ =~ /^ *\\end{document}/;
$latex .= $_;
$contents .= $_;
}
close TEX;
# if contents is empty, use header (LaTeX document is a fragment)
if ($contents eq "") {
$contents = $header;
$header = "";
}
# convert to Doxygen
my $doxygen = toDoxygen($latex);
my $doxygen = toDoxygen($contents);
# write to output file
print DOXY "/**\n\\page pagename\n\n$doxygen\n*/\n";
open DOXY, ">$doxyfname" or die "Could not open '$doxyfname'!: $!";
if ($header ne "") {
print DOXY "/*\n";
for my $line (split /\n/, $header) {
$line = " * $line";
$line =~ s/\s*$//;
print DOXY "$line\n";
}
print DOXY " */\n\n";
}
print DOXY "/**\n * \\page $texfname\n";
for my $line (split /\n/, $doxygen) {
$line = " * $line";
$line =~ s/\s*$//;
print DOXY "$line\n";
}
print DOXY " */\n";
close DOXY;
}
exit(0);
# convert LaTeX to doxygen documentation
sub toDoxygen {
......@@ -58,6 +78,9 @@ sub toDoxygen {
# regex for non-line-breaking whitespace
my $n = "[^\\S\n]";
# get rid of LaTeX comments
$text =~ s!([^%]?)%.*$!\1!mg;
# get rid of LSD LaTeX and Verbatim tags
$text =~ s!</?lal(?:LaTeX|Verbatim)[^>]*?>!!sg;
......@@ -109,19 +132,19 @@ sub toDoxygen {
# two arguments
$text =~ s!\\(?:
providecommand
)$bbr$bbr!!mgx;
)\*?$bbr$bbr!!mgx;
# two arguments, first optional
#$text =~ s!\\(?:
#idx
#)$bbk?$bbr!!mgx;
$text =~ s!\\(?:
idx
)\*?$bbk?$bbr!!mgx;
# one argument
$text =~ s!\\(?:
vfill|vspace
)$bbr!!mgx;
vfill|vspace|hspace
)\*?$bbr!!mgx;
# no arguments
$text =~ s!\\(?:
footnotesize|medskip|newpage|noindent
)$n*!!mgx;
footnotesize|medskip|newpage|noindent|newline|leavevmode
)\*?$n*!!mgx;
# remove these LaTeX commands but leave argument:
# one argument
......@@ -134,6 +157,9 @@ sub toDoxygen {
figure|table
)}!(MANUAL INTERVENTION $1 $2)!mgpx;
# convert verbatim commands
$text =~ s!\\verb(.)(.+?)\1!\\texttt{$2}!mg;
# convert formulae
$text =~ s!\$\$(.+?)\$\$!\\f[$1\\f]!sg;
$text =~ s!\$(.+?)\$!\\f\$$1\\f\$!sg;
......@@ -156,33 +182,43 @@ sub toDoxygen {
# convert descriptions
sub desc {
my ($text) = @_;
$text =~ s{\\begin$n*{description}(?<LIST>.*?)\\end$n*{description}}{
$_ = $+{LIST};
$text =~ s{DOXY(\((?:[^()]++|(?1))*\))}{
$_ = $1;
s/^\(*//;
s/\)*$//;
$_ = desc($_);
while (/\\item\[/) {
s!\\item$wbbk(?<TEXT>.*?)(?<END>\n*\\item\[|\Z)!<dt>$1</dt><dd>$+{TEXT}</dd>$+{END}!sx;
}
'<dl>' . desc($_) . '</dl>'
'<dl>' . $_ . '</dl>'
}sge;
return $text;
}
$text =~ s!\\begin$n*{(description|entry)}!DOXY(!mg;
$text =~ s!\\end$n*{(description|entry)}!)!mg;
$text = desc($text);
# convert numbered and unnumbered lists
sub list {
my ($text) = @_;
$text =~ s{\\begin$n*{(?<ENV>enumerate|itemize)}(?<LIST>.*?)\\end$n*{\k<ENV>}}{
my $e = $+{ENV};
$_ = $+{LIST};
$e =~ s!enumerate!ol!;
$e =~ s!itemize!ul!;
my ($text, $e) = @_;
$text =~ s{DOXY(\((?:[^()]++|(?1))*\))}{
$_ = $1;
s/^\(*//;
s/\)*$//;
$_ = list($_, $e);
while (/\\item/) {
s!\\item(?<TEXT>.*?)(?<END>\n*\\item|\Z)!<li>$+{TEXT}</li>$+{END}!sx;
}
"<$e>" . list($_) . "</$e>"
"<$e>" . $_ . "</$e>"
}sge;
return $text;
}
$text = list($text);
$text =~ s!\\begin{(enumerate)}!DOXY(!g;
$text =~ s!\\end{(enumerate)}!)!g;
$text = list($text, "ol");
$text =~ s!\\begin{(itemize)}!DOXY(!g;
$text =~ s!\\end{(itemize)}!)!g;
$text = list($text, "ul");
# convert tables
$text =~ s{\\begin$n*{tabular}$bbr?(?<TABLE>.*?)\\end$n*{tabular}}{
......@@ -203,9 +239,9 @@ sub toDoxygen {
# replace formatting commands
$text =~ s!\{\\(tt|it|rm|sc|sl|bf|sf)$n+!\\text$1\{!sg;
$text =~ s!\\verb(.)(.+?)\1!\\texttt{$2}!mg;
$text =~ s!\\emph!\\textit!sg;
$text =~ s!\\text(?:sc|sl|bf|sf)!\\texttt!sg;
$text =~ s!\\f\$\\text(tt|it)\s*$bbr\\f\$!\\text\1\2!sg;
$text =~ s{\\text(tt|it)\s*$wbbr}{
my $e = $1;
$_ = $2;
......@@ -214,6 +250,9 @@ sub toDoxygen {
($e eq 'tt' ? "\\c $_" : "\\e $_" ) :
($e eq 'tt' ? "<tt>$_</tt>" : "<em>$_</em>" )
}sge;
$text =~ s!\\prog$wbbr!<tt>\1</tt>!sg;
$text =~ s!\\option$wbbr!<tt>\1</tt>!sg;
$text =~ s!\\parm$wbbr!<i>\1</i>!sg;
# special treatment of 'Synopsis/Prototypes/Description/Uses/Algorithm/Notes' sections: turn into 'heading'
$text =~ s!\\(?:sub)*section\*?{(Synopsis|Description|Prototypes|Algorithm|Notes|Uses|Usage)}!\n### $1 ###\n!g;
......@@ -245,9 +284,9 @@ sub toDoxygen {
## intelligent guess about equation references
$text =~ s!([Ee]qs?|[Ee]quations?)[.\\~]*\\TODOref!\1.\\eqref!mg;
## intelligent guess about figure references
$text =~ s!([Ff]igs?|[Ff]igures?)[.\\~]*\\TODOref!\1.\\figref!mg;
$text =~ s!([Ff]igs?|[Ff]igures?)[.\\~]*\\TODOref$wbbr!\\ref \2 "this figure"!mg;
## intelligent guess about table references
$text =~ s!([Tt]ab?|[Tt]ables?)[.\\~]*\\TODOref!\1.\\tableref!mg;
$text =~ s!([Tt]ab?|[Tt]ables?)[.\\~]*\\TODOref$wbbr!\\ref \2 "this table"!mg;
# replace probable filenames with references
$text =~ s!<tt>(.*?\.[ch])</tt>!\\ref \1!mg;
......@@ -301,6 +340,9 @@ sub toDoxygen {
# remove trailing whitespace
$text =~ s!$n*$!!mg;