This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: Starting a fresh documentation project
- From: tubaman at flashmail dot com
- To: docbook at lists dot oasis-open dot org
- Date: Thu, 19 Dec 2002 02:54:49 -0600
- Subject: Re: DOCBOOK: Starting a fresh documentation project
- References: <1040017041.582.340.camel@zen8100a>
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.