[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Re: DOCBOOK: Starting a fresh documentation project
On Mon, Dec 16, 2002 at 04:38:28PM +1100, Zenaan Harkness wrote: > - sgml or xml docbook? XML - follow the herd > - toolchain? I love Docbook but it's "too complex" for many of my coworkers so I have it setup so they can use Almost Plain Text (APT) as source that then gets converted into Docbook using aptconvert. Then we use the slightly customized docbook-xsl stylesheets to produce HTML and FO using xsltproc. Then I run the FO files through Apache's FOP to get PDF. I then run all the html through tidy to make it nicer if anyone does a view source. All apt and docbook source is stored in cvs. Below is a snipet of our makefile. # GNU Makefile for document generation .SUFFIXES: # Nullifies the default suffix rules of make .SUFFIXES: .html .dbk .fo .pdf .apt .xml # Location of executables and libraries XSLTPROC = /usr/local/bin/xsltproc APTCONVERT = /usr/local/bin/aptconvert TIDY = /usr/local/bin/tidy JAVA_HOME = /usr/j2se/jre FOP = /usr/local/fop-0.20.3/fop.sh XSLDIR = /usr/local/docbook/docbook-xsl # Source files APTSRC = $(wildcard *.apt) DOCBOOKSRC = $(wildcard *.dbk) # Macros and stanzas to make all documents DOCBOOK = $(DOCBOOKSRC) $(APTSRC:.apt=.dbk) HTML = $(DOCBOOK:.dbk=.html) PDF = $(DOCBOOK:.dbk=.pdf) all: $(HTML) $(PDF) # Suffix rules .t2d.dbk: $(TXT2DOCBOOK) $< > $@ .apt.xml: $(APTCONVERT) -enc ISO8859_1 $@ $< 2>&1 .xml.dbk: cp $< $@ .dbk.html: $(XSLTPROC) -nonet -o $@ $(XSLDIR)/html/docbook.xsl $< -$(TIDY) -modify -quiet -indent -upper $@ .dbk.fo: $(XSLTPROC) -nonet -o $@ $(XSLDIR)/fo/docbook.xsl $< .fo.pdf: JAVA_HOME=$(JAVA_HOME); \ export JAVA_HOME; \ $(FOP) -fo $< -pdf $@ > - stylesheets/ addons that might be useful? Almost Plain Text - if you have those folks that don't want to deal with tags. It works great for small docs. > - images The docbook mediaobject tag should take care of this. APT has provisions for images also. > > What is given is my environment and requirements: > - Debian GNU/Linux exclusively ("testing") (i386) lucky dog! > 2) > Images - I have created a simple image in DIA for my introduction, and > could not get jw (I'm on debian) to include the image in the pdf output. > I tried png, jpeg, eps, ps, even tif (converted the png output of dia > using the gimp). Getting good images in printed output was something we > all but gave up on perfecting last time around too. > I'll be creating all images from scratch, so I'd be happy to learn to > use XFig or something else than Dia, as long as it is Free Software (as > in freedom)! As mentioned, I have the luxury of starting from scratch. Images work great for us in both HTML and PDF output formats. > 3) > Tables - didn't try one on the weekend, but this was another thing that > caused us a lot of grief first time round, particularly with the rtf > output. Perhaps it was a problem with pdf too, I can't remember. Tables are ok for us in HTML and PDF although I haven't tried tweaking the appearance of the output.
Powered by eList eXpress LLC