|
a/src/doc/user/00README.txt |
|
b/src/doc/user/00README.txt |
| 1 |
= Building the Recoll user manual
|
1 |
= Building the Recoll user manual
|
| 2 |
|
2 |
|
| 3 |
The Recoll user manual usually used DocBook SGML and used the FreeBSD doc
|
3 |
The Recoll user manual used to be written in DocBook SGML and used the
|
| 4 |
toolchain to produce the output formats. This had the advantage of an easy
|
4 |
FreeBSD doc toolchain to produce the output formats. This had the advantage
|
| 5 |
way to produce all formats including a PDF manual, but presented two
|
5 |
of an easy way to produce all formats including a PDF manual, but presented
|
| 6 |
problems:
|
6 |
two problems:
|
| 7 |
|
7 |
|
| 8 |
- Dependancy on the FreeBSD platform.
|
8 |
- Dependancy on the FreeBSD platform.
|
| 9 |
- No support for UTF-8 (last I looked), only latin1.
|
9 |
- No support for UTF-8 (last I looked), only latin1.
|
| 10 |
|
10 |
|
| 11 |
The manual is now compatible with XML. There is a small script that
|
11 |
The manual is now compatible with XML. There is a small script that
|
|
... |
|
... |
| 15 |
Beyond fixing a few missing closing tags, the main change that had to be
|
15 |
Beyond fixing a few missing closing tags, the main change that had to be
|
| 16 |
made was to make the anchors explicitly upper-case because the SGML
|
16 |
made was to make the anchors explicitly upper-case because the SGML
|
| 17 |
toolchain converts them to upper-case and the XML one does not, so the only
|
17 |
toolchain converts them to upper-case and the XML one does not, so the only
|
| 18 |
way to have compatibility is to make them upper-case in the first place.
|
18 |
way to have compatibility is to make them upper-case in the first place.
|
| 19 |
|
19 |
|
| 20 |
We still have a problem for producing the PDF manual, because few
|
20 |
We initially had a problem for producing the PDF manual, which motivated
|
| 21 |
straightforward approaches seem to exist:
|
21 |
keeping the SGML version for producing the PDF with the FreeBSD SGML
|
|
|
22 |
toolchain. This problem is now solved with dblatex, so that the SGML
|
|
|
23 |
version now has little reason to persist and it will go away at some point
|
|
|
24 |
in the future.
|
| 22 |
|
25 |
|
| 23 |
- http://docbookpublishing.com qui a meme une version programmatique (cf:
|
26 |
Asciidoc would also be a candidate as the source format, because it can
|
| 24 |
http://docbookpublishing.com/api/), mais necessite un peu de
|
27 |
easily produce docbook, so the future will probably be:
|
| 25 |
configuration.
|
|
|
| 26 |
- FOP but this is Java and complicated.
|
|
|
| 27 |
|
28 |
|
| 28 |
See also http://www.valdyas.org/linguistics/printing_unicode.html
|
29 |
asciidoc->docbook-xml-> html
|
| 29 |
Does not look simple, but dates from 2002 and seems to imply that FOP is
|
30 |
-> pdf
|
| 30 |
making progress.
|
|
|
| 31 |
|
|
|
| 32 |
The current conclusion would seem to be that the SGML version should stay
|
|
|
| 33 |
operational to give an easy way to make the PDF one on FreeBSD.
|
|
|
| 34 |
|
|
|
| 35 |
But see also notes about dblatex on the asciidoc page. Actually asciidoc would
|
|
|
| 36 |
be a candidate replacement for the source format.
|
|
|
| 37 |
http://www.methods.co.nz/asciidoc/userguide.html
|
|
|