Richard Kettlewell, <rjk@greenend.org.uk>
© 2000, 2003 Richard Kettlewell. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
RJKDOC is an SGML DTD for program documentation, plus some tools for generating other formats from it. The tools are written in C++ and use James Clarke's SP toolkit. The software may be copied under the terms of the GNU General Public License.
The motivation for RJKDOC is to produce both full manuals and reference "man pages" from the same source, removing the need to duplicate information between the two. Currently the output formats supported are plain text, HTML and man pages.
If you want something more flexible, detailed or powerful than RJKDOC then DocBook is probably a good place to look. If you just want something cheap and cheerful (or should that be "quick and dirty"?), then RJKDOC might be the right thing.
To write or modify RJKDOC documents you need at least some familiarity with SGML. Some introductory material can be found on the web at http://www.oasis-open.org/cover/general.html. Use of an SGML-aware editor is recommended.
Please send any bug reports or suggestions for improvements to Richard Kettlewell <richard+rjkdoc@sfere.greenend.org.uk>. Please give as much relevant detail as possible. Check http://www.greenend.org.uk/rjk/ for announcements of new versions, etc.
RJKDOC documents are SGML documents. If you're familiar with HTML you'll have some of the basics already. A full explanation of SGML is beyond the scope of this manual but we can cover the basics quickly.
As far as we are concerned an SGML document consists of a doctype declaration, saying what type of thing it is (for instance, to distinguish between HTML and RJKDOC documents), and then a top-level element. A doctype declaration looks like this:
<!doctype rjkdoc public "-//greenend.org.uk//DTD RJKDOC 0.1//EN">
An element consists of an open tag, possibly a body, and a close tag. Sometimes the close tag can be left implicit, and the software will work out where it goes automatically. The examples in this manual often rely on this.
The simplest kind of open tag looks like <NAME>. For instance the top level element of an RJKDOC document is started with <rjkdoc>, and finished with </rjkdoc>.
You can also have attributes inside the tag to provide additional information, for instance <NAME ATTR-NAME=ATTR-VALUE>. The attribute values might need quoting: if in doubt, do quote, by putting double quotes around the whole value. Double quotes and ampersands that appear inside the value need escaping; use &dqout; and & respectively. For instance to link to the URL http://www.example.com/?a=b&c=d you might write <url name="http://www.example.com/?a=b&c=d">.
The body consists of plain text and other elements. The meaning of the text depends on the element it appears within (and this is the whole point - you put the tags in to indicate to the software what each bit of the document means, so that it can be processed in the proper way.) If you want to put an angle bracket into the plain text you must use <, and the ampersand must be escaped as above.
An RJKDOC document consists of a title page, which has various bits of administrative information in it, and a body, consisting of chapters and appendices. A contents list is automatically inserted between the title page and the body.
The whole lot is wrapped up in an <rjkdoc> element, and it's also necessary to specify the document type. For example:
<!doctype rjkdoc public "-//greenend.org.uk//DTD RJKDOC 0.1//EN">
<rjkdoc>
<titlepage>
...
<body>
...
</rjkdoc>
The version number in the doctype line will be changed if any new features are added to the DTD.
A title page consists of a title, several author credits, an abstract and a copyright notice. The abstract and copyright notice are optional.
Example:
<titlepage>
<title>A sample document
<author>Fred Bloggs
<abstract>
<p>This is an example document.
Note that the element names (<title>, etc) can be in upper case or lower case.
The title and author elements contain inline text (see section 2.6). The copyright and abstract elements contain structured text (see section 2.5).
The body consists of a sequence of chapters, following by a sequence of appendices. These are both really types of section; the full list of kinds of section is as follows:
"Top level" sections
Second level sections (but can appear as a third-level section within a manpage)
Third, fourth and fifth level sections. If your document needs more depth than this then perhaps it is too complicated!
Second level sections (but with special structural properties) - see section 2.7 for more information.
Third level sections within manpages.
Apart from the manpage sections, which are described below, all kinds of section consist of a heading (which is mandatory) followed by (optionally) structured text (see section 2.5) and then (again, optionally) subsections of the appropriate kind.
All of the section types can take an id attribute, which allows you to provide a symbolic name which can be used in a <xref> element. See section 2.6.2.
The <heading> element contains inline text (see section 2.6).
Examples:
<body>
<chapter>
<heading>The first chapter
<p>The chapter text goes here...
<chapter>
<heading>The second chapter
Structured text comes in three kinds: paragraphs, preformatted text and lists. A block of structured text can be made up of any combination of these kinds of element.
Each paragraph is contained within a <p> element, and is reformatted by the processing software to fit the output medium. The contents of a paragraph is called inline text (see section 2.6). Example:
<p>See <file>rjkdoc.sgml</file> for further examples.
...which formats to:
See rjkdoc.sgml for further examples.
Preformatted text is contained within the <pre> element. No reformatting is done, and it is output in a monospaced font (where there is any choice about fonts). Example:
<pre>+--------------------+ | Boxed in | +--------------------+</pre>
...which formats to:
+--------------------+ | Boxed in | +--------------------+
(In fact, pre contains inline text just as p does.)
Note that the effect of using tab characters within <pre> is undefined, and will probably not do what you want.
Two kinds of list are supported at the moment. The first are tagged lists, which are contained in <taglist> elements and consist of a sequence of tags and items. Each item must be preceded by one or more tags, and you can't have tags without a corresponding item.
Plain lists use the <list> and are the same as tagged lists, except that there are no tags. The processor software might add bullet points or similar.
Items contain structured text. Tags, however, can only contain inline text - in effect they act like a single paragraph of their own.
Example of a tagged list:
<taglist> <tag><lit>file</lit> <item><p>The name of a file <tag><lit>prog</lit> <item><p>The name of a program </taglist>
...which formats to:
The name of a file
The name of a program
Example of an untagged list:
<list>
<item><p>The first item
<p>Second paragraph in the first item
<item><p>The second item
</list>
...which formats to:
The first item
Second paragraph in the first item
The second item
The basic structured text elements can all have <id> attributes. See section 2.6.2.
The simplest kind of inline text is just plain old text. However various markup elements are available to mark filenames, program names, etc:
The name of a file. Example: rjkdoc.sgml
The name of a program. Example: rjkdoc-html
The name of a function or procedure in a programming language. Example: TextDocument::format
A syntactic variable, i.e. a name which stands for something the user supplies. Example: filename
Any piece of text which is to be taken literally, e.g. something to be typed as-is into a computer; effectively the opposite of <var>. Example: <rjkdoc>
Emphasized text. Example: important
An email address. Example: <user@example.com>
An option, e.g. to a program. Example: -debug
Optional text, e.g. in the syntax of a program's command line. Example: [-debug]
All of these elements may be nested, though not all combinations are useful.
There are also some special empty elements that you can use:
This has an attribute of value name which gives the URL referenced. The element is replaced with the value, and (where possible) made into a link.
This has an attribute of value ref which identifies another element in the same document. The element identified is that one that has the same value in its id attribute as the value in the ref attribute of this element.
The elements which can have id attributes are all the section types except for <name> and <synopsis>, plus the basic types of structured text.
The <xref> element is replaced with text describe the referenced element (e.g. "section 2.2.3") and made into a link if possible.
This has two attributes, name and section. The element is replaced with text describing the referenced man page (usually name(section)) and made into a link where possible.
Sections introduced with <manpage> have a special structure. First, the element itself has a couple of attributes:
The name of the man page
The section number of the man page
Secondly, there is no <heading>; it is deduced from these attributes.
Thirdly, the man page doesn't have any initial text but always starts with a <name> element. This contain structured text by convention is always of the format "name - description", where name is the name of the program (or whatever) described and description is a brief summary description.
Following this is the (optional) <synopsis> element. This contains structured text. For programs it is a summary of the command line syntax; the <option> and <optional> elements are intended to be used here. For procedures and functions for a computer language, it lists the headers required and describes the arguments of the procedures and functions document, in whatever is the usual manner for the language. (For example in C, a function declaration is used, with explanatory names for the arguments.)
After this comes the <description> element, which is mandatory. This is the same as <section> except that it has no <heading>. It contains structured text followed, optionally, by <s1> subsections.
Any further sections required are contained in ordinary <section> elements.
Example:
<manpage name=someprog section=1>
<name>someprog - do something or other
<synopsis>
<p><prog>someprog</prog> <var>filename</var>
<description>
<p>The description text goes here...
This appendix contains a reference to the DTD itself and to the tools from the RJKDOC package. The latter may be used to translate RJKDOC documents into HTML, plain text or man pages.
rjkdoc - the RJKDOC DTD
This man page provides a quick reference to the RJKDOC DTD.
The doctype declaration for RJKDOC is as follows:
<!doctype rjkdoc public "-//greenend.org.uk//DTD RJKDOC 0.1//EN">
The following elements are supported by RJKDOC:
This element defines a summary of the document. Usually it would be a single paragraph of structured text, but may be more.
This element contains top level sections, and consists of a heading followed by plain text, followed by any number of sections and manual pages.
This element defines an author (either of the document or whatever the document describes).
This element encompasses the main body of the document. It consists of zero or more chapters followed by sero or more appendices.
This element contains top level sections, and consists of a heading followed by plain text, followed by any number of sections and manual pages.
This element contains the copyright notice for the document, which should be structured text.
This element contains the description section of a man page, and consists of structured text and <s1> subsections.
This element is used in inline text to delimit emphasized text. Note that there is no way of explicitly specifying bold, italic, etc.
This element is used in inline text to delimit email addresses.
The file tag is used in inline text to delimit filenames.
This element defines the heading for a section.
This element contains an item, as found in a list of some kind. Its contents is structured text.
This element contains a list, which is just a sequence of one or more items. Lists are an instance of structured text.
This element is used in inline text to delimit literal text, e.g. a string that would be typed unaltered into a program.
This defines a section of the document which stands as a man page. It contains a name, an optional synopsis, a description and any number of ordinary sections.
The name of the man page should be given in the name attribute and the section in the section attribute.
This empty element expands to a man page reference. The name attribute should be the name of the target man page and the section attribute should have the section. Normally this would expend to the name followed by the section in parentheses.
This defines the name section of a man page. It would normally be a single paragraph of structured text.
This element is used in inline text to delimit the name of an option, e.g. to a UNIX command line program. Usually the formatting would be the same as for <lit>.
This element is used in inline text to delimit optional text, e.g. in the description of the syntax of a command. Normally this would expand to square brackets.
This element contains a paragraph. It is an instance of structured text, and contains inline text.
This element contains preformatted inline text.
This element is used in inline text to delimit the names of functions and procedures, for example as found within a program's source code.
This element is used in inline text to delimit the names of programs.
This element surrounds the entire document. It consists of a title page followed by a body.
These elements represent increasingly deeply nested subsections. Each consists of a heading, structured text and (except for s3) subsections of the next level down.
This defines a top-level section of a chapter, appendix or man page. It consists of a heading, structured text and <s1> subsections.
This defines the synopsis section of a man page. It is constructed of structured text and would normally give a summary of the syntax of the command or function document, or whatever.
This element contains a tag as found in a tagged list. Its contents is inline text.
This element contains a tagged list, a primitive kind of table. It consists of a sequence of one or more tag-item groups; each such group consists of one or more tags and a single item. Tagged lists are an instance of structured text.
This element contains the title of the document.
This element defines the title page of a document. Typically this would appear at the start of a formatted version, though it doesn't have to.
A title page consists of a title, one or more authors, an optional abstract and an optional copyright notice.
This empty element defines a reference to a URL, which is specified using the name attribute. In HTML for example the URL would be formatted as a link (as well as the literal text).
This element is used in inline text to delimit the names of metasyntactic variables, i.e. strings in documentation that would stand for something else in a real example.
This empty element defines a reference to some other point in the document. The ref attribute should have the name of the other point in the document; the element will be replaced in processing by some appropriate text.
The following tags all support id attributes, which contains strings used as the target of ref attributes in the <xref> element: <chapter>, <appendix>, <manpage>, <description>, <section>, <s1>, <s2>, <s3>, <p>, <pre>, <taglist> and <list>.
The following entities are defined.
Æ
Á
Â
À
Å
Ã
Ç
Delta
É
È
Gamma
Í
Î
Ì
Ñ
Ó
Ô
Ò
Omega
Ø
Õ
Phi
Pi
''
prod
Psi
Sigma
sum
Theta
Ú
Ù
Upsi
Xi
Ý
á
â
æ
à
aleph
alpha
&
and
ang
~
å
*
ã
beta
bottom
\\
-
-
cap
ç
¢
chi
o
^
clubs
:
,
@
~=
©
cup
dArr
darr
delta
diams
÷
$
·
é
ê
è
{}
epsi
=
==
&
eta
</
exist
forall
gamma
>=
\'
>
<=>
<->
hearts
...
-
í
î
¡
ì
image
infin
int
iota
¿
isin
kappa
<=
lambda
(
<-
{
<=
_
(
[
<
---
|
-
µ
nabla
--
=/=
<>
¬
notin
nsub
nsube
nsup
nsupe
ñ
nu
#
nvDash
nvdash
ó
ô
ò
omega
oplus
or
ø
õ
otimes
¶
part
%
phis
pi
+
±
£
'
prop
psi
'
=>
)
->
}
real
rho
)
]
§
;
\
sigma
sigmav
spades
square
sub
sube
sup
supe
ß
tau
theta
~
×
[TM]
uArr
ú
uarr
û
ù
upsi
|=
|-
|
xi
ý
y
zeta
rjkdoc-text(1), rjkdoc-html(1), rjkdoc-man(1)
rjkdoc-text - convert rjkdoc sgml to plain text
rjkdoc-text [--debug] [--raw|--overstrike|--no-overstrike] filename
rjkdoc-text --help
rjkdoc-text --version
rjkdoc-text converts the file listed on the command line to a plain text file, and writes it to standard output.
Normally the immediate output of the processor is automatically piped through strike-text(1) to convert it to plain text (possibly with overstrikes). However it is also possible to get the raw output.
If you generate output with overstrikes, then programs such as less(1) can be used to read it. Also your printer may or may not be able to handle it directly.
Debug mode
Raw mode; the output will contain escapes intended for processing by strike-text(1).
Overstrike mode; the output will use backspaces and overprinting to get bold and underlined text.
Non-overstrike mode (the default).
Display usage summary
Display version number
rjkdoc-man(1), rjkdoc-html(1), strike-text(1), rjkdoc(5)
rjkdoc-html - convert rjkdoc sgml to HTML
rjkdoc-html [--debug] [--style filename] filename
rjkdoc-html --help
rjkdoc-html --version
rjkdoc-html converts the file listed on the command line to a single HTML file, and writes it to standard output.
Debug mode
Sets the name of the file to include in the document header instead of the embedded stylesheet. This can be an embedded stylesheet itself, or a collection of links to stylesheets, or something else.
Display usage summary
Display version number
The HTML file includes an embedded stylesheet, which may be overridden. It defines the following classes:
These are all used for the RJKDOC element of the same name.
Used for the <title> element
Used for <author> elements
Used for the abstract
Used for the copyright notice
Currently the output goes to a single big HTML file. Particularly for larger projects it would be useful to be able to split it up by chapter. This shouldn't be too hard to implement.
rjkdoc-text(1), rjkdoc-man(1), rjkdoc(5)
rjkdoc-man - extract man pages from rjkdoc sgml
rjkdoc-man [--directory directory] [--debug] filename
rjkdoc-man --help
rjkdoc-man --version
rjkdoc-man extracts the manpage sections from the file listed on the command line and writes them to files named name.section in the specified directory (or the current directory).
The date field in the .TH macro at the top is set from the last update time on the input file, and is formatted as year-month-day. The title field is taken from the title element of the input.
Debug mode
Specifies the directory where the output files should be written. The default is the current directory.
Display usage summary
Display version number
rjkdoc-text(1), rjkdoc-html(1), rjkdoc(5)
strike-text - convert marked text to plain or overstrike text
strike-text [--overstrike|--no-overstrike]
strike-text --help
strike-text --version
strike-text is a filter used to convert the intermediate "raw" form generated by rjkdoc-text(1) to either plain text, or plain text using overstrikes to achieve the effects of bold type and underlining. It always reads from standard input and writes to standard output; it is not possible to specify a filename on the command line. It is only really intended to be used from rjkdoc-text(1).
In the input, the following sequences have special meaning:
Start of bold text
Start of underlined text
Return to plain text
A literal !
Generate output using overstrikes (the default)
Generate plain text output, without overstrikes
Display usage summary
Display version number
rjkdoc-text(1)