%  devdoc.tex from ObjectProDSP 0.2
%  Copyright (C) 1994 1995, Mountain Math Software. All rights reserved.
%  
%  This file is part of ObjectProDSP, a tool for Digital Signal
%  Processing design, development and implementation. It is free
%  software provided you use and distribute it under the terms of
%  version 2 of the GNU General Public License as published
%  by the Free Software Foundation. You may NOT distribute it or
%  works derived from it or code that it generates under ANY
%  OTHER terms.  In particular NONE of the ObjectProDSP system is
%  licensed for use under the GNU General Public LIBRARY License.
%  Mountain Math Software plans to offer a commercial version of
%  ObjectProDSP for a fee. That version will allow redistribution
%  of generated code under standard commercial terms.
%  
%  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 version 2 of the GNU General
%  Public License along with this program. See file COPYING. If not
%  or if you wish information on commercial versions and licensing
%  write Mountain Math Software, P. O. Box 2124, Saratoga, CA 95070,
%  USA, or send us e-mail at: support@mtnmath.com.
%  
%  You may also obtain the GNU General Public License by writing the
%  Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
%  USA.  However if you received a copy of this program without the
%  file COPYING or without a copyright notice attached to all text
%  files, libraries and executables please inform Mountain Math Software.
%  
%  ObjectProDSP is a trademark of Mountain Math Software.
%  
\section{Updating the documentation}
\label{Sec:Doc}

\subsection{Help files}
\label{Sec:HelpFile}

The help files referenced in the menu data base and
the pull down menus are also used in the printed documentation.
They are written in a very restricted \DppNm{groff} format using the
\DppNm{mm} macro package. They are
translated to \LaTeX{}\index{LaTeX}  format for inclusion in the manuals.
The originals are in directory \\
\verb"$OPD_ROOT/doc/roff". 
A help file name {\tt help.hlp} comes from a file {\it X}{\tt help.roff}
or {\it X}{\tt helpT.roff}. `{\it X}' can be any single character.
The optional `{\tt T}' indicates the roff file must be processed with
\DppNm{tbl}. Such files must be displayed with a fixed font 
or the tables will be skewed. The `T' is used to control this.

\subsubsection{\protect\DppNm{Makefile} to process help files}

A subdirectory \DppNm{mmake} under the roff directory contains
tools for creating the \DppNm{Makefile} to process the help files with
\DppNm{groff} and \LaTeX{}\index{LaTeX}.
Each help file name is listed in one of three files shown
in Figure~\PageRef{Tab:OriginHelp}.
These are read by \DppNm{mmake}
(source file \DppNm{mmake.C}) to create the \DppNm{Makefile}
in the parent directory. If you add an example or help file
you need to update these list files and do a \DppNm{make}
in the directory they occur to create the \DppNm{Makefile}
with your changes in the parent directory.

\begin{table}
\begin{tabular}{|llll|} \hline
List file & Directory & Manual & Manual file \\
& \verb"$OPD_ROOT/doc/" & & \\ \hline
\DppNm{examp\_list} & \DppNm{examptex} & \DppUser{} & \DppNm{exampmn.tex} \\
\DppNm{node\_list} & \DppNm{nodetex} & \DppLib{} & \DppNm{ovnodlst.tex} \\
\DppNm{help\_list} & \DppNm{helptex} & \DppUser{} & \DppNm{mnroffmn.tex} \\
\hline
\end{tabular}
\caption{Lists of help files}
\label{Tab:OriginHelp}
\end{table}

Table~\PageRef{Tab:OriginHelp} also shows the
the directory (under {\tt \$OPD\_ROOT/doc}) that the
generated \LaTeX{} files are written to, the manual those
files are incorporated in and the file for that manual that
references these files. \DppNm{exampmn.tex} is created with
the names of all the  files in \DppNm{examp\_list}
and similarly \DppNm{ovnodlst.tex} is created with all
the names of all the files in \DppNm{node\_list}
when you \DppNm{make} the manuals. To add a new entry
to the documentation you only need to add it to the appropriate
list
and do the required \DppNm{make}'s.

\DppNm{mnroffmn.tex} includes the files from \DppNm{help\_list}
indirectly through several files that are created automatically.
This is to allow different introductory comments for different
groups of files. Comments in \DppNm{mnroffmn.tex} describe
these groups and are used to automatically create the indirect
include files. You can add a new help file to any of these sections
by adding it at the appropriate place in \DppNm{help\_list}
and doing the required makes.

\subsubsection{Help file format}

\begin{figure}
\input{sighlp.tex}
\caption{Example groff help file}
\label{Fig:HelpExamp}
\end{figure}

Figure~\PageRef{Fig:HelpExamp} is an example \DppNm{groff}
help file. It begins with a section name at level 1. All
help files should start this way. This will be translated
to a \verb"\"\DppNm{subsection} \LaTeX{} command. Lower level sections
will be translated consistently.

The \DppNm{groff} comment starting with `\verb|\"|\DppNm{.LINE}' is a way of
providing
different text to \LaTeX{} and \DppNm{groff}. The remainder
of the text on this line is {\it only} processed by \LaTeX{}. It
it is a comment in \DppNm{groff} and the `\verb|\"|\DppNm{.LINE}'
is removed from the \LaTeX{} file. The next line
is not copied to the \LaTeX{} files and is thus
{\it only} processed by \DppNm{groff}.

The \DppNm{groff} comment \verb|\"|\DppNm{.CAPTION} starts a \LaTeX{}
table. It provides a caption and label for the table as two
strings. Preceding these strings is a list of integers indicating
columns in the table. The text in those columns is enclosed in
the \verb"\"\DppNm{Index} macro. If the column number is negative
the \verb"\"\DppNm{DppNm} macro is used instead. The first macro includes
the text as an index entry. The second macro also sets the text
in {\tt typewriter font}.
The remainder of the table is specified in \DppNm{groff}
format and translated to \LaTeX{}.
Figure~\PageRef{Fig:TeXHelp} shows
the \LaTeX{} file generated from the \DppNm{groff} file in
Figure~\PageRef{Fig:HelpExamp}. Note any words in single quotes
in the \DppNm{.roff} file are made arguments of the \verb"\"\DppNm{DppNm}
macro in the \DppNm{.tex} file.

\begin{figure}
\input{sigtex.tex}
\caption{\LaTeX{} file generated from groff file}
\label{Fig:TeXHelp}
\end{figure}


\subsection{Overview and tutorial}

Appendix A in \DppTut{} is generated automatically from
the \DppNm{.tex} files created in subdirectory \DppNm{texs} from
the directory in which the node \DppNm{.usr} file is created.
Lists of these files are created  when you
\DppNm{make} the \DppTut{}. These files are sorted alphabetically
based on the class name and occur in the Appendix in that
order and grouped in sections as shown in Table~\PageRef{Tab:NodeDocWhere}.

As long as you are adding nodes
to an existing directory 
listed in Table~\ref{Tab:NodeDocWhere}
you do not need to do anything except remake this manual
to include new nodes in the Appendix. The names under `Files'
in this table are for the \DppLib{}.
A file `{\it name}{\tt .tex}' in the table will be
`{\it name}{\tt s.tex}' in the {\tt Makefile} for creating the Appendix.

No help  files are used in this manual.

\begin{table}
\begin{tabular}{|lll|} \hline
Directory under & File & Type of file \\
{\tt \$OPD\_ROOT/src/dsp} & & \\ \hline
\DppNm{nodes/proc}& \DppNm{node.tex} & processing nodes \\
\DppNm{nodes/proc32}& \DppNm{node.tex} & only used in 32 bit simulator \\
\DppNm{nodes/signal} & \DppNm{signal.tex} & signal generation nodes \\
\DppNm{nodes/sigdsk} & \DppNm{signal.tex} & read signal from disk \\
\DppNm{nodes/display} & \DppNm{display.tex} & output and display \\
{\it selected files} &\DppNm{basenod.tex} & shared member functions \\
\DppNm{lib/control} & \DppNm{auxfuncs.tex} & other than node classes \\
\DppNm{lib/network} & \DppNm{auxfuncs.tex} & other than node classes \\ 
\hline
\end{tabular}
\caption{Where nodes are documented}
\label{Tab:NodeDocWhere}
\end{table}


\subsection{Library manual}

Nodes in \DppLib{} are updated just as they are for \DppTut{} 
as described in the previous section.
The {.tex} files in subdirectory \DppNm{tex} (not \DppNm{texs}) are used.
Table~\PageRef{Tab:NodeDocWhere} shows where different kinds of nodes
occur in the manual and what directories are searched for these nodes.

Help files that describe nodes or classes of nodes are included in
\DppNm{ovnode.tex}. If you add a help file for a node or group of
nodes you should add it to \DppNm{ovnode.tex} and edit
the \DppNm{Makefile}.

\subsection{User's manual}

The nodes are not directly documented in the \DppUser{}.
However the entire menu tree is including the portions of
it that are built from the node definitions. The \LaTeX{}
files for this are created by the \DppNm{Makefile} in directory
\verb"$OPD_ROOT/doc/build".
You should run this \DppNm{make} whenever you add nodes, update
existing ones or make other changes to the menu data
base. This will update \LaTeX{} files for the \DppUser{}. 
These updated \DppNm{.tex} files are built  from \DppNm{opd.menu}
and the \DppNm{.nod} files
in subdirectory \DppNm{nodes} under {\tt \$OPD\_ROOT/\-src/\-menus}". 

All help files other than those documenting nodes or classes of
nodes are included in this manual from file \DppNm{mnroffmn.tex}.
You should update this file and the \DppNm{Makefile} for this manual
if you add help files like this.

\subsection{Developers manual}

The developers manual (this manual) does not ordinarily need to
be updated as a result of changing nodes or menus. However if
you need to define new base classes with new constructor
parameters you will need to update the structures defined in\\
\verb"$OPD_ROOT/src/util/mknode/ctorinit.C". \\
You should update the documentation
included in these data structures. That documentation
is used in creating several tables in Section~\PageRef{Sec:BaseConst}.

It is outside the current scope
of this manual to explain how to do this but if necessary you
should be able to figure it out from the code in \DppNm{ctorinit.h}
and \DppNm{ctorinit.C} and the \DppNm{Makefile} for the developer's
manual.

Several files are used as examples in creating this manual. If you
change any of these files you should check to insure this does 
not mess up their use in the documentation. These files are shown
in Table~\PageRef{Tab:DevFiles}.



\begin{table}
\begin{centering}
\begin{tabular}{|llrr|} \hline
File under \verb"$OPD_ROOT"& \LaTeX{} file & Figure & Page \\
\hline
\verb"src/dsp/nodes/proc/block.usr" & \DppNm{blockusr} \tref{Fig:blockusr} \\
\verb"src/include/ObjProDSP/arthtyp.h" & \DppNm{artyp} \tref{Fig:artyp} \\
\verb"src/menus/opd.menu" & \DppNm{mmenu} \tref{Fig:MenuExamp} \\
\verb"src/menus/opd.menu" & \DppNm{exampmenu} \tref{Fig:ExampMenuTree} \\
\verb"doc/roff/ssignalT.roff" & \DppNm{sighlp} \tref{Fig:HelpExamp} \\
\verb"doc/nodetex/ssignalT.tex" & \DppNm{sigtex}\tref{Fig:TeXHelp} \\
\hline
\end{tabular}
\caption{Source files used as examples in this manual}
\label{Tab:DevFiles}
\end{centering}
\end{table}

