Tidydoc manual (v)

Nicolas Burrus nicolas@burrus.name



1 Introduction

The goal of Tidydoc is to make documentation organization easier. 
It addresses the following problems:

• Add documents to a pool of documents. Give them the right names 
  and put them into the right directories. 

• Reorganize them a posteriori. 

• Generate a set of HTML pages to browse your documents. 

• Generate a bibtex file referencing all your documents.

You can add documents using the web interface or any file 
transfer program, such as scp. Tidydoc can then generate HTML 
files indexing your documents. A simple description file is 
required for each document. No additional tool is required, a 
standard Unix system with a Python interpreter will do the job. 
Every operation can be done through a web interface if you are 
running a web server or using the embedded standalone webserver. 
Tidydoc is written in Python in a spirit of flexibility and easy 
tweaking, but its default behavior should fit the needs of most 
people. 

Note that many concepts were inspired from Orgadoc http://www.gnu.org/software/orgadoc/
.

2 Quickstart

2.1 Using the embedded webserver

This is the fastest way to get started. Let us assume you want to 
create a documentation repository in $HOME/docs:

$ tar xvfj tidydoc-0.5.tar.bz2 # uncompress the sources

$ cd tidydoc-0.5

$ ./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 

$ cd 

$ mkdir docs 

$ td-create-htmlroot docs # initialize the documentation 
directory 

Now you have a brand new repository. You may want to edit 
$HOME/docs/config/tidydoc.conf to adjust some parameters, but 
default ones should be ok. Then you can start the embedded 
webserver:

$ td-web-server -c docs/config/tidydoc.conf

By default it will listen on port 8080. You can now open your web 
browser at the following url: http://localhost:8080.

2.2 Using apache webserver

This is more recommended if your host is accessible from the 
Internet. Repeat all the steps above but edit tidydoc.conf and 
change site_root to match your apache url. You might need to 
configure apache to that CGI scripts can be executed. Here is an 
example of httpd.conf tweak for a repository in /var/www/docs:

Alias /doc /var/www/docs



<Directory "/var/www/docs">

  Options FollowSymLinks

  AllowOverride None

</Directory>



<Directory "/var/www/docs/cgi-bin">

  AllowOverride None

  AddHandler cgi-script .cgi

  Options ExecCGI -MultiViews +SymLinksIfOwnerMatch

  Order allow,deny

  Allow from all

</Directory>

2.3 Using local filesystem only

Same steps than above, and edit tidydoc.conf to set a “file:///” 
like url as site_root. Now you can start adding documents using 
local files or urls:

$ td-add-doc -c ~/docs/config/tidydoc.conf my_favorite_doc.pdf 

$ td-add-doc -c \

~/docs/config/tidydoc.conf 
http://nicolas.burrus.name/tidydoc_manual.pdf
 

Or if you use only one document pool, you can copy the 
configuration file to your home directory, and it will be used by 
default (the -c option will not be required anymore):

$ cp ~/docs/config/tidydoc.conf ~/.tidydoc.conf 

$ td-add-doc http://nicolas.burrus.name/tidydoc_manual.pdf

By default td-add-doc will open emacs to edit the description 
file, and acroread to visualize the document (so that you can 
easily copy/paste elements of the pdf to fill in the 
description). This can be changed at the end of the configuration 
file.

Once the description file has been filled, quit emacs and 
acroread. If you did not enter any category, the document will be 
put in "unsorted".

Then you can generate html and bibtex files:

$ td-generate -c ~/docs/config/tidydoc.conf

Now ~/docs/index.html gives access to your documentation tree and 
~/docs/documents.bib contains the bibtex entries.

3 FAQ

3.1 How do I prevent tidydoc from analyzing a directory?

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.

3.2 What are those .dsc and .xml files?

Each document has to be described by an XML file. It can be 
written directly by hand (useful to index raw directories), but 
this is generally painful. Thus, simpler description files were 
introduced, with the extension .dsc. These files will be 
converted to .xml files automatically by Tidydoc.

3.3 I have updated Tidydoc but my existing repositories do not 
  get updated

If you update Tidydoc and re-run the generation script without 
modifying the description files, the document listing do not get 
updated. This is because a cache system is used to increase 
performance. To make sure that everything gets re-generated, a 
simple trick is to “touch” all .dsc files:

$ find . -name \*.dsc -exec touch {} \;

You can also remove all generated files (don't forget the .dump 
ones), but this is more fastidious. This will be automated in the 
future.

