.\" @(#)overall	1.14	12/12/92
.\"
.\" Use printsec in ~ptolemy/doc/bin or Makefiles in ~ptolemy/doc
.\" to print this out.  To get this section only, as a standalone document,
.\"     % cd ~ptolemy/doc/sect1/ptlang
.\"     % make print
.\"
.\" If you edit this document, PLEASE BE SURE TO MANUALLY CHANGE THE DATE
.\" BELOW, to indicate a new version.  Be sure you have properly checked
.\" out this file with SCCS (the version number should not be a number below):
.VR 0.1.14 12/12/92
.TI "\*(PT Documentation"
.AU
Edward A. Lee
Joseph T. Buck
.AE
.H1 "Introduction
.pp
.Id "documentation"
Since \*(PT is by design an extensible system,
the documentation must be also be extensible.
To ensure reasonable portability, only standard tools
in the Berkeley Unix\** environment
.(f
\** Unix is a trademark of AT&T.
.)f
have been used.
Furthermore, all shell scripts and Makefiles are supplied
along with the documentation so that they can be modified if
necessary.
The formating is with
.i ditroff
(device independent troff)
.Ir "ditroff program"
.Ir "troff program"
.Ir "eqn program"
.Ir "tbl program"
with the -me macros,
.i eqn ,
and
.i tbl .
In addition, some custom macros
.Ir "me troff macros"
have been supplied in order to enforce a consistent look
across all \*(PT documents.
These macros and their use are explained here.
The -me macros will not be covered, since they are adequately
documented elsewhere.
.pp
Since not all Unix systems have
.i ditroff ,
we also provide scripts for printing and previewing the documentation
using
.i groff ,
.Ir "groff program"
.Ir "Gnu groff program"
the freely redistributable replacement for
.i troff
from the Free Software Foundation.  If you wish to use
.i groff ,
follow the installation instructions at the end of this section.
.H1 "Printing the manual"
.pp
.Id "printing the Ptolemy manual"
.Id "manual, printing"
First, all scripts for printing the manual use the c shell,
and require that the printer you wish to use be defined.
To do this, place the following line in the file .cshrc in
.Ir "cshrc file"
your home directory:
.(c
setenv PRINTER lw
.)c
.Ir "PRINTER environment variable"
.Ir "environment variable, PRINTER"
where
.c lw
is replaced with whatever name your printer has.
.pp
All kernel documentation and utilities for printing documentation
are contained in the directory ``~ptolemy/doc''.
It is divided into sections as follows:
.ip "main:" 1i
This directory documents the \*(PT kernel and user interfaces.
.ip "bin:" 1i
The scripts for printing the manual are here.
.ip "headers:" 1i
The troff header files are here.
.lp
Domains are documented where their source code resides.
For instance, the documentation for the SDF domain is
in ``~ptolemy/src/domains/sdf/doc''.
Each directory with documentation has a Makefile.
Printing subsections of the manual can be
accomplished by typing "make print" in the appropriate directory.
.Ir "Makefile"
For instance, to print the whole manual,
.(c
% cd ~ptolemy/doc
% make print
.)c
To print only section 1 of the manual, which contains this section,
.(c
% cd ~ptolemy/doc/main
% make print
.)c
You can preview the document on the screen.  For instance,
.(c
% cd ~ptolemy/doc/main
% make preview
.)c
.Ir "previewing documents"
You can pass options to
.i ditroff .
For instance, suppose you wish
to print only pages 48 through the end of section 1.
Then use
.(c
make OPTIONS=-o48- print
.)c
Any set of
.i ditroff
options may be passed this way.
.Ir "ditroff options"
To print only the pigi document,
.(c
% cd ~ptolemy/doc/main/pigi
% make print
.)c
A table of contents for each major section will also be
printed.  Sorry, but this may not be printed in the proper
order, so some rearranging of the pages may be required.
If you are printing the entire manual, an index will be generated
after the entire manual has been printed.
If you have printed a new version of a subsection,
and wish to update the index, then:
.Id "index, printing"
.Id "printing the Ptolemy manual index"
.(c
% cd ~ptolemy/doc
% make prindex
.)c
.pp
When only a subsection is printed, every attempt is made to format
it as a standalone document.  For this reason, sections
may be numbered differently than they would be in the complete
manual.  In addition, a title page may appear that does not
appear when the complete manual is printed.
.H1 "Writing new sections"
.pp
.Id "writing new documentation"
.Id "documentation, writing new"
In order to get consistent documentation, a set of troff
macros is used to control most important formatting options.
These macros are explained here.
The set of macros used to document basic capabilities
is different from the set used to document demos, stars, and targets.
For stars, the formatted documentation will be generated
automatically by the preprocessor. For demos and targets, you must generate
it yourself.
.H2 "Basic documents"
.pp
An example of a basic document is this one,
covering \*(PT documentation.
The source for this document is in ``~ptolemy/doc/main/documents''.
The macros it uses are defined in ``~ptolemy/doc/headers''.
In that directory, it uses macros defined in the file called
``shared'', and in either the file called ``standalone'' or ``together'',
depending on whether the document is printed by itself
or in combination with other manual sections.
.pp
A typical document has the following syntax:
.(c
	.\\\\\&" %\&W\&%	%\&G\&%
	.VR 0.%\&I\&% %\&G\&%
	.TI "SECTION TITLE"
	.AU
	Author list
	one name per line
	no punctuation
	.AE
	.H1 "Section Title"
	.H2 "Title"
	.H3 "Title"
	.H4 "Title"
	.UH "Un-numbered header"
.)c
Text appearing between headers uses standard -me macro formatting.
The first line is a comment that will be translated by sccs
.Ir "sccs program"
into a version number for the document, looking something like:
.(c
	.\\\\\&" @(#)filename 1.1     10/14/90
.)c
This is interpreted by
.i ditroff
as a comment, and hence has no
affect on the output.
The version number that will appear on the output
is specified by the .VR macro.
.Id "VR troff macro"
It takes two arguments, a version number and a date.
These two arguments will be printed in the lower left and right
corners of each page, respectively.
If the version number is given as ``%\&I\&%'', it will be
translated by sccs into the same version number that follows
``filename'' in the ``@(#)'' line above.
For instance, this document is version ``1.14'' (see the lower
left corner), with a prepended number
corresponding to major releases of \*(PT.
If the date is given by ``%\&G\&%'', it will be translated
by sccs into a date as shown in the lower right hand corner of
this document.
.pp
The ``.TI'' macro gives the section title.
.Id "TI troff macro"
When the document is printed standalone, this title will be put
on a separate title page.
Otherwise, it will be a level-one header.
The rest of the macros should be self explanatory.
A table of contents will be generated using these headers.
.H2 "Adding to main"
.pp
If you are adding a new document to the ``main'' part of the \*(PT
documentation, contained in ``~ptolemy/doc/main'', then you must
edit the Makefile in ``~ptolemy/main''.
Simply add your new directory name to the definitions of the variables
.c DIRS
and
.c SECTIONS,
using existing entries as a model.
.pp
Your new directory should contain a file called ``overall''
which defines the entire document.
.Id "overall document file"
It may contain lines like
.(c
	.so filename
.)c
to source from another file.
Typically, all major subsections of the document would be written
in their own file, with a corresponding ``.so'' entry in ``overall''.
.pp
Your new directory should also itself contain a Makefile, used
for printing the document in standalone form.  This should be
a symbolic link to the file
``~ptolemy/doc/main/sectionMake'' \-
using a link rather than a copy guarantees that all sections will
print the same even if the master copy is modified.
.H2 "Index entries"
.pp
The documentation scripts for \*(PT will automatically
generate an index.
.Id "index entries"
The indexing system supports three kinds of index entries:
``definition'' entries are used when a term is defined in
some sense;
``example'' entries are used when a term is used in an example;
and ``reference'' enteries are used in all other cases \-
typically when a term is referenced.
When the index is printed, definition entries have their page
numbers in boldface, index entries have their page
numbers in italics, and reference entries have their page number
in the default font.
This allows the reader to quickly locate the information for which
they are searching.
.pp
Entries in the index must be defined in the document source
using one of the the macros:
.(c
	.Id "definition entry"
	.Ie "example entry"
	.Ir "reference entry"
.)c
for a definition, example, or reference entry, respectively.
(The .IE macro used in older versions of Ptolemy acts as a
reference entry).
The entries will be sorted alphabetically.
.Id "IE troff macro"
.Id "Id troff macro"
.Id "Ir troff macro"
.Id "Ie troff macro"
If you look at the index printed with this document,
you will find an entry ``index'' pointing right here.
If you wish for a two word entry to appear twice,
alphabetically by each of the two words, then you must use two index
entries:
.(c
	.Ir "two words"
	.Ir "words, two"
.)c
No additional editing will be done on index entries.
For this reason, index entries should be carefully chosen.
For example, please do not put the following entry in every
demo description:
.(c
	.IE "\*(PT demo"
.)c
This will lead to hundreds of identical, and very uninteresting index
entries.
Avoid index entries beginning with very generic words in the \*(PT
vocabulary, like \*(PT,
.c star,
.c galaxy,
or
.c domain.
Of course, if you are writing some explanation of these basic terms,
then an index entry is appropriate.
Before entering index entries for a star, look in the documentation
for similar stars to get an idea of the subject terms that have
already been used and might be related.
.pp
One final note: to generate an index entry for a star or galaxy,
use one of the macros:
.(c
	.Sr star domain
	.Se star domain
.)c
These will create reference or example index entry for the named star
in the given domain
in the ``C++ class font'' (to set it off from other entries), and will
parenthetically note that the entry is for a star in the specified domain.
.Id "Sr troff macro"
.Id "Se troff macro"
If the star is in the same domain as the current section of the documentation,
you can leave off the domain specifier.
For example,
the entry:
.(c
	.Sr autocor
.)c
when in SDF domain documentation will generate an index entry of the form:
.(c
	autocor \fR(SDF star)\fP
.)c
.H2 "Special fonts and displays"
.pp
By convention, \*(PT documentation always refers to \*(PT
using the troff string invoked by the sequence ``\\*(PT''.
.Id "PT troff string"
.Id "fonts, special"
This gets formatted in a standard way with a standard font.
The overall \*(PT version number is \*(PV, invoked
by the sequence ``\\*(PV''.
.pp
In addition, c++ class names are set in a special font
by using the ``.c'' macro:
.(c
	.c Class
.)c
as shown here:
.c Class.
.Id "c troff macro"
For a display entirely set in this font, with no fill,
use the macro pair ``.(c ... .)c'', as in
.(c
	.(c
	text
	goes
	here.
	.)c
.)c
which will come out like:
.(c
text
goes
here.
.)c
This font is also used to highlight keywords,
and to display sections of source code.
The ``.(c ... .)c'' macro pair attempt to keep the text between them
on one page, starting a new page if there isn't room on the current
one.  The ``.(d ... .)d'' macro pair have the same function
but without the keep.
.H2 "Documenting stars"
.pp
Manual entries for new stars will be generated automatically
if you follow the directions given in the section above on defining new
stars.  You need not, therefore, be concerned with the
troff macros used for this.
All editing of the star documentation should be done in the .pl file,
not in the troff file.
.Id "stars, documenting"
.Id "documentation, stars"
.H2 "Documenting new galaxies and universes"
.pp
.Id "galaxies, documenting"
.Id "demos, documenting"
.Id "documenting galaxies"
.Id "documenting demos"
.Id "documenting universes"
.Id "universes, documenting"
Unlike stars, galaxies and universes must be documented manually.
The troff source files for galaxies should go in XXX/doc/stars,
where XXX is the location of the domain source directory.
Since galaxies can be used exactly as if they were stars,
it is logical that their documentation should appear with
the stars.
Troff source files for demo universes should go in XXX/doc/demos,
where XXX is again the location of the domain source directory.
.pp
In both cases, the syntax of the document source files is as follows:
.(c
	.\\\\\&" %\&W\&%	%\&G\&%
	.NA "Name of demo universe"
	.SD
	Short descriptor
	.SE
	.SV %\&I\&% %\&G\&%
	.AL "Author list, with commas, and a period."
	.LO "Location of the galaxy or demo definition"
	.LD
	Long descriptor.
	This can contain any -me, eqn, or tbl directives.
	It can also contain un-numbered headers:
	.UH "title"
	.SA
	"See Also"
	List of pointers to other entries in the manual
	.ES \" Every entry must end with this call
.)c
The first line is again a
.i ditroff
comment, containing the SCCS version ID.
The second line defines how the version ID and date should be printed
when the manual is printed.
The version number %\&I\&% and date %\&G\&%
keywords have the same meaning as before.
The date here must be manually modified when the galaxy or demo is modified.
The rest of the entries should be self-explanatory.
Here is an example:
.(c
	.\\\\\&" %\&W\&%	%\&G\&%
	.NA adaptFilter
	.SD
	A demo of the LMS adaptive filter star
	.DE
	.Se LMS
	.SV %\&I\&% %\&G\&%
	.AL "Edward A. Lee"
	.LO "~ptolemy/src/domains/sdf/demo"
	.LD
	A Gaussian white noise signal serves as input to an
	FIR filter and an adaptive filter using the LMS algorithm.
	The output of the two filters and the error are displayed
	after the run.  By examining the parameters of the two
	filters, you can find the filenames for the FIR filter
	coefficients and the initial tap values.  The final tap
	values can be saved by specifying a saveTapsFile in the
	adaptive filter star.
	.SA
	IIDGaussian,
	LMS,
	FIR.
	.ES
.)c
Note that a carefully chosen index entry has been inserted here via
the ``.Se'' macro.
.Ie "Se troff macro"
\fIIt is not necessary to insert an explicit index entry for the
name of the galaxy or demo\fP.  This will be done automatically.
It is also recommended that index entries not be inserted
for all the ``See Also'' entries.
In this case, however, the main purpose of the demo is to demonstrate
the
.c LMS
star, and the name of the demo is not something like
.c LMSdemo,
so an explicit entry is advised.
.pp
For galaxies, additional entries are required to document the
inputs, outputs, and states.
The list of inputs is surrounded by the delimitters
.(c
	.IH
	...
	.PE
.)c
while the list of outputs is inside
.(c
	.OH
	...
	.PE
.)c
Each input or output is listed as follows
.(c
	.NE
	\\\\fIname\\\\fR (type): descriptor
.)c
States are delimitted by
.(c
	.SH
	...
	.ET
.)c
with each entry reading
.(c
	.NE
	\\\\fIname\\\\fR (type): descriptor
	.DF "default value"
.)c
State entries should also be made for demos with top-level parameters.
.pp
A single star, galaxy, or demo document page can be printed
using the command ``printpage filename''.
This command is stored in ~ptolemy/doc/bin, but also has a link
in ~ptolemy/bin, so it should be in your path.
.H2 "Documenting targets"
.pp
Targets should be documented in the same way that universes and
galaxies are documented, with careful attention paid to documenting
each parameter or state.
Troff source files for demos should go in XXX/doc/targets,
where XXX is again the location of the domain source directory.
.H2 "Documenting new domains"
.pp
.Id "domains, documenting"
.Id "documenting domains"
To include a new domain in the manual, you must 
edit the Makefile in ~ptolemy/doc to add to the
.c DIRS
variable the name of the directory containing the domain documentation.
This will cause your domain to be printed along with the rest of the manual.
Suppose your domain is documented in directory XXX/doc.
This directory should contain a set of specific files recognized
by the documentation scripts.
.UH "title:"
The directory XXX/doc should contain a file called ``title''
which defines the title page for the domain.
.Id "title page, domain"
.Id "domain title page"
A typical title page is:
.(c
	.\\\\\&" %\&W\&%	%\&G\&%
	.eh ''''
	.oh ''''
	.bp
	.(b C
	.sp 1.5i
	.S 200
	.ft 6
	2
	.S 80
	.sp 2i
	SDF
	.sp 1i
	Domain
	.)b
.)c
These are all -me macro calls, except ``.S'' which is defined
in ~ptolemy/doc/headers/shared.  It changes the font size in an orderly way.
The eighth line from the top specifies a section number for the overall
\*(PT document.  This is optional, but should obviously be a large
enough number so that is doesn't conflict with other domain sections.
.UH "init:"
The directory XXX/doc should contain a file called ``init''
with the following definitions:
.(c
	.\\\\\&" %\&W\&%	%\&G\&%
	.nr SN 0 \" Initialize section number
	.nr AS 2 \" Almagest section number
.)c
where the section number is changed to be the same as that used in
the ``title'' file.
Pages of the domain section will be numbered X-Y, where X is the
section number defined by the init file, and Y is the page number.
.UH "overall:"
Just as with ordinary manual sections, this file contains the
main documentation of the domain, including explanations of
its basic operation, how to add stars, how its interface to
other domains works, etc.
The macros it uses are identical to those of ``basic documents''
as explained above.
.UH "stars:"
This directory should contain the troff source documents for
the stars in the domain.
If the directory is absent, no stars documentation will be printed.
.UH "starstitle:"
This file contains the title of the stars documentation section,
as in the following example:
.(c
	.\\\\\&" %\&W\&%	%\&G\&%
	.TI "SDF Stars"
.)c
.UH "demos:"
This directory should contain the troff source documents for
the demos in the domain.
If the directory is absent, no demos documentation will be printed.
.UH "demotitle:"
This file contains the title of the demos documentation section,
as in the following example:
.(c
	.\\\\\&" %\&W\&%	%\&G\&%
	.TI "SDF Demos"
.)c
.H2 "Restricted filenames in domain documents"
.pp
The following filenames in an XXX/doc directory,
where XXX is the domain directory, have special functions, as explained above:
.Id "files, restricted, in domain documentation"
.Id "domain documentation, restricted files"
.(c
index
title
init
overall
stars (a directory)
starstitle
demos (a directory)
demostitle
Makefile
.)c
Complete documentation of a domain contains all of these,
plus possibly other files sourced using .so.
.H1 "Configuring your system to use the Gnu groff program"
.pp
If you do not have
.i ditroff ,
you may preview and print the documents by configuring your system
to use
.i groff
instead.  The
.i groff
package is a set of tools from the Free Software Foundation that
provide a freely redistributable, mostly-compatible replacement
for
.i troff ,
.i nroff ,
and related programs.
.pp
Since the command line interface to
.i groff
is quite different and some adjustments are required, different
scripts are provided.  To install them as the official document-printing
scripts, do the following (you must have appropriate write permission):
.(c
% cd ~ptolemy/doc/bin
% USE_GROFF
.)c
.Ir "USE_GROFF"
This command will install the
.i groff
scripts as the official scripts.
.pp
Since
.i groff
is a replacement for the old
.i troff
rather than for
.i ditroff ,
it cannot handle as many fonts; therefore the scripts for using
.i groff
cause some of the fancier fonts used in the manuals to print in bold
face instead.  There may be other glitches as well; however, the
resulting manuals are still quite usable.
.pp
The
.i groff
program can be obtained from many FTP sites;
.Ir "obtaining Gnu groff"
the Free Software Foundation
will also send a copy of it to you on tape for a reasonable fee.  Write
to:
.br
Free Software Foundation, Inc.
.br
675 Mass Ave, Cambridge, MA 02139, USA
.br
or send email to ``gnu@prep.ai.mit.edu'' for more information on obtaining FSF software.

