doc

src/doc/user/00README.txt

@@ -0,0 +1,33 @@
+= Building the Recoll user manual
+
+The Recoll user manual usually used DocBook SGML and used the FreeBSD doc
+toolchain to produce the output formats. This had the advantage of an easy
+way to produce all formats including a PDF manual, but presented two
+problems:
+
+ - Dependancy on the FreeBSD platform.
+ - No support for UTF-8 (last I looked), only latin1.
+
+The manual is now compatible with XML. There is a small script that
+converts the SGML (but XML-compatible) manual into XML (changes the header,
+mostly). The SGML version is still the primary one.
+
+Beyond fixing a few missing closing tags, the main change that had to be
+made was to make the anchors explicitly upper-case because the SGML
+toolchain converts them to upper-case and the XML one does not, so the only
+way to have compatibility is to make them upper-case in the first place.
+
+We still have a problem for producing the PDF manual, because few
+straightforward approaches seem to exist:
+
+ -  http://docbookpublishing.com qui a meme une version programmatique (cf:
+     http://docbookpublishing.com/api/), mais necessite un peu de
+     configuration. 
+ - FOP but this is Java and complicated.
+
+See also http://www.valdyas.org/linguistics/printing_unicode.html 
+Does not look simple, but dates from 2002 and seems to imply that FOP is
+making progress.
+
+The current conclusion would seem to be that the SGML version should stay
+operational to give an easy way to make the PDF one on FreeBSD.