############################################################################### # # NOTE: This file under revision control using RCS # Any changes made without RCS will be lost # # $Source: U:\\mhansen\\sites\\marchansen\\tech\\RCS\\tn109_technote.txt,v $ # $Revision: 1.1 $ # $Date: 2002-11-13 22:00:39-06 $ # $Author: mhansen $ # $Locker: mhansen $ # $State: Exp $ # # Number: TN109 # # Title: Tech Notes # ############################################################################### # # REVISION HISTORY: # # $Log: tn109_technote.txt,v $ # Revision 1.1 2002-11-13 22:00:39-06 mhansen # # Revision 1.0 2002-11-09 03:11:42-06 mhansen # Initial revision # # # 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