firebird-docs — chat stuff about documentation

Re: [Firebird-docs] Fixing the linux build

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

> As I reported a month ago, the Linux doc build is broken due to escaped
> newlines followed by comment characters in build.sh .
>
> If there are no objections I'll commit my proposed fix (repeated below)
> soon.

OK, done.

Grtz, Paul

Re: [Firebird-docs] Monolith docs

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

Hi Helen,

>> With the current setup, all docs in the manual module are chapters in
>> one big Firebird Doc. You can't build the docs separately. This may be
>> OK for an online HTML version, but not for the PDFs.
>>
>> Can we change this in an intelligent way? I.e. produce a PDF book set
>> where the books are separate files but can link to each other, just
>> like the IBPhoenix docset?

> fwiw, I did the IBPhoenix docs using Framemaker.  Doing the crosslinks
> in the two books was a *fun* exercise but the "stuff" behind it is huge.
>
> I don't have the XML version of Frame (toooo many $$$$$) but it might be
> worthwhile ploughing some of the PDF forums, e.g.
> http://www.pdfzone.com/discussions/ to see whether there is an open source
> linking tool you can use (PDFZone lists quite a lot of commercial ones).

I just had a look and this place is really _loaded_ with info. Will see
if I can find something of interest.

Making cross-document links in the XML source is no problem. It would be
ideal if the tools we use now (or other tools we can legally add to the
module) could produce separate PDF files without losing the cross-doc
links. Maybe they can already - I don't know. Until now this hasn't been
an issue because everything was One Doc. But we'll have to split it up -
as we add more docs, it also becomes more ridiculous to cram everything
(Intro to DocBook, Conversion Guide, Howtos, an everything else) into
one PDF file.

> So far, so good with the doc utility!  One tiny little point of English:
> "maturity" (not "matureness").  But I knew what you meant.  :-)

Thanks, I'll change it. But of course I checked my OED first before doing
so :-) : "matureness" exists too, it is in use since 1701. But it's very
rare, and IMO it also has a certain clumsiness (clumsity? ;-)) about it,
maybe because the English "-ness" is appended to the French "mature".
Anyway, "maturity" is the common word and much, much better.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Monolith docs

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

At 01:55 PM 2/11/2003 +0100, Paul Vinkenoog wrote:
>Hi all,
>
>With the current setup, all docs in the manual module are chapters in
>one big Firebird Doc. You can't build the docs separately. This may be
>OK for an online HTML version, but not for the PDFs.
>
>Can we change this in an intelligent way? I.e. produce a PDF book set
>where the books are separate files but can link to each other, just like
>the IBPhoenix docset?

fwiw, I did the IBPhoenix docs using Framemaker.  Doing the crosslinks in 
the two books was a *fun* exercise but the "stuff" behind it is huge.

I don't have the XML version of Frame (toooo many $$$$$) but it might be 
worthwhile ploughing some of the PDF forums, e.g. 
http://www.pdfzone.com/discussions/ to see whether there is an open source 
linking tool you can use (PDFZone lists quite a lot of commercial ones).

So far, so good with the doc utility!  One tiny little point of 
English:  "maturity" (not "matureness").  But I knew what you meant.  :-)

Helen

[Firebird-docs] Monolith docs

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

Hi all,

With the current setup, all docs in the manual module are chapters in
one big Firebird Doc. You can't build the docs separately. This may be
OK for an online HTML version, but not for the PDFs.

Can we change this in an intelligent way? I.e. produce a PDF book set
where the books are separate files but can link to each other, just like
the IBPhoenix docset?


Greetings,
Paul Vinkenoog

[Firebird-docs] tools.jar and JAVA_HOME in build scripts

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

Hello all,

In manual/src/build we have these build scripts for the manual module:

  build.bat (for Windows)
  build.sh  (for Linux)

Both scripts demand that the envvar JAVA_HOME be set, and both add
tools.jar to the Java classpath.

I suppose tools.jar is a leftover from a previous build tool, because
it is nowhere to be found on my systems (Windows and Linux) and the
builds work fine.

About JAVA_HOME:

- In build.bat JAVA_HOME is used twice, both times in the same line:
  first to call Java ("%JAVA_HOME%\bin\java.exe"), and a little later
  to add %JAVA_HOME%\lib\tools.jar to the classpath.

- In build.sh it is only used once, to add $JAVA_HOME/lib/tools.jar to
  the classpath. The executable is simply called as "java".

We seem to assume that the Java 2 executable will be in the search path
on Linux systems, but not on Windows systems. Is there a good reason for
this? To me, it would seem more logical to either call java like "java"
on boths OS'es, or to specify the path on both OS'es.

I just did test builds under Windows and Linux with the JAVA_HOME and
tools.jar references completely removed from the scripts (even with
JAVA_HOME unset in the environment) and everything was built correctly.

Looks like we can at least dump tools.jar. JAVA_HOME has to stay if we
want to specify the path to the executable; if not, it can go too.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Draft docbuilding Howto

[Tilo M. <tm...@al...>]

Hi Paul,

"Paul Vinkenoog" <pa...@vi...> schrieb im Newsbeitrag
news:Pin...@s4......
> Hi all,
>
> I've written a draft Howto on getting and building the Firebird docs
> from the manual module. It's not in CVS yet; an HTML version is at
> http://vinkenoog.nl/firebird/drafthowto/

Excellent work!

> Please comment (but don't start on the variablelists - I know they
> stink).

;)

> 'night,
> Paul Vinkenoog

-- 
Regards,
Tilo Muetze
--
Marathon - The SQL Tool for Firebird & InterBase
http://gmarathon.sourceforge.net

[Firebird-docs] Draft docbuilding Howto

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

Hi all,

I've written a draft Howto on getting and building the Firebird docs
from the manual module. It's not in CVS yet; an HTML version is at
http://vinkenoog.nl/firebird/drafthowto/

Please comment (but don't start on the variablelists - I know they
stink).


'night,
Paul Vinkenoog

Re: [Firebird-docs] A how-to on writing Firebird docs?

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

Hi Mauricio,

> Just to get a better understanding... Why *do* you want the help to
> be a docbook xml?  Please, I don't have any specific objections, but
> all the steps involved in the discussion list seem to make for a lot
> of trouble for anyone participating in the effort.  Please, bear in
> mind that I'm not criticizing, and that I have no other suggestion
> at the moment, but I would like to understand the "whys" in order to
> decide if I should/could think of someway to contribute.

I've also received this mail privately and replied (as you know of
course). Now I see that you posted it to the list too, but it took a
couple of days to show up - I think SF has a random delay function
built in somewhere in the mailing list chain :-)

Anyway, since the question is now on the list, I'll post my answer
here too, because other people may have the same question. It's been
answered before, but the archives are not always accessible - the
interface at SF is a bit awkward, often slow and I think also
incomplete; and the NNTP mirror at news.atkin.com has problems
regularly (right now it's down). So here goes:


> Just to get a better understanding... Why *do* you want the help to
> be a docbook xml?

Because with DocBook XML, you mark up the _structure_ of a text and
the _meaning_ of its elements: you tag things as chapters, sections,
subsections, titles, warnings, code snippets, filenames, tips, user
commands, etc.  etc...  There is no "pollution" by presentational
markup like in HTML, RTF, Word and other formats.

This results in a very clean and structured source text which is easy
to maintain, totally platform-independent *and* presentation-
independent,

From this DocBook XML source, we can then (automatically) build HTML,
PDF and other output for the readers. Stylesheets (which we can change
if we want to) control how the structural markup is translated to a
certain presentation.

> Please, I don't have any specific objections, but all the steps
> involved in the discussion list seem to make for a lot of trouble
> for anyone participating in the effort.

I'm afraid you are right :-(

It takes time to get familiar with DocBook XML. Ten months ago I'd
never heard of it - I learned using it because I wanted to help
produce Firebird documentation. But now that I know it, I find it even
easier to write then HTML or Word or whatever, precisely because I
never have to worry about the layout while I'm writing!

If I write a text in Word, I have to think about if I want section
titles bold or not - or perhaps in a nice color? - and then I have to
remember my decision so I don't do it another way ten pages further
down. And how do I make up a code snippet? And a command line? And a
warning? And... and... aaaargh!

But even if I *do* make some great rules for all these elements, and I
*do* apply them consequently throughout the text, the resulting
document will still suffer from these drawbacks:

- The information itself as to whether something is a code snippet, a
  warning, or a filename, is not included in the document - because
  I've already translated that info to makeup: font types, colors etc.

- I only have a Word text now. How to convert to PDF and HTML? Yes, I
  know: the latest Word versions do that, but you can't really control
  _how_ they do it.

If I write DocBook XML on the other hand, I rarely have to think about
which tags to use, because In DocBook you tag a command as <command>,
a filename as <filename>, a code snippet as <programlisting>, etc...
Easy!

Also, if everybody produces DocBook XML, we can have one common output
style (defined by the stylesheets). If we'd all produce HTML it would
be very difficult (and very frustrating for the docwriters) to have a
common style.


But - having said all that - if someone wants to help and he REALLY
has a big problem with DocBook XML, he can write in another format
too. But I hope everybody will at least give DocBook a good try before
they decide not to use it.


I hope I can finish the first - draft - Howto this week; it's about
how to download the manual module and build the docs. A second Howto
(hopefully within three weeks) will be on how to write docs in DocBook
XML format.


Greetings!
Paul Vinkenoog

 - no docs today, my mind has gone away -

Re: [Firebird-docs] Documentation FB 1.5

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

At 01:51 PM 25/10/2003 +0200, Paul Sjoerdsma wrote:
>Hi,
>
>Where can I find documentation about the new keywords etc that are
>available in FB 1.5

Release Notes.  Not 100% definitive yet (still changes coming through) but 
latest version is at www.ibphoenix.com (scroll down to 4th or 5th news item 
on the main page, right-click on the link).

Helen

Re: [Firebird-docs] A how-to on writing Firebird docs?

[Mauricio L. <ml...@ct...>]

Paul,

Just to get a better understanding... Why *do*  you want the help to be a
docbook xml?  Please, I don't have any specific objections, but all the
steps involved in the discussion list seem to make for a lot of trouble for
anyone participating in the effort.  Please, bear in mind that I'm not
criticizing, and that I have no other suggestion at the moment, but I would
like to understand the "whys"  in order to decide if I should/could think of
someway to contribute.

>    - why we really want you to write DocBook XML
>    - general as well as fbdocs-specific DocBook instructions + tips

Regards,

Mauricio Longo

[Firebird-docs] Fixing the linux build

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

Hi all,

As I reported a month ago, the Linux doc build is broken due to escaped
newlines followed by comment characters in build.sh .

If there are no objections I'll commit my proposed fix (repeated below)
soon.


Greetings,
Paul Vinkenoog (also working on a draft Howto)


Fixed build.sh follows:

#! /bin/sh

if [ "$JAVA_HOME" == "" ] ; then
  echo "    Error: The JAVA_HOME environment variable is not set."
  echo "    You must set it to point at your JDK or JRE distribution,"
  echo "    e.g. JAVA_HOME=/usr/java/j2sdk"
  exit 1
fi


# set up the classpath _CP_ :

# ----- ant libraries: ------
_CP_=../../lib/ant.jar
_CP_=$_CP_:../../lib/optional.jar

# ----- saxon libraries: ------
_CP_=$_CP_:../../lib/saxon.jar

# ----- FOP libraries: ------
_CP_=$_CP_:../../lib/fop.jar
_CP_=$_CP_:../../lib/batik.jar
_CP_=$_CP_:../../lib/avalon-framework-cvs-20020315.jar

_CP_=$_CP_:../../lib

_CP_=$_CP_:$JAVA_HOME/lib/tools.jar

java -Xmx100000000 -showversion -classpath $_CP_ org.apache.tools.ant.Main $*

[Firebird-docs] Documentation FB 1.5

[Paul S. <sjo...@pl...>]

Hi,

Where can I find documentation about the new keywords etc that are 
available in FB 1.5

regards
Paul Sjoerdsma

Re: [Firebird-docs] Firebird 1.5 releasenotes translators

[Frank Schlottmann-g. <fs...@us...>]

On Monday 13 October 2003 09:29, Helen Borrie wrote:
> Hello all,
> 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,

I could try to do some pages in german if nobody else volunteers.

Frank

-- 
"Fascinating creatures, phoenixes, they can carry immensely heavy loads,
 their tears have healing powers and they make highly faithful pets."
     - J.K. Rowling

Re: [Firebird-docs] Firebird 1.5 releasenotes translators

[Olivier M. <om...@ti...>]

Helen Borrie wrote:

> Hello all,
> Are any translators waiting/willing to translate the release notes for =

> Fb 1.5?  We already have French and Russian translations under way.

Pas de chance, j'allais proposer de m'occuper de la traduction=20
fran=E7aise. Par contre je peux servir pour relire la version fran=E7aise=
=2E

[No luck. I was to offer taking care of the french translation. On the=20
other hand, I volunteer to act as a proof-reader of this french version.]=


Helen btw, where can I download the latest (english) draft of these=20
release notes?

Sincerely yours,
--=20
Olivier Mascia

[Firebird-docs] Firebird 1.5 releasenotes translators

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

Hello all,
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.

heLen 

[Firebird-docs] Vacation

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

Hello fellow (would-be) docmakers, and all.

If I've been very quiet last month, it's because I was practically
buried in work. Didn't have time for anything else.

I'm going on a short (8 days) vacation in the Eifel now. Hope to
have more time when I come back!


Greetings - Abra=E7os - freundliche Gr=FC=DFe

Paul Vinkenoog

Re: [Firebird-docs] fb_lock_print: strange result

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

Hi Derryck,

> Any idea what this message from fb_lock_print means:
> (...)

Please ask this question in firebird-support (or firebird-devel if
it's specific to 1.5). This group here - firebird-docs - is about
the development of Firebird documentation.


Greetings,
Paul Vinkenoog

[Firebird-docs] fb_lock_print: strange result

[Derryck W. <der...@tn...>]

Hi all,

Any idea what this message from fb_lock_print means:

>
C:\PROGRA~1\Firebirdcs\bin>fb_lock_print
Unable to access lock table.
C:\Program Files\Firebirdcs\NLWCHTMS01.lck
operating system directive CreateFile failed
-The requested operation cannot be performed on a file with a user-mapped
section open.
<

from production machine w2k/sp4 SMP :
+/- 80 connectins to the server.

Regards,
Derryck

Re: [Firebird-docs] Comment out empty images dir in build.xml?

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

Hi Tilo,

>> That's right, but the difference is that once we have images there:
>> 1) the first workaround MUST be rolled back, or else the images
>>    don't get copied to dist, whereas
>> 2) the second one CAN be rolled back, but it can also stay in place

> I meant to say, rollback 1) and 2) when images are used in the
> docs. Or in other words: whatever method we use they are both
> workarounds until the images are used, therefore they are no longer
> needed when the images are used

OK, I went for #1 (temp. comment out lines in build.xml). It's less
"clever" but also simpler, and easier to make undone when the time
comes.

> (Englische Sprache, schwere Sprache...).

It still feels weird talking to you in English.

>> Schlaf wohl, du Himmelsknabe du ;-)
> Ich als s=FC=DFes Kind schlief tats=E4chlich sehr wohl ;)

;-)

Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Comment out empty images dir in build.xml?

[Tilo M. <tm...@al...>]

Hi Paul,

"Paul Vinkenoog" <pa...@vi...> schrieb im Newsbeitrag
news:Pin...@s4......
> That's right, but the difference is that once we have images there:
> 1) the first workaround MUST be rolled back, or else the images don't
>    get copied to dist, whereas
> 2) the second one CAN be rolled back, but it can also stay in place
>
> > Sorry for the confusion ;)
>
> Yeah, but now you've got me even more confused because I still don't
> know which one you prefer :-)


I meant to say, rollback 1) and 2) when images are used in the docs. Or in
other words: whatever method we use they are both workarounds until the
images are used, therefore they are no longer needed when the images are
used (Englische Sprache, schwere Sprache...).

> Think I'll better go to bed... clearer head tomorrow.
>
> Schlaf wohl, du Himmelsknabe du ;-)

Ich als süßes Kind schlief tatsächlich sehr wohl ;)

--
Regards,
Tilo Muetze
--
Marathon - The SQL Tool for Firebird & InterBase
http://gmarathon.sourceforge.net

Re: [Firebird-docs] Comment out empty images dir in build.xml?

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

Hi Tilo,

>>> Go for that workaround, later when the first image is used in the
>>> docs we can rollback that change.

>> Er... sorry if I sound stupid (I'm a bit sleepy), but which one do
>> you mean? The first one (commenting out, later uncomment) or the
>> second (Readme.txt and excludes)?

> Hm maybe I don't get it, but when we have images in that dir none of
> them is needed?!

That's right, but the difference is that once we have images there:
1) the first workaround MUST be rolled back, or else the images don't
   get copied to dist, whereas
2) the second one CAN be rolled back, but it can also stay in place

> Sorry for the confusion ;)

Yeah, but now you've got me even more confused because I still don't
know which one you prefer :-)

Think I'll better go to bed... clearer head tomorrow.

Schlaf wohl, du Himmelsknabe du ;-)
Paul

Re: [Firebird-docs] Comment out empty images dir in build.xml?

[Tilo M. <tm...@al...>]

Hi Paul,

"Paul Vinkenoog" <pa...@vi...> schrieb im Newsbeitrag
news:Pin...@so......
> > Go for that workaround, later when the first image is used in the
> > docs we can rollback that change.
>
> Er... sorry if I sound stupid (I'm a bit sleepy), but which one do you
> mean? The first one (commenting out, later uncomment) or the second
> (Readme.txt and excludes)?

Hm maybe I don't get it, but when we have images in that dir none of them is
needed?! Sorry for the confusion ;)

> Greetings,
> Paul

--
Regards,
Tilo Muetze
--
Marathon - The SQL Tool for Firebird & InterBase
http://gmarathon.sourceforge.net

Re: [Firebird-docs] docs/images/callouts still there

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

Hi Tilo,

>>>> Can you please ask them not to remove docbook and docbookx?

>>> I don't think the admins have yet opened a SF support for this,
>>> so no need to get active here.

>> The danger may be in the "yet". What if ...

> OK I have sent a message to firebird-admin.

Thanks - better safe than sorry!

Greetings,
Paul

Re: [Firebird-docs] Comment out empty images dir in build.xml?

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

Hello Tilo,

>>>[ about the empty folder src\docs\firebirddocs\images: ]
>>>
>>> Let's comment it out then, and uncomment it as soon as something
>>> is placed in that folder. And when it is no longer empty, it will
>>> also no longer be pruned by "update -P", so that part of the
>>> problem will solve itself.

>> Meanwhile I've thought of something that may be better:
>>
>> - create a file Readme.txt in the images dir;
>> - change the lines in the *html targets in build.xml that now read:
>>     <fileset dir="${src.dir}/docs/firebirddocs/images"/>
>>   to:
>>     <fileset dir="${src.dir}/docs/firebirddocs/images"
>>                                           excludes="Readme.txt"/>
>> (...)
>> What do you think?

> Go for that workaround, later when the first image is used in the
> docs we can rollback that change.

Er... sorry if I sound stupid (I'm a bit sleepy), but which one do you
mean? The first one (commenting out, later uncomment) or the second
(Readme.txt and excludes)?

Greetings,
Paul

Re: [Firebird-docs] A how-to on writing Firebird docs?

[Tilo M. <tm...@al...>]

Hi Paul,

"Paul Vinkenoog" <pa...@vi...> schrieb im Newsbeitrag
news:Pin...@so......
> > Why not use this description?
> > http://sourceforge.net/docman/display_doc.php?docid=766&group_id=1
>
> It's very lengthy, and specific to WinCVS. I'd prefer to give pointers
> to command line CVS, WinCVS and TortoiseCVS. WinCVS is fine, but
> TortoiseCVS is so easy and intuitive that it's almost a laugh! It
> also has SSH built in, unlike WinCVS.
>
> After that, a short explanation of how to ckeckout the manual module,
> with examples for all three programs. Same for update -dP. With
> read-only access, that's all they'll ever need.

When we do it we need to make sure that this documentation is always
up-to-date.
IMHO, our task should be writing Firebird docs and not redundant CVS docs. I
recommend using the SF WinCVS doc to give the user a introduction to CVS and
SSH setup at SF. Then we can simply suggest TortoiseCVS and  command line
CVS. We should also point the users to a good CVS documentation like
http://cvsbook.red-bean.com/cvsbook.html

> > I think our goal should be a nightly build of the html docs which
> > then can be made available online.
>
> That would be nice. But is this automatable on SF?

What I do for Marathon is to checkout the fresh sourcecode, compile and use
scp to put the binaries to the Marathon webspace. Of course this does not
work automatically due to my limited internet access. I can add an
appropriate build target when my time permits (in Oct.).

> Greetings,
> Paul Vinkenoog

--
Regards,
Tilo Muetze
--
Marathon - The SQL Tool for Firebird & InterBase
http://gmarathon.sourceforge.net