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