Existing Doc Systems, Part 1 (TexInfo)


Kim Lester (kim@dfusion.com.au)
Wed, 12 Jan 2000 18:12:08 +0000


         Existing Doc Systems, Part 1 (TexInfo)
         ======================================
 
 We need to discuss the pros/cons of existing systems before making an
 informed decision. To aid this I have documented some of the features
 of the main contenders. My notes are unbiased and any mistakes are
 unintentional. Many of the comments have been extracted from the
 relevant systems own doucmentation.
 These notes are by way of introduction to those unfamiliar with
 particular systems (eg me :) )
 
 Please make comments after having digested all this.
 Personal opinions are ok (eg "XXX feels cumbersome" or "I'll die
 before giving up XXX its the best" etc but please try and explain
 what gives you that feeling. If I can be objective so can you all.
 
 If I have missed out any significant/different systems tell me
 and prefereably point me at some references. No links/references no
 fair trial :-)
 
 I'll add more parts as I get time/discover other systems.
 Currently there are 3 parts.
 
 
 TexInfo (and Info system)
 =========================

Texinfo is a documentation system that uses a single source file to
produce both on-line information and printed output.
 
Using Texinfo, you can create a printed document with the normal
features of a book, including chapters, sections, cross references,
and indices. From the same Texinfo source file, you can create a
menu-driven, on-line Info file with nodes, menus, cross references,
and indices.

To make an Info file, you process a Texinfo source file with the
makeinfo utility.
An Info file is a Texinfo file formatted so that the Info
documentation reading program can operate on it.
Info files are divided into pieces called nodes, each of which
contains the discussion of one topic. Each node has a name, and
contains both text for the user to read and pointers to other nodes,
which are identified by their names. The Info program displays one
node at a time, and provides commands with which the user can move to
other related nodes.

Usually, you will design a document so that its nodes match the
structure of chapters and sections in the printed output. But there
are times when this is not right for the material being discussed.
Therefore, Texinfo uses separate commands to specify the node
structure for the Info file and the section structure for the printed
output.

 Tex vs TexInfo
 --------------
TeX is very powerful and has a great many features. Because a Texinfo
file must be able to present information both on a character-only
terminal in Info form and in a typeset book, the formatting commands
that Texinfo supports are necessarily limited.

[NOTE thus that the info file is a processed file not the original
source]

TeX and texi2roff work with many types of printer; similarly, Info
works with almost every type of computer terminal. This power makes
Texinfo a general purpose system, but brings with it a constraint,
which is that a Texinfo file may contain only the customary
"typewriter" characters (letters, numbers, spaces, and punctuation
marks) but no special graphics.

A Texinfo file is a plain ASCII file containing text and @-commands
Texinfo is the format in which documentation for GNU utilities and
libraries is written.

 Printing
 --------
 
To make a printed document, you process a Texinfo source file with
the TeX typesetting program. This creates a DVI file that you can
typeset and print as a book or report. If you do not have TeX, but do
have troff or nroff, you can use the texi2roff program instead.

 Tools
 -----
 
 Various format converters exist including:
         texi2html
         texi2pdf
         texi2dvi
         texi -> info (name?)
         
 

A sample texInfo source file (to get the feel of it)
----------------------------------------------------

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename sample.info
@settitle Sample Document
@c %**end of header

@setchapternewpage odd

@ifinfo
This is a short example of a complete Texinfo file.

Copyright 1990 Free Software Foundation, Inc.
@end ifinfo

@titlepage
@sp 10
@comment The title is printed in a large font.
@center @titlefont{Sample Title}

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990 Free Software Foundation, Inc.
@end titlepage

@node Top, First Chapter, (dir), (dir)
@comment node-name, next, previous, up

@menu
* First Chapter:: The first chapter is the
                     only chapter in this sample.
* Concept Index:: This index has two entries.
@end menu

@node First Chapter, Concept Index, Top, Top
@comment node-name, next, previous, up
@chapter First Chapter
@cindex Sample index entry

This is the contents of the first chapter.
@cindex Another sample index entry

Here is a numbered list.

@enumerate
@item
This is the first item.

@item
This is the second item.
@end enumerate

The @code{makeinfo} and @code{texinfo-format-buffer}
commands transform a Texinfo file such as this into
an Info file; and @TeX{} typesets it for a printed
manual.

@node Concept Index, , First Chapter, Top
@comment node-name, next, previous, up
@unnumbered Concept Index

@printindex cp

@contents
@bye
------------------------------------------------------------

TexInfo Summary
---------------
 
 TexInfo has many points in its favour and a couple of limitations.
 
 Pros:
     Existing body of conforming text
     Maintained by GNU
     Hardcopy formatting
     Simple ASCII commands
     Structured "node" format dpages have (parent, children, siblings)
     Indexes, Table of Contents, Cross-references
     Lists, tables, footnotes
     
 Cons:
     Info (viewable) files are not source documents (texi files are)
     Text only, no graphics
     Indexing system is not extensible enough for requirements (??)
     Not being an EMACS guru _I_ find info's navigation system hard to
      remember
 
  Notes:
      TexInfo commands are mostly structure but also formatting
        (eg 10pt space, emphasised text, justify, some font commands)
  
 
 A comment on TeX/LaTex
 ----------------------
 
         Would a variation on Tex be a useful document format?
         Tex output is very good/flexible on hardcopy. However it
         does not natively have the extra structure tags needed
         and interactive/hyper-link viewers don't really exist.
         Tex is really a text formatting language, which could be
         pressed into service but it wouldn't be the best option.
         As there are SGML tools to output Tex/DVI this isn't really
         an issue.



This archive was generated by hypermail 2.0b3 on Wed Jan 12 2000 - 13:14:50 EST