START-INFO-DIR-ENTRY
* Sgmltexi: (sgmltexi).    Sgmltexi
END-INFO-DIR-ENTRY

   Sgmltexi is an SGML system (DTD and tools) to make Texinfo
documentation using SGML. The Sgmltexi DTD is designed to follow most
of the Texinfo philosofy, hiding the node managing.

   Sgmltexi is to be intended as a simplified Texinfo using SGML; that
is: you cannot do all that it is possible with Texinfo alone. Sgmltexi
impose some restrictions, but maybe it can be simpler to write Texinfo
documentation this way.

   Copyright (C) 2000-2003 Daniele Giacomini <daniele@swlibero.org>

   Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, Version
1.1 or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the section
entitled "GNU Free Documentation License".

Short Contents
**************

Sgmltexi
Introduction to Sgmltexi
General structure for a Sgmltexi source file
Sectioning, nodes and menus
Block and in-line
Index and cross reference
Marking words and phrases
Marking block of text
List and tables
Insertions
Definitions
Conditional and literal back-end code
How to use the front-end
How to install
Dependencies
Encoding
Supported and unsupported Texinfo feature
Supported ISOnum entities: numeric and special graphic
Supported ISOpub entities: publishing
Supported ISOtech entities: general technical
Supported ISOlat1 entities: added latin 1
Supported ISOlat2 entities: added latin 2
GNU Free Documentation License
Index


Sgmltexi
********

   Sgmltexi is an SGML system (DTD and tools) to make Texinfo
documentation using SGML. The Sgmltexi DTD is designed to follow most
of the Texinfo philosofy, hiding the node managing.

   Sgmltexi is to be intended as a simplified Texinfo using SGML; that
is: you cannot do all that it is possible with Texinfo alone. Sgmltexi
impose some restrictions, but maybe it can be simpler to write Texinfo
documentation this way.

Introduction to Sgmltexi
************************

   Sgmltexi is a DTD with tools to get Texinfo. The idea is to have
another way to write Texinfo documents, intended to be a little bit
easier, but also with some limitations.

   Sgmltexi manages Texinfo nodes automatically, generating a an Info
menu at the Top node, and other menus if required. The node names may be
generated automatically with string like "chap 1", "app A" and so on, or
can be inserted manually, with different names.

   The Sgmltexi document has a precise scheme: there may be one or more
introductions, there is a body (made probably of chapters), there may be
appendixes and indexes. The body is organized into chapters, that may be
grouped into parts and also tomes. This way, also big documents are
easily managed.

   Sgmltexi is a work derived form ALtools and Alml, from the same
author. These are the SGML typesetting systems made for the need of an
Italian documentation project:
Appunti di informatica libera (http://a2.swlibero.org/).

Obtain Sgmltexi
===============

   At the moment, the main distribution source for Sgmltexi is the
following URI:

   `http://a2.swlibero.org/~daniele/software/sgmltexi/'

What's new about Sgmltexi
=========================

   The new Sgmltexi is simplified: the derivation system was removed,
and the Sgmltexi source files should be "expanded" to avoid the
horizontal tabs presence. The expansion is needed when reproducing
literal text, otherwise, strings like `\011' will appear, instead of
original tabs.

   This modification will reduce the pre-elaboration time, and will
avoid also some possible troubles with SGML files included inside the
main source.

   Please consider that this one might be the last release for
Sgmltexi, because the Texinfo development is taking different SGML/XML
paths.


General structure for a Sgmltexi source file
********************************************

   The typical Sgmltexi source start like this:

     <!DOCTYPE Sgmltexi PUBLIC "-//GNU//DTD Sgmltexi//EN">

   It can be useful to define also some internal entities, like this:

     <!DOCTYPE Sgmltexi PUBLIC "-//GNU//DTD Sgmltexi//EN"
     [
     <!ENTITY EDITION   "2003.10.11" >
     ...
     ...
     ]>

   All the document is enclosed inside the element `sgmltexi'. Inside,
there must be an `head' element, there may be an `intro' element, there
must be a `body' element, and there may be an `appendix' element. The
space after the `appendix' element may be occupied by some indexes
(will be shown later).

     <sgmltexi>
     <head>
     ...
     </head>
     <intro>
     ...
     </intro>
     <body>
     ...
     </body>
     <appendix>
     ...
     </appendix>
     </sgmltexi>

   The element `sgmltexi' has three possible attribute: `lang',
`charset' and `spacing'.

 - Attribute: lang
     This is a two letter code defining the text language. The use of
     this attribute generates a `@documentlanguage' command.


 - Attribute: charset
     This is the input character set, like it can be done with the
     Texinfo `@documentencoding' command. It is obscured by the
     `--input-encoding' option, that take precedence and generate a
     pure ISO 646 Texinfo output.


 - Attribute: spacing
     This is a deprecated feature that help controlling the spacing
     after sentences. It is deprecated because this action should be
     controlled with the language specific configuration. This attribute
     is here only as a last resort. Valid values are: `normal',
     `french' and `uniform'.  Selecting `french' or `uniform' it is
     introduced the command `@frenchspacing'.


     <sgmltexi lang="it" charset="ISO-8859-1" spacing="uniform">

`head'
======

   The `head' element is the more complicated. It is important to
define many informations about the document. Here it is the example
from this manual:

     <head>
         <admin>
             <setfilename content="sgmltexi.info">
             <settitle content="Sgmltexi">
             <setchapternewpage content="odd">
             <defindex name="sg">
             <syncodeindex from="sg" to="cp">
             <syncodeindex from="vr" to="cp">
             <infodir cat="Texinfo documentation system">
         </admin>
         <titlepage>
             <title>Sgmltexi</title>
             <subtitle>An alternative way to write Texinfo
             documentation</subtitle>
             <subtitle>This edition is for Sgmltexi
             &EDITION; for Texinfo 4</subtitle>
             <abstract>
                 <p>Sgmltexi is an SGML system (DTD and tools) to
                 make Texinfo documentation using SGML...</p>
                 ...
             </abstract>
             <author>Daniele Giacomini
             &lt;daniele@swlibero.org&gt;</author>
             <legal>
                 <copyright>Copyright &copy; 2000-2003 Daniele Giacomini
                 &lt;daniele@swlibero.org&gt;</copyright>
                 <publishnote>
                     <p>Published by...</p>
                 </publishnote>
                 <license>
                     <p>Permission is granted to make and distribute
                     verbatim copies of this manual...</p>
                     ...
                 </license>
                 <coverart>
                     <p>Cover art by ...</p>
                 </coverart>
             </legal>
         </titlepage>
         <shortcontents>
         <contents>
     </head>

   This is not all necessary, but it is a good starting point. Looking
at this example, can be recognized some important elements: `admin',
for administrative informations, and `titlepage'.

`admin'
=======

   The `admin' element is used to enclose some empty elements that
describe informations that should go inside the Texinfo header. The
order for these elements is not important, as Texinfo source will be
build in the right one. It follows a summary table and then the detailed
description.

*Element*   *Attribute* *Content*      *Description or Texinfo equivalence*
setfilename             empty          `@setfilename'
            content                    Info file name
settitle                empty          `@settitle'
            content                    title
setchapternewpage            empty          `@setchapternewpage'
            content     on, off, odd   tell how to separate chapters
footnotestyle            empty          `@footnotestyle'
            content     end, separate  where to place footnotes
headings                empty          `@headings'
            content     on, off,       how headings should work
                        single,        
                        double,        
                        singleafter,   
                        doubleafter    
defindex                empty          `@defindex'
            name                       define a two letter index name
defcodeindex            empty          `@defcodeindex'
            name                       define a two letter index name with
                                       `@code' items
synindex                empty          `@synindex'
            from                       source index, as a two letters name
            to                         destination index, as a two letters
                                       name
syncodeindex            empty          `@syncodeindex'
            from                       source index, as a two letters name
            to                         destination index, with `@code'
                                       items
infodir                 empty or       Info directory information
                        literal        
                        `@direntry'    
            cat                        The `@dircategory' argument

 - Element: setfilename
     This element is empty and is used to define the file name for
     Info, with the Texinfo command `@setfilename'.

      - Attribute: content
          This attribute is used to assign the file name.


     Use this element like this, only with the opening tag:

          <setfilename content="sgmltexi.info">


 - Element: settitle
     This element is empty and is used to define the title for Info,
     with the Texinfo command `@settitle'.

      - Attribute: content
          This attribute is used to assign the title.


     Use this element like this, only with the opening tag:

          <settitle content="Sgmltexi">


 - Element: setchapternewpage
     This element is empty and is used to define the Texinfo command
     `@setchapternewpage'.

      - Attribute: content
          This attribute is used to assign the desired value, that can
          be: `on', `off' or `odd'.


     Use this element like this, only with the opening tag:

          <setchapternewpage content="on">

     This element is not essential.


 - Element: footnotestyle
     This element is empty and is used to define the Texinfo command
     `@footnotestyle'.

      - Attribute: content
          This attribute is used to assign the desired value, that can
          be: `end' or `separate'.


     Use this element like this, only with the opening tag:

          <footnotestyle content="end">

     This element is not essential.


 - Element: heading
     This element is empty and is used to define the Texinfo command
     `@headings'.

      - Attribute: content
          This attribute is used to assign the desired value, that can
          be: `on', `off', `single', `double', `singleafter',
          `doubleafter'.


     Use this element like this, only with the opening tag:

          <headings content="double">

     This element is not essential.


 - Element: defindex
 - Element: defcodeindex
     These two empty elements are used to define the Texinfo commands
     `@defindex' and `@defcodeindex'.

      - Attribute: name
          This attribute is used to define the name of the new user
          index that is to be created. The name must be a two letter
          word.


     Use these elements like this, only with the opening tag:

          <defindex name="sg">

          <defcodeindex name="xx">

     These elements are used only as needed, for as many user defined
     index that are to be created.


 - Element: synindex
 - Element: syncodeindex
     These two elements are used to copy one index into another, like
     the command `@synindex' and `@syncodeindex' do with Texinfo.

      - Attribute: from
      - Attribute: to
          The first attribute is used to define the index to copy; the
          second is the index that receive the first one.


     Use this element like this, only with the opening tag:

          <syncodeindex from="fn" to="cp">

     This element is used only as needed, for as many user defined
     index that are to be created.


 - Element: infodir
     This element is used to define the Info directory menu item, when
     the file is installed with `install-info'.

      - Attribute: cat
          This attribute defines the category, like the Texinfo command
          `@dircategory' does.


     This element can be used empty, like this:

          <infodir cat="Texinfo documentation system">

     But this element can be used also more explicitly, like this:

          <infodir cat="Texinfo documentation system">
          * Sgmltexi: (sgmltexi).                SGML for Texinfo.
          * Sgmltexi install: (sgmltexi)install.  Install Sgmltexi.
          </infodir>

     This element is used only if needed. If the element is use empty,
     only one line inside the `@direntry' environment is inserted, with
     information already given.


`titlepage'
===========

   The `titlepage' element is used to enclose all informations that go
on the first pages of the document. The order of elements is important.
It follows a summary table and then the detailed description.

*Element*   *Attribute* *Content*      *Description or Texinfo equivalence*
title                   IN-LINE        `@title'
subtitle                IN-LINE        `@subtitle'
abstract                BLOCK          abstract of the document
author                  IN-LINE        `@author'
frontcovertext            BLOCK          text shown on the printed front
                                       cover
tpextra                 BLOCK          extra text shown inside title pages
legal                   copyright,     legal information
                        publishnote,   
                        license,       
                        coverart       
legal                   BLOCK          simplified legal information
copyright                              One copyright owner
publishnote             BLOCK          publishing note that should appear
                                       before the license
license                 BLOCK          license or reference to the
                                       license, or other conditions
                                       related to the document
coverart                BLOCK          coverart note that should appear
                                       after the license
dedications             BLOCK          dedications for a book

 - Element: title
     This element contains the document title; the title for the
     "printed" document. It is equivalent to `@title' for Texinfo. Use
     this element like this:

          <title>Sgmltexi</title>


 - Element: subtitle
     This element can be used to define one or more subtitles. It is
     equivalent to `@subtitle' for Texinfo. Use this element like this,
     after the title:

          <subtitle>An alternative way to write Texinfo documentation</subtitle>

     This element is used only as needed, without limitations.


 - Element: abstract
     This element can be used to define a brief description for the
     document. The content must be block text, like the element `p'.
     This text is used for Info typesetting, inside the Top node. Use
     this element like this:

          <abstract>
          
              <p>Sgmltexi is an SGML system (DTD and tools) to
              make Texinfo documentation using SGML.
              The Sgmltexi DTD is designed to...</p>
          
              <p>...</p>
          
          </abstract>

     This element can be used at most one time.


 - Element: author
     This element can be used to define one of the document authors.
     This element is equivalent to the Texinfo command `@author'. Use
     this element like this:

          <author>Tizio Tizi &lt;tizio@dinkel.brot.dg&gt;</author>
          <author>Caio Cai &lt;caio@dinkel.brot.dg&gt;</author>

     This element must be used at least one time.


 - Element: frontcovertext
     This element can be used to include one or more block of text,
     that should appear on the front cover, for the printed edition.
     Use this element like this:

          <frontcovertext>
          
              <p>Version 1.2.3</p>
          
              <p><image name="good-thing" height="5cm"></p>
          
          </frontcovertext>


 - Element: tpextra
     This element can be used to include one or more block of text,
     that should appear on different places: before the legal
     informations; after legal information; after the dedications. The
     name `tpextra' stand for "title page extra" text. Use this element
     like this:

          <tpextra>
          
              <p><strong>Pinco Pallino</strong> is a very old man...</p>
          
              <p><strong>Tizio Tizi</strong> studied telecommunication
              technology...</p>
          
          </tpextra>
          <legal>
              ...
              ...
          </legal>
          <tpextra>
          
              <p>The front cover picture is made by Sempronio.</p>
          
          </tpextra>
          <dedications>
              ...
              ...
          </dedications>
          <tpextra>
          
              <p>The software is very important; true free software is much more
              important.</p>
          
          </tpextra>

     The use of this element is optional, but notice that the last one
     can be used only if there is the dedications element before.


 - Element: legal
     This element is used to enclose other elements describing
     informations about copyright, license and publication.

      - Element: copyright
          This element contains a line of text describing the copyright
          owner for the document.


      - Element: publishnote
          This optional element, contains block of text that show
          information about the printed publication.


      - Element: license
          This element contains block of text to show the license
          conditions for the document.


      - Element: coverart
          This optional element, contains block of text that show who
          is responsible for the cover design.


     Use this element like this:

          <legal>
              <copyright>Copyright &copy; 2003 Free Software Foundation,
              Inc.</copyright>
              <publishnote>
                  <p>Published by...</p>
              </publishnote>
              <license>
                  <p>Permission is granted to copy, distribute and/or
                  modify this document under the terms of the GNU Free
                  Documentation License, Version 1.1 or any later version
                  published by the Free Software Foundation; with no
                  Invariant Sections, with no Front-Cover Texts, and with
                  no Back-Cover Texts. A copy of the license is included
                  in the section entitled "GNU Free Documentation
                  License".</p>
              </license>
              <coverart>
                  <p>Cover art by ...</p>
              </coverart>
          </legal>

     This element must be used at least one time.

     Actually, this element can have non special internal structure,
     enclosing simply other block elements. This way, if the standard
     structure described above is not good for the author intention, it
     may be used also like this:

          <legal>
              <p>Copyright &copy; 2003 Free Software Foundation, Inc.</p>
          
              <p>Published by...</p>
          
              <p>Permission is granted to copy, distribute and/or modify this
              document under the terms of the GNU Free Documentation License,
              Version 1.1 or any later version published by the Free Software
              Foundation; with no Invariant Sections, with no Front-Cover Texts,
              and with no Back-Cover Texts. A copy of the license is included in
              the section entitled "GNU Free Documentation License".</p>
          
              <p>Cover art by ...</p>
          </legal>


 - Element: dedications
     This optional element, contains block of text that show one or
     more dedications.


Table of contents
=================

   After the `titlepage', there is the place for one or more table of
contents. To obtain the insertion of these table of contents can be
used one of the following empty element.

 - Element: contents
     The standard table of contents, like the command `@contents' for
     Texinfo.


 - Element: shortcontents
 - Element: summarycontents
     A reduced table of contents, like the command `@shortcontents' and
     `@summarycontents' for Texinfo.


`menu'
======

   After the contents elements, may appear the `menu' element. This
element ask explicitly for the correspondent Texinfo `@menu' command.
At this level, the menu is inserted automatically, also without
inserting this element. But the `menu' element may be used to define a
specific (manual) menu for texinfo. See the following example:

     <menu>
     * introduction ::   Introduction
     * structure::       General structure for a Sgmltexi source file
     * how to use::      How to use the front-end
     * install::         How to install
     * GFDL::            GNU Free Documentation License
     * index::           Index
     </menu>

   The `menu' may be used also at chapter level and below, and there
can be also empty: in this case, an automatic Texinfo menu will be
inserted.

`intro'
=======

   After the `head' element there may be one `intro' element. This is
just a way to define a group of chapter that have no numbering.
Chapters inside this element are delimited in the same way as for the
`body' and `appendix' elements.

     <intro>
     <h1>Introduction to Sgmltexi</h1>
     
     <p>Sgmltexi is a DTD with tools to get Texinfo...</p>
     
     <p>Sgmltexi manage Texinfo nodes automatically,...</p>
     
     </intro>

`body'
======

   After the `head' and `intro' elements, there must be one `body'
element. This is the body of the document.

   The body may be divided into chapters, or parts, or tomes, depending
on the documentation project that is started. Tomes are delimited with
the element `tomeheading', that contains the tome title; parts are
delimited using the element `partheading', with the same meaning.

   Chapters and lower sectioning are a little anonymous, like HTML:
`h1', `h2', `h3' and `h4'.  This is done that way because introduction,
body and appendix may have the same method for text sectioning.

     <body>
     <partheader>Networking</partheader>
     
     <h1>IP protocol history</h1>
     
     <p>Bla bla bla...</p>
     
     <p>Bla bla bla...</p>
     
     <h2>ISO/OSI model</h2>
     
     <p>Bla bla bla...</p>
     
     <p>Bla bla bla...</p>
     
     <h1>IPv4 and IPv6</h1>
     
     <p>Bla bla bla...</p>
     
     <p>...</p>
     
     </body>

   Every sectioning element, from tome to last sub-subsection, have an
optional attribute: `id'. This attribute may be used to define an
identification string that can be the target for cross references.

     <h1 id="ip history">IP protocol history</h1>

   Note that due to Texinfo design limitations, cross references labels
cannot contain the comma.


`appendix'
==========

   After the body, it may be placed the `appendix'. This one is used to
delimit a group of chapters that must be intended as appendixes. This
way, also the appendix is organized in chapter delimited with `h1'
heading, and smaller sections.

Indexes
=======

   After the body and after the optional appendix, can be placed one or
more analytic index. This is obtained with a special heading element:
`indexheading'. This can be used only in conjunction with `printindex'
to define the type of index to include. The example should be clear
enough:

     ...
     <indexheading>Index of functions</indexheading>
     <printindex name="fn">
     <indexheading>Concept index</indexheading>
     <printindex name="cp">
     ...
     </sgmltexi>

   As can be seen from the example, `printindex' has an attribute,
`name', that tells the type of index to include.  In fact, this way is
generated the Texinfo command `@printindex'.

Sectioning, nodes and menus
***************************

   To write good documentation with Texinfo, it is required to have
control on nodes and menus. With Sgmltexi, nodes and menus can be
forgotten, but the Info result may suffer for this choice. Anyway, with
Sgmltexi it is possible to choose different levels of manual/automatic
node handling.

   Headings elements can incorporate some more attributes: `node' and
`menu'. The first one define the node name, overriding any automatic
determination; the second define the node description on the menu (the
automatical choice is otherwise the title).

     <h1 id="ip history" node="history" menu="History of IP protocol">
     IP protocol history</h1>

   This will generate on the Info menu, the following line:

     * history::         History of IP protocol

   The `node' and `menu' attribute may be used independently: the
attribute that is not used, will be determined automatically.

   Having access to nodes, it is possible to use them for cross
reference, without the need for the `id' attribute.

   Sgmltexi creates automatically the Top node menu. As already
explained before (*note top node menu::), the menu can be explicitly
defined. In this way, all nodes and descriptions must be made manually.

   Inserting the `menu' element at the bottom of a chapter, or at a
lower section, will ask an insertion of a lower Info menu. See the
example:

     <h1>IP protocol history</h1>
     
     <p>Bla bla bla...</p>
     
     <p>Bla bla bla...</p>
     
     <menu>
     
     <h2>ISO/OSI model</h2>
     
     <p>Bla bla bla...</p>
     
     <p>Bla bla bla...</p>
     
     <h2>More information</h2>
     
     <p>Bla bla bla...</p>
     
     <p>...</p>

   The example shows the insertion of an automatic Info menu before
`h2' sections. This menu may otherwise be described completely, like
this:

     <menu>
     * IP layer::        IP ISO/OSI layer model
     * more on IP::      More details on IP
     </menu>

   When the menu is described this way, node names must be the same as
the one used with the heading elements. That is: when writing the menu,
also nodes must be exactly declared, like this:

     <h1>IP protocol history</h1>
     
     <p>Bla bla bla...</p>
     
     <p>Bla bla bla...</p>
     
     <menu>
     * IP layer::        IP ISO/OSI layer model
     * more on IP::      More details on IP
     </menu>
     
     <h2 node="IP layer">ISO/OSI model</h2>
     
     <p>Bla bla bla...</p>
     
     <p>Bla bla bla...</p>
     
     <h2 node="more on IP">More information</h2>
     
     <p>Bla bla bla...</p>
     
     <p>...</p>

   It is evident that a `menu' attribute (like `<h2 menu="Much more
information">') has no effect in this case.

*Element*   *Attribute* *Content*      *Description or Texinfo equivalence*
tomeheading             IN-LINE        title of a tome
partheading                            title of a part
h1                      IN-LINE        title of a chapter, introduction or
                                       appendix
h2                      IN-LINE        title of a section
h3                      IN-LINE        title of a subsection
h4                      IN-LINE        title of a sub-subsection
indexheading            IN-LINE        title of an analytic index
            node                       Info node name
            menu                       Info node description
            next                       Next node name
            prev                       Previous node name
            up                         Up node name
            type        numbered,      type of section, for `h1' to `h4'
                        unnumbered,    elements
                        heading        

Unnumbered sections and simple headings
=======================================

   Elements `h1', `h2', `h3' and `h4' may have an additional attribute:
`type'. The keywords `numbered', `unnumbered' and `heading' may be
assigned. `numbered' is the default value; it means that the title will
be numbered (with numbers if inside `body', with letters if inside
`appendix').  Assigning `unnumbered', the titles are not numbered.
Assigning `heading', the titles are not numbered and not annotated
inside the table of context.

     <h1 type="unnumbered">Acknowledgements</h1>
     ...

   Inside the `intro' elements, titles cannot be numbered: it is
explicitly excluded.

Block and in-line
*****************

   Sgmltexi has a DTD where most of the elements are divided into two
categories, block and in-line, with the help of two parameter entities:
`block' and `inline' (SGML macro are `%block;' and `%inline;').

   A block is something like a paragraph, a list, a table; an in-line
is text, text emphatisation, anchors, cross references, and other
things that stay inside a text.

   Usually, but not necessarily, an in-line element contains text and
possibly other in-line elements; but a block element may be made to
contain in-line or other blocks. The Sgmltexi DTD don't consider the
possibility of block elements that may contain either block or in-line.
These kinds of contents are known as "flow" (this name is used inside
the HTML DTD) and are rarely useful.

   Some block elements, like `example', may contain block elements or a
single `pre' element (a special block element not classified as part of
the `%block;' macro). The `pre' element can contain only in-line that
is preformatted, that is: it maintains line breaks.

   The two basic block element are shown in the following table:

*Element*   *Attribute* *Content*      *Description or Texinfo equivalence*
p                       IN-LINE        paragraph, or simple block of text
            indent      `on', `off'    first line indentation; default is
                                       `on'
center                  IN-LINE        `@center'

Index and cross reference
*************************

   There are different kind of insertions for making indexes and cross
references, that reproduce equivalent Texinfo commands.

Indexes
=======

   Index entries are inserted with a group of empty elements: `cindex',
`findex', `vindex', `kindex', `pindex', `tindex' and `userindex'. All
these elements have the same attribute, `entry', that define the item
text to be inserted. The `userindex' has an additional attribute, to
define the user index name (that should be made of two letters).

   These elements are a kind of block that may be inserted just after
any sectioning title, like this:

     <h1>IP protocol history</h1>
     <cindex entry="IP protocol">
     <cindex entry="history">
     
     <p>Bla bla bla...</p>

   The following table resumes the meaning for so many different index
entry elements.

*Element*   *Attribute* *Content*      *Description or Texinfo equivalence*
cindex      entry       empty          concept index item
findex      entry       empty          function index item
vindex      entry       empty          variable index item
kindex      entry       empty          keystroke index item
pindex      entry       empty          program index item
tindex      entry       empty          data type index item
userindex   entry       empty          user defined index item
            name                       user defined index name (two
                                       letters)
printindex  name                       print the named index (two letters)

   The index is inserted with the element `printindex', already
described. Standard index names are listed in the following table.

*Index name*   *Description*
cp             concept index.
ky             keystroke index.
pg             program index.
fn             function index.
vr             variable index.
tp             data type index.

Cross references
================

   Cross reference elements are all in-line empty elements. All
information is given via attributes. As all cross reference elements are
implementations of equivalent Texinfo commands, there is only the
following table as description. Every attribute description follow its
own element. Please note that not all attributes are necessary.

*Element*   *Attribute* *Content*      *Description or Texinfo equivalence*
anchor                  empty          `@anchor'
            id                         anchor identity string
xref                    empty          `@xref'
            id                         node or anchor name
            name                       cross reference name
            title                      title or topic
            info                       info file name
            ptitle                     printed manual title
ref                     empty          `@ref'
            id                         node or anchor name
            name                       cross reference name
            title                      title or topic
            info                       info file name
            ptitle                     printed manual title
pxref                   empty          `@pxref'
            id                         node or anchor name
            name                       cross reference name
            title                      title or topic
            info                       info file name
            ptitle                     printed manual title
inforef                 empty          `@inforef'
            id                         node or anchor name
            name                       cross reference name
            info                       info file name
uref                    empty          `@uref'
            uri                        URI address
            name                       title or description
            replace                    replacement text
email                   empty          `@email'
            email                      electronic mail address
            name                       title or description

   Use like this:

     <p>Sgmltexi creates automatically the Top node menu. As already
     explained before (<pxref id="top node menu">), the menu can be
     ...

Marking words and phrases
*************************

   A lot of in-line elements are used to mark words or phrases.
Actually, the DTD is very permissive, so that every element of these can
contain any in-line element. It is so only to assure compatibility with
Texinfo, but may change in the future. The following table list these
elements, included `kbdinputstyle', used to select the style for the
`kbd' element.

*Element*   *Attribute* *Content*      *Description or Texinfo equivalence*
code                    IN-LINE        `@code'
kbd                     IN-LINE        `@kbd'
kbdinputstyle            empty          `@kbdinputstyle'
            style       `code',        how to show keyboard input style;
                        `example',     default is `distinct'
                        `distinct'     
key                     IN-LINE        `@key'
samp                    IN-LINE        `@samp'
var                     IN-LINE        `@var'
env                     IN-LINE        `@env'
file                    IN-LINE        `@file'
command                 IN-LINE        `@command'
option                  IN-LINE        `@option'
dfn                     IN-LINE        `@dfn'
cite                    IN-LINE        `@cite'
acronym                 IN-LINE        `@acronym'
url                     IN-LINE        `@url'
emph                    IN-LINE        `@emph'
strong                  IN-LINE        `@strong'
sc                      IN-LINE        `@sc'
roman                   IN-LINE        `@r'
italic                  IN-LINE        `@i'
bold                    IN-LINE        `@b'
typewriter              IN-LINE        `@t'

   Use like this:

     <p><strong>Pinco Pallino</strong> is a very old man...</p>
     
     <p><strong>Tizio Tizi</strong> studied telecommunication
     technology...</p>

Marking block of text
*********************

   Some block elements are used to mark other block of text or special
kind of in-line text. The DTD is very permissive, to assure maximum
compatibility with Texinfo, but this may change in the future. The
following table list these elements, included the special element
`pre', used to insert in-line preformatted text, and `exdent', used
inside `pre' to obtain an exdented line.

*Element*   *Attribute* *Content*      *Description or Texinfo equivalence*
exdent                  IN-LINE        `@exdent'
pre                     IN-LINE        preformatted text
quotation               BLOCK          `@quotation'
display                 BLOCK or `pre' `@display'
smalldisplay            BLOCK or `pre' `@smalldisplay'
example                 BLOCK or `pre' `@example'
smallexample            BLOCK or `pre' `@smallexample'
flushleft               IN-LINE        `@flushleft'
flushright              IN-LINE        `@flushright'
lisp                    BLOCK or `pre' `@lisp'
smalllisp               BLOCK or `pre' `@smalllisp'
cartouche               BLOCK or `pre' `@cartouche'
format                  BLOCK or `pre' `@format'
smallformat             BLOCK or `pre' `@smallformat'
texinfo                 literal        embedded literal Texinfo code
                        Texinfo        

   Use like this:

     <example>
     <p>Hello everybody</p>
     <p>Hello to the world</p>
     </example>

   In this case the `example' element contains preformatted text
(please not the use of two SGML entities, `lt' and `gt'):

     <example>
     <pre>
     #!/usr/bin/perl
     while ($line = &lt;STDIN&gt;)
       {
         chomp $line;
         print ("$line\r\n");
       }
     </pre>
     </example>

   If it is necessary to include a preformatted literal text, do like
this (please note that there is no need to hide `<' and `>'):

     <example>
     <pre>
     <![CDATA[
     #!/usr/bin/perl
     while ($line = <STDIN>)
       {
         chomp $line;
         print ("$line\r\n");
       }
     ]]>
     </pre>
     </example>

List and tables
***************

   List and tables are block elements. The following table list the
elements used to implement list and tables.

*Element*   *Attribute* *Content*      *Description or Texinfo equivalence*
itemize                 `item',        `@itemize'
                        `itemx', BLOCK 
            mark                       mark before items; default is
                                       `&bull;'
enumerate               `item',        `@enumerate'
                        `itemx', BLOCK 
            start                      starting number
table                   `item',        `@table'
                        `itemx', BLOCK 
            emphasis    `asis',        emphasis for the descriptive item
                        `code',        
                        `samp',        
                        `var', `kbd',  
                        `file'         
vtable                  `item',        `@vtable'
                        `itemx', BLOCK 
            emphasis    `asis',        emphasis for the descriptive
                        `code',        variable item
                        `samp',        
                        `var', `kbd'   
ftable                  `item',        `@ftable'
                        `itemx', BLOCK 
            emphasis    `asis',        emphasis for the descriptive
                        `code',        function item
                        `samp',        
                        `var', `kbd'   
item                    IN-LINE or     `@item'
                        empty          
itemx                   IN-LINE or     `@itemx'
                        empty          
multitable              `columnfraction'`@multitable'
                        or             
                        `columnexample';
                        `raw'          
columnfraction            .N             column fraction, where ".N" is the
                                       0.N fraction of the horizontal space
columnexample            pure text      column fraction, where the inserted
                                       text gives the example of the
                                       column extention
raw                     IN-LINE, `tab' row of the table
tab                     empty          column separation

   It follows some examples; first an unnumbered list:

     <itemize mark="#">
     <item>
     
         <p>First item.</p>
     
     <item>
     
         <p>Second item.</p>
     
     </itemize>

   Here is the result:

   # First item.

   # Second item.


   Here is a numbered list:

     <enumerate start="3">
     <item>
     
         <p>First item.</p>
     
     <item>
     
         <p>Second item.</p>
     
     </enumerate>

   Here is the result:

  3. First item.

  4. Second item.


   Here is a descriptive list:

     <table emphasis="code">
     <item>ls</item>
     <itemx>dir</itemx>
         <p>List directory contents.</p>
     <item>cd</item>
         <p>Change directory.</p>
     </table>

   Here is the result:

`ls'
`dir'
     List directory contents.

`cd'
     Change directory.

Insertions
**********

   Here are described some mixed elements that have not found a better
place. There are two types of such insertions: in-line and block
insertions. The first of the following tables list the in-line elements
and the second the block elements.

*Element*   *Attribute* *Content*      *Description or Texinfo equivalence*
dmn                     parsed         `@dmn'
                        character data 
math                    parsed         `@math'
                        character data 
footnote                IN-LINE        `@footnote'
image                   empty          `@image'
            name                       file name to be inserted (without
                                       extention)
            width                      image width
            height                     image height
whole                   IN-LINE        `@w' (preventing line break)
br                      empty          `@*' (line break)
dh                      empty          `@-' (discretionary hyphen)
hyphenation             empty          `@hyphenation'
            words                      list of hy-phen-a-ted words

*Element*   *Attribute* *Content*      *Description or Texinfo equivalence*
sp                      empty          `@sp'
            lines                      skip N lines
page                    empty          `@page'
group                   BLOCK          `@group'
need                    empty          `@need'
            mils                       thousandths of inch

Definitions
***********

   Here are described the elements implementing Texinfo definitions.

*Element*   *Attribute* *Content*      *Description or Texinfo equivalence*
args                    IN-LINE        argument of a definition
deffn                   `args', BLOCK  `@deffn'
            cat                        function category
            name                       function name
deffnx                  empty          `@deffnx', attributes like `deffn'
defun                   `args', BLOCK  `@defun'
            name                       function name
defunx                  empty          `@defunx', attributes like `defun'
defmac                  `args', BLOCK  `@defmac'
            name                       macro name
defmacx                 empty          `@defmacx', attributes like `defmac'
defspec                 `args', BLOCK  `@defspec'
            name                       special form name
defspecx                empty          `@defspecx', attributes like
                                       `defspec'
defvr                   BLOCK          `@defvr'
            cat                        variable category
            name                       variable name
defvrx                  empty          `@defvrx', attributes like `defvr'
defvar                  BLOCK          `@defvar'
            name                       variable name
defvarx                 empty          `@defvarx', attributes like `defvar'
defopt                  BLOCK          `@defopt'
            name                       option name
defoptx                 empty          `@defoptx', attributes like `defopt'
deftypefn               `args', BLOCK  `@deftypefn'
            cat                        category
            type                       data type
            name                       name
deftypefnx              empty          `@deftypefnx', attributes like
                                       `deftypefn'
deftypefun              `args', BLOCK  `@deftypefun'
            type                       data type
            name                       name
deftypefunx             empty          `@deftypefunx', attributes like
                                       `deftypefun'
deftypevr               BLOCK          `@deftypevr'
            cat                        category
            type                       data type
            name                       name
deftypevrx              empty          `@deftypevrx', attributes like
                                       `deftypevr'
deftypevar              BLOCK          `@deftypevar'
            data type                  type
            name                       name
deftypevarx             empty          `@deftypevarx', attributes like
                                       `deftypevar'
defcv                   BLOCK          `@defcv'
            cat                        category
            class                      class
            name                       name
defcvx                  empty          `@defcvx', attributes like `defcv'
defivar                 BLOCK          `@defivar'
            class                      class
            name                       name
defivarx                empty          `@defivarx', attributes like
                                       `defivar'
deftypeivar             BLOCK          `@deftypeivar'
            class                      class
            type                       type
            name                       name
deftypeivarx            empty          `@deftypeivarx', attributes like
                                       `deftypeivar'
defop                   `args', BLOCK  `@defop'
            cat                        category
            class                      class
            name                       name
defopx                  empty          `@defopx', attributes like `defop'
deftypeop               `args', BLOCK  `@deftypeop'
            cat                        category
            class                      class
            type                       type
            name                       name
deftypeopx              empty          `@deftypeopx', attributes like
                                       `deftypeop'
defmethod               `args', BLOCK  `@defmethod'
            class                      class
            name                       name
defmethodx              empty          `@defmethodx', attributes like
                                       `defmethod'
deftypemethod            `args', BLOCK  `@deftypemethod'
            class                      class
            type                       type
            name                       name
deftypemethodx            empty          `@deftypemethodx', attributes like
                                       `deftypemethod'
deftp                   `args', BLOCK  `@deftp'
            cat                        category
            name                       name
deftpx                  empty          `@deftpx', attributes like `deftp'

   It follows an example about the use of `deffn':

     <deffn cat="Command" name="sgmltexi">
         <args>[<var>options</var>]... <var>sgml_source</var></args>
     
         <p>This is the front-end for the SGML to Texinfo system.</p>
     
     </deffn>

   Here is the result:

 - Command: sgmltexi [OPTIONS]... SGML_SOURCE
     This is the front-end for the SGML to Texinfo system.


Conditional and literal back-end code
*************************************

   Texinfo has a special handling capability to select code depending
on the final typesetting. Things like these can be done with SGML using
marked sections, but it is not exactly the same thing.  Sgmltexi
includes some special elements to implement the conditional code
insertion used inside Texinfo, and allow to insert also some peace of
literal code.

*Element*   *Attribute* *Content*      *Description or Texinfo equivalence*
ifinfo                  IN-LINE        `@ifinfo' ... `@end ifinfo'
ifinfoblock             BLOCK          `@ifinfo' ... `@end ifinfo'
iftex                   IN-LINE        `@iftex' ... `@end iftex'
iftexblock              BLOCK          `@iftex' ... `@end iftex'
ifhtml                  IN-LINE        `@ifhtml' ... `@end ifhtml'
ifhtmlblock             BLOCK          `@ifhtml' ... `@end ifhtml'
ifplaintext             IN-LINE        `@ifplaintext' ...
                                       `@end ifplaintext'
ifplaintextblock            BLOCK          `@ifplaintext' ...
                                       `@end ifplaintext'
ifxml                   IN-LINE        `@ifxml' ... `@end ifxml'
ifxmlblock              BLOCK          `@ifxml' ... `@end ifxml'
ifnotinfo               IN-LINE        `@ifnotinfo' ... `@end ifnotinfo'
ifnotinfoblock            BLOCK          `@ifnotinfo' ... `@end ifnotinfo'
ifnottex                IN-LINE        `@ifnottex' ... `@end ifnottex'
ifnottexblock            BLOCK          `@ifnottex' ... `@end ifnottex'
ifnothtml               IN-LINE        `@ifnothtml' ... `@end ifnothtml'
ifnothtmlblock            BLOCK          `@ifnothtml' ... `@end ifnothtml'
ifnotplaintext            IN-LINE        `@ifnotplaintext' ...
                                       `@end ifnotplaintext'
ifnotplaintextblock            BLOCK          `@ifnotplaintext' ...
                                       `@end ifnotplaintext'
ifnotxml                IN-LINE        `@ifnotxml' ... `@end ifnotxml'
ifnotxmlblock            BLOCK          `@ifnotxml' ... `@end ifnotxml'
tex                     parsed         `@tex' ... `@end tex'
                        character data 
html                    parsed         `@html' ... `@end html'
                        character data 
texinfo                 parsed         Raw Texinfo code.
                        character data 

   Please note that `ifinfo', `iftex', `ifhtml', `ifplaintext', `ifxml',
`ifnotinfo', `ifnottex', `ifnothtml', `ifnotplaintext' and `ifnotxml',
are in-line elements that contain in-line text. On the other side,
`ifinfoblock', `iftexblock', `ifhtmlblock', `ifplaintextblock',
`ifxmlblock', `ifnotinfoblock', `ifnottexblock', `ifnothtmlblock',
`ifnotplaintextblock' and `ifnotxmlblock', are block elements that
contain block text.

   The distinction between `if...' and `if...block' is necessary to
avoid trouble with the SGML document type declaration.

   The in-line elements `tex', `html' and `texinfo', are made to
contain in-line literal text, usually enclosed inside `<![CDATA[' and
`]]>'.

   The element `texinfo' has no equivalence inside Texinfo, as it
represent just raw Texinfo code. See the following example:

     <p>The letter <texinfo>@ubaraccent{o}</texinfo> is a special...</p>

   It may be necessary to force literal reading, as for SGML. In this
case, the element content can be enclosed like this:

     <p>The letter <texinfo><![CDATA[@ubaraccent{o}]]></texinfo> is a...

   The example doesn't show any real reason to put the text inside a
CDATA environment, but there are other situations where it will be
necessary.

   It follows another example on the use of literal back-end code. The
intention is to show a simple mathematical expression: 123 + 10^(-1).


         <p><tex><![CDATA[$123+10^{-1}$]]></tex>
         <html><![CDATA[123+10<sup>-1</sup>]]></html>
         <ifinfo>123+10^-1</ifinfo>
         = 12.3</p>

   As current typesetting is made for Info the result is as it follows:

     123+10^-1 = 12.3


Troubles
========

   Texinfo, like TeX and *roff, distinguishes blocks because these are
separated from one or more lines. This way, the distinction between
blocks and in-lines is only a matter of vertical space. For example, the
following peace of Texinfo source shows three environments
`@ifTYPESETTING', which are part of the same block of text (the same
paragraph). That is: in-line.

     Current typesetting is
     @iftex
     TeX
     @end iftex
     @ifhtml
     HTML
     @end ifhtml
     @ifinfo
     Info
     @end ifinfo
     and you can see that...

   But in a different situation, these environments can became isolated
block of text, like this:

     Current typesetting is:
     
     @iftex
     TeX
     @end iftex
     
     @ifhtml
     HTML
     @end ifhtml
     
     @ifinfo
     Info
     @end ifinfo
     
     You can see that...

   With SGML this is not desirable, and difficult to implement. This is
the reason why Sgmltexi distinguishes from `@ifTYPESETTING' or
`@ifnotTYPESETTING', and `@ifTYPESETTINGblock' or
`@ifnotTYPESETTINGblock'.

   Sgmltexi try to preserve line breaks inside the SGML source, but in
this case, there is a consequence on the use of such conditional in-line
environments. This happens because Texinfo requires these commands to
lay alone on a single line. That is, if we would like to write something
like this:

     <p>Current typesetting
     is <iftex>TeX</iftex><ifhtml>HTML</ifhtml><ifinfo>Info</ifinfo>, so
     you know what I mean.</p>

   we expect that opening and closing tags will introduce proper line
breaks. But if it were so, the result would be the following,
transforming original in-line into undesired final block:

     Current typesetting is
     @iftex
     TeX
     @end iftex
     
     @ifhtml
     HTML
     @end ifhtml
     
     @ifinfo
     Info
     @end ifinfo
     , so you know what I mean.

   To resolve this problem, these in-line conditional tags don't
introduce any initial and final line break: it is up to the author to
think about this problem. This way, Sgmltexi must be used in the
following way, considering that there is no way to put the comma after
the typesetting name:

     <p>Current typesetting is
     <iftex>TeX</iftex>
     <ifhtml>HTML</ifhtml>
     <ifinfo>Info</ifinfo>
     so you know what I mean.</p>

   The same problem happens with `tex' and `html' elements, but in this
case there is no need to distinguish the content, that is meant to be
always in-line.

     <p>
     <tex>
     $$ \chi^2 = \sum_{i=1}^N
               \left (y_i - (a + b x_i)
               \over \sigma_i\right)^2 $$
     </tex>
     </p>

   When using SGML, inserting literal back-end code is just a last
resort that breaks standardization. In other words, if it is necessary
to use such expedient, maybe the SGML is the wrong choice for writing
documentation.


How to use the front-end
************************

   When the Sgmltexi source is ready, all that is needed is the program
`sgmltexi' to control the SGML parser and other elaborations.

 - Command: sgmltexi [OPTIONS]... SGML_SOURCE
     This is the front-end for the SGML to Texinfo system.


`--help'
     Display a brief help and exit.

`--version'
     Display version information and exit.

`--verbose'
     Display processing information.

`--force'
     Force things.

`--number-sections'
     Number sections for Info and HTML typesetting.

`--clean'
     Remove stale files associated with the source name.

`--input-encoding=ENCODING'
     Define an input encoding that will be converted automatically into
     entities. This option take precedence over the attribute `charset'
     of the `sgmltexi' element. Using this option the Texinfo source
     will be pure ASCII, and the command `@documentencoding' is used
     with the argument `ISO-646'.

     Available encodings are: `ISO-8859-1', `ISO-8859-2', ...
     `ISO-8859-10'. All encodings are not fully supported, because of
     Texinfo limitations. Unsupported codes are shown with the name of
     the corresponding standard entity, like this: `[ETH   ]'.

`--sgml-include=PARAMETER-ENTITY'
`--include=PARAMETER-ENTITY'
     Assign the word `INCLUDE' to an SGML parameter entity.

`--paper=PAPER'
     Define the paper format: `letter', `a4', `a4wide', `a4latex',
     `small'.

`--setchapternewpage={on|off|odd}'
     Define the chapter paper feed, overriding the tag
     `<setchapternewpage content="...">' inside the source.

`--footnotestyle={end|separate}'
     Define the footnote location, overriding the tag `<footnotestyle
     content="...">' inside the source.

`--sgml-syntax'
`--sgml-check'
     Check SGML syntax and report errors.

`--sp'
     SP output for debugging purpose.

`--texi'
`--texinfo'
     Generate a Texinfo source output.

`--dvi'
     Generate a DVI output.

`--ps'
`--postscript'
     Generate a PostScript output.

`--pdf'
     Generate a PDF output.

`--info'
     Generate an Info output.

`--text'
     Generate a text output.

`--html'
     Generate an HTML output.

`--xml'
     Generate a Texinfo XML output.

`--docbook'
     Generate a Docbook XML output.

   Each elaboration generates a file with `.diag' extention.  This file
contains the messages that may be shown with the option `--verbose'.

How to install
**************

   Sgmltexi is made of two Perl executables: `sgmltexi' and
`sgmltexi-sp2texi'. These files can be placed everywhere they can run
without giving the path; that is: inside a directory listed by the
environment variable `PATH'.

   It is needed Perl as `/usr/bin/perl'. If your system is organized
differently, you should modify the first line of these executables:

     #!/usr/bin/perl
     #...

   Sgmltexi expect to find some files:

`/usr/share/sgmltexi/sgmltexi.cat'
     the Sgmltexi SGML catalog;

`/usr/share/sgmltexi/sgmltexi.dcl'
     the Sgmltexi SGML declaration;

`/usr/share/sgmltexi/sgmltexi.dtd'
     the Sgmltexi DTD;

`/usr/share/sgmltexi/entities/'
     the directory containing the standard ISO 8879 entity files.

   All these files may be exactly where expected or there may be
symbolic links to recreate the expected files.

Gettext
=======

   The messages that Sgmltexi shows may be translated. To install the
already translated PO files, it is necessary to compile them like this:

     msgfmt -o sgmltexi.mo it.po

   In this example the file `it.po' is compiled and it is generated the
file `sgmltexi.mo'. This generated file must be copied inside the right
directory; in this case, may be `/usr/share/locale/it/LC_MESSAGES/'.

   If you don't have installed the Perl-gettext module and you don't
want to worry about it, you can comment the following instructions:

     # We *don't* want to use gettext.
     #use POSIX;
     #use Locale::gettext;
     #setlocale (LC_MESSAGES, "");
     #textdomain ("sgmltexi");

   Then you have to introduce a dummy `gettext()' function:

     sub gettext
     {
         return $_[0];
     }

Dependencies
************

   Sgmltexi depends on the following external software:

Perl
     the Perl interpreter;

SP
Jade
     the SGML parser known as SP, that may also be included inside Jade;

Perl-gettext
     a Perl module that include Gettext support;

Texinfo
TeX
     to get a final typesetting.

Encoding
********

   Sgmltexi has an incomplete support for ISO 8859-n encodings. It is
incomplete because Texinfo is not able to reproduce all characters.
There are two ways to define the use of one encoding with Sgmltexi: the
option `--input-encoding' and the attribute `charset' inside the
`sgmltexi' element.

   The choice has a different result. The option `--input-encoding'
generate a transformation of characters into SGML entities, and back to
Texinfo code. This way, the Texinfo code is surely pure ASCII (ISO
646), and entities that have no corresponding Texinfo code, are shown
like `[ETH   ]'. The use of the `charset' attribute results only on the
command `@documentencoding'; on some occasions, the result may be good
or not. Depending on the better result, it may be used one option or
the other.

   A good strategy may be the use of the `charset' attribute in any
case, adding the option `--input-encoding' when Texinfo doesn't
generate a good result alone, usually when typesetting for printing.

Standard and non-standard entities
==================================

   Sgmltexi DTD include all standard ISO 8879 entities (*Note ISOnum::,
*Note ISOpub::, *Note ISOtech::, *Note ISOlat1::, *Note ISOlat2::). In
fact, non all entities are really supported by Texinfo, and when an
unsupported entity is used, it is shown on the final typesetting like a
name enclosed inside square brackets, like `[ETH   ]'.

   Sgmltexi uses some non-standard entities, needed for compatibility
with Texinfo. These are shown on the following table.

*SGML macro*   *Texinfo       *Appearing*    *Description*
               command*                      
&dots;         @dots{}        ...            three dots
&enddots;      @enddots{}     ....           four dots
&TeX;          @TeX{}         TeX            the name "TeX"
&result;       @result{}      =>             
&expansion;    @expansion{}   ==>            
&print;        @print{}       -|             
&error;        @error{}       error-->       
&point;        @point{}       -!-            
&today;        @today{}       31 March 2003  
&esexcl;       @!             !              ending sentence exclamation
                                             mark
&esperiod;     @.             .              ending sentence period
&nes;          @:                            not ending sentence
&esquest;      @?             ?              ending sentence question mark

Supported and unsupported Texinfo feature
*****************************************

   Some Texinfo features are supported, others are not. Here is the
list.

`@WHITESPACE'
     `&emsp;'

`@!'
     `&esexcl;' (end sentence exclamation mark)

`@"'
`@''
     Use equivalent standard SGML entities, or ISO 8859-n characters if
     available.

`@*'
     `<br>'

`@,{c}'
`@,{C}'
     Use equivalent standard SGML entities, or ISO 8859-n characters if
     available.

`@-'
     `<dh>'

`@.'
     `&esperiod;' (end sentence period)

`@:'
     `&nes;' (not ending sentence)

`@='
     Unsupported.(1)

`@?'
     `&esquest;' (end of sentence question mark)

`@@'
     Simply `@'.

`@^'
`@`'
     Use equivalent standard SGML entities, or ISO 8859-n characters if
     available.

`@{'

`@}'
     Simply `{' and `}'.

`@~'
`@AA{}'
`@aa{}'
     Use equivalent standard SGML entities, or ISO 8859-n characters if
     available.

`@acronym{ABBREV}'
     `<acronym>ABBREV</acronym>'

`@AE{}'
`@ae{}'
     Use equivalent standard SGML entities, or ISO 8859-n characters if
     available.

`@afivepaper'
`@afourpaper'
`@afourlatex'
`@afourwide'
     Use command line option: `--paper=a5', `--paper=a4',
     `--paper=a4latex', `--paper=a4wide'.

`@alias NEW=EXISTING'
     Unsupported. May be used inside the `texinfo' element.

`@anchor{NAME}'
     `<anchor id="NAME">'

`@appendix TITLE'
`@appendixsec TITLE'
`@appendixsection TITLE'
`@appendixsubsec TITLE'
`@appendixsubsection TITLE'
`@appendixsubsubsec TITLE'
`@appendixsubsubsection TITLE'
     Appendixes are enclosed inside the `appendix' element.

`@asis'
     The word `asis' is used as an argument for the `emphasis'
     attribute for `table', `vtable' and `ftable' elements.

`@author AUTHOR'
     `<author>AUTHOR</author>'

`@b{TEXT}'
     `<bold>TEXT</bold>'

`@bullet{}'
     `&bull;'

`@bye'
     `</sgmltexi>'

`@c COMMENT'
`@comment COMMENT'
     Unsupported, as SGML has its own comment symbol. May be used
     inside the `texinfo' element.

`@cartouche'
     `<cartouche>TEXT-BLOCK</cartouche>'

`@center LINE-OF-TEXT'
     `<center>LINE-OF-TEXT</center>'

     Unsupported on title page.

`@centerchap TITLE'
     Unsupported.

`@chapheading TITLE'
     `<h1 type="heading">TITLE</h1>'

`@chapter TITLE'
     `<h1>TITLE</h1>'

`@cindex ENTRY'
     `<cindex entry="ENTRY">'

`@cite{REFERENCE}'
     `<cite>REFERENCE</cite>'

`@clear FLAG'
     Unsupported. May be used inside the `texinfo' element.

`@code{SAMPLE}'
     `<code>SAMPLE</code>'

`@command{COMMAND-NAME}'
     `<command>COMMAND-NAME</command>'

`@contents'
     `<contents>'

`@copyright{}'
     Use equivalent standard SGML entities, or ISO 8859-n characters if
     available.

`@defcodeindex INDEX-NAME'
     `<defcodeindex>INDEX-NAME</defcodeindex>'

`@defcv CATEGORY CLASS NAME'
`@defcvx CATEGORY CLASS NAME'
          <defcv cat="CATEGORY" class="CLASS" name="NAME">
          [<defcvx cat="CATEGORY" class="CLASS" name="NAME">]...
              ...
              ...
          </defcv>

`@deffn CATEGORY NAME ARGUMENT...'
`@deffnx CATEGORY NAME ARGUMENT...'
          <deffn cat="CATEGORY" name="NAME">
            <args>ARGUMENT...</args>
          [<deffnx cat="CATEGORY" name="NAME">
            <args>ARGUMENT...</args>]...
              ...
              ...
          </deffn>

`@defindex INDEX-NAME'
     `<defindex>INDEX-NAME</defcodeindex>'

`@definfoenclose NEWCMD, BEFORE, AFTER,'
     Unsupported. May be used inside the `texinfo' element.

`@defivar CLASS INSTANCE-VARIABLE-NAME'
`@defivarx CLASS INSTANCE-VARIABLE-NAME'
          <defivar class="CLASS" name="INSTANCE-VARIABLE">
          [<defivarx class="CLASS" name="INSTANCE-VARIABLE">]...
              ...
              ...
          </defivar>

`@defmac MACRO-NAME ARGUMENT...'
`@defmacx MACRO-NAME ARGUMENT...'
          <defmac name="MACRO-NAME">
            <args>ARGUMENT...</args>
          [<defmacx name="MACRO-NAME">
            <args>ARGUMENT...</args>]...
              ...
              ...
          </defmac>

`@defmethod CLASS METHOD-NAME ARGUMENT...'
`@defmethodx CLASS METHOD-NAME ARGUMENT...'
          <defmethod class="CLASS" name="METHOD-NAME">
            <args>ARGUMENT...</args>
          [<defmethodx class="CLASS" name="METHOD-NAME">
            <args>ARGUMENT...</args>]...
              ...
              ...
          </defmethod>

`@defop CATEGORY CLASS NAME ARGUMENT...'
`@defopx CATEGORY CLASS NAME ARGUMENT...'
          <defop cat="CATEGORY" class="CLASS" name="NAME">
            <args>ARGUMENT...</args>
          [<defopx cat="CATEGORY" class="CLASS" name="NAME">
            <args>ARGUMENT...</args>]...
              ...
              ...
          </defop>

`@defopt OPTION-NAME'
`@defoptx OPTION-NAME'
          <defopt name="OPTION-NAME">
          [<<defoptx name="OPTION-NAME">]...
              ...
              ...
          </defopt>

`@defspec SPECIAL-FORM-NAME ARGUMENT...'
`@defspecx SPECIAL-FORM-NAME ARGUMENT...'
          <defspec name="SPECIAL-FORM-NAME">
            <args>ARGUMENT...</args>
          [<defspecx name="SPECIAL-FORM-NAME">
            <args>ARGUMENT...</args>]...
              ...
              ...
          </defspec>

`@deftp CATEGORY NAME-OF-TYPE ATTRIBUTE...'
`@deftpx CATEGORY NAME-OF-TYPE ATTRIBUTE...'
          <deftp cat="CATEGORY" name="NAME-OF-TYPE">
            <args>ATTRIBUTE...</args>
          [<deftpx cat="CATEGORY" name="NAME-OF-TYPE">
            <args>ATTRIBUTE...</args>]...
              ...
              ...
          </deftp>

`@deftypefn CLASSIFICATION DATA-TYPE NAME ARGUMENT...'
`@deftypefnx CLASSIFICATION DATA-TYPE NAME ARGUMENT...'
          <deftypefn cat="CLASSIFICATION" type="DATA-TYPE" name="NAME">
            <args>ARGUMENT...</args>
          [<deftypefnx cat="CLASSIFICATION" type="DATA-TYPE" name="NAME">
            <args>ARGUMENT...</args>]...
              ...
              ...
          </deftypefn>

`@deftypefun DATA-TYPE FUNCTION-NAME ARGUMENT...'
`@deftypefunx DATA-TYPE FUNCTION-NAME ARGUMENT...'
          <deftypefun type="DATA-TYPE" name="FUNCTION-NAME">
            <args>ARGUMENT...</args>
          [<deftypefunx type="DATA-TYPE" name="FUNCTION-NAME">
            <args>ARGUMENT...</args>]...
              ...
              ...
          </deftypefun>

`@deftypeivar CLASS DATA-TYPE VARIABLE-NAME'
`@deftypeivarx CLASS DATA-TYPE VARIABLE-NAME'
          <deftypeivar class="CLASS" type="DATA-TYPE" name="VARIABLE-NAME">
          [<deftypeivarx class="CLASS" type="DATA-TYPE" name="VARIABLE-NAME">]...
              ...
              ...
          </deftypeivar>

`@deftypemethod CLASS DATA-TYPE METHOD-NAME ARGUMENT...'
`@deftypemethodx CLASS DATA-TYPE METHOD-NAME ARGUMENT...'
          <deftypemethod class="CLASS" type="DATA-TYPE" name="METHOD-NAME">
            <args>ARGUMENT...</args>
          [<deftypemethodx class="CLASS" type="DATA-TYPE" name="METHOD-NAME">
            <args>ARGUMENT...</args>]...
              ...
              ...
          </deftypemethod>

`@deftypeop CATEGORY CLASS DATA-TYPE NAME ARGUMENT...'
`@deftypeopx CATEGORY CLASS DATA-TYPE NAME ARGUMENT...'
          <deftypeop cat="CATEGORY" class="CLASS" type="DATA-TYPE" name="NAME">
            <args>ARGUMENT...</args>
          [<deftypeopx cat="CATEGORY" class="CLASS" type="DATA-TYPE" name="NAME">
            <args>ARGUMENT...</args>]...
              ...
              ...
          </deftypeop>

`@deftypevar DATA-TYPE VARIABLE-NAME'
`@deftypevarx DATA-TYPE VARIABLE-NAME'
          <deftypevar type="DATA-TYPE" name="VARIABLE-NAME">
          [<deftypevarx type="DATA-TYPE" name="VARIABLE-NAME">]...
              ...
              ...
          </deftypevar>

`@deftypevr CLASSIFICATION DATA-TYPE NAME'
`@deftypevrx CLASSIFICATION DATA-TYPE NAME'
          <deftypevr cat="CLASSIFICATION" type="DATA-TYPE" name="NAME">
          [<deftypevrx cat="CLASSIFICATION" type="DATA-TYPE" name="NAME">]...
              ...
              ...
          </deftypevr>

`@defun FUNCTION-NAME ARGUMENT...'
`@defunx FUNCTION-NAME ARGUMENT...'
          <defun name="FUNCTION-NAME">
            <args>ARGUMENT...</args>
          [<defunx name="FUNCTION-NAME">
            <args>ARGUMENT...</args>]...
              ...
              ...
          </defun>

`@defvar VARIABLE-NAME'
`@defvar VARIABLE-NAME'
          <defvar name="VARIABLE-NAME">
          [<defvarx name="VARIABLE-NAME">]...
              ...
              ...
          </defvar>

`@defvr CATEGORY NAME'
`@defvrx CATEGORY NAME'
          <defvr cat="CATEGORY" name="NAME">
          [<defvrx cat="CATEGORY" name="NAME">]...
              ...
              ...
          </defvr>

`@detailmenu'
          <menu>
              ...
              ...
          <detailmenu>
              ...
              ...
          </detailmenu>
          </menu>

`@dfn{TERM}'
     `<dfn>TERM</dfn>'

`@dircategory DIRPART'
`@direntry'
          <infodir cat="DIRPART">
              ...
              ...
          </infodir>

`@display'
     `<display>TEXT-BLOCK</display>'

`@dmn{DIMENSION}'
     `<dmn>DIMENSION</dmn>'

`@documentdescription DESCRIPTION @end documentdescription'
     `<documentdescription content="DESCRIPTION">'

`@documentencoding ENC'
     `<sgmltexi charset="ENC">'

     This is the input character set, like it can be done with the
     Texinfo `@documentencoding' command. It is obscured by the
     `--input-encoding' option, that take precedence and generate a
     pure ISO 646 Texinfo output.

`@documentlanguage CC'
     `<sgmltexi lang="CC">'

`@dotaccent{C}'
     Use equivalent standard SGML entities, or ISO 8859-n characters if
     available.

`@dots{}'
     `&dots;'

`@email{ADDRESS, DISPLAYED-TEXT}'
     `<email email="ADDRESS" name="DISPLAYED-TEXT">'

`@emph{TEXT}'
     `<emph>TEXT</emph>'

`@env{ENVIRONMENT-VARIABLE}'
     `<env>ENVIRONMENT-VARIABLE</env>'

`@enddots{}'
     `&enddots;'

`@enumerate [NUMBER-OR-LETTER]'
          <enumerate [start="NUMBER-OR-LETTER"]>
          <item>
              ...
              ...
          <item>
              ...
              ...
          </enumerate>

`@equiv{}'
     `&equiv;'

`@error{}'
     `&error;'

`@evenfooting'
`@evenheading'

`@everyfooting'
`@everyheading'
     Unsupported. May be used inside the `texinfo' element.

`@example'
          <example>
              ...
              BLOCK
              ...
          </example>

     preformatted:

          <example>
          <pre>
              ...
              IN-LINE
              ...
          </pre>
          </example>

     literal:

          <example>
          <pre>
          <![CDATA[
              ...
              IN-LINE
              ...
          ]]>
          </pre>
          </example>

`@exampleindent'
     Unsupported. May be used inside the `texinfo' element.

`@exlamdown'
     Use equivalent standard SGML entities, or ISO 8859-n characters if
     available.

`@exdent'
          <pre>
              ...
          <exdent>SOME EXDENTED TEXT</exdent>
              ...
          </pre>

`@expansion{}'
     `&expansion;'

`@file{FILENAME}'
     `<file>FILENAME</file>'

`@finalout'
     Unsupported. Actually it is always included.

`@findex ENTRY'
     `<findex entry="ENTRY">'

`@flushleft'
     `<flushleft>TEXT</flushleft>'

`@flushright'
     `<flushright>TEXT</flushright>'

`@footnote{TEXT-OF-FOOTNOTE}'
     `<footnote>TEXT-OF-FOOTNOTE</footnote>'

`@footnotestyle STYLE'
     `<footnotestyle content="STYLE">', or use command line option:
     `--footnotestyle=STYLE'.

`@format'
          <format>
          <pre>
              ...
              ...
          </pre>
          </format>

     literal:

          <format>
          <pre>
          <![CDATA[
              ...
              ...
          ]]>
          </pre>
          </format>

`@frenchspacing'
     `<sgmltexi spacing="french">'

`@ftable FORMATTING-COMMAND'
          <ftable emphasis="COMMAND">
          <item>DESCRIPTIVE-ITEM</item>
          [<itemx>DESCRIPTIVE-ITEM</itemx>]...
              TEXT-BLOCK...
              ...
              ...
          <item>DESCRIPTIVE-ITEM</item>
          [<itemx>DESCRIPTIVE-ITEM</itemx>]...
              TEXT-BLOCK...
              ...
              ...
          </ftable>

`@group'
     `<group>TEXT-BLOCK</group>'

`@H{C}'
     Use equivalent standard SGML entities, or ISO 8859-n characters if
     available.

`@heading TITLE'
     `<h2 type="heading">TITLE</h2>'

`@headings ON-OFF-SINGLE-DOUBLE'
     `<headings
     content="ON-OFF-SINGLE-DOUBLE-SINGLEAFTER-DOUBLEAFTER">', or use
     command line option:
     `--headings=ON-OFF-SINGLE-DOUBLE-SINGLEAFTER-DOUBLEAFTER'.

`@html'
     `<html>HTML_BACK_END_CODE</html>'

`@hyphenation{HY-PHEN-A-TED WORDS}'
     `<hyphenation words="HY-PHEN-A-TED WORDS">'

`@i{TEXT}'
     `<italic>TEXT</italic>'

`@ifclear FLAG'
     Unsupported. May be used inside the `texinfo' element.

`@ifhtml'
     There are two possibilities: in-line and block conditionals.

          <ifhtml>IN-LINE</ifhtml>

          <ifhtmlblock>
              BLOCK
              ...
          </ifhtmlblock>

     SGML gives the possibility to use marked sections. These can be
     controlled with Sgmltexi with the option `--sgml-include' at the
     command line. For example, the SGML source may be like this:

          <!DOCTYPE Sgmltexi PUBLIC "-//GNU//DTD Sgmltexi//EN"
          [
          <!ENTITY % HTML            "IGNORE">
          <!ENTITY % INFO            "IGNORE">
          <!ENTITY % TEX             "IGNORE">
          ...
          ...
          ]>
          <sgmltexi>
          ...
          ...
          <![%HTML;[
              <p>Here it is some text that is meant to appear only inside
              the HTML typesetting.</p>
          ]]>
          <![%INFO;[
              <p>Here it is some other text that is meant to appear only
              inside the Info typesetting.</p>
          ]]>
          <![%TEX;[
              <p>This text is meant to appear only inside the TeX
              typesetting.</p>
          ]]>
          ...
          ...
          </sgmltexi>

     Then, when typesetting for HTML, the option `--sgml-include=HTML'
     must be used:

          sgmltexi --sgml-include=HTML --html my_file.sgml

     When typesetting for Info, the option `--sgml-include=INFO' must
     be used:

          sgmltexi --sgml-include=INFO --info my_file.sgml

     The same way, when typesetting for TeX, the option
     `--sgml-include=TEX' must be used:

          sgmltexi --sgml-include=TEX --info my_file.sgml

`@ifinfo'
     There are two possibilities: in-line and block conditionals.

          <ifinfo>IN-LINE</ifinfo>

          <ifinfoblock>
              BLOCK
              ...
          </ifinfoblock>

     SGML gives also the possibility to use marked sections.  See
     `@ifhtml' for the explanation.

`@ifnothtml'
     There are two possibilities: in-line and block conditionals.

          <ifnothtml>IN-LINE</ifnothtml>

          <ifnothtmlblock>
              BLOCK
              ...
          </ifnothtmlblock>

     SGML gives the possibility to use marked sections. These can be
     controlled with Sgmltexi with the option `--sgml-include' at the
     command line. For example, the SGML source may be like this:

          <!DOCTYPE Sgmltexi PUBLIC "-//GNU//DTD Sgmltexi//EN"
          [
          <!ENTITY % NOTHTML         "IGNORE">
          <!ENTITY % NOTINFO         "IGNORE">
          <!ENTITY % NOTTEX          "IGNORE">
          ...
          ...
          ]>
          <sgmltexi>
          ...
          ...
          <![%NOTHTML;[
              <p>Here it is some text that is meant to appear only outside
              the HTML typesetting.</p>
          ]]>
          <![%NOTINFO;[
              <p>Here it is some other text that is meant to appear only
              outside the Info typesetting.</p>
          ]]>
          <![%NOTTEX;[
              <p>This text is meant to appear only outside the TeX
              typesetting.</p>
          ]]>
          ...
          ...
          </sgmltexi>

     Then, when typesetting for HTML, the options
     `--sgml-include=NOTINFO' and `--sgml-include=NOTTEX' must be used:

          sgmltexi --sgml-include=NOTINFO --sgml-include=NOTTEX --html my_file.sgml

     When typesetting for Info, the options `--sgml-include=NOTHTML' and
     `--sgml-include=NOTTEX' must be used:

          sgmltexi --sgml-include=NOTHTML --sgml-include=NOTTEX --info my_file.sgml

     The same way, when typesetting for TeX, the options
     `--sgml-include=NOTINFO' and `--sgml-include=NOTHTML' must be used:

          sgmltexi --sgml-include=NOTINFO --sgml-include=NOTHTML --tex my_file.sgml

`@ifnotinfo'
     There are two possibilities: in-line and block conditionals.

          <ifnotinfo>IN-LINE</ifnotinfo>

          <ifnotinfoblock>
              BLOCK
              ...
          </ifnotinfoblock>

     SGML gives also the possibility to use marked sections.  See
     `@ifnothtml' for the explanation.

`@ifnotplaintext'
     There are two possibilities: in-line and block conditionals.

          <ifnotplaintext>IN-LINE</ifnotplaintext>

          <ifnotplaintextblock>
              BLOCK
              ...
          </ifnotplaintextblock>

     SGML gives also the possibility to use marked sections.  See
     `@ifnothtml' for the explanation.

`@ifnottex'
     There are two possibilities: in-line and block conditionals.

          <ifnottex>IN-LINE</ifnottex>

          <ifnottexblock>
              BLOCK
              ...
          </ifnottexblock>

     SGML gives also the possibility to use marked sections.  See
     `@ifnothtml' for the explanation.

`@ifnotxml'
     There are two possibilities: in-line and block conditionals.

          <ifnotxml>IN-LINE</ifnotxml>

          <ifnotxmlblock>
              BLOCK
              ...
          </ifnotxmlblock>

     SGML gives also the possibility to use marked sections.  See
     `@ifnothtml' for the explanation.

`@ifplaintext'
     There are two possibilities: in-line and block conditionals.

          <ifplaintext>IN-LINE</ifplaintext>

          <ifplaintextblock>
              BLOCK
              ...
          </ifplaintextblock>

     SGML gives also the possibility to use marked sections.  See
     `@ifhtml' for the explanation.

`@ifset FLAG'
     Unsupported. May be used inside the `texinfo' element.

`@iftex'
     There are two possibilities: in-line and block conditionals.

          <iftex>IN-LINE</iftex>

          <iftexblock>
              BLOCK
              ...
          </iftexblock>

     SGML gives also the possibility to use marked sections.  See
     `@ifhtml' for the explanation.

`@ifxml'
     There are two possibilities: in-line and block conditionals.

          <ifxml>IN-LINE</ifxml>

          <ifxmlblock>
              BLOCK
              ...
          </ifxmlblock>

     SGML gives also the possibility to use marked sections.  See
     `@ifhtml' for the explanation.

`@ignore'
     Unsupported. May be used inside the `texinfo' element. If it is
     not necessary to have the text included inside the generated
     Texinfo source, standard SGML comments may be used:

          <!--
              This text is a comment, that is not reported
              inside the Texinfo generated source.
              ...
              ...
          -->

`@image{FILENAME, [WIDTH], [HEIGHT]}'
     `<image name="FILENAME" width="WIDTH" height="HEIGHT">'

`@include'
     Unsupported (see below). Use SGML mechanism instead, like this:

          <!DOCTYPE Sgmltexi PUBLIC "-//GNU//DTD Sgmltexi//EN"
          [
          <!ENTITY GPL        SYSTEM "licenses/gpl.sgml">
          <!ENTITY BSD        SYSTEM "licenses/bsd.sgml">
          ...
          ...
          ]>
          <sgmltexi>
          ...
          ...
          <appendix>
          &GPL;
          &BSD;
          ...
          ...
          </appendix>
          ...
          </sgmltexi>

     As it can be seen, the insertion of `licenses/gpl.sgml' and
     `licenses/bsd.sgml' happens when the SGML macro `&GPL;' and
     `&BSD;' appear inside the source.

     If it is necessary to include a Texinfo file, the element
     `texinfo' may be used like this:

          <p><texinfo>
          @include example.texi
          </texinfo></p>

     Please remember that `texinfo' is an in-line element.

`@inforef{NODE-NAME, [ENTRY-NAME], INFO-FILE-NAME}'
     `<inforef id="NODE-NAME" name="ENTRY-NAME" info="INFO-FILE-NAME">'

`\input MACRO-DEFINITION-FILE'
     Unsupported.

`@item'
     See `@table', `@ftable', `@vtable', `@itemize', `@enumerate' and
     `@multitable'.

`@itemize [MARK]'
          <itemize [mark="MARK"]>
          <item>
              ...
              ...
          <item>
              ...
              ...
          </itemize>

`@itemx'
     See `@table', `@ftable' and `@vtable'.

`@kbd{KEYBOARD-CHARACTERS}'
     `<kbd>KEYBOARD-CHARACTERS</kbd>'

`@kbdinputstyle STYLE'
     `<kbdstyle style="STYLE">'

`@key{KEY-NAME}'
     `<key>KEY-NAME</key>'

`@kindex ENTRY'
     `<kindex entry="ENTRY">'

`@L{}'
`@l{}'
     Use equivalent standard SGML entities, or ISO 8859-n characters if
     available.

`@lisp'
          <lisp>
              ...
              BLOCK
              ...
          </lisp>

     preformatted:

          <lisp>
          <pre>
              ...
              IN-LINE
              ...
          </pre>
          </lisp>

     literal:

          <lisp>
          <pre>
          <![CDATA[
              ...
              IN-LINE
              ...
          ]]>
          </pre>
          </lisp>

`@lowersections'
     Unsupported.

`@macro MACRO-NAME {PARAMS}'
     Unsupported. May be used inside the `texinfo' element.

`@majorheading TITLE'
     Unsupported. Maybe when Texinfo introduce `@part'.

`@math{MATHEMATICAL-EXPRESSION}'
     `<math>MATHEMATICAL-EXPRESSION</math>'

`@menu'
     `<menu>[INFO-MENU</menu>]'

`@minus{}'
     `&minus;'

`@multitable COLUMN-WIDTH-SPEC'
          <multitable>
          <columnfraction>COLUMNFRACTION</columnfraction>...
          <raw>ELEMENT[<tab>ELEMENT]...</raw>...
          ...
          </multitable>

          <multitable>
          <columnexample>TEXT-EXAMPLE</columnexample>...
          <raw>ELEMENT[<tab>ELEMENT]...</raw>...
          ...
          </multitable>

`@need N'
     `<need mils="N">'

`@node NAME, NEXT, PREVIOUS, UP'
     Use like this for standard manual node handling:

          <hN node="NAME">TITLE</hN>

     If it is required a complete control over nodes, also NEXT,
     PREVIOUS and UP nodes may be specified, like this:

          <hN node="NAME" next="NEXT" prev="PREVIOUS" up="UP" >TITLE</hN>

     Sgmltexi doesn't make any validity check over manual node
     insertions.

`@noindent'
     `<p indent="off">'

`@novalidate'
     Unsupported. May be used inside the `texinfo' element.

`O{}'
`o{}'
     Use equivalent standard SGML entities, or ISO 8859-n characters if
     available.

`@oddfooting'
`@oddheading'
     Unsupported. May be used inside the `texinfo' element.

`@option{OPTION-NAME}'
     `<option>OPTION-NAME</option>'

`@page'
     `<page>'

`@pagesizes [WIDTH][, HEIGHT]'
     Unsupported.

`@paragraphindent INDENT'
     Unsupported.

`@pindex ENTRY'
     `<pindex entry="ENTRY">'

`@point{}'
     `&point;'

`@pounds{}'
     Use equivalent standard SGML entities, or ISO 8859-n characters if
     available.

`@print{}'
     `&print;'

`@printindex INDEX-NAME'
     `<printindex name="INDEX-ENTRY">'

`@pxref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
     `<pxref id="NODE-NAME" name="ENTRY" title="TOPIC-OR-TITLE"
     info="INFO-FILE" ptitle="MANUAL">'

`@questiondown{}'
     Use equivalent standard SGML entities, or ISO 8859-n characters if
     available.

`@quotation'
          <quotation>
              ...
              IN-LINE
              ...
          </quotation>

`@r{TEXT}'
     `<roman>TEXT</roman>'

`@raisesections'
     Unsupported.

`@ref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
     `<ref id="NODE-NAME" name="ENTRY" title="TOPIC-OR-TITLE"
     info="INFO-FILE" ptitle="MANUAL">'

`@refill'
     Unsupported.

`@result{}'
     `&result;'

`@ringaccent{C}'
     Use equivalent standard SGML entities, or ISO 8859-n characters if
     available.

`@samp{TEXT}'
     `<samp>TEXT</samp>'

`@sc{TEXT}'
     `<sc>TEXT</sc>'

`@section TITLE'
     `<h2>TITLE</h2>'

`@set FLAG STRING'
     Unsupported. May be used inside the `texinfo' element.

`@setchapternewpage ON-OFF-ODD'
     `<setchapternewpage content="ON-OFF-ODD">', or use command line
     option: `--setchapternewpage=ON-OFF-ODD'.

`@setcontentsaftertitlepage'
     Unsupported.

`@setfilename INFO-FILE-NAME'
     `<setfilename content="INFO-FILE-NAME">'

`@setshortcontentsaftertitlepage'
     Unsupported.

`@settitle TITLE'
     `<settitle content="TITLE">'

`@shortcontents'
     `<shortcontents>'

`@shorttitlepage TITLE'
     Unsupported.

`@smallbook'
     Use command line option: `--paper=small'.

`@smalldisplay'
     `<smalldisplay>TEXT-BLOCK</smalldisplay>'

`@smallexample'
          <smallexample>
              ...
              BLOCK
              ...
          </smallexample>

     preformatted:

          <smallexample>
          <pre>
              ...
              IN-LINE
              ...
          </pre>
          </smallexample>

     literal:

          <smallexample>
          <pre>
          <![CDATA[
              ...
              IN-LINE
              ...
          ]]>
          </pre>
          </smallexample>

`@smallformat'
          <smallformat>
          <pre>
              ...
              ...
          </pre>
          </smallformat>

     literal:

          <smallformat>
          <pre>
          <![CDATA[
              ...
              ...
          ]]>
          </pre>
          </smallformat>

`@smalllisp'
          <smalllisp>
              ...
              BLOCK
              ...
          </smalllisp>

     preformatted:

          <smalllisp>
          <pre>
              ...
              IN-LINE
              ...
          </pre>
          </smalllisp>

     literal:

          <smalllisp>
          <pre>
          <![CDATA[
              ...
              IN-LINE
              ...
          ]]>
          </pre>
          </smalllisp>

`@sp LINES'
     `<sp lines="LINES">'

`@ss{}'
     Use equivalent standard SGML entities, or ISO 8859-n characters if
     available.

`@strong{TEXT}'
     `<strong>TEXT</strong>'

`@subheading TITLE'
     `<h3 type="heading">TITLE</h3>'

`@subsection TITLE'
     `<h3>TITLE</h3>'

`@subsubheading TITLE'
     `<h4 type="heading">TITLE</h4>'

`@subsubsection TITLE'
     `<h4>TITLE</h4>'

`@subtitle SUBTITLE'
     `<subtitle>SUBTITLE</subtitle>'

`@summarycontents'
     `<summarycontents>'

`@syncodeindex FROM-INDEX INTO-INDEX'
     `<syncodeindex from="FROM-INDEX" to="INTO-INDEX">'

`@synindex FROM-INDEX INTO-INDEX'
     `<synindex from="FROM-INDEX" to="INTO-INDEX">'

`@t{TEXT}'
     `<typewriter>TEXT</typewriter>'

`@tab'
     See `@multitable'.

`@table FORMATTING-COMMAND'
          <table emphasis="COMMAND">
          <item>DESCRIPTIVE-ITEM</item>
          [<itemx>DESCRIPTIVE-ITEM</itemx>]...
              TEXT-BLOCK...
              ...
              ...
          <item>DESCRIPTIVE-ITEM</item>
          [<itemx>DESCRIPTIVE-ITEM</itemx>]...
              TEXT-BLOCK...
              ...
              ...
          </table>

`@TeX{}'
     `&TeX;'

`@tex'
     `<tex>TEX_BACK_END_CODE</tex>'

`@thischapter'
`@thischaptername'
`@thisfile'
`@thispage'
`@thistitle'
     Unsupported. May be used inside the `texinfo' element.

`@tie{}'
     `&nbsp;'

`@tieaccent{CC}'
     Unsupported.(2)

`@tindex ENTRY'
     `<tindex entry="ENTRY">'

`@title TITLE'
     `<title>TITLE</title>'

`@titlefont{TEXT}'
     Unsupported.

`@titlepage'
     Unsupported. See Sgmltexi structure.

`@today'
     `&today;'

`@top'
     Generated automatically; in other words, it is hidden to the user.

`@u{C}'
`@ubaraccent{C}'
`@udotaccent{C}'
     Unsupported.(3)

`@unnumbered TITLE'
     `<h1 type="unnumbered">TITLE</h1>'

`@unnumberedsec TITLE'
     `<h2 type="unnumbered">TITLE</h2>'

`@unnumberedsubsec TITLE'
     `<h3 type="unnumbered">TITLE</h3>'

`@unnumberedsubsubsec TITLE'
     `<h4 type="unnumbered">TITLE</h4>'

`@uref{URL, [DISPLAYED-TEXT], [REPLACEMENT]}'
     `<uref uri="URL" name="DISPLAYED-TEXT" replace="REPLACEMENT">'

`@url{URL}'
     `<url>URL</url>'

`@v{C}'
     Unsupported.(4)

`@value{FLAG}'
     Unsupported. May be used inside the `texinfo' element.

`@var{METASYNTACTIC-VARIABLE}'
     `<var>METASYNTACTIC-VARIABLE</var>'

`@verb{XLITERAL_TEXTX}'
     `<verb char="X"><![CDATA[LITERAL_TEXT]]></verb>'

`@verbatim LITERAL_TEXT @end verbatim'
          <verbatim>
          <[CDATA[
          LITERAL_TEXT
          ]]>
          </verbatim>

`@verbatiminclude FILE'
     `<verbatiminclude file="FILE">'

`@vindex ENTRY'
     `<vindex entry="ENTRY">'

`@vskip AMOUNT'
     Unsupported. May be used inside the `texinfo' element.

`@vtable FORMATTING-COMMAND'
          <vtable emphasis="COMMAND">
          <item>DESCRIPTIVE-ITEM</item>
          [<itemx>DESCRIPTIVE-ITEM</itemx>]...
              TEXT-BLOCK...
              ...
              ...
          <item>DESCRIPTIVE-ITEM</item>
          [<itemx>DESCRIPTIVE-ITEM</itemx>]...
              TEXT-BLOCK...
              ...
              ...
          </vtable>

`@w{TEXT}'
     `<whole>TEXT</whole>'

`@xref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
     `<xref id="NODE-NAME" name="ENTRY" title="TOPIC-OR-TITLE"
     info="INFO-FILE" ptitle="MANUAL">'

   ---------- Footnotes ----------

   (1) Are there standard SGML entities? I need advice.

   (2) Is there a standard SGML entity? I need advice.

   (3) Are there standard SGML entities? I need advice.

   (4) Are there standard SGML entities? I need advice.

Supported ISOnum entities: numeric and special graphic
******************************************************

   The following table shows the current state of supported ISOnum
entities.

*SGML macro*   *Appearing*    *Description*
&half;         1/2            fraction one-half
&frac12;       1/2            fraction one-half
&frac14;       1/4            fraction one-quarter
&frac34;       3/4            fraction three-quarters
&frac18;       1/8            fraction one-eighth
&frac38;       3/8            fraction three-eighths
&frac58;       5/8            fraction five-eighths
&frac78;       7/8            fraction seven-eighths
&sup1;         [sup1  ]       superscript one
&sup2;         [sup2  ]       superscript two
&sup3;         [sup3  ]       superscript three
&plus;         +              plus sign
&plusmn;       +/-            plus-or-minus sign
&lt;           <              less-than sign
&equals;       =              equals sign
&gt;           >              greater-than sign
&divide;       [divide]       divide sign
&times;        [times ]       multiply sign
&curren;       [curren]       general currency sign
&pound;        #              pound sign
&dollar;       $              dollar sign
&cent;         [cent  ]       cent sign
&yen;          [yen   ]       yen sign
&num;          #              number sign
&percnt;       %              percent sign
&amp;          &              ampersand
&ast;          *              asterisk
&commat;       @              commercial at
&lsqb;         [              left square bracket
&bsol;         \              reverse solidus
&rsqb;         ]              right square bracket
&lcub;         {              left curly bracket
&horbar;       [horbar]       horizontal bar
&verbar;       |              vertical bar
&rcub;         }              right curly bracket
&micro;        [micro ]       micro sign
&ohm;          [ohm   ]       ohm sign
&deg;          [deg   ]       degree sign
&ordm;         [ordm  ]       ordinal indicator, masculine
&ordf;         [ordf  ]       ordinal indicator, feminine
&sect;         [sect  ]       section sign
&para;         [para  ]       pilcrow (paragraph sign)
&middot;       *              middle dot
&larr;         [larr  ]       leftward arrow
&rarr;         [rarr  ]       rightward arrow
&uarr;         [uarr  ]       upward arrow
&darr;         [darr  ]       downward arrow
&copy;         (C)            copyright sign
&reg;          [reg   ]       registered sign
&trade;        [trade ]       trade mark sign
&brvbar;       [brvbar]       broken (vertical) bar
&not;          [not   ]       not sign
&sung;         [sung  ]       music note (sung text sign)
&excl;         !              exclamation mark
&iexcl;        !              inverted exclamation mark
&quot;         "              quotation mark
&apos;         '              apostrophe
&lpar;         (              left parenthesis
&rpar;         )              right parenthesis
&comma;        ,              comma
&lowbar;       _              low line
&hyphen;       -              hyphen
&period;       .              full stop, period
&sol;          /              solidus
&colon;        :              colon
&semi;         ;              semicolon
&quest;        ?              question mark
&iquest;       ?              inverted question mark
&laquo;        [laquo ]       angle quotation mark, left
&raquo;        [raquo ]       angle quotation mark, right
&lsquo;        [lsquo ]       single quotation mark, left
&rsquo;        [rsquo ]       single quotation mark, right
&ldquo;        [ldquo ]       double quotation mark, left
&rdquo;        [rdquo ]       double quotation mark, right
&nbsp;                        no break (required) space
&shy;          [shy   ]       soft hyphen

Supported ISOpub entities: publishing
*************************************

   The following table shows the current state of supported ISOpub
entities.

*SGML macro*   *Appearing*    *Description*
&emsp;                        em space
&ensp;         [ensp  ]       en space (1/2-em)
&emsp13;       [emsp3 ]       1/3-em space
&emsp14;       [emsp4 ]       1/4-em space
&numsp;        [numsp ]       digit space (width of a number)
&puncsp;       [puncsp]       punctuation space (width of comma)
&thinsp;       [thinsp]       thin space (1/6-em)
&hairsp;       [hairsp]       hair space
&mdash;        [mdash ]       em dash
&ndash;        [ndash ]       en dash
&dash;         [dash  ]       hyphen (true graphic)
&blank;        [blank ]       significant blank symbol
&hellip;       [hellip]       ellipsis (horizontal)
&nldr;         [nldr  ]       double baseline dot (en leader)
&frac13;       1/3            fraction one-third
&frac23;       2/3            fraction two-thirds
&frac15;       1/5            fraction one-fifth
&frac25;       2/5            fraction two-fifths
&frac35;       3/5            fraction three-fifths
&frac45;       4/5            fraction four-fifths
&frac16;       1/6            fraction one-sixth
&frac56;       5/6            fraction five-sixths
&incare;       [incare]       in-care-of symbol
&block;        [block ]       full block
&uhblk;        [uhblk ]       upper half block
&lhblk;        [lhblk ]       lower half block
&blk14;        [blk14 ]       25% shaded block
&blk12;        [blk12 ]       50% shaded block
&blk34;        [blk34 ]       75% shaded block
&marker;       [marker]       histogram marker
&cir;          [cir   ]       circle, open
&squ;          [squ   ]       square, open
&rect;         [rect  ]       rectangle, open
&utri;         [utri  ]       up triangle, open
&dtri;         [dtri  ]       down triangle, open
&star;         [star  ]       star, open
&bull;         *              round bullet, filled
&squf;         [squf  ]       sq bullet, filled
&utrif;        [utrif ]       up tri, filled
&dtrif;        [dtrif ]       dn tri, filled
&ltrif;        [ltrif ]       l tri, filled
&rtrif;        [rtrif ]       r tri, filled
&clubs;        [clubs ]       club suit symbol
&diams;        [diams ]       diamond suit symbol
&hearts;       [hearts]       heart suit symbol
&spades;       [spades]       spades suit symbol
&malt;         [malt  ]       maltese cross
&dagger;       [dagger]       dagger
&Dagger;       [Dagger]       double dagger
&check;        [check ]       tick, check mark
&cross;        [ballot]       ballot cross
&sharp;        [sharp ]       musical sharp
&flat;         [flat  ]       musical flat
&male;         [male  ]       male symbol
&female;       [female]       female symbol
&phone;        [phone ]       telephone symbol
&telrec;       [telrec]       telephone recorder symbol
&copysr;       [copysr]       sound recording copyright sign
&caret;        [caret ]       caret (insertion mark)
&lsquor;       [lsquor]       rising single quote, left (low)
&ldquor;       [ldquor]       rising dbl quote, left (low)
&fflig;        [fflig ]       mall ff ligature
&filig;        [filig ]       mall fi ligature
&fjlig;        [fjlig ]       mall fj ligature
&ffilig;       [ffilig]       mall ffi ligature
&ffllig;       [ffllig]       mall ffl ligature
&fllig;        [fllig ]       mall fl ligature
&mldr;         [mldr  ]       m leader
&rdquor;       [rdquor]       rising dbl quote, right (high)
&rsquor;       [rsquor]       rising single quote, right (high)
&vellip;       [vellip]       vertical ellipsis
&hybull;       [hybull]       rectangle, filled (hyphen bullet)
&loz;          [loz   ]       lozenge - lozenge or total mark
&lozf;         [lozf  ]       blacklozenge - lozenge, filled
&ltri;         [ltri  ]       l triangle, open
&rtri;         [rtri  ]       r triangle, open
&starf;        [starf ]       bigstar - star, filled
&natur;        [natur ]       natural - music natural
&rx;           [rx    ]       pharmaceutical prescription (Rx)
&sext;         [sext  ]       sextile (6-pointed star)
&target;       [target]       register mark or target
&dlcrop;       [dlcrop]       downward left crop mark
&drcrop;       [drcrop]       downward right crop mark
&ulcrop;       [ulcrop]       upward left crop mark
&urcrop;       [urcrop]       upward right crop mark

Supported ISOtech entities: general technical
*********************************************

   The following table shows the current state of supported ISOtech
entities.

*SGML macro*   *Appearing*    *Description*
&aleph;        [aleph ]       aleph, Hebrew
&and;          [and   ]       logical and
&ang90;        [ang90 ]       right (90 degree) angle
&angsph;       [angsph]       angle-spherical
&ap;           [ap    ]       approximate
&becaus;       [becaus]       because
&bottom;       [bottom]       perpendicular
&cap;          [cap   ]       intersection
&cong;         [cong  ]       congruent with
&conint;       [conint]       contour integral operator
&cup;          [cup   ]       union or logical sum
&equiv;        ==             identical with
&exist;        [exist ]       at least one exists
&forall;       [forall]       for all
&fnof;         [fnof  ]       function of (italic small f)
&ge;           [ge    ]       greater-than-or-equal
&iff;          [iff   ]       if and only if
&infin;        [infin ]       infinity
&int;          [int   ]       integral operator
&isin;         [isin  ]       set membership
&lang;         [lang  ]       left angle bracket
&lArr;         [lArr  ]       is implied by
&le;           [le    ]       less-than-or-equal
&minus;        -              minus sign
&mnplus;       [mnplus]       minus-or-plus sign
&nabla;        [nabla ]       del, Hamilton operator
&ne;           [ne    ]       not equal
&ni;           [ni    ]       contains
&or;           [or    ]       logical or
&par;          [par   ]       parallel
&part;         [part  ]       partial differential
&permil;       [permil]       per thousand
&perp;         [perp  ]       perpendicular
&prime;        [prime ]       prime or minute
&Prime;        [Prime ]       double prime or second
&prop;         [prop  ]       is proportional to
&radic;        [radic ]       radical
&rang;         [rang  ]       right angle bracket
&rArr;         [rArr  ]       implies
&sim;          [sim   ]       similar
&sime;         [sime  ]       similar, equals
&square;       [square]       square
&sub;          [sub   ]       subset or is implied by
&sube;         [sube  ]       subset, equals
&sup;          [sup   ]       superset or implies
&supe;         [supe  ]       superset, equals
&there4;       [there4]       therefore
&Verbar;       [Verbar]       dbl vertical bar
&angst;        [angst ]       capital A, ring
&bernou;       [bernou]       bernoulli function (script capital B)
&compfn;       [compfn]       composite function (small circle)
&Dot;          [Dot   ]       dieresis or umlaut mark
&DotDot;       [DotDot]       four dots above
&hamilt;       [hamilt]       hamiltonian (script capital H)
&lagran;       [lagran]       lagrangian (script capital L)
&lowast;       [lowast]       low asterisk
&notin;        [notin ]       negated set membership
&order;        [order ]       order of (script small o)
&phmmat;       [phmmat]       physics M-matrix (script capital M)
&tdot;         [tdot  ]       three dots above
&tprime;       [tprime]       triple prime
&wedgeq;       [wedgeq]       corresponds to (wedge, equals)

Supported ISOlat1 entities: added latin 1
*****************************************

   The following table shows the current state of supported ISOlat1
entities.

*SGML macro*   *Appearing*    *Description*
&aacute;       á              small a, acute accent
&Aacute;       Á              capital A, acute accent
&acirc;        â              small a, circumflex accent
&Acirc;        Â              capital A, circumflex accent
&agrave;       à              small a, grave accent
&Agrave;       À              capital A, grave accent
&aring;        a*             small a, ring
&Aring;        A*             capital A, ring
&atilde;       ã              small a, tilde
&Atilde;       Ã              capital A, tilde
&auml;         ä              small a, dieresis or umlaut mark
&Auml;         Ä              capital A, dieresis or umlaut mark
&aelig;        ae             small ae diphthong (ligature)
&AElig;        AE             capital AE diphthong (ligature)
&ccedil;       ç              small c, cedilla
&Ccedil;       Ç              capital C, cedilla
&eth;          [eth   ]       small eth, Icelandic
&ETH;          [ETH   ]       capital Eth, Icelandic
&eacute;       é              small e, acute accent
&Eacute;       É              capital E, acute accent
&ecirc;        ê              small e, circumflex accent
&Ecirc;        Ê              capital E, circumflex accent
&egrave;       è              small e, grave accent
&Egrave;       È              capital E, grave accent
&euml;         ë              small e, dieresis or umlaut mark
&Euml;         Ë              capital E, dieresis or umlaut mark
&iacute;       í              small i, acute accent
&Iacute;       Í              capital I, acute accent
&icirc;        î              small i, circumflex accent
&Icirc;        Î              capital I, circumflex accent
&igrave;       ì              small i, grave accent
&Igrave;       Ì              capital I, grave accent
&iuml;         ï              small i, dieresis or umlaut mark
&Iuml;         Ï              capital I, dieresis or umlaut mark
&ntilde;       ñ              small n, tilde
&Ntilde;       Ñ              capital N, tilde
&oacute;       ó              small o, acute accent
&Oacute;       Ó              capital O, acute accent
&ocirc;        ô              small o, circumflex accent
&Ocirc;        Ô              capital O, circumflex accent
&ograve;       ò              small o, grave accent
&Ograve;       Ò              capital O, grave accent
&oslash;       /o             small o, slash
&Oslash;       /O             capital O, slash
&otilde;       õ              small o, tilde
&Otilde;       Õ              capital O, tilde
&ouml;         ö              small o, dieresis or umlaut mark
&Ouml;         Ö              capital O, dieresis or umlaut mark
&szlig;        ss             small sharp s, German (sz ligature)
&thorn;        [thorn ]       small thorn, Icelandic
&THORN;        [THORN ]       capital THORN, Icelandic
&uacute;       ú              small u, acute accent
&Uacute;       Ú              capital U, acute accent
&ucirc;        û              small u, circumflex accent
&Ucirc;        Û              capital U, circumflex accent
&ugrave;       ù              small u, grave accent
&Ugrave;       Ù              capital U, grave accent
&uuml;         ü              small u, dieresis or umlaut mark
&Uuml;         Ü              capital U, dieresis or umlaut mark
&yacute;       ý              small y, acute accent
&Yacute;       Ý              capital Y, acute accent
&yuml;         ÿ              small y, dieresis or umlaut mark

Supported ISOlat2 entities: added latin 2
*****************************************

   The following table shows the current state of supported ISOlat2
entities.

*SGML macro*   *Appearing*    *Description*
&abreve;       [abreve]       small a, breve
&Abreve;       [Abreve]       capital A, breve
&amacr;        [amacr ]       small a, macron
&Amacr;        [Amacr ]       capital A, macron
&aogon;        [aogon ]       small a, ogonek
&Aogon;        [Aogon ]       capital A, ogonek
&cacute;       c'             small c, acute accent
&Cacute;       C'             capital C, acute accent
&ccaron;       [ccaron]       small c, caron
&Ccaron;       [Ccaron]       capital C, caron
&ccirc;        c^             small c, circumflex accent
&Ccirc;        C^             capital C, circumflex accent
&cdot;         c.             small c, dot above
&Cdot;         C.             capital C, dot above
&dcaron;       [dcaron]       small d, caron
&Dcaron;       [Dcaron]       capital D, caron
&dstrok;                      small d, stroke
&Dstrok;       [Dstrok]       capital D, stroke
&ecaron;       [ecaron]       small e, caron
&Ecaron;       [Ecaron]       capital E, caron
&edot;         e.             small e, dot above
&Edot;         E.             capital E, dot above
&emacr;        [emacr ]       small e, macron
&Emacr;        [Emacr ]       capital E, macron
&eogon;        [eogon ]       small e, ogonek
&Eogon;        [Eogon ]       capital E, ogonek
&gacute;       g'             small g, acute accent
&gbreve;       [gbreve]       small g, breve
&Gbreve;       [Gbreve]       capital G, breve
&Gcedil;       G,             capital G, cedilla
&gcirc;        g^             small g, circumflex accent
&Gcirc;        G^             capital G, circumflex accent
&gdot;         g.             small g, dot above
&Gdot;         G.             capital G, dot above
&hcirc;        h^             small h, circumflex accent
&Hcirc;        H^             capital H, circumflex accent
&hstrok;       [hstrok]       small h, stroke
&Hstrok;       ''             capital H, stroke
&Idot;         I.             capital I, dot above
&Imacr;        [Imacr ]       capital I, macron
&imacr;        [imacr ]       small i, macron
&ijlig;        [ijlig ]       small ij ligature
&IJlig;        [IJlig ]       capital IJ ligature
&inodot;       [inodot]       small i without dot
&iogon;        [iogon ]       small i, ogonek
&Iogon;        [Iogon ]       capital I, ogonek
&itilde;       i~             small i, tilde
&Itilde;       I~             capital I, tilde
&jcirc;        j^             small j, circumflex accent
&Jcirc;        J^             capital J, circumflex accent
&kcedil;       k,             small k, cedilla
&Kcedil;       K,             capital K, cedilla
&kgreen;       [kgreen]       small k, Greenlandic
&lacute;       l'             small l, acute accent
&Lacute;       L'             capital L, acute accent
&lcaron;       [lcaron]       small l, caron
&Lcaron;       [Lcaron]       capital L, caron
&lcedil;       l,             small l, cedilla
&Lcedil;       L,             capital L, cedilla
&lmidot;       [lmidot]       small l, middle dot
&Lmidot;       [Lmidot]       capital L, middle dot
&lstrok;       /l             small l, stroke
&Lstrok;       /L             capital L, stroke
&nacute;       n'             small n, acute accent
&Nacute;       N'             capital N, acute accent
&eng;          [eng   ]       small eng, Lapp
&ENG;          [ENG   ]       capital ENG, Lapp
&napos;        [napos ]       small n, apostrophe
&ncaron;       [ncaron]       small n, caron
&Ncaron;       [Ncaron]       capital N, caron
&ncedil;       n,             small n, cedilla
&Ncedil;       N,             capital N, cedilla
&odblac;       o''            small o, double acute accent
&Odblac;       O''            capital O, double acute accent
&Omacr;        [Omacr ]       capital O, macron
&omacr;        [omacr ]       small o, macron
&oelig;        &#156;         small oe ligature
&OElig;        &#140;         capital OE ligature
&racute;       r'             small r, acute accent
&Racute;       R'             capital R, acute accent
&rcaron;       [rcaron]       small r, caron
&Rcaron;       [Rcaron]       capital R, caron
&rcedil;       r,             small r, cedilla
&Rcedil;       R,             capital R, cedilla
&sacute;       s'             small s, acute accent
&Sacute;       S'             capital S, acute accent
&scaron;       [scaron]       small s, caron
&Scaron;       [Scaron]       capital S, caron
&scedil;       s,             small s, cedilla
&Scedil;       S,             capital S, cedilla
&scirc;        s^             small s, circumflex accent
&Scirc;        S^             capital S, circumflex accent
&tcaron;       [tcaron]       small t, caron
&Tcaron;       [Tcaron]       capital T, caron
&tcedil;       t,             small t, cedilla
&Tcedil;       T,             capital T, cedilla
&tstrok;                      small t, stroke
&Tstrok;       [Tstrok]       capital T, stroke
&ubreve;       [ubreve]       small u, breve
&Ubreve;       [Ubreve]       capital U, breve
&udblac;       u''            small u, double acute accent
&Udblac;       U''            capital U, double acute accent
&umacr;        [umacr ]       small u, macron
&Umacr;        [Umacr ]       capital U, macron
&uogon;        [uogon ]       small u, ogonek
&Uogon;        [Uogon ]       capital U, ogonek
&uring;        u*             small u, ring
&Uring;        U*             capital U, ring
&utilde;       u~             small u, tilde
&Utilde;       U~             capital U, tilde
&wcirc;        w^             small w, circumflex accent
&Wcirc;        W^             capital W, circumflex accent
&ycirc;        y^             small y, circumflex accent
&Ycirc;        Y^             capital Y, circumflex accent
&Yuml;         Y"             capital Y, dieresis or umlaut mark
&zacute;       z'             small z, acute accent
&Zacute;       Z'             capital Z, acute accent
&zcaron;       [zcaron]       small z, caron
&Zcaron;       [Zcaron]       capital Z, caron
&zdot;         z.             small z, dot above
&Zdot;         Z.             capital Z, dot above

GNU Free Documentation License
******************************

Version 1.1, March 2000

Copyright (C) 2000  Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

0. PREAMBLE
===========

   The purpose of this License is to make a manual, textbook, or other
written document "free" in the sense of freedom: to assure everyone the
effective freedom to copy and redistribute it, with or without
modifying it, either commercially or noncommercially.  Secondarily,
this License preserves for the author and publisher a way to get credit
for their work, while not being considered responsible for
modifications made by others.

   This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.  It
complements the GNU General Public License, which is a copyleft license
designed for free software.

   We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does.  But this License is not limited to software manuals; it
can be used for any textual work, regardless of subject matter or
whether it is published as a printed book.  We recommend this License
principally for works whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS
================================

   This License applies to any manual or other work that contains a
notice placed by the copyright holder saying it can be distributed
under the terms of this License.  The "Document", below, refers to any
such manual or work.  Any member of the public is a licensee, and is
addressed as "you".

   A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.

   A "Secondary Section" is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject.  (For example, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.)  The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding them.

   The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.

   The "Cover Texts" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.

   A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the general
public, whose contents can be viewed and edited directly and
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input to
text formatters.  A copy made in an otherwise Transparent file format
whose markup has been designed to thwart or discourage subsequent
modification by readers is not Transparent.  A copy that is not
"Transparent" is called "Opaque".

   Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML or
XML using a publicly available DTD, and standard-conforming simple HTML
designed for human modification.  Opaque formats include PostScript,
PDF, proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the machine-generated
HTML produced by some word processors for output purposes only.

   The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page.  For works in
formats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.

2. VERBATIM COPYING
===================

   You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License.  You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute.  However, you may accept
compensation in exchange for copies.  If you distribute a large enough
number of copies you must also follow the conditions in section 3.

   You may also lend copies, under the same conditions stated above, and
you may publicly display copies.

3. COPYING IN QUANTITY
======================

   If you publish printed copies of the Document numbering more than
100, and the Document's license notice requires Cover Texts, you must
enclose the copies in covers that carry, clearly and legibly, all these
Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts
on the back cover.  Both covers must also clearly and legibly identify
you as the publisher of these copies.  The front cover must present the
full title with all words of the title equally prominent and visible.
You may add other material on the covers in addition.  Copying with
changes limited to the covers, as long as they preserve the title of
the Document and satisfy these conditions, can be treated as verbatim
copying in other respects.

   If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.

   If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a publicly-accessible computer-network location containing a complete
Transparent copy of the Document, free of added material, which the
general network-using public has access to download anonymously at no
charge using public-standard network protocols.  If you use the latter
option, you must take reasonably prudent steps, when you begin
distribution of Opaque copies in quantity, to ensure that this
Transparent copy will remain thus accessible at the stated location
until at least one year after the last time you distribute an Opaque
copy (directly or through your agents or retailers) of that edition to
the public.

   It is requested, but not required, that you contact the authors of
the Document well before redistributing any large number of copies, to
give them a chance to provide you with an updated version of the
Document.

4. MODIFICATIONS
================

   You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release the
Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy of
it.  In addition, you must do these things in the Modified Version:

   *  *A.* Use in the Title Page (and on the covers, if any) a title
     distinct from that of the Document, and from those of previous
     versions (which should, if there were any, be listed in the
     History section of the Document).  You may use the same title as a
     previous version if the original publisher of that version gives
     permission.

   *  *B.* List on the Title Page, as authors, one or more persons or
     entities responsible for authorship of the modifications in the
     Modified Version, together with at least five of the principal
     authors of the Document (all of its principal authors, if it has
     less than five).

   *  *C.* State on the Title page the name of the publisher of the
     Modified Version, as the publisher.

   *  *D.* Preserve all the copyright notices of the Document.

   *  *E.* Add an appropriate copyright notice for your modifications
     adjacent to the other copyright notices.

   *  *F.* Include, immediately after the copyright notices, a license
     notice giving the public permission to use the Modified Version
     under the terms of this License, in the form shown in the Addendum
     below.

   *  *G.* Preserve in that license notice the full lists of Invariant
     Sections and required Cover Texts given in the Document's license
     notice.

   *  *H.* Include an unaltered copy of this License.

   *  *I.* Preserve the section entitled "History", and its title, and
     add to it an item stating at least the title, year, new authors,
     and publisher of the Modified Version as given on the Title Page.
     If there is no section entitled "History" in the Document, create
     one stating the title, year, authors, and publisher of the
     Document as given on its Title Page, then add an item describing
     the Modified Version as stated in the previous sentence.

   *  *J.* Preserve the network location, if any, given in the Document
     for public access to a Transparent copy of the Document, and
     likewise the network locations given in the Document for previous
     versions it was based on.  These may be placed in the "History"
     section.  You may omit a network location for a work that was
     published at least four years before the Document itself, or if
     the original publisher of the version it refers to gives
     permission.

   *  *K.* In any section entitled "Acknowledgements" or "Dedications",
     preserve the section's title, and preserve in the section all the
     substance and tone of each of the contributor acknowledgements
     and/or dedications given therein.

   *  *L.* Preserve all the Invariant Sections of the Document,
     unaltered in their text and in their titles.  Section numbers or
     the equivalent are not considered part of the section titles.

   *  *M.* Delete any section entitled "Endorsements".  Such a section
     may not be included in the Modified Version.

   *  *N.* Do not retitle any existing section as "Endorsements" or to
     conflict in title with any Invariant Section.


   If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant.  To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.

   You may add a section entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties-for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.

   You may add a passage of up to five words as a Front-Cover Text, and
a passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version.  Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or through
arrangements made by) any one entity.  If the Document already includes
a cover text for the same cover, previously added by you or by
arrangement made by the same entity you are acting on behalf of, you
may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.

   The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.

5. COMBINING DOCUMENTS
======================

   You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice.

   The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy.  If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of Invariant
Sections in the license notice of the combined work.

   In the combination, you must combine any sections entitled "History"
in the various original documents, forming one section entitled
"History"; likewise combine any sections entitled "Acknowledgements",
and any sections entitled "Dedications".  You must delete all sections
entitled "Endorsements."

6. COLLECTIONS OF DOCUMENTS
===========================

   You may make a collection consisting of the Document and other
documents released under this License, and replace the individual
copies of this License in the various documents with a single copy that
is included in the collection, provided that you follow the rules of
this License for verbatim copying of each of the documents in all other
respects.

   You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert a
copy of this License into the extracted document, and follow this
License in all other respects regarding verbatim copying of that
document.

7. AGGREGATION WITH INDEPENDENT WORKS
=====================================

   A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, does not as a whole count as a Modified Version of
the Document, provided no compilation copyright is claimed for the
compilation.  Such a compilation is called an "aggregate", and this
License does not apply to the other self-contained works thus compiled
with the Document, on account of their being thus compiled, if they are
not themselves derivative works of the Document.

   If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one quarter
of the entire aggregate, the Document's Cover Texts may be placed on
covers that surround only the Document within the aggregate.  Otherwise
they must appear on covers around the whole aggregate.

8. TRANSLATION
==============

   Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections.  You may include a
translation of this License provided that you also include the original
English version of this License.  In case of a disagreement between the
translation and the original English version of this License, the
original English version will prevail.

9. TERMINATION
==============

   You may not copy, modify, sublicense, or distribute the Document
except as expressly provided for under this License.  Any other attempt
to copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License.  However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such parties
remain in full compliance.

10. FUTURE REVISIONS OF THIS LICENSE
====================================

   The Free Software Foundation may publish new, revised versions of
the GNU Free Documentation License from time to time.  Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.  See
http://www.gnu.org/copyleft/.

   Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation.  If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.

How to use this License for your documents
==========================================

   To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

     Copyright (c)  YEAR  YOUR NAME.
     Permission is granted to copy, distribute and/or modify this document
     under the terms of the GNU Free Documentation License, Version 1.1
     or any later version published by the Free Software Foundation;
     with the Invariant Sections being LIST THEIR TITLES, with the
     Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
     A copy of the license is included in the section entitled "GNU
     Free Documentation License".

   If you have no Invariant Sections, write "with no Invariant Sections"
instead of saying which ones are invariant.  If you have no Front-Cover
Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
LIST"; likewise for Back-Cover Texts.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.

Index
*****

abstract:
          See ```titlepage'''.
admin:
          See ```admin'''.
appendix:
          See ```appendix'''.
author:
          See ```titlepage'''.
block:
          See ``Block and in-line''.
body:
          See ```body'''.
cat:
          See ```admin'''.
charset:
          See ``General structure for a Sgmltexi source file''.
content:
          See ```admin'''.
contents:
          See ``Table of contents''.
copyright:
          See ```titlepage'''.
coverart:
          See ```titlepage'''.
dedications:
          See ```titlepage'''.
defcodeindex:
          See ```admin'''.
defindex:
          See ```admin'''.
dependencies:
          See ``Dependencies''.
encoding:
          See ``Encoding''.
entities:
          See ``Encoding''.
footnotestyle:
          See ```admin'''.
from:
          See ```admin'''.
frontcovertext:
          See ```titlepage'''.
Gettext:
          See ``How to install''.
h1:
          See ```body'''.
h2:
          See ```body'''.
h3:
          See ```body'''.
h4:
          See ```body'''.
head:
          See ```head'''.
heading:
          See ```admin'''.
how to use Sgmltexi:
          See ``How to use the front-end''.
in-line:
          See ``Block and in-line''.
indexheading:
          See ``Indexes''.
infodir:
          See ```admin'''.
installation:
          See ``How to install''.
intro:
          See ```intro'''.
ISOlat1:
          See ``Supported ISOlat1 entities: added latin 1''.
ISOlat2:
          See ``Supported ISOlat2 entities: added latin 2''.
ISOnum:
          See ``Supported ISOnum entities: numeric and special graphic''.
ISOpub:
          See ``Supported ISOpub entities: publishing''.
ISOtech:
          See ``Supported ISOtech entities: general technical''.
lang:
          See ``General structure for a Sgmltexi source file''.
legal:
          See ```titlepage'''.
license:
          See ```titlepage'''.
menu <1>:
          See ``Sectioning, nodes and menus''.
menu:
          See ```menu'''.
name:
          See ```admin'''.
node:
          See ``Sectioning, nodes and menus''.
partheading:
          See ```body'''.
PATH:
          See ``How to install''.
printindex:
          See ``Indexes''.
publishnote:
          See ```titlepage'''.
setchapternewpage:
          See ```admin'''.
setfilename:
          See ```admin'''.
settitle:
          See ```admin'''.
shortcontents:
          See ``Table of contents''.
spacing:
          See ``General structure for a Sgmltexi source file''.
standard entities:
          See ``Encoding''.
structure:
          See ``General structure for a Sgmltexi source file''.
subtitle:
          See ```titlepage'''.
summarycontents:
          See ``Table of contents''.
supported:
          See ``Supported and unsupported Texinfo feature''.
syncodeindex:
          See ```admin'''.
synindex:
          See ```admin'''.
title:
          See ```titlepage'''.
titlepage:
          See ```titlepage'''.
to:
          See ```admin'''.
tomeheading:
          See ```body'''.
tpextra:
          See ```titlepage'''.
unsupported:
          See ``Supported and unsupported Texinfo feature''.