TN109 - Tech Notes
109.1 Summary
This quick and dirty technical documentation method is used for this
document and many of the other tech notes on this web site. Notes are
typed as plain ASCII text with certain, minimal standards for
formatting. A CGI dynamically displays these ASCII tech notes,
reformatting them slightly, adding an index, and converting embedded
references to links.
Primary advantage is speed of documentation compared to things like
DocBook or HTML. Finished documents can be read either with a browser or
an ordinary text editor.
Disadvantages include limited features to created complicated formats
and no method to include graphics. See TN109.5 for more sophisticated
alternatives.
109.2 Source files
Source files are ASCII text with certain embedded information:
a. Lines beginning with # are comments and not displayed by
the CGI.
b. Each comment line can contain one name/value pair, the
delimiter is a colon followed by white space (one or more
spaces or tabs) i.e. ": "
c. Each file must have at least two name value pairs:
Number: TNnnn
Title: Document Title
These Number and Title values are used by the CGI
d. Sections are divided by a line beginning with the document
number immediately followed by a period and at least one
more digit and then white space. General sections are numbered
sequentially. i.e. "nnn.n"
e. Embedded links -- any embedded email addresses or URL's will
be converted by the CGI to links. Also references to other
tech notes beginning "TNnnn" will be converted to a link.
To look at the source file for this tech note:
http://www.marchansen.com/bin/txt.cgi/tn109/tn109.txt
109.3 Display CGI
The display CGI, view.cgi, converts ASCII text files formatted in the
"tech note" format and outputs HTML. It also prepends a standard header;
appends a standard footer; generates and prepends index; converts
titles and section headings to different display Format; and converts
embedded URL's and other tech note references to links.
Usage: view.cgi/[tech_note]
If tech_note argument is supplied it must be in the default tech note
directory. The tech_note argument is passed as extra path information,
NOT with the "?" delimiter.
If no argument is supplied then it is assumed that the tech note is
"index.txt" in the current directory. Presumably, there is an index.cgi
in the same directory which is a link to view.cgi. This feature permits
simpler paths for tech note URLs.
For example, the URL to this tech note is:
http://www.marchansen.com/tn109/
tn109 is actually a directory. The http server on this host will execute
the default cgi, index.cgi if no index.html is present. The contents of
this directory are:
lrwxrwxrwx 1 mhansen 15 Nov 8 18:24 index.cgi -> ../bin/view.cgi
lrwxrwxrwx 1 mhansen 15 Nov 8 18:24 index.txt -> tn109.txt
-rw-r--r-- 1 mhansen 2752 Nov 8 18:25 tn109.txt
Download view.cgi from:
http://www.marchansen.com/bin/txt.cgi/tn109/view.cgi
109.4 Revision Control
Because these are ASCII files, any software configuration management
tool may be used. Even if I have more sophisticated tools available, I
typically just use RCS for tech note files.
109.5 More Sophisticated Alternatives
Besides obvious alternative like HTML or Microsoft Word some serious
technical documentation alternatives include:
DocBook An XML/SGML vocabulary particularly well suited to books
and papers about computer hardware and software.
http://www.docbook.org/
http://www.oasis-open.org/committees/docbook/
Framemaker WYSIWYG SGML/XML authoring tool. Particularly strong for
extensive technical documentation projects with
complicated formatting and graphics, more so if
documentation will be published.
http://www.adobe.com/products/framemaker/
Javadoc Javadoc is part of Sun Microsystems Java distribution for
generating API documentation in HTML format from doc
comments in source code.
http://java.sun.com/j2se/javadoc/
LaTeX LaTeX is a TeX macro package, that provides a document
processing system. LaTeX allows markup to describe the
structure of a document, so that the user need not think
about presentation.
http://www.latex-project.org/
Lout Lout is a document formatting system similar in style to
LaTeX and produces a PostScript file which can be printed
on most laser printers and graphic display devices. Plain
text and PDF output are also available.
Lout offers a range of advanced features, including
optimal paragraph breaking, automatic hyphenation,
PostScript EPS file inclusion and generation, equation
formatting, tables, diagrams, rotation and scaling, sorted
indexes, bibliographic databases, running headers and odd-
even pages, automatic cross referencing, formatting of
C/C++ programs, and much more, all ready to use.
http://snark.ptc.spbu.ru/~uwe/lout/lout.html
man The traditional UNIX man pages are written with the -man
macros for nroff/troff. see MAN(5).
http://docs.sun.com/db/doc/801-6680-05/6i11qd7av?a=view
MTex A system from DEC for producing man pages in both HTML and
nroff formats from a single source format.
http://research.compaq.com/SRC/mtex/
nroff/troff The original open system documentation tool.
See "Unix Text Processing", by Dale Dougherty and Tim
O'Reilly.
http://www.oreilly.com/openbook/utp/
perlpod Perl "Plain Old Documentation" (POD). Simple-to-use markup
language typically used for writing documentation for
Perl, Perl programs, and Perl modules. Translators are
available for converting Pod to various formats like plain
text, HTML, man pages, and more.
http://www.perl.com/
http://www.perlpod.com/
Sgmltexi SGML typesetting system based on Texinfo.
http://packages.debian.org/stable/doc/sgmltexi.html
TeX TeX is a typesetting system, "intended for the creation of
beautiful books - and especially for books that contain a
lot of mathematics"
http://www.tug.org/
Texinfo Texinfo is the official documentation format of the GNU
project. It is used by many non-GNU projects as well.
Texinfo uses a single source file to produce both online
information and printed output. This means that instead of
writing two different documents, one for online
information and another for a printed manual, you need
write only one document.
You can read the on-line information, known as an "Info
file", with an Info documentation-reading program. By
convention, Texinfo source file names end with a .texi or
.texinfo extension. You can write and format Texinfo files
into Info files within GNU emacs, and read them using the
emacs Info reader. You can also format Texinfo files into
Info files using makeinfo and read them using info, so
you're not dependent on emacs. The distribution includes a
Perl script, texi2html, that will convert Texinfo sources
into HTML.
http://www.gnu.org/software/texinfo/
TWiki A well developed Wiki variation from Peter Thoeny,
supporting revision control and an expandable
architecture with numerous plugins, add-ons, and skins
developed by other parties.
http://www.twiki.org/
Wiki "Wiki" is Hawaiian for quick. Refers collectively to
numerous variants and clones of the original Wiki concept
described in "The Wiki Way" (Addison-Wesley 2001) by Bo
Leuf and Ward Cunningham. A web based documentaion/content
management system, where uses can change the content via
forms with their browser.
http://www.wiki.org/
List of variants: http://c2.com/cgi/wiki?WikiEngines
|
