[GRASS-dev] Grass Documentation How-to html page

[Patton, Eric]

-----Original Message-----
From: Hamish
To: Patton, Eric
Cc: grass-dev at grass.itc.it
Sent: 10/2/2006 1:38 AM
Subject: Re: [GRASS-dev] Grass Documentation How-to html page

Eric wrote:
>> Borrowing heavily from my conversations with Maciek, I have written a
>> step-by-step how-to for improving Grass documentation

Hamish:
>Glad to see this, sometimes with GRASS development I think (like GIS)
>often the answers are simple to find & easy to enact, *if you know where
>to look* before you start looking. This sort of tutorial goes a long way
>to fixing that problem. 

Thanks.

Hmaish:
>Can you put this up on the wiki? (probably in the development section)

Sure.

Hamish:
>Add a link to help page translation efforts?

Sure.

Hamish:
>link to the CVS web interface, or write a script to pluck the latest
>description.html file for any given module. (aim for really low barrier
>to entry) Little html experience is needed.

I thought I had included a link to the CVS how-to :

"To begin, you must obtain the latest Grass source code from the CVS
repositories. Detailed instructions on how to do so can be found <a
href:"http://grass.itc.it/faq/cvs_howto">here.</a>"

But I think I got the formatting wrong, because this link is broken; it just
links back to itself. Actually, all the html links don't work. Can you see
anything obviously wrong?

Hamish:
>Note how to add images. (r.terraflow, v.voronoi,...)
>see doc/html_documentation.txt

Ok, I'll have to brush up on how to do this, as I've never tried it yet.

Eric:
>> Once you have downloaded the CVS source code, open a terminal and
>> change directory to /your_cvs_directory/grass6/vector/v.in.ascii. You
>> have to make your edits/corrections to the original copy of the
>> module's description.html page within grass6/vector/v.in.ascii, not a
>> copy of this page.
>> Open a text editor and make your edits to description.html. Depending
>> on where your cvs source is on disk, you may have to do so as root
>> (Ex: sudo gedit description.html). Save your edits by overwriting the
>> original description.html.

Hamish:
>There's no reason you can't make a copy and work from that, and no
>reason you have to be root. T "cvs diff" may no longer work, but that's not
the end of the
>world if you hung on to the original.

Maciek had advised me to make diffs from the original description html,
because I had tried diffing a copy of a manpage somewhere in /home, and he
had problems applying it to CVS. (?) I'm not sure why it didn't work, just
following suggestions. I'll CC: him on this to see why.

Hamish:
>The CVS source doesn't need to have any superuser access, it's proably very
good advice that >it isn't given such rights.

My cvs source is located in /opt, where my Grass installation folder is
located, so that's probably why I wrote that. I'll modify that to include
your suggestions.

Hamish:
>If editing in the source tree is a problem, just make a copy of the file
>and:

>diff -u /usr/src/grass/.../description.html description.html.NEW

I think this was what I tried originally with Maciek, where we ran into
problems. Not sure. Aanyway, I'll change the how-to to mention that one copy
any description.html into a safe place like /home, make edits, then create a
diff -u against their source description.html - sound good?

Thanks for the feedback,

~ Eric.