?? Author: James Dodd (doddjames@yahoo.co.uk)

// version 0.8 //

// inline style "style/justified.css" //

// split into pages until level 2 //

> The Doco Manual

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

// insert automatic index, level 2 //

This manual pertains to release version $(doco.document.version),
which is "available for download here" target:doco_distro{http://sourceforge.net/project/showfiles.php?group_id=95529}.

You can view this document "in sections" {doco.html}, as "one long page" {$(doco.document.printable)},
or in it's "source form" {manual.txt}.

Please aid this project by making "support requests" {http://sourceforge.net/tracker/?func=add&group_id=95529&atid=611703} and
"bug reports" {http://sourceforge.net/tracker/?func=add&group_id=95529&atid=611702} 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 "XSL" 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" target:jre{http://java.sun.com/j2se/1.4.2/download.html} (or above)
@ You may need to "view the installation instructions" target:jre_instruct{http://java.sun.com/j2se/1.4.2/jre/install.html}
@ You will need to configure some environment variables

[ Environment Variable Name | Value to Set ]
[ JAVA_HOME [code] | Where Java was installed to ]
[ PATH [code] | Your original path, plus JAVA_HOME/bin [code] ]

>>> Get Doco

@ Download Doco from "SourceForge.net" target:doco_distro{http://sourceforge.net/project/showfiles.php?group_id=95529}, and
put it in your "JAVA_HOME/lib/ext" [code] directory.

Simple, eh?

>> Quick Start Tutorial

_"Note that this guide assumes that a "Java" 1.4+ JRE is installed, JAVA_HOME [code] is set,
and the java [code] executable is in your path (see the "installation section" {#h2.Installation}).
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" {index.html}), please formulate
a rude and indignant "support request" {http://sourceforge.net/tracker/?func=add&group_id=95529&atid=611703} or
a "bug" {http://sourceforge.net/tracker/?func=add&group_id=95529&atid=611702}.

+ My First Document

Create a file called basic_cribsheet.txt [code] 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 $(doco.date).
|
| You can reference your own variables, which may or may not be defined: $(my.name).
|
| [ 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 [code].

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" {basic_cribsheet.html}.

+ Styling the Document

Download "this stylesheet" {style/default.css} (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 [code] hierarchy
into mirror locations in the quickstart/html [code] directory.

In addition, it has generated you a nice index.html [code].  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 [code].  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 $(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 (g)word or phrase(g)
| # 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 [code] 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 {basic_cribsheet.html}.

+ Automatic Regeneration

Since invoking Doco every time you make a change is quite dull, you could always opt to use the daemon [code] 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 [code] 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 [code], verify that the daemon [code] 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.." [code] to style/default.css [code] in every page generated by Doco.

>>> Style Inheritance

The style [code] 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 {#h2.Power Feature: Breadcrumbing}, the automatically generated navigational aspects of the page will have
a "CSS" class of navigation [code].

Also, any blocks that look like this

| | some preformatted text

..will be output with a "CSS" class of raw [code].

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 [code] 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" [red] and here is "some blue text" [blue].  And here is a filename [code].

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):

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

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.

# Java system properties
# Standard Doco variables
# User defined variables

>>> Java Variables

Here are the "Java" variables you can use..

[ Property | Meaning | Value during this build ]
[ file.separator | File separator | $(file.separator) ]
[ java.class.path | Java classpath | (too long to show here) ]
[ java.class.version | Java class version number | $(java.class.version) ]
[ java.home | Java installation directory | $(java.home) ]
[ java.vendor | Java vendor-specific string | $(java.vendor) ]
[ java.vendor.url | Java vendor URL | $(java.vendor.url) ]
[ java.version | Java version number | $(java.version) ]
[ line.separator | Line separator | (a control character) ]
[ os.arch | Operating system architecture | $(os.arch) ]
[ os.name | Operating system name | $(os.name) ]
[ os.version | Operating system version | $(os.version) ]
[ path.separator | Path separator (for example, ":") | $(path.separator) ]
[ user.dir | User's current working directory | $(user.dir) ]
[ user.home | User home directory | $(user.home) ]
[ user.name | User account name | $(user.name) ]

>>> Standard Doco Variables

[ Variable | Meaning | Value during this build | Assignation ]
[ doco.date | toString of a new Date object | $(doco.date) | Dynamic ]
[ doco.version | The version of Doco used | $(doco.version) | From doco-variables.properties ]
[ doco.author | The author of Doco | $(doco.author) | From doco-variables.properties ]
[ doco.document.version | The version of the document (if versioned) | $(doco.document.version) | Dynamic ]
[ doco.document.printable | The name of the printable version of the document (if split into pages) | $(doco.document.printable) | Dynamic ]

>>> User Defined Variables

These must be placed in your .dpr [code] 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 [code] or CVS [code]
@ Directories containing a file called .docoignore [code]

Directories containing a .docoignore [code] 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" {index.html}.

>> 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" {#h1.The Doco Manual}.

>> 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 [code] 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" target:template{templates/example_template.dtf}.

And here's a "document that uses the template" target:templated{templates/example_templated.dsf}.

Since both of these files exist in the Doco manual project, you can view
the "actual generated result" target:templated_result{templates/example_templated.html} to see what it looks like.

>> Power Feature: Custom Mappings

Mappings are defined in your .dpr [code] file.

| doco.mapping.<searchExpression>=<replaceExpression>

You need to be reasonably technically minded to be able to understand "regex syntax" {http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html}.

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 (d)segue(d) means (this example uses the same mapping).

Note that the <searchExpression> is subject to some Java "Properties loading" target:java_api{http://java.sun.com/j2se/1.4.2/docs/api/java/util/Properties.html#load(java.io.InputStream)} 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" target:_regexp{http://java.sun.com/j2se/1.4.1/docs/api/java/util/regex/Pattern.html},
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 {http://ant.apache.org/} 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" {mailto:doddjames@yahoo.co.uk}.

[ Company | Business | URL | Usage Profile | Build Integration? ]
[ Create Services Ltd | Credit Cards | http://www.createservices.com/ | Technical Documentation | Y ]
[ Trampoline Systems | Collaboration Software | http://www.tramposys.net/ | Technical Documentation | Y ]