firebird-docs — chat stuff about documentation

Re: [Firebird-docs] Quick Start Guide. Thoughts

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

Hi Gregory,

> IMO, "the field where the command line is" is calling "Target" (the
> label of this field) (6.2.2). May so it will be easier for reader to
> understand what about the point is?

What language version do you have? On my Dutch Win2K, it's labeled
(translated to English) "Path to executable file".

Which is not entirely correct, because the command line contains more
than that; it also contains arguments.

I think "field where the command line is" or "field containing the
command line" is a good description, given the fact that different
languages may use labels with different meanings.

> Why *NIX OS are called Posix?

> AFAIK OS/2, Windows NT/200x/XP are also POSIX-compatible. But as I
> understand in the Guide we do not talk about them using term
> "Posix".

I don't know about OS/2, but the WinNT family only has some very, very
limited POSIX compliant stuff built in.

That said, maybe it's better to talk about "Unices" or "Linux and the
like" instead of Posix. After all, the examples differ mostly in path
formats, and Posix doesn't say that paths must be of the form
"/this/is/a/path". A system can be Posix conformant and still have
Windows type paths (except that they *must* be case-sensitive).


Greetings,
Paul Vinkenoog

[Firebird-docs] Russian (was: Firebird 1.5 Quick Start Guide)

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

Hi Gregory,

> Are you talking (finally) about translating the behavior of
> <important>, <note>, <warning> elements/tags?

I wasn't, but these translations are already there. If you include the
attribute

  lang="ru"

in your top-level element, all built-in terms will appear in Russian:
"Contents" becomes Sodyerzhanyie, "Note" becomes Zamyechanyie,
"Important" Bazhno, etc. (all in Cyrillic of course).

Only problem is that in the PDF body, the font doesn't seem to contain
Cyrillic characters; they are all replaced with pound signs (#). This
has to be fixed.

In the outline (the navigation frame on the left) the Cyrillic appears
OK. The HTML is OK too.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] froid@email.it or froid@froid.it

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

At 10:59 AM 15/10/2004 +0200, you wrote:
>Gregory,
>
>GS> I've got a message from hos...@em... for each message
>GS> that I send to this list. The message is on Italian(?), but AFAIU
>GS> it says that fr...@em... is unreachable (or smth similar) and
>GS> advice me to try to use fr...@fr... instead.
>
>...and I thought it was just me!

Fixed;  now he can send mail but can't receive it. ---H.

>--
>Nando                            mailto:na...@de...
>
>
>
>-------------------------------------------------------
>This SF.net email is sponsored by: IT Product Guide on ITManagersJournal
>Use IT products in your business? Tell us what you think of them. Give us
>Your Opinions, Get Free ThinkGeek Gift Certificates! Click to find out more
>http://productguide.itmanagersjournal.com/guidepromo.tmpl
>_______________________________________________
>Firebird-docs mailing list
>Fir...@li...
>https://lists.sourceforge.net/lists/listinfo/firebird-docs

Re: [Firebird-docs] froid@email.it or froid@froid.it

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

Gregory,

GS> I've got a message from hos...@em... for each message
GS> that I send to this list. The message is on Italian(?), but AFAIU
GS> it says that fr...@em... is unreachable (or smth similar) and
GS> advice me to try to use fr...@fr... instead.

...and I thought it was just me!
-- 
Nando                            mailto:na...@de...

[Firebird-docs] froid@email.it or froid@froid.it

[Gregory S. <sap...@ya...>]

Sorry for OT

Who is mister fr...@em... (fr...@fr...)?
I've got a message from hos...@em... for each message that I send to this list. The message is on Italian(?), but AFAIU it says that fr...@em... is unreachable (or smth similar) and advice me to try to use fr...@fr... instead.

-- 
Gregory Sapunkov
what a wonderful world...

Re: [Firebird-docs] Firebird 1.5 Quick Start Guide

[Gregory S. <sap...@ya...>]

>Yes. It's not so principle for me now (XMLmind is working, HTML is
>building - it's enough to start... later I will return to this, IMO this >problem of win98, I'll try to build on win2000 later)

Ok, on win2000 everything is fine.

-- 
Gregory Sapunkov
what a wonderful world...

[Firebird-docs] Quick Start Guide. Thoughts

[Gregory S. <sap...@ya...>]

Hi,

IMO, "the field where the command line is" is calling "Target" (the label of this field) (6.2.2). May so it will be easier for reader to understand what about the point is?

Why *NIX OS are called Posix?
AFAIK OS/2, Windows NT/200x/XP are also POSIX-compatible. But as I understand in the Guide we do not talk about them using term "Posix".

p.s. Maybe I'm wrong? (-:

-- 
Gregory Sapunkov
what a wonderful world...

Re: [Firebird-docs] Firebird 1.5 Quick Start Guide

[Gregory S. <sap...@ya...>]

Paul,

>> I've read Paul's guide for doc writers, checkout manual module,
>> install XMLmind standard edition.  I'm using Win98 box and for now I
>> couldn't build all documentation (due to system problems).
>
>Are those problems still there?

Yes. It's not so principle for me now (XMLmind is working, HTML is building - it's enough to start... later I will return to this, IMO this problem of win98, I'll try to build on win2000 later)

>
>> But I could build separate manuals, i.e with XMLmind
>> DocBook->...->Convert to HTML... menu item.
>
>Yes, you don't need our build tools for that. But the free Standard
>Edition of XMLMind doesn't let you build PDF.

I've noticed that (-:

>Also, our tools produce HTML and PDF that looks a lot better than the
>XMLMind conversion result :-)

Ok, I'll try it.

>> So the main question is... What I shoul do? (-: Could i just open
>> quickstartguide-1.5.xml and change English words to Russian
>> equivalent and then save the result as quickstartguide-1.5.ru.xml?
>
>Yes, that's the idea. Keep the structure intact and translate the
>text. It shouldn't be necessary to change XML tags. You can use
>XMLMind, but also a simple text editor, to do this job.

Ok

>> About How to get and build...
>> I didn't find any notes about FOP installation
>
>You don't have to install FOP separately. If you check out the manual
>module, fop.jar will be in the manual/lib directory. The build scripts
>take care of calling FOP.

On win98 I've got the result statement that fop couldn't be located...


...


>Since you're going to build an entire manual: will you also do that in
>DocBook XML?

hm... Are you talking (finally) about translating the behavior of <important>, <note>, <warning> elements/tags?

Is it your intention to commit the sources to the
>Firebird doc subproject?

Yes it is.

If so, we should think about setting up
>different (sub)trees for the various languages.

that's why I've come here

If not, you can still
>change your local firebirddocs.xml in whichever way you like (kick out
>the English stuff) so you can build your Russian docs easily.
>
>If you need help with getting the build tools to work, please give us
>more details about what goes wrong.

thanks

>> RPM is stand for RPM Packet Manager (www.rpm.org)
>
>So they changed it into a recursive acronym, huh? It used to be RedHat
>Package Manager. Next thing you know, API will mean API Programming
>Interface.

(-:

>But I'll change that, too (sigh)

BTW, RPM _Package_ Manager (it was a "typo")

-- 
Gregory Sapunkov
what a wonderful world...

Re: [Firebird-docs] Firebird 1.5 Quick Start Guide

[Gregory S. <sap...@ya...>]

>At 01:38 PM 14/10/2004 +0200, you wrote:
>>Helen,
>>
>> >>RPM is stand for RPM Packet Manager (www.rpm.org)
>>
>>HB> Actually, RPM stands for "RedHat Package Manager".

>You can understand why they had to devolve from the "RedHat" part --- but 
>RPM never managed packets!!  (It doesn't say "packets" on the website...)

I can guess what's this stuff is about (-:
As to "packet", it's my mistake... sorry, I was thinking just about "RedHat"... some times copy-paste can help to avoid mistakes... certainly (due to main page) RPM is standing for "RPM Package Manager" (-: 

-- 
Gregory Sapunkov
what a wonderful world...

Re: [Firebird-docs] Firebird 1.5 Quick Start Guide

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

At 01:38 PM 14/10/2004 +0200, you wrote:
>Helen,
>
> >>RPM is stand for RPM Packet Manager (www.rpm.org)
>
>HB> Actually, RPM stands for "RedHat Package Manager".
>
>then go tell the folks that make it that they have to change their
>website. ;-)

You can understand why they had to devolve from the "RedHat" part --- but 
RPM never managed packets!!  (It doesn't say "packets" on the website...)

Helen

Re: [Firebird-docs] Firebird 1.5 Quick Start Guide

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

Helen,

>>RPM is stand for RPM Packet Manager (www.rpm.org)

HB> Actually, RPM stands for "RedHat Package Manager".

then go tell the folks that make it that they have to change their
website. ;-)

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

Re: [Firebird-docs] Firebird 1.5 Quick Start Guide

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

Hi Gregory,

> I'm going to translate Firebird 1.5 Quick Start Guide into Russian

Nice!

> I've read Paul's guide for doc writers, checkout manual module,
> install XMLmind standard edition.  I'm using Win98 box and for now I
> couldn't build all documentation (due to system problems).

Are those problems still there?

> But I could build separate manuals, i.e with XMLmind
> DocBook->...->Convert to HTML... menu item.

Yes, you don't need our build tools for that. But the free Standard
Edition of XMLMind doesn't let you build PDF.

Also, our tools produce HTML and PDF that looks a lot better than the
XMLMind conversion result :-)

> So the main question is... What I shoul do? (-: Could i just open
> quickstartguide-1.5.xml and change English words to Russian
> equivalent and then save the result as quickstartguide-1.5.ru.xml?

Yes, that's the idea. Keep the structure intact and translate the
text. It shouldn't be necessary to change XML tags. You can use
XMLMind, but also a simple text editor, to do this job.

> About How to get and build...
> I didn't find any notes about FOP installation

You don't have to install FOP separately. If you check out the manual
module, fop.jar will be in the manual/lib directory. The build scripts
take care of calling FOP.

To build your own translation, you must first incorporate
quickstartguide-1.5.ru.xml in the firebirddocs XML tree. If you open
src/docs/firebirddocs.xml you can see how this is done for the other
docs.

After that, if the id of your translation is e.g. qsg15-ru and *if*
the build tools work on your system (!), you can build the pdf with:

  build pdf -Drootid=qsg15-ru

(The possibility to specify the rootid on the command line is new. I
didn't have time to document it in the howtos yet!)

Since you're going to build an entire manual: will you also do that in
DocBook XML? Is it your intention to commit the sources to the
Firebird doc subproject? If so, we should think about setting up
different (sub)trees for the various languages. If not, you can still
change your local firebirddocs.xml in whichever way you like (kick out
the English stuff) so you can build your Russian docs easily.

If you need help with getting the build tools to work, please give us
more details about what goes wrong.


> About Quick Guide (IMO, not principal but...)
> SMP is stand for Symmetrical Multiprocessing or Multiprocessor and
> not just "multi-processor"

Thanks, I'll change that.

> RPM is stand for RPM Packet Manager (www.rpm.org)

So they changed it into a recursive acronym, huh? It used to be RedHat
Package Manager. Next thing you know, API will mean API Programming
Interface.

But I'll change that, too (sigh)


Greetings!
Paul Vinkenoog

Re: [Firebird-docs] Firebird 1.5 Quick Start Guide

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

At 01:17 PM 14/10/2004 +0400, you wrote:

>About Quick Guide (IMO, not principal but...)
>SMP is stand for Symmetrical Multiprocessing or Multiprocessor and not 
>just "multi-processor"
>RPM is stand for RPM Packet Manager (www.rpm.org)

Actually, RPM stands for "RedHat Package Manager".

H.

Re: [Firebird-docs] Firebird 1.5 Quick Start Guide

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

Le 14/10/2004 11:17, Gregory Sapunkov a dit :
> Hi,
> 
> I'm going to translate Firebird 1.5 Quick Start Guide into Russian 
good news, welcome !
> So the main question is... What I shoul do? (-: Could i just open quickstartguide-1.5.xml and change English words to Russian equivalent and then save the result as quickstartguide-1.5.ru.xml?
> 
I think yes, it's the way I use for the french translation
(sorry I'm late, because of job troubles, but it will come)

[Firebird-docs] Firebird 1.5 Quick Start Guide

[Gregory S. <sap...@ya...>]

Hi,

I'm going to translate Firebird 1.5 Quick Start Guide into Russian (and I would like to publish it as a part of Firebird's manual). I've asked Helen for sanctions and she recommend to join to Firebird's Doc subproject.
I've read Paul's guide for doc writers, checkout manual module, install XMLmind standard edition.
I'm using Win98 box and for now I couldn't build all documentation (due to system problems). But I could build separate manuals, i.e with XMLmind  DocBook->...->Convert to HTML... menu item.

So the main question is... What I shoul do? (-: Could i just open quickstartguide-1.5.xml and change English words to Russian equivalent and then save the result as quickstartguide-1.5.ru.xml?

About How to get and build... 
I didn't find any notes about FOP installation

About Quick Guide (IMO, not principal but...)
SMP is stand for Symmetrical Multiprocessing or Multiprocessor and not just "multi-processor"
RPM is stand for RPM Packet Manager (www.rpm.org)

-- 
Gregory Sapunkov
what a wonderful world...

Re: [Firebird-docs] gsec doc

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

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

Morning Paul,

> > Does this mean that the latest GSEC 'manual' is ok now ?
> 
> Yes! The only thing that wasn't OK was the blank line in the nested
> compact itemizedlist, and that was caused by the stylesheets.
> 

Excellent - I'll get on with some more writing now :o)


> BTW, the stylesheet updates have been committed today. And I've added
> another goodie wrt lists: if you *don't* specify a spacing for an
> inner list, it takes on the enclosing list's spacing. So you can
> toggle an entire list tree from normal to compact and back just by
> setting the outermost list's spacing attribute. Of course you can
> override this automatic behaviour at any level.

Nice. Isn't XSL great - when you know what you are doing that is.


> ... you own the copyright unless you explicitly give it
> away. But there's no need to do that. What we have to do soon, though,

OK, I'll leave things as they are then for now, thanks.


> 
> > Cheers,
> > Norman. (Slightly sun tanned !)
> 
> So you did come out from under that tree now and then? :-)

Well, I had to go shopping with SWMBO, and walking from the beach to the 
tevernas and back again did expose me slightly - even with my factor 45 
and my welder's helmet :o) 

Re: [Firebird-docs] Copyright (was: gsec doc)

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

At 03:30 AM 1/10/2004 +0200, you wrote:
>H
>I'm going to study the IDPL, and some others, a bit more before I
>decide how to license my own docs. The way it talks about computer
>source code and executables makes the IDPL a little less fit for docs.
>And I don't like the special protection Mozilla and Netscape get
>against lookalike names.

? Lookalike names?

btw, are you planning to go to bed or have you given up on the idea?  :-)

Helen

[Firebird-docs] Copyright (was: gsec doc)

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

Hi Helen,

> Actually, the IDPL that is being used for the new Firebird source
> files is ideal for the docs.  It is not "copyleft" which means that
> anyone can add the docs unchanged to their own custom documentation
> without having to publish the sources of their own documentation.
> Licensing it is essential, since the licence makes the permission of
> the author ("Initial Developer" + later contributors) implicit.
>
> You actually need to add the IDPL to the Getting Started Guides,
> since we released those sources under IDPL and I forgot to give you
> a licence notice.  The same applies to any of the IBP Publications
> stuff that is coming through.
>
> Would you like me to write a licence notice?

Yes, for the docs originating from IBPhoenix I think it's best if you
write that notice (there's a template at the bottom of the IDPL but
you probably knew that long before I did ;-)).

Do you want to include the entire IDPL with the QSG's or just a
pointer?

I'm going to study the IDPL, and some others, a bit more before I
decide how to license my own docs. The way it talks about computer
source code and executables makes the IDPL a little less fit for docs.
And I don't like the special protection Mozilla and Netscape get
against lookalike names.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] gsec doc

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

At 01:54 AM 1/10/2004 +0200, you wrote:

>The way it is now, people have to ask permission to redistribute our
>docs. (It would be the same if you left the (c) notice out, by the
>way. As soon as you produce a document, you own the copyright.) But
>that's not how it should be: our doc sources should be true Open
>Source, just like the engine's sources.

Actually, the IDPL that is being used for the new Firebird source files is 
ideal for the docs.  It is not "copyleft" which means that anyone can add 
the docs unchanged to their own custom documentation without having to 
publish the sources of their own documentation.  Licensing it is essential, 
since the licence makes the permission of the author ("Initial Developer" + 
later contributors) implicit.

You actually need to add the IDPL to the Getting Started Guides, since we 
released those sources under IDPL and I forgot to give you a licence 
notice.  The same applies to any of the IBP Publications stuff that is 
coming through.

Would you like me to write a licence notice?

Helen

Re: [Firebird-docs] gsec doc

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

Hi Norman,

> Does this mean that the latest GSEC 'manual' is ok now ?

Yes! The only thing that wasn't OK was the blank line in the nested
compact itemizedlist, and that was caused by the stylesheets.

BTW, the stylesheet updates have been committed today. And I've added
another goodie wrt lists: if you *don't* specify a spacing for an
inner list, it takes on the enclosing list's spacing. So you can
toggle an entire list tree from normal to compact and back just by
setting the outermost list's spacing attribute. Of course you can
override this automatic behaviour at any level.

> What about the copyright notice which currently says 'copyright
> Norman Dunbar' - is this correct ? I'd hate to be being restrictive
> in any way.

It's correct - you own the copyright unless you explicitly give it
away. But there's no need to do that. What we have to do soon, though,
is to decide what OS licence would be appropriate for our docs. It
would be nice (but by no means necessary) if we all used the same
licence.

The way it is now, people have to ask permission to redistribute our
docs. (It would be the same if you left the (c) notice out, by the
way. As soon as you produce a document, you own the copyright.) But
that's not how it should be: our doc sources should be true Open
Source, just like the engine's sources.

> Cheers,
> Norman. (Slightly sun tanned !)

So you did come out from under that tree now and then? :-)


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Reminder! Changing some target and output directory

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

In article <Pin...@so...>, 
pa...@vi... says...
> Docwriters,
> 
> A reminder of what I posted last Wednesday.
> 
> If there are no objections I'll commit the proposed changes on
> Tuesday.
> 
> -------------------------------------------------------------------
> 

<SNIP>

Hi Paul,

nothing wrong in what you are proposing, as far as I can see. It all 
makes sense.


Cheers,
Norman.

Re: [Firebird-docs] gsec doc

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

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

<SNIP stuff about blanks in nested lists, warpping paras etc>

OK, got all that. Thanks.

Does this mean that the latest GSEC 'manual' is ok now ?

What about the copyright notice which currently says 'copyright Norman 
Dunbar' - is this correct ? I'd hate to be being restrictive in any way.


Cheers,
Norman. (Slightly sun tanned !)

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

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

Hello Helen,

> Snipped a whole lot of stuff that is true about **using Acrobat.**
> But user settings aren't saved.  Whenever you open a PDF, you get
> the default magnification under which it was created.

Only if it was saved with an explicit magnification (as I just found
out). But our manual docs aren't. Like most docs, they were created
with "magnification: default", which means that the reader/user
settings are applied.

These settings *are* saved, both under Windows (Registry) and Linux
(~/.acrobat/prefs). What gets saved, and how, depends on Acrobat
version and OS. With older versions as well as under Linux, some
settings are automatically saved from the session and others need to
be set explicitly under Edit -> Preferences -> General. (You'll find
Magnification: Default Zoom here, for instance. Note that this is the
Reader's default zoom, not the document's.)

Newer Windows versions save more settings automatically, although the
Edit -> Preferences stuff is still at your disposal.

> As for 168% magnification - it's one I would never choose - so the
> argument that it has something to do with Registry settings or the
> like doesn't work.

I don't assume you've chosen that zoom factor explicitly, but can it
be a combination of settings you did choose? Like: no navigation pane
or a very narrow one, combined with "fit width"? If you open the new
QSG 1.0 or 1.5, do you see a horizontal scrollbar in the document
pane?

And if you open an IBPhoenix doc - like the "old" QSG - do you see it
as _wide_ as the new ones? And an IB6 doc? If so, I'm pretty sure that
those are your user settings. Of course you see a bigger fraction of
an IBPhoenix page, because they are square (7" x 7"). The manual doc
pages are A4, which has a width:height ratio of 1:sqrt(2) or roughly
7:10


Greetings,
Paul Vinkenoog

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

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

At 05:56 PM 26/09/2004 +0200, you wrote:
>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:

Snipped a whole lot of stuff that is true about **using Acrobat.**
But user settings aren't saved.  Whenever you open a PDF, you get the 
default magnification under which it was created.

I have experience only with creating PDFs from Frame and from Word's PDF 
Writer.  In both cases, you select the default magnification before you 
launch the writer and that's what you get every time you open the PDF.

As for 168% magnification - it's one I would never choose - so the argument 
that it has something to do with Registry settings or the like 
doesn't  work.  There are no Registry settings on Linux, either.

Helen

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

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

Docwriters,

A reminder of what I posted last Wednesday.

If there are no objections I'll commit the proposed changes on
Tuesday.

-------------------------------------------------------------------

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