Tidydoc manual (v0.6)



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 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 [http://www.cygwin.com||Cygwin] with , , , ,  and 
everything should work as on Unix/Linux. A convenience script  is 
generated by  to start  more easily. Note that HTML preview of 
PDF files is currently not supported on Windows (it should work 
with a version of  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  on your document repository so that  scripts 
and  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  example and copy/paste the missing 
directives. If you never modified , you can also re-run 
td-create-htmlroot after removing the  directory.

