[publican-list] I'm quite lost...

[Norman Dunbar]

Good Morning Chris,

> I've volunteered to write for fedora-docs,
Good man! Even though I'm not a Fedora user, I do appreciate all the 
hard work volunteers put in to make it a great product.

>  but I have no idea as in how to use the tools to actually produce the documentation!
Ah yes, how I remember when I first started writing Docbook 
documentation for the Firebird Database project (www.firebirdsql.org) - 
I too had no clue and I found that trying to find a good beginner's 
guide to Docbook was quite difficult back then.

> I understand that I must learn some Docbook, but what version, what
> parts and how much of it?
I suspect you will be learning Docbook 4.5 or maybe even 5.x - but they 
are, to all intents and purposes, quite similar. Best check what  the 
rest of the Fedora docs are using - I suspect 4.5 to be honest.

> Then it is the Publican tool. Does anybody know of a good screencast or
> something to get me going with this tool?
I'm afraid not. The User Guide is quite good, but isn't really a 
tutorial. In fact, when I have time, I intend to create a small tutorial 
mainly for my own use - I'm getting old, I forget stuff :-( - which I 
will make freely available (if it's any good of course!)

Now, I'm sure the Publican people won't mind me pointing you off 
project, but why not take a look at the documents for documentation 
writers over at the Firebird project. Granted they will be aimed at that 
particular style of documentation, but you will get a general 
introduction to Docbook.

Try these links:

The main documentation site:

http://www.firebirdsql.org/en/reference-manuals/ scroll down to the 
section on "Manuals For Firebird Docwriters".


How To Write DocBook:

ONLINE: 
http://www.firebirdsql.org/file/documentation/reference_manuals/user_manuals/html/docwritehowto.html

PDF: 
http://www.firebirdsql.org/file/documentation/reference_manuals/user_manuals/Firebird-Docwriting-Guide.pdf


These should be read in conjunction with the links to other docs that 
you have been given already by Misty. (Although the link given for the 
user guide takes you to release 1.3 - I think 2.5 is actually the latest 
available release. (2.6 is the very latest release but I don't think 
it's packaged up for Fedora yet - I may be wrong!)

The 2.5 user guide for Publican is at 
http://jfearn.fedorapeople.org/en-US/Publican/index.html select the 
required version on the left and click on the appropriate link for the 
particular format you want (under User Guide) - you have the choice of 
epub, html, html-single or pdf. Enjoy!

I printed out my guide and read it a few times through away from the 
computer (in the bath!) before I tried to do anything with it.


As for an editor, I've tried and failed to like Serna. That's just me.

I tend to prefer using any text editor I have around - Kate, Kwrite or 
vi[m] on a KDE system, Gedit or vi[m] on Gnome. Emacs probably has a 
Docbook setup, but that's another editor I cannot get my head around!

For a GUI, I always seem to return to XML Mind Editor aka XXE. This is 
available in a paid for and a free version. For Open Source 
documentation writers, the free version is adequate and available at 
http://www.xmlmind.com/xmleditor/download.shtml.

There is support, via a members only list which you can join at 
http://www.xmlmind.com/mailman/listinfo/xmleditor-support - although 
they do like you to read the FAQ - 
http://www.xmlmind.com/xmleditor/faq.html - before asking! ;-)

One last thing for now, Docbook will drive you insane at first! It's 
extremely frustrating indeed - well I found it so - but eventually, it 
will click. The fact that you can generate multiple output formats from 
one single input file is extremely useful - especially when you have to 
update something! You only do it once.

One thing I'd suggest, keep your source files in a version control 
system - I use Subversion - because when you make changes and then 
decide it's all pants and want to undo them, it's simple with a version 
control taking care of the reversions! My sources live in one folder, 
and are version controlled to another - on the same laptop. I have found 
it extremely useful indeed, plus, it saves a whole lot of time.

Good luck.


Cheers,
Norman.

PS. I've found everyone on this list to be very helpful, even though 
they know I'm not a Fedora user! I did try Fedora, 14 was pretty good I 
have to say, 15 and Gnome 3, I just don't like at all. Luddite? Me? ;-)

-- 
Norman Dunbar
Dunbar IT Consultants Ltd

Registered address:
Thorpe House
61 Richardshaw Lane
Pudsey
West Yorkshire
United Kingdom
LS28 7EL

Company Number: 05132767