From 3e3bce2bfa9935ef6cb69e39878a5e73468cb0bd Mon Sep 17 00:00:00 2001 From: Davis King Date: Sat, 25 Apr 2009 13:23:16 +0000 Subject: [PATCH] Added a little README file that gives a rough explanation of what is going on in the docs folder. --HG-- extra : convert_revision : svn%3Afdd8eb12-d10e-0410-9acb-85c331704f74/trunk%403018 --- docs/README.txt | 55 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 docs/README.txt diff --git a/docs/README.txt b/docs/README.txt new file mode 100644 index 000000000..22c6f3e89 --- /dev/null +++ b/docs/README.txt @@ -0,0 +1,55 @@ +This "package" is just a copy of the stuff I use to generate the documentation +for the dlib library. It contains a copy of the XSLT and XML I use to +generate the HTML documentation. + +The current version of these files can be obtained from the dlib subversion +repository at: https://dclib.svn.sourceforge.net/svnroot/dclib/trunk/docs + +======================== Overview ======================== + +I write all my documentation in XML files. If you look through the files in +the docs folder you will see each of them. There is also a stylesheet.xsl +file which contains all the XSLT I wrote to transform XML files into HTML. +Anyway, I use that stylesheet to generate the dlib documentation from those +XML files. + +There is also a stylesheet inside the docs/chm folder (htmlhelp_stylesheet.xsl) +that knows how to look at the XML files and generate the table of contents +files needed by the htmlhelp tool (the thing that makes chm help files). + +======================== Installing the required tools ======================== + +To begin with, the XML and XSLT is usable on any operating system, however, +all the scripts I have in the docs folder that automate everything are bash +shell scripts. I also use stuff like wine and other Linux tools and I have +only ever tested any of this in Debian. So if you want to use all the scripts +then you should probably run this stuff in Linux. But if not you can probably +hack something together :) + +There are four scripts in the docs folder. + + - testenv: This script tests your environment for all the needed utilities. + Run it and it should tell you what else you need to install. + Note that the htmlify utility is something I wrote and is in + the htmlify subfolder. You should build and install it. + (go into that folder, make a subfolder called build, then cd + into build and say: "cmake ..; make; sudo make install". + You will need to install cmake if you don't have it already) + + - makedocs: This remakes all the HTML documentation by pulling files out + of the dlib repository. If you want to use this stuff for your + own projects you will need to edit this file a bit. + + Note that this script puts its output in the docs/web and + docs/chm/docs folders. I use the chm folder for off-line + documentation while the web folder contains what goes onto + dclib.sourceforge.net. Both sets of HTML are generated from + the same XML files and are mostly the same. You will see + and tags inside the XML though in + cases where the two differ. + + - makesnapshot and makerel: These run makedocs as well as create tar and + zip files of the project. They also run htmlhelp in wine to + generate the chm help files. Note that you will need to run + docs/chm/htmlhelp/setup_htmlhelp.sh before it will work in wine. +