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.

The document looks very plain (you don't have a CSS stylesheet)
The ASCII art isn't working properly (there's no CSS to specify a fixed-width font)
The variable 'my.name' does not exist (it wasn't defined)
The text you would have expected to appear in different colours, didn't (no CSS classes available with the given names)
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.

The variable 'my.name' does not exist (it wasn't defined).
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.