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
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:
It can be useful to define also some internal entities, like this:
...
...
]>
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).
...
...
...
...
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'.
`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:
SgmltexiAn alternative way to write Texinfo
documentationThis edition is for Sgmltexi
&EDITION; for Texinfo 4
Sgmltexi is an SGML system (DTD and tools) to
make Texinfo documentation using SGML...
Permission is granted to make and distribute
verbatim copies of this manual...
...
Cover art by ...
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:
- 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:
- 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:
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:
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:
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:
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:
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:
But this element can be used also more explicitly, like this:
* Sgmltexi: (sgmltexi). SGML for Texinfo.
* Sgmltexi install: (sgmltexi)install. Install Sgmltexi.
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:
Sgmltexi
- 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:
An alternative way to write Texinfo documentation
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:
Sgmltexi is an SGML system (DTD and tools) to
make Texinfo documentation using SGML.
The Sgmltexi DTD is designed to...
...
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:
Tizio Tizi <tizio@dinkel.brot.dg>Caio Cai <caio@dinkel.brot.dg>
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:
Version 1.2.3
- 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:
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".
Cover art by ...
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:
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".
Cover art by ...
- 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:
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.
Introduction to Sgmltexi
Sgmltexi is a DTD with tools to get Texinfo...
Sgmltexi manage Texinfo nodes automatically,...
`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.
Networking
IP protocol history
Bla bla bla...
Bla bla bla...
ISO/OSI model
Bla bla bla...
Bla bla bla...
IPv4 and IPv6
Bla bla bla...
...
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.
IP protocol history
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:
...
Index of functionsConcept index
...
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).
IP protocol history
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:
IP protocol history
Bla bla bla...
Bla bla bla...
]]>
This text is meant to appear only inside the TeX
typesetting.
]]>
...
...
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.
IN-LINE
BLOCK
...
SGML gives also the possibility to use marked sections. See
`@ifhtml' for the explanation.
`@ifnothtml'
There are two possibilities: in-line and block conditionals.
IN-LINE
BLOCK
...
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:
...
...
]>
...
...
Here it is some text that is meant to appear only outside
the HTML typesetting.
]]>
Here it is some other text that is meant to appear only
outside the Info typesetting.
]]>
This text is meant to appear only outside the TeX
typesetting.
]]>
...
...
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.
IN-LINE
BLOCK
...
SGML gives also the possibility to use marked sections. See
`@ifnothtml' for the explanation.
`@ifnotplaintext'
There are two possibilities: in-line and block conditionals.
IN-LINE
BLOCK
...
SGML gives also the possibility to use marked sections. See
`@ifnothtml' for the explanation.
`@ifnottex'
There are two possibilities: in-line and block conditionals.
IN-LINE
BLOCK
...
SGML gives also the possibility to use marked sections. See
`@ifnothtml' for the explanation.
`@ifnotxml'
There are two possibilities: in-line and block conditionals.
IN-LINE
BLOCK
...
SGML gives also the possibility to use marked sections. See
`@ifnothtml' for the explanation.
`@ifplaintext'
There are two possibilities: in-line and block conditionals.
IN-LINE
BLOCK
...
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.
IN-LINE
BLOCK
...
SGML gives also the possibility to use marked sections. See
`@ifhtml' for the explanation.
`@ifxml'
There are two possibilities: in-line and block conditionals.
IN-LINE
BLOCK
...
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:
`@image{FILENAME, [WIDTH], [HEIGHT]}'
`'
`@include'
Unsupported (see below). Use SGML mechanism instead, like this:
...
...
]>
...
...
&GPL;
&BSD;
...
...
...
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:
@include example.texi
Please remember that `texinfo' is an in-line element.
`@inforef{NODE-NAME, [ENTRY-NAME], INFO-FILE-NAME}'
`'
`\input MACRO-DEFINITION-FILE'
Unsupported.
`@item'
See `@table', `@ftable', `@vtable', `@itemize', `@enumerate' and
`@multitable'.
`@itemize [MARK]'
...
...
...
...
`@itemx'
See `@table', `@ftable' and `@vtable'.
`@kbd{KEYBOARD-CHARACTERS}'
`KEYBOARD-CHARACTERS'
`@kbdinputstyle STYLE'
`'
`@key{KEY-NAME}'
`KEY-NAME'
`@kindex ENTRY'
`'
`@L{}'
`@l{}'
Use equivalent standard SGML entities, or ISO 8859-n characters if
available.
`@lisp'
...
BLOCK
...
preformatted:
...
IN-LINE
...
literal:
`@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}'
`'
`@menu'
`[INFO-MENU]'
`@minus{}'
`−'
`@multitable COLUMN-WIDTH-SPEC'
COLUMNFRACTION...
ELEMENT[ELEMENT]......
...
TEXT-EXAMPLE...
ELEMENT[ELEMENT]......
...
`@need N'
`'
`@node NAME, NEXT, PREVIOUS, UP'
Use like this for standard manual node handling:
TITLE
If it is required a complete control over nodes, also NEXT,
PREVIOUS and UP nodes may be specified, like this:
TITLE
Sgmltexi doesn't make any validity check over manual node
insertions.
`@noindent'
`
'
`@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}'
`'
`@page'
`'
`@pagesizes [WIDTH][, HEIGHT]'
Unsupported.
`@paragraphindent INDENT'
Unsupported.
`@pindex ENTRY'
`'
`@point{}'
`&point;'
`@pounds{}'
Use equivalent standard SGML entities, or ISO 8859-n characters if
available.
`@print{}'
`&print;'
`@printindex INDEX-NAME'
`'
`@pxref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
`'
`@questiondown{}'
Use equivalent standard SGML entities, or ISO 8859-n characters if
available.
`@quotation'
...
IN-LINE
...
`@r{TEXT}'
`TEXT'
`@raisesections'
Unsupported.
`@ref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
`'
`@refill'
Unsupported.
`@result{}'
`&result;'
`@ringaccent{C}'
Use equivalent standard SGML entities, or ISO 8859-n characters if
available.
`@samp{TEXT}'
`TEXT'
`@sc{TEXT}'
`TEXT'
`@section TITLE'
`
TITLE
'
`@set FLAG STRING'
Unsupported. May be used inside the `texinfo' element.
`@setchapternewpage ON-OFF-ODD'
`', or use command line
option: `--setchapternewpage=ON-OFF-ODD'.
`@setcontentsaftertitlepage'
Unsupported.
`@setfilename INFO-FILE-NAME'
`'
`@setshortcontentsaftertitlepage'
Unsupported.
`@settitle TITLE'
`'
`@shortcontents'
`'
`@shorttitlepage TITLE'
Unsupported.
`@smallbook'
Use command line option: `--paper=small'.
`@smalldisplay'
`TEXT-BLOCK'
`@smallexample'
...
BLOCK
...
preformatted:
...
IN-LINE
...
literal:
`@smallformat'
...
...
literal:
`@smalllisp'
...
BLOCK
...
preformatted:
...
IN-LINE
...
literal:
`@sp LINES'
`'
`@ss{}'
Use equivalent standard SGML entities, or ISO 8859-n characters if
available.
`@strong{TEXT}'
`TEXT'
`@subheading TITLE'
`