![]() |
![]() |
![]() |
![]() |
![]() |
An aptconvert command looks like:
aptconvert option ...
option output_file input_file ...
input_file.
For example, the document you are currently reading,
the APT User Guide, is contained in 4 input files: intro.txt, format.txt,
install.txt and using.txt. Converting it to HTML is as simple as running
aptconvert userguide.html intro.txt format.txt install.txt
using.txt.
Converting the format section (a valid APT document on
its own) to PDF can be done by executing
aptconvert format.pdf
format.txt.
Default: not verbose.
Default: no table of contents.
APT anchors are used as index entries.
Default: no index.
Default: sections are numbered.
Example: -meta keywords "XML XSL XSLT XPath".
Default: no metas.
Example: -pi html homeURL http://www.pixware.fr.
Default: no PIs.
Example: -rule fig jpg 'fig2dev -L jpeg %F %G'
Src_to_dst_rule is a command template where all occurences of %F are substituted with the source graphics file name and where all occurences of %G are substituted with the destination graphics file name.
Default: no rules.
Default: a4.
Default: en.
Default: your platform default encoding.
A converter is a backend which translates an APT document to another format. A converter is associated to a file name extension. For example, the LaTeX converter is automatically used when the output file ends with .tex.
An extractor is a preprocessor which extracts an APT document embedded into source code (i.e. à la javadoc). A extractor is associated to a file name extension. For example, the Tcl extractor is automatically used when the input file ends with .tcl.
Options which are common to all the APT documents processed on your site (-lang, -paper, -rule) should be put in a system-wide configuration file rather than being passed to the command line. See installing aptconvert.
An aptconvert configuration file is a text file (a Java property file) containing lines in the form property=value.
Example:
v=1 toc=1 lang=fr paper=a4 latex.usepackage.0=bookman # Screen resolution is 110dpi not 72dpi (72/120=0.65). .gif.eps=giftopnm %F | pnmtops -scale 0.65 -rle > %G .fig.jpg=fig2dev -L jpeg %F %G keywords=pixware realtime \ data acquisition
Blank lines are allowed. Lines beginning with # are ignored. A \ at the end of each line must be used if value is more than one line long.
Properties corresponding to PIs are named format.pi_key and properties corresponding to rules are named .src_ext.dst_ext. Other properties not containing dots and not recognized as options are assumed to be metas.
Each time aptconvert is run, it attempts to read options from:
This example describes how aptconvert handles figures. What follows are the actions taken by aptconvert when converting to HTML an APT document containing a figure named images/architecture:
Therefore aptconvert tries to access a file named input_file_directory/images/architecture.gif. If it finds such file, it copies it to output_file_directory (unless input and output file directories are the same) and that's it.
.gif.eps=giftopnm %F | pnmtops -scale 0.65 -rle > %G .fig.eps=fig2dev -L ps %F %G .fig.jpg=fig2dev -L jpeg %F %G
Aptconvert tries to access a file named input_file_directory/images/architecture.gif because first rule begins with .gif, but this fails like step 1.
Therefore it attempts to find a rule converting Fig graphics to GIF, but this fails.
Aptconvert runs the fig2dev graphics converter with appropriate arguments and the generated HTML document finally gets its image.
Extensions | html htm |
-toc | yes |
-index | yes |
-paper | N/A |
-lang | en es de fr it |
-enc | ASCII ISO8859_1 ISO8859_2 ISO8859_3 ISO8859_4 ISO8859_5 ISO8859_6 ISO8859_7 ISO8859_8 ISO8859_9 SJIS UTF8 UTF16 Cp1250 Cp1251 Cp1252 Cp1253 MacArabic MacCentralEurope MacCroatian MacCyrillic MacGreek MacHebrew MacIceland MacRoman MacRomania MacThai MacTurkish MacUkraine |
Graphics formats | gif jpeg png |
Processing instructions:
When paging is enabled, a navigation toolbar is automatically added at the top of generated HTML pages.
When paging is enabled, the output file name is used as a template to give each page its own file name. Example: aptconvert -pi html paging 2 -toc -index userguide.html intro.txt format.txt install.txt using.txt generates files named: userguide1.html, userguide2.html, userguide2_1.html, ..., userguidetoc.html, userguideindex.html.
Default: 0 (single-page document).
Default: no style sheet.
Default: no home icon.
Default: if the output file name ends with .xhtml or .xhtm, the default value is yes, otherwise it is no.
Note that the generated XHTML conforms to the compatibility guidelines recommended by the W3C and is therefore well supported by most browsers.
Default: none in SGML mode;
http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd
or
http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd
in XML mode (valid XML
documents must have a systemId).
When using the transitional DTD, some deprecated elements and attributes (such as center, border, compact, etc) well supported by old browsers are generated.
When using the strict DTD, these deprecated elements and attributes are replaced by equivalent CSS style attributes.
Default: no in SGML mode; yes in XML mode.
if showTitle=no, the title, author and date of the document are just converted to (invisible) head/title and head/meta HTML elements.
Default: no.
Meta-information:
Extensions | tex |
-toc | yes |
-index | yes |
-paper | a4 a5 b5 letter legal executive |
-lang | br ca hr cs da nl en eo et fi fr gl de el he hu ga it no pl pt ro ru gd sk sl es sv tr cy |
-enc | ASCII Cp1250 Cp1252 Cp437 Cp850 Cp852 Cp865 ISO8859_1 ISO8859_2 ISO8859_3 ISO8859_4 ISO8859_5 MacRoman |
Graphics formats | eps |
Processing instructions:
Example: -pi latex documentclass [11pt]report.
Default: [P]article, P specified by -paper.
N varies for 0 to 10, so there are 11 such PIs available.
Example: -pi latex usepackage.5 [french]babel.
Default packages:
Default: plain if classic=yes or if the document has no title, otherwise a custom style using the fancyhdr package.
N varies for 0 to 10, so there are 11 such PIs available.
Example: -pi latex hyphenation.0 "gno-mon gno-mons gno-mon-ly".
Default: builtin TeX hyphenation rules.
Default: no.
Default: no (not the classic look!).
Meta-information:
Therefore it is possible to specify once for all that you are the author of all the documents your write by adding, for example, the following lines into your .aptconvertrc or aptconvert.ini:
author=Joe User\n\ juser@incredible-widgets.com
The APT document is first converted to LaTeX before being converted to PostScript using the commands specified by pass1 and pass2. Therefore everything said about LaTeX is relevant when outputting PostScript.
Extension is ps.
Processing instructions:
Default: latex doc.
Default: dvips -o %O doc.
About command templates:
The APT document is first converted to LaTeX before being converted to PDF using the commands specified by pass1, pass2, and pass3. Therefore everything said about LaTeX is relevant when outputting PDF.
Extension is pdf.
Default: latex doc.
Default: dvips -o doc.ps doc.
Default: ps2pdf doc.ps %O.
Example 1: add this to your .aptconvert/aptconvert.ini if you want an hypertext TOC and/or Index.
latex.usepackage.0=hyperref pdf.pass1=latex doc pdf.pass2=dvips -z -o doc.ps doc pdf.pass3=ps2pdf doc.ps %O
Example 2: add this to your .aptconvert/aptconvert.ini if you prefer to use pdflatex (you still have a problem with graphics because pdflatex does not support EPS). Note how pass3 has been suppressed.
pdf.pass1=pdflatex doc pdf.pass2=mv doc.pdf %O pdf.pass3=
Extensions | sgml (DocBook/SGML) xml (DocBook/XML) |
-toc | N/A |
-index | N/A |
-paper | N/A |
-lang | any (not checked) |
-enc | ASCII ISO8859_1 ISO8859_2 ISO8859_3 ISO8859_4 ISO8859_5 ISO8859_6 ISO8859_7 ISO8859_8 ISO8859_9 SJIS UTF8 UTF16 Cp1250 Cp1251 Cp1252 Cp1253 MacArabic MacCentralEurope MacCroatian MacCyrillic MacGreek MacHebrew MacIceland MacRoman MacRomania MacThai MacTurkish MacUkraine |
Graphics formats | gif jpeg eps |
Processing instructions:
Default: -//OASIS//DTD DocBook V4.1//EN in SGML mode; -//OASIS//DTD DocBook XML V4.0//EN in XML mode.
Default: none in SGML mode; http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd in XML mode (valid XML documents must have a systemId).
Default: no style sheet.
Default: <emphasis>.
Default: <emphasis role="bold">.
Default: <literal>.
Default: <!-- HR -->.
Default: <!-- PB -->.
Default: <!-- LB -->.
Meta-information: not yet implemented.
Extensions | rtf |
-toc | no |
-index | no |
-paper | a3 a4 a5 b4 b5 executive ledger legal letter
tabloid <w>x<h> |
-lang | no |
-enc | ASCII Cp1250 Cp1251 Cp1252 ISO8859_1 |
Graphics formats | ppm |
Notes:
Processing instructions:
Unit: cm. Default: 2.
Unit: cm. Default: 2.
Unit: cm. Default: 2.
Unit: cm. Default: 2.
Unit: pts. Default: 10.
Unit: pts. Default: 10.
Unit: dpi. Default: 72.
Default: palette
Default: ascii
Meta-information: none.
An APT document may be embedded into source code files. In fact, APT was originally designed to speed up the authoring of reference manuals for C++ class libraries by embedding documentation into the header files.
When given an input file which ends with the right extension, for example .h for a C header file, aptconvert will automatically try to extract APT document fragments out of it.
The input file must end with .tcl.
Single line comment containing a document fragment:
#x eof - Check for end of file condition on channel
is extracted and rendered as:
eof - Check for end of file condition on channel
Note that comment line begins with #x (x like eXtract), followed by two spaces because the document fragment is a paragraph.
Multi-line comment block containing a document fragment:
#x #===================== # # <<eof>> <channelId> #
is extracted and rendered as:
eof channelId
First comment line contains exclusively the #x marker. Following lines begin with a single #. Note that indentation of the comment block containing the document fragment is allowed.
An open line after single or multi-line document fragments is mandatory. Otherwise the source code found immediatly after a fragment is extracted to and put into a verbatim display.
Example:
#x # # Returns 1 if an end of file condition occurred during the # most recent input operation on channelId (such as gets), 0 # otherwise. # proc eof {channelId} { return [eofImpl $channelId] }
is extracted and rendered as:
proc eof {channelId} { return [eofImpl $channelId] }
Returns 1 if an end of file condition occurred during the most recent input operation on channelId (such as gets), 0 otherwise.
By default the verbatim display is inserted before the document fragment. It is possible to specify another place by using the ~~x extraction directive.
Example:
#x #=== # #~~x # # Returns 1 if an end of file condition occurred during the # most recent input operation on channelId (such as gets), 0 # otherwise. # proc eof {channelId} { return [eofImpl $channelId] }
is extracted and rendered as:
proc eof {channelId} { return [eofImpl $channelId] }
Returns 1 if an end of file condition occurred during the most recent input operation on channelId (such as gets), 0 otherwise.
A box is drawn around extracted verbatim displays by using the tcl.verbatim PI:
Document extraction from C/C++ source file works exactly like extraction from Tcl files. The main difference is that C/C++ comments do not begin #.
The input file must end with .c, .h, .cpp, .hpp, .cxx, .hxx, .cc or .hh.
The PI used to draw a box around extracted verbatim displays is c.verbatim.
Examples:
//x Single line paragraph. //x // First line. // Second line. // /*x Single line paragraph. */ /*x First line. Second line. */ /** Single line paragraph. */ /** * Returns the value of the attribute called <name> * if such attribute exists or null otherwise. */ virtual const xstAnyValue* FindAttribute(const char* name);
Notes: