Here we describe a number of UNIX shell command line utilities to query and maintain the GENESIS Documentation System as a filesystem based database of documents. Note that these tools are not used to search the contents of the documents. The GENESIS and Neurospaces websites provide this type of user-functionality.
Typing userdocs- in a bash system command shell followed by striking ¡tabż key twice will show all the available commands to query and maintain the GENESIS Documentation System.
Each command has a help page that shows all the available options to the invoked command. This page isinvoked by the –help argument (for example userdocs-build –help).
Here we summarize the function of all the commands.
This is an interactive tutorial with examples that show typical usage of the tools mentioned above.
To learn about how to build individual documents:
$ userdocs-build --help
userdocs-build: build documentation and prepare them for web
publication. Arguments on the command line are taken as documents
that need to be build. If no arguments are given, all documents will
/usr/local/bin/userdocs-build <document name1> <document name2> ...
--check check documentation filesystem correctness.
--dry-run print what documents would be build without actually building them.
--email send the built document to this email address, repeat for each receiver.
NOTE: see http://www.amirwatad.com/blog/archives/2009/03/21/send-email-from-the-command-line-using-gmail-account/ as an example of a local configuration of your MTA.
--help print usage information.
--parse-only only execute parse commands, without actually building documentation.
--regex selects documents by name (default is all).
--report-output report what output has been generated.
--report-tags report the tags associated with the selected documents instead of building the documents.
--set-name select a document set (builtin default is userdocs).
--tags process the documents with these tags, multiple tags options may be given.
--version give version information.
--v|verbose tell what is being done, specify multiple times to get more feedback.
firefox -new-window html/htdocs/neurospaces_project/userdocs/documentation-homepage/documentation-homepage.html
To display all the tags currently in use:
$ userdocs-build --report-tags
To learn what documents are shown on the contents page of level 1 documentation:
$ userdocs-build --tags contents-level1 --dry-run
We can then build one specific document (for instance the user-intro document) with:
$ userdocs-build user-intro
Note that we do not prefix the name of the document with its directory.
To build all the documents shown on the contents page of level 1 documentation:
$ userdocs-build --tags contents-level1
To build all the documentation you issue the userdocs-build command by itself. This will take some time to run. The result is a directory hierarchy with html documents in your home directory ( /neurospaces_project/userdocs/source/snapshots/0/html/htdocs/neurospaces_project/userdocs/).
It is convenient to combine some of these options. For instance to learn which tags are associated with the user-intro document:
$ userdocs-build --report-tags user-intro
To know which tags are associated with the documents in level 1 documentation:
$ userdocs-build --report-tags --tags level1
To know which documents are still in draft status and thus unpublished:
$ userdocs-build --dry-run --tags draft