OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [docbook-apps] too confused to make progress


On Thursday 11 January 2007 02:26, Craig White wrote:
> On Wed, 2007-01-10 at 15:58 -0800, Bob Stayton wrote:
> > Hi Craig,
> > No, this list certainly accepts newbie questions.  I'm just not clear
> > where to direct you.  The DocBook Wiki pages list several tutorials:
> >
> > http://wiki.docbook.org/topic/DocBookTutorials
> >
> > It seems many of the DocBook tutorials were written for SGML, or SGML and
> > XML.  You should ignore all the SGML stuff and focus on XML documents and
> > tools. Perhaps a tutorial on XML would help?
>
> ----
> agreed - XML is obviously where I want to go. I have been all over that
> Wiki page and stepped through much of them but the interspersion of SGML
> has clearly been part of the confusion.

Hello Craig,

I understand that the whole docbook thang can be confusing. 

It sounds like you are at least able to write a valid and well-formed Dobook 
XML document and now want to be able to transform them to other formats like 
HTML and PDF.

I understand that you already have tools installed on Fedora and the natural 
thing to do is to use them. However, this can often be more confusing than 
productive, especially when it does not work. There can be a number of 
reasons for this, but when you are just starting, knowing what is wrong can 
be hard.

My first suggestion is just to let the installed helper scripts be for now and 
focus on understanding the toolchain. To help you with this , download and 
install, the Oxygen XML Editor [http://www.oxygenxml.com]. This is not a free 
editor, but there is a full-featured, time limited trial period.

Using Oxygen will give you a GUI from which to work and a build environment 
where you can create HTML and PDF. While building, you will be able to create 
various new transformations. However, Oxygen does give you some basic 
transformation scenarios. The fields provided by Oxygen to define these 
scenarios will give you a good idea of the inputs required in order to build 
HTML and PDF. Inspect them, it sometimes helps to see things in GUI.

Oxygen will also help you check that your documents are valid and well-formed 
according the Docbook DTD. It may be that  the help scripts installed with 
Fedora are breaking because of problems in the markup. Anyway, using Oxygen 
will help make sure that this is not the reason.

Dig around the Oxygen install folder. You will find most of the tools you need 
for docbook and building. Sometimes learning by example is a good idea.

I think that once you have a better idea with Oxygen, then documents such as 
Bobs most excellent book Docbook XSL The Complete Guide 
[http://www.sagehill.net/docbookxsl/index.html], will start to make more 
sense as you will be able to visually see what Bob is speaking about.

Now, if you get stuck anywhere. Ask here, or if you feel more comfortable I am 
happy to help directly.

-- 
Sean Wheller
Technical Author
email: sean@inwords.co.za
im: seanwhe@jabber.org
skype: seanwhe
cel: +27-84-854-9408
web: http://www.inwords.co.za


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]