From b164a9ff9f4e7b25eb8f1835b7fe6b9a849c7ff8 Mon Sep 17 00:00:00 2001 From: michael Date: Tue, 18 Mar 2003 00:14:51 +0000 Subject: [PATCH] + Added fpdoc --- docs/Makefile | 10 +- docs/Makefile.4ht | 1 + docs/Makefile.hev | 2 +- docs/Makefile.l2h | 14 + docs/fpdoc.tex | 1694 +++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 1718 insertions(+), 3 deletions(-) create mode 100644 docs/fpdoc.tex diff --git a/docs/Makefile b/docs/Makefile index 2ddee5a85b..9ab77ed2ec 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -22,7 +22,7 @@ #INSTALLDEBUG=1 # Which docs are made when 'html' is specified -HTML = user units ref prog +HTML = user units ref prog fpdoc # Can be 'report','book', 'html', 'hevea', 'ts3' 'ts4' ifdef USEHEVEA @@ -332,6 +332,8 @@ prog.dvi: prog.tex includes user.dvi: user.tex includes +fpdoc.dvi: fpdoc.tex includes + units.pdf: units.tex includes $(CHAPTERS) ref.pdf: ref.tex includes @@ -344,6 +346,7 @@ onechap.pdf: onechap.tex includes onechap.dvi: onechap.tex includes +fpdoc.pdf: fpdoc.tex includes dvi : $(DVI) @@ -537,7 +540,10 @@ execute: # # $Log$ -# Revision 1.19 2003-03-17 08:27:27 michael +# Revision 1.20 2003-03-18 00:14:51 michael +# + Added fpdoc +# +# Revision 1.19 2003/03/17 08:27:27 michael # + Split out html generation # # Revision 1.18 2003/03/16 15:24:58 peter diff --git a/docs/Makefile.4ht b/docs/Makefile.4ht index f5b85d6ab3..eab5cfc1c6 100644 --- a/docs/Makefile.4ht +++ b/docs/Makefile.4ht @@ -26,5 +26,6 @@ units: htmlincludes preamble3 units.html prog: htmlincludes preamble3 prog.html onechap: htmlincludes preamble3 onechap.html ref: htmlincludes preamble4 ref.html +fpdoc: htmlincludes preamble3 fpdoc.html html: htmlincludes $(HTML) diff --git a/docs/Makefile.hev b/docs/Makefile.hev index a3b24559dc..11e58d5333 100644 --- a/docs/Makefile.hev +++ b/docs/Makefile.hev @@ -12,6 +12,6 @@ units: htmlincludes units.html prog: htmlincludes prog.html onechap: htmlincludes onechap.html ref: htmlincludes ref.html +fpdoc: htmlincludes fpdoc.html html: htmlincludes $(addsuffix .html,$(HTML)) - diff --git a/docs/Makefile.l2h b/docs/Makefile.l2h index 047ae8d21c..94efab060d 100644 --- a/docs/Makefile.l2h +++ b/docs/Makefile.l2h @@ -86,5 +86,19 @@ ifndef DEBUG endif touch onechap.chk +fpdoc: fpdoc.chk +fpdoc.chk: htex.chk includes + cp -f preamble.html preamble.inc + $(LATEX2HTML) $(LATEX2HTMLOPTS) -split 2 -link 2\ + -t "Free Pascal documentation tool manual" fpdoc.htex + -sed -f foot.sed fpdoc/footnote.html + -mv fpdoc/footnote.html fpdoc/footnode.html +ifndef DEBUG + -rm -f fpdoc/labels.pl fpdoc/internals.pl fpdoc/.*.pag fpdoc/.*.dir + -rm -f fpdoc/images.* fpdoc/*.log fpdoc/WARNINGS +endif + touch fpdoc.chk + + html: $(HTML) diff --git a/docs/fpdoc.tex b/docs/fpdoc.tex new file mode 100644 index 0000000000..680856b1a6 --- /dev/null +++ b/docs/fpdoc.tex @@ -0,0 +1,1694 @@ +% +% $Id$ +% This file is part of the FPC documentation. +% Copyright (C) 1997, by Michael Van Canneyt +% +% The FPC documentation is free text; you can redistribute it and/or +% modify it under the terms of the GNU Library General Public License as +% published by the Free Software Foundation; either version 2 of the +% License, or (at your option) any later version. +% +% The FPC Documentation 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 +% Library General Public License for more details. +% +% You should have received a copy of the GNU Library General Public +% License along with the FPC documentation; see the file COPYING.LIB. If not, +% write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, +% Boston, MA 02111-1307, USA. +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Preamble. +\input{preamble.inc} +\latex{% + \ifpdf + \pdfinfo{/Author(Michael Van Canneyt) + /Title(Users' Guide) + /Subject(FPDoc Users' guide) + /Keywords(Free Pascal) + } +\fi} +% +% Settings +% +\makeindex +% +% Start of document. +% +\newcommand{\fpdoc}{\textsc{FPDoc}\xspace} +\newcommand{\seesu}[1]{section \ref{suse:#1}, page \pageref{suse:#1}\xspace} +\newcommand{\seetag}[1]{\tag{#1} (\pageref{tag:#1})\xspace} +\newcommand{\tag}[1]{\textbf{#1}} +\newcommand{\attr}[1]{\textit{#1}} +\usepackage{tabularx} +\usepackage{syntax} +\begin{document} +\title{FPDoc :\\Free Pascal code documenter: Reference manual} +\docdescription{Reference manual for FPDoc} +\docversion{0.9} +\date{\today} +\author{Micha\"el Van Canneyt} +\maketitle +\tableofcontents + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Introduction +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\chapter{Introduction} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% About this document +\section{About this document} +This is the reference manual for \fpdoc, a free documentation tool for +Pascal units. It describes the usage of \fpdoc and how to write +documentation with it. + +It attempts to be complete, but the tool is under continuous development, +and so there may be some slight differences between the documentation and +the actual program. In case of discrepancy, the sources of the tool are the +final reference. A \file{README} or \file{CHANGES} file may be provided, and +can also give some hints as to things which have changed. In case of doubt, +these files or the sources are authoritative. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% About FPDoc +\section{About \fpdoc} +\fpdoc is a tool that combines a Pascal unit file and a description file +in XML format and produces reference documentation for the unit. The +reference documentation contains documentation for all of the identifiers +found in the unit's interface section. The documentation is fully +cross-referenced, making it easy to navigate. It is also possible to refer +to other documentation sets written with \fpdoc, making it possible to +maintain larger documentation sets for large projects. + +Contrary to some other documentation techniques, \fpdoc does not require the +presence of formatted comments in the source code. It takes a source file +and a documentation file (in XML format) and merges these two together to a +full documentation of the source. This means that the code doesn't get +obfuscated with large pieces of comment, making it hard to read and +understand. + +\fpdoc is package-oriented, which means that it considers units as part of a +package. Documentation for all units in a package can be generated in one +run. + +At the moment of writing, the documentation can be generated in the +following formats: +\begin{description} +\item[HTML] Plain HTML. Javascript is used to be able to show a small window +with class properties or class methods, but the generated HTML will work +without JavaScript as well. Style sheets are used to do the markup, so the +output can be customised. +\item[XHTML] As HTML, but using a more strict syntax. +\item[LaTeX] LaTeX files, which can be used with the \file{fpc.sty} file +which comes with the \fpc documentation. From this output, PDF documents can +be generated, and with the use of latex2rtf, RTF or Winhelp files. Text +files can also be generated. +\end{description} +Plans exist to create direct text output and RTF output as well. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Getting more information. +\section{Getting more information.} +If the documentation doesn't give an answer to your questions, +you can obtain more information on the Internet, on the following address: + +\htmladdnormallink{http://fpdoc.freepascal.org/} +{http://fpdoc.freepascal.org} + +It contains links to download all \fpdoc related material. + +Finally, if you think something should be added to this manual +(entirely possible), please do not hesitate and contact me at +\htmladdnormallink{michael@freepascal.org}{mailto:michael@freepascal.org}. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Installation +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\chapter{Compiling and Installing \fpdoc} +\label{ch:Installation} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Compiling +\section{Compiling} +In order to compile \fpdoc, the following things are needed: +\begin{enumerate} +\item The fpdoc sources. These can be downloaded from the \fpdoc website. +\item The \fpc compiler sources. \fpdoc uses the scanner from the \fpc +comiler to scan the source file. +\item The FCL units (or their sources) should be installed. +\item fpcmake is needed to create the makefile for fpdoc. It comes with +\fpc, so if \fpc is installed, there should be no problem. +\item To make new internationalisation support files, \file{rstconv} must be +installed, and the GNU gettext package. +\end{enumerate} +Links to download all these programs can be found on the \fpdoc website. + +When the fpdoc sources have been unzipped, the Makefile must be generated. +Before generating the makefile, the location of the compiler source +directory should be indicated. In the \file{Makefile.fpc} file, which has a +windows ini file format, locate the \var{fpcdir} entry in the \var{defaults} +section: +\begin{verbatim} +fpcdir=../.. +\end{verbatim} +and change it so it points to the top-level \fpc source directory. + +After that, running \file{fpcmake} will produce the \file{Makefile}, and +running \file{make} should produce 2 executables: \file{fpdoc} and +\file{makeskel}. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Installation +\section{Installation} + +When installing from sources, a simple +\begin{verbatim} +make install +cd intl +make install +\end{verbatim} +should completely install the documentation tool. + +When installing from a archive with the binaries, it should be sufficient +to copy the binaries to a directory in the \var{PATH}. + +To have fpdoc available in several languages, the language files should be +installed in the following directory on Unix systems: +\begin{verbatim} +/usr/local/share/locale/XX/LC_MESSAGES/ +\end{verbatim} +or +\begin{verbatim} +/usr/share/locale/XX/LC_MESSAGES/ +\end{verbatim} +Depending on the setup. Here \var{XX} should be replaced by the locale +identifier. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Usage +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\chapter{\fpdoc usage} +\label{ch:usage} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Usage +\section{fpdoc} +Using \fpdoc is quite simple. It takes some command-line options, and based +on these options, creates documentation. The command-line options can be +given as long or short options, as is common for most GNU programs. + +In principle, only 2 command-line options are needed: +\begin{description} +\item[package] This specifies the name of the package for which +documentation must be created. Exactly one package option can be +specified. +\item[input] The name of a unit file for which documentation should be +generated. This can be a simple filename, but can also contain some syntax +options as they could be given to the \fpc scanner. More than one +\var{input} option can be given, and documentation will be generated for all +specified input files. +\end{description} + +Some examples: +\begin{verbatim} +fpdoc --package=fcl --input=crt.pp +\end{verbatim} +This will scan the \file{crt.pp} file and generate documentation for it +in a directory called \file{fcl}. +\begin{verbatim} +fpdoc --package=fcl --input='-I../inc -S2 -DDebug classes.pp' +\end{verbatim} +This will scan the file \file{classes.pp}, with the \var{DEBUG} symbol +defined, the scanner will look for include files in the \file{../inc} +directory, and \var{OBJFPC}-mode syntax will be accepted. + +(for more information about these options, see the \fpc compiler user's +guide) + +With the above commands, a set of documentation files will be generated in +HTML format (this is the standard). There will be no description of any of +the identifiers found in the unit's interface section, but all identifiers +declarations will be present in the documentation. + +The actual documentation (i.e. the description of each of the identifiers) +resides in a description file, which can be specified with the \var{descr} +option: + +\begin{verbatim} +fpdoc --package=fcl --descr=crt.xml --input=crt.pp +\end{verbatim} +This will scan the \file{crt.pp} file and generate documentation for it, +using the descriptions found in the file{crt.xml} file. The documentation +will be written in a directory called \file{fcl}. +\begin{verbatim} +fpdoc --package=fcl --descr=classes.xml \ + --input='-I../inc -S2 -DDebug classes.pp' +\end{verbatim} +All options should be given on one line. +This will scan the file \file{classes.pp}, with the \var{DEBUG} symbol +defined, the scanner will look for include files in the \file{../inc} +directory, and \var{OBJFPC}-mode syntax will be accepted. + +More than one input file or description file can be given: +\begin{verbatim} +fpdoc --package=fcl --descr=classes.xml --descr=process.xml \ + --input='-I../inc -S2 -DDebug classes.pp' \ + --input='-I../inc -S2 -DDebug process.pp' +\end{verbatim} +Here, documentation will be generated for 2 units: \file{classes} +and \var{process} + +The format of the description file is discussed in the next chapter. + +Other formats can be generated, such as latex: +\begin{verbatim} +fpdoc --format=latex --package=fcl \ + --descr=classes.xml --descr=process.xml\ + --input='-I../inc -S2 -DDebug classes.pp' \ + --input='-I../inc -S2 -DDebug process.pp' +\end{verbatim} +This will generate a LaTeX file called \file{fcl.tex}, which contains the +documentation of the units \file{classes} and \var{process}. The latex file +contains no document preamble, it starts with a chapter command. +It is meant to be included (using the LaTeX include command) in a latex +document with a preamble. + +The output of \fpdoc can be further customised by several command-line +options, which will be explained in the next section. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Usage +\section{\fpdoc command-line options reference} +In this section all \fpdoc command-line options are explained. + +% content +\subsection{content} +\label{suse:content} +This option tells \fpdoc to generate a content file. +A content file contains a list of all the +possible anchors (labels) in the generated documentation file, and can be +used to create cross-links in documentation for units in other packages, +using the counterpart of the content option, the \var{import} option +(\seesu{import}). + +%descr +\subsection{descr} +\label{suse:descr} +This option specifies the name of a description file that contains the +actual documentation for the unit. This option can be given several +times, for several description files. The file will be searched relative to +the current directory. No extension is added to the file, it should be a +complete filename. + +If the filename starts with an 'at' sign \var{@}, then it is interpreted +as a text file which contains a list of filenames, one per line. +Each of these files will be added to the list of description files. + +The nodes in the description files will be merged into one big tree. This +means that the documentation can be divided over multiple files. When +merging the description files, nodes that occur twice will end up only once +in the big node tree: the last node will always be the node that ends up in +the parse tree. This means that the order of the various input commands or +the ordering of the files in the file list is important. + +Examples: +\begin{verbatim} +--descr=crt.xml +\end{verbatim} +will tell \fpdoc to read documentation from \file{crt.xml}, while +\begin{verbatim} +--descr=@fcl.lst +\end{verbatim} +will tell \fpdoc to read filenames from \file{fcl.lst}; each of the +filenames found in it will be added to the list of files to be scanned for +descriptions. + +%format +\subsection{format} +\label{suse:format} +Specifies the output format in which the documentation will be generated. +Currently, the following formats are known: +\begin{description} +\item[htm] Plain HTML with 8.3 conforming filenames. +\item[html] HTML with long filenames. +\item[xhtml] XHTML with long filenames. +\item[latex] LaTex, which uses the \file{fpc.sty} style used by the \fpc +documentation. +\item[xml-struct] Structured XML. +\end{description} + +% help +\subsection{help} +Gives a short copyright notice. + +% hide-protected +\subsection{hide-protected} +\label{suse:hideprotected} +By default, the documentation will include descriptions and listings of +protected fields and methods in classes or objects. This option changes this +behaviour; if it is specified, no documentation will be generated for these +methods. Note that public methods or properties that refer to these +protected methods will then have a dangling (i.e. unavailable) link. + +% html-search +\subsection{html-search} +\label{suse:htmlsearch} +This option can be used when generating HTML documentation, to specify an +url that can be used to search in the generated documentation. The URL will be +included in the header of each generated page with a \var{Search} caption. +The option is ignored for non-html output formats. + +\fpdoc does not generate a search page, this should be made by some external +tool. Only the url to such a page can be specified. + +Example: +\begin{verbatim} +--html-search=../search.html +\end{verbatim} + +% import +\subsection{import} +\label{suse:import} +Import a table of contents file, generated by \fpdoc for another package +with the \var{content} option (\seesu{content}). This option can be used +to refer to documentation nodes in documentation sets for other packages. +The argument consists of two parts: a filename, and a link prefix. + +The filename is the name of the file that will be imported. The link +prefix is a prefix that will be made to each HTML link; this needs to be +done to be able to place the files in different directories. + +Example: +\begin{verbatim} +--import=../fcl.cnt,../fcl +\end{verbatim} +This will read the file fcl.cnt in the parent directory. For HTML +documentation, all links to items in the fcl.cnt file, the link will be +prepended with \file{../fcl}. + +This allows a setup where all packages have their own subdirectory of a +common documentation directory, and all content files reside in the main +documentation directory, as e.g. in the following directory tree: +\begin{verbatim} +/docs/fcl + /fpdoc + /fpgui + /fpgfx + /fpimg +\end{verbatim} +The file fcl.cnt would reside in the \file{docs} directory. Similarly, for +each package a contents file \file{xxx.cnt} could be places in that +directory. Inside the subdirectory, commands as the above could be used to +provide links to other documentation packages. + +Note that for Latex documentation, this option is ignored. + +% input +\subsection{input} +\label{suse:input} +This option tells \fpdoc what input file should be used. The argument can +be just a filename, but can also be a complete compiler command-line with +options that concern the scanning of the Pascal source: defines, include +files, syntax options, as they would be specified to the \fpc compiler +when compiling the file. If a complete command is used, then it should be +enclosed in single or double quotes, so the shell will not break them in +parts. + +It is possible to specify multiple input commands; they will be treated one +by one, and documentation will be generated for each of the processed files. + +% lang +\subsection{lang} +\label{suse:lang} +Select the language for the generated documentation. This will change all +header names to the equivalent in the specified language. The documentation +itself will not be translated, only the captions and headers used in the +text. + +Currently, valid choices are +\begin{description} +\item[de] German. +\item[fr] French. +\item[nl] Dutch. +\end{description} + +Example: +\begin{verbatim} +--lang=de +\end{verbatim} +Will select German language for headers. + +The language files should be installed correctly for this option to work. +See the section on installing to check whether the languages are installed +correctly. + +% latex-highlight +\subsection{latex-highlight} +\label{suse:latexhighlight} +Switches on an internal latex syntax highlighter. This is not yet +implemented. By default, syntax highlighting is provided by the syntax +package that comes with \fpc. + +% output +\subsection{output} +\label{suse:output} +This option tells \fpdoc where the output file should be generated. +How this option is interpreted depends on the format that is used. +For latex, this is interpreted as the filename for the tex file. +For all other formats, this is interpreted as the directory where all +documentation files will be written. The directory will be created if +it does not yet exist. + +The filename or directory name is interpreted as relative to the current +directory. + +Example: +\begin{verbatim} +--format=html --output=docs/classes +\end{verbatim} +will generate HTML documentation in the directory \file{docs/classes}. +\begin{verbatim} +--format=latex --output=docs/classes.tex +\end{verbatim} +will generate latex documentation in the file \file{docs/classes}. + +% package +\subsection{package} +\label{suse:package} +This option specifies the name of the package to be used. The package name +will also be used as a default for the \var{output} option (\seesu{output}). + +% show-private +\subsection{show-private} +\label{suse:showprivate} +By default, no documentation is generated for private methods or fields of +classes or objects. This option causes \fpdoc to generate documentation +for these methods and fields as well. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Makeskel +\section{makeskel} +\label{se:makeskel} + +% Introduction +\subsection{introduction} +\label{suse:makeskelintro} +The makeskel tool can be used to generate an empty description file +for a unit. The description file will contain an element node for each +identifier in the interface section of the Pascal unit. + +It's usage is quite straightforward: the name of an input file +(one or more) must be specified (as for \fpdoc), an output file, +and the name of a package: +\begin{verbatim} +makeskel --package=rtl --input=crt.pp --output=crt.xml +\end{verbatim} +This will read the file \file{crt.pp} and will create a file \file{crt.xml} +which contains empty nodes for all identifiers found in \file{crt.pp}, all +in a package named \var{rtl}. + +The \var{input} option can be given more than once, as for the \file{fpdoc} +command: +\begin{verbatim} +makeskel --input='-Sn system.pp' --input=crt.pp --output=rtl.xml +\end{verbatim} +As can be seen, the \var{input} option can contain some compiler options, +as is the case for \fpdoc. The above command will process the files +\file{system.pp} and \var{crt.pp}, and will create \tag{element} tags +for the identifiers in both units in the file \var{rtl.xml}. + +The output of \file{makeskel} is a valid, empty description file. It will +contain a \tag{module} tag for each unit specified, and each \tag{module} +will have \tag{element} tags for each identifier in the unit. + +Each \tag{element} tag will by default contain \tag{short}, \tag{descr}, +\tag{errors} and \tag{seealso} tags, but this can be customised. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Makeskel +\section{Makeskel option reference} +\label{se:makeskeloption} +The output of \file{makeskel} can be customised using several options, which +are discussed below. + +% disable-arguments +\subsection{disable-arguments} +\label{suse:msdisablearguments} +By default, for each function or procedure argument, a \tag{element} tag will +be generated. This option disables this behaviour: no \tag{element} tags +will be generated for procedure and function arguments. + +% disable-errors +\subsection{disable-errors} +\label{suse:msdisableerrors} +If this option is specified, no \tag{errors} tag will be generated in the +element nodes. By default all element tags contain a \tag{errors} node. + +The \tag{errors} tag is ignored when it is not needed; Normally, an +\tag{errors} tag is only needed for procedure and function elements. + +% disable-function-results +\subsection{disable-function-results} +\label{suse:disablefunctionresults} +If this option is specified, then no \tag{element} tag will be generated for +function results. By default, \file{makeskel} will generate a result node +for each function in the interface section. The result node is used in the +documentation to document the return value of the function under a separate +heading in the documentation page. Specifying this option suppresses the +generation of the \tag{element} tag for the function result. + +% disable-private +\subsection{disable-private} +\label{suse:disableprivate} +If this option is specified, then no \tag{element} tags will be generated +for private methods or fields of classes or objects. +The default behaviour is to generate nodes for private methods or fields. +It can be used to generate a skeleton for end-user and developer +documentation. + +% disable-protected +\subsection{disable-protected} +\label{suse:disableprotected} +If this option is specified, then no \tag{element} tags will be generated +for protected and private methods or fields of classes or objects. +The default is to generate nodes for protected methods or fields. If this +option is given, the option \var{--disable-private} is implied. It can be +used to generate end-user-only documentation for classes. + + +% disable-seealso +\subsection{disable-seealso} +\label{suse:msdisableseealso} +If this option is specified, no \tag{seealso} tag will be generated in the +element nodes. By default all \tag{element} tags contain a \tag{seealso} tag. + + +% emitclassseparator +\subsection{emitclassseparator} +\label{suse:msemitclassseparator} +When this option is specified, at the beginning of the elements for the +documentation of a class, a comment tag is emitted which contains a +separator text. This can be useful to separate documentation of different +classes and make the description file more understandable. + +% help +\subsection{help} +\label{suse:mshelp} +\file{Makeskel} emits a short copyright notice and exits when this option is +specified. + +% input +\subsection{input} +\label{suse:msinput} +This option is identical in meaning and functionality as the \var{input} +option for \fpdoc. (\seesu{input}) It specifies the Pascal unit source +file that will be scanned and for which a skeleton description file will be +generated. Multiple \var{input} options can be given, and \tag{element} +tags will be written for all the files, in one big output file. + +% lang +\subsection{lang} +\label{suse:mslang} +This option is used to specify the language for messages emitted by +\file{makeskel}. The supported languages are identical to the ones +for \fpdoc: +\begin{description} +\item[de] German. +\item[fr] French. +\item[nl] Dutch. +\end{description} + +% output +\subsection{output} +\label{suse:msoutput} +This option specifies the name of the output file. A full filename must be +given, no extension will be added. If this option is omitted, the output +will be sent to standard output. + +% package +\subsection{package} +\label{suse:mspackage} +This option specifies the package name that will be used when generating the +skeleton. It is a mandatory option. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% The description file. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\chapter{The description file} +\label{ch:descriptionfile} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Introduction +\section{Introduction} +The description file is a XML document, which means that it is a kind of +HTML or SGML like format, however it is more structured than HTML, making it +easier to parse - and makes it easier to connect or merge it with a Pascal +source file. Since the allowed syntax uses a lot of HTML tags, this makes +it easy to write code for those that are familiar with writing HTML. + +More information about the XML format, SGML and HTML can be found on the +website of the W3 (World Wide Web) consortium: +\htmladdnormallink{http://www.w3.org/}{http://www.w3.org} + +The remaining of this chapter assumes a basic knowledge of tags, their +attributes and markup language, so these terms will not be explained here. + +The minimal documentation file would look something like this: +\begin{verbatim} + + + + + + + +\end{verbatim} +The header \tag{xml} tag is mandatory, and indicates that the file contains a +documentation XML document. + +Inside the document, one or more top-level \tag{fpdoc-descriptions} +tags may appear. Each of these tags can contain one or more \tag{package} +tags, which must have a \attr{name} attribute. The name attribute will be +used by fpdoc to select the documentation nodes. + +Inside a \tag{package} tag, one or more \tag{module} tags may appear. there +should be one \tag{module} tag per unit that should be documented. The value +of the \attr{name} attribute of the \var{module} should be the name of the +unit for which the \tag{module} tag contains the documentation. The value +of the \var{name} attribute is case insensitive, i.e. +\begin{verbatim} + +\end{verbatim} +can be used for the documentation of the \file{crt} unit. + +As it is above, the documentation description does not do much. To write +real documentation, the \tag{module} tag must be filled with the +documentation for each identifier that appears in the unit interface header. + +For each identifier in the unit interface header, the \tag{module} should +contain a tag that documents the identifier: this is the \tag{element} tag. +The name attribute of the element tag links the documentation to the +identifier: the \attr{name} attribute should have as value the fully +qualified name of the identifier in the unit. + +For example, to document the type +\begin{verbatim} +Type + MyEnum = (meOne,meTwo,meThree); +\end{verbatim} +an \tag{element} tag called \var{myenum} should exist: +\begin{verbatim} + + +\end{verbatim} +But also for each of the three enumerated values an \tag{element} tag should +exist: +\begin{verbatim} + + + + + + +\end{verbatim} +As it can be seen, the names of the identifiers follow a hierarchical +structure. More about this in the next section. + +Now the tags for the types are present, all that should be done is to fill +it with the actual description. For this, several tags can be placed inside +a \tag{element} tag. The most important tag is the \tag{descr} tag. The +contents of the \tag{descr} tag will be used to describe a type, function, +constant or variable: + +\begin{verbatim} + + +The MyEnum type is a simple enumeration type which is not +really useful, except for demonstration purposes. + + +\end{verbatim} + +A second important tag is the \tag{short} tag. It should contain a +short description of the identifier, preferably a description that fits on +one line. The \tag{short} tag will be used in +various overviews, at the top of a page in the HTML documentation (a +synopsis) or will be used instead of the \tag{descr} tag if that one +is not available. It can also be used in different other cases: For +instance the different values of an enumeration type will be laid +out in a table, using the \tag{short} description: +\begin{verbatim} + +The first enumeration value + + +The second enumeration value + + +The third enumeration value + +\end{verbatim} +This will be converted to a table looking more or less like this: + +\begin{tabularx}{\textwidth}{lX} +meOne & The first enumeration value \\ +meTwo & The second enumeration value \\ +meThree & The third enumeration value \\ +\end{tabularx} + +For functions and procedures, a list of possible error conditions can be +documented inside a \tag{errors} tag. This tag is equivalent to the +\tag{descr} tag, but is placed under a different heading in the generated +documentation. + +Finally, to cross-reference between related functions, types or classes, a +\tag{seealso} tag is also introduced. This will be used to lay out a series +of links to related information. This tag can only have sub-tags which are +\var{link} tags. For more about the \tag{link} tag, see \seetag{link}. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% cross-referencing +\section{Element names and cross-referencing} + +\subsection{Element name conventions} +As mentioned in the previous section, the \var{element} tag's \attr{name} +attribute is hierarchical. All levels in the hierarchy are denoted by a dot +(.) in the name attribute. + +As shown in the previous example, for an enumerated type, the various +enumeration constants can be documented by specifying their name as +\var{enumname.constname}. For example, given the type +\begin{verbatim} +Type + MyEnum = (meOne,meTwo,meThree); +\end{verbatim} +The various enumeration values can be documented using the element names +\var{MyEnum.meOne}, \var{MyEnum.meTwo} and \var{MyEnum.meThree}: +\begin{verbatim} + + + + + + +\end{verbatim} +Note that the casing of the name attribute need not be the same as the +casing of the declaration. + +This hierarchical structure can be used for all non-simple types: +\begin{itemize} +\item Enumeration type values. +\item Fields in records, objects, classes. For nested record definitions, +multiple levels are possible in the name. +\item Methods of classes and objects. +\item Properties of classes. +\item Function and procedure arguments. +\item Function results. The name is always the function name followed by +\var{Result}. +\end{itemize} + +\subsection{Cross referencing: the \var{link} tag} +To refer to another point in the documentation (a related function, class or +whatever), a \tag{link} tag exists. The \var{link} tag takes as a sole +attribute a target \attr{id} attribute. The link tag usually encloses a +piece of text. In the HTML version of the documentation, this piece of text +will function as a hyperlink. In the latex version, a page number reference +will be printed. + +The \attr{id} attribute contains the name of an element to which the link +refers. The name is not case sensitive, but it must be a fully qualified +name. + +An example of the link type would be: +\begin{verbatim} +The MyEnum type is a simple type. +\end{verbatim} + +The link attribute also has a short form: +\begin{verbatim} +The type is a simple type. +\end{verbatim} +In the short form, the value of the \attr{id} attribute will be used as the +text which will be hyperlinked. This is especially useful in the \tag{seealso} +tag. + +To refer to a type in another unit, the unit name must be prepended to the +\attr{id} attribute: +\begin{verbatim} + +\end{verbatim} +will link to the \var{myenum} type in a unit named \file{myunit}. + +To refer to a node in the documentation of another package, the package name +should be prepended to the \attr{id} attribute, and it should be prepended +with the hash symbol (\#): +\begin{verbatim} + +\end{verbatim} +will link to the constant \var{sofrombeginning} in the \file{classes} unit +of the FCL reference documentation. Note that for this to work correctly, +the contents file which was created when generating the documentation of +the type must be imported correctly (see the \var{import} option). + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Tag reference +\section{Tag reference} +\subsection{Overview} +The tags can roughly be divided in 2 groups: +\begin{enumerate} +\item Documentation structure tags. These are needed for fpdoc to do it's +work. They determine what elements are documented. See \seet{structtags} +\item Text structure and formartting tags. These tags indicate blocks of text, such as +paragraphs, tables, lists and remarks, but also specify formatting: apply formatting (make-up) +to the text, or to provide links to other parts of the text. These mostly occur in +text structure tags. See \seet{formattags} +\end{enumerate} + +\begin{table}[ht] +\caption{Documentation structure tags}\label{tab:structtags} +\begin{tabularx}{\textwidth}{lXr} +Tag & Description & Page \\ \hline +descr & Element description & \pageref{tag:descr} \\ +element & Identifier documentation & \pageref{tag:element} \\ +errors & Error section & \pageref{tag:errors} \\ +fpdoc-description & Global tag & \pageref{tag:fpdocdescription} \\ +module & Unit tag & \pageref{tag:module} \\ +package & Package global tab & \pageref{tag:package} \\ +seealso & Cross-reference section & \pageref{tag:seealso} \\ +short & Short description & \pageref{tag:short} \\ \hline +\end{tabularx} +\end{table} + +\begin{table}[ht] +\caption{Text formatting tags}\label{tab:formattags} +\begin{tabularx}{\textwidth}{lXr} +Tag & Description & Page \\ \hline +b & Format bold & \pageref{tag:b} \\ +caption & Specify table caption & \pageref{tag:caption} \\ +code & Syntax highlight code & \pageref{tag:code} \\ +dd & definition data & \pageref{tag:dd} \\ +dl & definition list & \pageref{tag:dl} \\ +dt & Definition term & \pageref{tag:dt} \\ +i & format italics & \pageref{tag:i} \\ +li & list element & \pageref{tag:li} \\ +link & Cross-reference & \pageref{tag:link} \\ +ol & numbered list & \pageref{tag:ol} \\ +p & paragraph & \pageref{tag:p} \\ +pre & Preformatted text & \pageref{tag:pre} \\ +remark & remark paragraph & \pageref{tag:remark} \\ +table & Table & \pageref{tag:table} \\ +td & Table cell & \pageref{tag:td} \\ +th & Table header & \pageref{tag:th} \\ +tr & Table row & \pageref{tag:tr} \\ +u & format underlined & \pageref{tag:u} \\ +ul & bulleted list & \pageref{tag:ul} \\ +var & format as variable & \pageref{tag:var} \\ \hline +\end{tabularx} +\end{table} + +The nodes for formatting a text resemble closely the basic HTML formatting tags with the +following exceptions: +\begin{itemize} +\item Each opening tag must have a corresponding closing tag. +\item Tags are case sensitive. +\item Tables and paragraphs are at the same level, i.e. a table cannot occur +inside a paragraph. The same is true for all 'structural' tags such as +lists, +\end{itemize} + +Also, if special formatting tags such as a table or lists are inserted, then +the remaining text must be inside a paragraph tag. This means that the +following is wrong: +\begin{verbatim} + +Some beginning text +
    +
  1. A list item
    2. +
+some ending text + +\end{verbatim} +Instead, the correct XML should be +\begin{verbatim} + +

Some beginning text

+
    +
  1. A list item
    2. +
+

some ending text

+ +\end{verbatim} + +% Tag B +\subsection{\tag{b} : format bold} +\label{tag:b} +This tag will cause the text inside it to be formatted using a bold font. + +Example: +\begin{verbatim} +Normal text Bold text normal text. +\end{verbatim} +will be formatted as:\\ +Normal text \textbf{Bold text} normal text. + +See also: \seetag{i}, \seetag{u}. + +% Tag caption +\subsection{\tag{caption} : Specify table caption} +\label{tag:caption} +This tag can occur inside a \tag{table} tag and serves to set the table +caption. + +Example +\begin{verbatim} + + + +
This caption will end up above the table
Column 1Column 2
+\end{verbatim} + +See also: \seetag{table} + +% Tag code +\subsection{\tag{code} : format as pascal code} +\label{tag:code} +The \tag{code} tag serves to insert Pascal code into the text. When possible +this code will be highlighted in the output. It can be used to put +highlighted Pascal code in the documentation of some identifier. It can +occur inside \tag{descr} or \tag{errors} tags. + +Note that any text surrounding the \tag{code} tag should be placed in +paragraph tags \tag{p}. + +Example: +\begin{verbatim} + +With Strings do + For i:=Count-1 downto 0 do + Delete(i); + +\end{verbatim} + +Seealso: \seetag{pre}, \seetag{p} + +% Tag descr +\subsection{\tag{descr} : Descriptions} +\label{tag:descr} +This is the actual documentation tag. The contents of this tag will be +written as the documentation of the element. It can contain any mixture of +text and markup tags. The \tag{descr} tag can only occur inside a +\tag{element} or \tag{module}. + +Example: +\begin{verbatim} + +Myenum is a simple enumeration type + +\end{verbatim} + +See also: \seetag{element}, \seetag{short}, \seetag{errors}, \seetag{seealso} + +% Tag dd +\subsection{\tag{dd} : definition data.} +\label{tag:dd} +The \tag{dd} tag is used to denote the definition of a term in a definition +list. It can occur only inside a definition list tag (\tag{dl}), after a +definition term (\tag{dt}) tag. It's usage is identical to the one in HTML. + +Example: +\begin{verbatim} +
+
FPC
stands for Free Pascal Compiler.
+
+\end{verbatim} +Will be typeset as +\begin{description} +\item[FPC] stands for Free Pascal Compiler. +\end{description} + +See also: \seetag{dl}, \seetag{dt}, \seetag{ol}, \seetag{ul} + +% Tag dl +\subsection{\tag{dl} : definition list.} +\label{tag:dl} +Definition lists are meant to type a set of terms together with their +explanation. It's usage is identical to the one in HTML, with the exception +that it cannot occur inside ordinary text: surrounding text should always be +enclosed in paragraph tags. + +Example: +\begin{verbatim} +
+
meOne
First element of the enumeration type.
+
meTwo
Second element of the enumeration type.
+
meThree
Thir element of the enumeration type.
+
+\end{verbatim} +Will be typeset as +\begin{description} +\item[meOne] First element of the enumeration type. +\item[meTwo] Second element of the enumeration type. +\item[meThree] Third element of the enumeration type. +\end{description} + +See also: \seetag{dt}, \seetag{dd}, \seetag{ol}, \seetag{ul} + +% Tag dt +\subsection{\tag{dt} : definition term.} +\label{tag:dt} +The \tag{dt} tag is used in definition lists to enclose the term for which a +definition is presented. It's usage is identical to the usage in HTML. + +Example: +\begin{verbatim} +
+
FPC
stands for Free Pascal Compiler.
+
+\end{verbatim} +Will be typeset as +\begin{description} +\item[FPC] stands for Free Pascal Compiler. +\end{description} + +See also: \seetag{dl}, \seetag{dd}, \seetag{ol}, \seetag{ul} + + +% Tag element +\subsection{\tag{element} : Identifier documentation} +\label{tag:element} +The \tag{element} contains the documentation for an identifier in a unit. It +should occur inside a \var{module} tag. It can contain 4 tags: +\begin{description} +\item[short] For a one-line description of the identifier. Is used as a +header or is used in overviews of constants, types, variables or classes. +\item[descr] Contains the actual description of the identifier. +\item[errors] For functions an procedures this can be used to describe error +conditions. It will be put in a separate section below the description +section. +\item[seealso] Used to refer to other nodes. will be typeset in a separate +section. +\end{description} + +The \tag{element} tag should have at least the \attr{name} attribute, it +is used to link the element node to the actual identifier in the Pascal unit. +Other attributes may be added in future. + +Example: +\begin{verbatim} + +Myenum is a simple enumeration type + +\end{verbatim} + +See also: \seetag{descr}, \seetag{short}, \seetag{errors}, \seetag{seealso} + +% Tag errors +\subsection{\tag{errors} : Error section.} +\label{tag:errors} +The \tag{errors} tag is used to document any errors that can occur when +calling a function or procedure. it is placed in a different section in the +generated documentation. It occurs inside a \tag{element} tag, at the same +level as a \tag{descr} or \tag{short} tag. It's contents can be any +text or formatting tag. + +Example: +\begin{verbatim} + +MyDangerousFunction is a dangerous function +When MyDangerousFunction fails, all is lost + +\end{verbatim} + +See also: \seetag{descr}, \seetag{short}, \seetag{element}, \seetag{seealso} + +% Tag fpdoc-description +\subsection{\tag{fpdoc-description} : Global tag} +\label{tag:fpdocdescription} +The \tag{fpdoc-description} tag is the topmost tag in a description file. It +contains a series of \tag{package} tags, one for each package that is +described in the file. + +See also: \seetag{package} + +% Tag i +\subsection{\tag{i} : Format italics} +\label{tag:i} +The \tag{i} tag will cause its contents to be typeset in italics. It can +occur mixed with any text. + +Example: +\begin{verbatim} +Normal text italic text normal text. +\end{verbatim} +will be formatted as:\\ +Normal text \textit{italic text} normal text. + +See also: \seetag{b}, \seetag{u} + +% Tag li +\subsection{\tag{li} : list element} +\label{tag:li} +The tag \tag{li} denotes an element in a \tag{ol} or \tag{ul} list. +The usage is the same as for it's HTML counterpart: It can occur +only inside one of the \tag{ol} or \tag{ul} list tags. +It's contents may be arbitrary text and formatting tags, contrary to HTML +tags, the \tag{li} tag always must have a closing tag. Note that it cannot be used in a +definition list (\seetag{dl}). + +Example: +\begin{verbatim} +
    +
  • First item in the list
    • +
  • Second item in the list
    • +
+\end{verbatim} +Will be typeset as +\begin{itemize} +\item First item in the list. +\item Second item in the list. +\end{itemize} + +See also: \seetag{ol}, \seetag{ul}. + +% Tag link +\subsection{\tag{link} : Cross-reference} +\label{tag:link} +The \tag{link} tag is used to insert a reference to an element inside some +piece of text or inside the \tag{seealso} section. It is similar in +functionality to the +\begin{verbatim} +some linked text +\end{verbatim} +construct in HTML. + +The mandatory \attr{id} attribute of the \tag{link} tag should have the +name of an element tag in it. This name is not case sensitive. \fpdoc +will issue a warning if it cannot find a matching name. It will look for +matching names in the current file, and in all content files that have been +specified with the \var{import} command-line option. + +The link tag can exist in 2 forms: one with separate closing tag, +surrounding a piece of text, one without separate closing tag. If a piece of +text is surrounded by the link tag, then the text will be converted to a +hyperlink in the HTML documentation. If there is no surrounded text, then +the value of the \attr{id} attribute will be used as the text. This means +that +\begin{verbatim} +TStream +\end{verbatim} +and +\begin{verbatim} + +\end{verbatim} +are completely equivalent. + +Example: +\begin{verbatim} +The stringlist class is a descendent of the + class. +\end{verbatim} + +See also: \seetag{element}, the \var{import} option (\seesu{import}). + +% Tag module +\subsection{\tag{module} : Unit reference} +\label{tag:module} +The \tag{module} tag encloses all \tag{element} tags for a unit. It can +contain only \tag{element} tags for all identifiers in the unit and +a \tag{descr} tag describing the unit itself. The \tag{module} tag should +occur inside a \tag{package} tag. + +The \attr{name} attribute should have as a value the name of the unit which +is described by the module. This name is not case sensitive. + +Example: +\begin{verbatim} + + +The classes unit contains basic class definitions for the FCL. + + +\end{verbatim} + +See also: \seetag{package}, \seetag{descr}, \seetag{element} + +% Tag ol +\subsection{\tag{ol} : Numbered list.} +\label{tag:ol} +The \tag{ol} tag starts a numbered list. It can contain only \seetag{li} +tags, which denote the various elements in the list. Each item will be +preceded by a number. The \tag{ol} tag can +occur inside a text, but surrounding text should always be enclosed in a +\seetag{p} paragraph tag, i.e. an \tag{ol} tag should occur always at the +same level as a \tag{p} tag. + +Example: +\begin{verbatim} +

some text before

+
    +
  1. First item in the list
    2. +
  2. Second item in the list
    3. +
+\end{verbatim} +Will be typeset as: + +some text before +\begin{enumerate} +\item First item in the list. +\item Second item in the list. +\end{enumerate} + +See also: \seetag{li}, \seetag{ul}. + + +% Tag paragraph +\subsection{\tag{p} : Paragraph} +\label{tag:p} +The \tag{p} tag is the paragraph tag. Every description text should be +enclosed in a \tag{p} tag. Only when there is only one paragraph (and no +lists or tables or remarks) in a description node, then the \tag{p} tag may +be skipped. + +Note that if a description node contains a \tag{table}, \tag{pre}, \tag{code} +or any list tag, then the text surrounding these tags {\em must} be put +inside a \tag{p} paragraph tag. This is different from the behaviour in HTML. + +The paragraph tag must always have an opening tag and a closing tag, unlike +html where only the opening tag may be present. + +Example: +\begin{verbatim} + +This is a paragraph which need not be surrounded by paragraph tags. + +\end{verbatim} +\begin{verbatim} + +

+This is the first paragraph. +

+

+This is the second paragraph. +

+ +\end{verbatim} + +See also: \seetag{table}, \seetag{dl}, \seetag{remark},\seetag{code}, +\seetag{ol},\seetag{ul},\seetag{ol} + +% Tag package +\subsection{\tag{package} : Package reference} +\label{tag:package} +The \tag{package} tag indicates the package for which the description file +contains documentation. A package is a collection of units which are +logically grouped together (for a library, program, component suites). The +\attr{name} attribute of the \tag{package} tag will be used to select the +package node in the description file: Only the \tag{package} node with name as +specified by the \var{package} command-line option will be used when +generating documentation. All other package nodes will be ignored. + +The \tag{package} node must always reside in a \tag{fpdoc-description} node. +It can contain a \tag{descr} node, and various \tag{module} nodes, one node +per unit in the package. + +See also: \seetag{fpdocdescription}, \seetag{module}, \seetag{descr} + +% Tag pre +\subsection{\tag{pre} : Insert text as-is} +\label{tag:pre} +The \tag{pre} tag can be used to insert arbitrary text in the documentation. +The text will not be formatted in any way, and will be displayed as it is +encountered in the description node. It is functionally equivalent to the +\tag{pre} tag in HTML. + +Note that if there is text surrounding the \tag{pre} tag, it should be placed +inside a \tag{p} paragraph tag. + +Example: +\begin{verbatim} +
+This is some text.
+  This is some more text
+
+    And yet more text...
+
+\end{verbatim} +This will be typeset as: +\begin{verbatim} +This is some text. + This is some more text + + And yet more text... +\end{verbatim} + +See also: \seetag{code}, \seetag{p} + +% Tag remark +\subsection{\tag{remark} : format as remark} +\label{tag:remark} +A \tag{remark} tag can be used to make a paragraph stand out. The +\tag{remark} is equivalent to the \tag{p} tag, but it's contents is +formatted in a way that makes it stand out from the rest of the text. + +Note that any text before or after the \tag{remark} tag must be enclosed in +paragraph (\tag{p}) tags. + +Example: +\begin{verbatim} +

Normal text.

+ +This text will stand out. + +

Again normal text.

+\end{verbatim} +Will be formatted as + +Normal text. +\begin{remark} +This text will stand out. +\end{remark} +Again normal text. + +See also: \seetag{p}, \seetag{code}, \seetag{pre} + +% Tag seealso +\subsection{\tag{seealso} : Cross-reference section} +\label{tag:seealso} +The \tag{seealso} section can occur inside any \tag{element} tag, and will +be used to create a list of cross-references. The contents of the +\tag{seealso} tag is a list of \tag{link} tags. No other text is allowed +inside this tag. Note that both the long and short form if the link tag may +be used. + +Example: +\begin{verbatim} + + +Create + +\end{verbatim} + +See also: \seetag{link}, \seetag{element} + +% Tag short +\subsection{\tag{short} : Short description} +\label{tag:short} +The \var{short} description is used to give a short description of an +identifier. If possible, the description should fit on a single line of +text. The contents of this tag will be used for the following purposes: +\begin{itemize} +\item Used as the synopsis on a page that describes an identifier. +\item Used in overviews of constants, types, variables, record fields, +functions and procedures, classes, and for method and property listings of classes. +\item Replaces the \tag{descr} tag in an \tag{element} if no \tag{descr} tag is present. +\item In the description of an enumerated type, the enumeration values are +typeset in a table, each row containing the name of the value and the short +description. +\item In the description of a function or procedure that accepts arguments, +the arguments are followed by their short description. +\item In the declaration of a class or record, each method, field or property +is followed by the short description. +\end{itemize} + +Example: +\begin{verbatim} + +First element of MyEnum + +\end{verbatim} + +See also: \seetag{element}, \seetag{descr} + +% Tag table +\subsection{\tag{table} : Table start} +\label{tag:table} +The \var{table} tag starts a table, as in HTML. A table can contain +\tag{tr} (table row), \tag{th} (table header row) or \tag{caption} tags. +Any text surrounding the table must be enclosed in paragraph tags (\tag{p}). + +Example: +\begin{verbatim} + + + + + + + + + + + + + + + +
+TALignment values and their meanings. +
ValueMeaning
taLeftJustifyText is displayed aligned to the left.
taRightJustifyText is displayed aligned to the right
taCenterText is displayed centred.
+\end{verbatim} +Will be formatted approximately as follows: + +\begin{tabularx}{\textwidth}{lX} +Value & Meaning \\ \hline +\var{taLeftJustify} & Text is displayed aligned to the left. \\ +\var{taRightJustify} & Text is displayed aligned to the right \\ +\var{taCenter} & Text is displayed centred. +\end{tabularx} + +See also: \seetag{th}, \seetag{caption}, \seetag{tr}, \seetag{p} + +% Tag td +\subsection{\tag{td} : Table cell} +\label{tag:td} +The \tag{td} tag is used to denote one cell in a table. It occurs +inside a \tag{tr} or \tag{th} tag, and can contain any text and formatting +tags. + +Example: +\begin{verbatim} + + + +
Cell (1,1)Cell (2,1)
Cell (1,2)Cell (2,2)
+\end{verbatim} +Will be formatted approximately as + +\begin{tabular}{ll} +Cell (1,1) & Cell (2,1) \\ +Cell (1,2) & Cell (2,2) +\end{tabular} + +See also: \seetag{table}, \seetag{th}, \seetag{tr} + +% Tag th +\subsection{\tag{th} : Table header} +\label{tag:th} +The \var{th} table header tag is used to denote the first row(s) of a table: +It (they) will be made up differently from the other rows in the table. +Exactly how it is made up depends on the format. In printed documentation +(latex) a line will be drawn under the row. In HTML, the font and background +may be formatted differently. + +The \tag{th} tag can only occur inside a \tag{table} tag, and can contain +only \tag{td} tags. + +Example: +\begin{verbatim} + + + +
Cell (1,1)Cell (2,1)
Cell (1,2)Cell (2,2)
+\end{verbatim} +Will be formatted approximately as + +\begin{tabular}{ll} +Cell (1,1) & Cell (2,1) \\ \hline +Cell (1,2) & Cell (2,2) +\end{tabular} + +See also: \seetag{tr}, \seetag{table} + +% Tag tr +\subsection{\tag{tr} : table row} +\label{tag:tr} +The \tag{tr} tag denotes a row in a table. It works the same as in HTML. +It can occur only in a \tag{table} tag, and should contain only \tag{td} +table data tags. + +Example: +\begin{verbatim} + + + +
Cell (1,1)Cell (2,1)
Cell (1,2)Cell (2,2)
+\end{verbatim} +Will be formatted approximately as + +\begin{tabular}{ll} +Cell (1,1) & Cell (2,1) \\ +Cell (1,2) & Cell (2,2) +\end{tabular} + +See also: \seetag{table}, \seetag{th}, \seetag{td} + +% Tag u +\subsection{\tag{u} : Format underlined} +\label{tag:u} + +Example: +\begin{verbatim} +Normal text underlined text normal text. +\end{verbatim} +will be formatted as:\\ +Normal text \underline{underlined text} normal text. + +See also: \seetag{i}, \seetag{b}. + +% Tag ul +\subsection{\tag{ul} : bulleted list} +\label{tag:ul} +The \var{ul} tag starts a bulleted list. This works as under HTML, with the +exception that any text surrounding the list must be enclosed in paragraph +tags (\tag{p}). The list elements should be enclosed in \tag{li} tags. + +Example: +\begin{verbatim} +

some text before

+
    +
  1. First item in the list
    2. +
  2. Second item in the list
    3. +
+\end{verbatim} +Will be typeset as: + +some text before +\begin{itemize} +\item First item in the list. +\item Second item in the list. +\end{itemize} + +See also: \seetag{li}, \seetag{ol}. + +% Tag var +\subsection{\tag{var} : variable} +\label{tag:var} +The \tag{var} tag is used to mark a piece of text as a variable (or, more +general, as an identifier). It will be typeset differently from the +surrounding text. Exactly how this is done depends on the output format. + +Example: +\begin{verbatim} +The Items property gives indexed access to... +\end{verbatim} +Will be typeset as + +The \var{Items} property gives indexed access to... + +See also: \seetag{b}, \seetag{u}, \seetag{i}, \seetag{code} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Generated output files. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\chapter{Generated output files.} +\label{ch:outputfiles} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% HTML output +\section{HTML output} +The HTML output consists of the following files, per unit: + +\begin{enumerate} +\item A general unit description with the contents of the module's + \tag{descr} tag. The \var{uses} clause is documented here as well. +All units in the \var{uses} clause together with their \tag{short} + description tags are typeset in a table. +\item A listing of all constants in the unit. +\item A listing of all types in the unit (except classes). +\item A listing of all variables in the unit. +\item A listing of all functions/procedures in the unit. +\item A listing of all classes in the unit. +\end{enumerate} +All these overviews are hyperlinked to pages which contain the documentation +of each identifier. Each page starts with the name of the identifier, +plus a synopsis (made from the \tag{short} tag's contents). After that +follows the declaration, and the description. The description is filled with +the \tag{descr} node of the identifiers \tag{element} tag. + +If an \var{errors} tag was present, an 'Errors' section follows the +description. Similarly, if there is a \tag{seealso} tag, a 'See also' +section with cross-reference links is made. + +For classes, the declaration contains hyperlinks to separate pages which +document all the members of the class. Each member in the declaration is +followed by the \tag{short} tag of the member's \tag{element} tag, if one +exists. As an extra, the class hierarchy is given, plus links to pop-up pages +(if JavaScript is available, otherwise they are normal links) which contain +alphabetical or hierarchical listings of the methods, fields or properties +of the class. + +For functions and procedures, the declaration will be typeset in such a way +that all function arguments (if they are present) are in tabular format, +followed by the short description of the argument. If it concerns a +function, and a result element exists, the result description will be +provided in a separate section, before the actual description. + +The declaration of an enumerated type will be laid out in a table, with the +enumeration value at the left, and the short description node of the value's +element. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Latex output +\section{Latex output} + +The latex output is in one big file with the name of the package as +specified on the command line. in this file, one chapter is made per +unit. + +Per unit the following sections are made: + +\begin{enumerate} +\item A section with all constants. +\item A section with all types. +\item A section with all variables. +\item A section with all functions and procedures. +\item A section per declared class. +\end{enumerate} + +For the constants, types and variables, the declaration is given, followed +by the \tag{descr} node of the element corresponding to the identifier. +All other nodes are ignored. + +For functions and procedures, a subsection is made per procedure or +function. This subsection consists of a list with the following entries: +\begin{description} +\item[Synopsis] filled with the contents of the \tag{short} tag. +\item[Declaration] Filled with the declaration of the function. +\item[Arguments] A tabular description of all arguments, if \tag{short} tags +are found for them. +\item[Description] Description of the function. Filled with the contents of +the \tag{descr} tag. +\item[Errors] Description of any error conditions. Filled with the contents +of the \tag{errors} tag. +\item[See Also] Cross-references to other functions. Filled with the +contents of the \tag{seealso} tag. +\end{description} + +For classes, a subsection is made with an overview of implemented methods. +Then a subsection is presented with available properties. + +Then follows a subsection per method. These are formatted as a function, with an +additional \textbf{Visibility} list element, giving the visibility of the +function. + +After the methods, a list of properties is given , formatted as a method, +with an additional \var{Access} list element, specifying whether the +property is read/write or not. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% End of file +\end{document} \ No newline at end of file