This document was created using APHID-DocBook

APHID User Manual

version 0.7


Table of Contents

1. Abstract
2. What is APHID?
3. Installing APHID
3.1. Windows
3.1.1. System Requirements
3.1.2. Installation
3.1.3. Updating APHID
3.1.4. Uninstalling APHID
3.2. UNIX (Linux)
3.2.1. System Requirements
3.2.2. Installation
3.2.3. Updating APHID
3.2.4. Uninstalling APHID
3.3. The APHID Directory Structure
4. Using APHID
4.1. Converting TEXT Documents to DocBook/XML
4.2. Converting TEXT Documents to Other Formats
4.3. Command Options
4.4. Converting DocBook/XML Documents to Other Formats
4.5. Configuration files
4.5.1. Windows
4.5.2. UNIX
5. The APT format
5.1. Document structure
5.2. Document elements
5.2.1. Block level elements
5.2.2. Text level elements
5.3. An Example APT formatted document
6. Changes
6.1. Version 0.7
6.2. Version 0.6
7. To Do
7.1. General
7.2. Text Documents
7.3. DocBook Documents
7.4. HTML Documents
7.5. HTML Help Documents
7.6. PDF Documents

1. Abstract

APHID (Ant-driven Platform-independent Hodge-podge for Issuing DocBook) is an easy-to-install and easy-to-use DocBook environment. With APHID, you can start working with DocBook XML documents right away. Create articles and books and transform them from one single source to multiple output formats like HTML, HTML Help, or PDF. No in-depth knowledge of DocBook, XML, XSL, HTML or CSS is required. APHID is a derivative work of eDE (http://www.e-novative.de).

2. What is APHID?

With APHID, you can transform text and DocBook XML documents from a single source document (or multiple source documents) to various output formats, including a single HTML file, a multiple of HTML files, and PDF. The well-documented parameterization and customization of the original DocBook XSL stylesheets make understanding DocBook and working customizing it to your personal needs really simple. APHID allows you to customize general, document-type, and document-specific settings and stylesheets. The command-line interface and ANT-driven framework allow for easy automation of document generation.

APHID is released under the GNU General Public License (GPL). For detailed information about the license terms, see the file COPYING located in the directory where you installed APHID.

Comments and suggestions for improving APHID are most welcome.

3.  Installing APHID

3.1. Windows

3.1.1. System Requirements

  1. A Windows NT-based operating system (Windows NT, Windows 2000, Windows XP, Windows 2003, etc.). APHID does not run on Windows 95, Windows 98, and Windows ME.

  2. About 45 MB free hard disk space on your hard drive. APHID can be installed to any hard drive.

  3. An installed Java Runtime Environment (JRE) or Java Software Development Kit (JSDK), version 1.4 or greater.

3.1.2. Installation

To install APHID:

  1. Unzip the contents of the ZIP file to a folder of your choice.

  2. Open a command window (RUN CMD).

  3. If your environment does not have JAVA_HOME defined, edit the initialization script (APHID.CMD). Uncomment and edit the line that defines JAVA_HOME.

  4. Run the initialization script (APHID.CMD)

  5. You're done unless you want to provide a customized system-wide configuration to APHID users.

    In this case, use a text editor to create a file containing aptconvert properties (more about this in the Using APHID section). For example, create a file called \path\to\aphid\custom_configuration.bat.

  6. Start generating documents.

There are several ways that you can set up your APHID environment. The top-level directory of APHID contains a file named aphid.cmd. The simplest way to use APHID is to run the script from inside a command window. For example:

CMD /K \path\to\aphid\APHID.CMD

This will initialize the necessary environment variables and modify the titlebar of the window. The script has been designed so that it can be invoked from anywhere. It is not necessary to be in the script directory when you run aphid.cmd. Once the script has been run, simply change directory to where you want to create/transform your documents and start working. When you are finished, just type exit in the command window.

A second option is to setup the environment variables manually. To to this, you must define APHID_HOME, ANT_HOME, and ANT_OPTS. Additionally, the PATH environment variable must be modified to begin with: %APHID_HOME%\bat and %ANT_HOME%\bin.

3.1.3. Updating APHID

Updating APHID is as simple as installing it. Simply unzip the contents of the ZIP file into the folder where you previously installed APHID. Provided you have followed the instructions about creating your own custom configurations, all of your customizations will continue to work.

Optionally, you can install multiple versions of APHID into different locations. You need to make sure, however, that your environment variables are setup to invoke the correct installation of APHID.

The only reason to maintain multiple versions of APHID would be to continue to process old documents in the event that I introduce a backward-incompatible change into APHID, or if you need to continue to process older versions of docbook documents once they are deprecated. Both of these issues should be rare.

3.1.4. Uninstalling APHID

To uninstall APHID, simply delete the directory where you installed APHID. If you manually setup your environment, remove the APHID_HOME, ANT_HOME, and ANT_OPTS environment variables, and remove %APHID_HOME%\bat and %ANT_HOME%\bin from your PATH.

3.2. UNIX (Linux)

3.2.1. System Requirements

  1. About 45 MB free hard disk space on your file system. APHID can be installed anywhere file system. If you wish to install aphid to a location accessible by multiple users (such as /usr/local/aphid, for example) you will need the approriate privileges to create the directory, etc.

  2. An installed Java Runtime Environment (JRE) or Java Software Development Kit (JSDK), version 1.4 or greater.

3.2.2. Installation

To install APHID:

  1. Unzip the contents of the ZIP file to a directory of your choice.

  2. If your environment does not have JAVA_HOME defined, edit the initialization script (aphid.sh). Uncomment and edit the line that defines JAVA_HOME.

  3. Source the initialization script (aphid.sh)

  4. You're done unless you want to provide a customized system-wide configuration to APHID users.

    In this case, use a text editor to create a file containing aptconvert properties (more about this in the Using APHID section). For example, create a file called /path/to/aphid/custom_configuration.

  5. Start generating documents.

There are several ways that you can set up your APHID environment. The top-level directory of APHID contains a file named aphid.sh. The most simple way to use APHID is to cd to the directory where APHID is installed and source the script. For example:

cd /path/to/aphid
source aphid.sh
   or
. aphid.sh

This will initialize the necessary environment variables. The script has been designed so that it can be invoked from anywhere. It is necessary to be in the script directory when you source aphid.sh. Once the script has been run, simply change directory to where you want to create/transform your documents and start working.

A second option is to setup the environment variables manually. To to this, you must define APHID_HOME, ANT_HOME, and ANT_OPTS in your .profile or .bashrc, etc. depending upon your SHELL. Additionally, the PATH environment variable must be modified to begin with: $APHID_HOME/bat and $ANT_HOME/bin.

3.2.3. Updating APHID

Updating APHID is as simple as installing it. Simply unzip the contents of the ZIP file into the folder where you previously installed APHID. Provided you ave followed the instructions about creating your own custom configurations, all of your customizations will continue to work.

Optionally, you can install multiple versions of APHID into different locations. You need to make sure, however, that your environment variables are setup to invoke the correct installation of APHID.

The only reason to maintain multiple versions of APHID would be to continue to process old documents in the event that I introduce a backward-incompatible change into APHID, or if you need to continue to process older versions of docbook documents once they are deprecated. Both of these issues should be rare.

3.2.4. Uninstalling APHID

To uninstall APHID, simply delete the directory where you installed APHID. If you manually setup your environment, remove the APHID_HOME, ANT_HOME, and ANT_OPTS environment variables, and remove $APHID_HOME/bin and $ANT_HOME/bin from your PATH.

3.3. The APHID Directory Structure

The APHID installation directory has various subdirectories. A short description of their purpose/content follows:

ant

Apache ANT. APHID uses ANT to drive the processing of all documents. The file build.xml in the APHID_HOME directory defines how documents are processed.

aptconvert

A command-line tool that can be used to convert APT (Almost Plain Text) formatted text to HTML, XHTML, PDF, PostScript, (MS Word loadable) RTF, and DocBook XML. Note, that APHID only uses aptconvert to convert text documents into DocBook/XML. The rest of the aptconvert functionality is not used by APHID.

bat

Windows batch files (executable files) that represent the APHID commands

bin

Shell scripts (executable files) that represent the APHID commands. These can be run under Unix, Linux, and Cygwin.

docs

APHID documentation. The DocBook Reference Manual DocBook: The Definitive Guide is located in the file docs/tdg/en/html/docbook.html. The APHID User Guide is available in both HTML (docs/aphid/userguide.html) and PDF (docs/aphid/userguide.pdf) formats.

docbook

The DocBook XML Document Type Definition (DTDs) for the various versions of DocBook that APHID supports

fop

The Apache Form Objects Processor (FOP). APHID uses FOP to generate PDF documents from XML documents.

jars

Third-party JAVA jar files used to extend functionality of APHID's internal tools (e.g. ANT, FOP, etc.).

saxon6

Version 6 of Saxon, an XSL processor. APHID uses Saxon to transform the XML sources to the various output formats.

saxon8

Version 8 of Saxon, an XSL processor. APHID does not currently use this version of Saxon to transform the XML sources to the various output formats. This directory is currently used for internal testing.

stylesheet

The XSL stylesheets that define the layout of the individual output formats. It also contains the CSS stylesheets used to format the generated HTML. Filenames beginning with aphid_ should not be modified since they will be overwritten by APHID updates. Customizations should be made in the files beginning with custom_.

templates

APHID template documents for articles, books and boilerplate text. APHID creates new articles and books from these template documents.

xsl

The DocBook XSL stylesheets that define the transformation from DocBook/XML to the various output formats.

4.  Using APHID

There are two primary ways that you can use APHID. The first is to convert Almost Plain Text (APT) documents into other output formats (PDF, HTML, etc.). This is typically the way that someone new to DocBook/XML (or someone that wants to generate DocBook/XML documents without having to learn DocBook) would use it. The commands to do this are described in the Converting TEXT Documents to DocBook/XML section.

The second way that you can use APHID is to validate DocBook/XML documents that you have created and use them to generate another output format (PDF, HTML, etc.). It is not necessary to create a DocBook/XML document with APHID in order to convert DocBook/XML into another output format. You can use any text editor or other external method to create the DocBook/XML file. The commands to convert valid DocBook/XML documents into other output formats is described in the Converting DocBook/XML Documents to Other Formats section.

For an introduction to DocBook and a reference of all tags, refer to the DocBook Manual DocBook: The Definitive Guide. This guide is included in the APHID distribution. It is located in the file docs/tdg/en/html/docbook.html.

Beginners are advised to search for appropriate examples there, copy and paste them into your own documents, and modify them as needed. If you are new to DocBook, read the chapter Creating DocBook Documents to understand what DocBook is about.

4.1.  Converting TEXT Documents to DocBook/XML

The text-to-docbook conversion command looks like: text2dook <-a> <-b> <-o output_file> <-v DTD_version> <input_file> ... input_file.

For example, the document you are currently reading, the APHID User Guide, is contained in 5 input files: intro.txt, install.txt, using.txt, changes.txt, and todo.txt. Creating the XML document is as simple as running: text2dbook -o userguide.xml intro.txt install.txt using.txt changes.txt todo.txt.

Converting the introductory section, a valid APT (Almost Plain Text) formatted text document on its own, to XML can be done by executing: text2dbook intro.txt.

4.2. Converting TEXT Documents to Other Formats

All of the text-conversion commands (text2chunk, text2dbook, text2html, and text2pdf) have the same options as described in Command Options.

For example, re-creating the APHID User Guide is as simple as running: text2pdf -o userguide.pdf intro.txt install.txt using.txt changes.txt todo.txt.

Similarly, creating the HTML document is as simple as running: text2html -o userguide.html intro.txt install.txt using.txt changes.txt todo.txt. When creating HTML documents (regardless of the number of input documents), there are two possiblities for creating the output file(s):

  1. A single HTML document. This is created by running text2html.

  2. Multiple HTML documents. This is created by running text2chunk. When executing this command you can specify an output file, however, it will be ignored. The top-level document will always be named index.html.

4.3.  Command Options

Options can be appear in any order.

-a

Create a DocBook/XML article document.

-b

Create a DocBook/XML book document.

Only one of the above options (a or b) may be specified.

If both options are specified, APHID will report an error.

If both options are omitted, the default document type that will be created is an article.

Note that DocBook/XML book support is really a hack in the current implementation. Essentially, article tags are replaced with book tags in the generated XML document. Future versions of APHID will do a much better job of creating DocBook/XML book documents.

-o

Specify an output name for the document. This option MUST be immediately followed with the name of the output file.

Default: There is no default for the -o option.

If this option is ommitted, the default name of the output document is the basename of the input file, plus an XML extension.

Example: text2dbook intro.txt results in an output document named intro.xml.

If there is a list of input files, the output name is the same as the basename of the first filename in the list plus an XML extension.

Example: text2html intro.txt page3.txt page2.txt results in an output document named intro.html.

The only exceptions are the text2chunk and text2chunk commands. These documents generate multiple HTML files and the top-level document is ALWAYS named index.html. If the -o option is specified APHID silently ignores it.

-v

The DocBook DTD version to use for validation. This option MUST be immediately followed with the version info.

Default: There is no default for the -v option.

If this option is ommitted, the default DTD version that will be used for validation is 4.5.

Valid versions: 4.0, 4.1.2, 4.2, 4.3, 4.4, 4.5, or simple.

4.4. Converting DocBook/XML Documents to Other Formats

All of the docbook-conversion commands (dbook2chunk, dbook2html, and dbook2pdf) have the same command structure. For example, the docbook-to-pdf conversion command looks like: dbook2pdf input_file.

The default name of the output document is the basename of the input file, plus a PDF extension. For example, dbook2pdf intro.xml results in an output document named intro.pdf.

Note that, if your primary DocBook/XML document references other documents via the internal or external entities mechanism, it is not necessary to list those documents when invoking dbook2pdf; they are automatically included. (If you did not understand the last sentence, don't worry. It probably would not mean anything to you unless you were already familiar with the structure of a DocBook/XML document.)

Creating an HTML document is as simple as running: dbook2html userguide.xml.

Again, if your primary DocBook/XML document references other documents via the internal or external entities mechanism, it is not necessary to list those documents when invoking dbook2html; they are automatically included.

When creating HTML documents (regardless of the number of input documents), there are two possiblities for creating the output file(s):

  1. A single HTML document. This is created by running dbook2html.

  2. Multiple HTML documents. This is created by running dbook2chunk. When executing this command the top-level document will always be named index.html.

4.5. Configuration files

Options which are common to all the APHID documents processed on your site (article vs. book, DTD version to use for validation, etc.) can be put in a system-wide configuration file rather than being passed to the command line. See Installing APHID.

An APHID configuration file is a text file containing environment variable settings.

While you may be tempted to modify the default configuration file directly, avoid thie temptation. Any changes made to the default configuration file will be lost when APHID is upgraded. Always create a custom configuration file if you wish to over-ride the default configuration.

Be aware that a custom configuration file also provides the opportunity to modify settings that cannot be modified from the command line (paper type, encoding, language, verbosity, etc.).

4.5.1. Windows

  • The file contains lines in the form: set variable = value.

  • Lines beginning with rem are ignored, however, you cannot use a redirection character "(" or ")" or pipe (|) in a batch file comment. This is a limitation of the Windows command shell, not APHID.

  • Blank lines are allowed.

    Example:

    set docbook_type=article
    set docbook_version=4.5
    set APT_ENCODING=ISO8859_1
    set APT_DBOOK_ENCODING=ISO8859_1
    set APT_PAPER_TYPE=letter
    set APT_VERBOSITY=1

    Each time APHID is run, it attempts to read options from:

    1. The default configuration file named aphid_configuration.bat found in the %APHID_HOME%\bat directory.

    2. The configuration file found in the %APHID_HOME% directory named custom_configuration.bat.

    3. The configuration file found in the %HOME% user directory named custom_configuration.bat.

    4. The configuration file found in the directory containing the source document named custom_configuration.bat.

    5. The command line.

    Options are set in that order. For example, if you have a system-wide configuration file and a configuration file in your HOME directory, the settings in the HOME directory will over-ride the system-wide configuration. Similarly, the command line ALWAYS takes precedence over any configuration file.

4.5.2. UNIX

  • The file contains lines in the form: variable = value.

  • Lines beginning with # are ignored.

  • A \ at the end of each line must be used if value is more than one line long.

  • Blank lines are allowed.

    Example:

    docbook_type=article
    docbook_version=4.5
    APT_ENCODING=ISO8859_1
    APT_DBOOK_ENCODING=ISO8859_1
    APT_PAPER_TYPE=letter
    APT_VERBOSITY=1

    Each time APHID is run, it attempts to read options from:

    1. The default configuration file named aphid_configuration found in the $APHID_HOME/bin directory.

    2. The configuration file found in the $APHID_HOME directory named custom_configuration.

    3. The configuration file found in the $HOME user directory named custom_configuration.

    4. The configuration file found in the directory containing the source document named custom_configuration.

    5. The command line.

    Options are set in that order. For example, if you have a system-wide configuration file and a configuration file in your HOME directory, the settings in the HOME directory will over-ride the system-wide configuration. Similarly, the command line ALWAYS takes precedence over any configuration file.

5. The APT format

In the following section, boxes containing text in typewriter-like font are examples of APT source.

5.1. Document structure

A short APT document is contained in a single text file. A longer document may be contained in a ordered list of text files. For instance, first text file contains section 1, second text file contains section 2, and so on.

Note:

Splitting the APT document in several text files on a section boundary is not mandatory. The split may occur anywhere. However doing so is recommended because a text file containing a section is by itself a valid APT document.

A file contains a sequence of paragraphs and ``displays'' (non paragraphs such as tables) separated by open lines.

A paragraph is simply a sequence of consecutive text lines.

  First line of first paragraph.
  Second line of first paragraph.
  Third line of first paragraph.
  
  Line 1 of paragraph 2 (separated from first paragraph by an open line).
  Line 2 of paragraph 2.

The indentation of the first line of a paragraph is the main method used by an APT processor to recognize the type of the paragraph. For example, a section title must not be indented at all.

A ``plain'' paragraph must be indented by a certain amount of space. For example, a plain paragraph which is not contained in a list may be indented by two spaces.

My section title (not indented).

  My paragraph first line (indented by 2 spaces).

Indentation is not rigid. Any amount of space will do. You don't even need to use a consistent indentation all over your document. What really matters for an APT processor is whether the paragraph is not indented at all or, when inside a list, whether a paragraph is more or less indented than the first item of the list (more about this later).

    First paragraph has its first line indented by four
spaces. Then the author did even bother to indent the
other lines of the paragraph.

  Second paragraph contains several lines which are all 
  indented by two spaces. This style is much nicer than 
  the one used for the previous paragraph.

Note that tabs are expanded with a tab width set to 8.

5.2. Document elements

5.2.1. Block level elements

5.2.1.1. Title

A title is optional. If used, it must appear as the first block of the document.

                                    ------
                                    Title
                                    ------
                                    Author
                                    ------
                                     Date

A title block is indented (centering it is nicer). It begins with a line containing at least 3 dashes (---).

After the first --- line, one or several consecutive lines of text (implicit line break after each line) specify the title of the document.

This text may immediately be followed by another --- line and one or several consecutive lines of text which specifies the author of the document.

The author sub-block may optionaly be followed by a date sub-block using the same syntax.

The following example is used for a document with an title and a date but with no declared author.

                                    ------
                                    Title
                                    ------
                                    ------
                                     Date
                                    ------

The last line is ignored. It is just there to make the block nicer.

5.2.1.2. Paragraph

Paragraphs other than the title block may appear before the first section.

  Paragraph 1, line 1.
  Paragraph 1, line 2.

  Paragraph 2, line 1.
  Paragraph 2, line 2.

Paragraphs are indented. They have already been described in the document structure section.

5.2.1.3. Section

Sections are created by inserting section titles into the document. Simple documents need not contain sections.

Section title

* Sub-section title

** Sub-sub-section title

*** Sub-sub-sub-section title

**** Sub-sub-sub-sub-section title

Section titles are not indented. A sub-section title begins with one asterisk (*), a sub-sub-section title begins with two asterisks (**), and so forth up to four sub-section levels.

5.2.1.4. List
      * List item 1.

      * List item 2.

        Paragraph contained in list item 2.

            * Sub-list item 1.

            * Sub-list item 2.

      * List item 3.

List items are indented and begin with a asterisk (*).

Plain paragraphs more indented than the first list item are nested in that list. Displays such as tables (not indented) are always nested in the current list.

To nest a list inside a list, indent its first item more than its parent list. To end a list, add a paragraph or list item less indented than the current list.

Section titles always end a list. Displays cannot end a list but the [] pseudo-element may be used to force the end of a list.

      * List item 3.
        Force end of list:

      []

--------------------------------------------
Verbatim text not contained in list item 3
--------------------------------------------

In the previous example, without the [], the verbatim text (not indented as all displays) would have been contained in list item 3.

A single [] may be used to end several nested lists at the same time. The indentation of [] may be used to specify exactly which lists should be ended. Example:

      * List item 1.

      * List item 2.

            * Sub-list item 1.

            * Sub-list item 2.

            []

-------------------------------------------------------------------
Verbatim text contained in list item 2, but not in sub-list item 2
-------------------------------------------------------------------

There are three kind of lists, the bulleted lists we have already described, the numbered lists and the definition lists.

      [[1]] Numbered item 1.

                [[A]] Numbered item A.

                [[B]] Numbered item B.

      [[2]] Numbered item 2.

A numbered list item begins with a label beetween two square brackets. The label of the first item establishes the numbering scheme for the whole list:

[[1]]

Decimal numbering: 1, 2, 3, 4, etc.

[[a]]

Lower-alpha numbering: a, b, c, d, etc.

[[A]]

Upper-alpha numbering: A, B, C, D, etc.

[[i]]

Lower-roman numbering: i, ii, iii, iv, etc.

[[I]]

Upper-roman numbering: I, II, III, IV, etc.

The labels of the items other than the first one are ignored. It is recommended to take the time to type the correct label for each item in order to keep the APT source document readable.

      [Defined term 1] of definition list 2.

      [Defined term 2] of definition list 2.

A definition list item begins with a defined term: text between square brackets.

5.2.1.5. Verbatim text
----------------------------------------
Verbatim 
         text,
                preformatted,
                                escaped.
----------------------------------------

A verbatim block is not indented. It begins with a non indented line containing at least 3 dashes (---). It ends with a similar line.

+-- instead of --- draws a box around verbatim text.

Like in HTML, verbatim text is preformatted. Unlike HTML, verbatim text is escaped: inside a verbatim display, markup is not interpreted by the APT processor.

5.2.1.6. Figure
[Figure name] Figure caption

A figure block is not indented. It begins with the figure name between square brackets. The figure name is optionally followed by some text: the figure caption.

The figure name is the pathname of the file containing the figure but without an extension. Example: if your figure is contained in /home/joe/docs/mylogo.jpeg, the figure name is /home/joe/docs/mylogo.

If the figure name comes from a relative pathname (recommended practice) rather than from an absolute pathname, this relative pathname is taken to be relative to the directory of the current APT document (a la HTML) rather than relative to the current working directory.

Why not leave the file extension in the figure name? This is better explained by an example. You need to convert an APT document to PostScript and your figure name is /home/joe/docs/mylogo. A APT processor will first try to load /home/joe/docs/mylogo.eps. When the desired format is not found, a APT processor tries to convert one of the existing formats. In our example, the APT processor tries to convert /home/joe/docs/mylogo.jpeg to encapsulated PostScript.

5.2.1.7. Table

A table block is not indented. It begins with a non indented line containing an asterisk and at least 2 dashes (*--). It ends with a similar line.

The first line is not only used to recognize a table but also to specify column justification. In the following example,

  • the second asterisk (*) is used to specify that column 1 is centered,

  • the plus sign (+) specifies that column 2 is left aligned,

  • the colon (:) specifies that column 3 is right aligned.

*----------*--------------+----------------:
| Centered | Left-aligned | Right-aligned  |
| cell 1,1 | cell 1,2     | cell 1,3       |
*----------*--------------+----------------:
| cell 2,1 | cell 2,2     | cell 2,3       |
*----------*--------------+----------------:
Table caption

Rows are separated by a non indented line beginning with *--.

An optional table caption (non indented text) may immediately follow the table.

Rows may contain single line or multiple line cells. Each line of cell text is separated from the adjacent cell by the pipe character (|). (| may be used in the cell text if quoted: \|.)

The last | is only used to make the table nicer. The first | is not only used to make the table nicer, but also to specify that a grid is to be drawn around table cells.

The following example shows a simple table with no grid and no caption.

*-----*------*
 cell | cell
*-----*------*
 cell | cell
*-----*------*
5.2.1.8. Horizontal rule
=====================

A non indented line containing at least 3 equal signs (===).

5.2.1.9. Page break
^L

A non indented line containing a single form feed character (Control-L).

5.2.2. Text level elements

5.2.2.1. Font
  <Italic> font. <<Bold>> font. <<<Monospaced>>> font.

Text between < and > must be rendered in italic. Text between << and >> must be rendered in bold. Text between <<< and >>> must be rendered using a monospaced, typewriter-like font.

Font elements may appear anywhere except inside other font elements.

It is not recommended to use font elements inside titles, section titles, links and defined terms because a APT processor automatically applies appropriate font styles to these elements.

5.2.2.2. Anchor and link
  {Anchor}. Link to {{anchor}}. Link to {{http://www.pixware.fr}}. 
  Link to {{{anchor}showing alternate text}}.
  Link to {{{http://www.pixware.fr}Pixware home page}}.

Text between curly braces ({}) specifies an anchor. Text between double curly braces ({{}}) specifies a link.

It is an error to create a link element that does not refer to an anchor of the same name. The name of an anchor/link is its text with all non alphanumeric characters stripped.

This rule does not apply to links to external anchors. Text beginning with http:/, https:/, ftp:/, file:/, mailto:, ../, ./ (..\ and .\ on Windows) is recognized as an external anchor name.

When the construct {{{ name } text }} is used, the link text text may differ from the link name name.

Anchor/link elements may appear anywhere except inside other anchor/link elements.

Section titles are implicitly defined anchors.

5.2.2.3. Line break
  Force line\
  break.

A backslash character (\) followed by a newline character.

Line breaks must not be used inside titles and tables (which are line oriented blocks with implicit line breaks).

5.2.2.4. Non breaking space
  Non\ breaking\ space.

A backslash character (\) followed by a space character.

5.2.2.5. Special character
  Escaped special characters: \~, \=, \-, \+, \*, \[, \], \<, \>, \{, \}, \\.

In certain contexts, these characters have a special meaning and therefore must be escaped if needed as is. They are escaped by adding a backslash in front of them. The backslash may itself be escaped by adding another backslash in front of it.

Note that an asterisk, for example, needs to be escaped only if its begins a paragraph. (* has no special meaning in the middle of a paragraph.)

  Copyright symbol: \251, \xA9, \u00a9.

Latin-1 characters (whatever is the encoding of the APT document) may be specified by their codes using a backslash followed by one to three octal digits or by using the \x NN notation, where NN are two hexadecimal digits.

Unicode characters may be specified by their codes using the \u NNNN notation, where NNNN are four hexadecimal digits.

5.2.2.6. Comment
~~Commented out.

Text found after two tildes (~~) is ignored up to the end of line.

A line of ~ is often used to ``underline'' section titles in order to make them stand out of other paragraphs.

5.3. An Example APT formatted document

The following is an example APT document:

                                    ------
                                    Title
                                    ------
                                    Author
                                    ------
                                     Date

  Paragraph 1, line 1.
  Paragraph 1, line 2.

  Paragraph 2, line 1.
  Paragraph 2, line 2.

Section title

* Sub-section title

** Sub-sub-section title

*** Sub-sub-sub-section title

**** Sub-sub-sub-sub-section title

      * List item 1.

      * List item 2.

        Paragraph contained in list item 2.

            * Sub-list item 1.

            * Sub-list item 2.

      * List item 3.
        Force end of list:

      []

+------------------------------------------+
Verbatim text not contained in list item 3
+------------------------------------------+

      [[1]] Numbered item 1.

                [[A]] Numbered item A.

                [[B]] Numbered item B.

      [[2]] Numbered item 2.

  List numbering schemes: [[1]], [[a]], [[A]], [[i]], [[I]].

      [Defined term 1] of definition list.

      [Defined term 2] of definition list.

+-------------------------------+
Verbatim text
                        in a box        
+-------------------------------+

  --- instead of +-- suppresses the box around verbatim text.

[aphid-image] APHID Graphic Image

*----------*--------------+----------------:
| Centered | Left-aligned | Right-aligned  |
| cell 1,1 | cell 1,2     | cell 1,3       |
*----------*--------------+----------------:
| cell 2,1 | cell 2,2     | cell 2,3       |
*----------*--------------+----------------:
Table caption

  No grid, no caption:

*-----*------*
 cell | cell
*-----*------*
 cell | cell
*-----*------*

  Horizontal line:

=======================================================================

^L
  New page.

  <Italic> font. <<Bold>> font. <<<Monospaced>>> font.

  {Anchor}. Link to {{anchor}}. Link to {{http://www.pixware.fr}}. 
  Link to {{{anchor}showing alternate text}}.
  Link to {{{http://www.pixware.fr}Pixware home page}}.

  Force line\
  break.

  Non\ breaking\ space.

  Escaped special characters: \~, \=, \-, \+, \*, \[, \], \<, \>, \{, \}, \\.

  Copyright symbol: \251, \xA9, \u00a9.

~~Commented out.

The source document (text file) for this example can be found in the file named docs/aphid/example.txt.

The HTML document generated from this example can be found in the file named docs/aphid/example.html.

The PDF document generated from this example can be found in the file named docs/aphid/example.pdf.

6. Changes

6.1. Version 0.7

  • Completely rewrote the batch files. Among the major changes:

    1. The user must now specify the complete filename including the extension. The extension is no longer required to be TXT.

    2. The command now accepts switches. The user can now specify whether they want to create an article or a book via the "-a" or "-b" switch. One one or the other is allowed. The user can specify the preferred DTD version via the "-v" switch. Currently supported DTD versions are simple, and 4.0 - 4.5. The default is still 4.3. Switches can be listed in any order.

    3. The user can now specify a list of files to be converted. By default, the name of the output file will be the name of the first text file in the list minus the extension plus .XML. For example, if the the list of files passed is intro.txt, page1.txt, and page2.txt, the name of the generated file will be intro.xml.

  • Processing of the text file has been moved directly into the batch file. ANT is no longer used to do the initial conversion from TXT to XML. ANT is only called to "indentify" the file. This greatly increases the speed of the TXT to XML conversion.

  • All APT related variables are now set via the load_configuration.bat file.

  • Added APT-related variables. The user can now define or over-ride things such as the default language, encoding scheme, paper size, etc. Additionally, the user can now set their own defaults on either a global level, or at the document level.

  • Got rid of stuff related to document_deploy. We don't deploy anything. This was a hold-over from the original eDE stuff.

  • Added custom config stuff for overriding the default config at a global or document specific level.

  • Commented out the initial setting of the aphid_document_repository and aphid_document_output. The user can uncomment and set them to override the defaults. The script now correctly sets them only if they weren't already set.

  • Changed the URL displayed in the HTML header and footer that is generated by aphid.xsl. It noew has the correct sourceforge URL for the APHID project.

  • Updated the Simple DocBook DTD to 1.2CR1, 09 Mar 2006 (a customization of DocBook XML V4.5CR2)

  • Fixed numerous bugs related to option processing. Multi-stage (i.e.TXT to PDF) processing with an output file specified at the command line now works correctly.

  • Added processing of DocBook v4.4 and v4.5 documents.

  • Changed the default Docbook version to 4.5.

  • Got rid of the ANT pretty build stuff. While interesting, it's really not related to this project.

  • Updated the XSL stylesheets to version 1.69.1

  • Added check to make sure that JAVA_HOME is set.

  • Modified ANT calls to use ANT_HOME. Removed some stuff which has been commented out for a while. Squashed a few bugs.

  • Added UNIX versions of the scripts. Now APHID is truly platform independent!

  • Added environment setup scripts that the user can source/run in order to initialize their APHID environment.

  • Added code to read the environment variables and issue an error message if APHID_HOME is not set up. Also reset the aphid.root variable to use APHID_HOME.

  • Added version 2.0.1.7 (11 Oct 2006) of "DocBook: The Definitive Guide" so users don't have to go hunt down information on creating XML documents.

6.2. Version 0.6

  • Added the ability to generate change-bars when creating HTML documents. This is very preliminary. More work needs to be done in order to make this user-friendly. There is no easy way to do this with PDF docs yet.

7. To Do

7.1. General

  • Add support for all of the DocBook options that can be passed to aptconvert in the default configuration files.

  • Test the document repository functionality.

7.2. Text Documents

  • Implement the ablility to create DocBook/XML chapters.

  • Support the use of internal and external "entities".

  • Support linking across source documents. (This may not be possible)

7.3. DocBook Documents

  • Support the -o option for the dbook2xxx commands.

  • Create a few default CSS stylesheets for example documents?

7.4. HTML Documents

  • Modify the default stylesheet to generate documents more like the default pixware.css.

  • Incorporate styles from the Forrest Project and how they generate HTML documents (the abilty to have note, warning, important, etc. styles).

  • Complete implementation of changebars.

7.5. HTML Help Documents

  • Implement generation of HTML Help (Windows only, CHM files)

7.6. PDF Documents

  • Modify the default stylesheet to generate documents more like the default pixware.css.

  • Incorporate styles from the Forrest Project and how they generate PDF documents (the abilty to have note, warning, important, etc. styles).

  • Implement the ability to add changebars. (This may not be possible)

  • Fix bugs related to using PNG images. APHID will use them; aptconvert has a problem dealing with them.

This document was created using APHID-DocBook