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/.
This is the fastest way to get started. Let us assume you want to create a documentation repository in $HOME/docs:
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:
By default it will listen on port 8080. You can now open your web browser at the following url: http://localhost:8080.
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:
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:
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):
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:
Now ~/docs/index.html gives access to your documentation tree and ~/docs/documents.bib contains the bibtex entries.
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).
If you want td-generate not to go into a particular directory, create a .td_raw_dir file into it.
This way td-generate will not consider this directory.
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.
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:
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.
You need to re-run td-create-htmlroot on your document repository so that CGI scripts and HTML files get updated.
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.