dlib/docs/README.txt

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 Mercurial 
repository at: http://dclib.hg.sourceforge.net:8000/hgroot/dclib/dclib 

======================== 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).  

Also note that the first 80 or so lines of the stylesheet.xsl file contains
stuff specific to the dlib project and thus should be changed or removed
as appropriate if you want to reuse it for a different project. 

======================== 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
	     dlib's repository in the tools/htmlify folder.  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 
	     dlib.net.  Both sets of HTML are generated from the same XML 
	     files and are mostly the same.  You will see <chm></chm> and 
	     <web></web> tags inside the XML though in cases where the two 
	     differ.
	
 - makerel:  Runs makedocs as well as creates tar and zip files of the project.  
	     It also runs 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.


======================== License for documentation files ========================

To the extent possible under law, Davis E King has waived all copyright and 
related or neighboring rights to dlib documentation (XML, HTML, and XSLT files).
This work is published from United States. 

That is, I (Davis the author) don't care what you do with this.  So do
whatever you want :)