[Qgis-community-team] Re: documentation format

[Otto Dassau]

Hi Tara, 

have you read the information at the DocumentationWritersCorner? For Windows
there is a SVN-client named "Tortoise SVN". The download page is here:

http://tortoisesvn.net/downloads

I only don't know good latex editors, so here others can help, also give some
hints to get into it:

Step 1) checkout from svn:
- install the tortoise svn tool and reboot
- right mouse click on the desktop and select SVN checkout (popup window)
- in the popup window enter repo URL to english  master doc in head:
  https://svn.osgeo.org/qgis/docs/trunk/english_us/user_guide and checkout dir:
  e.g.  \xxx\xxx\Tara\Desktop\qgis-user_guide 
-> this checks out only the english userguide without translation branches
  at the moment, enogh for the beginning I think 

Step 2) edit latex files:
- change into trunk: \xxx\Tara\Desktop\qgis-docs\user_guide\
- latex text sources are in *.tex files
- now you need a latex editor and I don't know what tool is nice to use for
  windows, so others need to help.

Step 3) commit changes back to svn:
- inside the user_guide folder with a right mouse -> TortoiseSVN you can
  commit, check for modifications etc.

hope this helps for the beginning. Help for Tortoise SVN is availble here:
http://tortoisesvn.net/docs/release/TortoiseSVN_en/index.html

regards,
 Otto


On Mon, 05 May 2008 07:17:13 -0700
Tara Athan <tara_athan at alt2is.com> wrote:

> Well, OK I'll give it a try. Do we have a set of instructions for someone just
> getting started contributing to documentation? I am finding it difficult to
> get off the ground here.  What I am looking for is:
> 1. how to get a copy of the primary documentation, ie the latex source
> 2. a template for the markup
> 
> Thanks, Tara
> 
> 
> Otto Dassau wrote: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.
> 
> 
> Best regards
> 
> 	Stephan Holl
> 
> 
>     
>   
>