firebird-docs — chat stuff about documentation

Re: [Firebird-docs] Re: important, tip, note, warning and caution rendering in PDF

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

Hi Carlos,

> Done looks nice, i have updated the PDF
> of the protocol documentation into the CVS :)

It looks good, especially if you consider how disastrous our
PDF rendering was only 2 weeks ago! At last we're on the right
track :-)


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Re: important, tip, note, warning and caution rendering in PDF

[<car...@te...>]

Hello:

>   rebuild the protocol document later today,

Done looks nice, i have updated the PDF
of the protocol documentation into the CVS :)




--
Best regards

Carlos Guzmán Álvarez
Vigo-Spain

Re: [Firebird-docs] Re: important, tip, note, warning and caution rendering in PDF

[<car...@te...>]

Hello:

>...except that you sneakily merged two templates into one, and in
>doing so disabled graphical admonitions ;-)
>
hehe ... :) ... i was interested only in the non-graphical ones :)

>I think the colored background is a good idea, but only for
>non-graphical admonitions. (If there's an icon next to the admoniton
>the background coloring may ruin the appearance, and the icon already
>attracts the attention anyway.)
>
Agree.

>If you don't want the padding, you also don't need the table.
>
I will modify my local copy and rebuild the protocol document later today,
thanks very much for your help (i have no experience with DocBook and
XSL :) but looks nice)





--
Best regards

Carlos Guzmán Álvarez
Vigo-Spain

Re: [Firebird-docs] Re: important, tip, note, warning and caution rendering in PDF

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

Hi Carlos,

> Hope the above one is more correct, it's the same as the docbook
> stylesheet one

...except that you sneakily merged two templates into one, and in
doing so disabled graphical admonitions ;-)

> but adding the background color:
>
>   <xsl:template match="note|important|warning|caution|tip">
>       <xsl:param name="node" select="."/>
>       <xsl:variable name="id">
>           <xsl:call-template name="object.id"/>
>       </xsl:variable>
>       <xsl:variable name="color">
>           <xsl:choose>
>               <xsl:when test="name($node)='note'">F0FFFF</xsl:when>
>               <xsl:when test="name($node)='warning'">FFE4E1</xsl:when>

<snip>

I think the colored background is a good idea, but only for
non-graphical admonitions. (If there's an icon next to the admoniton
the background coloring may ruin the appearance, and the icon already
attracts the attention anyway.)

So in my copy, I overrode the nongraphical.admonition template:

  <xsl:template name="nongraphical.admonition">
    <xsl:variable name="id">
      <xsl:call-template name="object.id"/>
    </xsl:variable>

    <xsl:variable name="color">
      <xsl:choose>
        <xsl:when test="name()='note'">F0FFFF</xsl:when>
        <xsl:when test="name()='warning'">FFE4E1</xsl:when>
        <xsl:when test="name()='caution'">FFE4E1</xsl:when>
        <xsl:when test="name()='tip'">F0FFFF</xsl:when>
        <xsl:when test="name()='important'">FFE4E1</xsl:when>
      </xsl:choose>
    </xsl:variable>

    <fo:block space-before.minimum="0.8em"
              space-before.optimum="1em"
              space-before.maximum="1.2em"
              background-color="#{$color}"
              id="{$id}">
      <fo:table>
        <fo:table-column/>
        <fo:table-body>
          <fo:table-row>
            <fo:table-cell padding="6pt">

              <xsl:if test="$admon.textlabel != 0 or title">
                <fo:block keep-with-next='always'
                          xsl:use-attribute-sets="admonition.title.properties">
                   <xsl:apply-templates select="." mode="object.title.markup"/>
                </fo:block>
              </xsl:if>

              <fo:block xsl:use-attribute-sets="admonition.properties">
                <xsl:apply-templates/>
              </fo:block>

            </fo:table-cell>
          </fo:table-row>
        </fo:table-body>
      </fo:table>
    </fo:block>
  </xsl:template>


I didn't add extra indentation because with a bg color I find it nicer
if the admonition aligns with the surrounding blocks.

The table is necessary because of the padding. If you don't use a
table, the text aligns with the surroundings but the padding extends
outwards, which I find ugly.

Now you *can* compensate the padding with margins or indents, but
alas... if you do that, admonitions belonging to already-indented
blocks like listitems etc., will then OUTdent, because margins and
indents turn out not to be relative to the block, but to the content
region. (Maybe there's a simple way around this, but I don't know
it...)

If you don't want the padding, you also don't need the table.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] IB6 vs. FB synopsis

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

Hi Boris,

> I've been running IB6 for quite a while now I'd like to switch
> to FB.

Good idea! :-)

> Where can I find a compact listing of changes made to FB against
> IB6?  Maybe an appendix to the IB-Doc, showing the LIMIT-extension
> made to the SELECT-statement etc.

The best place to find this information is the Release Notes document
of your downloaded Firebird package. Also read any WhatsNew* documents
if they are there.

The QuickStart Guide is very useful too, but this doesn't concentrate
on the new features; it's a general basic tutorial. If it's not in
your download, you can get it here:

  http://www.ibphoenix.com/downloads/qsg.pdf


Good luck!
Paul Vinkenoog

Re: [Firebird-docs] IB6 vs. FB synopsis

[Aage J. <aag...@on...>]

Boris Schlüszler wrote:
> Hi!
> 
> I've been running IB6 for quite a while now I'd like to switch to FB.
> Where can I find a compact listing of changes made to FB against IB6?
> Maybe an appendix to the IB-Doc, showing the LIMIT-extension made to the
> SELECT-statement etc.


(Please use the support forum)

You can read about the changes in the ReleaseNotes for Fb/1.0 _plus_ 
Releaseotes for Fb/1.5.


-- 
Aage J.

[Firebird-docs] IB6 vs. FB synopsis

[Boris <bo...@ts...>]

Hi!

I've been running IB6 for quite a while now I'd like to switch to FB.
Where can I find a compact listing of changes made to FB against IB6?
Maybe an appendix to the IB-Doc, showing the LIMIT-extension made to the
SELECT-statement etc.

Regards,

[Firebird-docs] Re: important, tip, note, warning and caution rendering in PDF

[<car...@te...>]

Hello:

Hope the above one is more correct, it's
the same as the docbook stylesheet one
but adding the background color:

    <xsl:template match="note|important|warning|caution|tip">
        <xsl:param name="node" select="."/>
        <xsl:variable name="id">
            <xsl:call-template name="object.id"/>
        </xsl:variable>
        <xsl:variable name="color">
            <xsl:choose>
                <xsl:when test="name($node)='note'">F0FFFF</xsl:when>
                <xsl:when test="name($node)='warning'">FFE4E1</xsl:when>
                <xsl:when test="name($node)='caution'">FFE4E1</xsl:when>
                <xsl:when test="name($node)='tip'">F0FFFF</xsl:when>
                <xsl:when test="name($node)='important'">FFE4E1</xsl:when>
            </xsl:choose>
        </xsl:variable>

        <fo:block space-before.minimum="0.8em"
                    space-before.optimum="1em"
                    space-before.maximum="1.2em"
                    start-indent="0.25in"
                    end-indent="0.25in"
                    background-color="#{$color}"
                    id="{$id}">
            <xsl:if test="$admon.textlabel != 0 or title">
                <fo:block keep-with-next='always'
                            
xsl:use-attribute-sets="admonition.title.properties">
                    <xsl:apply-templates select="." 
mode="object.title.markup"/>
                </fo:block>
            </xsl:if>

            <fo:block xsl:use-attribute-sets="admonition.properties">
                <xsl:apply-templates/>
            </fo:block>
        </fo:block>
    </xsl:template>





--
Best regards

Carlos Guzmán Álvarez
Vigo-Spain

[Firebird-docs] important, tip, note, warning and caution rendering in PDF

[<car...@te...>]

Hello:

I have modified the fo.xsl file adding a modified template
(based on the docbook one) for note, important, warning,
caution and tip elements for render them with a background
color, i haven't done it in the best way but seems
to work ;) ,  it's of interest here it's:

    <xsl:template match="note|important|warning|caution|tip">
        <xsl:param name="node" select="."/>
        <xsl:variable name="color">
            <xsl:choose>
                <xsl:when test="name($node)='note'">F0FFFF</xsl:when>
                <xsl:when test="name($node)='warning'">FFE4E1</xsl:when>
                <xsl:when test="name($node)='caution'">FFE4E1</xsl:when>
                <xsl:when test="name($node)='tip'">F0FFFF</xsl:when>
                <xsl:when test="name($node)='important'">FFE4E1</xsl:when>
            </xsl:choose>
        </xsl:variable>
        <fo:block background-color="#{$color}">
            <xsl:call-template name="nongraphical.admonition"/>
        </fo:block>
    </xsl:template>




Comments are welcome !! :D



--
Best regards

Carlos Guzmán Álvarez
Vigo-Spain

[Firebird-docs] Things to improve

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

Hi all,

Quoting from my "Major improvements in PDF" message:

> Things still to be improved/solved:
>
> - Internal links to elements at chapter/article level or
>   above don't work.

This is solved in the new version of the DocBook stylesheets.

> - Section headers can still wind up at the bottom of a page,
>   with the section text starting at the next.
> - Widows/orphans.

These two are due to Apache FOP not having fully implemented the
"keep-with-next" attribute. So we'll have to live with those until
it's implemented, or until we find a better free FO processor - which
is not likely - or a PDF postprocessor that can fix it.

The new stylesheets also fix a problem I mentioned in the Docwriting
Howto: non-monospaced <literallayout> was badly rendered (as fully
justified lines, or worse).

I'm planning to commit the new stylesheets to CVS in a couple of
days. First I'm going to try them out some more. They do introduce
some minor new inconveniences but "nothing a couple of whiskey-and-
sodas couldn't fix".


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] SQL2003 Update

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

Hi Lester,

> The problem of cause is that what the list hides at present is where
> a word is actually used differently between the various columns. The
> SQL ones are on the whole consistent, but do not necessarily match
> the Firebird, MySQL or PostgeSQL use :)

> That is why I'm trying to populate the secondary pages and identify
> the uses. The simple glossary is not going to be useful unless the
> context of a words use is established.

If the use of a word is *somewhat* different, I don't think it's a
problem. A glossary is just to get an idea of what a word means "by
and large".

But if it's used for two completely different actions, yes, then it
needs explanation. Either within a single definiton, or by linking to
different definitions.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] SQL2003 Update

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

Paul Vinkenoog wrote:

> Hi Lester,
> 
> 
>>http://home.lsces.co.uk/TikiPro/wiki/index.php?page=Firebird+Words+Reference
>>
>>has been updated with the SQL2003 Reserved and NonReserved words and
>>a few mistakes in SQL99 have been corrected.
> 
> This thing is getting bigger and bigger!
> 
> Just curious: is there a difference between "NRes" and an empty cell?
> Iow, do empty cells reflect a NULL state wrt those particular data
> items in your brain? ;-)

Res = Reserved Word
NRes = Non-reserved word

Blank means in essence - not defined.
So what we need to be aiming for is to fill in the Firebird list to 
match the SQL2003 list. Any Res or NRes in the Firebird list, but not in 
the SQL2003 standard are 'extras'.

The problem of cause is that what the list hides at present is where a 
word is actually used differently between the various columns. The SQL 
ones are on the whole consistent, but do not necessarily match the 
Firebird, MySQL or PostgeSQL use :)

That is why I'm trying to populate the secondary pages and identify the 
uses. The simple glossary is not going to be useful unless the context 
of a words use is established.

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

Re: [Firebird-docs] SQL2003 Update

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

Hi Lester,

> http://home.lsces.co.uk/TikiPro/wiki/index.php?page=Firebird+Words+Reference
>
> has been updated with the SQL2003 Reserved and NonReserved words and
> a few mistakes in SQL99 have been corrected.

This thing is getting bigger and bigger!

Just curious: is there a difference between "NRes" and an empty cell?
Iow, do empty cells reflect a NULL state wrt those particular data
items in your brain? ;-)


Greetings,
Paul Vinkenoog

[Firebird-docs] Major improvements in PDF rendering

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

Hello all,

We've finally made a breakthrough in the PDF rendering. A newly-
created driver stylesheet (fo.xsl) overrides a number of things in
the default transformation stylesheets, solving our three major
problems:

- All URL links were broken.
- Bookmarks weren't generated.
- Headers were often too big, and crammed tight between sections
  with no extra space above them.

There's still plenty of room for improvement, but at least the PDF
docs are publishable now. You can find them via this page:

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


Things still to be improved/solved:

- Internal links to elements at chapter/article level or above
  don't work.
- Section headers can still wind up at the bottom of a page, with
  the section text starting at the next.
- Widows/orphans.
- URL hyphenating. Not that I'm fond of this, but it may prevent
  ugly justification in short paragraphs containing long URLs.


Changes to the stylesheets etc. have been committed to CVS. (Note: at
this moment, anon CVS still gives an "old" fo.xsl of around 3K - the
right one is around 16K).


Greetings,
Paul Vinkenoog

[Firebird-docs] SQL2003 Update

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

http://home.lsces.co.uk/TikiPro/wiki/index.php?page=Firebird+Words+Reference

has been updated with the SQL2003 Reserved and NonReserved words and a 
few mistakes in SQL99 have been corrected.

Interesting bit is that all of the functions that were Reserved words in 
SQL92, and Non-Reserved in SQL99 are now back to Reserved words in SQL2003.

Started a few of the cross reference pages, but that is going to take 
more time :)

I'll look at slipping this into the XML version as well.

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

Re: [Firebird-docs] segmentedlists and lousy PDFs (Help!)

[<car...@te...>]

Hello:

>Um... did you read the rest of my message? It breaks the PDF build.
>
Ooopps sorry :)





--
Best regards

Carlos Guzmán Álvarez
Vigo-Spain

Re: [Firebird-docs] segmentedlists and lousy PDFs (Help!)

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

Hi Carlos,

>> To get the right (table) format in the PDF too, you can add this
>> instruction (at the same place as the <?dbhtml...> line):
>>
>>   <?dbfo list-presentation="table"?>
>>
>> Or we can add this line to build.xml, PDF target:
>>
>>   <param name="segmentedlist.as.table" expression="1"/>
>>
>  I will test it, thanks :)

Um... did you read the rest of my message? It breaks the PDF build.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] segmentedlists and lousy PDFs (Help!)

[<car...@te...>]

Hello:

>By the way, using <constant> directly within a <listitem> is not valid
>DocBook. The current version of our build tools doesn't have a problem
>with it though. Valid is e.g.
>
>  <listitem>
>    <para><constant>isc_info_sql_select</constant></para>
>  </listitem>
>
I will fix them thanks :)

>No, that one is the stylesheet for producing the defaulthtml target.
>
Ok.

>PDF is produced in wto steps: first, a Formatting Objects file
>firebirddocs.fo is produced. The master stylesheet used for this
>is manual/src/docs/docbook/fo/docbook.xsl
>
>Then, a FOP (Formatting Objects Processor) turns the .fo into a .pdf
>
>To get the right (table) format in the PDF too, you can add this
>instruction (at the same place as the <?dbhtml...> line):
>
>  <?dbfo list-presentation="table"?>
>
>Or we can add this line to build.xml, PDF target:
>
>  <param name="segmentedlist.as.table" expression="1"/>
>
I will test it, thanks :)





--
Best regards

Carlos Guzmán Álvarez
Vigo-Spain

Re: [Firebird-docs] Checking format for gbak doc

[Frederic G. M. <fg...@os...>]

OK. XXE made me think every document had a "book" root. I'll change this.

"Paul Vinkenoog" <pa...@vi...> a écrit dans le message de
news:Pin...@s4......
> Hello Fr=E9d=E9ric,
>
> > I've made a first attempt at the docbook format with XXE. Can
> > someone check the first page to tell me if the use I make of the
> > various elements is in line with typical FB custom for docs ?
> >
> > It is available at:
> >     http://radbase.riff.org/pub/gbakFormat.xml
>
> Looks very good! One thing though: you have chosen for a <book>
> containing <chapter>s. But unless it's going to be very big indeed,
> it's better to make an <article> containing <sect1> etc.
>
> Greetings,
> Paul Vinkenoog
>
>
>
> -------------------------------------------------------
> This SF.Net email is sponsored by the new InstallShield X.
> From Windows to Linux, servers to mobile, InstallShield X is the one
> installation-authoring solution that does it all. Learn more and
> evaluate today! http://www.installshield.com/Dev2Dev/0504
> _______________________________________________
> Firebird-docs mailing list
> Fir...@li...
> https://lists.sourceforge.net/lists/listinfo/firebird-docs
>

Re: [Firebird-docs] Checking format for gbak doc

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

Hello Fr=E9d=E9ric,

> I've made a first attempt at the docbook format with XXE. Can
> someone check the first page to tell me if the use I make of the
> various elements is in line with typical FB custom for docs ?
>
> It is available at:
>     http://radbase.riff.org/pub/gbakFormat.xml

Looks very good! One thing though: you have chosen for a <book>
containing <chapter>s. But unless it's going to be very big indeed,
it's better to make an <article> containing <sect1> etc.

Greetings,
Paul Vinkenoog

[Firebird-docs] segmentedlists and lousy PDFs (Help!)

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

Hi Carlos,

> The  new  draft  has  fixed  the latest  issues  you  have  reported
> (thanks!!)
>
> As a test it includes a segmented list, in the Databases/Attachment
> section, that looks pretty well in the HTML output and really bad in
> the PDF :), but it's a good test in any case :)

One "problem" with a tabular segmentedlist is that you can't get rid
of the table headers, but in this case they are very useful. In fact
they are so useful that you could drop the list title.

The trouble with the PDF is that the segmentedlist is rendered in list
format. Which is totally stupid here :-(

By the way, using <constant> directly within a <listitem> is not valid
DocBook. The current version of our build tools doesn't have a problem
with it though. Valid is e.g.

  <listitem>
    <para><constant>isc_info_sql_select</constant></para>
  </listitem>


> What i need to review for change the PDF output, the
> firebirddocs.xsl ??

No, that one is the stylesheet for producing the defaulthtml target.

PDF is produced in wto steps: first, a Formatting Objects file
firebirddocs.fo is produced. The master stylesheet used for this
is manual/src/docs/docbook/fo/docbook.xsl

Then, a FOP (Formatting Objects Processor) turns the .fo into a .pdf

To get the right (table) format in the PDF too, you can add this
instruction (at the same place as the <?dbhtml...> line):

  <?dbfo list-presentation="table"?>

Or we can add this line to build.xml, PDF target:

  <param name="segmentedlist.as.table" expression="1"/>

Unfortunately, in both cases the .fo is built correctly but the PDF
rendering breaks at that point.

This crummy PDF production is really becoming a problem. I'll invest
some time in finding out if it can be fixed. Maybe the newer DocBook
versions do better on this point. Or maybe there are other
alternatives.

If anybody has experience with this: help and advice is much
appreciated!


Greetings,
Paul Vinkenoog

[Firebird-docs] Checking format for gbak doc

[FGM <fg...@os...>]

Hello,

I've made a first attempt at the docbook format with XXE. Can someone check
the first page to tell me if the use I make of the various elements is in
line with typical FB custom for docs ?

It is available at:
    http://radbase.riff.org/pub/gbakFormat.xml

Of course, it is just a first page: don't expect it to document the format
already !

Frederic

Re: [Firebird-docs] Where to start?

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

Hi Armando,

> I think the to-do list is what follows, but I'm not sure:
>
>> Why not take a look at PostgreSQL:
>> http://www.postgresql.org/docs/7.3/static/index.html
>> - A tutorial, great for newbies with databases in general 
>>   and Firebird in particular
>> - From the users point of view, DML, DDL
>> - From the admin point of view, setup, optimize, deploy
>> - Programmer Guide, API
>> - SQL Reference
>> - Developer Guide, also with infos for people willing to 
>>   contribute to Fb

> Please confirm if I got the right one.

Yes, that and a little list I posted earlier in that thread:

> - a DDL guide
> - a DML guide
> - an SQL reference
> - an API guide
> - a Programmer's Guide
> - ...
> - ...

But this was never worked out to something formal. Wouldn't have made
much sense, too, because at the time there was only Tilo and me and a
little later Tilo announced that he didn't have time to write docs
(he's active in the Marathon Project).

> Strangely enough, one of my main concerns about Firebird Docs is 
> beginner docs as I find hard to persuade people to try it without 
> good documentation for beginners.

Maybe you would like to work on updating the Quickstart Guide then?
And later on, (pieces of) Using Firebird.

But feel free to come up with something else.

>> - One existing project that could use input is the Glossary.
>
> Sorry about this Paul, but I'll try to give some help outside the 
> glossary project. That is not really the kind of area I would work 
> on (I hate glossaries and glossaries hate me in return).

OK, stay away from the Glossary - we don't want any bloodshed :-)


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] OOo and DocBook

[<car...@te...>]

Hello:

>Carlos is sending me revisions now and then (produced with OO) and
>they are correct.
>
I'm not using OpenOffice on the revisions,
i used it only on the first one, for all other i'm using a text editor :)


--
Best regards

Carlos Guzmán Álvarez
Vigo-Spain

[Firebird-docs] OOo and DocBook (was: A how-to on...)

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

Hi Helen,

> You also need to get the three XSLT files.  Actually, this link is
> better to cover fully what you need to do to activate XML filtering
> (as I discovered yesterday after several frustrating hours trying to
> make OO.o 1.1.1 behave as described in the UserGuide.html page).
> It's incredible that they don't have these two pieces together in
> one document!!

> Start here and use method 1:
> http://xml.openoffice.org/xmerge/docbook/

Thanks for finding this out. I did visit that page before but decided
not to follow the instructions because it was for Beta/RC versions.

Installed that stuff now. Yes, it works, but (for me) it's very
counterintuitive. Too used to XXE I guess. Also, if I import and
re-export, or if I make a simple new DocBook file, it sometimes
exports broken DocBook XML.

BTW, to everybody who's going to follow the instructions on that
webpage: under "Creating a new DocBook filter" they swapped the import
and export stylesheets. The correct choices are:
  docbooktosoff* for import
  sofftodocbook* for export


> Paul, I'm working on the converter for the Framemaker xml and I
> really don't think it will be rocket science to write another one
> for reprocessing the OO docbook output, if it's needed.

OK, but let's first see if it's needed :-)
Carlos is sending me revisions now and then (produced with OO) and
they are correct.


Greetings,
Paul Vinkenoog