Folks,
Richard's comments about a template made me want to talk a little bit
about DocBook SGML. I write all of our HOWTO documents in DocBook
SGML or DocBook XML (the only real difference is the first couple of
header lines of the file and the file extension) because I then have
one source document from which I can very easily generate HTML, PDF
and text versions. That's why I use it. I've also been working with
tagged languages (like SGML, HTML, XML, etc.) for about 8 or 9 years,
so I'm right at home working within them.
However, I realize that many people are NOT comfortable working with
such languages and find the process of authoring in SGML rather
time-consuming, frustrating, annoying, intimidating, aggravating...
(pick your adjective, I've heard it called all of that!)
But some people have contacted me saying that they would be interested
in learning more about it. Unfortunately, the *worst* part of working
with DocBook is, in my opinion, getting set up to use the processing
tools. Many of them are, um, well, er, "not ready for prime time"
when it comes to getting the installation and configuration set up.
The process of setting that all up has turned off more than one person
to writing in DocBook. The good news is that the tools are rapidly
improving.
If any of you would like to try out working in DocBook for a HOWTO, but
don't want to deal with the processing, there's two options I thought
I would mention:
1. I'm certainly glad to take a look at any document and process it.
Take the SGML template I've put online (or grab the SGML version
of one of the HOWTOs), mark it up as best you can, and fire it in
to me. I can run it through my tools, process it, and send it
back to you. Given how long I've been living/breathing this stuff,
if there are any markup errors, it usually takes me a trivial amount of
time to find and fix them - and I don't mind doing so.
2. David Merrill at the Linux Documentation Project
(http://www.linuxdoc.org/ ) has put together an online processor
that works via e-mail. All you do is send an email message to
"[EMAIL PROTECTED]" with you DocBook SGML file as an
attachment to the message (the message subject and body are
ignored and can be anything). As long as the suffix on the attached
file is ".sgml", the processor will process it and (assuming the
markup is correct) send you a message like the one below that tells
you where to retrieve your files. (If your markup is incorrect,
I believe it sends you back a list of the errors.) I've written
David asking if we (on this list) can use it and I'm fairly sure
he'll say yes.
So both of those options are available to you.
As far as actually *editing* a file, I use vim, an updated (and MUCH
improved) version of the classic vi text editor, on a Linux system with
some macros that I have written to speed the entry of markup tags.
(you can see my .vimrc file at http://www.lodestar2.com/software/docbook/ )
There are versions of VIM for Windows as well. (http://www.vim.org/ )
Other people use Emacs... or some of the other editors that are out there.
One list is available at:
http://www.linuxdoc.org/LDP/LDP-Author-Guide/editing.html
In any event, know that these resources are out there if you want to
experiment with authoring in DocBook.
Regards,
Dan
----- Forwarded message from Docbook Processor <[EMAIL PROTECTED]> -----
Date: Mon, 9 Jul 2001 13:06:06 -0400
From: Docbook Processor <[EMAIL PROTECTED]>
To: <[EMAIL PROTECTED]>
Cc: [EMAIL PROTECTED]
Subject: DocBook Successful
S U C C E S S
Email DocBook Processor v0.5
This service is strictly for the use of LDP authors, LDP volunteers, and
people who have asked me politely like civilized human beings.
If you experienced any problems with your submission, please write to
[EMAIL PROTECTED], and please include the version number and sgml filename
so I can investigate.
Thank you!
You can download your results from
http:[EMAIL PROTECTED]/template-howto
Error : DocBook Successful
JOB: 8102
FILENAME: template-howto.sgml
BASENAME: template-howto
HTMLNAME: template-howto.html
TEXTNAME: template-howto.txt
DOC: template-howto
WORKUSER: [EMAIL PROTECTED]
WORKDOC: [EMAIL PROTECTED]/template-howto
HTTPDOC: http:[EMAIL PROTECTED]/template-howto
FROM: [EMAIL PROTECTED]
RET MAIL: <[EMAIL PROTECTED]>
EMAIL: <[EMAIL PROTECTED]>
NSGMLS: 0
DB2HTML: 0
JADE: 0
LYNX:
Processing Log
nsgmls -s -E 10 foo.sgml (results)
----- End forwarded message -----
--
Dan York, Director of Training [EMAIL PROTECTED]
Ph: +1-613-751-4401 Mobile: +1-613-263-4312 Fax: +1-613-564-7739
e-smith, inc. 150 Metcalfe St., Suite 1500, Ottawa,ON K2P 1P1 Canada
http://www.e-smith.com/ open source, open mind
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
