The Doco Manual

Doco is a simple but powerful text-to-web engine.

Contents

    The Doco Manual
        Introduction
        Installation
        Quick Start Tutorial
        Advanced Topic: Styling
        Advanced Topic: Table Cell Spanning
        Advanced Topic: Variable Substitutions
        Advanced Topic: Additional Features
        Power Feature: Index Page Generation
        Power Feature: Table of Contents
        Power Feature: Breadcrumbing
        Power Feature: Document Inclusions
        Power Feature: Templating
        Power Feature: Custom Mappings
        Power Feature: Versioning
        Power Feature: Snapshotting
        Ant Build Integration
        Roll Credits..

This manual pertains to release version 0.8, which is available for download here.

You can view this document in sections, as one long page, or in it's source form.

Please aid this project by making support requests and bug reports where necessary.

Introduction

Producing presentable documentation is mildly uninteresting (strike that), downright boring and often incredibly frustrating.

You've basically got 3 options, in order of user-friendliness.

• Word Processor - go with the herd and use Word. Linux users, Windoze bashers and people who don't have it installed won't hate you. Much. Exporting to web page(s) will always render predictable, lightweight markup which looks exactly like you wanted it to (er.. I lied)
• HTML - lovingly (cough) hand-crafted or generated by some heavyweight bloatware
• Wiki - choose arbitrarily from 1m flavours and also experience the joys (splutter) of installing and configuring the product itself, PHP, mySQL, a web server..
• XML - use the extremely simple and lightweight (ahem) DocBook standard, or better still reinvent the wheel with your own format and XML transforms (please don't)

Or maybe you could try Doco.

It's not aimed at people trying to make amazing-looking websites.

It is aimed at people who need to produce good-looking, highly navigable document sets, quicksmart.

Installation

Requirements

You can use any platform that supports Java J2SE (no, this does not include your phone).

You need be reasonably familiar with your platform's shell.

Instructions

Install Java

• Download Java JRE 1.4 (or above)
• You may need to view the installation instructions
• You will need to configure some environment variables

Get Doco

• Download Doco from SourceForge.net, and put it in your JAVA_HOME/lib/ext directory.

Simple, eh?

Quick Start Tutorial

Note that this guide assumes that a Java 1.4+ JRE is installed, JAVA_HOME is set, and the java executable is in your path (see the installation section). You should also have an open shell (command prompt).

Proving it Works

The simplest way to prove to yourself that Doco works in your environment and to learn quickly is to play with a pre-existing project - in this case the Doco manual itself (i.e. the source for the pages you're reading right now).

First get Doco to output the zipped version of its own manual:

 java Doco -manual

..this will output a file:

 doco_manual.zip

Unzip it (using a tool appropriate to your operating system), then build the HTML version of the manual from the Doco sources using a 'project file' (which tells Doco where to look for sources and where to output the HTML, etc.):

 java Doco -dpr doco_manual/doco_manual.dpr

Now point your browser at the locally generated document index.

 doco_manual/html/index.html

If you can't see it or it looks funny (it should look like this), please formulate a rude and indignant support request or a bug.

My First Document

Create a file called basic_cribsheet.txt in the current directory. Paste in the following text.

 > Doco Cribsheet (Basic)

 Please look at the "source of this document" {basic_cribsheet.txt}.

 >> Second Level Heading

 Paragraphs are
 formatted automatically,
 despite line breaks.

 >>> Third Level Heading (etc)

 + Relative Heading (+1)

 ++ Relative Heading (+2)

 This is an example of an _italic_ word.

 This is an example of _"an italic phrase"_.

 This is an example of a *bold* word.

 This is an example of *"a bold phrase"*.

 This is an example of a --stricken-- word.

 This is an example of --"a stricken phrase"--.

 This is an example of an +underlined+ word.

 This is an example of +"an underlined phrase"+.

 ?? This is a comment that doesn't appear in the HTML version.

 @ This is an example of an unordered list.
 @@ List elements can be arbitrarily nested.
 @@@ Which is useful.
 @ In many circumstances.

 # This is an example of an ordered list.
 # You can nest these, too.  But we did that already.
 You can have more than one line per bullet.

 This is a single word absolute link to Google {http://www.google.com/}.

 This is a phrase link to the "source of this document" {basic_cribsheet.txt}

 This is a intra-document link to the "Second Level Heading" {#h2.Second Level Heading}.

 Here's an image:

 ((http://doco.sf.net/style/logo.jpg))

 A built in variable is the date, which is Tue Jun 01 14:22:50 BST 2004.

 You can reference your own variables, which may or may not be defined: Captain Pugwash.

 [ Name | Position | Salary ]
 [ Bob | CEO | Massive ]
 [ Sue | Secretary, sleeping with Bob | Considerable ]
 [ Rita | Secretary, not sleeping with Bob | Pitiful ]

 You will find that you need to escape !\{things} sometimes.

 Tab    preservation   works    just    fine.

 ASCII art is old-hat but some people like it.

 /-------------- \    data    /-------------- \
 |   Process A   |----------->|   Process B   |
 \---------------/            \---------------/

 <html> and <xml> tags are not problematic.

 Here is an example of styling a single word [red].

 Here is an example of "styling a phrase" [blue].

 This is an example of a (g)custom mapping(g)
 that will expand to a Google search.

Note that bold, italics, strike and underline can be combined if you observe the following markup wrapping precedence from the outside inwards: bold outermost, then italics, then underline, with strike being innermost.

E.g. an emboldened and italicised word must be presented to Doco like *_this_* and NOT like _*this*_.

Great. Now generate the HTML output. We'll do this in the simplest way possible, first.

 java Doco -in basic_cribsheet.txt -out basic_cribsheet.html

Point your browser at the output file basic_cribsheet.html.

If you're reasonably observant, you'll notice a few things.

1. The document looks very plain (you don't have a CSS stylesheet)
2. The ASCII art isn't working properly (there's no CSS to specify a fixed-width font)
3. The variable 'my.name' does not exist (it wasn't defined)
4. The text you would have expected to appear in different colours, didn't (no CSS classes available with the given names)
5. The promise of a Google search was not fulfilled (you didn't define the mapping)

This is what the cribsheet looks like with the Doco CSS.

Styling the Document

Download this stylesheet (you can modify it or junk it at your leisure).

Create a directory structure like this (you will need to move the files into the correct place).

 quickstart/
       source/
           basic_cribsheet.txt
           style/
               default.css

Now run Doco over the hierarchy. This entails using a different mode.

 java Doco -from quickstart/source -to quickstart/html

Doco will have generated HTML for all documents in the quickstart/source hierarchy into mirror locations in the quickstart/html directory.

In addition, it has generated you a nice index.html. Take a look at this file in your browser.

 quickstart/html/index.html

Now it looks nicer, but the following problems are still present.

1. The variable 'my.name' does not exist (it wasn't defined).
2. The promise of a Google search was not fulfilled (you didn't define the mapping)

To fix these, we need some metadata.

Introducing Variables

Create a file called quickstart/quickstart.dpr. This is a 'Doco Project File'.

Paste the following text into it.

 # Project Information
 # -------------------

 # The name of the project.
 # This will be used by the GUI, eventually.
 doco.project.name=Quickstart Cribsheet

 # Where the source is.
 # This can be a relative or absolute path.
 # Relative paths are relative to this document.
 doco.project.from=source

 # Where to generate documents to.
 # This can be a relative or absolute path.
 # Relative paths are relative to this document.
 doco.project.to=html

 # Doco will try to process files with these extensions.
 # txt and dsf are processed by default unless overridden.
 # doco.sources=dsf,txt

 # Doco will generate index files to this filename.
 # This is 'index.html' unless overridden.
 # doco.index=index.html

 # Variables
 # ---------

 # An example of a custom variable (substitute with (no value for variable 'my.variable'))
 # You can define any { key -> value } pair.
 # Don't use the prefix 'doco.' - this is reserved for Doco.
 my.name=Captain Pugwash

 # Custom Mappings
 # To make these yourself, you should be reasonably technically minded.
 # ---------------

 # This converts a "word or phrase" {http://www.google.com/search?q=word or phrase}
 # into a www.google.com search.
 doco.mapping.(\\s)\\(g\\)(.+?)\\(g\\)=$1"$2"$1{http://www.google.com/search?q=$2}

Now run Doco over this file. The key/value pairs tell it what to do.

 java Doco -dpr quickstart/quickstart.dpr

Uh-oh. Nothing happened. Why? Because the source document did not change, Doco sees no reason to regenerate it, that's why. When you end up with a lot of documents you'll appreciate the time saving. Trust me.

You need to modify the quickstart/source/basic_cribsheet.txt file somehow. Meddle with it somehow, save it, run Doco the same way and reload the page in your browser.

You should now be viewing a carbon copy of this.

Automatic Regeneration

Since invoking Doco every time you make a change is quite dull, you could always opt to use the daemon mode.

Try this.

 java Doco -dpr quickstart/quickstart.dpr -daemon -interval 1

This will cause the process to poll for changes every 1 second.

If you are using Windows then you are unlucky - you will need to open a new MSDOS prompt because this busies your current window indefinitely. UNIX users can of course just put the process in the background.

Make a change to quickstart/source/basic_cribsheet.txt, verify that the daemon output looks like it has done something, then check that the changes havebeen reflected in the HTML output by reloading the page in your browser.

Summary

Well done. If you've completed the Quickstart then you know most of Doco's basic features.

Maybe this is as far as you need to go for what you require, but there are a lot more features.

Advanced Topic: Styling

Default Stylesheet

There will be a <link rel.. to style/default.css in every page generated by Doco.

Style Inheritance

The style directory of each directory in the source hierarchy is inherited by all subdirectories of that directory as mirrored in the output hierarchy. This means you can have disparate style subtrees in the same overall hierarchy.

Reserved CSS Classes

If you use breadcrumbing, the automatically generated navigational aspects of the page will have a CSS class of navigation.

Also, any blocks that look like this

 | some preformatted text

..will be output with a CSS class of raw.

Inlined CSS fragments are also possible by inserting a directive into a document.

 // inline style "relative/path/some-style.css" //

 ..or..

 // inline style "/absolute/path/some-style.css" //

 ..or..

 // inline style "http://some.web.location/style.css" //

Note that HREFs for assets used by the CSS are relative to the CSS in the output hierarchy, not to the generated HTML file itself.

Phrase Styling

You can use any available style class (either in 'default.css' or some inlined CSS) in the normal flow of your document.

Here is an some red text and here is some blue text. And here is a filename.

The above markup looks like this:

 Here is an "some red text" [red] and here is "some blue text" [blue].
 And here is a filename [code].

Advanced Topic: Table Cell Spanning

Table cell spanning is supported. Note that some rows look the same but have different column spanning schemes (look at the source below it to see what's going on):

Spanning is achieved with 'extend leftwards' and 'extends rightwards' syntax. Here is the table above's source.

 [ Cell 1 | Cell 2 | Cell 3 | Cell 4 ]
 [ 1 | 2 | 3 | 4 ]
 [ 1 | -> | 3 | 4 ]
 [ 1 | 2 | <- | 4 ]
 [ 1 | -> | -> | -> ]
 [ <- | 2 | -> | 4 ]

It should be obvious that the following rows are not legal, as there is no preceding or following cell to extend:

 [ -> | x | x ]
 [ x | x | <- ]

You control the look of the table with CSS.

Advanced Topic: Variable Substitutions

Variables are inserted into your source like this.

 My name is $(my.name).
 This document last produced on $(doco.date).

Variable Types

Three types of variables can be used in Doco.

1. Java system properties
2. Standard Doco variables
3. User defined variables

Java Variables

Here are the Java variables you can use..

Standard Doco Variables

User Defined Variables

These must be placed in your .dpr file and are of the following form.

 some.key=some.value

Advanced Topic: Additional Features

Countermanding Processing

This directive stops Doco from processing the document. This can be useful if your document is in a really a bad way (or extremely immature draft status) and you don't want the output to be viewable yet.

Here is an example of the directive:

 // countermand processing (<reason>) //

The <reason> will be output on the console then Doco skips the file that contains this directive.

Power Feature: Index Page Generation

Doco will automatically place an index page..

 index.html

..in each directory it processes for Doco documents. Files of this name that already exist in this directory will be overwritten.

Index File Name

The name of the index file can be altered with an override in your project file.

 doco.index=whatever.html

Ignored Directories

Indexes will not be generated for

• Directories called style or CVS
• Directories containing a file called .docoignore

Directories containing a .docoignore file will also not appear as subdirectories of parent indexes.

Descriptive Text

If you place a file with the name

 description

..in any given directory, then this is written to the Doco index by way of explanatory text.

The names of your files are automatically and ordered tidied for viewing.

Here is an example index.

Power Feature: Table of Contents

A contents section can be inserted anywhere in the document, but of course it's normally best at the top, just after the first heading.

The directive to tell the processor to do this for you is:

 // insert automatic index, level <N> //

..where <N> is the depth to which you would like indexing. Anything more than about 5 may suggest an overly-hierarchical document.

You will have noticed a contents section in the first page of this document.

Power Feature: Breadcrumbing

This feature allows you to split the document into chunks, and to navigate forwards, backwards and upwards within it.

The directive used to tell the processor to do this is

 // split into pages //

By default (as shown above), Doco will split every section into a separate page. However, it is usual to want breadcrumbing to occur up to a specified level, rather than for all levels.

You do this with an until clause.

 // split into pages until level 2 //

Whenever page splitting is enabled, Doco also writes a 'printable' version (i.e. one that is not split into pages) to the file, i.e.

 <originalFileName>_full.html

..in the target directory.

You can always reference this file from within the breadcrumbed document using the following variable.

 $(doco.document.printable)

Power Feature: Document Inclusions

Doco has two types of includes - one happens before any Doco markup is parsed, and the other includes directly into the document directly before it's finalized to disk.

Both of them can take relative (to the source document location) and absolute paths.

 // include "relative/path/file.txt" before processing //
 // include "/absolute/path/Sample.java" before processing and indent //
 // include "relative/path/include.html" after processing //
 // include "/absolute/path/include.html" after processing //

If the file is not found, an error message is inlined into the document.

 *"The file <fileName> does not exist!"*

Power Feature: Templating

Doco supports templates, which are really easy to use.

Here are the steps involved in using templates:

• Create a template file, say 'report.dtf'. The extension '.dtf' means "Doco Template File"
• Fill in the template with whatever structure you want, using any Doco conventions you want
• Create Doco variable placeholders for the data you want to be replaceable
• Create a document, say 'my_report.txt' and specify the template's variable placeholders

Doco does the rest!

Here's an example template.

And here's a document that uses the template.

Since both of these files exist in the Doco manual project, you can view the actual generated result to see what it looks like.

Power Feature: Custom Mappings

Mappings are defined in your .dpr file.

 doco.mapping.<searchExpression>=<replaceExpression>

You need to be reasonably technically minded to be able to understand regex syntax.

Here is an example custom mapping.

 # A custom mapping (this is a dictionary.com lookup)
 doco.mapping.(\\s)\\(d\\)(.+?)\\(d\\)\\s=$1"$2"$1{http://dictionary.reference.com/search?q=$2}$1

You would use it like this

 ..which was a nice (d)seque(d) from the previous topic..

While we're about it, you might as well see what segue means (this example uses the same mapping).

Note that the <searchExpression> is subject to some Java Properties loading escaping rules.

It is very likely that you will need to tinker with any custom mapping a few times before you get it working properly.

Power Feature: Versioning

Doco supports versioning in an unusual but useful way.

To start at the beginning, the directive for versioning is of the form

 // version <version> //

..where <version> is completely up to you, e.g. "1.0", "draft" etc.

For the purposes of this explanation, we will assume a document called "func_spec", with a version of "1.0". When a versioned source is processed by Doco, the following things happen:

• The original (func_spec.txt) is copied to func_spec_v1.0.txt in the source hierarchy. This means you have a copy of the 1.0 source when you move to a new version.
• This versioned source (func_spec_v1.0.txt) is copied across to the output hierarchy (in the usual manner).
• The outputs of the source document become versioned. The outputs for the example document source func_spec.txt may include:
• func_spec_v1.0.html (the vanilla output location, or the first page of a split document).
• func_spec_v1.0_<pageNumber>.html (for documents that have been split into pages).
• func_spec_v1.0_full.html (for the printable version of a page-split document).
• The vanilla output name (func_spec.html) will comprise a navigable table of versions, ordered by last-generated date.
• All non-versioned links to vanilla outputs will be repointed to their versioned equivalents.

It is worth noting that if a non-versioned document becomes versioned, any referring pages' links will thenceforce take you to a table of versions rather than the document itself (useful, as the referring document cannot know which version is pertinent to the viewer).

Power Feature: Snapshotting

Snapshotting is analagous to petrifying the state of related assets, so that items linked to by your document are effectively frozen in time. This means that if you are including (say) a diagram which you know may change (but your document is pertinent only to what that diagram looks like right now) then you can take a snapshot (copy) and your links will be re-pointed automatically.

Doco does this with the following directive:

 // snapshot <pattern> "<codeName>" //

..where <pattern> is a regular expression pattern, and <codeName> is any identifier of your choosing ("alpha", "moses", "2004-10-10" etc.).

An example would be:

 // snapshot .*\\.gif "Jan-2004" //

The above directive would snapshot all GIF images with a codename of "Jan-2004".

The <pattern> will partially match against links to other documents, images etc (in fact anything that can be linked to with an HREF). "Partial" matching means that if the linked asset contains the pattern then it's considered a match (rather than requiring an exact match, which would be laborious to enumerate).

The <codeName> is useful as it allows different documents (possibly authored by different people) to share the same frozen assets. Say you and a colleague are working on different technical documentation but you both include a diagram (and that diagram is subject to change, which your documents do not want to reflect). In that case, both of you can agree a codename to use for a certain state of that asset (e.g. "draft", "1.0", "alpha" or some made up funky-sounding name).

There is some behaviour of the snapshotting algorithm that is worth knowing about:

• If a matched link starts with "http://", it is ignored (because the resource is not local)
• A matched link starting with "file://" is perfectly legal. Doco will work out whether it's an output-document-relative or absolute path.
• If the link can possibly be part of an output of the source document (i.e. pointing at, or within an output of itself), then it is excluded from the match algorithm. This exclusion list includes:
• The source document itself (e.g. func_spec.txt)
• Any versioned copy of the source or output documents (e.g. func_spec_v<anyVersion>.txt or func_spec_v<anyVersion>.html)
• Printable versions of the output, if it was split into pages (e.g. func_spec_full.html or func_spec_v<anyVersion>_full.html)
• Any page of the output, if it was split (e.g. func_spec_10.html), including when these pages are versioned (e.g. func_spec_v1.0_10.html)

Ant Build Integration

Doco is easily integrated into Ant builds.

 <target
     name="doco"
     description="Documents the Project."
 >
     <taskdef name="doco"
         classname="com.acmejava.doco.DocoAntTask"
         classpath="<path_to>/doco-${doco.version).jar"
     />
     <doco
         dpr="my_project.dpr"
     />
 </target>

Roll Credits..

Contributors

Thanks to all of the following people who have contributed in one way or another.

• James Dodd (lead developer)
• Simon Birt
• Mark Phillips
• Paul Krause
• Camden Holt
• Raffaello Bartocci
• Tethys
• Peter Wouda
• Sam Hatoum
• Jason Harris

Known Users

If you find Doco useful, please tell us about it.