[PYTHON DOC-SIG] New TIM tools, alpha-tester release

[Bill Janssen]

I've re-written our TIM tools, used for the ILU documentation, as a more
general Python script, instead of the extremely constrained Perl script
we were using.  If you'd like to try it out, and look for problems, it's
available as ftp://ftp.parc.xerox.com/pub/ilu/misc/tim.tar.gz.

If you aren't sure what TIM is, here's a bit from the README:

   TIM is essentially a superset of the GNU texinfo language, version 2.
It adds several features such as support for pictures and URLs, but its
most important extension is to provide domain-specific markup commands
to allow adding arbitrary meta-information to Texinfo documents.

Introduction
============

   Both TIM and Texinfo input files contain text `marked up' with
document markup commands.  These commands are similar to LaTeX
commands, except that they start with an at-sign character rather than
a backslash.  They contain  meta-information about the area of the text
to which they apply.  For example:
       A kernel server @dfn{export}s its objects by making them available
       to other modules.  It may do so via one or more @dfn{port}s, which are
       abstractly a tuple of (@metavar{rpc protocol}, @metavar{transport type},
       @metavar{transport address}).  For example, a typical port might
       provide access to a kernel server's objects via
@code{(@protocol{Sun RPC},
       @transport{TCP/IP}, UNIX port 2076)}.  Another port on the
       same kernel server might provide access to the objects via
       @code{(@protocol{Xerox Courier}, @transport{XNS SPP}, XNS port 1394)}.

When formatted, this paragraph would look like
     A kernel server exports its objects by making them available to
     other modules.  It may do so via one or more ports, which are
     abstractly a tuple of (RPC PROTOCOL, TRANSPORT TYPE, TRANSPORT
     ADDRESS).  For example, a typical port might provide access to a
     kernel server's objects via `(`Sun RPC', `TCP/IP', UNIX port
     2076)'.  Another port on the same kernel server might provide
     access to the objects via `(`Xerox Courier', `XNS SPP', XNS port
     1394)'.

Extensions to GNU Texinfo
=========================

   TIM removes the need to begin every file with `\input texinfo', and
to end every file with `@bye'.  These lines are added automatically by
TIM as needed.  This allows a file to define both a stand-alone
document, and to be included as a section in some larger document.

TIM Domain-Independent Format
-----------------------------

   TIM domain-independent format (DIF) is basically Texinfo with four
new built-in commands.  They are:

   * `@url', a style command, is used to mark World Wide Web URL forms
     that appear in the text.

   * `@picture', a command with arguments, is used to include an
     Encapsulated Postscript picture into the document.  It takes two
     arguments, the name of the file, and a caption for the picture.
     The caption may be omitted.

   * `@ttitalic', a style command, is used to indicate that this span
     should be rendered in an italic typewriter font, if available.

   * `@timmacro', a command with arguments, allows the user to define
     domain-specific markup commands.  The two arguments are the macro
     name, and the macro's replacement in vanilla DIF.  For example,
     to define a style command used to mark Python literals appearing
     in your document, you'd use a command like

          @timmacro Python code

     which defines a new style command `Python', which will be
     treated like the standard Texinfo command `code' for purposes
     of output formatting.


=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================