firebird-docs

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

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

I downloaded 'ant', which requires a java package. I've downloaded the =
java package but haven't installed it yet. If and when I get them =
working I can run the script to download jboss which is supposed to be a =
sample set of manuals in DocBook format.

At the moment it's seems like a bit of work. If I can just email my =
stuff to Joseph Alba, and let him worry about pasting it into some HTML =
generator system, I'll skip it. I can tell you exactly what DocBook DTD =
I use; none yet. The one chunk I submitted so far was RTF (Rich Text =
Format), which is like a DOC file only not binary and not propriatary. =
When my FoxPro or C++ code wants to crank out a report, it generates an =
RTF file which I distribute by diskette or email.

----------- Previous Message --------------
From: "Tilo Muetze" <tm...@iq...>
To: <fir...@li...>
Date: Thu, 26 Apr 2001 16:25:24 +0200
Organization: IQ Compusulting
Subject: [Firebird-docs] Re: Firebird-docs digest, Vol 1 #6 - 4 msgs

Andy, Joseph and other who wan't to contribute to the documentation,
I've downloaded, installed and tried to use Docbook but it is really
complicated to start. If anyone out there has already put together the =
frame
for the documentation using Docbook please tell me.
I've seen a message from Andy containing a first draft of the Firebird =
docu,
but as I only have digest mode I can not download the attachment, so =
please
tell me which format you have used!

Re: [Firebird-docs] DocBook

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

Hi,

I will try to get some framework set up for us.  This all requires more
experimentation, but it will probably be easier to convert plain text to
xml than rtf to xml.  On the other hand, if we do get the framework on
sourceforge, you could just write the stuff in xml and not worry about the
conversion ( if you got emacs+psgml set up).  Is it easy to go rtf to plain
text? Are there linux rtf editors?

thanks
david jencks



On 2001.04.27 07:26:03 -0400 Andy Canfield wrote:
> I downloaded 'ant', which requires a java package. I've downloaded the
> java package but haven't installed it yet. If and when I get them working
> I can run the script to download jboss which is supposed to be a sample
> set of manuals in DocBook format.
> 
> At the moment it's seems like a bit of work. If I can just email my stuff
> to Joseph Alba, and let him worry about pasting it into some HTML
> generator system, I'll skip it. I can tell you exactly what DocBook DTD I
> use; none yet. The one chunk I submitted so far was RTF (Rich Text
> Format), which is like a DOC file only not binary and not propriatary.
> When my FoxPro or C++ code wants to crank out a report, it generates an
> RTF file which I distribute by diskette or email.
> 
> ----------- Previous Message --------------
> From: "Tilo Muetze" <tm...@iq...>
> To: <fir...@li...>
> Date: Thu, 26 Apr 2001 16:25:24 +0200
> Organization: IQ Compusulting
> Subject: [Firebird-docs] Re: Firebird-docs digest, Vol 1 #6 - 4 msgs
> 
> Andy, Joseph and other who wan't to contribute to the documentation,
> I've downloaded, installed and tried to use Docbook but it is really
> complicated to start. If anyone out there has already put together the
> frame
> for the documentation using Docbook please tell me.
> I've seen a message from Andy containing a first draft of the Firebird
> docu,
> but as I only have digest mode I can not download the attachment, so
> please
> tell me which format you have used!
> 
> 
> 
> 
> _______________________________________________
> Firebird-docs mailing list
> Fir...@li...
> http://lists.sourceforge.net/lists/listinfo/firebird-docs
> 

[Firebird-docs] Reducing the burden

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

Random and off the wall thought.  Suppose you don't
explain SQL at all.  There are tons of books about
SQL - some quite good.  If we explain how we differ
from the descriptions in one of those books, you'll
have somewhat less of the boring part to write and
can spend time worrying about important stuff like
connection strings.

Cheers,

Ann

Re: [Firebird-docs] DocBook

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

""Andy Canfield"" <an...@ad...> schrieb im Newsbeitrag
news:001101c0cf0c$fcb8caa0$3f1bfea9@think6...
> At the moment it's seems like a bit of work. If I can just email my =
> stuff to Joseph Alba, and let him worry about pasting it into some HTML =
> generator system, I'll skip it. I can tell you exactly what DocBook DTD =
> I use; none yet. The one chunk I submitted so far was RTF (Rich Text =
> Format), which is like a DOC file only not binary and not propriatary. =
> When my FoxPro or C++ code wants to crank out a report, it generates an =
> RTF file which I distribute by diskette or email.

I know exactly where you talking about. The whole Docbook setup is not the
simplest task. But if David will setup an framework for us, I will put it on
a website with exact information how to get started.
--

Regards,
Tilo Muetze
IQ Compusulting
www.iq-c.de

[Firebird-docs] DocBook

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

> I will try to get some framework set up for us.  This all requires =
more
> experimentation, but it will probably be easier to convert plain text =
to
> xml than rtf to xml.  On the other hand, if we do get the framework on
> sourceforge, you could just write the stuff in xml and not worry about =
the
> conversion ( if you got emacs+psgml set up).  Is it easy to go rtf to =
plain
> text? Are there linux rtf editors?

As far as I know, rtf is a non-proprietary format. On the other hand, =
the detailed description I have is labelled "Microsoft Technical =
Support"; I hadn't noticed that.

If you open the RTF document under Windows (It can be read by Word or by =
WordPad which is bundled with Windows or with Word Viewer which is =
downloadable for free from Microsoft), then you can cut and paste into =
any editor that runs on Windows. But this would only preserve the =
attributes, and not provide structure ( section, subsection, heading, =
etc. ).

RTF is ASCII text with a bunch of formatting codes. Much like HTML, =
except that the codes look like "\par" instead of "<BR>". AFAIK, there =
is no equivalent to the HTML link capability. If you have an RTF file, =
read it with any ASCII text editor and you'll see the codes; you can =
then replace the RTF codes with HTML codes or, better yet, wait until =
we've got something like DocBook working and standardized and replace =
the RTF codes with the DocBook XML codes. I'm just cranking out =
(formatted) text right now.

Assuming we go ahead with DocBook, we need somebody to tell us what =
codes to put in at what spots. The XML has many different ways to do =
things. Presumably DocBook is one set of codes. But what do we have that =
is called <SECTION> ... </SECTION> and what do we have that is called =
<DIVISION> ... <DIVISION>, etc.? Someone should decide and tell the rest =
of us.

Of course, at that point, we will be two sets of writers; those who have =
DocBook up and running and those who do not. Any person can check out =
the source and edit the source file (which contains the DocBook codes), =
but only the first group will be able to see the results formatted =
before checking it back in. Once we've got the layout instructions, I =
will try to get DocBook working on my machine and personally convert =
Connections.rtf to the proper DocBook codes as a learning test case.