firebird-docs

[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.

[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>