firebird-docs — chat stuff about documentation

Re: [Firebird-docs] Draft Docwriting Howto available

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

Hello Karl,

>>   http://vinkenoog.nl/firebird/drafthowto/

> The link is broken (Server not found)
> Is this a correct adress ? You are owner of a top-level.domain :-)

Yes, it's correct, but there was a UPS problem this weekend so the
server was unreachable for a couple of hours. It's back up now.


Greetings,
Paul Vinkenoog


PS:
If you *subscribe* to this list at

  http://lists.sourceforge.net/lists/listinfo/firebird-docs

your messages will appear without delay, whether you mail them or post
them through the news interface.


PPS:
Top level domains are .com, .de, .nl, .org etc. I dont't own any of
those :-)

Re: [Firebird-docs] Draft Docwriting Howto available

[Karl S. <web...@st...>]

pa...@vi... (Paul Vinkenoog) wrote in 
news:Pin...@s4...:

> Hello all,
> 
> The Docwriting Howto is not yet completely finished, but everything
> you need to know about DocBook is in there now. I placed it at
> 
>   http://vinkenoog.nl/firebird/drafthowto/
> 

The link is broken (Server not found)
Is this a correct adress ? You are owner of a top-level.domain :-)

Re: [Firebird-docs] Command Line and SQL Reference

[Milan B. <mi...@yu...>]

Phil Shrimpton wrote:
>>>I would like to provide them with the command line reference for all
>>>FB command line tools, as well as the FB SQL 'syntax'.
>>>
>>>Does anyone have this information in Excel (or simlar) format that I
>>>can use to convert to Palm format?
>>
>>I'm afraid you're gonna have to write it yourself ;-)
> 
> 
> ..I knew it was going to be a cut and paste job :-(

Well, for command line reference, you have everything in IB6 docs. SQL 
syntax is also there, but you'll need to add all stuff from various 
Firebird release notes to make it complete.

HTH



-- 
Milan Babuskov
http://fbexport.sourceforge.net

[Firebird-docs] Draft Docwriting Howto available

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

Hello all,

The Docwriting Howto is not yet completely finished, but everything
you need to know about DocBook is in there now. I placed it at

  http://vinkenoog.nl/firebird/drafthowto/

so you can all have a look and comment on it. The second Howto is
the one I just added.

I would especially like to know:

- Are the sections about DocBook clear? Because for most people, I
  think mastering DocBook is going to be the main obstacle.

- I state somewhere that it will take "less than an hour" to learn
  (from the Howto) what you need about DocBook. Is that realistic?

If you find any English language errors, please let me know too. (Of
course I'll try to prove you wrong if you point out an error, but
don't let *that* stop you - that's just how I am :-))

I also changed the HTML stylesheet a bit, a) to make the variablelists
decent, b) to make the tables less ugly, and c) to create more space
above section headers.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Command Line and SQL Reference

[Phil S. <ph...@sh...>]

On Thursday 15 January 2004 11:21, Paul Vinkenoog wrote:

Hi,

> > I would like to provide them with the command line reference for all
> > FB command line tools, as well as the FB SQL 'syntax'.
> >
> > Does anyone have this information in Excel (or simlar) format that I
> > can use to convert to Palm format?
>
> I'm afraid you're gonna have to write it yourself ;-)

..I knew it was going to be a cut and paste job :-(

> If it exists however, it would be a great starting point for a
> Firebird SQL Reference. Myself I've been thinking of setting up a
> Firebird DB where I can put all the information for the Firebird API
> Reference. Once everything's in the DB I could generate the XML docs
> automatically 

Over the past year or so we (my company) has converted all our docs to XML, 
from 'marketing rubbish' right down to low level API documents of our 
products.  It took a lot of time and effort, but now, from the same source, 
we can produce 'web sites', PDF's, word processor documents, online help, and 
just about every format we think we may need.

Phil


-- 
                         Discover a lost art - play Marbles
                                     April 2004
ICQ: 760757 | AIM: pjshrimpton | Y!: pjshrimpton | pjs...@ja...

Re: [Firebird-docs] Command Line and SQL Reference

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

Hi Phil,

> We are currently in the process of equiping our field engineers with
> PDA's (Palms) containing all our support documents etc.
>
> I would like to provide them with the command line reference for all
> FB command line tools, as well as the FB SQL 'syntax'.
>
> Does anyone have this information in Excel (or simlar) format that I
> can use to convert to Palm format?

I'm afraid you're gonna have to write it yourself ;-)

If it exists however, it would be a great starting point for a
Firebird SQL Reference. Myself I've been thinking of setting up a
Firebird DB where I can put all the information for the Firebird API
Reference. Once everything's in the DB I could generate the XML docs
automatically (well, first I'd have to write the XML generator :-))


Good luck with your project!

Greetings,
Paul Vinkenoog

[Firebird-docs] Build.sh issue

[Dimitrios C. I. <dc...@in...>]

Hi all,

  after i installed the java re (rpm) and exported the JAVA_HOME 
variable i try to execute the build.sh script. It returned an error 
that the java command cannot be found. The JAVA_HOME was correct so 
i edit the script and added $JAVA_HOME/bin/java blah blah .....

  The jre is installed in /usr/java/j2re1.4.2_03 dir. Is it my 
distro (RH8.0 Full Update) or is it a bug ?

Dimitris

[Firebird-docs] Command Line and SQL Reference

[Phil S. <ph...@sh...>]

Hi,

We are currently in the process of equiping our field engineers with PDA's 
(Palms) containing all our support documents etc.

I would like to provide them with the command line reference for all FB 
command line tools, as well as the FB SQL 'syntax'.

Does anyone have this information in Excel (or simlar) format that I can use 
to convert to Palm format?  I will of course donate the Palm 'databases' back 
to the project.

Phil
-- 
                         Discover a lost art - play Marbles
                                     April 2004
ICQ: 760757 | AIM: pjshrimpton | Y!: pjshrimpton | pjs...@ja...

RE: [Firebird-docs] PocketBook: MAJ and MIN?

[Nigel W. <ni...@e-...>]

> I'm a little confused with the [MAJ] and [MIN] tags. Can 
> these go anywhere in the paragraph?
> I understand the other tags, as they're close to HTML.
> 
> CQ

Ok. Got food.

The main problem is that DocBook needs a <para> to be fairly atomic, ie, not
interrupted with any new <section>'s.

This may not be entirely correct(yet), but to allow the freedom, I'm adding
a meta-data layer to the paragraph. This metadata stores:
New section(y/n), and title
New subsection(y/n), and title
Close the current sub-section(y/n)
Close the current section(y/n)

But it's not in yet. In the mean time, if you could use a separate paragraph
for each logical section/subsection, it'll make adding the layer much
easier.

If you're making a new section, put at the top of the paragraph:
[MAJ][TTL]Title of new section[/TTL]

If you start a new subsection, create a new paragraph, and do the following:
[MIN][TTL]Title of new subsection[/TTL]

And when you're finishing a (sub)section, use:
[/MIN] or [/MAJ]

This'll make it easier to pull the meta-data when I convert it.
It also keeps it easy for the HTML renderer(and subsequent PDF renderer) to
produce good outputs.

Clear as mud? 
I'd better go update the 'Site Usage' page to contain this info.

Good Luck!

Nige.

RE: [Firebird-docs] PocketBook: MAJ and MIN?

[Nigel W. <ni...@e-...>]

Woosh! Caught me at a bad time!

Paul V. and I are throwing ideas around on how to get better DocBook output
out of FireFly(The doc engine), and this is the bit that's changing...

If you don't mind, I'll go get a salad, and have a think...

N.

> -----Original Message-----
> From: fir...@li... 
> [mailto:fir...@li...] On Behalf 
> Of Claire Q'vant
> Sent: Monday, 12 January 2004 12:24
> To: Firebird-Docs
> Subject: [Firebird-docs] PocketBook: MAJ and MIN?
> 
> I'm a little confused with the [MAJ] and [MIN] tags. Can 
> these go anywhere in the paragraph?
> I understand the other tags, as they're close to HTML.
> 
> CQ
> 
> 
> -------------------------------------------------------
> This SF.net email is sponsored by: Perforce Software.
> Perforce is the Fast Software Configuration Management System offering
> advanced branching capabilities and atomic changes on 50+ platforms.
> Free Eval! http://www.perforce.com/perforce/loadprog.html
> _______________________________________________
> Firebird-docs mailing list
> Fir...@li...
> https://lists.sourceforge.net/lists/listinfo/firebird-docs
> 

[Firebird-docs] PocketBook: MAJ and MIN?

[Claire Q'v. <cla...@ya...>]

I'm a little confused with the [MAJ] and [MIN] tags. Can these go anywhere in the paragraph?
I understand the other tags, as they're close to HTML.

CQ

RE: [Firebird-docs] Pocketbook on the backburner

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

* WARNING: ME-TOO MAIL AHEAD! *

>> If you have any more questions about the pocketbook app, we'd
>> better take it off-list...(sorry Helen)

> Why sorry Helen?  because I'm the mail witch?
>
> It seems not something that should go off-list. At least to my tiny
> mind, it makes more sense for people doing documentation to stay
> much-in-touch. Firebird-docs should be "base-camp" for everybody.

Yep!

I'm glad this list is coming to life a bit, and Nigel's efforts are
fully on topic.


Greetings,
Paul Vinkenoog

RE: [Firebird-docs] Pocketbook on the backburner

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

At 10:50 AM 12/01/2004 +1100, Nigel Weeks wrote:
> > I could possibly begin on the 'Creating Tables' chapter.  Is
> > there some kind of code to say 'Work in Progess' for an article?
> >
> > Might take me a while to get familiar with your app...
> >
> > Claire.
> >
>
>Just don't post it to a section for moderation. You can take as much time as
>you like.
>If you want to show it before it's committed, use the URL of the 'Preview
>Article' window.
>
>If you have any more questions about the pocketbook app, we'd better take it
>off-list...(sorry Helen)

Why sorry Helen?  because I'm the mail witch?

It seems not something that should go off-list.  At least to my tiny mind, 
it makes more sense for people doing documentation to stay 
much-in-touch.  Firebird-docs should be "base-camp" for everybody.

Helen

RE: [Firebird-docs] Pocketbook on the backburner

[Nigel W. <ni...@e-...>]

> I could possibly begin on the 'Creating Tables' chapter.  Is 
> there some kind of code to say 'Work in Progess' for an article?
> 
> Might take me a while to get familiar with your app...
> 
> Claire.
> 

Just don't post it to a section for moderation. You can take as much time as
you like.
If you want to show it before it's committed, use the URL of the 'Preview
Article' window.

If you have any more questions about the pocketbook app, we'd better take it
off-list...(sorry Helen)

N.

Re: [Firebird-docs] Pocketbook on the backburner

[Claire Q'v. <cla...@ya...>]

On Mon, 12 Jan 2004 08:49:30 +1100
"Nigel Weeks" <ni...@e-...> wrote:

> Sorry Paul(and others), the pocketbook will have to wait a week - snowed
> under with work.
> 
> If you have ideas for content(even new pocketbook titles, ie, developers
> guide, etc), I will be lurching.
> 
> Nige.

I could possibly begin on the 'Creating Tables' chapter.  Is there some kind of code to say 'Work in Progess' for an article?

Might take me a while to get familiar with your app...

Claire.

[Firebird-docs] Pocketbook on the backburner

[Nigel W. <ni...@e-...>]

Sorry Paul(and others), the pocketbook will have to wait a week - snowed
under with work.

If you have ideas for content(even new pocketbook titles, ie, developers
guide, etc), I will be lurching.

Nige.

Re: [Firebird-docs] I want to help to translate to spanish

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

Hi Jose,

> Hello, I would like to colaborate to translating documentation to
> spanish. What can I do ?

Have you got any idea yet *what* you want to translate? Helen asked
translators for the Release Notes; don't know if she already found
someone for Spanish.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] ATTN Lou, Jose, and all: better not post thru Atkin newsgroup

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

Hi all,

> Jose for instance posted two messages on January 3, but it took 5
> days before they appeared on the list. Lou posted a message on the
> 6th that took 2 days to arrive. (Clearly there was a clog in the
> pipeline that got removed, or decided to go away by itself, on
> January 8.)

Pavel Cisar sent me an email today; the explanation turns out to be
different from what I thought:

If you are subscribed to the _mailing list_ and you post through the
Atkin _news interface_, your message will be forwarded to the list
automatically and immediately (if Atkin runs smoothly).

If you are not a mailing list subscriber, you can still post via the
news interface but your message will be held for approval by the
moderator (Pavel). He usually reads and forwards these messages every
day, but he's had some extremely busy days recently. That, combined
with the fact that Jose and Lou weren't subscribed to the list, was
the cause of the delay.

So you should always subscribe to the mailing list if you want your
messages to arrive quickly. And I still think it's also best to mail
your contributions to the list, because that's the most direct way.


Greetings,
Paul Vinkenoog

[Firebird-docs] ATTN Lou, Jose, and all: better not post thru Atkin newsgroup

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

Hi all,

The Atkin newsgroup interface to this and other lists is great for
browsing and reading, but it does suffer from hickups and delays. Jose
for instance posted two messages on January 3, but it took 5 days
before they appeared on the list. Lou posted a message on the 6th that
took 2 days to arrive. (Clearly there was a clog in the pipeline that
got removed, or decided to go away by itself, on January 8.)

This happens quite often if you post through the newsgroup interface.
So if you want your messages to arrive promptly, always send them by
EMAIL to fir...@li... - they'll usually show up
after a couple of minutes.


Greetings,
Paul Vinkenoog

[Firebird-docs] I want to help to translate to spanish

[XyVy <xy...@on...>]

Hello, I would like to colaborate to translating documentation to 
spanish. What can I do ?

thanks.
Jose Velasco.

RE: [Firebird-docs] Docs, create, I can

[Nigel W. <ni...@e-...>]

> But did you also write the part that does the actual PDF rendering?

Ah heck no, that's "htmldoc", a tool for turning all sorts of docs into all
sorts of other docs

> DocBook elements (there are hundreds, of which we
> actively use a few dozens) are all about structure and semantics,
> never about layout or makeup. This makes it ideal for storing
> technical documentary content. The makeup of the rendered documents
> is controlled through stylesheets.

Groovy!
 
> Your system will certainly be easier to use, but it doesn't have the
> richness of DocBook, _and_ it includes makeup codes. Please don't take
> this as criticism: like I said, I thought the output looked great.
> 
> DocBook is not really hard to learn, but for some people it could be
> an obstacle just high enough to keep them from contributing at all.
> For these people your setup could be a godsend.

Well, it's there if people want to have a go. Just register, create,
preview, and submit to a section for moderation...;-)

 
> The Docwriting
> Howto will include all you need to know to get started, and I think
> you can master the DocBook part in less than an hour - not to learn it
> by heart, but to read and understand it, and to get started with the
> docwriting. But maybe that's overoptimistic; I'm really interested to
> know what people think of it once they read it.

I shall peruse it when it's available! ;-)

> Can you have more than one pocketbook at your site? I sure hope so
> because to cram all the docs together in one giant PDF is not exactly
> ideal...

I would imagine so. The P133 has 40MB ram, so it should do it just fine.
I could quickly break out each section into it's own pocketbook - rough, but
a start.

Have a good night's sleep!

N.

RE: [Firebird-docs] Docs, create, I can

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

Hi Nigel,

>> I visited your pages, they look really good! And so does the
>> PDF. Can I ask what engine you use to generate it? It does a better
>> job than ours :-)

> I wrote the engine myself. It's fully PHP and Firebird powered, and
> a cron job to create the PDF every 5 minutes.

But did you also write the part that does the actual PDF rendering?


>> Well, yes and no. The more good documentation, the better. But for
>> the project at SourceForge we
>> a) really want DocBook sources

> I'm presuming this is so you can quickly convert from XML markup,
> into HTML/PDF in a snap.

Not only that. Also important is that it's an open standard,
platform-independent, and especially that it's completely
makeup-free. DocBook elements (there are hundreds, of which we
actively use a few dozens) are all about structure and semantics,
never about layout or makeup. This makes it ideal for storing
technical documentary content. The makeup of the rendered documents
is controlled through stylesheets.

> This system uses simple tags for bolds/underlines/code snippets,
> etc, and generates HTML/PDF for you instantly. Perhaps I can make
> your life easier.

Your system will certainly be easier to use, but it doesn't have the
richness of DocBook, _and_ it includes makeup codes. Please don't take
this as criticism: like I said, I thought the output looked great.

DocBook is not really hard to learn, but for some people it could be
an obstacle just high enough to keep them from contributing at all.
For these people your setup could be a godsend.

> Or perhaps I can add a DocBook output filter...

Yes, but it would only output very poor DocBook. For it would have to
drop all the bold, italics etc. stuff (since that doesn't exist in
DocBook) and it would not know where and how to apply other DocBook
tags such as <database>, <filename>, <literal>, <blockquote>,
<example>, <bookinfo>, etc. etc., and there's also the question of
assigning IDs to elements (often necessary in DocBook for
cross-referencing).

So this output would then have to be edited by someone who's
knowledgeable about DocBook and about the subject matter, possibly in
cooperation with the original author. Of course that's still
better than not having the doc at all... but I really do hope people
will want to invest a little time to learn DocBook. The Docwriting
Howto will include all you need to know to get started, and I think
you can master the DocBook part in less than an hour - not to learn it
by heart, but to read and understand it, and to get started with the
docwriting. But maybe that's overoptimistic; I'm really interested to
know what people think of it once they read it.

> Unfortunately my skills include:
> Bare-iron installs(framework in pocketbook)
> Securing databases(framework in pocketbook)
> Theories of database design
> Tables/triggs/st.procs/ref.integ/exceptions (no views yet - haven't
> had a need yet)
> PHP based apps, both web and command-line

What do you mean: unfortunately? I think you could make some nice
Firebird-related docs with this knowledge :-)

> I wouldn't mind wrapping many of these how-to's and docs into one
> pocketbook. Any problems here?
> (References would be listed, or course)

That would require the permission of each individual author, unless
they explicitly state in their documents that it's OK to republish
them in another format.

Can you have more than one pocketbook at your site? I sure hope so
because to cram all the docs together in one giant PDF is not exactly
ideal...


OK, signing off now... tired...

Paul Vinkenoog

Re: [Firebird-docs] Docs, create, I can

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

Hi Steve,

> I already have the migration doc from IBPhoenix:
>
>         http://www.ibphoenix.com/a542.htm
>
> and the one from Marcelo Lopez Ruiz:
>
>         http://www.xlprueba.com.ar/ib/defaulthtml/ch01.html
>
> I'm assuming neither of these are the Sourceforge doc. Or am I just
> not with it yet today?

At SF, we have the one from Marcelo, but for the moment only as a
DocBook XML source. If you want to build it you'd have to checkout the
manual module. But since you already have it...

This situation is going to change in the near future; we'll place the
finished docs as PDF and/or HTML in the files section. But first I
would like to finish the Docwriting Howto and improve the PDF output
if possible. It really doesn't look good.


Greetings,
Paul Vinkenoog

RE: [Firebird-docs] Docs, create, I can

[Nigel W. <ni...@e-...>]

Hi Paul,

> I visited your pages, they look really good! And so does the PDF. Can
> I ask what engine you use to generate it? It does a better job than
> ours :-)
> 

I wrote the engine myself. It's fully PHP and Firebird powered, and a cron
job to create the PDF every 5 minutes.
Doc Writers need only register on the site, and start producing articles.
Moderators decide when the article is ready for inclusion in the book.

It's probably an ideal system for multiple doc writers to prepare their
articles, and get them included in the final documentation...(I dunno)

> On thing though: the "Firebird Documentation Project" already exists,
> as a subproject of the official Firebird Project at SourceForce. So if
> you continue with yours as a separate project, I think you'd better
> give it another name in order to avoid confusion.
> 

Already changed. It's now called 'Firebird Pocketbook'. PDF should have
caught up by the time you get this email...

> 
> > Hopefully, it's a matter of, 'The more, The merrier?'
> 
> Well, yes and no. The more good documentation, the better. But for the
> project at SourceForge we
> a) really want DocBook sources (if you can't produce that, someone
>    else will have to convert it, which takes time), and

I'm presuming this is so you can quickly convert from XML markup, into
HTML/PDF in a snap. This system uses simple tags for bolds/underlines/code
snippets, etc, and generates HTML/PDF for you instantly. Perhaps I can make
your life easier.
Or perhaps I can add a DocBook output filter...

> b) would like to coordinate things a bit so there's not too 
> much overlap.
>    Of course this doesn't mean that WE decide what YOU write 
> about; just
>    that the docwriters talk about what they would like to / 
> are going to
>    write about, so we can make the best possible use of our collective
>    knowledge and skills.

Unfortunately my skills include:
Bare-iron installs(framework in pocketbook)
Securing databases(framework in pocketbook)
Theories of database design
Tables/triggs/st.procs/ref.integ/exceptions (no views yet - haven't had a
need yet)
PHP based apps, both web and command-line

> Not that I know. *Certainly* not in the SourceForge project. To date,
> we have very little: an introduction, an MS-SQL-To-Firebird Migration
> Guide, a Docbuilding Howto, a second Howto in the making and that's
> it. And I'll start documenting the Firebird API soon.
> 
> Now there's also a lot of free docs (and pointers to it) available at
> ibphoenix.com. I suggest you have a look there to see if some of the
> things you mentioned have already been taken care of, and then decide
> on what to start with.
> 
I wouldn't mind wrapping many of these how-to's and docs into one
pocketbook. Any problems here?
(References would be listed, or course)

Nige.

Re: [Firebird-docs] Docs, create, I can

[<Ste...@si...>]

Hi Paul,

>*Certainly* not in the SourceForge project. To date,
>we have very little: an introduction, an MS-SQL-To-Firebird Migration
>Guide,

I'm having a bad time finding the MS SQL to Firebird Migration doc on 
Sourceforge. Where is it?

I already have the migration doc from IBPhoenix:

        http://www.ibphoenix.com/a542.htm

and the one from Marcelo Lopez Ruiz:

        http://www.xlprueba.com.ar/ib/defaulthtml/ch01.html

I'm assuming neither of these are the Sourceforge doc. Or am I just not 
with it yet today?

Steve Miller
Language Software Development
SIL International