discuss: Docbook, Xml, Jade etc.
Subject:
Re: Docbook, Xml, Jade etc.
From:
Kian Spongsveen ####@####.####
Date:
28 Jul 2003 10:48:39 -0000
Message-Id: <200307281254.07961.sybase@kian.org>
I can only agree with you that writing these docs has a steep learning curve.
I just started out myself, so let me explain how I did it.
1) I looked at the sample docs and some of the existing HOWTOs and saw how the
tags are used. Since (X)HTML and XML share a common heritage from SGML it was
quite easy to understand, think of it as HTML including all the tags you were
missing.
2) I found the "xsltproc" command you were sent in an e-mail on this list. I
run SuSE and just searched for that command and "docbook" and installed all
the stuff from the DVD. If you run Slackware or LFS you are expected to learn
every little piece of software from scratch - I got tired of that and buy
boxed distributions instead. I've had it with editing config files and
setting up runlevels with vi. The same goes for all the DocBook-stuff as
well, just like setting up apache or postgreSQL from scratch. Be prepared to
tech yourself everything or be flamed when asking. I expect RedHat and
Mandrake also provide what you need pre-packaged.
3) Once I had installed the packages, I tried the xsltproc command on the
Sample-HOWTO and viewed the result in my browser.
4) Then I started my first baby steps of writing my doc, tagging parts of
sentences as needed. I used jEdit, a Java-based GUI editor with tag
completion, syntax highlighting and so on. Any editor will do, I hate both
Emacs and vi for any serious work - they belong to an era we should be done
with with a few exceptions.
5) Tag text, xsltproc, view, edit, repeat.
6) Curse that there is no WYSIWYG editor to help you do this. Yes, that sucks
and I expect it puts off a lot of potential authors from contributing. Maybe
the "write everything in Word and mail it to a volunteer" comment belongs on
the front page of TLDP, not on request in this mailing list.
I expect that I am using some tags "wrong" even if I generate readable HTML
from my doc. And I don't want to know what Jade is, even those using it
complain. I'm going to mail my draft and have someone competent proof-read it
in the end, but the actual contents is getting there. I feel the markup makes
me structure it better while I'm writing.
--
Kian Spongsveen
