This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: 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.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]