doctools_fmt(n) 1.0 doctools "Documentation tools"

NAME

doctools_fmt - Specification of simple tcl markup for manpages

SYNOPSIS

vset varname value vset varname include filename manpage_begin command section version manpage_end moddesc desc titledesc desc copyright text description require pkg ?version? section name para see_also args keywords args arg text cmd text opt text emph text strong text comment text sectref text syscmd text method text option text widget text fun text type text package text class text var text file text uri text term text const text nl lb rb example_begin example_end example text list_begin what list_end bullet enum lst_item text call args arg_def type name ?mode? opt_def name ?arg? cmd_def command tkoption_def name dbname dbclass usage args

DESCRIPTION

This manpage specifies a documentation format for manpages. It is intended to complement both the doctoc format for writing tables of contents and the docidx format for writing indices. See doctoc_fmt and docidx_fmt for the specification of these two formats.

This format is called doctools. It provides all the necessary commands to write manpages. Like for the doctoc and docidx formats a package is provided implementing a generic framework for the conversion of doctools to a number of different output formats, like HTML, TMML, nroff, LaTeX, etc. The package is called doctools, its documentation can be found in doctools. People wishing to write a formatting engine for the conversion of doctools into a new output format have to read doctools_api. This manpage will explain the interface between the generic package and such engines.

OVERVIEW

doctoc is similar to LaTex in that it consists primarily of text, with markup commands embedded into it. The format used to mark something as command is different from LaTeX however. All text between matching pairs of [ and ] is a command, possibly with arguments. Note that both brackets have to be on the same line for a command to be recognized.

In contrast to both doctoc and docidx this format does allow plain text beyond white space. This plain text will be the contents of the described manpage.

FORMATTING COMMANDS

• The main commands are manpage_begin, manpage_end, moddesc, titledesc, and description. Four of these five are required for a manpage. The optional command is titledesc. The first two are the first and last commands in a manpage. Neither text nor other commands may precede manpage_begin nor follow manpage_end. The command description separates header and body of the manpage and may not be omitted.
  
  The remaining commands (moddesc and titledesc) provide one-line descriptions of module and specific title respectively.
  
  
• The only text allowed between manpage_begin and description is the command require. Other commands or normal text are not permitted. require is used to list the packages the described command(s) depend(s) on for its operation. This list can be empty.
  
  
• After description text and all other commands are allowed. The text can be separated into highlevel blocks using named sections. Each block can be further divided into paragraphs via para.
  
  
• The commands see_also and keywords define whole sections named SEE ALSO and KEYWORDS. They can occur everywhere in the manpage but making them the last section is the usual thing to do. They can be omitted.
  
  
• There are five commands available to markup words, arg, cmd, opt, emph and strong. The first three are used to mark words as command arguments, as command names and as optional. The other two are visual markup to emphasize words. The term words is used in a loose sense here, i.e application of the commands to a sequence of words is entirely possible, if they are properly quoted. Note that usage of strong is discouraged as this command is deprecated and only present for backwards compatibility
  
  
• Another set of commands is available to construct (possibly nested) lists. These are list_begin, list_end, lst_item, bullet, enum, call, arg_def, opt_def, cmd_def, and tkoption_def. The first two of these begin and end a list respectively.
  
  The argument to the first command denotes the type of the list. The allowed values and their associated item command are explained later, in the section detailing the Commands.
  
  The other commands start list items and each can be used only inside a list of their type. In other words, bullet is allowed in bulletted lists but nowhere else, enum in enumerated lists and lst_item and call are for definition lists. These two commands also have some text directly associated with the item although the major bulk of the item is the text following the item until the next list command.
  
  The last list command, call is special. It is used to describe the syntax of a command and its arguments. It should not only cause the appropriate markup of a list item at its place but also add the syntax to the table of contents (synopsis) if supported by the output format in question. nroff and HTML for example do. A format focused on logical markup, like TMML, may not.
  
  
• The command usage is similar to call in that it adds the syntax to the table of contents (synopsis) if supported by the output format. Unlike call, this command doesn't add any text to the output as a direct result of the command. Thus, it can be used anywhere within the document to add usage information. Typically it is used near the top of the document, in cases where it is not desireable to use call elsewhere in the document, or where additional usage information is desired (e.g.: to document a "package require" command).

Commands

vset varname value

Sets the formatter variable varname to the specified value. Returns the empty string.

vset varname

Returns the value associated with the formatter variable varname.

include filename

Reads the file named filename, runs it through the expansion process and returns the expanded result.

manpage_begin command section version

This command begins a manpage. Nothing is allowed to precede it. Arguments are the name of the command described by the manpage, the section of the manpages this manpages lives in, and the version of the module containing the command. All have to fit on one line.

manpage_end

This command closes a manpage. Nothing is allowed to follow it.

moddesc desc

This command is required and comes after manpage_begin, but before either require or description. Its argument provides a one-line description of the module described by the manpage.

titledesc desc

This command is optional and comes after manpage_begin, but before either require or description. Its argument provides a one-line expansion of the title for the manpage. If this command is not used the manpage processor has to use information from moddesc instead.

copyright text

This command is optional and comes after manpage_begin, but before either require or description. Its argument declares the copyright assignment for the manpage. When invoked more than once the assignments are accumulated.

A doctools processor is allowed to provide auch information too, but a formatting engine has to give the accumulated arguments of this command precedence over the data coming from the processor.

description

This command separates the header part of the manpage from the main body. Only require, moddesc, or titledesc may precede it.

require pkg ?version?

May occur only between manpage_begin and description. Is used to list the packages which are required for the described command to be operational.

section name

Used to structure the body of the manpage into named sections. This command is not allowed inside of a list or example. It implicitly closes the last paragraph before the command and also implicitly opens the first paragraph of the new section.

para

Used to structure sections into paragraphs. Must not be used inside of a list or example.

see_also args

Creates a section SEE ALSO containing the arguments as cross-references. Must not be used inside of a list or example.

keywords args

Creates a section KEYWORDS containing the arguments as words indexing the manpage. Must not be used inside of a list or example.

arg text

Declares that the marked text is the name of a command argument.

cmd text

Declares that the marked text is the name of a command.

opt text

Declares that the marked text is something optional. Most often used in conjunction with arg to denote optional command arguments.

emph text

Emphasize the text.

strong text

Emphasize the text. Same as emph. Usage is discouraged. The command is deprecated and present only for backward compatibility.

comment text

Declares that the marked text is a comment.

sectref text

Declares that the marked text is a section reference.

syscmd text

Declares that the marked text is a system command.

method text

Declares that the marked text is a object method.

option text

Declares that the marked text is a option.

widget text

Declares that the marked text is a widget.

fun text

Declares that the marked text is a function.

type text

Declares that the marked text is a data type.

package text

Declares that the marked text is a package.

class text

Declares that the marked text is a class.

var text

Declares that the marked text is a variable.

file text

Declares that the marked text is a file .

uri text

Declares that the marked text is a uri.

term text

Declares that the marked text is a unspecific terminology.

const text

Declares that the marked text is a constant value.

nl

Vertical space to separate text without breaking it into a new paragraph.

lb

Introduces a left bracket into the output.

rb

Introduces a right bracket into the output. The bracket commands are necessary as plain brackets are used to denote the beginnings and endings of the formatting commands.

example_begin

Formats subsequent text as a code sample: line breaks, spaces, and tabs are preserved and, where appropriate, text is presented in a fixed-width font.

example_end

End of a code sample block.

example text

Formats text as a multi-line block of sample code. text should be enclosed in braces.

list_begin what

Starts new list of type what. The allowed types (and their associated item commands) are:

bullet

bullet

enum

enum

definitions

lst_item and call

arg

arg_def

cmd

cmd_def

opt

opt_def

tkoption

tkoption_def

list_end

Ends the list opened by the last list_begin.

bullet

Starts a new item in a bulletted list.

enum

Starts a new item in an enumerated list.

lst_item text

Starts a new item in a definition list. The argument is the term to be defined.

call args

Starts a new item in a definition list, but the term defined by it is a command and its arguments.

arg_def type name ?mode?

Starts a new item in an argument list. Specifies the data-type of the described argument, its name and possibly its i/o-mode.

opt_def name ?arg?

Starts a new item in an option list. Specifies the name of the option and possible (i.e. optional) arguments.

cmd_def command

Starts a new item in a command list. Specifies the name of the command.

tkoption_def name dbname dbclass

Starts a new item in a widget option list. Specifies the name of the option, i.e. the name used in scripts, name used by the option database, and the class (type) of the option.

usage args

Defines a term to be used in the table of contents or synopsis section, depending on the format. This command is silent, as it doesn't add any text to the output as a direct result of the call. It merely defines data to appear in another section.

EXAMPLE

The tcl sources of this manpage can serve as an example for all of the markup described by it. Almost every possible construct (with the exception of require) is used here.

SEE ALSO

docidx_fmt, doctoc_fmt, doctools, doctools_api

KEYWORDS

HTML, LaTeX, TMML, generic markup, manpage, markup, nroff

COPYRIGHT

Copyright © 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net>
Copyright © 2003 Andreas Kupries <andreas_kupries@users.sourceforge.net>