This program is licensed under the Gnu GPL license http://www.gnu.org/copyleft/gpl.html.
The goal of the tidydoc program is to make documentation organization
easier. It addresses the following problems:
tidydoc is written in Python in a spirit of flexibility
and easy tweaking, but with default behaviors which fit the needs of
most people.
You can add documents using arbitrary commands, such as a
simple cp or through ssh with scp.
tidydoc can then generate HTML files indexing your documents. A
simple XML file is required for each document, including some
informations. These description files may be generated by using
tidydoc upload facilities, but this is not mandatory.
No additional tool is required, a standard Unix system with a Python interpreter will do the job.
Version 0.3 includes the following features:
.dsc files can be used instead of XML documents
tidydoc was written by Nicolas Burrus nicolas.burrus@ensta.fr.
Many concepts were inspired from Orgadoc http://www.gnu.org/software/orgadoc/.
This section describes the simplest way to start using tidydoc.
This will be done through a commented sequence of shell commands:
$ tar xvfj tidydoc-0.2.tar.bz2 # uncompress the sources
$ cd tidydoc-0.2
$ ./configure --prefix=/usr/local # files will get installed in /usr/local
$ make # generate files and documentation
$ make install # installation, you might need to be root
$ mkdir /var/www/tidydoc
$ td-create-htmlroot /var/www/tidydoc # initialize the html root dir.
$ cp /usr/local/share/doc/tidydoc/examples/tidydoc.conf /etc/ # or /usr/local/etc/
$ emacs /etc/tidydoc.conf # you can replace emacs by your favorite text editor ...
=> set input_path and output_path to /var/www/tidydoc
Now you can start adding documents:
$ td-add-doc my_favorite_doc.pdf
$ td-add-doc http://www.good_website.org/document.pdf
And generating html and bibtex files:
$ td-generate
=> /var/www/tidydoc/index.html gives access to your documentation tree
=> /var/www/tidydoc/documents.bib now contains the bibtex entries
td-add-docTo add documents, use the td-add-doc command.
The format for running the td-add-doc program is:
Usage: td-add-doc [options] document_file [description_file]
Options
-c, --config configfile Config file to use.
-v, --version Print version number.
.dsc file. If not specified,
tidydoc will generate one automatically.
td-add-doc open the document and ask you to fill out a
.dsc file describing its content. A confirmation is required
before actually sending the file.
Destination directories and file names will be determined from the description file. If a new category is introduced, a new directory will be automatically created. The naming scheme for files is `first_author.year.conf.title.extension'.
.dsc file format.dsc files are simples. Here is a sample file:
% This is a comment
Title: Fractals are everywhere in real world
% One author per line
Author: Patrick Foobar
Date: 1989
Conf: micai
Pages: 4
Keywords: fractals nature
% Url towards the document.
Link: http://patrick.foobar.com/fractals.pdf
% Line breaks are taken into account.
Abstract: Fractional Brownian motions number of physical phenomena
fractional order. However, the precise meaning of such complementary
approaches are The first one, based on nonstationary nature of
measurements; the second one, self-similarity properties of FBM and
reveals an underlying stationary structure relative to each
time-scaling.
% public or private
Visibility: public
Language: english
% Kind of bibtex entry
Bibtex type: article
% Additional bibtex fields
Bibtex fields:
volume = {5}
number = {2}
pages = {121--125}
Comment:
% One category per line
Categories:
math/fractals/papers
by_author/flandrin
For PDF files, some of these fields might be automatically filled by
td-add-doc.
Start by using the sample configuration file:
# Destination path for doc uploads. May be a directory on a remote host.
upload_dest_path = "/tmp/tidydoc"
# File containing the categories list.
# td-generate creates a categories file into output_path.
# This is used by td-add-doc to list existing categories.
categories_path = output_path + '/td_categories'
# Command which will be executed to upload a document into its first category.
# Some variables will be substituted:
# %(destdir)s : upload_dest_path / category
# %(orig_doc_path)s : path towards the input document
# %(orig_dsc_path)s : path towards the input description
# %(final_doc_name)s : destination name of the document
# %(final_dsc_name)s : destination name of the description
upload_commands = \
"""
mkdir -p "%(destdir)s" || exit 1
cp "%(orig_doc_path)s" "%(destdir)s"/"%(final_doc_name)s" || exit 1
cp "%(orig_dsc_path)s" "%(destdir)s"/"%(final_dsc_name)s" || exit 1
"""
# Command which will be executed to upload a document into other categories.
# Some variables will be substituted:
# %(destdir)s : upload_dest_path / category
# %(rel_first_destdir)s : path towards the directory of the first category
# %(final_doc_name)s : destination name of the document
# %(final_dsc_name)s : destination name of the description
link_commands = \
"""
mkdir -p "%(destdir)s" || exit 1
ln -sf "%(rel_first_destdir)s/%(final_doc_name)s" "%(destdir)s"/"%(final_doc_name)s" || exit 1
ln -sf "%(rel_first_destdir)s/%(final_dsc_name)s" "%(destdir)s"/"%(final_dsc_name)s" || exit 1
"""
# Commands which will be executed when a document is to be added.
# The document will then be uploaded.
# The following variables are substituted:
# %(orig_doc_path)s : path of the input document
# %(tmp_dsc_path)s : path of the temporary description file already created
add_doc_commands = \
"""
kfmclient exec "%(orig_doc_path)s" &
emacs "%(tmp_dsc_path)s"
"""
Configuration variables are Python instructions. Some special variables
will be substituted by tidydoc.
td-reorganize-doc Usage: td-reorganize-doc [options] dsc_file
Options
-c, --config configfile Config file to use.
-v, --version Print version number.
td-reorganize-doc takes a description file, and modify the
corresponding document organization accordingly. A typical use case is
to modify a .dsc file, e.g. changing the title and adding a new
category, and then calling td-reorganize-doc to rename the file
and link it into the new categories.
td-reorganize-doc must be use in a machine where the
input_path is available through the file system, i.e. not a
machine which uses ssh to upload documents.
td-generate will walk through the documentation tree and create
HTML files for each directory. It looks for .xml files, which
describe documents. If a document wants to be indexed, an associated
.xml file have to be crated. XML files can also describe
directories, not only files.
td-generate will also look for .dsc files, and convert
them into .xml files.
Here is a sample XML description, corresponding to the previous
.dsc file.
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<title>Fractals are everywhere in the world</title>
<file>foobar.89.micai.fractals_are_everywhere_in_the_world.pdf</file>
<nbpages>10</nbpages>
<type>public</type>
<author>Patrick Foobar</author>
<date>1989</date>
<language>english</language>
<summary>Fractional Brownian motions number of physical phenomena<br>
fractional order. However, the precise meaning of such complementary<br>
approaches are The first one, based on nonstationary nature of<br>
measurements; the second one, self-similarity properties of FBM and<br>
reveals an underlying stationary structure relative to each<br>
time-scaling.</summary>
<comment><content></content></comment>
<url>http://patrick.foobar.com/fractals.pdf</url>
</document>
td-generate Usage: td-generate [options]
Options
-c, --config configfile Config file to use.
-v, --version Print version number.
td-generate will read the configuration file, and then
recursively creates HTML files. If you want td-generate not to
go into a particular directory, create a .td_raw_dir file into
it.
$ cd my_docs/mess
$ touch .td_raw_dir
This way td-generate will not consider this directory.
The default configuration file is commented, here is an example:
# Path where document, xml and dsc files are located.
input_path = "/tmp/tidydoc"
# Path where generated files should be put.
output_path = "/tmp/tidydoc"
# Template files path.
templates_path = "/usr/local/share/tidydoc/templates"
# Root url of the website. Only useful with html.
site_root = "file:///tmp/tidydoc"
## HTML parameters
# HTML files which have to be generated at the site root.
site_root_html_files = ["nav.html"]
# HTML files which have to be generated for each directory.
directories_html_files = ["index.html", "doclist.html"]
# Treeview file to link for each directory.
treeview_subdirs_link = "doclist.html"
# Whether treeview should be in multiframe mode or not.
treeview_multiframes = True
By using the default HTML template files, this will create documents with a navigation panel on the left frame, and the document descriptions on the right frame.
HTML output is driven by template files, which are processed by
td-generate, by substituting some special variables into it. For
example, the template file for index.html should be named
index.html.tpl, and might look like this for a multiframe document:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN">
<html>
<head>
<title>Documentation</title>
</head>
<frameset cols="35%,65%">
<frame src="%%SITE_ROOT%%/nav.html" name="treeframe" id="treeframe">
<frame src="doclist.html" name="basefrm" id="basefrm">
</frameset>
</html>
%%SITE_ROOT%% will be substituted by td-generate.
Some template files have a special meaning:
document.tpl Processed to create a description for each document.
link.tpl Processed to create a link for each document.
subdir.tpl Processed to create a link for each subdirectory.
In order to get a nice tree-like view, Treeview
(http://www.treeview.net) is supported. To use it, you need to
copy the whole directory doc/examples/treeview in your
output_path. This way, td-generate will automatically
create a docNodes.js linking your documents. You can also
download directly the archive from the treeview web site.
td-generate will generate a global bibtex file for all your
documents. The output file can be specified in tidydoc.conf:
## Bibtex parameters
# Output .bib file.
bibtex_file = output_path + "/documents.bib"