firebird-docs — chat stuff about documentation

[Firebird-docs] Request for reviewers of the Jaybird manual

[Mark R. <ma...@la...>]

The Jaybird Programmers Manual has been stuck on Jaybird 2.1 for quite a 
while now. I'm in the process of rewriting parts and adding details on 
newer features, but I'd really like some feedback.

The development snapshot is on 
https://www.firebirdsql.org/file/documentation/drivers_documentation/java/manual-SNAPSHOT/jaybird_manual.html

I'm specifically looking for feedback regarding the overall flow, 
missing information/features, unclear sections, etc.

I'd also like some help identifying parts that could either be removed 
or trimmed (as unnecessary or repeating, to verbose, etc), or parts that 
might be better to move/rewrite from the 'User Manual' part to a future 
'Reference' part.

Mark
-- 
Mark Rotteveel

Re: [Firebird-docs] GitHub, Build bugs with Java 9, Assorted Questions!

[Mark R. <ma...@la...>]

On 13-2-2018 21:31, Norman Dunbar wrote:
> I'm in the process of making some corrections assigned to me on Jira and
> I have downloaded and extracted the ALLJARS.ZIP file, as well as the 
> stuff for the libs directory.
> 
> I have a clean install in other words.
> 
> I've forked the documentation repository so that I can work on it.
> 
> Q1. I assume, perhaps wrongly, that when I'm done I can create a pull 
> request for the fixes?

Yes, you can. If you're not familiar with git: do your changes on a 
branch and create a pull request from that branch. That way you can keep 
your master the same as the upstream master (see 
https://help.github.com/articles/syncing-a-fork/).

> Q2. Also, as we still copying everything into the B_Release branch?

As far as I understand, yes.

> I've done a "./build.sh docs" and everything has built ok, except, the 
> multi-page HTML docs which don't go into dist/html, they just get built 
> into the root folder. This truly messes up a "git status" command as all 
> the files are listed.
>
> Q3. Anyone else seen this? With a clean build? Oracle Java 9?

The build doesn't work with Java 9. In any case, it works OK for me with 
Java 8, on Windows.

> I did clear everything out again, from the root folder, and did a 
> "./build.sh html" and got exactly the same mess. I can manually move 
> things into dist, but I can't see anything in the build.xml that might 
> be causing this - but I'm not an Ant guru I'm afraid.
>
> Q4. Any clues?
> 
> 
> 
> 
> Ok, moving on the the main topic, the ANT build fails to work under Java 
> 9. We are using the 2005 version of ANT - version 1.6.5 and this bug 
> that hit me tonight, was fixed in version 1.9.8 and 1.10.0 back in 2016.
> 
> The bug produces the following output:
> 
> BUILD FAILED
> 
> /data/SourceCode/firebird-documentation/src/build/build.xml:770: The 
> following error occurred while executing this line:
> 
> /data/SourceCode/firebird-documentation/src/build/build.xml:477: 
> java.lang.NoClassDefFoundError: 
> jdk/internal/reflect/ConstructorAccessorImpl
> 
> 
> The workaround, courtesy of 
> https://bz.apache.org/bugzilla/show_bug.cgi?id=59556, is to edit the file:
> 
> firebird-documentation/src/build/build.xml
> 
> To change the following 4 lines:
> 
> grep -n "com.icl.saxon.StyleSheet" 
> /data/SourceCode/firebird-documentation/src/build/build.xml
> 
> 404:        <java classname="com.icl.saxon.StyleSheet" 
> classpathref="saxon.path" failonerror="true" fork="true">
> 
> 477:        <java classname="com.icl.saxon.StyleSheet" 
> classpathref="saxon.path" failonerror="true" fork="true">
> 
> 646:        <java classname="com.icl.saxon.StyleSheet" 
> classpathref="saxon.path" failonerror="true" fork="true">
> 
> 694:        <java classname="com.icl.saxon.StyleSheet" 
> classpathref="saxon.path" failonerror="true" fork="true">
> 
> 
> Each of those lines needs the " fork=true" adding just before the 
> closing '>' and if the above wraps around, they should be all on one line.

It doesn't all need to be on one line, it just needs to be syntactically 
correct XML (and of course, valid Ant elements/attributes/values).

> Lines 404, 477, 646 and 694 need amending.
> 
> 
> Mine look like the above. Once done and saved, the docs will build again.
> 
> Sorry to be such a PITA with the questions, but at least I've solved one 
> of my problems! ;-)

Looking at the build.xml, the change that enabled this forking is the 
cause of the problem. In the html target, immediately after the java 
task you modified is the following:

         <!-- destdir/out parameters are ignored due to chunking
              so we move all chunked html files to their destination: -->
         <move todir="${html.dir}">
             <fileset dir="${build.dir}" includes="*.html"/>
         </move>

I have observed that under Java 8, it writes the files in src/build, and 
then after building, it moves them to the dist/html folder.

Given you say you see the files in the root (and I assume you mean the 
root of the firebird-documentation repo), it is possible that forking 
changed the current working directory (from ./src/build to ./), as the 
fork is likely applying the Ant basedir as its working directory.

As the files are now in a different location, the above move fails.

A possible workaround is to add dir="${html.dir}" to the java task in 
the html task (when fork="true", this will use that as the current 
working directory), I haven't tested it though. However, I'm not sure if 
forking may cause other issues, so maybe we should tread carefully here.

In any case, maybe we should look at updating ant (and maybe some of the 
other dependencies).

Mark
-- 
Mark Rotteveel

Re: [Firebird-docs] GitHub, Build bugs with Java 9, Assorted Questions!

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

On 13/02/18 20:31, Norman Dunbar wrote at great length ....

Q5. I appear to be no longer allowed to login to 
www...@cm...:

The RSA host key for cms.firebirdsql.org has changed,
and the key for the corresponding IP address 78.47.64.209
is unknown. This could either mean that
DNS SPOOFING is happening or the IP address for the host
and its host key have changed at the same time.


I've cleaned out the known_hosts entry, as advised, and reconnected to 
add the new one back in, but now I'm asked for a password.

Do I need to send Sergey my public key again?


Cheers,
Norm.

-- 
Norman Dunbar
Dunbar IT Consultants Ltd

Registered address:
27a Lidget Hill
Pudsey
West Yorkshire
United Kingdom
LS28 7LG

Company Number: 05132767

[Firebird-docs] GitHub, Build bugs with Java 9, Assorted Questions!

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

Evening All,

I'm in the process of making some corrections assigned to me on Jira and
I have downloaded and extracted the ALLJARS.ZIP file, as well as the 
stuff for the libs directory.

I have a clean install in other words.

I've forked the documentation repository so that I can work on it.

Q1. I assume, perhaps wrongly, that when I'm done I can create a pull 
request for the fixes?

Q2. Also, as we still copying everything into the B_Release branch?


I've done a "./build.sh docs" and everything has built ok, except, the 
multi-page HTML docs which don't go into dist/html, they just get built 
into the root folder. This truly messes up a "git status" command as all 
the files are listed.

Q3. Anyone else seen this? With a clean build? Oracle Java 9?

I did clear everything out again, from the root folder, and did a 
"./build.sh html" and got exactly the same mess. I can manually move 
things into dist, but I can't see anything in the build.xml that might 
be causing this - but I'm not an Ant guru I'm afraid.

Q4. Any clues?




Ok, moving on the the main topic, the ANT build fails to work under Java 
9. We are using the 2005 version of ANT - version 1.6.5 and this bug 
that hit me tonight, was fixed in version 1.9.8 and 1.10.0 back in 2016.

The bug produces the following output:

BUILD FAILED

/data/SourceCode/firebird-documentation/src/build/build.xml:770: The 
following error occurred while executing this line:

/data/SourceCode/firebird-documentation/src/build/build.xml:477: 
java.lang.NoClassDefFoundError: jdk/internal/reflect/ConstructorAccessorImpl


The workaround, courtesy of 
https://bz.apache.org/bugzilla/show_bug.cgi?id=59556, is to edit the file:

firebird-documentation/src/build/build.xml

To change the following 4 lines:

grep -n "com.icl.saxon.StyleSheet" 
/data/SourceCode/firebird-documentation/src/build/build.xml

404:        <java classname="com.icl.saxon.StyleSheet" 
classpathref="saxon.path" failonerror="true" fork="true">

477:        <java classname="com.icl.saxon.StyleSheet" 
classpathref="saxon.path" failonerror="true" fork="true">

646:        <java classname="com.icl.saxon.StyleSheet" 
classpathref="saxon.path" failonerror="true" fork="true">

694:        <java classname="com.icl.saxon.StyleSheet" 
classpathref="saxon.path" failonerror="true" fork="true">


Each of those lines needs the " fork=true" adding just before the 
closing '>' and if the above wraps around, they should be all on one line.

Lines 404, 477, 646 and 694 need amending.


Mine look like the above. Once done and saved, the docs will build again.

Sorry to be such a PITA with the questions, but at least I've solved one 
of my problems! ;-)


Cheers,
Norm.

-- 
Norman Dunbar
Dunbar IT Consultants Ltd

Registered address:
27a Lidget Hill
Pudsey
West Yorkshire
United Kingdom
LS28 7LG

Company Number: 05132767

[Firebird-docs] Enabled notification of pushes to repository

[Mark R. <ma...@la...>]

As you may have noticed from the last two messages, I have enabled 
notifications about pushes/commits to the documentation repository.

These notifications will show which files have changed, but not the diff 
of the change itself. To get the diff, use the commit link, or - when 
the mail contains multiple commits - the full diff-link at the end of 
the message.

We hope this will help translators tracking what has changed. For now 
this should be considered an experiment. By all means, let us know if 
this isn't considered helpful (or too much noise), in that case we could 
consider posting to a separate list.

Right now, I have configured GitHub to use the git name + email address 
of the 'author' of the commit(s) as the 'from'-address. It is also 
possible to use a fixed value of "GitHub <no...@gi...>", both 
have there pros and cons. If you have a strong opinion about it, let us 
know as well ;)

Mark
-- 
Mark Rotteveel

[Firebird-docs] [FirebirdSQL/firebird-documentation] a2cf3d: Delete file added for notification testing

[Mark R. <ma...@la...>]

  Branch: refs/heads/master
  Home:   https://github.com/FirebirdSQL/firebird-documentation
  Commit: a2cf3dec26c5b164fb7834309dbbd2730a659493
      https://github.com/FirebirdSQL/firebird-documentation/commit/a2cf3dec26c5b164fb7834309dbbd2730a659493
  Author: Mark Rotteveel <ma...@la...>
  Date:   2018-02-13 (Tue, 13 Feb 2018)

  Changed paths:
    R src/testfile.txt

  Log Message:
  -----------
  Delete file added for notification testing

[Firebird-docs] [FirebirdSQL/firebird-documentation] 565f4e: Test commit notification to mailinglist

[Mark R. <mro...@us...>]

  Branch: refs/heads/master
  Home:   https://github.com/FirebirdSQL/firebird-documentation
  Commit: 565f4e815fe4ffc0f802c316b92a01410e2baee6
      https://github.com/FirebirdSQL/firebird-documentation/commit/565f4e815fe4ffc0f802c316b92a01410e2baee6
  Author: Mark Rotteveel <mro...@us...>
  Date:   2018-02-13 (Tue, 13 Feb 2018)

  Changed paths:
    A src/testfile.txt

  Log Message:
  -----------
  Test commit notification to mailinglist

Re: [Firebird-docs] Install firebird on android

[Mark R. <ma...@la...>]

On 4-1-2018 09:20, guidocavalera--- via Firebird-docs wrote:
> Hi i want to use a firebird DB on android and i ve downloaded all files 
> from firebirdorg but how can i install it ?

The firebird-docs list is for discussion about (writing) the documentation.

You will need to post to firebird-devel as Android support is still 
experimental (as far as I'm aware).

Mark
-- 
Mark Rotteveel

[Firebird-docs] Install firebird on android

[<gui...@li...>]

Hi i want to use a firebird DB on android and i ve downloaded all files from firebirdorg but how can i install it ?

Bye

Re: [Firebird-docs] Strange behaviour with char '#'

[Köditz, M. <Mar...@it...>]

Sorry, wrong mailing-list.

Von: Köditz, Martin
Gesendet: Freitag, 15. Dezember 2017 09:12
An: 'Chatter regarding Firebird documentation' <fir...@li...>
Betreff: Strange behaviour with char '#'

Hi,

I stumbled upon the following problem:
I have a field of type varchar(7). When inserting the string '#eeeeee' the field value remains zero.

Does the character '#' have a special role?

Regards,
Martin

[Firebird-docs] Strange behaviour with char '#'

[Köditz, M. <Mar...@it...>]

Hi,

I stumbled upon the following problem:
I have a field of type varchar(7). When inserting the string '#eeeeee' the field value remains zero.

Does the character '#' have a special role?

Regards,
Martin

Re: [Firebird-docs] Understanding question about CASE in connection pooling

[Köditz, M. <Mar...@it...>]

Then I understood it correctly. Thank you Helen.

Martin

Re: [Firebird-docs] Understanding question about CASE in connection pooling

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

Sunday, December 10, 2017, 3:44:41 AM, Martin wrote:

> I need some help to understand this section (connection pooling)

>> External connections made by statements WITH COMMON TRANSACTION (the default) will remain open

>> until the current transaction ends. They can be reused by subsequent calls to EXECUTE STATEMENT, but

>> only if the connect string is exactly the same, including case

>  

> What is meant by „including case“? The case sensitivity? Or something else?

It means "...with upper and lower case characters exactly as they occur in
the original string."  Can you do something with that phrase?

Helen

[Firebird-docs] Understanding question about CASE in connection pooling

[Köditz, M. <Mar...@it...>]

Hi,

I need some help to understand this section (connection pooling)
> External connections made by statements WITH COMMON TRANSACTION (the default) will remain open
> until the current transaction ends. They can be reused by subsequent calls to EXECUTE STATEMENT, but
> only if the connect string is exactly the same, including case

What is meant by "including case"? The case sensitivity? Or something else?

Regards,
Martin

Re: [Firebird-docs] Open pull requests

[Köditz, M. <Mar...@it...>]

Hi,

I stumbled upon these mistakes during my translation work. Since I am not a native speaker, I did not want to push this data directly. Here I prefer a four-eye principle.

As Paul said, I could push obvious mistakes directly.

Since I am not yet finished with the translation of the chapter, I did not want to contact the mailing list for each pull request. But I think this will take on a certain routine over time.

Best regards
Martin

Re: [Firebird-docs] Open pull requests

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

Mark Rotteveel wrote:

> Two weeks ago, Martin created two pull requests with minor changes to
> the 2.5 language reference (see
> https://github.com/FirebirdSQL/firebird-documentation/pulls). I noticed
> they are still open.
>
> I feel hesitant to merge them myself as I'm only occasionally doing
> documentation work, but at the same time I think as a form of 'PR', it
> would be better to merge things quickly, especially if they are minor.
>
> So, two questions:
>
> 1. Are there objections if I merge these two?

None at all.

> 2. How to handle this going forward?

Martin has been a committer for a long time. In cases like this, I think
he could push the corrections directly to the repository.

When in doubt and if it's not your 'own' document, discuss it in
firebird-docs. That's the way we used to do it. Unless we prefer to
have discussions about changes on GitHub.

You mail made me realise that I didn't know about these pull requests.
I've now added myself as a "watcher". (Like I said earlier, I'm a
complete newbie to GitHub.)


Cheers,
Paul Vinkenoog

[Firebird-docs] Open pull requests

[Mark R. <ma...@la...>]

Two weeks ago, Martin created two pull requests with minor changes to 
the 2.5 language reference (see 
https://github.com/FirebirdSQL/firebird-documentation/pulls). I noticed 
they are still open.

I feel hesitant to merge them myself as I'm only occasionally doing 
documentation work, but at the same time I think as a form of 'PR', it 
would be better to merge things quickly, especially if they are minor.

So, two questions:

1. Are there objections if I merge these two?
2. How to handle this going forward?

Mark
-- 
Mark Rotteveel

Re: [Firebird-docs] SourceForge CVS to GitHub migration done

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

Tuesday, November 28, 2017, 1:21:39 PM, PaulV wrote:


> And this CHM file describes the ODBC driver?

Yes, it's the same content as the PDF and the HTML with some edits to
stop it exploding when you try to hit an external link.  Oh, and about
a zillion fewer Firebird logos. ;-)

> So it naturally belongs to
> the Fb-ODBC 2.0.5 documentation? Then I'd put the source files
> - unzipped, for easier version control - in a subdir of refdocs/fbodbc205,
> e.g. refdocs/fbodbc205/chm or whichever name you think is best.

refdocs/fbodbc205/chm-source

Helen

Re: [Firebird-docs] SourceForge CVS to GitHub migration done

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

Helen wrote:

> 1. Created a new../refdocs/images subdir, currently containing the
> images for the ODBC manual.

Perfect.

> 2.  Created a new ../refdocs/fbodbc205 directory containing the source
> for the ODBC manual.
> 3.  Added fbodbc205 to refdocs.xml.

Ditto.

> Next thing, I have source files for the build of the CHM file, for use
> with the M$ help compiler, all zipped up.  Where should I put them?
> I'll write a little readme.

And this CHM file describes the ODBC driver? So it naturally belongs to
the Fb-ODBC 2.0.5 documentation? Then I'd put the source files
- unzipped, for easier version control - in a subdir of refdocs/fbodbc205,
e.g. refdocs/fbodbc205/chm or whichever name you think is best.

Cheers,
Paul

Re: [Firebird-docs] SourceForge CVS to GitHub migration done

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

Hello Mark,

>> Next thing, I have source files for the build of the CHM file, for use
>> with the M$ help compiler, all zipped up.  Where should I put them?
>> I'll write a little readme.

> What are these CHM files for? You could consider just adding them 
> (unzipped) in a specific subfolder of the repository, or create a 
> separate repository for this.

Ahm actually, I was asking PaulV that question...you may not be aware
that we don't do CHM, but the ODBC fans seem to like them.  Our
DocBook system doesn't produce it but it turned out to be relatively
simple to produce from the html that it does generate.  I could
probably produce VS help from them as well, some other time when I'm
in an experimental frame of mind.  Of course, both the CHM and VS help
compilers are proprietary Microsoft products, so some might say it
would be evil to encourage these people. ;-)

So I was really just sounding out Paul as to where he thought might be
a good place to put the source files for the CHM file - obviously (I
thought) *where?* relative to the parent docbook source from which
they evolved.  A different repository does not make any sense.
Tainted or not, it is still Firebird documentation.

Helen

Re: [Firebird-docs] SourceForge CVS to GitHub migration done

[Mark R. <ma...@la...>]

On 2017-11-27 01:02, Helen Borrie wrote:
> Actually I had to do a minor update today as I'd left something out,
> so the commit messages don't all reflect what I did yesterday. ;-)
> 
> Next thing, I have source files for the build of the CHM file, for use
> with the M$ help compiler, all zipped up.  Where should I put them?
> I'll write a little readme.

What are these CHM files for? You could consider just adding them 
(unzipped) in a specific subfolder of the repository, or create a 
separate repository for this.

> The other thing is - we don't seem to have a notification channel for
> checkins to this repository.  Can something similar be done for this
> one as was done for the main Firebird repo?  (After a lot of messing
> about, we finally got main repo notifications coming into
> firebird-checkins a few weeks ago.  I'm not sure they are perfect yet,
> though....)

I'll search (or ask) on firebird-devel what they did for this.

Mark

Re: [Firebird-docs] SourceForge CVS to GitHub migration done

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

I wrote:

> This sounds like a new book, I don't recall reading about it though - or maybe I've 
> forgotten - is there a thread or link I can follow to read about it please? Thanks.

Cancel that request, I found it. Thanks.

Cheers,
Norm.
-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.

Re: [Firebird-docs] SourceForge CVS to GitHub migration done

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

Morning Helen, well it is here!

> The other thing is - we don't seem to have a notification channel for
> checkins to this repository.  

As a temporary measure until a correct solution is implemented, login to github as yourself and navigate to the docs repository. Near the top of the page is a 'watch' button. Click it. Now when you next login to github, there will be a blue dot beside the bell icon at the top of the screen if any updates have been made. Click the bell to see what's what.

> I'll need to do another lot, for the Developer's Guide, when I get the
> go-ahead from Denis.  

This sounds like a new book, I don't recall reading about it though - or maybe I've forgotten - is there a thread or link I can follow to read about it please? Thanks.


Cheers,
Norm.


-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.

Re: [Firebird-docs] SourceForge CVS to GitHub migration done

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

Monday, November 13, 2017, 12:03:31 AM, Mark wrote:

> The migration from SourceForge CVS to GitHub has been completed. The 
> repository is at
> https://github.com/FirebirdSQL/firebird-documentation 
> (with clone URL
> gi...@gi...:FirebirdSQL/firebird-documentation.git or 
> https://github.com/FirebirdSQL/firebird-documentation.git )

> If there are any problems or questions, let me know.

Over the weekend I did some commits.  a few things:

Paul, when you have a moment, could you look at what I did:

1. Created a new../refdocs/images subdir, currently containing the
images for the ODBC manual.
2.  Created a new ../refdocs/fbodbc205 directory containing the source
for the ODBC manual.
3.  Added fbodbc205 to refdocs.xml.

I did all this with pushing from my local repo.

Actually I had to do a minor update today as I'd left something out,
so the commit messages don't all reflect what I did yesterday. ;-)

Next thing, I have source files for the build of the CHM file, for use
with the M$ help compiler, all zipped up.  Where should I put them?
I'll write a little readme.

The other thing is - we don't seem to have a notification channel for
checkins to this repository.  Can something similar be done for this
one as was done for the main Firebird repo?  (After a lot of messing
about, we finally got main repo notifications coming into
firebird-checkins a few weeks ago.  I'm not sure they are perfect yet,
though....)

I'll need to do another lot, for the Developer's Guide, when I get the
go-ahead from Denis.  It's good to go Beta for reviewing, as far as
I'm concerned, but I understand Denis still has a meaty job to do
translating his source code downloads.  That doesn't affect the
production of the book at all, except that every chapter ends with a
link to the respective source code pack and they are all at some stage
of being re-done. I haven't heard from Denis for a couple of weeks, so
I don't know exactly where we're at.  If anyone is interested in
taking a browse through the PDF or the HTML, the latest builds are in
my repository at https://github.com/helebor/fbmanuals in the /dist
subdirectory.  Note that gitHub's PDF browser is not crash-hot;  it's
better to download it when the Download button appears.

Helen

[Firebird-docs] Pull Request: Updated link to new Git repository in doc history

[Köditz, M. <Mar...@it...>]

Hi,

I have added a pull request "Updated link to new Git repository in doc history."
https://github.com/FirebirdSQL/firebird-documentation/pull/2

Since we moved the repository from CVS, we should adjust the paths. I think a link to the commits list would be best.

If this is OK, I will take over the changes for German docs too.

Regards,
Martin