firebird-docs — chat stuff about documentation

Re: Magnification, was Re: [Firebird-docs] Quickstart 1.5 and Classic

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

Hi Helen,

> Another comment I meant to include was regarding the default
> magnification of the PDF output.  Currently it is 168%, which is
> probably OK for people with 19" monitors but at 1024 * 768 it's
> about one-third of a page to a screen.  Can you do it at 100%?

I'm not aware that you can set a default magnification within the
document. From my experience, this is something you set in Acrobat
(Reader), which saves your last settings in the Registry.

How much of the page you see depends on a lot of things:

- Screen resolution;
- Window size;
- Navigation pane on/off, and if on: splitter position;
- Fit settings: Fit Page | Fit Width | Actual Size | Fit Visible;
- View settings: Single Page | Continuous | Side by Side;
- Explicit zoom factor (if set; "True" size == 100%)...
- Width-to-height ratio of page.

If your zoom factor is 168% @ 1024x768 (my resolution too BTW) I
suppose you have the nav pane off, and Fit Width selected. Depending
on how many rows of tool buttons there are, this shows almost half a
page. But you still may need three clicks to get to the next page if
your view setting is "Single Page" instead of "Continuous".

I think you should arrange the panes, zoomfactor etc. the way you like
it, and the next time you start Acrobat it will load those settings
again (at least in the versions I know). For online reading, "pages"
don't have much meaning. You scroll screen by screen. If you really
want an overview of the entire page you can always click the "Fit
Page" button. The letters may be too small to read then, but the only
way to solve that is to roughly halve the page height. Doing so would
be fooling ourselves because this wouldn't show more information on
the screen. In fact it would show less, because the fraction of the
page height used by headers and footers would be doubled. Also, it
would be disastrous for printing (unless you print Landscape).


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Quickstart 1.5 and Classic

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

Hi Helen,

> We need to give examples in the GSEC and isql pieces that will work
> with Classic on Win32 and its requirement to use localhost for local
> connections.

I agree. I read the recent thread in fb-support and people should
really know this. I'll take care of it.


> Also, the blue box on P 12 (?) that highlights the need to use
> double quotes around the connection string containing "Program
> Files" should really get promoted to the beginning of the Win32
> stuff.

What do you consider the beginning of the Win32 stuff? Lots of
sections have Win32 and Posix subsections. Also, doesn't the note
about double quotes also apply to Posix?


> Another point to note with the command-line examples is the need to
> begin commands with either the absolute path to the executable or
> (if run from the bin dir) with dot-slash.

Dot-slash works on Unices only. Dot-backslash works on Win32 but is
silly and unnecessary (contrary to *nix, current dir has precedence
over PATH in Windows). In the doccers' Howtos, I've sometimes done
this:

  To achieve blahblahblah, give this command:

    build    [ Windows ]
    ./build  [ Linux ]

But the QSG contains lots of command line examples and if we do this
at every occasion it will create a lot of unrest in the doc,
especially if we also add full-path examples.

What if we solve it like this:

  - Create a section "An important note about paths" early in the QSG.
    Explain about absolute and relative paths, under Windows and Posix,
    give general command-line examples for each, and warn the user
    that this is important to keep in mind during the rest of the
    guide.

  - Include a *short* (one line) reminder, including a backlink, at
    the start of each (group of) command line example(s) further on in
    the guide.

This way the guide won't be cluttered with examples that are repeated
in 4 variations all the time, but the reader also won't easily forget
the "lesson" taught.


> A point about the "Author" designation on these IBP docs.  The
> author should be "IBPhoenix Editors" not "Helen Borrie".

OK, will change that.


> I should have some UFB chapters coming along to you this week. They
> will have to be very carefully reviewed and checked.

Great! I was going to ask for it this week or so :-) Just send them,
but I'll probably start working on them *after* the upcoming Committee
meeting.


Greetings,
Paul Vinkenoog

Magnification, was Re: [Firebird-docs] Quickstart 1.5 and Classic

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

Another comment I meant to include was regarding the default magnification 
of the PDF output.  Currently it is 168%, which is probably OK for people 
with 19" monitors but at 1024 * 768 it's about one-third of a page to a 
screen.  Can you do it at 100%?

Helen

[Firebird-docs] Quickstart 1.5 and Classic

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

Paul,

We need to give examples in the GSEC and isql pieces that will work with 
Classic on Win32 and its requirement to use localhost for local connections.

Also, the blue box on P 12 (?) that highlights the need to use double 
quotes around the connection string containing "Program Files" should 
really get promoted to the beginning of the Win32 stuff.

Another point to note with the command-line examples is the need to begin 
commands with either the absolute path to the executable or (if run from 
the bin dir) with dot-slash.

A point about the "Author" designation on these IBP docs.  The author 
should be "IBPhoenix Editors" not "Helen Borrie".  I wrote the QSG on 
commission and IBP owns the copyright;  the upcoming UFB manual is 
definitely not all my work.  I picked that up from two other authors when 
it was about 40% done and I wrote it under a commission as well.

I should have some UFB chapters coming along to you this week.  They will 
have to be very carefully reviewed and checked.  There are a lot of errors 
there and some ghastly duplications of passages.  The latter I will try to 
eliminate when I convert them to XML but I'm sure to miss some...

cheers,
Helen

Re: [Firebird-docs] rtf/txt output

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

Paul,

P> Another little update, this time on txt format. I saw a question on
P> one of the XSL lists today and the answer was: first generate (single
P> file) HTML and feed that to lynx -dump. I immediately tried it out and
P> it looks *really neat* ! Easy to automate too.

will try, thanks. Since I haven't got the need to automate it yet,
Firefox + a little manual retouch has done the job so far. I'll surely
use the automation feature when FR has an actual user manual.

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

Re: [Firebird-docs] rtf/txt output

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

Hi Nando,

> is there a way to have txt or rtf output, preferably with the
> Firebird-docs build system?

Another little update, this time on txt format. I saw a question on
one of the XSL lists today and the answer was: first generate (single
file) HTML and feed that to lynx -dump. I immediately tried it out and
it looks *really neat* ! Easy to automate too.


Greetings,
Paul Vinkenoog

[Firebird-docs] Changing some target and output directory names

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

Hi all,

[ docwriters/docbuilders, please comment on this! Nothing described
[ below has been committed to CVS yet, as it affects us all.

While I was busy moving files around and creating new trees anyway
(see my other post) I also attacked some of the target names and
destination directories.


Renamed targets:

  defaulthtml -> html

    (hate to type long words and "default" adds nothing to the
    meaning. In fact it's misleading because this is not the
    default target. "help" is the default target.)

  printablehtml -> monohtml

    ("mono" is more descriptive: this target produces a single
    HTML file. Anybody who wants to *print* this while there's
    a perfectly nice PDF available is an idiot.
    This target is not actively maintained, by the way. It just
    happens to be there.)

  dist -> zip

    (this target produces zip files. *Every* target's output winds
    up in the dist tree, so it's confusing to call just one of them
    "dist")

I also added some convenience targets like cleandocs, cleanzip etc.
These perform a clean first, and then build the intended target.

Furthermore, if you type "build <oldtarget>", you get a friendly
message informing you of the new target name.


Output directories:

  html goes into dist/html (was: dist/docs/defaulthtml)
  monohtml goes into dist/monohtml (was: dist/docs/printablehtml)
  pdf goes into dist/pdf (was: dist/docs)

    (I think docs is an unnecessary extra layer. After all, docs
    are all we produce.)

  zip goes into dist/zip (was: dist)

    (I think it's "cleaner" if they go into their own subdir).


Please let me now what you think of this. We can still change the
scheme, or call the whole thing off if the majority of docwriters
wants to stick with the current setup.


Greetings,
Paul Vinkenoog

[Firebird-docs] Changes to stylesheets

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

Hi all,

[ Note: the following is somewhat technical. You don't need to read
[ this if all you want to do is write and build docs. You should read
[ it if you're interested in the workings of the transformation
[ stylesheets, or if you're planning to tweak templates yourself.


Changing the PDF rendering so that it produces a nice coverpage with
Firebird logo again added hundreds of lines to the driver stylesheet
src/docs/fo.xsl

With almost 2000 lines and dozens of templates this file was becoming
harder and harder to manage. So the time had come to organize the
custom templates business differently.

In order to understand what's coming next, you need to know:

- that the function of the XSL stylesheets is to describe how the
  DocBook XML sources should be transformed into HTML and FO (FO is
  later rendered to PDF). Each stylesheet contains a number of
  templates describing a specific transformation.

- that the src/docs/docbook tree contains the default transformation
  stylesheets from docbook.org. Anything we don't like in the DocBook
  stylesheets must be overridden in custom templates. These custom
  templates were, until now, situated in src/docs/firebirddocs.xsl
  (for HTML) and src/docs/fo.xsl (for FO, the basis for PDF). These
  so-called driver stylesheets imported the DocBook stylesheets and
  then overrode some templates and/or parameters.


What I've done now is to create a new tree src/docs/xsl for our custom
stylesheets. src/docs/xsl itself contains the driver stylesheets, who
now have the same base name as the build target they're used for.

The overriding templates however are no longer in the driver
stylesheets. They are in files that live in subdirs of src/docs/xsl.
These files and subdirs mimic (part of) the structure of
src/doc/docbook, in such a way that each overriding template is
located in a file with the same name and relative path within
src/docs/xsl as the overridden template's file has within
src/docs/docbook. The templates are effectuated by <include>
directives in the driver stylesheets.

This is the only way to keep things manageable. A great benefit is
that it makes the structure of the stylesheets system clear, and you
can immediately see where a template's original is located.


NOTE: Nothing of this has been committed to CVS yet! See also my
upcoming post about changing some target names.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] translations

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

Hola Ernesto!

> ... hope to have more time this weekend to start with the
> translation. Also, I have seen in the web that OpenOffice is able to
> use a 'filter' to output docbook format; i will check that too, it
> would be terrific to have a full-blown word processor to write
> instead of a simple xml editor!

I wouldn't do that if I were you, *especially* because you're making a
translation instead of writing a new doc. This means you don't have to
create any DocBook tags yourself - they are already there. All you
have to do is overwrite the English text that's between the tags with
its Spanish equivalent.

OO's support for DocBook is rather problematic. Importing a richly
marked-up DocBook document like the Quick Start Guide, altering it and
then exporting it again to DocBook format is asking for trouble.

If you want a wordprocessor-like environment, download XXE Standard
Edition at http://www.xmlmind.com/xmleditor/download.shtml You can
open the Quick Start Guide and replace the English text with Spanish
without worrying about the tags. Just take care with Del and Backspace
because they can delete tags as well as text characters. (Keep a copy
of the English version handy so you can check if you accidentally
removed some tags.)


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] CVS checkout pb

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

Hello Philippe,

> As cvs does not respond (time out) in anonymous mode , I try with
> my sourceforge login, but I reveive :
>
> (...) Permission denied (...)
>
> how can I correct this, is there because I am not member of the
> Firebird project ?

That's right, for ssh checkout it's not enough to have an SF login,
you must be a member of the project.

You can wait until the anon server is up again, but... since you're
going to contribute your translation to the project (at least that's
what I understand) you could also ask Helen to add you to the project.


Greetings,
Paul Vinkenoog

[Firebird-docs] CVS checkout pb

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

As cvs does not respond (time out) in anonymous mode , I try with my sourceforge
login, but I reveive :
In C:\LivreFB-CVS\docfb: C:\Program Files\TortoiseCVS\cvs.exe -z3 checkout -P manual
CVSROOT=:ext:mak...@cv...:/cvsroot/firebird

cvs checkout: Updating manual
cvs checkout: failed to create lock directory for `/cvsroot/firebird/manual'
(/cvsroot/firebird/manual/#cvs.lock): Permission denied
cvs checkout: failed to obtain dir lock in repository `/cvsroot/firebird/manual'
cvs [checkout aborted]: read lock failed - giving up

how can I correct this, is there because I am not member of the Firebird project ?

-- 
Philippe Makowski

[Firebird-docs] translations

[Ernesto C. <ec...@ci...>]

Hi
    I was too busy lately to try but simple things with docbook... hope 
to have more time this weekend to start with the translation. Also, I 
have seen in the web that OpenOffice is able to use a 'filter' to output 
docbook format; i will check that too, it would be terrific to have a 
full-blown word processor to write instead of a simple xml editor!

greetings from Argentina,

Ernesto Cullen

Re: [Firebird-docs] gsec doc

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

Norman, and all,

I wrote:

> I've now changed the stylesheet so that compact lists have no
> vertical space above them. This makes the inner list look
> better. However, now the outer list has also lost the leading
> whiteline. To get it back, wrap the outer list in a <para>.

OK, that was a dumb idea. Now you have to check every time whether a
list is wrapped in a para or not. Worse, every time you toggle a list
from normal to compact or back, you have to wrap/unwrap it so that the
spacing is OK.

So I changed that back and added something else: the stylesheet now
checks if a compact list is inside another compact list (directly or
indirectly). If so, the blank line above the inner list is omitted.
This works fine, and you don't have to think about it.

(Not committed yet.)


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Quick Start Guide 1.5

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

Hi Artur,

[ Quick Start Guide with frontpage + logo ]

> Paul, for me it's just perfect.
>
> Reason:
>
> It's simple
> It has just the info we need:
>     - our logo
>     - the title
>     - author
>
> Great!

OK, I've made it the official version now. I'll also change the
stylesheets so that from now on, all PDFs will be rendered like this.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Quick Start Guide 1.5

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

Hi Artur, and all,

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

How about this version:

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

Note: I can easily change position, size and alignment of text and
graphics, or remove the top and/or bottom lines.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] gsec doc

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

Hi Norman,

> Sorted. Both inner and outer lists are compact being as the are
> single line listitems.

Still doesn't look good because of the blank line before the inner
list. But that's not your fault: all lists have that by default, just
like paras, blockquotes, etc.

I've now changed the stylesheet so that compact lists have no vertical
space above them. This makes the inner list look better. However, now
the outer list has also lost the leading whiteline. To get it back,
wrap the outer list in a <para>.

This goes for all compact lists: as from now (or rather; as from the
moment I commit these changes), they'll have no more "automatic" empty
line above them. Wrap them in a <para> if you want it there.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Quick Start Guide 1.5

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

Paul Vinkenoog wrote:

> How about this version:
> 
>   http://www.firebirdsql.org/pdfmanual/Firebird-1.5-QuickStart-WithCover.pdf
> 
> Note: I can easily change position, size and alignment of text and
> graphics, or remove the top and/or bottom lines.

Paul, for me it's just perfect.

Reason:

It's simple
It has just the info we need:
    - our logo
    - the title
    - author

Great!

Artur

Re: [Firebird-docs] Quick Start Guide 1.5

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

Hm, this one seems to have gotten "lost in the mail":

Hi Artur, and all,

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

How about this version:

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

Note: I can easily change position, size and alignment of text and
graphics, or remove the top and/or bottom lines.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Quick Start Guide 1.5

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

Hi all,

> How about this version:
>
>   http://www.firebirdsql.org/pdfmanual/Firebird-1.5-QuickStart-WithCover.pdf

Another note: logo may look crummy on screen, but when printed it's OK.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] gsec doc

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

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

Hi Paul,

<SNIP>

> After "Coming up in this chapter", you made the outer list compact and
> left the inner list spacious. That also doesn't look good. I would
> make the inner list compact, and the outer list either compact too or
> leave it as default.
> 
> Hm, maybe I shouldn't have started about those compact lists so
> shortly before your holiday...

Sorted. Both inner and outer lists are compact being as the are single 
line listitems. The other itemi[sz]ed lists are normal - they look 
better that way as they are multi-line.

Everything in 'attempt 4' uploaded to :

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

> Well, whatever you do, have a great time!

Thanks, I'll try :o)

Cheers,
Norm.

Re: [Firebird-docs] Quick Start Guide 1.5

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

Hello Ernesto,

> I would like to do a spanish translation of the QuickStart guide.
> Do I have to do it in docbook?

You don't *have to*, but it would be ideal. Do you have experience
with DocBook? Even if you don't, translating the sources won't be
difficult: the structure and the markup are already there; all you
have to do is translate the text between the tags.

> If I do, the translation would be integrated into the doc module?

That, too, would be ideal. Do you know how to get the sources?
Documentation can be found here (HTML version):

  http://www.firebirdsql.org/manual/firebird-docwriters-info.html

and here (PDF version):

  http://www.firebirdsql.org/pdfmanual/Firebird-Docwriters-Info.pdf

And you can always get help here if you're stuck.


That said, if you really don't feel up to doing it in DocBook, you can
choose another format, and we'll see if and how we can integrate it in
the manual module.

(Or: you could do the text translation and I could put it in DocBook
format. You see... lots of possibilities here :-))


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Quick Start Guide 1.5

[Ernesto C. <ec...@ci...>]

I would like to do a spanish translation of the QuickStart guide. Do I 
have to do it in docbook? If I do, the translation would be integrated 
into the doc module?

Ernesto Cullen


A6-CMO Philippe Makowski wrote:

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

Re: [Firebird-docs] Quick Start Guide 1.5

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

Hi Artur,

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

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

I've been thinking about that too. The Table of Contents could be
moved to page 2 (or even 3), so the title page becomes some sort of
cover. Finally I didn't do it because the current version is better
for on-screen reading.

But I'll make a "front page" version this weekend, and we can see
which one we like best. It's true that for printed copies, this one
doesn't look good - it looks like a draft. Not "classy".


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Widowed section headers in PDF

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

Hi Lester,

(replying to an "old" one here)

>>   <fo:block break-before="page" font-size="12pt" ...>
>>     Using a GUI client</fo:block>
>>
>> Of course it's still a hack, but now it takes less time and we keep
>> the sources clean.

> That will do me for the time being ;)
>
> As for this not being part of DocBook DTD, on one hand I can
> understand the reasoning, BUT a header should never be the last
> thing on a page.

That's right, but such a rule can never be in the DocBook DTD because
DocBook does not (and should not) know about pages or page length.

So it's the processing software that must take care of this.

Now, producing PDF from DocBook is a two-phase process:

- First, the Saxon processor takes the DocBook XML sources and - using
  the transformation stylesheets - outputs a Formatting Objects (FO)
  file. FO files are well-formed XML; you can view and edit them with
  an XML editor.
  The FO thus produced does contain keep-with-next attributes for
  headers and some other elements.

- Then, we call Apache FOP to pick up the FO and transform it into
  PDF (no stylesheets involved here). And that's where the problem
  lies: Apache FOP hasn't fully implemented keep-with-next support
  yet, so headers may wind up on the bottom of a page.

It will probably take some time before Apache FOP supports
keep-with-next. This was posted a couple of weeks ago on the fop-user
list (note: we use version 0.20.5):

  "Any patches you submit to 0.20.5 are unlikely to be committed to
   the code base. Any work you do on FOP 1.0 dev will be highly
   welcome. However, as you've already noticed the development branch
   is not yet up to 0.20.5 so we need to do a lot more work on core
   features before it is ready for "tweaking"

   The reason for this situation is that FOP 1.0 dev is not just an
   evolution of FOP 0.20.5, but was a ground up re-write. This was
   necessary because the structure of the code in 0.20.5 did not allow
   for key features such as keep-* properties."

Bottom line: we'll have to hand-tweak the FO files (add
'break-before="page"' attributes) for some time to come.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] gsec doc

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

Hi Norman,

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

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

Yes, this GSEC Commands list is a great example of where you _don't_
want to use compact spacing, because the listitems themselves contain
empty lines. I use compact for lists with single-line items, and
*sometimes* if the items may be two or three lines. It all depends...
if I'm not sure I try both and see how I like it in the PDF.

After "Coming up in this chapter", you made the outer list compact and
left the inner list spacious. That also doesn't look good. I would
make the inner list compact, and the outer list either compact too or
leave it as default.

Hm, maybe I shouldn't have started about those compact lists so
shortly before your holiday...


> Problem is, Crete (and most other Greek Islands) tend to be somewhat
> hilly, and I get awful vertigo when travelling on the roads.

Too bad!

> I suspect I'll just have to sit in the shade reading books - and
> maybe doing a bit of drawing - for a couple of weeks.

Well, whatever you do, have a great time!


Greetings,
Paul Vinkenoog