firebird-docs

[Firebird-docs] New potential doc writer

[Norman D. <No...@Bo...>]

Greetings,

I've signed up to this list.
I've got a SourceForge account all ready and waiting.
I've downloaded the manual CVS repository.
I've downloaded and practiced with XML Mind's editor - very nice !
I'm now hopefully ready to devote some spare time (of which I have very 
little) to writing docs for Firebird, and giving a little back to the 
project.

My initial thoughts are to do a book on the various commandline utilities 
supplied with Firebird (1.5) - you know, GBAK, GFIX etc etc.

Is this a good idea, useful etc ?

Quick question, and possibly a request for a new 'howto', how do I adapt 
the build.xml script to allow me to build my own standalone book before 
adding it into the Firebird set ? So far, I've been validating, spell 
checking and 'building' my test books from within XML MInd itself, but the 
Docbuilder how to states that the (new) docs must be able to be built 
correctly before submission.


Cheers,
Norman.

-- 
Using M2, Opera's revolutionary e-mail client: http://www.opera.com/m2/

Re: [Firebird-docs] New potential doc writer

[Paul V. <pa...@vi...>]

Hi Norman,

> I'm now hopefully ready to devote some spare time (of which I have
> very little) to writing docs for Firebird, and giving a little back
> to the project.
>
> My initial thoughts are to do a book on the various commandline
> utilities supplied with Firebird (1.5) - you know, GBAK, GFIX etc

Good idea!

And it might even be less work than you think. Now that the Firebord
Book is out, IBPhoenix are going to transfer the chapters of their
Using Firebird guide to the project, just like they have done with the
Quick Start Guide. We receive these docs in a format that's "almost
DocBook". In "Using Firebird" there are already chapters on isql, gbak
and gfix, and sections on the other tools. You could use those as a
basis for your book - or use them for reference only, whatever.

> Quick question, and possibly a request for a new 'howto', how do I
> adapt the build.xml script to allow me to build my own standalone
> book before adding it into the Firebird set ?

Better leave build.xml alone and edit /src/docs/firebirddocs.xml:
define an entity for your book (or one entity for each chapter) and
include it (or them) further down. If you open the file you'll see how
it works; just look at how it's done for the other books. You can
comment out the others in your local copy to speed up the build
process.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] New potential doc writer

[Norman D. <No...@Bo...>]

In article <Pin...@so...>, 
pa...@vi... says...
> 
> Good idea!
> 
> And it might even be less work than you think. Now that the Firebord
> Book is out, IBPhoenix are going to transfer the chapters of their
> Using Firebird guide to the project, just like they have done with the
> Quick Start Guide. We receive these docs in a format that's "almost
> DocBook". In "Using Firebird" there are already chapters on isql, gbak
> and gfix, and sections on the other tools. You could use those as a
> basis for your book - or use them for reference only, whatever.
> 

Well, I haven't got that far in Helen's book yet, but I'm working on it! 
On the other hand, I've already worked through the GSEC options and 
foibles and written up a first draft of that. The good thing about 
working it out for yourself , kis how much you learn. The source code is 
handy too :o) 

> Better leave build.xml alone and edit /src/docs/firebirddocs.xml:
> define an entity for your book (or one entity for each chapter) and
> include it (or them) further down. If you open the file you'll see how
> it works; just look at how it's done for the other books. You can
> comment out the others in your local copy to speed up the build
> process.
> 

No worries, I can follow that route without too much difficulty, I'll 
see how it pans out soon.


Many thanks.


Cheers,
Norman.

-- 

It's bad luck to be superstitious.

Re: [Firebird-docs] New potential doc writer

[Paul V. <pa...@vi...>]

Hi Norman,

> Well, I haven't got that far in Helen's book yet, but I'm working
> up it!

I'm still in chapter 2 or so - I read it in bed but by the time I wind
up there I'm usually too tired ;-)

> On the other hand, I've already worked through the GSEC options and
> foibles and written up a first draft of that. The good thing about
> working it out for yourself , kis how much you learn.

Yep, fully agree!

>> Better leave build.xml alone and edit /src/docs/firebirddocs.xml:
>> define an entity for your book (or one entity for each chapter) and
>> include it (or them) further down. (...)

> No worries, I can follow that route without too much difficulty,
> I'll see how it pans out soon.

OK, but please don't hesitate to ask if you get stuck.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] New potential doc writer

[Norman D. <No...@Bo...>]

In article <Pin...@s4...>, 
pa...@vi... says...
> >> Better leave build.xml alone and edit /src/docs/firebirddocs.xml:
> >> define an entity for your book (or one entity for each chapter) and
> >> include it (or them) further down. (...)
> 
> > No worries, I can follow that route without too much difficulty,
> > I'll see how it pans out soon.
> 
> OK, but please don't hesitate to ask if you get stuck.
> 

Morning Paul,

I've managed to add my GSEC document to the firebirddocs.xml. I had a 
few problems in PDF generation if it as added as a book, but I reworked 
it as an article, and all is well.


Cheers,
Norm.

-- 

Re: [Firebird-docs] New potential doc writer

[Paul V. <pa...@vi...>]

Hi Norman,

> I've managed to add my GSEC document to the firebirddocs.xml. I had
> a few problems in PDF generation if it as added as a book, but I
> reworked it as an article, and all is well.

It should work equally well as a <book>. BTW, as you probably noticed,
"build pdf" results in One Big Book containing all our documentation,
which is stupid. So for the PDF generation, we have to resort to a
little trick:

- Open manual/src/docs/fo.xsl and find this line:
  <xsl:param name="rootid" select="''"/>

- Fill in the topmost DocBook id of the document you want to produce.
  For instance, if the id is "cltools", change the line to:
  <xsl:param name="rootid" select="'cltools'"/>

- Now if you issue a "build pdf", the PDF file will only contain the
  cltools document. Note: it will still be called "firebirddocs.pdf"
  but of course you can rename it.

In the meantime I've committed some more PDF rendering improvements to
CVS. It may be worth updating your local copy of the manual tree.

Please let us know if/when you've got something to show! :-)


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] New potential doc writer

[Norman D. <No...@Bo...>]

In article <Pin...@s4...>, 
pa...@vi... says...

> It should work equally well as a <book>. BTW, as you probably noticed,
> "build pdf" results in One Big Book containing all our documentation,
> which is stupid. So for the PDF generation, we have to resort to a
> little trick:
<SNIP>

I'm not too bothered by the fact it's an all in one pdf, at least I know 
my stuff 'integrates' properly in the various contents pages etc.

> 
> In the meantime I've committed some more PDF rendering improvements to
> CVS. It may be worth updating your local copy of the manual tree.
> 

I've just done this and rebuilt everything.


> Please let us know if/when you've got something to show! :-)
> 

I've got a first attempt with GSEC and I've started on GBAK. I've also 
amended the top level firebirddocs.xml to include these two as entities 
(I might be getting the hang of this DocBook stuff !). Where do I send 
them for a review ?


Cheers,
Norm.


-- 

There's no such thing as gravity, the Earth sucks.

Re: [Firebird-docs] New potential doc writer

[Paul V. <pa...@vi...>]

Hi Norman,

> I've got a first attempt with GSEC and I've started on GBAK. I've
> also amended the top level firebirddocs.xml to include these two as
> entities (I might be getting the hang of this DocBook stuff
> !). Where do I send them for a review ?

The best procedure is to put it up (DocBook source + HTML and/or PDF)
on a website and post the URL here. This way everybody who's
interested can read and comment. If that's not possible, you can mail
it to me (and others, if they show interest).


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] New potential doc writer

[Norman D. <No...@Bo...>]

In article <Pin...@s4...>, 
pa...@vi... says...
> Hi Norman,
> 
> The best procedure is to put it up (DocBook source + HTML and/or PDF)
> on a website and post the URL here. This way everybody who's
> interested can read and comment. If that's not possible, you can mail
> it to me (and others, if they show interest).
> 

Hi Paul,

I've built a single pdf file and the multipage (defaulthtml) for GSEC. 
I've got it uploaded to a temporary site at 

http://www.bountiful.demon.co.uk/firebird/index.html.

The xml source is there too. 

Don't be too surprised when you 'next' off the end to a 404 error, the 
GBAK stuff isn't there yet, because it isn't finished yet.


Cheers,
Norm.

PS. All comments, good or bad gratefully received until the end of this 
week when I'm off to Greece for about 3 weeks :o) My wife wants some 
sun, I'll be the one in the shade.

She won't let me take my laptop, so I won't be updating anything after 
Thursday night this week. 

--