twiki format to docbook

[Karsten Wade]

On Tue, 2004-03-09 at 06:46, Paul Pianta wrote:
> personally - i took a quick look at the fedora-doc tutorial but i bombed 
> out when it came to Emacs stuff (pretty early that means). I have never 
> touched emacs in my life and i am very happy editing with vi and gedit. 
> I don't want to learn emacs - i know it is powerful and efficient once 
> you get familiar with it - but i honestly don't have the time to get 
> familiar with it! I have already put in years of time learning vi 
> tricks. I also find the emacs interface outdated and counter-intuitive 
> (for a newbie anyway).
> 
> So after such a rant ... I would just like to say that it would be nice 
> to have something other than just emacs to choose from when creating 
> docs for the fedora-doc project. If a wiki/twiki converter is possible, 
> or something else (conglomerate?) then bring in on!!

Just wanted to take a chance to reiterate a point I've made, lost in the
noise.

Because Norm Walsh is an Emacs user, and because of the power of pSGML
(and now nXML) modes, learning DocBook is very easy in Emacs.  However
...

You do not have to use Emacs to author/edit DocBook.

You just need to conform to the DocBook standards.  If you parse your
document against the DTD, then indenting should be consistent.  I'm sure
there are keybindings and other DocBook tools for Vi.  Perhaps someone
who prefers to use Vi could make a tutorial on using Vi for DocBook with
the Fedora docs project toolchain. :)

There is still the hurdle of learning DocBook.  But considering that it
is basically the Linux documentation standard of the moment (i.e., what
the Linux Doc Project uses), this is a useful skill that will help with
more than Fedora documentation.  It's easier to learn than HTML (because
there are no exceptions and funky browser specific rules).  You have a
nicely working toolchain, so you don't have to overcome the "getting it
to render" problems.

There are several good DocBook authors who hang out on #fedora-docs on
irc.freenode.net, so please come by and ask for assistance while you are
learning DocBook.

Think about it this way -- it may be easier for you to learn and use
Python than C, but Python is not the language for writing kernel code. 
To make submissions for the kernel, you need to use the right language
and authoring standards.  What editor you use is your choice.  As long
as the end result is to spec, you are fine.  Our Doc Guide should
provide that spec for us.  If you find that the spec is tied up with
Emacs specifics, please file a bugzilla report detailing what needs to
be untied.  Tammy can assign that one to me, I'd be happy to make the
fixes. :)

- Karsten

-- 
Karsten Wade .:. RHCE .:. Sr. Technical Writer      .:.    <name_title />
kwade at redhat.com       www.redhat.com/docs               <email_URL />
rhea.redhat.com                                  <product id="WAF_CMS" />  
www.redhat.com/solutions/security/SELinux.html   <product id="SELinux" />
2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41    <gpg_fingerprint />