next up previous
Next: Formatting engines Up: (doc)Tools for a new Previous: Overview


The doc* formats

As stated in the introduction the goal was to create a lightweight, easy to use and still powerful language for the creation of documentation, mainly manpages.

The result of this effort is the doctools system. The sources of this system are freely available under the same license as Tcl itself, as a module of the tcllib bundle of packages [11]. An application using the doctools packages is the doctools processor dtp, also freely available [12].

The system defines actually not a single format, but three. The primary format has the same name as the overall system, doctools and is intended for the creation of manpages. The other two formats are doctoc and docidx, for the creation of tables of contents, and of keyword based indices. While all of them can be written manually it is anticipated that documents in the secondary formats will most likely be generated automatically out of a set of documents written in the primary format.

Brief documents written in the defined formats can be seen in the figures 1, 2 and 3. They were taken from the documentation for tcllib itself, all of which is written in doctools, thus not only providing the means of processing the formats, but also serving as a pool of examples.


Table: sha1 manpage in doctools 
[manpage_begin sha1 n 1.0.3]
[moddesc   {sha1 hash}]
[titledesc {Perform sha1 hashing}]
[require Tcl 8.2]
[require sha1 [opt 1.0.3]]
[description]
[para]

This package provides commands to compute a SHA1 digests of arbitrary
messages.

[section COMMANDS]
[list_begin definitions]
[call [cmd ::sha1::sha1] [arg msg]]

The command takes a message and returns the SHA1 digest of this message
as a hexadecimal string.

[call [cmd ::sha1::hmac] [arg key] [arg text]]

The command takes a key string and a text and returns the hmac of the

[list_end]

[section EXAMPLES]

[para]
[example {
% sha1::sha1 "hello world"
2aae6c35c94fcfb415dbe95f408b9ce91ee846ed
}]

[para]
[example {
% sha1::hmac "our little secret" "hello world"
a7ed9d62819b9788e22171d9108a00c370104526
}]

[keywords sha1 hashing security]
[manpage_end]


Table: Excerpted table of contents for Tcllib 
[toc_begin {Tcllib -- Table of Contents} Modules]
[item tcllib/modules/base64/base64.man base64 {Procedures to encode and decode base64}]
[item tcllib/modules/base64/uuencode.man uuencode {encode/decoding a binary file}]
[item tcllib/modules/base64/yencode.man yencode {encode/decoding a binary file}]
...
[item tcllib/modules/crc/cksum.man cksum {calculate a cksum(1) compatible checksum}]
[item tcllib/modules/crc/crc16.man crc16 {Perform a 16bit Cyclic Redundancy Check}]
[item tcllib/modules/crc/crc32.man crc32 {Perform a 32bit Cyclic Redundancy Check}]
[item tcllib/modules/crc/sum.man sum {calculate a sum(1) compatible checksum}]
[item tcllib/modules/csv/csv.man csv {Procedures to handle CSV data.}]
[item tcllib/modules/des/des.man des {Perform DES encryption of Tcl data}]
[item tcllib/modules/dns/tcllib_dns.man dns {Tcl Domain Name Service Client}]
[item tcllib/modules/html/html.man html {Procedures to generate HTML structures}]
[item tcllib/modules/irc/irc.man irc {Create IRC connection and interface.}]
...
[item tcllib/modules/smtpd/smtpd.man smtpd {Tcl SMTP server implementation}]
[item tcllib/modules/soundex/soundex.man soundex Soundex]
[item tcllib/modules/stooop/stooop.man stooop {Object oriented extension.}]
[item tcllib/modules/struct/struct_list.man list {Procedures for manipulating lists}]
[item tcllib/modules/struct/struct_tree.man tree {Create and manipulate tree objects}]
[item tcllib/modules/uri/uri.man uri {URI utilities}]
[toc_end]


Table: Excerpted keyword index of Tcllib 
[index_begin Tcllib {Keyword index}]
  [key C++]
    [manpage tcllib/modules/stooop/stooop.man stooop]
  [key CGI]
    [manpage tcllib/modules/ncgi/ncgi.man ncgi]
  [key DES]
    [manpage tcllib/modules/des/des.man des]
  [key DNS]
    [manpage tcllib/modules/dns/tcllib_dns.man dns]
  [key HTML]
    [manpage tcllib/modules/doctools/docidx.man docidx]
    [manpage tcllib/modules/doctools/docidx_api.man docidx_api]
    [manpage tcllib/modules/doctools/docidx_fmt.man docidx_fmt]
    [manpage tcllib/modules/doctools/doctoc.man doctoc]
    [manpage tcllib/modules/doctools/doctoc_api.man doctoc_api]
    [manpage tcllib/modules/doctools/doctoc_fmt.man doctoc_fmt]
    [manpage tcllib/modules/doctools/doctools.man doctools]
    [manpage tcllib/modules/doctools/doctools_api.man doctools_api]
    [manpage tcllib/modules/doctools/doctools_fmt.man doctools_fmt]
    [manpage tcllib/modules/doctools/mpexpand.man mpexpand]
  [key LaTeX]
    [manpage tcllib/modules/doctools/docidx_api.man docidx_api]
    [manpage tcllib/modules/doctools/docidx_fmt.man docidx_fmt]
    [manpage tcllib/modules/doctools/doctoc_api.man doctoc_api]
    [manpage tcllib/modules/doctools/doctoc_fmt.man doctoc_fmt]
    [manpage tcllib/modules/doctools/doctools_api.man doctools_api]
    [manpage tcllib/modules/doctools/doctools_fmt.man doctools_fmt]
...
[index_end]

The result of converting the sha1 documentation in figure 1 into plain text can be seen in figure 4. Other output formats with predefined formatting engines[*] are nroff, HTML, TMML, LATEX [6], and Wiki format [24].


Table: sha1 manpage, converted to plain text 
sha1 - sha1 hash
Generated from file 'tcllib/modules/sha1/sha1.man' by tcllib/doctools with format 'text'
sha1(n) 1.0.3  "sha1 hash"

NAME
====

sha1 - Perform sha1 hashing

SYNOPSIS
========

package require Tcl 8.2
package require sha1 ?1.0.3?

::sha1::sha1 msg
::sha1::hmac key text

DESCRIPTION
===========

This package provides commands to compute a SHA1 digests of arbitrary messages.

COMMANDS
========

    ::sha1::sha1 msg

        The command takes a message and returns the SHA1 digest of this message
        as a hexadecimal string.

    ::sha1::hmac key text

        The command takes a key string and a text and returns the hmac of the

EXAMPLES
========

| % sha1::sha1 "hello world"
| 2aae6c35c94fcfb415dbe95f408b9ce91ee846ed

| % sha1::hmac "our little secret" "hello world"
| a7ed9d62819b9788e22171d9108a00c370104526

KEYWORDS
========

hashing, security, sha1

The conceptual ancestor of the three formats is LATEX and its metaphor of having text as the main part of the documentation, interspersed with markup commands.

Another concept borrowed from that ancestor and TMML is that of semantic markup. This means that all markup defines what a component of the document is, but not its appearance. This is left to the conversion into an output format. The opposing term is visual markup which declares the appearance of the content without giving it structure. Examples for that are HTML, or naked TEX[*]. The use of semantic markup is important as it is this feature which allows the creation of tools which extract meta information from a document and use that to generate other documents, like an index of keywords. From the point of view of the system itself the extraction of meta data is actually nothing more than just another output format.

The full specifications of the three formats are part of the doctools module in tcllib and are not iterated here.

next up previous
Next: Formatting engines Up: (doc)Tools for a new Previous: Overview
[email protected]