firebird-docs — chat stuff about documentation

[Firebird-docs] Firebird Trigger

[Peter K. <kf...@pc...>]

I am trying to upgrade my existing Firebird db. However due to some tables
modification may fire my triggers which will end up disturbing or even
corrupting my existing data on another table. Is there a way that I can
switch all triggers during my database upgrade?

[Firebird-docs] Re: {Firebird-docs} Docs Built with Ventura

[Darcy O'N. <ds...@sk...>]

Hey Paul,

>
>It will take some time before we can make money this way, but I sure
>hope this will happen in the future. In the meantime good electronic
>documentation can help making Firebird better known; and good PDF docs
>can give a very professional impression.
>
>I imagine that it must be frustrating at times to get the Ventura
>import to work. Especially when I come with these long lists about
>"this don't work - that should be better". I really don't want to be
>overcritical but it just _has_ to be right. Looking good is not
>enough.
>  
>
Not really. I have worked for many years and have come to the conclusion 
that most people only want the best for whatever project I'm working on.

 From an individual stand point I would just like to get some starter 
documentation out the door. I'm not concerned at this point how it gets 
done, just that we can get it to some of the new users. These users will 
hopefully see the benefits of using Firebird and increase the user base, 
which of course every once in a while will add a new developer, which 
helps the whole project.

>The irony here is that all this level-of-indentation stuff works out
>of the box with our "internal" PDF generation. Just push the button,
>lean back, ignore all the error messages and out it pops. But it
>doesn't look good, the URLs are broken, and some other things too.
>
>So whichever road we take, there's work to be done and we don't know
>how much before we get it right.
>  
>
Eventually Ventura will work, it's probably the most powerful long 
document publishing system out there (yes even better than FrameMaker), 
but since it has so many features I just need to link them properly with 
the XML source.

Anyway, for now I'm probably going to tackle this problem on two fronts. 
One, keep working on Ventura for 'one button publishing' and two, get 
some documentation out the door and into the hands of the user, even if 
it means a little hand editing.

So keep the comment coming, I don't take things critically and know that 
at the end of the day it will all be worth it.

Darcy

Re: [Firebird-docs] New PDF Build from Ventura

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

Hi Darcy,

> You can find a copy of the latest PDF document build at:
>
> http://firebird.methyl.ca/writing.pdf
>
> The are significant number of improvements in this document. A
> couple of issues still remain outstanding (tips / important block
> text).

OK, I had a thorough look at it today. Some of the points listed
below are simply copied from my "old" list; some have changed or
disappeared, and one or two new issues showed up.

But before I start the list let me first say that yes, a lot has been
improved and I noticed that too. Especially the URL links - which at
first didn't work but made lots of trouble - are working great now,
and are nicely inlined in the text. Thanks! I'm not going to list all
the improvements here, but I just wanted to say this because otherwise
it looks like I'm only criticizing (as the list is still pretty long).


List of suboptimalities (nice bit of Newspeak, eh?):
====================================================

+ <sect1>: Could use more vertical space before it (say twice as much
  as now). And the headers should be bigger.

+ <orderedlist>: numeration loweralpha should be rendered as a, b, c...
  instead of A, B, C...

+ <quote> tags should not translate to italics. Italics emphasize,
  whereas quotes often relativize. Best translate them as surrounding
  double-quotes.

+ Internal links should work.

+ Still trouble with nested lists, e.g. under "Style" where the nested
  list OUTdents instead of indents, and doesn't have bullets.

+ <orderedlist> under "Docwriter's block" is enumerated D, E, F...
  instead of 1, 2, 3... Also, <para>s *within* a listitem get a
  capital letter and are thus promoted to a listitem (the famous
  paras-in-listitems problem).

+ New: Under "Your copyright" the entire paragraph now gets a bullet,
  and is also moved closer to the section header. The URL link in this
  paragraph doesn't work (unlike most, which are fine now).

+ <programlisting> should have fixed-width font.

+ <screen>: has fixed-width font now, good! But it shouldn't add a
  three-character (or thereabouts) wide left margin.

+ <variablelist>: preferably, they should be indented as a whole, just
  like <itemizedlist> and <orderedlist>, *and* the <listitem>s should
  be indented wrt the <term>s - just like in the HTML version. If this
  is a problem the <term>s could be on the same indentation level as
  the surrounding text, but the <listitem>s should really indent.

+ <sgmltag>: start- and enddtags are rendered correctly now, but
  empty-element tags still aren't (need '<' prefix and '/>' suffix).

+ admonitions: In the <important> rendering, the blue filling is not
  aligned with the frame. Or is that intentional?
  <note>s (and possibly others) are still not recognizable as such.

+ spaces next to tags still get eaten sometimes, e.g.:

    cvs update -d[ only if you want to update first]

  Upon closer scrutiny, it turns out that not only the space between
  "-d" and "[" disappeared, but even that the "[" was pulled into the
  "command" rendering (selecting text in the PDF makes this clear).
  There was also a space between "t" and "]".

  Also, under "Elements we use frequently":

    filename- command - application- envar
    subscript- superscript
    varname- constant- database

  etc...
  In the source, the hyphens never touch the words. The words
  are tagged, so this is again a case of the spaces-adjacent-to-tags-
  get-eaten syndrome.

  Finally, under "function - parameter - returnvalue":

    promptis

  But I'm sure there's more... :-)

+ <literallayout> should not indent wrt its context, but there should
  be some vertical space (say: one empty line) above and below it.

+ Tables: <tfoot> elements should wind up at the foot of the table,
  not near the top. <thead> and <tfoot> content should be printed
  bold or italic (preferably bold) to distinguish them from ordinary
  rows.
  "align" attributes should be honoured if possible.

+ <computeroutput> is an inline element and shouldn't be formatted
  as a block.

+ Spaces before a smiley are still eaten in the PDF - even in
  UNprofessional docs! Woe, woe! :-)


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Docs Built with Ventura

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

Hello Darcy,

> Think of it this way: the most poorly managed document system that
> still produces readable documents is better than the best managed
> document system that produces broken and non-user friendly
> document. Having spent years working at one of the worlds largest
> oil companies I can tell you that most of the documents were poorly
> managed (i.e. Excel = database, Word = desktop publishing system,
> Document Control System - None, Format Standard = Microsoft) but
> very accessible to the end user. Because the dumbest people could
> access the documents, the company was very successful.

What you say is true, but many companies have since discovered that
this unmanageability of documents is becoming a bigger and bigger
problem. In fact this is the most important reason why formats such as
DocBook - separating content from presentation - were developed, and
companies are now investing noticeable resources in converting their
documentation.

> We should probably concentrate on documenting Firebird as opposed to
> building the perfect doc system, even though that in itself is a
> worthy cause.

Sure, our main goal is to produce documentation. But to be able to do
that, and especially to keep them manageable, we must invest time in
the system too. The more we can automate the rendering, the better.
Everything that's not automated when it comes to e.g. the PDF
rendering will have to be done by hand *over and over again* - for
every new document, and for every new revision of every existing
document. That's why I don't mind investing time thinking about and
discussing the Ventura import you're working on. Because if this
works, and if we succeed in minimizing the handwork, the time invested
will pay itself back n-fold: we will have uncompromised DocBook
sources, clear and attractive HTML pages, *and* state-of-the-art
PDFs with minimal (ideally none at all) post-rendering correction
necessary.

In other words, by investing time in improving the rendering system
now, we will have more time later to concentrate on what it's all
about: writing docs.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Docs Built with Ventura

[Darcy O'N. <ds...@sk...>]

Hello,

>If we should take this route: what would you like to see in there, and
>in which situation(s) exactly?
>  
>
Not sure yet, we have lots of time to figure this out so I'll just keep 
hacking away with the XML Map and see if I can get a reasonable solution.

>
>True, but the HTML, PDF, etc. are also (maybe even more so) "only" a
>means to an end: our goal is to produce documentation and make it
>accessible for the users. The output formats are not goals in
>themselves, they are means to let the user access the information in a
>practical and user-friendly way. In ten years there may be totally
>different output formats, but the DocBook sources will still be valid
>because they don't contain presentational markup - only structured
>informational content. 
>
We're pretty much on the same page here, DocBook manages the 
'information', but the end users require an accessible document. Without 
informed end users there really isn't a project. Since I started using 
Firebird the only docs available we're from Interbase, since we are 
moving away from Interbase it's going to get harder and harder for 
people to migrate from other databases.

Think of it this way: the most poorly managed document system that still 
produces readable documents is better than the best managed document 
system that produces broken and non-user friendly document. Having spent 
years working at one of the worlds largest oil companies I can tell you 
that most of the documents were poorly managed (i.e. Excel = database, 
Word = desktop publishing system, Document Control System - None, Format 
Standard = Microsoft) but very accessible to the end user. Because the 
dumbest people could access the documents, the company was very successful.

>There's a better way to do this: I could write a small program that
>reads any XML file, extracts the tags, and looks them up in a list of
>known tags. Any tags not in the list are reported so you can deal with
>them. This is faster (apart from writing the prog once) and more
>reliable than having everybody doing it manually. If this would be of
>help to you, I could write such a program in 1 - 3 weeks (depending on
>how busy I am with other things).
>  
>
The Ventura XML map actually creates a list of used tags, it would be 
easier for me to use diff to see which new tags were added during a 
'release' period. We should probably concentrate on documenting Firebird 
as opposed to building the perfect doc system, even though that in 
itself is a worthy cause.

>Am I right in saying that the real problem is not in the tags (because
>we can deal with those one by one) but in the nesting? Is Ventura not
>aware of the nesting? That's the impression I get right now.
>  
>
I agree that for the most part the DocBook standard is good, but even 
the in the DocBook guide it clearly states in the <para> description 
that 'Some processing systems may find the presence of block elements in 
a paragraph difficult to handle. - and - There is no easy answer to this 
problem." No single solution is perfect and over time this will get 
better, so for now we'll see what we can do.

Darcy O'Neil

Re: [Firebird-docs] Docs Built with Ventura

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

Hi Darcy,

> I didn't mean to break the DocBook standard just identify certain
> <para> tags better.

Do you have any suggestion how? Without breaking DocBook validity,
that is. The only possibility I see is to use the "role" attribute and
scan for that in your import definition. However, this would impose on
every docwriter the task to manually add this attribute whenever he or
she inserts a <para> in certain situations. I don't know if this will
work in practice.
On a more philosophical level, it does kind of "pollute" the source
document.

If we should take this route: what would you like to see in there, and
in which situation(s) exactly?

>> It's not really a question of being "compatible" - our docs *are*
>> DocBook docs. And the processing tools we use are based on that. It
>> just so happens they do a poor job when it comes to PDF.

> Actually the real documents are HTML, PDF and possible RTF. Nobody
> reads a DocBook XML file. The DocBook standard is only a 'means to
> an end', and a way to manage the information.

True, but the HTML, PDF, etc. are also (maybe even more so) "only" a
means to an end: our goal is to produce documentation and make it
accessible for the users. The output formats are not goals in
themselves, they are means to let the user access the information in a
practical and user-friendly way. In ten years there may be totally
different output formats, but the DocBook sources will still be valid
because they don't contain presentational markup - only structured
informational content. That's why we should be careful not to bend our
DocBook sources in order to satisfy one particular representation. If
already we succeeded (which is doubtful) we might wind up with less
clean DocBook sources and as a result get al kinds of other problems
later, e.g. when we start rendering to new formats like HTML Help, or
formats that don't even exist yet today.

Again, the problem you're facing right now is not in the DocBook
sources but in the rendering. So if possible, that's where we should
deal with it, not in the sources - because those are fine.


Now, about listing the tags and reporting the use of "new" tags: I
don't think we can ask that from the docwriters. They are supposed to
produce valid DocBook and apply the right tag for the situation. If
they would have to check the tags they use against an external list
and maintain a second list to report any tag you haven't taken care of
yet, things become pretty cumbersome.

There's a better way to do this: I could write a small program that
reads any XML file, extracts the tags, and looks them up in a list of
known tags. Any tags not in the list are reported so you can deal with
them. This is faster (apart from writing the prog once) and more
reliable than having everybody doing it manually. If this would be of
help to you, I could write such a program in 1 - 3 weeks (depending on
how busy I am with other things).


Am I right in saying that the real problem is not in the tags (because
we can deal with those one by one) but in the nesting? Is Ventura not
aware of the nesting? That's the impression I get right now.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Docs Built with Ventura

[Darcy O'N. <ds...@sk...>]

Hello,

> Another consideration is that there's nothing wrong with the DocBook
> format as such. The problem you're facing now has to do with importing
> it into Ventura (which does support XML, but unfortunately not
> DocBook). So if the problem can be solved it has to be solved there,
> not by bending or breaking the DocBook standard.

I didn't mean to break the DocBook standard just identify certain <para> 
tags better.

>>Are we looking to be 100% compatible with DocBook?
> 
> It's not really a question of being "compatible" - our docs *are*
> DocBook docs. And the processing tools we use are based on that. It
> just so happens they do a poor job when it comes to PDF.

Actually the real documents are HTML, PDF and possible RTF. Nobody reads 
a DocBook XML file. The DocBook standard is only a 'means to an end', 
and a way to manage the information. The users of the Firebird database 
are expecting to read the documents in an easily recognizable and 
standard format i.e. Paper, PDF, HTML

The comment about being 100% compatible is better said as: can we 
reasonably be expected to support all the tags, from the start, in the 
DocBook standard when creating manuals if we want to develop quality 
manuals.

>>I'm thinking should we freeze the tags we use now, and then as
>>people have a need for more advanced stuff we add them as we go.
> 
> That would first require the generation of a list with all the tags we
> use now, and then ask people to avoid other tags if they can. 

Actually we don't want people to avoid tags, just tell us when they are 
going to use them, if they aren't on the current list, then I can add 
them to the mapping file and it will work fine. Without that notice the 
doc will publish fine but the section using the new tag won't look like 
the author intended.

  > - First realize it doesn't have to be solved in a week. If you see a
>   chance to develop a fix but it will take more time, by all means
>   take your time! If we can have these great-looking PDF versions in
>   half a year, without the errors they contain now: fine.
> 
> - Second: if it really can't be fixed, we could add a transformation
>   layer between the DocBook XML and Ventura. That is: we could develop
>   XSL stylesheets that convert the DocBook XML files to something
>   that's similar but with the "problem tags" removed or replaced by
>   other tags (which we could define ourselves). This layer wouldn't be
>   DocBook anymore; it would only be used for the Ventura import. Mind
>   you: this could take months too before it worked! But that's no
>   reason not to start with it if we can't fix it otherwise.

The best solution is to do a document release. i.e. freeze the document 
at a certain point, cut it and then process it with Ventura. Any errors 
can be hand edited. Now to most computer people automations is what they 
are used too, from a desktop publishers standpoint you have to manually 
go through each page and make the document perfect. If that means a few 
hours of hand editing for a better document then I'd prefer to do that. 
Spending days or hours making a 'transform layer' isn't worth it.

>   Before we do such a thing though, we could also have a look at
>   improving the current FO-producing stylesheets. After all, if we can
>   produce good and attractive PDF without Ventura, this would even be
>   better. But this too will take a lot of time I'm afraid.

That's the current benefit of Ventura in that it is designed to publish 
books and make them look good without a lot of time. I suspect that if 
we get the XML import at 90 to 95% the other stuff can be hand edited to 
make the document perfect.

Darcy O'Neil

Re: [Firebird-docs] FbManager documentation

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

Hi Helen,

[ fbmanager - firebird ]

>> The overall project license is MPL in both cases. IPL applies only
>> to code that originates from Borland.

> Ummm, the overall project licence is **not** MPL.  The Jury (read
> project Admins) is still out on what licence to use for new code.
> It is not likely to be MPL.  It's likely to end up being IDPL
> (Initial Developer's Public License).  Reason for eschewing MPL is
> the control Mozilla/Netscape has over the licence.

On the Project Summary Page it says:

  License: Mozilla Public License 1.0 (MPL)

That's why I assumed this was our overall or "default" license.

> The IDPL is distributed with Firebird 1.5 - see the Firebird root
> directory.  It is, like the IPL, a MPL derivative.

Thanks - I must admit I've never looked at it! ;-)


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Docs Built with Ventura

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

Hi Darcy,

> 1. The use of the <para> tag, especially when nested in
> <itemizedlist> - <listitem>, is causing some problems. The reason
> for this is that in Ventura you specify the relationship of the tag
> <itemizedlist><listitem><para> and then Ventura knows what 'Style'
> to apply to that section. The problem comes into play when Ventura
> doesn't recognize the 'tree structure', so it just applies the
> standard <para> tag. And in this case it should have bullet's.

But a standard <para> shouldn't have a bullet, should it? Is the
problem maybe that Ventura _does_ remember "we're inside a bulleted
list now" and then gives each paragraph a bullet just like Word does?
DocBook is like HTML in this respect: a listitem gets one bullet,
right at the start, no matter what happens inside.

What happens if you import an HTML file containing a structure like
this:

  <ul>
    <li>
      <p>First paragraph inside listitem</p>
      <p>Second paragraph inside listitem</p>
      <p>Third paragraph inside listitem</p>
    </li>
    <li>
      ...
    </li>
  </ul>

Do all the paragraphs get bullets too?

> In short to make it convenient we need to figure out a way for
> Ventura to recognize the nested tags without me building every
> possible relationship. This can even cause havoc in the Section tags
> <sect1> <sect2> etc. But luckily they only go to <sect5> so it's
> limited.  However, you can infinitely nest tags.
>
> Basically, should we use <simpara> for the simple paragraphs,

It wouldn't solve the problem, because there would still be a lot of
paras-in-listitems left that contain blockquotes, programlistings etc.
You can't use a <simpara> there. Also, many DocBook-aware XML editors
start a <para> when you hit Enter. The docwriter would have to
manually change that to <simpara> all the time (and then back to
<para> as soon as he includes a block element in the paragraph).

> or possible use and 'element' tag to identify nested tags?

What do you mean by that? In any case we can't invent new tags because
then the document isn't DocBook anymore. Editors will deem it invalid
and refuse to treat it as DocBook (you could still edit it as general
XML but then you lose all the DocBook validation). Processors will
break on it. So that's simply not an option.

Another consideration is that there's nothing wrong with the DocBook
format as such. The problem you're facing now has to do with importing
it into Ventura (which does support XML, but unfortunately not
DocBook). So if the problem can be solved it has to be solved there,
not by bending or breaking the DocBook standard.

> Are we looking to be 100% compatible with DocBook?

It's not really a question of being "compatible" - our docs *are*
DocBook docs. And the processing tools we use are based on that. It
just so happens they do a poor job when it comes to PDF.

> I'm thinking should we freeze the tags we use now, and then as
> people have a need for more advanced stuff we add them as we go.

That would first require the generation of a list with all the tags we
use now, and then ask people to avoid other tags if they can. That's
not a good approach. One of the reasons DocBook was chosen is its
richness of structural and semantical tags. If you author a DocBook
doc, you should always use the best-fitting tag for the situation, AND
only choose tags on the basis of meaning. You should never try to
choose tags for presentational reasons, or because proprietary
application A or B can't deal with certain tags or combinations
thereof. As soon as you start doing that, you are working towards one
specific representation of the text (possibly harming other
renderings) and you make your document less valuable.

Try to look at it this way: the DocBook XML version *is* the document.
The HTML and PDF renderings are ways to look at it, they are a kind of
viewport. If we have a problem with the rendering, we must try to fix
the rendering, not change the document itself.

That said, you're still left with the problem. As an outsider to
Ventura I can't say if it can be fixed, and how. But:

- First realize it doesn't have to be solved in a week. If you see a
  chance to develop a fix but it will take more time, by all means
  take your time! If we can have these great-looking PDF versions in
  half a year, without the errors they contain now: fine.

- Second: if it really can't be fixed, we could add a transformation
  layer between the DocBook XML and Ventura. That is: we could develop
  XSL stylesheets that convert the DocBook XML files to something
  that's similar but with the "problem tags" removed or replaced by
  other tags (which we could define ourselves). This layer wouldn't be
  DocBook anymore; it would only be used for the Ventura import. Mind
  you: this could take months too before it worked! But that's no
  reason not to start with it if we can't fix it otherwise.

  Before we do such a thing though, we could also have a look at
  improving the current FO-producing stylesheets. After all, if we can
  produce good and attractive PDF without Ventura, this would even be
  better. But this too will take a lot of time I'm afraid.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] FbManager documentation

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

At 03:12 PM 25/03/2004 +0100, you wrote:
>Hi Nando,
>
> > well, I'm not writing code (though I am participating in the design)
> > so I can't speak for the developers, but they would be happy to make
> > the tool part of the Firebird project *and* continue to maintain it
> > (if the Firebird project accepts both the code and the developers,
> > of course). I don't know if the license and other bits are
> > compatible, though (not my field really).
>
>The overall project license is MPL in both cases. IPL applies only to
>code that originates from Borland.

Ummm, the overall project licence is **not** MPL.  The Jury (read project 
Admins) is still out on what licence to use for new code.  It is not likely 
to be MPL.  It's likely to end up being IDPL (Initial Developer's Public 
License).  Reason for eschewing MPL is the control Mozilla/Netscape has 
over the licence.

The IDPL is distributed with Firebird 1.5 - see the Firebird root 
directory.  It is, like the IPL, a MPL derivative.

Helen

[Firebird-docs] New PDF Build from Ventura

[Darcy O'N. <ds...@sk...>]

You can find a copy of the latest PDF document build at:

http://firebird.methyl.ca/writing.pdf

The are significant number of improvements in this document. A couple of 
issues still remain outstanding (tips / important block text).

All suggestions are welcome.

Darcy O'Neil

Re: [Firebird-docs] FbManager documentation

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

Hi Nando,

> well, I'm not writing code (though I am participating in the design)
> so I can't speak for the developers, but they would be happy to make
> the tool part of the Firebird project *and* continue to maintain it
> (if the Firebird project accepts both the code and the developers,
> of course). I don't know if the license and other bits are
> compatible, though (not my field really).

The overall project license is MPL in both cases. IPL applies only to
code that originates from Borland.


Greetings,
Paul Vinkenoog

[Firebird-docs] Spaces (was: PDF rendering)

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

Hi Darcy,

>> Maybe the space got eaten because Ventura thinks there should't be
>> a space before a colon? This has to be fixed, because there are
>> also other situations where a space precedes a colon, e.g. in a C
>> code fragment or in a ratio.

> I think maintaining 'spaces' is going to be the hardest part of
> these doc's. Ventura supports formatting without problems i.e. cut
> and paste a text doc into Ventura and it will keep the tabs and
> spacing perfectly.  Import XML and it doesn't see the spaces because
> it see the doc as a XML file and removes all spacing, then applies
> formating to the tags.

I don't understand this. Sure it can remove all spacing *between*
elements, i.e. it can convert

  <section>
    <para>
      <emphasis>
         Don't forget this!
      </emphasis>
    </para>
  </section>

to:

  <section><para><emphasis>Don't forget this!</emphasis></para></section>

But here we're talking about spacing between words etc. *inside*
elements. I suppose Ventura doesn't convert <para>This is some
text</para> to <para>Thisissometext</para>, and neither should it
convert <para>a = x == y ? b : c</para> to <para>a=x==y?b:c</para> or
<para>Hi :-)</para> to <para>Hi:-)</para>


Greetings,
Paul Vinkenoog

[Firebird-docs] Docs Built with Ventura

[Darcy O'N. <ds...@sk...>]

OK, so things are moving along great except for a couple of things.

1. The use of the <para> tag, especially when nested in <itemizedlist> - 
<listitem>, is causing some problems. The reason for this is that in 
Ventura you specify the relationship of the tag 
<itemizedlist><listitem><para> and then Ventura knows what 'Style' to 
apply to that section. The problem comes into play when Ventura doesn't 
recognize the 'tree structure', so it just applies the standard <para> 
tag. And in this case it should have bullet's.

In short to make it convenient we need to figure out a way for Ventura 
to recognize the nested tags without me building every possible 
relationship. This can even cause havoc in the Section tags <sect1> 
<sect2> etc. But luckily they only go to <sect5> so it's limited. 
However, you can infinitely nest tags.

Basically, should we use <simpara> for the simple paragraphs, or 
possible use and 'element' tag to identify nested tags?

Are we looking to be 100% compatible with DocBook? I'm thinking should 
we freeze the tags we use now, and then as people have a need for more 
advanced stuff we add them as we go. It makes it much easier for me if 
someone tells me they're putting in <tagx> and they want it formated in 
such a way. As opposed to someone using a whole bunch of uncommon tags 
that break the document. Eventually, the whole DocBook standard could be 
supported but that's a big project in it's self! Maybe I should call 
Corel :)

Darcy O'Neil

Re: [Firebird-docs] FbManager documentation

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

Paul,

P> Iirc you also wrote in FFmembers that once ready, the lightweight
P> version would be "donated" to the Firebird project. I suppose that
P> means transfering the sources to the firebird project at SF?

well, I'm not writing code (though I am participating in the design)
so I can't speak for the developers, but they would be happy to make
the tool part of the Firebird project *and* continue to maintain it
(if the Firebird project accepts both the code and the developers, of
course). I don't know if the license and other bits are compatible,
though (not my field really).

P> wouldn't it be better to start an fbmanager (or fowl, or whatever)
P> module in firebird right away and develop it there?

OTTOMH I can't see why not. I have just forwarded your idea to
fbmanager-devel.

P> I don't know how much you know already about the manual setup

close to nothing, but I will be traveling in the next few days and I
have downloaded the docs I need to read...

P> we have all the documents in one DocBook <set>. One of the advantages is
P> that we can easily link to any other document in the set. If you would
P> develop the fbmanager documentation within the Firebird manual module,
P> we can all benefit from this.

P> The best approach IMO is to make a separate <book> for the fbmanager
P> documentation.

OK, so it would be a <book> and that <book> will be part of the whole
<set>. Sounds right.

P> You can find the most recent version of the Howtos at the doc
P> subproject homepage:

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

I'll be offline, so I've downloaded Darcy's pdf for the time being.
I hope it's enough for a start.

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

Re: [Firebird-docs] FbManager documentation

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

Paul,

P> Maybe you posted to the newsgroup from another email account than the
P> one you subscribed to the mailing list with?

my fault. I posted (through SMTP) with a different e-mail account.
I didn't notice it because one account forwards to the other, and I
almost never use the old one.
Now everything is OK.
Thanks
-- 
Nando Dessena
mailto:na...@de...

Re: [Firebird-docs] ATTN Darcy, and all: PDF rendering

[dso <ds...@sk...>]

Hello,

>>1. Chapter 1 - Basically, with Ventura a chapter system allows
> 
> But is it mandatory that a doc (a single PDF file) have at least one
> chapter? It's not the end of the world, but it looks a little silly to
> have a document with just a "Chapter One" and no other chapters, even
> though it is in itself complete. Oh well, if we can't change this, we
> can put the Docbuilding + Docwriting Howtos in one PDF (they already
> form one DocBook <book> together).

Actually the Chapter can be removed for single doc's no problem. But if 
we do go to a 'complete' book then the chapters are beneficial. In the 
separated Chapters I just need to create a 'chapterless' template. Easy 
enough.

>>4a. <sect1> Vertical Space - this is a preference issue, design wise
>>4b. <sect1> New Page - Looks good for websites, absolutely horrible
> 
> OK, agreed. The point is that the Docwriting Howto turned out a lot
> bigger than I had originally envisaged. Some of the sections look more
> like chapters. No problem as long as we have that extra vertical space
> before <sect1>'s (and a little less before <sect2>'s, etc.)

Can be done, I'm going make some modifications to the layout etc., and 
then put a copy on my website for you to review. We'll do the final 
adjustments as we go.

>>10. <sgmltag class="starttag"> - Fixed
>>11. <sgmltag class="genentity"> - Fixed
> Class endtag too, I suppose? Anyway it's the same procedure.

Yep, those all work.

>>21. Smiley's - In professional docs???
> Sure, why not? :-)
> 
> This was a doc for fellow (aspiring) docwriters. Tone is a little more
> familiar here and there.

OK, now I just need to see if Smiley's are supported in Ventura.

> Maybe the space got eaten because Ventura thinks there should't be a
> space before a colon? This has to be fixed, because there are also
> other situations where a space precedes a colon, e.g. in a C code
> fragment or in a ratio.

I think maintaining 'spaces' is going to be the hardest part of these 
doc's. Ventura supports formatting without problems i.e. cut and paste a 
text doc into Ventura and it will keep the tabs and spacing perfectly. 
Import XML and it doesn't see the spaces because it see the doc as a XML 
file and removes all spacing, then applies formating to the tags.

Anyway, like I said, worst case scenario requires a little hand editing 
prior to final publishing.

Darcy

Re: [Firebird-docs] FbManager documentation

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

Hi Nando,

> I have received a notice saying that my mail to this list is
> moderated since I have not subscribed. I don't want to represent a
> source of more work for whoever is moderating the list,

Pavel Cisar.

> nonetheless I'm not sure what should I be subscribed to to be
> able to post freely here. I thought subscribing to the list was
> enough. :-)

I works like this: if you subscribe to the mailing list (via email or
via the list page at SF) you can mail to the list (of course) and you
can also post through the Atkin news interface. In both cases your
messages will go to the list immediately.

If you're not subscribed to the mailing list you obviously can't mail
to it (well you can, but it bounces :-)) but you *can* post through
the news interface. However, in that case your message is held until
Pavel approves it. This is necessary to stop all the spam that used to
be posted.

Maybe you posted to the newsgroup from another email account than the
one you subscribed to the mailing list with?


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] FbManager documentation

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

Hi Nando!

> Now to the subject of this message: I am in charge of writing
> documentation for a project that has the temporary name of
> "FbManager", which aims to be a simple, lightweight, cross-platform
> GUI for Firebird (think of it as a graphical isql + gbak +
> gsec). Once it's finished, we would like to have it distributed
> together with Firebird so newbies (especially under Windows) notice
> they have actually installed something. :-)

Iirc you also wrote in FFmembers that once ready, the lightweight
version would be "donated" to the Firebird project. I suppose that
means transfering the sources to the firebird project at SF? If so,
wouldn't it be better to start an fbmanager (or fowl, or whatever)
module in firebird right away and develop it there?

> Having said this, perhaps it would be a good idea to integrate such
> documentation with the Firebird documentation from the start.

If fbmanager is going to move over to Firebird: absolutely. If it
remains an SF project of its own, it all depends on what's convenient
for you guys. For the Firebird Documentation subproject it would be a
great plus to have the fbmanager docs aboard, because after all this
_is_ going to be the "official" Firebird GUI, distributed with it - or
at least with some packages.

I don't know how much you know already about the manual setup, but we
have all the documents in one DocBook <set>. One of the advantages is
that we can easily link to any other document in the set. If you would
develop the fbmanager documentation within the Firebird manual module,
we can all benefit from this.

The best approach IMO is to make a separate <book> for the fbmanager
documentation.

You can find the most recent version of the Howtos at the doc
subproject homepage:

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

The versions at vinkenoog.nl may be slightly different. I'll replace
them with links to the offcial Firebird site.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] ATTN Darcy, and all: PDF rendering

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

Hi Darcy,

A lot of things fixed already, great!

> 1. Chapter 1 - Basically, with Ventura a chapter system allows
> linking from the Table of Contents, also we can create one large
> book from multiple XML files. Even though we may have one big book,
> we could still have individual docs.

But is it mandatory that a doc (a single PDF file) have at least one
chapter? It's not the end of the world, but it looks a little silly to
have a document with just a "Chapter One" and no other chapters, even
though it is in itself complete. Oh well, if we can't change this, we
can put the Docbuilding + Docwriting Howtos in one PDF (they already
form one DocBook <book> together).

> 4a. <sect1> Vertical Space - this is a preference issue, design wise
> it is infinitely adjustable.
> 4b. <sect1> New Page - Looks good for websites, absolutely horrible
> for books, to much white space and actually that would be a chapter
> if you did a page break after every <sect1>

OK, agreed. The point is that the Docwriting Howto turned out a lot
bigger than I had originally envisaged. Some of the sections look more
like chapters. No problem as long as we have that extra vertical space
before <sect1>'s (and a little less before <sect2>'s, etc.)

> 10. <sgmltag class="starttag"> - Fixed
> 11. <sgmltag class="genentity"> - Fixed

Class endtag too, I suppose? Anyway it's the same procedure.

> 21. Smiley's - In professional docs???

Sure, why not? :-)

This was a doc for fellow (aspiring) docwriters. Tone is a little more
familiar here and there.

Maybe the space got eaten because Ventura thinks there should't be a
space before a colon? This has to be fixed, because there are also
other situations where a space precedes a colon, e.g. in a C code
fragment or in a ratio.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Ventura docs, logo's, etc.

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

Hi Darcy,

> Right now I think working out the technical details is the best
> direction. From what I'm seeing right now it shouldn't be a
> problem. The 'style' of the future Firebird docs is something we
> will all need to discuss but it would be easier if I could just make
> a change, publish the doc correctly and then collect opinions.
> Repeat until finished and 80% of the group is happy.

I agree. We just have to realize that when it comes to logos -
especially on the cover of our docs - the opinions should not only
be collected from firebird-docs, but from the entire Firebird
community (well, at least the active members/contributors).


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] FbManager documentation

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

Darcy,

D> Welcome to the Firebird Doc group!

Thank you. Been lurking here for a while, actually.

D> As for your question I think for now
D> what you can do is develop your documentation in the same style and 
D> format as the Firebird docs. See http://vinkenoog.nl/firebird/drafthowto/

I'll study the docs and come back when I have a clearer idea of what's
needed.

D> Trying to add more work to this project at the moment would not good.

I'm not sure I follow you here. I'm not porposing anyone should do
more work to please my needs. ;-) I just wonder how much should it be
integrated with the Firebird docs themselves. If the tool is going to
be distributed with Fb, chances are it will be the first approach for
new users to the software, hence the first piece of documentation
people will look for (the kind of people who actually read docs,
anyway).
I guess that using the guidelines above will facilitate integration if
needed in the future, so I'll stick to them.

D> However, absolutely feel free to contribute ideas towards documentation 
D> on this list.

Will do, thanks.
Ciao
-- 
Nando Dessena
mailto:na...@de...

Re: [Firebird-docs] FbManager documentation

[Darcy O'N. <ds...@sk...>]

Hello Nando,

Welcome to the Firebird Doc group! As for your question I think for now 
what you can do is develop your documentation in the same style and 
format as the Firebird docs. See http://vinkenoog.nl/firebird/drafthowto/

Right know we are trying to get some good database documents developed. 
Trying to add more work to this project at the moment would not good.

However, absolutely feel free to contribute ideas towards documentation 
on this list. Part of the process is developing a series of professional 
documents along with the standard docs (HTML, XML, PS, TXT) and we need 
as many opinions as possible. This information may also help you in the 
development of your own project.

Darcy O'Neil

Nando Dessena wrote:

>Hello,
>first of all, kudos to everyone for the grat work that's going on here.
>I hope I'll be able to contribute something myself.
>
>Now to the subject of this message: I am in charge of writing
>documentation for a project that has the temporary name of
>"FbManager", which aims to be a simple, lightweight, cross-platform
>GUI for Firebird (think of it as a graphical isql + gbak + gsec). Once
>it's finished, we would like to have it distributed together with
>Firebird so newbies (especially under Windows) notice they have
>actually installed something. :-)
>
>Having said this, perhaps it would be a good idea to integrate such
>documentation with the Firebird documentation from the start.
>
>Comments?
>  
>

Re: [Firebird-docs] FbManager documentation

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

BTW,
I have received a notice saying that my mail to this list is moderated
since I have not subscribed. I don't want to represent a source of more
work for whoever is moderating the list, nonetheless I'm not sure what
should I be subscribed to to be able to post freely here. I thought
subscribing to the list was enough. :-)
Clarifications welcome.
-- 
Nando Dessena
mailto:na...@de...

Re: [Firebird-docs] ATTN Darcy, and all: PDF rendering

[Darcy O'N. <ds...@sk...>]

Hello,

Well things are moving along pretty well. Here are a few remaining 
issues, some discussion might help resolve them, plus it will give you 
more background on the process.

1. Chapter 1 - Basically, with Ventura a chapter system allows linking 
from the Table of Contents, also we can create one large book from 
multiple XML files. Even though we may have one big book, we could still 
have individual docs.

2. URL Links - Can be fixed, some links will have to me manually 
identified and created but it's a small job that I will do.

3. URL Wreaking Havoc - Mostly fix, a few small adjustments but looks good.

4a. <sect1> Vertical Space  - this is a preference issue, design wise it 
is infinitely adjustable
4b. <sect1> New Page - Looks good for websites, absolutely horrible for 
books, to much white space  and actually that would be  a chapter if you 
did a page break after every <sect1>

5. Blockquotes - Fixed

6. <quote> Double Quotes - Fixed

7. Space Eater (primerif) - Fixed

8. Internal Links - Will work again might require manual intervention

9. <programlisting> White Space - This is the big issue that needs some 
more experimenting. Manual intervention worst case

10. <sgmltag class="starttag"> - Fixed

11. <sgmltag class="genentity"> - Fixed

12. <literal> - Fixed

13. <emphasis> - Fixed

14. Admonitions - Fixed - Graphics will be added later

15. Paragraphs within a listitem shouldn't get bullets - this will be an 
interesting issue as the <para> is so common but Ventura has a hard time 
working with nested tags. Should be able to fix but needs more research

16. listitems in an <orderedlist> - Fixed

17. <literallayout> - partially fixed

18. Tables - Future (can be fixed)

19. command, application, subscript etc. Fixed

20. <computeroutput> - Fixed

21. Smiley's - In professional docs???

22. Nested Lists - Fixed

I'll post a followup message detailing some future issues that may come up.

Darcy