GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing pasdoc.github.io — Introduction, Conclusion Files and Additional Files

Introduction, Conclusion Files and Additional Files

Table of Contents

1. Introduction
2. Simple example
3. Format of introduction/conclusion files
4. Special tags
5. More examples

1. Introduction

You can provide extra documentation files to be included in your documentation, like an introduction and a conclusion. This is useful if you want to have some general information about your codebase, not related to any particular item in the code.

Use these CommandLine options:

--introduction=FILE-NAME
--conclusion=FILE-NAME
--additional=FILE-NAME (use this as many time as you need, to add any number of additional files). Short form: -A.

2. 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).

3. 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 Writing Documentation 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)

4. 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 the HTML output format HeadingLevel = 1 results in <h2>Section title</h2>, HeadingLevel = 2 results in <h3>Section title</h3> etc.
- In the LaTeX output format 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 @link tag. 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.

5. More examples

See the test introduction file.
See also PasDocAutoDoc — there’s an "Overview" page included, and it was generated using --introduction command-line option.

PasDoc

Download

Features:

Supported Tags:

Command Line:

Development:

Developers pages:

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.