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

Contents

Simple example
Format of introduction/conclusion files
Special tags
More examples

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: In HTML output, the argument is the text used in navigation frame to link to the introduction and conclusion. In LaTeX output, this tag is ignored.
@title: This is 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): This starts a new section.
- HeadingLevel is 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 may be 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 is, well, the section title, that will be shown to the reader of the generated documentation.
@anchor(AnchorName): This sets 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 LinkTag.
@tableOfContents: inserts table of contents into introduction or conclusion

More examples

See the test unit of this feature and the accompanying test introduction file and the HTML output of this test unit and introduction.
See also PasDocAutoDoc – there's an "Overview" page included, and it was generated using --introduction command-line option.