Introduction and Conclusion Files

You can use the CommandLine options --introduction=FILE-NAME and --conclusion=FILE-NAME to add additional special pages to your documentation.

Since PasDoc 0.16.0 you can also use option --additional=FILE-NAME to provide any number of additional files. Option --additional can be shortened to -A.

Simple example

Create a file named introduction.txt with contents like

@shorttitle(Intro)
@title(General introduction to my source code)

Some text describing your source code.

Then call pasdoc like this

pasdoc --introduction=introduction.txt ...

In HTML output you will get an additional page introduction.html in your documentation, with contents based on the introduction.txt file. On the navigation frame you will have a link "Intro" to this page. In LaTeX output the introduction will be added as the first chapter of the documentation (conclusion will be added as the last chapter).

Format of introduction/conclusion files

The text inside the introduction/conclusion files is treated very much like normal pasdoc descriptions. This means that all rules explained in WritingDocumentation apply here too: @-tags are allowed, you must write @@ to get single @ character, URLs are automatically turned into links, an empty line starts a new paragraph etc.

In particular, you can use the @link tag to link from introduction/conclusion to other items in your documentation. Also, you can create links to the introduction/conclusion by specifying the introduction/conclusion filename (without extension) as the link target, e.g.

@link(introduction)

Special tags

Some special @-tags are allowed only in introduction/conclusion files:

@shortTitle(my short title)

Specify a short title of the introduction/conclusion. In HTML output, the my short title is shown in the navigation frame to link to the introduction and conclusion. In LaTeX output, this tag is ignored.

@title(my title)

Specify the title of introduction/conclusion. In HTML output, the argument is the top level heading at the beginning of the page for the introduction and conclusion. In LaTeX output, the argument is the chapter’s title.

@section(HeadingLevel AnchorName Section title)

Start a new section. The @section tag contains:

  • HeadingLevel: a number used to indicate section nesting. It must be an integer >= 1. E.g. in HtmlOutput HeadingLevel = 1 results in <h2>Section title</h2>, HeadingLevel = 2 results in <h3>Section title</h3> etc. In LatexOutput HeadingLevel = 1 results in \section{Section title} , HeadingLevel = 2 results in \subsection{Section title} etc.

  • AnchorName: used to link to a given section (from the introduction/conclusion files or a Pascal items descriptions) using a LinkTag_. Allowed AnchorNames are valid Pascal identifiers (first character is an underscore or a letter, followed by any combination of letters, digits and underscores).

  • Section title: title shown in the documentation.

@anchor(AnchorName)

Set up an anchor at this place. The anchor name must be a valid Pascal identifier. Anchors are not visible in the generated documentation, but you can link to them with a @link tag

@tableOfContents

Insert table of contents here.

More examples