[Olena] oln doc.2: Add example extraction.

Still numerous FIXMES. Index: ChangeLog from Astrid Wang &lt;astrid(a)lrde.epita.fr&gt; * configure.ac: Check for doxygen. Index: doc/ChangeLog from Astrid Wang &lt;astrid(a)lrde.epita.fr&gt; * ref/exdoc.pl, * ref/exdoc.config, * ref/exdoc.mk: New. * ref/doxygen.config.in: New. Index: configure.ac --- configure.ac Mon, 15 Sep 2003 17:23:46 +0200 burrus_n (oln/3_configure. 1.47.1.1.1.1.1.4.1.15.1.10 640) +++ configure.ac Mon, 29 Sep 2003 16:53:58 +0200 astrid (oln/3_configure. 1.47.1.1.1.1.1.4.1.15.1.10 640) @@ -231,6 +231,16 @@ ### Stuff pertaining to the documentation ### +### The reference manual uses Doxygen +### FIXME: could be much better. + +AC_CHECK_PROG([DOXYGEN], [doxygen], [doxygen]) +## if test -z "$DOXYGEN"; then +## AC_MSG_WARN([`doxygen' not found -- `doxygen' must be installed to generate the documentation]) +AC_CONFIG_FILES([doc/ref/doxygen.config + doc/ref/configfile.in]) +## fi + ### The documentation tree is both a component... OLN_COMPONENT([doc], Index: doc/ref/exdoc.pl --- doc/ref/exdoc.pl Mon, 29 Sep 2003 21:48:17 +0200 astrid () +++ doc/ref/exdoc.pl Mon, 29 Sep 2003 19:30:04 +0200 astrid (oln/v/26_exdoc.pl 644) @@ -0,0 +1,334 @@ +#! /usr/bin/perl -w +# Extract all examples from the manual source. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA +# 02111-1307 USA + +use strict; +use IO::File; +use Text::Wrap; +use File::Basename; +use Getopt::Long qw(GetOptions); +use Pod::Usage qw(pod2usage); + +my $me = basename ($0); + +# Array of hash tables holding the information from the config file +my @config; + +# &parse_config ($FILE) +# --------------------- +# Parse the config file. + +sub parse_config($) +{ + open (CONFIGFILE, $_[0]) or die "$me: Can't open $_[0]: $!"; + + # Number of entries + my $entries = -1; + + while (<CONFIGFILE>) + { + if (/\[ENTRY\]/) { $entries++ } + else + { + SWITCH: + { + last SWITCH if (/^\s*(\#+.*)*$/); + $config[$entries]{"command_prefix"} = $1 and last SWITCH if (/\s*COMMAND_PREFIX\s*=\s*([^\#]*[^\s])\s*(\#+.*)*$/); + $config[$entries]{"tag_open"} = $1 and last SWITCH if (/\s*TAG_OPEN\s*=\s*([^\#]*[^\s])\s*(\#+.*)*$/); + $config[$entries]{"tag_close"} = $1 and last SWITCH if (/\s*TAG_CLOSE\s*=\s*([^\#]*[^\s])\s*(\#+.*)*$/); + $config[$entries]{"captions"} = $1 and last SWITCH if (/\s*CAPTIONS\s*=\s*([^\#]*[^\s])\s*(\#+.*)*$/); + $config[$entries]{"out"} = $1 and last SWITCH if (/\s*OUT\s*=\s*([^\#]*[^\s])\s*(\#+.*)*$/); + $config[$entries]{"$1"} = $2 and last SWITCH if (/\s*ALIAS\s*([^\s]*)\s*=\s*([^\#]*[^\s])\s*(\#+.*)*$/); + + die "$0: Error: Unmatching entry: $_"; + } + } + } + close CONFIGFILE; + die "$me: Invalid config file `$_[0]'" if ($entries == -1); # FIXME: not strict enough. + + for (my $i = 0; $i < @config; $i++) + { + $config[$i]{"tag_open"} = $config[$i]{"command_prefix"} . $config[$i]{"tag_open"}; + $config[$i]{"tag_close"} = $config[$i]{"command_prefix"} . $config[$i]{"tag_close"}; + } + + for my $i ( 0 .. $#config ) + { + for my $role ( keys %{ $config[$i] } ) + { + print "elt $i $role is $config[$i]{$role}\n"; + } + } +} + +# Dependencies of KEY as a simple string. +my %dependency; +# Set to 1 if KEY is not to keep as a dependency. +my %ignore; + +# &DEPEND ($TARGET, @DEPENDENCY) +# ------------------------------ +sub depend ($@) +{ + my ($target, @dependency) = @_; + @dependency = (grep { !exists $ignore{$_} } @dependency); + push @{$dependency{$target}}, @dependency + if @dependency; +} + +# List of files already opened. $FILE{FILE} is where FILE was +# first defined. +my %file; + +# &register ($FILE) +# ----------------- +# Make sure the $FILE name is used only once (as input or output), to +# avoid clashes. +sub register ($) +{ + my ($file) = @_; + die "$me: $.: $file already used in $file{$file}" + if $file{$file}; + $file{$file} = "$ARGV:$."; +} + + +# example_to_verbatim(CODE) +# ------------------------- +# Strip Texinfo markup. +sub example_to_verbatim ($) +{ + my ($contents) = @_; + + $contents =~ s/^\@(c |comment|dots|end (ignore|group)|ignore|group).*$//gm; + # Remove the Texinfo tags. + $contents =~ s/^\@(error|result)\{\}//gsm; + $contents =~ s/\@([{@}])/$1/gsm; + $contents =~ s/^\(a)comment.*//gm; + + return $contents; +} + + +# &REPORT (@MESSAGE) +# ------------------ +# Report some @MESSAGE to the user. +sub message (@) +{ + print STDERR "$me: $ARGV:$.: ", @_, "\n"; +} + + +# &STORE ($FILE, $CONTENTS) +# ------------------------- +# Save the $CONTENTS in the $FILE, unless it already contains $WHAT. +sub store ($$) +{ + my ($file, $contents) = @_; + if (-f $file) + { + local $/; # Turn on slurp-mode. + my $f = new IO::File "< $file" + or die "$me: cannot open $file for reading: $!\n"; + my $old_contents = $f->getline; + if ($old_contents eq $contents) + { + message "$file: unchanged"; + return ; + } + } + my $out = new IO::File (">$file") + or die "$me: cannot create $file: $!\n"; + print $out $contents; + message "$file: new"; +} + + +# The directory where to store the extracted results. +# Parse our options, trying to retain backwards compatibility with pod2man but +# allowing short forms as well. --lax is currently ignored. +my %option; +Getopt::Long::config ('bundling_override'); +GetOptions (\%option, + 'configfile|c=s', + 'srcdir|s=s', + 'output-dir|O=s', + 'help|h') or exit 1; +pod2usage (0) if $option{help}; + +my $odir = $option{"output-dir"} || "extract"; +if (! -d $odir) +{ + mkdir $odir or die "$me: cannot create $odir: $!\n"; +} +my $makefile = new IO::File "> $odir/makefile" + or die "$me: cannot create $odir/makefile: $!\n"; +print $makefile "include $option{srcdir}/../exdoc.mk\n"; +print $makefile ".PHONY: all dvi eps html pdf txt\n"; +# print $makefile "all: txt\n"; +my $example; +my $last_file; + +parse_config ($option{"configfile"}); + +while (<>) +{ + ## @dotcaption{ord, file} + ## ====================== + if (/^\(a)dotcaption{([-.\w]+),\s*([^\}]+)}/) + { + my $ord = $1; + my $file = $2; + register $ord; + register $file; + store "$odir/$ord.file", "$file.dot"; + depend "html", "$ord.jpg"; + depend "pdf", "$ord.pdf"; + depend "txt", "$ord.txt"; + depend "dvi", "$ord.eps"; + } + + ## @example/@end example + ## ===================== + ## Memoize the contents. + else + { + my $i = 0; + + print $_; + for ($i = 0; ($i < @config) + && not ((/^\s*$config[$i]{"tag_open"}\s*$/ .. /^\s*$config[$i]{"tag_close"}\s*$/)); $i++) + { + } + + if ($i < @config) + { + print "PASSEJAMAISLA\n"; + if (/^\s*$config[$i]{"tag_open"}\s*$/) + { + # Nothing. + undef $example; + } + elsif (/^\s*$config[$i]{"tag_close"}\s*$/) + { + if (defined $last_file) + { + # Output as a verbatim file. + store "$odir/$last_file", example_to_verbatim ($example); + undef $last_file; + } + } + ## @filecaption{ord, filename} + ## Outputting the previous @example as a file. + elsif (/^\s*$config[$i]{"command_prefix"}filecaption{([-.\w]+),\s*([^\}]+)}/) + { + my ($ord, $file) = ($1, "$2"); + register $file; + $last_file = $file; + } + else + { + $example = $example . $_; + } + } + + + ## @c extdoc-ignore: file + ## ## A file that we should not depend upon (e.g., it does not exist). + elsif (/^\@c extdoc-ignore: (.*)$/) + { + message "ignoring $1"; + $ignore{$1} = 1; + } + + + ## @havmcaption{ord, args} + ## @mipsycaption{ord, args} + ## @tccaption{ord, args} + ## @sedcaption{ord, args} + ## ## Running `havm', `mipsy', `tc', or `sed' on the ARGS. + else + { + my $i = 0; + for ($i = 0; ($i < @config) && +# not (/^\s*$config[$i]{"command_prefix"}($config[$i]{"captions"})caption{([-.\w]+),\s*([^\}]+)}/); $i++) + not (/^\s*\\cxxcaption{([-.\w]+),\s*([^\}]+)}/); $i++) + {} +# FIXME: What's wrong with these regexp? +# if ($i < @config && /^\s*$config[$i]{"command_prefix"}($config[$i]{"captions"})caption{([-.\w]+),\s*([^\}]+)}/) + if ($i < @config && /^\s*\\(cxx)caption{([-.\w]+),\s*([^\}]+)}/) + { + my $prog; + + + if (defined $config[$i]{$1}) + { + $prog = $config[$i]{$1}; + + print $prog; + } + else + { + $prog = $1; + } + my $ord = $2; + my $args = $3; + my $out = "$ord.$config[$i]{out}"; + register $out; + store "$odir/$ord.cmd", "$prog $args"; + depend "pdf", $out; + depend "html", $out; + depend "txt", $out; + depend "dvi", $out; + + # Dependencies: args except options and output redirections. + depend $out, grep { !/^[->]/ } split (' ', $args); + } + } + } +} + + +for my $target (sort keys %dependency) +{ + ## print $makefile ".PHONY: $target\n"; + # Using "map" only to get some functional composition of s///, + # but there is a single string here. + print $makefile (map ({ s/$(?!\z)/ \\/gm; $_ } + wrap ("$target: ", + " " x length ("$target: "), + @{$dependency{$target}})), + "\n"); +} + +### Setup "GNU" style for perl-mode and cperl-mode. +## Local Variables: +## perl-indent-level: 2 +## perl-continued-statement-offset: 2 +## perl-continued-brace-offset: 0 +## perl-brace-offset: 0 +## perl-brace-imaginary-offset: 0 +## perl-label-offset: -2 +## cperl-indent-level: 2 +## cperl-brace-offset: 0 +## cperl-continued-brace-offset: 0 +## cperl-label-offset: -2 +## cperl-extra-newline-before-brace: t +## cperl-merge-trailing-else: nil +## cperl-continued-statement-offset: 2 +## End: Index: doc/ref/exdoc.mk --- doc/ref/exdoc.mk Mon, 29 Sep 2003 21:48:17 +0200 astrid () +++ doc/ref/exdoc.mk Mon, 29 Sep 2003 16:28:00 +0200 astrid (oln/v/27_exdoc.mk 644) @@ -0,0 +1,56 @@ +%.dot: %.file + cp $$(cat $<) $@ + +%.texi: %.cmd +## Eval the cmd to preserve embedded redirections. + eval $$(cat $<) >$*.out 2>$*.err; \ + echo $$? >$*.sta + rm -f $@ + echo '@example' >> $@ + echo "$$ @kbd{$$(cat $<)}" >> $@ + if test -s $*.err; then \ + sed -n -e 's/\([{@}]\)/@\1/g' \ + -e '/./s/.*/@error{}&/p' $*.err >> $@;\ + fi + if test -s $*.out; then \ + expand $*.out | \ + sed -e 's/\([{@}]\)/@\1/g' \ + -e "s/é/@'e/g" \ + -e 's/è/@`e/g' \ + -e 's/ê/@^e/g' \ + -e 's/ë/@"e/g' \ + -e 's/î/@^i/g' \ + -e 's/ï/@"i/g' \ + -e 's/ô/@^o/g' \ + >>$@;\ + fi +## Display the exit status only if not 0, as it confuses the +## students to see so many `=> 0'. But, if there is nothing output +## at all, it is even more confusing, so output `=> 0' only when +## needed. + if test ! -e $@ \ + || test $$(cat $*.sta) -ne 0; then \ + sed 's/.*/@result{}&/' $*.sta >> $@; \ + fi + echo "@strong{Example $*}: @kbd{$$(cat $<)}" >> $@ + echo '@end example' >> $@ + +## Once for PDF. +## ratio = 2 makes it wider. +## size (in Inches) makes it fit into A4. +%.eps: %.dot + dot -Gratio=2 -Gsize=8,8 -Tps2 $*.dot -o $*.ps + ps2epsi $*.ps $*.eps + +%.pdf: %.eps + epstopdf $*.eps -o $*.pdf + +## Another for HTML (JPG), using natural size. +%.jpg: %.dot + dot -Tps2 $*.dot -o $*.j.ps + ps2epsi $*.j.ps $*.j.eps + convert $*.j.eps $*.jpg + +## And the text... +%.txt: %.dot + cp $< $@ Index: doc/ref/exdoc.config --- doc/ref/exdoc.config Mon, 29 Sep 2003 21:48:17 +0200 astrid () +++ doc/ref/exdoc.config Mon, 29 Sep 2003 19:34:41 +0200 astrid (oln/v/28_exdoc.conf 644) @@ -0,0 +1,7 @@ +[ENTRY] + COMMAND_PREFIX = \ # In Doxygen, commands begin with a `\' + TAG_OPEN = code + TAG_CLOSE = endcode + CAPTIONS = cxx # We want to run cxx on the extracted files (see line below) + ALIAS cxx = g++ # Here, cxx means g++ but you can choose other compilers + OUT = texi # FIXME: should be obsolete Index: doc/ref/doxygen.config.in --- doc/ref/doxygen.config.in Mon, 29 Sep 2003 21:48:17 +0200 astrid () +++ doc/ref/doxygen.config.in Fri, 26 Sep 2003 13:02:40 +0200 astrid (oln/v/29_doxygen.co 644) @@ -0,0 +1,209 @@ +# Doxyfile 1.3.2 + +#--------------------------------------------------------------------------- +# General configuration options +#--------------------------------------------------------------------------- +PROJECT_NAME = @PACKAGE_NAME@ +PROJECT_NUMBER = @PACKAGE_VERSION@ +OUTPUT_DIRECTORY = . +OUTPUT_LANGUAGE = English +USE_WINDOWS_ENCODING = NO +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = YES +EXTRACT_LOCAL_CLASSES = NO +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = NO +STRIP_FROM_PATH = +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = NO +SHORT_NAMES = NO +HIDE_SCOPE_NAMES = NO +SHOW_INCLUDE_FILES = YES +JAVADOC_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +DETAILS_AT_TOP = NO +INHERIT_DOCS = YES +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +DISTRIBUTE_GROUP_DOC = NO +TAB_SIZE = 8 +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ALIASES = pouetcaption= +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_JAVA = NO +SHOW_USED_FILES = YES +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = @top_srcdir@/olena/oln/ +FILE_PATTERNS = *.hh \ + *.hxx \ + *.cc +RECURSIVE = YES +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_SOURCE_FILES = NO +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = NO +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +VERBATIM_HEADERS = YES +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +ALPHABETICAL_INDEX = NO +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_ALIGN_MEMBERS = YES +GENERATE_HTMLHELP = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +BINARY_TOC = NO +TOC_EXPAND = NO +DISABLE_INDEX = NO +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = NO +TREEVIEW_WIDTH = 250 +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = YES +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4wide +EXTRA_PACKAGES = +LATEX_HEADER = +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = NO +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = NO +XML_OUTPUT = xml +XML_SCHEMA = +XML_DTD = +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- +GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration::addtions related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +PERL_PATH = /usr/bin/perl +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = YES +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = YES +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +UML_LOOK = YES +TEMPLATE_RELATIONS = YES +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DOT_IMAGE_FORMAT = png +DOT_PATH = +DOTFILE_DIRS = +MAX_DOT_GRAPH_WIDTH = 1024 +MAX_DOT_GRAPH_HEIGHT = 1024 +MAX_DOT_GRAPH_DEPTH = 0 +GENERATE_LEGEND = YES +DOT_CLEANUP = YES +#--------------------------------------------------------------------------- +# Configuration::addtions related to the search engine +#--------------------------------------------------------------------------- +SEARCHENGINE = NO +CGI_NAME = search.cgi +CGI_URL = +DOC_URL = +DOC_ABSPATH = +BIN_ABSPATH = /usr/local/bin/ +EXT_DOC_PATHS = -- astrid