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

[Gary Sherman]

On May 4, 2008, at 4:20 PM, Tara Athan wrote:
> 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:

I have used both Docbook and Latex to develop documentation and  
frankly I prefer Latex. I find it more flexible and the tool set is  
mature and established.
Below are some of my observations.

> 1. documentation contributors have to learn latex or someone has to be
> the middle-man to convert their contributions to latex

The learning curve is pretty gentle, especially since the document  
setup is done. If you are going to use Docbook, you are going to have  
to learn that as well. Building the document is as simple as running  
"make"

 From the tldp document link below you'll find this statement  
regarding Docbook:
"Its drawbacks are complexity, a not entirely mature (though rapidly  
improving) toolset, and introductory-level documentation that is  
scanty and (too often) highly obfuscated."

Latex on the other hand has volumes of good reference and tutorial  
material.

> 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.html 
> >
> 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.
>
As I said, I've used both---I prefer Latex.

My 2cents...

-gary

> Thanks, Tara
> _______________________________________________
> Qgis-community-team mailing list
> Qgis-community-team at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/qgis-community-team
>
> _______________________________________________
> Qgis-community-team mailing list
> Qgis-community-team at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/qgis-community-team

-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-
Gary Sherman
Chair, QGIS Project Steering Committee
-Micro Resources: http://mrcc.com
   *Geospatial Hosting
   *Web Site Hosting
-Desktop GIS Book:
   *http://desktopgisbook.com
"We work virtually everywhere"
-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-