njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1 | |
sewardj | 49fbe60 | 2005-07-25 17:58:48 +0000 | [diff] [blame] | 2 | Valgrind Documentation |
| 3 | ---------------------- |
| 4 | This text assumes the following directory structure: |
| 5 | |
sewardj | 7fd59fc | 2005-11-17 18:04:58 +0000 | [diff] [blame^] | 6 | Distribution text files (eg. AUTHORS, NEWS, ...): |
sewardj | 49fbe60 | 2005-07-25 17:58:48 +0000 | [diff] [blame] | 7 | valgrind/ |
| 8 | |
| 9 | Main /docs/ dir: |
| 10 | valgrind/docs/ |
| 11 | |
| 12 | Top-level XML files: |
| 13 | valgrind/docs/xml/ |
| 14 | |
| 15 | Tool specific XML docs: |
| 16 | valgrind/<toolname>/docs/ |
| 17 | |
| 18 | All images used in the docs: |
| 19 | valgrind/docs/images/ |
| 20 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 21 | Stylesheets, catalogs, parsing/formatting scripts: |
| 22 | valgrind/docs/lib/ |
| 23 | |
| 24 | Some files of note: |
| 25 | docs/xml/index.xml: Top-level book-set wrapper |
| 26 | docs/xml/FAQ.xml: The FAQ |
| 27 | docs/xml/vg-entities.xml: Various strings, dates etc. used all over |
| 28 | docs/xml/xml_help.txt: Basic guide to common XML tags. |
| 29 | |
njn | f7c00b1 | 2005-07-19 21:46:19 +0000 | [diff] [blame] | 30 | The docs/internals directory contains some useful high-level stuff about |
| 31 | Valgrind's internals. It's not relevant for the rest of this discussion. |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 32 | |
| 33 | Overview |
| 34 | --------- |
| 35 | The Documentation Set contains all books, articles, |
| 36 | etc. pertaining to Valgrind, and is designed to be built as: |
| 37 | - chunked html files |
| 38 | - PDF file |
| 39 | - PS file |
| 40 | |
| 41 | The whole thing is a "book set", made up of multiple books (the user |
| 42 | manual, the FAQ, the tech-docs, the licenses). Each book could be |
| 43 | made individually, but the build system doesn't do that. |
| 44 | |
| 45 | CSS: the style-sheet used by the docs is the same as that used by the |
| 46 | website (consistency is king). It might be worth doing a pre-build diff |
| 47 | to check whether the website stylesheet has changed. |
| 48 | |
| 49 | |
| 50 | The build process |
| 51 | ----------------- |
| 52 | It's not obvious exactly when things get built, and so on. Here's an |
| 53 | overview: |
| 54 | |
| 55 | - The HTML docs can be built manually by running 'make html-docs' in |
| 56 | valgrind/docs/. (Don't use 'make html'; that is a valid built-in |
| 57 | automake target, but does nothing.) Likewise for PDF/PS with 'make |
| 58 | print-docs'. |
| 59 | |
sewardj | 8bc09dc | 2005-07-25 17:54:06 +0000 | [diff] [blame] | 60 | - 'make dist' (nb: at the top level, not in docs/) puts the XML files |
| 61 | into the tarball. It also builds the HTML docs and puts them in too, |
| 62 | in valgrind/docs/html/ (including style sheets, images, etc). |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 63 | |
| 64 | - 'make install' installs the HTML docs in |
| 65 | $(install)/share/doc/valgrind/html/, if they are present. (They will |
| 66 | be present if you are installing from the result of a 'make dist'. |
| 67 | They might not be present if you are developing in a Subversion |
| 68 | workspace and have not built them.) It doesn't install the XML docs, |
| 69 | as they're not useful installed. |
| 70 | |
| 71 | If the XML processing tools ever mature enough to become standard, we |
| 72 | could just build the docs from XML when doing 'make install', which |
| 73 | would be simpler. |
| 74 | |
| 75 | |
| 76 | The XML Toolchain |
| 77 | ------------------ |
| 78 | I spent some time on the docbook-apps list in order to ascertain |
| 79 | the most-useful / widely-available / least-fragile / advanced |
| 80 | toolchain. Basically, everything has problems of one sort or |
| 81 | another, so I ended up going with what I felt was the |
| 82 | least-problematical of the various options. |
| 83 | |
| 84 | The maintainer is responsible for ensure the following tools are |
| 85 | present on his system: |
| 86 | - xmllint: using libxml version 20607 |
| 87 | - xsltproc: using libxml 20607, libxslt 10102 and libexslt 802 |
| 88 | (Nb:be sure to use a version based on libxml2 |
| 89 | version 2.6.11 or later. There was a bug in |
| 90 | xml:base processing in versions before that.) |
| 91 | - pdfxmltex: pdfTeX (Web2C 7.4.5) 3.14159-1.10b |
| 92 | - pdftops: version 3.00 |
| 93 | - DocBook: version 4.2 |
| 94 | - bzip2 |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 95 | |
| 96 | A big problem is latency. Norman Walsh is constantly updating |
| 97 | DocBook, but the tools tend to lag behind somewhat. It is |
| 98 | important that the versions get on with each other. If you |
| 99 | decide to upgrade something, then it is your responsibility to |
| 100 | ascertain whether things still work nicely - this *cannot* be |
| 101 | assumed. |
| 102 | |
| 103 | Print output: if make expires with an error, cat output. |
| 104 | If you see something like this: |
| 105 | ! TeX capacity exceeded, sorry [pool size=436070] |
| 106 | |
| 107 | then look at this: |
| 108 | http://lists.debian.org/debian-doc/2003/12/msg00020.html |
| 109 | and modify your texmf files accordingly. |
| 110 | |
| 111 | |
sewardj | 7fd59fc | 2005-11-17 18:04:58 +0000 | [diff] [blame^] | 112 | Catalog/Stylesheet Location |
| 113 | --------------------------- |
| 114 | Suse 10: |
| 115 | /usr/share/xml/docbook/ |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 116 | |
| 117 | |
sewardj | 7fd59fc | 2005-11-17 18:04:58 +0000 | [diff] [blame^] | 118 | |
| 119 | Notes [Nov. 2004]: |
| 120 | ----------------- |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 121 | - the end of file.xml must have only ONE newline after the last tag: |
| 122 | </book> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 123 | - pdfxmltex barfs if given a filename with an underscore in it |
| 124 | |
| 125 | |
sewardj | 7fd59fc | 2005-11-17 18:04:58 +0000 | [diff] [blame^] | 126 | Notes [July 2005] |
| 127 | ----------------- |
| 128 | jrs had to install zillions of packages on SuSE 9.2 in order to |
| 129 | build the print docs (make print-docs), including |
| 130 | passivetex |
| 131 | xpdf (for pdftops, which does the nicest job) |
| 132 | |
| 133 | Even then, pdfxmltex eventually dies with "TeX capacity exceeded, |
| 134 | sorry [pool size = 67555]" or some such. To fix this, he edited |
| 135 | /etc/texmf/texmf.cnf and changed |
| 136 | pool_size.pdfxmltex = 500000 |
| 137 | |
| 138 | to 1500000 and that fixed it. |
| 139 | |
| 140 | |
| 141 | Notes [Nov. 2005] |
| 142 | ----------------- |
| 143 | After upgrading to Suse 10, found a (known) bug in PassiveTex which |
| 144 | broke the build, so added a bug-fix to 'docs/lib/vg-fo.xsl'. |
| 145 | Bug-fix related links: |
| 146 | http://lists.oasis-open.org/archives/docbook/200509/msg00032.html |
| 147 | http://www.dpawson.co.uk/docbook/tools.html#d850e300 |
| 148 | http://www.haskell.org/pipermail/glasgow-haskell-bugs/2005-January.txt |
| 149 | |
| 150 | |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 151 | References: |
| 152 | ---------- |
| 153 | - samba have got all the stuff |
| 154 | http://websvn.samba.org/listing.php?rep=4&path=/trunk/&opt=dir&sc=1 |
| 155 | |
| 156 | excellent on-line howto reference: |
| 157 | - http://www.cogent.ca/ |
| 158 | |
| 159 | using automake with docbook: |
| 160 | - http://www.movement.uklinux.net/docs/docbook-autotools/index.html |
| 161 | |
| 162 | Debugging catalog processing: |
| 163 | - http://xmlsoft.org/catalog.html#Declaring |
| 164 | xmlcatalog -v <catalog-file> |
| 165 | |
| 166 | shell script to generate xml catalogs for docbook 4.1.2: |
| 167 | - http://xmlsoft.org/XSLT/docbook.html |
| 168 | |
| 169 | configure.in re pdfxmltex |
| 170 | - http://cvs.sourceforge.net/viewcvs.py/logreport/service/configure.in?rev=1.325 |
| 171 | |
| 172 | some useful xls stylesheets in cvs: |
| 173 | - http://cvs.sourceforge.net/viewcvs.py/perl-xml/perl-xml-faq/ |
| 174 | |
| 175 | |
njn | 0ce9da2 | 2004-11-30 14:08:24 +0000 | [diff] [blame] | 176 | TODO LESS CRUCIAL: |
| 177 | ------------------ |
njn | 2777d93 | 2004-11-30 14:10:13 +0000 | [diff] [blame] | 178 | - add the HOWTO doc? |
njn | 12bb6d4 | 2004-11-30 14:09:22 +0000 | [diff] [blame] | 179 | - writing-tools.xml refers to vg-catalog.xml but it's not in the repo... should |
| 180 | it be, and if so, how should it be used? |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 181 | - get rid of blank pages in fo output |
| 182 | - concat titlepage + subtitle page in fo output |
| 183 | - generate an index for the user manual (??) |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 184 | - run through and check for not-linked hrefs: grep on 'http' |
| 185 | - run through and check for bad email addresses: grep on '@' etc. |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 186 | - go through and wrap refs+addresses in '<address>' tags |
| 187 | |
| 188 | |