firebird-docs — chat stuff about documentation

[Firebird-docs] Connections

[Andy C. <an...@ad...>]

Here's a first cut at a first piece of the Firebird Manual. It's still =
being written; I haven't covered the other connect parameters; I haven't =
cross-checked the information with the Beta docs. Actually, I'd like to =
forget the Beta docs and rely upon the unpublished release docs if I =
could. Please look at it and comment. Thanks.

Copyright status: Because I am an anarchist, I do not (declare / file / =
claim) copyright. Since there is no Firebird "organization", I hereby =
give permission to copyright it to ibphoenix under the same terms as new =
code contributed to the Firebird executable. As far as I know, no one =
has a copyright on any of the material presented here (because I wrote =
it) except that the last section was lifted from an email from Jim =
Starkey and he may have copyright on that material.

[Firebird-docs] Re: Three Questions

[Andy C. <an...@ad...>]

> > Connections
> > SQL Language
> > The isql tool

> Just write about it, and indicate in parenthesis things that you want =
to be
> added but are not familiar with. If I know about it, I'll write about =
it or
> if not, somebody else will.

I shall do so. I will also send you preliminary versions; I welcome your =
comments, suggestions, and guidance. I won't worry about format for now; =
you can probably read anything I can create and, worse comes to worse, =
you can cut and paste.

> By the way, have you downloaded the 10mb references of Interbase?

If you are referring to the Beta Documentation, I downloaded that last =
autumn when I started with Open Source Interbase. IMHO it is reasonably =
complete and well written, but it suffers from copyright restrictions =
and lack of a global search. When it's incorrect there's no legal way to =
fix it. Ann is supposed to be putting the updated unreleasable version =
where I can download it so that I can learn. I also have all the HLP =
files from the autumn download of InterBase (for reference, not for =
copying).

> What ever we do, we should be careful NOT to copy anything from this,
> otherwise, all our efforts will go to waste since the community won't =
be
> able to freely use it.
No mechanical copying. No deliberate mental copying. Ideas are =
necessary. For example, AFAIK, Borland owns copyright on the only =
documents that say what the Firebird SQL syntax is. ANYONE who writes =
down what Firebird accepts for the CREATE TABLE command syntax must have =
learned it from Borland copyrighted material, because it does not exist =
anywhere else.

> Thanks for you help. Let's get going.
Yo!

__________________________________
http://www.laonet.net/AndyCanfield

[Firebird-docs] Re: Three Questions

[Joseph A. <ja...@il...>]

> That doesn't mean that you have to do it all; it means that you get the
flack, the questions, the worry, the gold star.

By experience, the community does not give flak or pass blame around. In my
view the gold star is for the community.

> Here's my list:
>
> Connections - I'd like to work up coherent coverage of connections. I
can't handle some of the UNIX / NT details but I think I can cover the
commands, the mechanisms, the rules and the guidelines.

Just write about it, and indicate in parenthesis things that you want to be
added but are not familiar with. If I know about it, I'll write about it or
if not, somebody else will.

>
> SQL Language Reference - This is the massive part. While I tend to write
pretty good specifications, which this is, essentially, I may not know all
the ins and outs. But for the Firebird group it may be easier for me to
write it and others correct it than to wait for others to have the time to
write it. If you've got a more qualified candidate hand it to her.
>

> The isql tool - In my outline this goes in a section including gpre, gbak,
dli, etc. I use isql a lot and I'd like to cover it. What I get wrong know
can be altered later.
>

By the way, have you downloaded the 10mb references of Interbase?

What ever we do, we should be careful NOT to copy anything from this,
otherwise, all our efforts will go to waste since the community won't be
able to freely use it.

Thanks for you help. Let's get going.

Have a great day.

Joseph Alba
ja...@il...

Re: [Firebird-docs] Re: Three Questions

[Pavel C. <pc...@at...>]

Hi all,

Only for record and to clear some mud water...

Everyone has fairly much free range within the Firebird project, the  
main idea being if you think it's right just go ahead and do it. No 
orders from some artificial authority. There is very simple formal 
procedure for any work -> Explain what you're going to do, did or 
doing in appropriate mailing list or forum. If it affects others then 
inform others in advance and wait a little to receive any feedback. 
That is, the legitimacy of any work / action is confirmed in public 
forum. Size of the audience asked for approval should be in direct 
proportions to importance / impact of work for / on others. But final 
decision is always made by actual workers (with all consequences 
:-), not by lurkers or by people occupied with work outside the 
scope of discussed issue. The dead-ends and bad decisions are 
corrected when necessary on the way. Open Source projects are 
very dynamic beasts, and we always throw out code, work, doc, 
web pages etc. if it doesn't work or doesn't fulfils actual needs. It's 
famous Permanent Reconstruction / Rewriting / Reengineering of 
all thriving open source projects :-)

So, do whatever you'll see fit to reach your goal. I think that you're 
on path to deliver something that we all badly need. ANY work that 
move us a little bit closer to the final goal will be appreciated and 
remembered.

Best regards
-- Pavel Cisar

Firebird - the most addictive database
http://firebird.sourceforge.net

[Firebird-docs] Re: Three Questions

[Andy C. <an...@ad...>]

> Actually, I did not take the tin can.=20
When Helen / Ann / Jim / Pavel want to know what's going on with the =
documentation, who are they going to ask? You. That means you've got the =
tin can. Being the person that everything is routed through, you're the =
only one who knows what's going on, you're necessary to hand out tasks, =
you've got the tin can. You put yourself in the prime spot, so you're =
it. That doesn't mean that you have to do it all; it means that you get =
the flack, the questions, the worry, the gold star.

> One pressing need is to have a Firebird documentation that is not 70% =
lifted
> from the Interbase version. One idea I'm looking into is to use the =
other
> database servers' documentations as guides and outlines, while putting =
in
> Firebird instructiosn.

If we don't run into copyright problems with those other sources, yeah.=20

> I really thank you for volunteering to help. It would be neat if you =
can
> give me the topics (or titles) you would like to work on, so I don't =
have to
> duplicate those areas. (I believe in delegation and teamwork.)

In order for there to be delegation there must be a boss. That's you.

Here's my list:

Connections - I'd like to work up coherent coverage of connections. I =
can't handle some of the UNIX / NT details but I think I can cover the =
commands, the mechanisms, the rules and the guidelines.

SQL Language Reference - This is the massive part. While I tend to write =
pretty good specifications, which this is, essentially, I may not know =
all the ins and outs. But for the Firebird group it may be easier for me =
to write it and others correct it than to wait for others to have the =
time to write it. If you've got a more qualified candidate hand it to =
her.

The isql tool - In my outline this goes in a section including gpre, =
gbak, dli, etc. I use isql a lot and I'd like to cover it. What I get =
wrong know can be altered later.

> I hope you won't mind doing this on a private e-mail conversation =
first. By
> experience, I can assure you that this is a lot better because we can =
thresh
> out difficult ideas and express ourselves more freely without inviting
> flames from others. When things have settled down to a pretty level =
field,
> that's the time we go public. I hope that's okay with you.

If we were in a company I'd have no trouble with this. I would go to the =
boss to make confirm that you are authorized to do this and that I am =
assigned to take direction from you. However, in Firebird there is no =
central authority and so there is no one who can say "Yes, Andy, do it =
his way." In Firebird the community is the authority. You tell me that =
Helen told you, but Helen didn't confirm it to me, and even if she did I =
don't know to what extent I should be taking directives from Helen. The =
one person I have heard enough about, and enough from, to respect =
personally is Ann. If anyone in Firebird has the authority to tell me =
"go there", it is Ann, and she has it because I gave it to her.

I'm going to send this directly to you and I expect that you will be =
sending things directly to me. However, I am also going to post this to =
Firebird-docs so that the community, who in effect is our stockholders, =
has notice and record of what is going on.=20

[Firebird-docs] Re: Three Questions

[Andy C. <an...@ad...>]

A: As much as possible of this discussion should be fed through =
Firebird-docs, yes? Seems to me that people perceive Firebird-develop as =
development=3Dcoding, and don't want it cluttered up with documentation =
issues. But if you and I rely on direct e-mail we have no community.=20

B: We need to think about what source format. DocBook has been =
recommended; I read up on it last night and it's not bad but then again =
I haven't got it executing yet.

THREE QUESTIONS:

> 1. What do we want?
We want documentation for Firebird; available via the Internet, globally =
searchable, accurate, up to date, maintained. For me, appearance is =
secondary. Electronic version is critical, print version is secondary. I =
think of the term "User's Manual" but conceptually the target is =
everything you need to know about FB.

> 2. What do we have?
We have a number of very busy people who know everything, and a large =
number of people who know a little bit. We have pretty good =
documentation which we can't copy but we can read. We have very good =
articles about various "side" issues.

> 3. Can we do what we want with what we have?
Certainly. There's a critical speed/time trade-off; the more people we =
can suck into this engine the faster we'll get ofr the ground.

Because of the distributed nature of our knowledge, I think it's =
critical that we encourage Ann, Boris, Claudio, David, etc. to correct =
things without having to install any software or learn any conventions. =
The people who know the most are the most busy; we must find an =
efficient way to tap their brains.=20

> I'd like to do things the Linux way. If you want something, try =
starting it
> and send it to me.
I'm not familar with "the Linux way". I thought that the open source way =
was to create a pool and encourage people to contribute. But whatever.=20

A few days ago I volunteered to have the tin can tied to my ankle; now =
Joseph Alba has taken the tin can and tied it to his ankle. You're =
welcome to it. You will be the caretaker for the Firebird Documentation. =
When formatting issues are settled, please create the outline - source =
for editing and web site for reading. Then the rest of us will start =
filling in the stubs.

Is this a good plan? Is it how you see your role?

----- Original Message -----=20
From: "Joseph Alba" <ja...@il...>
To: "Andy Canfield" <an...@ad...>
Sent: Tuesday, April 24, 2001 22:11
Subject: Re: [Firebird-devel] Documentation

> Dear Andy,
> Thanks for your comments. Helen B. informed me that Doug has a lot of =
load
> right now, so, I should take up the cudgels for documentation.
> Right now, I'd like to be more specific with what must be achieved. I
> believe in the maxim that in any new undertaking, ask yourself 3 =
questions
> 1. What do we want?
> 2. What do we have?
> 3. Can we do what we want with what we have?
> What we have is a community of volunteers. Gleaned from your =
suggestions,
> among those what we want is are Reference Manuals and Users Guides =
that is
> not copyrighted by Borland. (Other suggestions are How To's collation,
> etc...)
> I'd like to do things the Linux way. If you want something, try =
starting it
> and send it to me. For the community, I will assume that you will not =
claim
> any intellectual rights to the product, and I will assume the right to
> correct and revise it and present it to the community for further
> corrections. Everything will be Open Source with Firebird Community =
having
> the last say. If somebody else wants to improve on it, they send me =
their
> revisions.
> I will have a website where you can download the beta docs. Really =
like the
> Linux Documentation way.
> So, Andy, if you have something in mind, start writing it and send it =
to me,
> so I can go over it and present it to the community.
> By the way, don't worry about my credentials. I was asked by Helen and =
Ann
> last year to play second fiddle to Doug. But now, they told me to get =
things
> going.
> Thanks a lot for your enthusiasm. I'm looking forward to your =
contribution.
> Have a great day!
> Joseph Alba

[Firebird-docs] Outline

[Andy C. <an...@ad...>]

I think that the first goal is to construct a hierarchy and implement it =
as a web page tree. I suggest a top-level which is "documentation" and =
would function as a sort of refreence library, be able to link to =
articles, different site's "documentation" pages, etc. One of those =
links is to "User's Manual" which would be comparable to the beta docs, =
perhaps a bit more extensive. The Manual itself would, of course, be =
organized as a web page tree rather than as a few massive files. The =
whole thing is designed to be used interactively, not downloaded, =
although for people in Thailand and Antarctica it would be nice to have =
a downloadable version.

The difference in the two levels is that "Manual" is supposed to be a =
coherent document, with standard formatting styles and great =
integration, whereas "Documentation" is more like a library, where every =
piece is different. So "Documentation" is very mush like the ibphoenix =
documentation page, although I don't know just what the standard is =
there for including and excluding. The Firebird documenation page, like =
a library, should strive to include everything, as long as it's not =
definitely wrong, regardless of how useful. Not everything, of course, =
needs to be on the front page; we could have an "obsolete" subsection =
pointing to the IB 3 docs, for example.

For the "Manual", here's a tentative outline:

* "What Can Firebird Do For You" - covers material relevant to a project =
planner in deciding whether or not to use Firebird. What we can do, what =
we can't do. Available extensions (IBObjects, Delphi, etc.).

* "How To Use This Manual" - should be read by anyone who wants to find =
something here.

* "An Introduction to Firebird" - Takes the newbie who knows some Excel =
and explains concepts and terminology.

* "Installation" - A general guide plus specific installation on each =
platform. Covers not only server machines but also client machines.

* "Getting Started" - ? How to get something on the screen. Probably =
substructured into subcompondents for API, ODBC, Delphi, etc.

* "Connections" - Everything you'd ever want to know about connections - =
users, roles, connection strings, etc.

* "The C Application Program Interface"

* "Firebird SQL Language Reference Manual"

* "Tools" - IBConsole, isql, gpre, gli, etc. Something on every piece we =
ship with the product, even if we say "This is Jim's favorite but nobody =
else ever uses it." (;>)

* "Release Notes" - A reasonable level of information on every release =
for every platform. The user may be running an old version; this will =
tell him about it and whether he should upgrade.

* "Bugs" - symptoms, work-arounds. If fixed, which release was it fixed =
in. Psuedo-bugs =3D things people are surprised by that aren't really =
bugs.

Of course, sections can be added later, and sections can be subdivided. =
Some of the material already exists, such as "Introduction to Firebird"; =
it just needs to be updated / integrated / reformatted. Material such as =
"SQL Language Reference" exists but can't be copied, and so has to be =
regenerated.

Given a set of pegs, people can hang things from them. Let's figure out =
what kind of pegs we want, and then get the pegs on the wall in a couple =
of weeks.=20

Re: [Firebird-docs] Documentation Source Format]

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

David,
> So, here's what i suggest:
[snip]

I will try to help with documentation of Firebird(this seems the only place
where I can actively contribute...). To accomplish that I will follow your
instructions for installing Docbook. But please be patient with me cause I
first have to download, install and must become familiar with the different
tools(and also XML).

Tilo

Re: [Firebird-docs] HELP.GDB

[Ann W. H. <aha...@ib...>]

At 05:57 PM 4/24/2001 +0700, Andy Canfield wrote:
>HELP.GDB appears to be documentation for qli.exe = Query Language 
>Interpreter. Since I cannot find the word "Copyright" in the text it 
>appears to be unprotected by Copyright. Is QLI an obsolete version of ISQL 
>? It does not appear to be mentioned in the beta docs.

QLI is an obsolete version of ISQL in the same sense that a
cappuccino machine is an obsolete version of instant coffee.
It has been maintained (minimally) because it's a major part
of the test suite.  There's some documentation at ibphoenix.com.
I believe that a copyright notice is required to establish
damages in a copyright suit, but material without a mark is
still copyright the author.


Regards,

Ann

[Firebird-docs] DocBook

[Andy C. <an...@ad...>]

David Jencks has suggested that we use the SXML (Standard Extensible =
Markup Language) DTD (Document Type Definition) DocBook as source for =
the documentation. Do others here have opinions on DocBook?

If I write something and John Doe sees that it's wrong, I want John to =
be able to correct my mistake in ten minutes. The web page he's reading =
has a link labelled "Click here to edit this page." John gets something =
he can edit on his present computer, Linux or UNIX or Mac or Windows. =
John doesn't need to have memorized a markup language in order to fix =
typos, add a sentence or two, remove a mistake. Following simple =
embedded instructions (e.g. "mailto:..." ) he can send his alterations =
in after only a few minutes. If it takes more than ten minutes John =
won't bother and we'll lose out on his corrections.

David Jencks wrote:
> 1. get ant, you'll need it for the compilation stuff. =20
> http://jakarta.apache.org/builds/ant/release/v1.3/bin/
> You will need java, probably jdk 1.3 for ant and the xml/xsl
> parsing/transformation.

I only have Windows. So far I think that I want three pieces:
[1] ANT: I downloaded jakarta-ant-1.3-bin.zip; installed 17 MB.
[2] JDK (1.3?) Do you have a link for the source to jdk ?
[3] DOCBOOK: I downloaded docbk41.zip; installed 1 MB.
[4] JBOSS: can't get it until I get JDK and get ANT working.
Do I need any other pieces?

[Firebird-docs] HELP.GDB

[Andy C. <an...@ad...>]

HELP.GDB appears to be documentation for qli.exe =3D Query Language =
Interpreter. Since I cannot find the word "Copyright" in the text it =
appears to be unprotected by Copyright. Is QLI an obsolete version of =
ISQL ? It does not appear to be mentioned in the beta docs.

[Firebird-docs] Re: [Firebird-devel] Documentation

[Andy C. <an...@ad...>]

I brought up the documentation issue in firebird-devel and the result =
was the issue has moved to the firebird-docs list at sourceforge.

I cannot get through to www.interbase2000.org so I can't check your =
reference.

I feel that Firebird documentation is seriously crippled and needs work. =
I hope to participate in creating a good documentation facility for it. =
I want to help create a "Reference Manual" slash "User's Manual" that is =
dynamic and inclusive.

The best documentation available for Firebird, the Beta Docs, are all =
tied up in copyright issues. Apparently Borland won't let us extend and =
update those docs to cover both InterBase and Firebird. If this is true, =
I will help document Firebird and let Borland pay for documenting =
InterBase.

What I wish for is not so much a printed manual as a web site where the =
divisions of the "manual" correspond to subtrees on the site.=20

The whole thing MUST be globally searchable; the second worst problem =
with Borland's documentation is that you have to figure out, on your =
own, where Borland stuffed the information. The worst thing about =
Borland's documenation is that we don't have any way to correct it when =
it's wrong.

Being a web site, this can not only can cover the material like a =
manual, but it can include links to other documents either here or on =
other systems - FAQ's, papers, various "Documentation" pages, etc. With =
a little effort it can be a reference library and not just a manual.

Being browser based, it can be burned into a CD-ROM.

There's talk that the source for this web site Firebird manual should be =
in the CVS tree at Firebird. That make sense to me. There's talk about =
it being in Docbook; I'll have a look at that.=20

Significantly, however, I want to get away from the classical model =
which is documenation professionals writing everything. There is so much =
work that we must go towards an open source model where anyone who knows =
something can check out the relevant portion of the 'manual', update it, =
and check it back in. The level of mandatory review is not yet clear.

To restate, what I want as a first cut is a web page user's manual tree =
of the topics, in name covering the material in the beta docs but in =
practice all the pages will be empty until somebody has the time to =
write them. There will probably be one higher level which functions as a =
documentation library, with one link into this web page user's manual =
tree.

If you, or anyone, can pry something loose from Borland it would help. =
Even the docs for InterBase 3 would be a help. If you want to work with =
me, if you want me to work with you, say the word. One way or another, =
we should do this on the Firebird-Docs list.

----- Original Message -----=20
From: "Joseph Alba" <ja...@il...>
To: <fir...@li...>
Sent: Monday, April 23, 2001 23:35
Subject: [Firebird-devel] Documentation


Hi to all Interbase newbies and devotees. This is Joseph Alba of the =
Interbase
documentation (see www.interbase2000.org). I would like to take your =
views on
how the Interbase documentation effort should begin, and how we should =
go about
it.

My goal is to have a weekly beta on the documentation. All who want to
contribute and comment are invited to write me privately at my email =
address
ja...@il...

As I mentioned to Helen, my experience as an independent developer makes =
me
careful about job specification, scope, and definition. I would like to =
deliver
a documentation set that is NOT an exhaustive tome of Interbase, but =
rather,
what Interbase users would want and need.

So, all suggestions and comments are welcome and needed. Please help. =
And please
reply in private to my email address

Thanks,

Joseph Alba
ja...@il...

[davidjencks@earthlink.net: Re: [Firebird-docs] Documentation Source Format]

[David J. <dav...@ea...>]

First time this went just to Andy, I'm forwarding to the list.
On 2001.04.22 21:44:32 -0400 David Jencks wrote:
Hi,

I suggested Docbook, more references later.  Here is what I recommend:

1. All sources in DocBook xml in cvs either in the main firebird
sourceforge project or in a separate documentation project.

2. Stylesheets, xml processors, xsl processors, xml to pdf processors also
in the sourceforge tree in a kind of bin directory.

3. Nightly or weekly (automated?) builds of xml to web html, printable
html, and pdf.  web html copied to main firebirdsql.org site, also zipped
up for ftp site.  Printable html and pdf also copied to ftp site.

4. Main contributors have cvs write access to xml source.  Everyone else
uses sourceforge patch process to submit changes/additions.

This process has the following advantages:
1. Everything is under version control. This is essential for any serious
project.

2. Everything is is a standard acsii based format.

3. Documentation can be produced automatically in many formats (three noted
above, I'm sure many more are possible).

4. Through use of xml, content is separated from presentation style. 
Authors can concentrate on logical structure of content, clear
explanations, etc, and don't have to worry about making it look nice.

5. Through use of xsl stylesheets, presentation style can be updated for
the entire documentation set at once, without having to reformat each page
individually.

6. <rant> xml is easier to write than html </rant>


Ok, hopefully you're convinced now.

I learned about docbook by writing some (unreleased) documentation for the
jboss project (www.jboss.org, also on sourceforge).  I looked at their
setup, spent a little time setting up emacs and psgml, and started writing.
 emacs+psgml fills in or suggests the allowable tags, provides tag by tag
navigation, and numerous other features I haven't begun to use yet.  It was
REALLY EASY to use--beats m$ word any day, IMHO.  Then I ran what I had
(pretty much preverified xml since psgml was suggesting all the tags based
on the dtd) through the ant transformation script, and voila, beautiful
documentation formatted way better than I could have done with days or
weeks of struggling with html.

So, here's what i suggest:

1. get ant, you'll need it for the compilation stuff.  
http://jakarta.apache.org/builds/ant/release/v1.3/bin/
You will need java, probably jdk 1.3 for ant and the xml/xsl
parsing/transformation.

2. borrow the jboss documentation stuff as an example.  I attach an ant
script that will check it out of cvs for you. Put this script in the folder
you would like the manual checked out into, and run it. I haven't used ant
in windows, but I believe it should work the same.  Command line is
ant -buildfile cvsmanual.xml

3.  Look at what they have.  Source xml docs are in manual/src/docs/, to
generate the documentation from source run the build.bat (build.sh in
linux) in the manual/src/build directory.

4. To write your own xml, you need a helpful editor.  emacs for windows is
discussed extensively at 
http://www.gnu.org/software/emacs/windows/ntemacs.html
which also mentions how to get psgml for xml editing.  The keybindings for
emacs are, well, unusual, but I have found them easy to get used to and
very much worth it.

There are other editors for xml available, none of which have I tried.  I
have seen Xeena from alphaworks.ibm.com mentioned several times but have so
far failed to download it successfully.  Maybe windows users will have
better luck.  I don't know if it is oriented more towards book-type docs or
data record type docs.

5. There are many resources for docbook, most of which I haven't looked at.
 A big mover is normal walsh, his web site http://www.nwalsh.com/ has lots
of information.  The official location of docbook is
http://www.oasis-open.org/.  Norman Walsh also (co) wrote a book from
OReilly, DocBook: the Definitive Guide.

6. One thing that will be necessary is to convert the jboss specific
stylesheet customizations to what we need.  I haven't looked at what would
be involved, but the changed at jboss to xml based documentation was
recent, done by one person, and didn't take all that long.

More questions? please ask.

Thanks
David Jencks

On 2001.04.22 10:28:32 -0400 Andy Canfield wrote:
> Here's what I see so far:
> 
> 1. A page available on the world wide web which is the top of a tree; the
> tree functions as a "User's Manual" for Firebird. Anyone on the World
> Wide Web can read the tree.
> 
> 2. Any reader can obtain the source for one of the pages on that tree. If
> the master source is HTML, then the page itself is the master source. If
> the master source is something else, then we'll need a link to obtain the
> source.
> 
> 3. Any reader can then update the material of that page and submit it.
> Certain trusted people can put it directly in the CVS tree; general
> population will have to e-mail it to a reviewer who will confirm and
> check it in.
> 
> 4. According to one poster, checking in something in the CVS tree can
> automatically update the documentation tree web site.
> 
> I did not originally envision using CVS simply because I'm not familiar
> with it, but I can imagine how it helps to be able to track back what
> changes were made when and by whom. It is not clear whether step [2]
> needs to include some kind of "Check out" operation.
> 
> I am leery of the master source being in some format other than HTML.
> HTML can be viewed by anyone on any computer using any browser. HTML can
> be edited by anyone on any computer using any ASCII text editor such as
> Notepad or VI. I certainly want readers to be able to make contributions
> without having to install special software on their machines. 
> 
> One distinction is that I don't see this as the production of a few
> documentation writers. I see this as the organized knowledge of the
> Firebird community. The more pretty we want the output, the fewer people
> we can get to contribute.
> 
> One note: when you make your suggestions, please remember that I am 12
> time zones from New York City. I am out of touch, somewhat out of date,
> and have no access to any UNIX computer. Someone suggesting using
> DocBook(x) xml format; please give me a link where I can learn about
> this. Thanks.
> 
> 
> 
> 
> _______________________________________________
> Firebird-docs mailing list
> Fir...@li...
> http://lists.sourceforge.net/lists/listinfo/firebird-docs
> 
<project name="jboss-cvs" default="cvs.checkout.all" basedir=".">

  <property name="cvs.dir" value="${basedir}/dev"/>
  <property name="cvs.repos" value=":pserver:ano...@cv...:/cvsroot/jboss"/>
  <property name="checkout.cmd" value="checkout"/>
  <property name="update.cmd" value="update -d -P"/>
  

  <target name="setup.cvs">
    <mkdir dir="${cvs.dir}"/>
  </target>


  <target name="cvs.checkout.manual" depends="setup.cvs">
    <cvs cvsRoot="${cvs.repos}"
       package="manual"
       dest="${cvs.dir}"
       command="${checkout.cmd}"
    />
  </target>
  
  
  <target name="cvs.checkout.all" depends="cvs.checkout.manual"/>
  

  <target name="cvs.update.manual" depends="setup.cvs">
    <cvs cvsRoot="${cvs.repos}"
       package="manual"
       dest="${cvs.dir}"
       command="${update.cmd}"
    />
  </target>
  
  
  <target name="cvs.update.all" depends="cvs.update.manual"/>
  

</project>

[Firebird-docs] Documentation Source Format

[Andy C. <an...@ad...>]

Here's what I see so far:

1. A page available on the world wide web which is the top of a tree; =
the tree functions as a "User's Manual" for Firebird. Anyone on the =
World Wide Web can read the tree.

2. Any reader can obtain the source for one of the pages on that tree. =
If the master source is HTML, then the page itself is the master source. =
If the master source is something else, then we'll need a link to obtain =
the source.

3. Any reader can then update the material of that page and submit it. =
Certain trusted people can put it directly in the CVS tree; general =
population will have to e-mail it to a reviewer who will confirm and =
check it in.

4. According to one poster, checking in something in the CVS tree can =
automatically update the documentation tree web site.

I did not originally envision using CVS simply because I'm not familiar =
with it, but I can imagine how it helps to be able to track back what =
changes were made when and by whom. It is not clear whether step [2] =
needs to include some kind of "Check out" operation.

I am leery of the master source being in some format other than HTML. =
HTML can be viewed by anyone on any computer using any browser. HTML can =
be edited by anyone on any computer using any ASCII text editor such as =
Notepad or VI. I certainly want readers to be able to make contributions =
without having to install special software on their machines.=20

One distinction is that I don't see this as the production of a few =
documentation writers. I see this as the organized knowledge of the =
Firebird community. The more pretty we want the output, the fewer people =
we can get to contribute.

One note: when you make your suggestions, please remember that I am 12 =
time zones from New York City. I am out of touch, somewhat out of date, =
and have no access to any UNIX computer. Someone suggesting using =
DocBook(x) xml format; please give me a link where I can learn about =
this. Thanks.

[Firebird-docs] Documentation Site

[Andy C. <an...@ad...>]

embedded responses follow; as you read, keep in mind this example: the =
Beta docs and Borland's SqlRef.HLP file contain, as far as I know, the =
only existing specification of the SQL syntax accepted by Firebird.

----- Original Message -----=20
From: "Helen Borrie" <he...@di...>
To: <fir...@li...>
Sent: Friday, April 20, 2001 16:30
Subject: Re: [Firebird-devel] Firebird/InterBase Documentation Sources

At 03:46 PM 20-04-01 +0700, Andy Canfield wrote:
>I am working on documentation.
>[snip]
>What I look for as a first goal is a web page which references all =
documentation files, containing copies where possible or mere links =
where copyright problems arise. Such a documenation site would serve as =
a centralized Internet reference source but would not yet be searchable =
due to the variety of formats.

> Are you sure you are not reinventing the wheel? =20
> this resource already exists, at www.ibphoenix.com...

I believe you are referring to=20
    http://www.ibphoenix.com/ibp_document.html
IBPhoenix is a commercial organization, not the Firebird project. While =
the IBPhoenix people are dedicated to Firebird, the site is company, not =
community. No obvious way to contribute exists. No obvious way to search =
it exists. No obvious way to add my two cents to one of the pages.

I don't like the structure, personally. For example, try going to that =
web page and and find out the command-line parameters to gbak.exe. It's =
not searchable, there's no entry that says "Here is the documentation of =
gbak". At a second level there is a link to "the relevant person" if you =
want to code for gbak, even so the link points to a page that is =
effectively blank.

From http://www.ibphoenix.com/ibp_document.html I can't tell what is and =
what is not documented. It looks like a resource shop, not an =
interactive manual. In some sense, if I asked for the Firebird =
documentation and someone handed me     =
http://www.ibphoenix.com/ibp_document.html I would would feel as if I =
had not been handed the documentation, but a place from which I might =
obtain the documentation. The page is an excellent source of =
downloadable documentation but it is not the document itself. It looks =
like the Firebird version of amazon.com. What I am thinking about is =
more like a web-based version of the Beta docs, with better structure =
and links to anything that doesn't embed. What I hope to build is the =
user's manual. The closest thing we have to a user's manual is the Beta =
Docs.

Just as www.ibphoenix.com is not Firebird code, it's a place where you =
can find out where to obtain Firebird code, so too it is not the =
documenation (manual), it is a place where you can find the =
documentation.

> The final version of the IB6 docs exists already - it is ready to =
print. =20
> Unfortunately, it is not owned by Borland;  however, since it is a=20
> corrected and updated version of the existing beta docs,=20
> the owners cannot publish it without infringing Borland's copyright=20
> and giving Borland's lawyers their day in court.
It must be owned by someone! If Borland has copyright and XYZ updates it =
then Borland and XYZ have, in some sense, joint copyright, yes? Who is =
XYZ? Presumably employees of XYZ have the right to read it. Who owns the =
stock of XYZ? Even if I can't publish it, reading it would teach me more =
about Firebird so that I can write more accurate documentation. I keep =
thinking of the syntax of the CREATE VIEW command; if the Beta Docs are =
wrong on that, someone somewhere should have noticed and written a =
correction. It's a correction I need to read.

> This ever-so-slightly interesting piece of resource material=20
> was a casualty of the u-know-wot, nudge-nudge, wink-wink,=20
> not allowed to mention without getting flamed, events of last July.
In preparation for building a document, I am wandering over the =
burned-out ruin in the hopes of finding bits and pieces that can be =
useful, one way or another. That's all. I don't care about who set the =
fire (I have my opinions). I'm doing it for Firebird; not for Borland, =
not for Ashton-Tate, not for Inprise, not for IBPhoenix, much as I may =
respect some of the people there.

The closest thing we have to a user's manual is the Beta Docs - =
copyright someone else, we can't distribute them, we can't correct them, =
we can't extend them. Borland is under no obligation to continue to =
provide them as free downloads. As time goes on the Beta Docs will =
become more and more inaccurate; how do we deal with this?

> Are you sure you are not reinventing the wheel? =20
Sure I am. That's because the existing wheel is copyrighted. When James =
Watt invented the steam engine, the obvious way to use it was via a =
crank shaft. But the crank shaft was patented by someone else, so Watt's =
company had to use planetary gears. The existing documentation is =
scattered and the copyrights on it are even more scattered. I'm hoping =
to create a virtual manual that everyone can contribute to.

[Firebird-docs] Documentation Site

[Andy C. <an...@ad...>]

(embedded responses)

----- Original Message -----=20
From: "Jeff Dodds" <je...@el...>
Newsgroups: sourceforge.firebird-devel
To: <fir...@li...>
Sent: Friday, April 20, 2001 19:42
Subject: Re: [Firebird-devel] Firebird/InterBase Documentation Sources
> Re: Documentation
>   If you are interested in creating new open source documentation for
> Firebird I am interested in helping out.  One of the major problems I =
see
> with the Firebird project is that they don't own the major =
documentation for
> their product, it can't bare the Firebird name, and it can't be =
modified and
> republished.

Thank you.

> I realize this is a Herculean task, but if we take it slow and step by =
step
> it should be possible.

If we take it slow and step by step it may take ten years. If we can get =
a million monkeys working on it it may take only six months.=20

>   I also realize the current documentation is excellently and expertly
> written and that we would not be able to use it, except as a reference
> source.  I would work with the full knowledge and hope that my work =
would
> someday (or quickly) be rewritten and I would freely allow it to be.  =
I
> don't wish to hold any copyright over the material, I think at this =
time, it
> would only slow down the process of building a new documentation =
source.

Great! That's what we need.

>   Do you have a webspace where this new work could begin to be =
published?

As of 2001/04/22 02:32 GMT all these gave "The page cannot be displayed"
    http://www.firebirdsql.org/
    http://firebirdsql.org/
    http://firebirdsql.net/
    http://www.firebirdsql.net/
    http://firebirdsql.com/
    http://www.firebirdsql.com/
I'd like one of them to lead to a web page which has a "Documentation" =
link that leads to what I'm doing. Whether that is stored on IBPhoenix =
or SourceForge or elsewhere. As I understand it, the Domain name / IP =
address link is flexible enough that it can point into such a location, =
and it can be moved if problems arise. As long as it's under the control =
of the Firebird community. I could plop it on LaoNet but the link from =
Vientiane to the rest of the world would slow down everyone. I expect =
that one or more of our Firebird community people will donate space.=20

[Firebird-docs] Re: [Firebird-admin] Documentation

[Mark O'D. <mar...@lu...>]

Hi Helen

All sounds pretty good stuff, and it's sounds like some sort of solution 
to our documentation conundrum. 

I think the linux documentation uses the SGML suite of tools.  I looked 
at it a but, but not much.  They generate html, ps, txt versions from 
the source.

Bill would be good to get involved, I understand he had a lot of his own 
stuff anyway that could help.

On the sourceforge stuff, they seem to be over their initial growth 
pains, and are a bit more reliable recently.  Depending upon how you go 
it might be worth useing, CVS is pretty good at distributed development, 
and that seems to be how this is also going to work.

Cheers

Mark


Helen Borrie wrote:

> Hi All,
> 
> Recently, folk have started rumbling about documentation, which is 
> GOOD.  Bear with me while I brainstorm a little here...
> 
> 1.  A radical plan which is formulating in the green, greasy depths of 
> my mind is to give up on the IBDH project - not because it aint great 
> (we REALLY need that book) but because it's financially out of reach 
> for me to do it as planned.  However, for a developer book, its 
> outline is good - the result of many eyes and hands.  I have more 
> stuff to add to the outline - ideas continue to come through - so that 
> I think we have the bases pretty well covered already through 
> community effort.
> 
> With the permission of my translators (who are a good and rational 
> bunch, for sure) I would like to transmogrify the IBDH project into 
> the Firebird Documentation project.
> 
> A bonus in this might be that I/we can persuade Bill Karwin to come 
> aboard such a project, now that the angst has subsided.  Bill himself 
> outlined an ambitious Open Document project for documenting IB, from 
> all angles.  I would be willing to take on the role of manager/editor, 
> much as I planned for the IBDH.  It would be so much the better for 
> Bill's participation.
> 
> 2.  At the time the IBDH was conceived, it was in the context that ISC 
> was planning to publish the updated IB 6 manuals.  We could change the 
> content and organisation of material in Ann's publication-ready 
> version radically to circumvent copyright restrictions.  The rewriting 
> and re-editing of the content would be well within my range.  There is 
> no copyright on the intellectual content of these docs.  In my view, 
> the IB6 Manuals' organisation is still very poor.  We could kill two 
> birds with one stone by reusing the ISC work in a revised, expanded 
> and more user-friendly documentation set.
> 
> 3.  As to format... I'm one who likes to have a well-indexed book on 
> hand in preference to anything in electronic format.  There are lots 
> who agree with me;  and just as many who prefer helpfiles, html, PDFs 
> or whatever.  The "infrastructure" of the IBDH was on track to store 
> all the content in a database and apply various processing tracks to 
> it to enable output in many formats - hard-copy drafts, print-ready 
> copy, HTML, Linux How-To, etc.  Obviously the means to this end is XML 
> and Unicode.  If we can persuade all contributors to submit material 
> in plain text Unicode, we can keep things open for alternative outputs 
> to suit whatever requirements arise.
> 
> 4.  Incorporating the sourcecode development stuff...we need to get 
> this under some form of version control, I think.  I certainly have 
> provision for it in the IBDH database structure.  If we can have a 
> server somewhere that is dedicated just to documentation, I believe we 
> can do some good management and version control that doesn't suffer 
> from the vicissitudes of Sourceforge.  They do it in the Linux 
> projects and IMO it works well.
> 
> Well, just some embryonic thoughts...
> 
> Helen
> 
> All for Open and Open for All
> InterBase Developer Initiative · http://www.interbase2000.org
> _______________________________________________________
> 
> _______________________________________________
> Firebird-admin mailing list
> Fir...@li...
> http://lists.sourceforge.net/lists/listinfo/firebird-admi
> n



-- 
Your database needs YOU!
http://firebird.sourceforge.net