[svlug] writing documentation with images?

[R P Herrold]

On Wed, 9 Jul 2008, Florin Andrei wrote:

> I want to write a HOWTO on a particular topic in the field of video
> processing. Given the subject, the document must include many images, it
> cannot be text only (not even ASCII art).

> I would like to create the document in a manner similar to the Linux
> Documentation Project - write a master file in some sort of markup
> language, containing text and references to image files, then run a
> bunch of command-line utilities to convert it to:
> - HTML all in one page
> - HTML one page per chapter
> - PDF A4 and Letter
> - PS A4 and Letter

TIFF and .ps image captures, .dot for graphs; LaTeX and 
latex2html for the rest.  The Makefile in ./doc/ in any 
tarball at:
 	http://www.trading-shim.org/
yields the webbish and PDF (passing through a .ps stage); 
relaying papersize between A4 and Letter is a trivial option 
change and a couple of 'sed'.

See sample output at:
 	http://www.trading-shim.org/pdfs/manual.pdf
and the HTML represted by it at:
 	http://www.trading-shim.org/doc/

> AFAICT, the LDP only has text documents, no images. What 
> would be the best way to make such a document that also 
> contains images?

The included figures are built programatically with 'graphviz' 
from the source .c and .h files, or screenshots captured with 
'import' from 'Imagemagick'

> Ideally, the whole workflow should be based on software 
> commonly found on recent and popular Linux distributions.

Part of our external release process includes testing on 32 
and 64 bit Centos, ; Debian testing, and OS/X.  I do this with 
three 'fire and forget' scripts, one for each distribution.

We work with CentOS 5, Debian testing, and OS/X; and need only 
add graphviz, which the Scientific Linux archive has in SRPM 
form with Centos; Debian had it all readily apt-get'able; 
OS/X is a bit trickier.  ;)

-- Russ herrold