firebird-docs — chat stuff about documentation

Re: [Firebird-docs] Navigation icons

[Lester C. <le...@ls...>]

Paul Vinkenoog wrote:

> Hmmm... this would confuse ME, I'm afraid :-)
> So the stack of books should be for the overall ToC? But then the
> floating top book would suggest you go to the top.

The way I work, each module is it's own book, with a TOC and 
Index. Each can be accessed in it's own right, so the top 
level is the library rather than some vast TOC :)

THAT I think is the problem. As the volume grows will a 
complex TOC become too cumbersome?

-- 
Lester Caine
-----------------------------
L.S.Caine Electronic Services

Re: [Firebird-docs] Navigation icons

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

Hi Lester,

>> I think the way we use the navigation icons is a bit weird: the
>> upward-pointing triangle is used to jump to the topmost T.o.C., and
>> the one that looks like a sheet of paper with lines on it is used
>> to go one level up. I think it should be the other way round,
>> especially if you look at how the other triangles are used (next -
>> previous).

> I use Contents and Index rather than Icons, and people still get
> confused. In this case we have 'Bookcase' and 'Book Contents' so
> perhaps the Up arrow should be three overlapping boxes indicating
> 'Books' and trim the size of the second to match the top book on
> the first?

Hmmm... this would confuse ME, I'm afraid :-)
So the stack of books should be for the overall ToC? But then the
floating top book would suggest you go to the top.

Actually, I think this "books" metaphore doesn't work. I think users
see the HTML version as a series of webpages (which it is), not as
books on a shelf. It's easy to get lost in this web of pages,
especially since each book/article is split up into a number of pages,
and also becuase of how the left/right triangles work:

- sometimes they take you to the previous/next section, which is
  intuitive, and you stay on the same level.
- sometimes they take you from the last page of a book to the first
  page of the next book (or vice versa), which is less intuitive and
  you also go up/down one level when this happens (because the first
  page is the "local ToC" - if you click "next" a couple of times you
  can get back there by clicking the "up one level" link).

I don't think this is Very Bad, but at least the two "upward" links
should be very clear about where they take you to. I'll try to find
more alternatives and present them on a test page so we can see what
works best.


Greetings,
Paul Vinkenoog

[Firebird-docs] Copyright

[Robert J M. <rj...@ar...>]

I think the current copyright regime for the docs looks a bit 
unmanageable. I would have something like this:

* By contributing to the documentation project, you are automatically 
granting the firebird foundation a non-exclusive, perpetual license to 
use it however they wish.
* The foundation agrees to release your contribution to the world under 
a creative commons attribution, sharealike license, and may release it 
under other licenses in future 
(http://creativecommons.org/licenses/by-sa/1.0/)
* In certain cases, you may contribute material that you do not have 
full copyright ownership over. In these cases, you must mark the 
contribution with an XML tag so that it can be identified by the 
foundation, and they will be able to abide by the license terms. The 
cases are as follows:
 - Postgresql documentation license
 - (add others)

Robert Munro

Re: [Firebird-docs] Navigation icons

[Lester C. <le...@ls...>]

Paul Vinkenoog wrote:

> I think the way we use the navigation icons is a bit weird: the
> upward-pointing triangle is used to jump to the topmost T.o.C., and
> the one that looks like a sheet of paper with lines on it is used to
> go one level up. I think it should be the other way round, especially
> if you look at how the other triangles are used (next - previous).

I use Contents and Index rather than Icons, and people still 
get confused. In this case we have 'Bookcase' and 'Book 
Contents' so perhaps the Up arrow should be three 
overlapping boxes indicating 'Books' and trim the size of 
the second to match the top book on the first?

-- 
Lester Caine
-----------------------------
L.S.Caine Electronic Services

Re: [Firebird-docs] Navigation icons (was: On air)

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

Hi,

>   http://www.firebirdsql.org/devel/doc/manual/defaulthtml/

I think the way we use the navigation icons is a bit weird: the
upward-pointing triangle is used to jump to the topmost T.o.C., and
the one that looks like a sheet of paper with lines on it is used to
go one level up. I think it should be the other way round, especially
if you look at how the other triangles are used (next - previous).

Any ideas?


Greetings,
Paul Vinkenoog

[Firebird-docs] Re: On air

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

> Well, the first four docs from our manual module are finally online.
> The direct URL is
>
>   http://www.firebirdsql.org/devel/docs/manual/defaulthtml/

Sorry, "docs" --> "doc". Correct URL is:

  http://www.firebirdsql.org/devel/doc/manual/defaulthtml/


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Minor DocBook -> PDF Improvement

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

Hi all,

> - Variablelists are rendered as (frameless) tables. The effect is
>   that the <listitem> content moves considerably to the right. If
>   you have preformatted stuff in there (which does happen) it runs
>   off the right edge of the page.
>
>   If the <term> of a <varlistentry> exceeds a certain length, in
>   the PDF it overlaps with the <listitem> text. See example in:
>     Docwriting Howto
>       :: Writing your DocBook doc
>         :: Elements we use frequently
>           :: Various inline elements

OK, this has been solved with a parameter called variablelist-as-block
or so. I'll have to spend some more time on these documentation pages
:-)


Grtz,
Paul Vinkenoog

[Firebird-docs] On air

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

Hi all,

Well, the first four docs from our manual module are finally online.
The direct URL is

  http://www.firebirdsql.org/devel/docs/manual/defaulthtml/

Links to the two user docs have been placed on the Documentation::User
Documentation page of the website. I have yet to update the
Developer's Corner::Firebird Documentation page to link to the
Docwriters' Howtos.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Missing Documentation / Howto

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

Hello Hans-G,

> I'm using Firebird (1.5 RC8, Fedora Core1, Kernel 2.6.??) since two
> weeks.  First Steps in Delphi 6 finished successfull. Now I'm
> searching for Documentations / HowTo for implementing Firebird in
> OpenOffice. I Tried it with JDBC Driver.

Darcy O'Neil just put up a document describing this:

  http://www.methyl.ca/pdf/OOoFBvp.pdf

This will also be placed on the project website soon.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Firebird 1.5 releasenotes translators

[Carmen S. <cs...@we...>]

Helen Borrie schrieb:

> Are any translators waiting/willing to translate the release notes for 
> Fb 1.5?  We already have French and Russian translations under way.  
> Spanish, Portuguese, German, Japanese, etc. please contact me or post to 
> the list, so we can coordinate and perhaps spread the load.
> 
> Sources are in Word 7 (yeah, Erk!) 67 pp.
> 

67 Pages are too much for me for translating in German (and I hope 
someone has done it in the past), but since Dezember 2003 I have 
translated the InnoSetup files to German for a project which needs 
Firebird. Maybe you're interested? I have to update from RC7 to Release, 
but that should be done soon. So if you're interested, send a short 
message to the newsgroups or personal mail to me.

I'm not a translator, only a software developer, so some translations 
could be made better...

Bye,

Carmen Smolne

Re: [Firebird-docs] Minor DocBook -> PDF Improvement

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

Hi Phil,

> In build XML, if you change...
>
> <style basedir="${src.dir}/docs"
>                      style="src/docs/docbook/html/docbook.xsl"
>                      destdir="${printablehtml.dir}"
>                      includes="firebirddocs.xml"/>
>
> ...to...
>
> <style basedir="${src.dir}/docs"
>                      style="src/docs/docbook/html/docbook.xsl"
>                      destdir="${printablehtml.dir}"
>                      includes="firebirddocs.xml">
>      <param name="title.margin.left" expression="0pc"/>
> </style>
>
> It will sort out the alignment of the all the Titles in the PDF
> output

Thanks, that looks better indeed. I've changed it. But in the pdf
target, not in the printablehtml target like you did ;-)


> We use DocBook for all our documentation, and the PDF output we get
> is more than acceptable, I could look in to see what we are doing
> different if that is of any interest?

Have you ever rendered the manual module stuff to PDF with our current
build setup? Well I suppose you have :-) I think the result really
sucks. I want to learn more about how this works, but that will take
time. So yes, if you have any ideas for improvements I would really
appreciate it. Here are some of the things I would like to see
changed:

- More spacing between sections, i.e. titles should be closer to their
  own section than to the previous one.

- Can links be made visible as such (underlined or so)?

- Generated URL links are broken. They point to "URL"s like this:
  http://url(news://news.atkin.com/sourceforge.firebird-doc)

- Widows/orphans: sometimes a section header winds up at the bottom
  of a page.

- Non-monospaced <literallayout> is justified. See example in:
    Docwriting Howto
      :: Writing your DocBook doc
        :: Elements we use frequently
          :: Program listings, screens, literal layout, and examples
            :: literallayout

- Variablelists are rendered as (frameless) tables. The effect is that
  the <listitem> content moves considerably to the right. If you have
  preformatted stuff in there (which does happen) it runs off the
  right edge of the page.

  If the <term> of a <varlistentry> exceeds a certain length, in the
  PDF it overlaps with the <listitem> text. See example in:
    Docwriting Howto
      :: Writing your DocBook doc
        :: Elements we use frequently
          :: Various inline elements

  All of this senseless bloodshed can be avoided if - just like in
  HTML - the <term> (<dt> in HTML) is placed on a line of its own, and
  the <listitem> (<dd> in HTML) on the lines *below* it, and indented
  by a couple of characters.

- Ouch! Random hyphenating in tables! Like this:
          InterB-
          ase

- An Appendix is rendered as if it were a subsection of the preceding
  section. It doesn't start on new page (ideally I would like to see
  it started on a recto page).

- Most headers are way too big, which is especially disturbing for
  "minor" sections.

- Can the PDF output be "chunked" just like the HTML? Now we can only
  produce the entire docset in one PDF. This is not reader-friendly,
  and it gets worse as more docs are added. It would be ideal if each
  <book> was in a separate PDF document. It would be even more ideal
  if a cross-document index would be generated (like with the Borland
  6.0 docset).

- It is possible to have a navigation frame generated?


If you have ideas to improve any of these points, that would be great.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Firebird :: OpenOffice.org Connectivity

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

Hello Darcy,

>> http://www.methyl.ca/pdf/OOoFBvp.pdf

> I'm going away for a week but I'll have a look when I come back.

It looks great, except that there's again one mention of "IBPheonix"
instead of IBPhoenix, in the Introduction.

Note: I can't judge the technical content as such, as I don't have
any experience with this!


Greetings,
Paul Vinkenoog

[Firebird-docs] Missing Documentation / Howto

[Hans-G. N. <ha...@no...>]

Hello NG

I'm using Firebird (1.5 RC8, Fedora Core1, Kernel 2.6.??) since two weeks.
First Steps in Delphi 6 finished successfull. Now I'm searching for
Documentations / HowTo for implementing Firebird in OpenOffice. I Tried it
with JDBC Driver.

Thanks

Re: [Firebird-docs] Postgres docs

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

Hi Robert,

> I've been meaning to suggest this for ages, but has anyone considerd
> adapting the postgres docs for firebird? The copyright would allow
> it:
> http://www.postgresql.org/docs/7.4/static/LEGALNOTICE.html

Yes, we definitely can do that - as long as we include that notice.

> It's already docbook. We could just work through it, changing
> everything to be how firebird does it.

They use DocBook SGML instead of XML, so it might need some tweaking.

> Some parts would need almost no modification at all (like most of
> the SQL), some parts would end up total rewrites, but having the
> postgres as examples would still help ensure that coverage was good
> (ie. if we answer every question that they answer then we have
> answered most of the common questions).

Good idea. I don't think we should use their docs as the basis for all
our documentation, but it could be advantageous if every docmaker, on
a per-document basis, at least had a good look at the PostgreSQL docs
to see if and how s/he could use them.

I'll include this advice in the Docwriting Howto. Thanks!


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Changes to docset structure

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

Hi Robert,

>> Until now the auto-generated HTML file names look like this:
>> bk01ch01.html, bk02ch01s08.html, etc. Very uninformative, but for
>> online browsing it's not disastrous. It IS disastrous however when
>> the docs are committed - with these names - to the 'web' CVS
>> module.

> I'm not against the change of names, but either way, the HTML should
> not be commited to CVS. The latest version (and possibly the last
> stable version) should definately be published on the web, and
> probably available to download as a tarball / zip file etc, but if
> you put it in the CVS, people will be tempted to edit it there.

You're right. I thought we had to commit the HTML version to the CVS
web module because the website was autogenerated from that module, but
I had it wrong. Yes, there is a script that will place committed stuff
on the website, but it's not necessary to do it that way. I can FTP
straight to the site.

I'm still figuring out one or two things and maybe I'll have to
contact Pavel (who's in charge of the website) again, but I expect
to put op the docs within a couple of days now.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Changes to docset structure

[Robert J M. <rj...@ar...>]

Paul Vinkenoog wrote:

>Hi all,
>
>The first docs from the manual module will soon be published (in HTML)
>on the project website. To make them look as good as possible, I've
>prepared some changes to the docset structure and the stylesheets.
>None of the changes have been committed yet. I'll list them here;
>please respond if you have any objections, or ideas for further
>enhancements:
>
>- Until now the auto-generated HTML file names look like this:
>  bk01ch01.html, bk02ch01s08.html, etc. Very uninformative, but for
>  online browsing it's not disastrous. It IS disastrous however when
>  the docs are committed - with these names - to the 'web' CVS module.
>  
>
I'm not against the change of names, but either way, the HTML should not 
be commited to CVS. The latest version (and possibly the last stable 
version) should definately be published on the web, and probably 
available to download as a tarball / zip file etc, but if you put it in 
the CVS, people will be tempted to edit it there. This would be bad. 
There's also the issue of keeping the CVS html in sync with the CVS 
docbook, which is a really silly issue, but it's bound to cause some 
problems. An editor may have a docbook XML viewing / editing program, 
but not have the ability to build the HTML if they don't have Java 
installed, for example.

Robert Munro

[Firebird-docs] Minor DocBook -> PDF Improvement

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

Hi,

In build XML, if you change...

<style basedir="${src.dir}/docs"
                         style="src/docs/docbook/html/docbook.xsl"
                         destdir="${printablehtml.dir}"
                         includes="firebirddocs.xml"/>

...to...

<style basedir="${src.dir}/docs"
                         style="src/docs/docbook/html/docbook.xsl"
                         destdir="${printablehtml.dir}"
                         includes="firebirddocs.xml">
     <param name="title.margin.left" expression="0pc"/>
</style>

It will sort out the alignment of the all the Titles in the PDF output

We use DocBook for all our documentation, and the PDF output we get is more 
than acceptable, I could look in to see what we are doing different if that 
is of any interest?

Phil

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

Re: [Firebird-docs] Firebird :: OpenOffice.org Connectivity

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

Hi Darcy,

> Here's another document detailing how to get OpenOffice.org
> connected to a Firebird database using Jay Bird.
>
> Take a look and let me know if you see any errors. It's also
> licensed under the GNU Free Document License, so add it or publish
> it to wherever you feel it will be most helpful to the community.
>
> http://www.methyl.ca/pdf/OOoFBvp.pdf

I'm going away for a week but I'll have a look when I come back.

> p.s. any suggestions for the next document?

As a general advice: take a good look at www.ibphoenix.com and
www.firebirdsql.org to see wat kind of documentation is already
available. From what's "missing", choose a subject you're good at
and would like to write about.

BTW: have you ever considered writing DocBook XML docs? This is the
standard we use in the manual module. If you're interested, look at
http://vinkenoog.nl/firebird/docset/firebird-docwriters-info.html
(temporary location) to read more about it.


See you later,
Paul Vinkenoog

Re: [Firebird-docs] Changes to docset structure

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

Hello all,

> The first docs from the manual module will soon be published (in
> HTML) on the project website. To make them look as good as possible,
> I've prepared some changes to the docset structure and the
> stylesheets.  None of the changes have been committed yet.

Just committed the changes to the manual module. I'll be away for a
week now; when I'm back I'll place the HTML docs on the website.


Greetings,
Paul Vinkenoog

[Firebird-docs] Firebird :: OpenOffice.org Connectivity

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

Here's another document detailing how to get OpenOffice.org connected to 
a Firebird database using Jay Bird.

Take a look and let me know if you see any errors. It's also licensed 
under the GNU Free Document License, so add it or publish it to wherever 
you feel it will be most helpful to the community.

http://www.methyl.ca/pdf/OOoFBvp.pdf

The Dreamweaver / PHP / Firebird doc will be updated soon. Also, I'll be 
checking these out with the latest Firebird 1.5  to make sure they are 
compatible.

Darcy

p.s. any suggestions for the next document?

Re: [Firebird-docs] Changes to docset structure

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

Hi all,

> The first docs from the manual module will soon be published (in
> HTML) on the project website. To make them look as good as possible,
> I've prepared some changes (...)

> I'll put up the complete HTML version on a temp location in an hour
> or so, so everybody can see what's in there and how it's going to
> look. Will post the URL here.


  http://vinkenoog.nl/firebird/docset/


Good night,
Paul

Re: [Firebird-docs] Changes to docset structure

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

Hello Michael,

> A little status report from me: I have finished my tests yesterday,
> and have made some drafts on how to organize the SQL reference I
> intend to write. I will work some on it in the next days, and hope
> to be able to present you an initial version around friday.

That's good news - but I probably won't be able to read your message
until next Friday (5 March) because I'm leaving for a short holiday
this Friday afternoon.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Changes to docset structure

[Michael G. <gl...@ok...>]

Hi all,

> The first docs from the manual module will soon be published (in HTML)
> on the project website. To make them look as good as possible, I've
> prepared some changes to the docset structure and the stylesheets.
> None of the changes have been committed yet. I'll list them here;
> please respond if you have any objections, or ideas for further
> enhancements:

sounds all nice to me :) A little status report from me: I have finished 
my tests yesterday, and have made some drafts on how to organize the SQL 
reference I intend to write. I will work some on it in the next days, 
and hope to be able to present you an initial version around friday.

Michael

[Firebird-docs] Changes to docset structure

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

Hi all,

The first docs from the manual module will soon be published (in HTML)
on the project website. To make them look as good as possible, I've
prepared some changes to the docset structure and the stylesheets.
None of the changes have been committed yet. I'll list them here;
please respond if you have any objections, or ideas for further
enhancements:

- Until now the auto-generated HTML file names look like this:
  bk01ch01.html, bk02ch01s08.html, etc. Very uninformative, but for
  online browsing it's not disastrous. It IS disastrous however when
  the docs are committed - with these names - to the 'web' CVS module.
  For as we maintain the docs and add new ones, the order may be
  changed, sections inserted etc... this will cause lots of files to
  get different names, their previous names now being assigned to other
  files. That is *very* CVS-unfriendly. It screws up diffing, annotating,
  viewing file histories, and it also eats up more space on the server.

  Solution: changed a certain param in firebirddocs.xsl so the files
  take their names from the ids of the chapters or sections they
  contain. These ids will stay the same for a long time, often forever.
  A additional advantage is that as a human being, you can now also
  see what a file is about: migration-mssql-intro.html, docwritehowto-
  docbook-authoring-tools.html, ibfbcoex-running-ib-fb-together.html...

- Marcelo Lopez Ruiz' Migration Guide was inserted as a <book> with
  only one <chapter> which in turn had many <section>s. This looked
  silly, particularly in the TOC, so I merged the <book> and <chapter>
  layers into one <article> layer.
  I also changed the nested <section> tags to <sect1>, <sect2> tags to
  give the CSS finetuning entries a better grip on it.

- I gave the <set> and the <book>s ids, and gave the <set> a <title>
  ("Firebird Documentation Set").

- Commented out the Preface from the build, because half of the links
  it contains are broken by now, and the information as such (how to
  set up CVS - how to produce a DocBook file) can now be found in the
  more complete Docbuilding and Docwriting Howtos. Furthermore I think
  this information does not belong in a user doc - it's only for
  docwriters.

- Also commented out the Firebird intro. This document consists of two
  very short sections; together, they contain very little info, and
  part of it is not suited for normal users. The other part could
  serve as a basis for a nice introduction to Firebird though.

  Note: both the Preface and the Intro are still in our manual tree of
  course! We can pick them up any time we want. The commenting-out
  only means that they will not be included in the HTML version *now*.

- Moved Marcelo's Migration Guide (see above) into the Firebird
  Database Documentation book. Added a new doc: "Coexistence of
  Firebird and InterBase" to that same book.

- Changed some other (mostly cosmetical) things in the stylesheets.


I'll put up the complete HTML version on a temp location in an hour or
so, so everybody can see what's in there and how it's going to look.
Will post the URL here.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Firebird :: PHP :: Dreamweaver :: Phakt

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

Hi Darcy,

> I've created a document for using Firebird with Dreamweaver, PHP,
> Apache& Phakt. (...)

> http://www.methyl.ca/pdf/DMX-PHP-FB.pdf

It looks great! It would ne nice to put it on the project website
too. Only a couple of characters seem to have fallen off:

- Under "Server Side Requirements", there's no closing ')' after
  Slackware.
- Under "Client Side Requirements", it says 'hakt' instead of 'Phakt'
- Again under "Server...", you use a trailing slash after the
  firebirdsql URL. This doesn't hurt a bit of course, but you don't
  do it with the other URLs. So while I'm nitpicking anyway... ;-)
- Oh, my (just notice this now): On page 2 under Resources, you
  mention IBPheonix and www.ibpeonix.com. Should be Phoenix.


Greetings,
Paul Vinkenoog