firebird-docs — chat stuff about documentation

Re: [Firebird-docs] Quick Start Guide 1.5

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

Salut Philippe,

>> http://www.firebirdsql.org/pdfmanual/Firebird-1.5-QuickStart.pdf

> Well done !
> so I can start the french translation

Alors bonne chance! / Good luck!


Grtz,
Paul Vinkenoog

Re: [Firebird-docs] gsec doc

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

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

Hi Paul,

There attempt number 3 at :

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

> 
> Yes, I think it's better now.
> 

Phew !

> One more thing though: in verbatim environments (screen, program-
> listing etc.) you must limit the line length to 72 characters,

OK, I've fixed the >72 character problems and it does look miles better 
when rendered as PDF. I was wondering how to fix that problem, I just 
forgot to ask.

> Also, if you use leading whitespace in verbatims, it's nicer if you
> match the amounts. E.g. in "GSEC Commands" there are two screens
> shortly after one another. The first has a 7 char left margin, the
> second 5.

Must have been a cut and paste screw up on my part, those two 'screens' 
were lifted directly from a DOS session of GSEC -help. Sorted now - no 
leading spaces.

> (Actually I'm not even sure if you should use a <screen> here. You're
> not presenting this as a screen example to the user, but as an
> enumeration. So an <itemizedlist> would be more logical.)

I've sorted thoise two, and the one above which you didn't spot :o)

> BTW, a tip: for lists, you can set 'spacing="compact"'. This is often
> nicer if the items are short. Unfortunately, it only works for the PDF
> output.

Done this. I'm not sure I like the look of the output though. Seems to 
make the explanation paragraph too close to the line above. Still ...


> > No, that's in France, I'm off to Crete :o)
> 
> Alright, smartypants! :-)  Watch out for the labyrinths...

I'll do my best. Problem is, Crete (and most other Greek Islands) tend 
to be somewhat hilly, and I get awful vertigo when travelling on the 
roads. I suspect I'll just have to sit in the shade reading books - and 
maybe doing a bit of drawing - for a couple of weeks.

> [ Mystery man: ]
<SNIP>
> him. Better take this EPOCMAN passage out, or people will start
> worrying if they *don't* find him in their USERS table ;-)

EPOCMAN, the mystery, is no more. He's still there in the display 
command output, but no-one will know that he is a mysterious entity.

That's it then, I might get a chance to check email etc tomorrow (I tend 
to use Atkin for posts as I get a daily digest via email) but I'll be 
travelling home for the weekend in the PM and then off to places sunny 
next week.

I'll 'see' you when I get back.

Cheers,
Norm.

PS. Helen - good book, well worth the wait. I'm up to selectable stored 
procs at the moment. I notice that it is still over 1000 pages, did they 
put back the bits they were going to put on a downloadable 'CD' ?

N.

Re: [Firebird-docs] gsec doc

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

Hi Norman,

> I've reworked the gsec document as per your comments and it is
> in the same place as before :
>
> http://www.bountiful.demon.co.uk/firebird/index.html

Yes, I think it's better now.

One more thing though: in verbatim environments (screen, program-
listing etc.) you must limit the line length to 72 characters,
otherwise they run into the right margin (or even off the edge) in
the PDF output. That's not something that's "wrong" in your source,
it's just a practical limitation.

Also, if you use leading whitespace in verbatims, it's nicer if you
match the amounts. E.g. in "GSEC Commands" there are two screens
shortly after one another. The first has a 7 char left margin, the
second 5.

(Actually I'm not even sure if you should use a <screen> here. You're
not presenting this as a screen example to the user, but as an
enumeration. So an <itemizedlist> would be more logical.)

BTW, a tip: for lists, you can set 'spacing="compact"'. This is often
nicer if the items are short. Unfortunately, it only works for the PDF
output.


>> Nice!
>>
> No, that's in France, I'm off to Crete :o)

Alright, smartypants! :-)  Watch out for the labyrinths...


[ Mystery man: ]

> I'm using 1.5.0.4306 which is probably a late model candidate build.

4306 is the official, corrected, 1.5.0 Windows installer release (4290
was the first official 1.5.0 on all platforms but the Win installer
had a bug). I checked an untouched 4306 package today and EPOCMAN
isn't in the security database. My guess is that some tool has added
him. Better take this EPOCMAN passage out, or people will start
worrying if they *don't* find him in their USERS table ;-)


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Quick Start Guide 1.5

[Artur A. <su...@ar...>]

Paul Vinkenoog wrote:
>   http://www.firebirdsql.org/pdfmanual/Firebird-1.5-QuickStart.pdf

Great Work!

One small remark: I wonder if it's possible to build some kind of a 
"front page" for it. Some people will want to print it, and a front page 
will make the difference.

Artur

Re: [Firebird-docs] gsec doc (was: New potential doc writer)

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

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

Hi Paul,

I've reworked the gsec document as per your comments and it is in the 
same place as before :

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

The XML is there too.


> > All comments, good or bad gratefully received until the end of this
> > week when I'm off to Greece for about 3 weeks :o)
> 
> Nice!
> 
No, that's in France, I'm off to Crete :o)

> By the way: which Fb package did you use? I mean, because of the
> presence of EPOCMAN. He shouldn't be there, at least not in official
> packages.

I'm using 1.5.0.4306 which is probably a late model candidate build. 
I'll download the latest at some point soon. I'm not 'in production' 
with any databases so I'm not too worried yet.

> 
> Remarks:
> 
> - Yes, good idea to make it a <book>. But you should use <chapter>
>   elems instead of <article>s inside. Unlike the "Firebird Database
>   Documentation" book, which is a rather loose collection of articles,
>   your book's children belong closely together.
>   You can leave out <articleinfo/chapterinfo> since you're the
>   only author.
> 

It's now a book, with chapters instead of articles, and no articleinfo 
either. It builds ok so I'll continue in theis mode with the rest of the 
commandline stuff.

> - If you show a screen (i.e. a mixture of prompts / user input /
>   computer output), use a <screen>, not a <programlisting>. The
>   latter is for code fragments, SQL scripts or fragments, etc.
> 
Done. See new version online.

> - The screens in the Introduction are very informative, but I think
>   you should show them in a later section. Throwing bulky stuff
>   in the reader's direction at this early stage may scare them
>   out of reading the rest. There are women and children reading this!
> 
Women and children are safe again. I've reworked the introduction and 
removed all the scary stuff. It's very gentle now.

> An intro should ideally start with a couple of short paragraphs
> explaining what the tool is all about (like you do), possibly
>  followed by an overview of what's to come in the rest of the
>  sections (e.g. using itemizedlists or orderedlists).
>  After the intro, first some sections about the most common usages
>  (again, like you do). But I wouldn't show those lengthy screens and
>  look-what-happens-if-you-make-a-mistake examples too early.

Sorted. An overview of things to come has been added and scary stuff 
moved down a litle bit.

>  BTW: Maybe you should mention in the intro that on some platforms
>  (and depending on the Fb installation package) non-root users may
>  not be able to run gsec due to filesystem permissions, regardless
>  of whether they know the SYSDBA password or not.

Done.

> - ids should be all-lowercase: firebird-utilities instead
>  of firebird-Utilities; fbutilities-gsec-intro instead of
>  FBUtilities-gsec-intro, etc.

Sorted, I've reduced the size of them too and they are all lower case.

> - ids should start with the parent id, except when the parent is the
>  <set>, or when it is a <book> consisting of <article>s that hang
>  only loosely together (like "Firebird Database Documentation").

Guess what, I've done this as well. :o)

<SNIP>

Thanks for your assistance on my first attempts, hopefully the new 
version meets with 'standards' and I can get on and do some more while I 
still have time (ie Thursday evening !) before my holidays.



Cheers,
Norman.

PS. The start of GBAK has slipped into the pdf and html too, best 
ignored for now - its a very early draft.

[Firebird-docs] gsec doc (was: New potential doc writer)

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

Hi Norman,

> 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.

Overall, it looks very good! But see some remarks at the bottom
(lengthy as usual...)

> All comments, good or bad gratefully received until the end of this
> week when I'm off to Greece for about 3 weeks :o)

Nice!

> 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.

Can't you smuggle it between some shirts? :-)

By the way: which Fb package did you use? I mean, because of the
presence of EPOCMAN. He shouldn't be there, at least not in official
packages.


Greetings,
Paul Vinkenoog


Remarks:

- Yes, good idea to make it a <book>. But you should use <chapter>
  elems instead of <article>s inside. Unlike the "Firebird Database
  Documentation" book, which is a rather loose collection of articles,
  your book's children belong closely together.
  You can leave out <articleinfo/chapterinfo> since you're the
  only author.

- If you show a screen (i.e. a mixture of prompts / user input /
  computer output), use a <screen>, not a <programlisting>. The
  latter is for code fragments, SQL scripts or fragments, etc.

- The screens in the Introduction are very informative, but I think
  you should show them in a later section. Throwing bulky stuff
  in the reader's direction at this early stage may scare them
  out of reading the rest. There are women and children reading this!

  An intro should ideally start with a couple of short paragraphs
  explaining what the tool is all about (like you do), possibly
  followed by an overview of what's to come in the rest of the
  sections (e.g. using itemizedlists or orderedlists).
  After the intro, first some sections about the most common usages
  (again, like you do). But I wouldn't show those lengthy screens and
  look-what-happens-if-you-make-a-mistake examples too early.

  BTW: Maybe you should mention in the intro that on some platforms
  (and depending on the Fb installation package) non-root users may
  not be able to run gsec due to filesystem permissions, regardless
  of whether they know the SYSDBA password or not.

- ids should be all-lowercase: firebird-utilities instead
  of firebird-Utilities; fbutilities-gsec-intro instead of
  FBUtilities-gsec-intro, etc.

- ids should start with the parent id, except when the parent is the
  <set>, or when it is a <book> consisting of <article>s that hang
  only loosely together (like "Firebird Database Documentation").

  Litmus test is probably whether what you write is going to wind up
  in one PDF file. If so, give the top element (the book, in this case)
  an id (e.g. fbutils) and let all child ids start with that:
  fbutils-gsec, fbutils-gsec-intro, fbutils-gbak, fbutils-gbak-restore.

  (Yes, I know I sinned against this principle in the docbuild and
  docwrite howtos! But I was still young then :-) Will probably
  correct it one day)

  You don't have to reflect the entire hierarchy in the id once you
  descend below the sect1 level, otherwise you may wind up with
  outrageous ids like fbutils-gsec-commandline-linux-modify-usernames.
  But set, book, chapter, article and sect1 (or toplevel <section>)
  ids are used to generate the HTML file names, so try to be
  consistent down to and including sect1 level. (And try to keep
  those ids both short and informative.)

-- end-o-remarks --

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. 

--

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...

> 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] Quick Start Guide 1.5

[A6-CMO P. M. <mak...@a6...>]

Le 07/09/2004 02:45, Paul Vinkenoog a écrit :
> Hi all,
> 
> Last week's posting about the updated Quick Start Guide resulted in
> exactly 0 comments, so I suppose it's acceptable. The latest version
> (with master font now 11 instead of 10 for easier reading, and titles
> blue instead of green to move away from the InterBase docstyle) is at
> 
>   http://www.firebirdsql.org/pdfmanual/Firebird-1.5-QuickStart.pdf
> 
Well done !
so I can start the french translation

-- 
Philippe Makowski

Re: [Firebird-docs] Quick Start Guide 1.5

[Helen B. <he...@tp...>]

At 03:48 AM 7/09/2004 +0200, you wrote:

>I don't know how much CVS space we use. But since it's practically all
>source code, what else can we do?

Actually (OT for docs, sorry) Mark O'Donohue has private stuff stored in 
his rabbits area, including mp3s. Because the web-visible area is 
replicated in the cvs tree, on the (wrong) assumption that maintaining the 
web stuff via CVS would earn us statistics, we actually have all this 
stuff, including all that garbage, in two places.

For bona fide sources, there is no problem asking for more space.  The idea 
was first to get people to clear out their garbage so we'd know how much to 
ask for.

As far as I could tell, I was seeing the PDFs for the manual branch when I 
was cruising inside the CVS tree.  I'll again check this, to make sure that 
the binaries are not getting duplicated into the web branch by Mark's old 
scripts....

Helen

Re: [Firebird-docs] Quick Start Guide 1.5

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

Hi Helen,

> Damn, Paul, I meant to post a complimentary comment about it and
> totally forgot.  Both the PDF and the HTML versions are *very
> impressive*.

Thanks! :-)


>> Links to the QSG on our website have been updated.

> I'll recheck these links since, up till yesterday at least, we still
> had docs links pointing to the old version at IBPhoenix.

That's correct, I updated them only a few hours ago, in these four
locations: homepage sidebar, downloads menu, page_userdoc (added) and
manual subproject homepage. I think these are the only locations.

> I'm trying to do a makeover of all this stuff and coordinate the
> existing, neglected Doc Index with the documentation project. (...)
> Anyway, you and I need to get our heads together on this.

And hopefully a couple more people... anyway, the documentation pages
really need a big overhaul.

> The SF Admin people have been yelling at us (project admins)
> regarding our gross overuse of space on the CVS server so, in the
> long term, making the CVS tree the repository for multiple versions
> of our PDFs isn't going to win us any friends.

Fwiw, the PDFs (and the HTML) from the manual subproject aren't in the
CVS tree, because they can easily be re-rendered from the DocBook
sources (which are in CVS) should the need arise.

I wonder - are we such a big project? The Firebird home tree
(/home/groups/f/fi/firebird) currently uses around 215 M disk
space. That includes 145 M in the download subdir, of which 115 M for
the 1.5.1. prerelease. Officially, all group homedirs have a 100 M
soft quotum.

I don't know how much CVS space we use. But since it's practically all
source code, what else can we do?


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Quick Start Guide 1.5

[Helen B. <he...@tp...>]

At 02:45 AM 7/09/2004 +0200, you wrote:
>Hi all,
>
>Last week's posting about the updated Quick Start Guide resulted in
>exactly 0 comments, so I suppose it's acceptable. The latest version
>(with master font now 11 instead of 10 for easier reading, and titles
>blue instead of green to move away from the InterBase docstyle) is at
>
>   http://www.firebirdsql.org/pdfmanual/Firebird-1.5-QuickStart.pdf
>

Damn, Paul, I meant to post a complimentary comment about it and totally 
forgot.  Both the PDF and the HTML versions are *very impressive*.


>I'll also redo the other PDFs in the new style, and put up the 1.0
>QSG. This may take a little time as the PDFs still need some manual
>postprocessing after the build :-(
>
>Links to the QSG on our website have been updated.

I'll recheck these links since, up till yesterday at least, we still had 
docs links pointing to the old version at IBPhoenix.  As you know, I'm 
trying to do a makeover of all this stuff and coordinate the existing, 
neglected Doc Index with the documentation project.  It would have been 
further forward by now if SF hadn't been offline for a big chunk of the 
weekend.  I've been bogged down in Monday and Tuesday stuff since 
then.  :-(  Anyway, you and I need to get our heads together on this.

>Helen, if you're reading this: the release package builders need to be
>aware of the new QSG and its location. Should I announce it via the
>admin list, or via the devel list, or email them directly?

Announce it via the Admin list for now, so we can get some informed 
feedback from the package builders.  Once we've settled it, we can put up 
directions for the package builders regarding documentation.

In the past, certain persons argued strenuously against storing binary 
files on SF at all - hence why we currently don't have a SF repository for 
the release notes.  The SF Admin people have been yelling at us (project 
admins) regarding our gross overuse of space on the CVS server so, in the 
long term, making the CVS tree the repository for multiple versions of our 
PDFs isn't going to win us any friends.

These are Admin issues that need to be raised and shaken out for 
good-and-all.    There's a lot I don't know about our file resources on SF, 
as I'm discovering in the process of wending my way around the website and 
trying to document it for the new web team.  :-(

Helen

[Firebird-docs] Quick Start Guide 1.5

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

Hi all,

Last week's posting about the updated Quick Start Guide resulted in
exactly 0 comments, so I suppose it's acceptable. The latest version
(with master font now 11 instead of 10 for easier reading, and titles
blue instead of green to move away from the InterBase docstyle) is at

  http://www.firebirdsql.org/pdfmanual/Firebird-1.5-QuickStart.pdf

I'll also redo the other PDFs in the new style, and put up the 1.0
QSG. This may take a little time as the PDFs still need some manual
postprocessing after the build :-(

Links to the QSG on our website have been updated.

Helen, if you're reading this: the release package builders need to be
aware of the new QSG and its location. Should I announce it via the
admin list, or via the devel list, or email them directly?


Greetings,
Paul Vinkenoog

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...
> >> 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] rtf/txt output

[Nando D. <na...@de...>]

Paul,
thanks for all the pointers. I'll try and report back any useful
results.
Ciao
-- 
Nando Dessena
mailto:na...@de...

Re: [Firebird-docs] rtf/txt output

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

Hi all,

A little update on RTF rendering:

Only the development branch of Apache FOP renders to RTF. See

  http://xml.apache.org/cvs.html

Quicker (and probably better) is jfor, which also converts FO -> RTF.

  http://www.jfor.org


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] rtf/txt output

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

Hi Nando,

> is there a way to have txt or rtf output, preferably with the
> Firebird-docs build system? I am organizing the upcoming
> FlameRobin's documentation and if would be great to be able to show
> the readme file directly in the setup screens (on Windows).
> Unfortunately InnoSetup can only display rtf and text files.

FOP (which we use to produce PDF) supports several output formats,
including text and RTF. Unfortunately, when I just made a setup to
test those renderings, the plaintext looked like garbage and choked on
the first table, and the RTF didn't even get started... :-(

Still I would be surprised if there didn't exist any stylesheets to
produce (at least) plaintext from DocBook. It should be so basic. But
they're not included in our DocBook stylesheets.

Can InnoSetup display HTML? From XMLMind you can produce single-file
HTML. Or with our tools (printablehtml target). If you can't display
that, you could save the HTML file as text from a browser.

Other than that, you could google on "docbook" + "plaintext" +
"stylesheet*". And search the Mulberry XSL list archive:
http://www.mulberrytech.com/xsl/xsl-list/

(I just did some quick searches without luck; but there are a lot of
result pages, it just takes time to check them all out...)

BTW, if you *do* find anything useful, please let us know so we can
integrate it in the build tools.


Greetings,
Paul Vinkenoog

[Firebird-docs] rtf/txt output

[Nando D. <na...@de...>]

Hello,
is there a way to have txt or rtf output, preferably with the
Firebird-docs build system? I am organizing the upcoming FlameRobin's
documentation and if would be great to be able to show the readme file
directly in the setup screens (on Windows). Unfortunately InnoSetup
can only display rtf and text files.

Hints, anyone?

Ciao
-- 
Nando Dessena
mailto:na...@de...

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...@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,

> 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

[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/

[Firebird-docs] 1.5 Quick Start Guide ready - please comment!

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

Hi all,

The updating of the Quick Start Guide to 1.5 has now been completed.
Please have a look at it and tell me if there are any errors left
(typos; facts wrong; etc.)

This is important because the QSG will be included with future
Firebird releases.

I would also welcome your opinions on:
- The font. Too small?
- The margins. Too wide?
- The page size: is A4 OK or should I make it Letter to accommodate
  the Yankees? ;-)

Compared to the IBPhoenix version, these are the most important
changes:
- Separate 1.0 and 1.5 QuickStartGuides.
- Added section on Classic/Superserver early in the guide because
  users are faced with that choice when choosing a download (Linux)
  or when installing (Windows).
- Added section on security (1.5 version only).
- Various smaller additions, enhancements and corrections.


The 1.5 QSGs are here (HTML and PDF versions):

  http://www.firebirdsql.org/manual/qsg15.html
  http://www.firebirdsql.org/pdfmanual/Firebird-1.5-QuickStart.pdf

1.0:

  http://www.firebirdsql.org/manual/qsg10.html
  (PDF: a little later. PDF rendering has again been improved over
  the weekend but still needs hand-tweaking.)

Or visit the doc subproject home page where you can find all the
links:

  http://www.firebirdsql.org/index.php?op=devel&sub=doc


Greetings,
Paul Vinkenoog