firebird-docs

[Firebird-docs] Building new Firebird docs

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

Hi all,

A number of people have expressed interest in helping with the docs
lately, so this might be a good time to discuss what kind of
documentation we would like to produce, and how we are going to set
things up.

But first, if you are new to the Firebird Documentation subproject,
read this webpage if you haven't already done so; it contains a lot
of information about the tools you are going to need:

  http://
  firebird.sourceforge.net/index.php?op=devel&sub=doc&id=development

Also follow the links in the section titled "Environment setup".

NOTE: Do not yet checkout ("download") the manual module from the
Firebird CVS tree at SourceForge. In the current state the doc
building process doesn't work. Tilo fixed it, but it seems the
changes didn't make it to the CVS tree yet.

(Well you can still checkout the module of course, to test your
CVS setup :-))

TIP: For XML editing, I prefer XMLMind because it really lets you
work with the *structure* of your document. Being Java-based, it
loads slowly and it also has one big drawback: it won't let you work
in source (flat text) mode. Still, I prefer it to the others I've
tested. The Standard Edition is free; you can find it at:

  http://www.xmlmind.com/xmleditor/


Later,
Paul Vinkenoog

Re: [Firebird-docs] Building new Firebird docs

[Herman T. <tim...@sk...>]

Paul Vinkenoog wrote:

> Hi all,
> 
> A number of people have expressed interest in helping with the docs
> lately, so this might be a good time to discuss what kind of
> documentation we would like to produce, and how we are going to set
> things up.
> 
> But first, if you are new to the Firebird Documentation subproject,
> read this webpage if you haven't already done so; it contains a lot
> of information about the tools you are going to need:
> 
>   http://
>   firebird.sourceforge.net/index.php?op=devel&sub=doc&id=development
> 
> Also follow the links in the section titled "Environment setup".
> 
> NOTE: Do not yet checkout ("download") the manual module from the
> Firebird CVS tree at SourceForge. In the current state the doc
> building process doesn't work. Tilo fixed it, but it seems the
> changes didn't make it to the CVS tree yet.
> 
> (Well you can still checkout the module of course, to test your
> CVS setup :-))
> 
> TIP: For XML editing, I prefer XMLMind because it really lets you
> work with the *structure* of your document. Being Java-based, it
> loads slowly and it also has one big drawback: it won't let you work
> in source (flat text) mode. Still, I prefer it to the others I've
> tested. The Standard Edition is free; you can find it at:
> 
>   http://www.xmlmind.com/xmleditor/
> 
Why not just writing the documentation in OpenOffice?
It is open source, multi-platform, you can produce PDF and  RTF and DOC 
formats as well, and the internal format is XML based (if I'm not 
mistaking?)
Brgds,
Herman

-- 
Suse Linux Professional 8.1 on Athlon 1.1 Ghz 512 Mb
Anti Spam = remove the "dot" and the "at"
Registered Linux User #264690

Re: [Firebird-docs] Building new Firebird docs

[Robert (J. M. <rj...@ar...>]

Herman Timmermans wrote:

> Why not just writing the documentation in OpenOffice?
> It is open source, multi-platform, you can produce PDF and  RTF and DOC 
> formats as well, and the internal format is XML based (if I'm not 
> mistaking?)

Because it is way too flexible, and the documentation will end up in a 
big mess.

The documentation needs to be in a simple framework, with things like 
headings, SQL code snippets, other code snippets etc. identified clearly 
and consistently wherever they appear, so that when converting to other 
formats, they can remain consistent. Rules can then be enforced, like 
not having a title in the middle of a block of code. Diff and merge 
operations could be performed when people edit things, allowing 
different peoples ideas to be merged semi-automatically, which just 
couldn't be done with an office type package.

Robert Munro