/\ \ /\ \ /\ \
______ ___ ___
/\ _ \ /\_ \ /\_ \
\ \ \L\ \\//\ \ \//\ \ __ __ _ __ ___
\ \ __ \ \ \ \ \ \ \ /'__`\ /'_ `\/\`'__\/ __`\
\ \ \/\ \ \_\ \_ \_\ \_/\ __//\ \L\ \ \ \//\ \L\ \
\ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
\/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
/\____/
\_/__/
Allegro's _tx documentation format.
By Grzegorz Adam Hankiewicz.
====================================
============ Disclaimer ============
====================================
During years the makedoc program has been used to output Allegro's
documentation in different file formats. Nobody ever cared to document
the _tx format or makedoc's source code. The result is that this late
reference might be wrong or inaccurate, please take it with a grain of
salt. And remember that makedoc is not a _real_ program, it's a hack,
just don't tell anybody else...
================================
============ Format ============
================================
_tx files are simple 8 bit text files written in a specific codepage
(usually latin1/iso-8859-1). The makedoc tool is codepage agnostic: if
you are using makedoc to generate documents in other codepages, you
are going to need to parse makedoc's output to adjust it to your needs.
This is usually not a very big problem, since you could use utf8 and
later convert it to your own codepage.
Taking the original allegro._tx as a reference, you can see that _tx
files are really a rich mixture of the supported output formats, and this
richness is stripped out appropriately for each output (ie: HTML tags won't
appear in plain ascii output, etc).
Lines starting with $@ will go unprocessed to the texi (and later info)
output. Such lines won't even appear in other outputs. Lines starting
with @# are comments and will be ignored by makedoc. A few simple HTML
tags like <li>, <br> or <pre> can be written directly where needed:
makedoc will strip them correctly in non-HTML output. Lines starting with
@ alone are special makedoc commands which can mean different things:
@multiplefiles
This command tells makedoc to generate multiple HTML files for a
document containing several @heading commands. It's ignored by all
the other output formats.
@ignore_css
By default the HTML output will use CSS to color text. Since CSS
implementation quality varies from a browser to another, you can use
this to avoid having unreadable documentation. Or just get a better
browser...
@external-css=filename.css
Use this switch to tell makedoc to output a default CSS file for
the HTML documentation. The specified file will be overwritten.
If @ignore_css is used, this option is ignored. If this option
is not set, then CSS will be be inlined in the HTML file.
@locale=xxx
An obsolete command. It was used by several output formats to set
correctly the language of the document. Nowadays you should be using
@rtf_language_header= and @charset= when apropiate.
@rtf_language_header=xxx
This can appear multiple times and is used only in rtf output. Rtf
documents need a special header for a specific language. This header
tells the viewer which fonts should be used with the document. By
default makedoc will generate a language header suitable for latin1
alike languages. Documents in other languages like Chinese or Korean
should use this to override the default header. This command replaces
the obsolete @locale command. Example for a Korean rtf:
@rtf_language_header={\fonttbl{\f0\froman\fcharset129\fprq2 ����;}
@rtf_language_header={\f1\fmodern\fcharset129\fprq1 ;}
@rtf_language_header={\f2\froman\fcharset129\fprq2 ;}}
@charset=xxx
This command is used by HTML output. Each generated HTML file needs a
meta tag with information about the used character set. By default
makedoc will use iso-8859-1 as character set. You can use this command
to override that meta tag. Example for Korean HTML files:
@charset=euc-kr
@document_title=xxx
Required for HTML output. Sets the title of each HTML file. For
multifile output, to this string makedoc will append the text of the
@heading command used to generate each individual file.
@h=<html><head><title>xxx</title></head><body>
An old and less flexible version of @document_title. While you can
still use it, it will deactivate immediately CSS generation and the
generated HTML code won't be valid (at least the header part)
@html_see_also_text=xxx
Optional command. By default, when HTML cross references for
identifiers and sections are generated, the text "See also:" precedes
the links. With this command you can customize it, which is necessary
for non-english documents.
@html_examples_using_this_text=xxx
Optional command. By default, when HTML cross references are generated
for examples, the text "Examples using this:" precedes the links. With
this command you can customize it, which is necessary for non-english
documents.
@html_footer=xxx
Required for multifile HTML output. This is the text that will appear
at the footer of each individual html file which is not the index.
@f=<a href="file.html">Back to contents</a>
Old version of @html_footer, preserved for backwards compatibility.
@html_footer puts the apropiate link tags around the text you provide.
@f1=<p><hr><p><a href="
@f2=">Back to Contents</a><p></body></html>
Yet another ugly old version of @html_footer. Same story: don't use it.
@rtfh=xxx
Similar to @document_title but for rtf output. Soon to be deprecated.
@manh=xxx
Header of each manpage.
@mans=xxx
Added to each manpage, something like #include <allegro.h>.
@titlepage
@!titlepage
Lines enclosed between those two commands are the title page of the
document.
@!indent
@indent
Lines enclosed between those two commands won't be indented.
@!html
@html
Lines enclosed between those two commands won't appear in HTML output.
@!text
@text
Lines enclosed between those two commands won't appear in text output.
@!texinfo
@texinfo
Lines enclosed between those two commands won't appear in texinfo
output.
@heading
This command introduces a new chapter or section in the document. In
HTML multifile will create a separate file. The following line has to
be the title of the new section.
@headingnocontent
Similar to @heading, this won't generate a table of contents of the
chapter.
@hnode xxx
Similar to @heading but doesn't create another file. xxx represents
the title of the new subsection.
@chapter
Like @heading, but one level above. It allows to partition the
documentation into multiple parts, each containing multiple @heading
sections. Currently, only the devhelp output format makes use of
this.
@endchapter
Ends the last chapter started by @chapter. Otherwise, a chapter ends
at the next @chapter command or at the end of the file.
@tallbullets
Uses tall bullets in the output formats that support them.
@html_spaced_list_bullet
Prepend a '<p>' to HTML output every time a <li> tag is found. This is
useful to space visually lists, used mainly for the changes log.
@contents
Generates an index for the info and html outputs.
@shortcontents
Similiar to @contents, but is always present in html files, even with
formats like devhelp or chm which normally put the results of
@contents into their navigation pane instead of the actual html.
@htmlindex xxx
Used in the main index HTML file of the document, creates a link to an
external file, xxx being the name without extension. Please try to
avoid this and use the next command instead.
@externalfile filename title
A replacement of htmlindex. The main difference is that htmlindex
would name the link exactly as it's filename. This is usually not
enough descriptive and tends to get in the way of translators.
filename can't contain spaces, which are used to mark the
beginning of title, or extension.
@mangle_emails=xxx yyy
From the line this command is found on, <email> tags will be mangled.
The mangling will depend on xxx and yyy, which have to be separated
exactly by one space. '@' characters in email addresses will be
replaced by the xxx part, dots will be replaced by the yyy part.
Possible example for a spanish document:
@mangle_emails=EN PUNTO
This would transform 'yo@terra.es' into 'yo EN terra PUNTO es'.
@retval
Used to mark the section of a function description involved with the
return value of this function. It has to be obviously at the end of
the function description.
@html_return_value_text=xxx
Optional command. By default, when HTML output is generated, the text
"Return value:" precedes sections marked with the @retval command.
With this command you can customize it, which is necessary for
non-english documents.
@html_text_substitution=xxx|yyy
With this command you can improve the hyperlinked nature of the HTML
documentation. During the second post processing part of the HTML
generation, all xxx texts will be replaced with yyy. This can be used
to create links to external documents which are not links in the text
version, or provide more complex HTML only features.
@html_text_substitution=readme.txt|<a href="readme.html">readme.txt</a>
@shortdesc xxxx
A single line description of the function/define/macro whatever you
are documenting. This description will appear for example in the name
of man pages, which can be queried with the apropos command.
@man_shortdesc_force1=xxx
@man_shortdesc_force2=xxx
Man pages use the short description in the title. However, one of the
ways of locating a man page is usually running `apropos string', and
maybe it's difficult to formulate short descriptions which always
contain a specific keyword. That's why these commands exist. For every
man page title, the first string is searched ignoring case. If this
string is found, nothing happens. Otherwise, the second string will
be appended to the short description (if any). This allows to populate
all manpages with a nice title without having to specify a short
description for each of them. Example:
@man_shortdesc_force1=allegro
@man_shortdesc_force2=Allegro game programming library.
===================================
============ Functions ============
===================================
The _tx format is about documenting functions. Functions, variables and
macros are specified with several @ characters at the appropriate points.
Given the function "int get_uformat(void);", you would write in a _tx
source file:
@@int @get_uformat(void);
Returns the currently selected text encoding format.
If you want to generate a cross reference for that function, you can use
the @xref command followed by a sequence of tokens separated by commas.
Several @xref commands can appear together for the same function:
@@void @set_uformat(int type);
@xref get_uformat, register_uformat, set_ucodepage, set_uformat
@xref ustrsize, ugetc, ugetx, usetc, uwidth, ucwidth, uisok
@xref ugetat, usetat, uinsert, uremove, allegro_init
Sets the current text encoding format...
If the name function is too long to fit horizontally (use a width of 80
for your document if you want it to be readable in output formats like
plain ascii or info), you can split the function over several lines:
@\void @register_uformat(int type,
@\ int (*u_getc)(const char *s),
@\ int (*u_getx)(char **s),
@\ int (*u_setc)(char *s, int c),
@\ int (*u_width)(const char *s),
@\ int (*u_cwidth)(int c),
@@ int (*u_isok)(int c));
@xref set_uformat, uconvert, ugetc, ugetx, usetc, uwidth, ucwidth, uisok
Installs a set of custom handler...
Remember to end the last line with @@ instead of @\. Use allegro._tx as a
reference if you have any problems documenting your functions.
If you want to generate a cross reference to examples using the function,
you can use the @eref command, which works exactly like @xref, but will be
colored differently in the HTML output.
Finally, for functions which have a return value, you should use the
@retval command to mark the first paragraph which talks about the return
value. Output formats like HTML or man pages will highlight the beginning
of this section (which should be the last of the function description) so
the user can quickly see it. Possible example:
@@int @set_window_close_button(int enable);
@xref set_window_close_hook, set_window_title
@eref exwindow, exdialog
On platforms that are capable of it, this routine disables or
enables the window close button for your Allegro program.
@retval
If the close button is successfully disabled, this function returns
zero. On platforms where...
===================================
============ Meta tags ============
===================================
_tx files previously used the <pre> and </pre> tags in source files to
generate preformatted text in HTML, which was used to represent code
which had to appear verbatim. Now with the use of optional CSS for HTML
code, the HTML tags needed to generate the appropriate effect are longer
than a simple <pre>. Makedoc provides some "macros" or "meta tags" which
you can use to avoid typing long HTML commands:
<textblock>
...
<endblock>
<codeblock>
...
<endblock>
<textblock> and <codeblock> will be converted to <blockquote class="text">
<pre> and <blockquote class="code"><pre> respectively. <endblock> will
expand to </pre></blockquote>. The good thing is that if you disable CSS
makedoc will expand them to only <pre> and </pre>.
The colors used by the text and code blocks depend on the taste of the
last person who hacked makedoc, so you can't rely on them to be
consistent through versions. Luckily, since 4.1.4, html output uses CSS
in an external file, meaning that it's easier for you to customize those
colors after the output has been generated.
Note that makedoc will overwrite the .css file with each generation.
Create somewhere a directory with your .css file and use a script after
each generation to copy only the .html files to this new directory. Of
course, compare your .css file to the one generated by makedoc after
Allegro releases, the css properties/names could have changed and you may
want to update your .css file to match the new version.
============================================
============ Special characters ============
============================================
You can't use directly '<' or '>' in your text. While makedoc is clever
and won't try to convert your text, HTML browsers could misunderstand
these characters. Therefore you have to use < for '<' and > for '>',
which will be replaced correctly for every possible output.
The '&' character also has a special meaning for HTML. However, since a
_tx file doesn't use this, it will always be replaced by '&' in the
HTML output and you won't have to care about this.
====================================
============ Conclusion ============
====================================
Hopefully this throws some light on the format. Consider this document
incomplete and subject to change. After all, makedoc can be considered as
a moving target, and if tomorrow the Allegro documentation needs to use
whatever feature, the format will change and you will have to rewrite
your _tx files. Sorry! At least makedoc will try to warn you about this.
![[logo]](/logo.png){kind=logo}