Doxer - Software documentation system
Tim Janik
Document revised: Tue Jan 31 01:51:22 2006
GNU General Public License version 2 or (at your option) any later version.

Table of Contents
1 · Introduction
2 · Overall Laoyut
3 · Markup Macros
4 · Structure Macros
5 · Other Macros
6 · Markup Tests

1 Introduction

Doxer is a software documentation system. That means it can parse source code files, such as .c, .h, .cc and .hh files, and extract documentation from C and C++ source code.

Also, doxer supports an '@'-escape based markup sytsem which allowes for definition of custom markup macros and aliases, based on the set of standard macros supplied with doxer.

2 Overall Laoyut

Doxer first parses the raw input text (usually .doxi files) and identifies and expands macros. Then it identifies structural macro definitions (e.g. lists and tables) and sections. After that, automcatic line breaks are generated, and sections are post-process to allow numbering and TOC (table of content) generation.

Sections are usually hierarchically structured. However for canvas based layouts, groups can be assigned to sections, which directly manipulates the resulting layout area within a predetermined layout mask a section ends up in. Groups are supported by the HtmlGenerator backend.

The possible groups supported in section definitions are:

@section0{group=header} HEADER
@section0{group=lheader} LEFT HEADER
@section0{group=cheader} CONTENT HEADER
@section0{group=rheader} RIGHT HEADER
@section0{group=left} LEFT
@section0{group=content} CONTENT (default)
@section0{group=right} RIGHT
@section0{group=lfooter} LEFT FOOTER
@section0{group=cfooter} CONTENT FOOTER
@section0{group=rfooter} RIGHT FOOTER
@section0{group=footer} FOOTER

And are arranged in the predetermined layout mask as follows:

+----------------------------------------------+
|                    HEADER                    |
+--------------+----------------+--------------+
| LEFT  HEADER | CONTENT HEADER | RIGHT HEADER |
+--------------+----------------+--------------+
|              |                |              |
|     LEFT     |    CONTENT     |    RIGHT     |
|              |   (default)    |              |
|              |                |              |
+--------------+----------------+--------------+
| LEFT  FOOTER | CONTENT FOOTER | RIGHT FOOTER |
+--------------+----------------+--------------+
|                    FOOTER                    |
+----------------------------------------------+

3 Markup Macros

@doxer_bold{TEXT}
Display TEXT with a bold font. Example script in bold font.
@doxer_italic{TEXT}
Display TEXT with an italic font. Example script in italic font.
@doxer_underline{TEXT}
Display TEXT in an underlined style. Example script in underlined style.
@doxer_strikethrough{TEXT}
Display TEXT in a strikethrough style. ~~Example script in strikethrough style.~~
@doxer_subscript{TEXT}
Display TEXT with a subscript font. _{Example script in subscript font.}
@doxer_superscript{TEXT}
Display TEXT with a superscript font. ^{Example script in superscript font.}
@doxer_monospace{TEXT}
Display TEXT in monospaced manner. Example script in monospaced manner.

4 Structure Macros

@enumerate
Starts an enumeration list, opens a scope.
@itemize
Starts an itemized list, opens a scope.
@item
Marks a bullet point of an list.
@table
Starts a table, opens a scope.
@row
Startd an table row, opens a scope.
@cell
Marks a column cell inside a table row.
@done
Ends the innermost scope

5 Other Macros

@doxer_newline{}
Force a line break in the output.
@doxer_line{} LINE-NUMBER '"' FILENAME '"' '\n'
Source file/line adjustment directive.
@doxer_alias{ALIAS-NAME} SUBSTITUTION-TEXT '\n'
Define ALIAS-NAME as a shorthand for SUBSTITUTION-TEXT, leading spaces are ignored.
@include{} '"' FILENAME '"' '\n'
@include{} '<' FILENAME '>' '\n'
Temporarily suspend the current parsing context and parse FILENAME.
@doxer_dnl{} DUMMYTEXT '\n'
Commentary mechanism, the macros, DUMMYTEXT and newline are ignored.
@doxer_args{ARG-REFERENCE}
A macro used in command definitions as a place holder for command arguments. Arguments are referenced by their positional numbers, argument 0 is the command name. Argument ranges, delimited by ':' are supported. '*' can be used as a place holder for all arguments except argument 0. 'line' can be used to refer to the text parsed after the macro braces up to the first newline. 'content' can be used to refer to the text body, enclosed by a macro and it's respective @done directive. 'all' can be used to refer to the combination of '*', 'line' and 'content'.
@doxer_set{VARIABLE [, FLAGS]} VALUE-TEXT '\n'
Set the value of VARIABLE to VALUE-TEXT. Possible FLAGS are:
'parse_date' - to interpret VALUE-TEXT as an ISO-8601 compliant date string or some variants thereof;
'unstripped' - to avoid stripping space off of VALUE-TEXT before assigning VARIABLE.
@doxer_add{VARIABLE [, FLAGS]} VALUE-TEXT '\n'
A variant of @doxer_set{}, that adds VALUE-TEXT to the list variable VARIABLE.
@doxer_get{VARIABLE}
Replaces the macro occourance with the value of VARIABLE.

6 Markup Tests

Different types of keys: F1 F2 F3 F4 Shift+A Shift+A Ctrl+Shift+Del Alt+SysReq Esc
Menu paths, /-seperated: -> Top -> FirstLevel -> Leaf Item
Menu: -> File -> Save As...
Menu: -> Help -> Online Help Desk...
Type names: BseProject GtkWidget guint void imaginative-type
GUI Properties: "Visible" "Auto Activate"
Identifiers: visible auto-activate
@uri{http://www.gtk.org}: http://www.gtk.org
@uri{http://www.gtk.org, The Gtk+ Website}: The Gtk+ Website
@longuri{http://www.gtk.org}: http://www.gtk.org (http://www.gtk.org)
@longuri{http://www.gtk.org, The Gtk+ Website}: The Gtk+ Website (http://www.gtk.org)
HTML-Validator
CSS-Validator
Link-Validator
This Page As PlainText