Create a New Document
The GENESIS Documentation System is fully automated with versioning under
the control of monotone. To learn more about monotone and its use by
GENESIS see Version Control and to learn more about the levels of GENESIS
documentation see Documentation Overview. This document assumes that you
are familiar with that material.
Here, we introduce some of the flexibility, features, and requirements of the
GENESIS Documentation System. We describe the location of source files within
this system, the contents of a documentation folder/directory, and how to create a
new document. UNIX shell command line utilities are available to query and
maintain the GENESIS Documentation System as a filesystem based database of
To learn how to add a new document to the GENESIS version control system
see Version Control. Once a document is under version control and identified
with the correct tags (see below) it can be automatically published from your
local computer to the GENESIS website (www.genesis-sim.org) to be available for
other members of the GENESIS community.
Location of GENESIS Documentation
Following a Developer Installation the documents that make up the GENESIS
Documentation System are located in your local workspace. The default location
of your local workspace is:
The source materials for individual GENESIS documents are located in uniquely
named folders/directories in your local workspace. One of the directories in
the workspace is named NewDocument. This directory and the files it
contains provide the templates for a generic GENESIS document. The
files included by default are descriptor.yml and NewDocument.tex, and a
sub-directory named figures (see also GENESIS source code directory
The Default YAML Descriptor File
The name of the descriptor file descriptor.yml should not be changed. The default
contents of this file include: attributes (terminated by a colon) and tags (indicated
by a hyphen), for example:
comment: Optional comment.
description: Briefly describe document contents here.
document name: Insert a user readable document name here.
- --- The three dashes on the first line of the file descriptor.yml are part
of the YAML syntax for automated software engineering.
Note: The meaning of the white space/indents in the descriptor.yml
file is defined for YAML.
- comment: Optional comment about the documentation file, e.g. reason
for being tagged -obsolete.
- description: The default file description “Briefly describe file
contents here.” should be replaced with a short description of the
subject matter of the documentation file. It is recommended that this
file description is less than 80 characters on a single line.
- documentname: Provide a document name which gives the title of the
documentation file. This name is used as a link to the given file in the
GENESIS Documentation System. This name is independent of and
should be more human readable than the actual name of the document
file it identifies.
- tags: List of tags used to identify the current document and locate
it correctly in the documentation hierarchy. The default tags include
-genesis3, -level2, and -published. These tags indicate that the
document is part of the GENESIS Documentation System at the level of
User Guides and Documentation (Level 2) and that that the document
will be published when documentation is rebuilt (see neurospaces_cron),
but that in the absence of a - contents-level2 tag, the document
name will not appear in the Level 2 Contents index (see below).
- New tags may be created by adding them to the descriptor.yml
file, but see below for a list of the tags currently recognized. Note:
The tagging system is case insensitive to avoid tag duplication.
- Importantly, each
of the directories contents-level1 . . . contents-level7 in your
local workspace contains a list of the documentation to be found at
the given level. These content indices are generated automatically
during a GENESIS installation, a userdocs module installation,
or a GENESIS update. They provide direct links to all documents
tagged for the given level of documentation.
Two important attributes are not included in the default descriptor.yml file, but may
be added as required:
- redirect: If present, this attribute is followed by a user supplied URL
and automatically generates a HTTP redirect during a documentation
system build. This allows documentation external to the GENESIS
Documentation System to be automatically incorporated in the absence
of any local documentation (with the exception of the descriptor.yml
file). See HTTP redirect for an example.
- summary: If present, this attribute is followed by a short user
supplied description of the contents of the document. This description
will appear after the document name on the contents index
page of the documentation level given by (for example here) the
The Default Documentation Source File
Source files for the GENESIS Documentation System are currently produced with
the LATEX typesetting package (see www.latex-project.org). It is planned
that Microsoft Word (.doc format) and OpenOffice (.odt, ODF format) file
formats will also be automatically recognized by the GENESIS Documentation
The default LATEX documentation source file NewDocument.tex in the
NewDocument folder can be compiled to produce a readable PDF file. It gives
help and examples for colorizing text, generating static hyperlinks to
local and remote documentation, and how to insert a figure into your
The Figures Folder
This directory contains any figures that your new document source file may
include. The name of this folder should not be changed.
Create a New Document
There are four simple steps to the creation of a new document within the
GENESIS Documentation System.
- Create document: To automatically create one or more new document
template structures, simply envoke the userdocs-create script at a terminal
command line prompt and give the name of the document you wish to
create as an argument:
This command creates a new document folder/directory and its
sub-directories by copying the template NewDocument file and assigning the
given document name to both the documentation folder (here, for example,
it would be my-document) and the default documentation file it contains
(here, my-document.tex). It also inserts a description and a document name
into the descriptor.yml file.
You can also specify multiple document names to create a series of
userdocs-create <my-document1> <my-document2> <my-document3> . . .
Important: It is a requirement of the GENESIS Documentation System
that the names of the descriptor file descriptor.yml and the directory figures
located in the document folder should not be changed.
For more details see Manual Document Creation. The remaining steps in
document creation are currently manual.
- Add Related Document Hyperlinks: Hyperlinks to one or more related
documents are by default located at the beginning of each document source
.tex file following the Related Documentation heading. There are two
ways to add links here:
- Hyperlinks to Manually Created
GENESIS Documentation: For Level 1 and 2 documentation,
this is done in the usual way with the LATEX href command. See
New Document for an implementation example .
- Hyperlinks to Automatically Generated GENESIS
Documentation: Hyperlinks to the automatically generated
documentation of Levels 3–7 requires a tagging construct. This is by
default located at the beginning of each document source .tex file
following the Related Documentation heading. The generation
of these links is controlled by a tagging construct which is
automatically expanded whenever the document system is
% start: userdocs-tag-replace-items <related-do-nothing>
% end: userdocs-tag-replace-items <related-do-nothing>
The default tag for this system is <related-do-nothing>, which
allows a document to be created and published in the absence of any
More than one related document hyperlink can be added to a
document by the addition of tags you create that replace the default
tag. For example:
% start: userdocs-tag-replace-items <your-tag-name1> <your-tag-name2> <your-tag-name3> . . .
% end: userdocs-tag-replace-items <your-tag-name1> <your-tag-name2> <your-tag-name3> . . .
As shown in the above example, the related tag(s) should have the
where <your-tag-name1> is replaced by an identifier you
Note: The default related document hyperlink related-do-nothing
relies on a document called do-nothing.tex.
- Update the descriptor.yml file: Each directory/file in the GENESIS
Documentation System is tagged on the basis of its content, for
- The GENESIS version: This tags the version of GENESIS that
the document refers to, e.g. -genesis3.
- Level of the GENESIS document: This must be one of
the seven levels of the GENESIS Documentation System, which
- -level1 (introductory documentation)
- -level2 (user/developer documentation)
- -level3 (autogenerated documentation)
- -level4 (autogenerated technical documentation)
- -level5 (autogenerated algorithm documentation)
- -level6 (autogenerated api documentation)
- -level7 (inline source code documentation)
Important: When creating a new document, the default tag
(-level2) in the associated descriptor.yml file should be replaced with
a tag from the above list that identifies the correct level of the
For more on the levels of the GENESIS Documentation System see the
- Tag Appearance of Document Name in Contents Index: A
document name (given by the documentname: attribute) will not
appear in the documentation contents list unless one of the
-contents-level1…-contents-level7 tags is present in the
associated descriptor.yml file. The presence of this tag results in the
document name being placed in alphabetical order in the contents page
of the level specified by the tag. If you do not want the name of the
document to appear in the contents page you should remove this
tag. This functionality allows one or more documents to be
hyperlinked from a summary document (see particularly Level 1
and 2 documentation) without the name of the hyperlinked
document(s) also appearing in the contents page of the given
- Insert “Related Document” hyperlink tags: To link a new
document (Referring Document in following figure) to another
document (Referenced Document in following figure) under its
Related Documentation section, place the appropriate tag after the
tag construct at the head of the Referring Document and place
the same tag in the descriptor.yml file of the Referenced
Document. The following figure illustrates these relationships.
- Tag document origin: If the document has been created from one
located on the Neurospaces wiki then a --wiki tag should be
inserted in the descriptor.yml file.
- Tag document status: For a given document to be part of
the documentation version control system and the GENESIS
Documentation System, it must be in a documentation folder along
with a descriptor.yml file that contains only one of either the -draft,
-local, or -published tags. Note: The -published tag in the
descriptor.yml file associated with your new document should
be replaced with the -draft tag while you are working on
the document to prevent it being published to the GENESIS
Precedence of publication related tags: Three tags control
publication of documents within the GENESIS Documentation System.
They are interpreted in a hierarchical manner, such that the
presence of the -draft tag along with either the -local and/or
-published tag will prevent the document from being included into a
build/update of the Documentation System. Alternatively, a document
will not be published to be browser viewable in the absence of
either the -local or -published tag. So if documentation
is (not) appearing where you expect after an update, it is a
good idea to check the publication tags in the descriptor.yml
- -draft: The presence of this tag in the descriptor.yml file
associated with a document will prevent the document
from being published, i.e. viewable within a browser. For a
document to be publishable, the -draft tag must be replaced
with either the -local or the -published tag.
- -local: This tag indicates that a document will be included
into any local build of the the GENESIS Documentation
System. The presence of this tag means that a document will
be browser viewable on (a) local machine(s), but will not
appear as a ‘published’ document on the GENESIS web site
at http://genesis-sim.org. This tag is useful to developers
for checking documentation prior to publication on the web
via the GENESIS web site and can be used to control who
can view documentation locally.
- -published: The presence of this tag in the descriptor.yml
file will cause the associated document to be published to the
GENESIS Documentation System on the GENESIS web site,
as long as neither the -draft nor the -local tags are present
in the same descriptor.yml file (see next item). Similarly,
absence of the -draft tag but presence of the -local tag
will prevent publication of a document to the GENESIS web
site even if the -published tag is present.
Tags in the descriptor file currently recognized by the documentation
build system include:
Other useful tags include:
Note: User supplied tags not recognized by the documentation
build system may still be useful for local control and sorting
of documentation. Importantly, when adding your own tags
remember that the interpretation of the descriptor.yml file by the
GENESIS Documentation System is sensitive to white space and
- Update the figures folder: Place any figures or images, etc that your
source document file contains in the figures directory.
Incorporate References in Your Document
The GENESIS Documentation System currently supports BibTeX by default.
The two LATEXcommands at the end of the NewDocument template enable this
functionality. They are:
These commands allow you to define a citation style for your references and give
the location of a file that complies with the BibTex file format requirements
and contains your bibliography. Currently, the default name of this file is
g3-refs.bib. It contains all the references for the GENESIS Publication
Incorporate a Pre-existing Document, File, or Video
The GENESIS Documentation System recognizes a number of different file
formats. The purpose is to allow preexisting documentation to be directly
included without having first to be converted to the LATEX format.
To incorporate a pre-existing document into the GENESIS Documentation
- Include a tag in the descriptor.yml file in the document directory.
Currently, the following file format tags are recognized (Note. No tag
is necessary for either LATEX files as the .tex file name suffix is the
default for the GENESIS Documentation System or .eps files in the
- - eps Encapsulated postscript.
- - pdf Portable document format.
- Place the document file in the document directory (NOT the figures
It is also possible to incorporate audio and video files as part of documentation.
Currently recognized audio file format tags include:
- - wav Microsoft .wav file format.
- - mp3 Digital audio encoding format.
To incorporate video into a GENESIS document:
- Create an account with a video sharing website, e.g. YouTube.
- Upload your video(s).
- Embed a link to the video(s) into the document describing their
contents. See NewDocument, for further details.
Note: With document incorporation (c.f. creation) the document to be
included is located in the <document-name> directory and NOT the figures
Document Version Tracking and Control
To learn more about document version tracking and control in the GENESIS
Documentation System, see Version Control.
Document Hyperlink Checking
The validity of the hyperlinks embedded in GENESIS documentation (see
NewDocument) are checked by userdocs_cron each time the GENESIS
Documentation System is rebuilt. The output of this check can be viewed at
Webcheck can also be run locally to check hyperlinks. When run in
directory, the command makewebcheck will produce a report in
To learn more about the automated publication of documents in the GENESIS
Documentation System, see Publication.