______ ___ ___ /\ _ \ /\_ \ /\_ \ \ \ \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
  • ,
    or 
     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=xxx
      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=Back to contents
      Old version of @html_footer, preserved for backwards compatibility.
      @html_footer puts the apropiate link tags around the text you provide.

   @f1=
    Back to Contents
    
      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 .

   @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 '
    ' to HTML output every time a 
  •  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,  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|readme.txt

   @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 
     and 
     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 
    . Makedoc provides some "macros" or "meta tags" which
   you can use to avoid typing long HTML commands:

   
   ...
   
   
   
   ...
   

    and  will be converted to 
    
   
     and 
     respectively.  will
   expand to 
    . The good thing is that if you disable CSS
   makedoc will expand them to only 
     and 
    .

   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.