% ___________________________________________________________________________
% |#########################################################################|
% |                                                                         |
% | The Manual for the C++ Reference Manual Style   cc_manual.tex           |
% | -------------------------------------------------------------           |
% |                                                                         |
% | 02.09.1996   Lutz Kettner   kettner@acm.org                             |
% | Zurich, Switzerland                                                     |
% | $Revision$                                                       |
% | $Date$                                            |
% |_________________________________________________________________________|
% |#########################################################################|

% The style is compatible with LaTeX2e:
\documentclass[12pt]{article}
\usepackage{latexsym}
\usepackage{amssymb}
\usepackage{path}
\usepackage{epsfig}
\usepackage{cc_manual}
\usepackage{latex_converter}
\usepackage{makeidx}
% \makeindex

%\pagestyle{empty}
\textwidth 15.4cm 
\textheight 24 cm
\topmargin -14mm       
\evensidemargin 3mm 
\oddsidemargin 3mm


\parindent0em
\setlength{\parskip}{1.4ex}

\sloppy

{
  \begingroup
    \catcode`\|=0
    \catcode`\[=1
    \catcode`\]=2
    \catcode`\{=12
    \catcode`\}=12    
    \catcode`\\=12    
    |gdef|Open[[|tt {]]
    |gdef|Close[[|tt }]]
    |gdef|Backslash[[|tt \]]
  |endgroup
}

\newcommand{\Mindex}[1]{\index{#1@\protect\Backslash{\tt #1}}}
\newcommand{\TTindex}[1]{\index{#1@{\tt #1}}}
\newcommand{\Dindex}[1]{#1\index{#1}}

\def\ind{\hspace*{7mm}}

% ----------------------------------------------------------------------
\title {{\tt cc\_extract} and {\tt cc\_check}\\[2mm]
        Extracting Sources from \CC\ Reference Manuals}

\author{Lutz Kettner}

\date{\ccRevision. \ccDate}

\begin{document}

\maketitle

\tableofcontents
\thispagestyle{empty}
\clearpage
\thispagestyle{empty}
~\vfill

\input{disclaimer}

\cleardoublepage\setcounter{page}{1}

% ----------------------------------------------------------------------
\section{Introduction}

The tools for writing \CC\ reference manuals are arranged around a
\LaTeX\ style file called {\tt cc\_manual.sty}. The style provides
three groups of macros. The first group is a set of commonly used
abbreviations such as \verb+\R+ for \R. The second group helps to
structure the text with subtitles such as \verb+\ccDefinition+ or
\verb+\ccPrecond+.  The third group handles \CC\ declarations and
formats the declarations nicely. The \LaTeX\ to {\tt HTML}
converter~\cite{k-lhcll-99} fully supports the {\tt
  cc\_manual.sty}.\TTindex{cc\_manual.sty}\TTindex{HTML}

A set of \Dindex{tools} is dedicated to achieve \Dindex{consistency}
between the manual and the current implementation. A \Dindex{software
  engineering} process like the {\em \Dindex{waterfall model}\/} or
the {\em \Dindex{spiral model}\/} \cite{Fairley85} differentiates the
task of software development into design and implementation (among
other steps).  The result of the design phase is the specification,
here a \CC\ reference manual. The result of the implementation phase
is the source code and an additional implementation documentation (not
to be confused with the reference manual). \index{web tools} Web tools
\cite{Knuth84,Knuth94,Williams92} may be used to combine
implementation and its documentation.

The specification in the reference manual contains \CC\ declarations
that are repeated in the {\tt *.h} header files of the implementation.
The syntax in the {\tt *.tex} reference manual files uses \CC\ style
declarations to simplify the task of the manual authors (no additional
syntax) and the task for tools when processing the manual.  In
conformance with the development process the {\tt
  cc\_extract}\TTindex{cc\_extract} tool transforms the specification
to the declaration part of a {\tt *.h} header file. Neither a complete
{\tt *.h} header file is written in the manual nor a {\tt *.h} header
file is used for writing the manual.  A couple of declarations and
definitions have to be in an {\tt *.h} header file but must not be in
any specification (e.g. private class members or inline function
definitions). The second reason for this is more a matter of taste. It
is the idea of the web tools \cite{Knuth84} to write code within the
documentation instead of writing comments within code. Furthermore, if
the implementation is done with \Dindex{web tools}, the manual
specification would appear as a \CC\ comment within a {\tt *.h} header
file within a web file -- the second nesting level.

When the specification evolves as indicated by the \Dindex{software
  engineering} {\em cycle model}, the {\tt *.h} header files has to be
kept updated. An automatic {\em splicing mechanism\/} is possible, but
has not been developed so far. A {\em cut-and-paste\/} approach can be
used for the moment. Experience from practice indicates that the {\tt
  *.h} header files might get changed without updating the
specification in the manual (so not as clean as in the software
engineering {\em cycle model}).  Here, the {\tt
  cc\_check}\TTindex{cc\_check} tool can test whether all declarations
within a specification are currently contained within a {\tt *.h}
header file. Nonetheless, we believe in the benefits of keeping design
and implementation tasks separated and encourage this by keeping the
specification in its extra file and not mangled with the
implementation.\footnote{A side effect is that the file change date of
  the {\tt *.tex} file indicates changes in the specification, which
  is not true for the file change date of a {\tt *.h} header file.}

Both tools, {\tt cc\_extract} and {\tt cc\_check}, are documented in
this manual. The \LaTeX\ style file, {\tt cc\_manual.sty}, is
documented in~\cite{k-clswr-99}. The \LaTeX\ to HTML converter is
documented in~\cite{k-lhcll-99}.  An overview of the files involved
and the tools is given in Figure~\ref{ToolsOverviewFig}.

\def\figuretopindent{\vspace{2ex}}

\begin{figure}
    \psfig{file=tools_overview.ips,width=\textwidth}%
    \caption{The files and tools involved in the manual writing
      process.\index{files}\index{tools}}
    \label{ToolsOverviewFig}\figuretopindent
\end{figure}

The next section describes the {\tt cc\_extract} tool in detail.
Thereafter in Section~\ref{sectionChecker}, the {\tt cc\_check} tool
is explained.  The installation of these tools is not described in
this manual. Please refer to the {\tt README} and {\tt INSTALLATION}
files that are shipped with the distribution.

{\bf Note:} Both tools are in a less developed state than the \LaTeX\ 
style file or the \LaTeX\ to HTML converter.

% ----------------------------------------------------------------------
\section{Extracting Declarations from a Manual with {\tt cc\_extract}}
\label{sectionExtract}
\index{extract declarations}\index{declaration extraction}
\index{tools}
\TTindex{cc\_extract}

The {\tt cc\_extract} program reads a specification and writes all
declarations to the standard output. The output is in \CC\ format,
i.e., the declarations are copied literally and the documentation is
put in \CC\ comments. The documentation also is made a bit more
readable by translating several \LaTeX\ macros to ASCII text. The
synopsis for the program is:

\ind{\tt cc\_extract [<options>] [<infile> ...]}

Multiple input files are processed sequentially and the output is
concatenated. If no input file is given the program reads from the
standard input. Available options are:

\begin{tabular}{ll}
    {\tt -nomc}  & Suppress the output of main comments. \\
    {\tt -nosc}  & Suppress the output of subsidiary comments. \\
    {\tt -noc}   & Suppress the output of any comments (main and subsidiary).\\
    {\tt -trace} & Produce a debug trace from the {\tt bison} parser. \\
    {\tt -h, -help} & A short usage message and a summary of the options.
\end{tabular}

In principle, the main text of the specification is not converted to
\CC\ comments. Within class declarations, the main text is converted
to main comments that can be suppressed with {\tt -nomc}. The second
argument of declarations, which is formatted in the third column as
documentation, is converted to subsidiary comments that can be
suppressed with {\tt -nosc}. No comments at all are converted with the
option {\tt -noc}. The {\tt bison} parser trace is most likely
unreadable for users who are unexperienced with grammars. Nonetheless,
this trace can be very useful to figure out why a certain keyword is
not recognized in a certain context. The entries in the trace refers
to the {\tt extract\_syntax.output} file produced by {\tt bison}
parser generator. It is located in the source code directory of the
{\tt cc\_extract} program.

The {\tt cc\_extract\_include} program reads a specification and
writes all \verb+\ccInclude+ macros converted to C preprocessor
includes to the standard output. The synopsis for the program is:

\ind{\tt cc\_extract\_include [<infile> ...]}
\TTindex{cc\_extract\_include}\index{include file extraction}

A short example demonstrates the {\tt cc\_extract} program. A
specification file with a short class and two declarations is given.

{\footnotesize
\begin{verbatim}
    A short main text which is not converted.

    \begin{ccClassTemplate}{A<T>}
        A main text within a class declaration. References to the
        classname \ccClassName\ are possible. Math mode, $i$, \CC\ code like
        \ccStyle{a + b;}, or \cgal\ typical abbreviations are translated.

        \ccCreationVariable{a}
        \ccMethod{foo( const A<T>& b);}{A subsidiary comment for the 
            {\tt foo}-function. It does something with \ccVar\ and \ccStyle{b}.} 
    \end{ccClassTemplate}

    \ccFunction{template< class T> void bar( const A<T>& a);}{Another
         subsidiary comment.}
\end{verbatim}
}

The extracted \CC\ code with all comments (no command line options applied).
A simple line-breaking algorithm formats the text.

{\footnotesize
\begin{verbatim}
    template < class T >
    class A {
    public:

    // A main text within a class declaration. References to the classname
    // A<T> are possible. Math mode, i, C++ code like `a + b;', or CGAL
    // typical abbreviations are translated.
    // 
    // New creation variable is: `a'

        foo( const A<T>& b);
            // A subsidiary comment for the foo-function. It does something
            // with `a' and `b'.
    };

    template< class T> void bar( const A<T>& a);
        // Another subsidiary comment.
\end{verbatim}
}

The extracted \CC\ code with no comments (command line option {\tt
  -noc}  applied).

{\footnotesize
\begin{verbatim}
    template < class T >
    class A {
    public:
        foo( const A<T>& b);
    };
    template< class T> void bar( const A<T>& a);
\end{verbatim}
}

% ----------------------------------------------------------------------
\section{Correctness Checking for a Manual with {\tt cc\_check}}
\label{sectionChecker}
\index{correctness checking}\index{checking correctness}
\index{tools}
\TTindex{cc\_check}

The {\tt cc\_check} program reads a specification and checks it
against an implementation. The synopsis for
the program is either one of the two forms:

\ind{\tt cc\_check <spec-files...> [-against [<options>] <impl-files...>]}\\
\ind{\tt cc\_check -against [<options>] <impl-files...>}

Multiple specification files are concatenated to one specification.
Similarly, multiple implementation files are concatenated to one
implementation. If either set of files is not specified, it is read
from the standard input. Available options are:

\begin{tabular}{ll}
    {\tt -fw}      & recognize FunnelWeb or AnyWeb keywords.\\
    {\tt -match}   & print all matched text.\\
    {\tt -unmatch} & print all unmatched text.\\
    {\tt -comm}    & print all commented text.\\
    {\tt -trace} & Produce a debug trace from the {\tt bison} parser. \\
    {\tt -h, -help} & A short usage message and a summary of the options.
\end{tabular}

\index{match}
The options are mainly for debugging. The exception is {\tt -fw}.
This option enables the recognition of FunnelWeb (and AnyWeb) keywords
or key sequences, so that the checker can distinguish what is text and
what is code. To debug the checker, it is useful to know what parts
of the input are recognized ({\tt -match}), what parts are refused as
comments ({\tt -comm}), or what parts do not match ({\tt -unmatch}).
All three command line options can be used in any combination. They
copy those parts of the input to {\tt stdout} that belong to their
category. It is, for example, easy to see if the parser recognize
some portion of the implementation as a comment where it should not.

The program checks whether all specifications have an implementation.
This is done with a pattern matching approach. Each specification is
translated into a regular expression that represents possible
implementations. A declaration, such as in a header file, is
sufficient for an implementation.  If the pattern matches in the
implementation, the check is fulfilled.  Otherwise an error message is
printed denoting the source file and line of the specification for
which the implementation is missing. Obviously, the program cannot
locate where the implementation should have been. For partial matches
(see below), the location in the implementation is also given. In the
case of any errors, the program prints a message that the temporary
generated program {\tt cc\_checker} remains available for checking the
implementation again after corrections. It is called with all
parameters given to {\tt cc\_check} after the {\tt -against} option.

\index{pattern}
The patterns are not perfect, e.g., they are not context sensitive and
sometimes simply different names for arguments are enough for a
mismatch. For this reason and for performance issues, it is preferable
to check only single files.  {\tt cc\_check} applied to the output of
{\tt cc\_extract} should returns 0 in any case. The possible return
values are:

\begin{tabular}{ll}
    0      & all declarations match or only warnings have occurred.\\
    1      & a fatal error like unreadable files has occurred.\\
    2      & a declaration in the specification has no match in the
             implementation.\\
    3      & a partial match has occurred. This can be treated as a warning.
\end{tabular}

A partial match (return value 3) of a function declaration occurs if
the declaration matches a prefix in the implementation so that more
arguments (with default values) can follow. This is possible in the
implementation without mentioning them in the manual. The program
{\tt cc\_check} will report warnings for them since it is not capable
of checking that all remaining arguments have default values.
\index{match}\index{partial match}


The program {\tt cc\_check} is in fact a {\tt csh}-script. It needs
additionally the programs {\tt flex} (sorry, {\tt lex} will not work),
the C compiler {\tt gcc} or alternatively {\tt cc} (can be modified in
the script), and {\tt cc\_build\_checker} build in this delivery.
The program {\tt flex} is a scanner generator and slightly misused
here for the pattern matching. For long specifications the parser
generation can be quite time consuming.
\TTindex{cc\_build\_checker}\index{scripts}
\TTindex{flex}\TTindex{gcc}

\TTindex{DEBUG}\index{environment variable} In addition to the command
line options another debug technique is implemented in the {\tt
  csh}-script. If the environment variable DEBUG is set the script
echos each command executed. The {\tt rm} commands to remove files are
echoed with a \# in front. The temporary files are not removed in
DEBUG mode in order to examine them later.

% =====================================================
\newpage
\bibliographystyle{plain}
%\bibliography{kettner}
\bibliography{manual}

\small
%\printindex

\end{document}

