[work] [Qgis-community-team] documentation format

[Otto Dassau]

Hi Tara, 

I would also propose to work with latex, at least for the moment. As Gary and
Stephan said, everything is there and working, so you don't have to learn much
to get started, it is flexible and there are many people (incl. me), who
are willing and able to help and assist, if there are problems. We already
thought of changing to another tool, but always came back to latex.  

If you like you can nominate Stephan, Otto and many other people in the project
as "latex admins", so you don't have to worry, if something doesn't work.

If the long run I agree, it might make sense to switch to another system,
especially when I think of a smooth and easy translation of the master
document. This is currently more difficult (labour-intensive) and not solved,
but we all will help you there as well and find the best solution together.

From my point of view, you don't have to be a latex guru at all and all you need
to know about latex to contribute, coordinate and lead the documentation process
is really very limited - no need to worry about ;-)

regards,
 Otto

On Mon, 5 May 2008 06:40:52 +0200
Stephan Holl <stephan.holl at intevation.de> wrote:

> Hi,
> 
> Am Montag, 5. Mai 2008 02:20:53 schrieb Tara Athan:
> > Hello, all! In a moment of madness, I agreed to lead the QGIS
> > documentation team. Currently, the documentation is developed in latex
> > and then exported to html and pdf formats. I see a few problems with this:
> > 1. documentation contributors have to learn latex or someone has to be
> > the middle-man to convert their contributions to latex
> > 2. latex mixes presentation and structural markup- recommended practice
> > is to separate them
> > 3. I haven't used latex in over 20 years.
> > So I would like to propose that we change to a different format
> > (understanding full well and accepting the responsibility for converting
> > from the old format to the new)
> >
> > In this reference
> >
> > <http://en.tldp.org/HOWTO/Software-Release-Practice-HOWTO/documentation.htm
> >l> Docbook is recommended. After a quick perusal of some introductory
> > material, such as
> >   <http://docbook.org/tdg/en/html/ch01.html>
> > it is looking like a good choice to me.
> > There is an application for converting from laTex to DocBook
> >    <http://www.cse.ohio-state.edu/~gurari/TeX4ht/>
> >
> > I would like to know if anyone on the team has experience in using this
> > format and can offer advice as to whether this would  be a good idea.
> 
> I have worked with latex for documentation for several year now and I think 
> that it is worth learning it!
> 
> From my point of view we should use our time to complete the docs in latex and

> not waste time in converting from on to another format.
> 
> I can offer a hand to fix some latex-issues if needed since I am quite 
> familiar with the latex-code used in the docs.
> 
> just my 0,02¢
> 
> Best regards
> 
> 	Stephan Holl
> 
>