Tidydoc manual (v0.6)


September 18, 2009

1 Introduction

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

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 some concepts were inspired from Orgadoc http://www.gnu.org/software/orgadoc/.

2 Quickstart for Unix/Linux

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.6.tar.bz2 # uncompress the sources 
$ cd tidydoc-0.6 
$ ./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 Quickstart for Windows

Install Cygwin with autoconf, automake, make, python, wget and everything should work as on Unix/Linux. A convenience script launch.bat is generated by td-create-htmlroot to start td-web-server more easily. Note that HTML preview of PDF files is currently not supported on Windows (it should work with a version of pdftohtml compiled on Cygwin though, but this has not been tested).

4 FAQ

4.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.

4.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.

4.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.

4.4 I have updated Tidydoc but the web interface seems unchanged

You need to re-run td-create-htmlroot on your document repository so that CGI scripts and HTML files get updated.

4.5 I have updated Tidydoc and my old configuration file does not work anymore

Some directives might have been added in the lastest release, check the provided tidydoc.conf example and copy/paste the missing directives. If you never modified tidydoc.conf, you can also re-run td-create-htmlroot after removing the config/ directory.