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

GRASS GIS GRASS GIS developer
1

Hi guys,

Borrowing heavily from my conversations with Maciek, I have written a
step-by-step how-to for improving Grass documentation, specifically man
pages. I welcome any feedback and suggestions for improvement. My knowledge
of html is pretty basic, hopefully there aren't too many errors. It looks OK
to me in Firefox. I was thinking perhaps this page could be linked/inserted
into the main Grass GDP page, so it can be easily found for those who are
interested in improving the documentation.

Let me know what you think,

~ Eric.

-----Original Message-----
From: grass-dev-bounces@grass.itc.it
To: GRASS developers list
Cc: pkg-grass-general@lists.alioth.debian.org; grass-announce@grass.itc.it
Sent: 9/26/2006 10:29 AM
Subject: [GRASS-dev] GRASS 6.2.0RC1 released

Hi,

I have packaged the GRASS 6.2.0RC1 release:
http://grass.itc.it/grass62/source/

Fixes:
    * d.vect.thematic -s fixes (michael)
    * Vietnamese translation (Bui Huu Manh)
    * reverted Pbuffer changes in NVIZ (Brad)
    * projection codes updated to EPSG 6.11 (Markus)
    * g.region zoom= off by one error (Glynn)
    * fix hardcoded Helvetica tcl fonts to a single file setting (in
$GISBASE/etc/gtcltk/options.tcl) (michael)

Thanks to all contributors. Please test rigorously...
especially gis.m.

Thanks
Markus

_______________________________________________
grass-dev mailing list
grass-dev@grass.itc.it
http://grass.itc.it/mailman/listinfo/grass-dev

(attachments)

Updating_Docs_How-to.html (3.09 KB)

2

I haven't read the file in detail, but think in principle this is an excellent contribution. I'd love to help by doing a debug run through the instructions. I probably won't be able to get to it until the weekend, though.

Cheers,
Scott

On 26 Sep 2006, at 11:09, Patton, Eric wrote:

Hi guys,

Borrowing heavily from my conversations with Maciek, I have written a
step-by-step how-to for improving Grass documentation, specifically man
pages. I welcome any feedback and suggestions for improvement. My knowledge
of html is pretty basic, hopefully there aren't too many errors. It looks OK
to me in Firefox. I was thinking perhaps this page could be linked/inserted
into the main Grass GDP page, so it can be easily found for those who are
interested in improving the documentation.

Let me know what you think,

~ Eric.

-----Original Message-----
From: grass-dev-bounces@grass.itc.it
To: GRASS developers list
Cc: pkg-grass-general@lists.alioth.debian.org; grass-announce@grass.itc.it
Sent: 9/26/2006 10:29 AM
Subject: [GRASS-dev] GRASS 6.2.0RC1 released

Hi,

I have packaged the GRASS 6.2.0RC1 release:
http://grass.itc.it/grass62/source/

Fixes:
    * d.vect.thematic -s fixes (michael)
    * Vietnamese translation (Bui Huu Manh)
    * reverted Pbuffer changes in NVIZ (Brad)
    * projection codes updated to EPSG 6.11 (Markus)
    * g.region zoom= off by one error (Glynn)
    * fix hardcoded Helvetica tcl fonts to a single file setting (in
$GISBASE/etc/gtcltk/options.tcl) (michael)

Thanks to all contributors. Please test rigorously...
especially gis.m.

Thanks
Markus

_______________________________________________
grass-dev mailing list
grass-dev@grass.itc.it
http://grass.itc.it/mailman/listinfo/grass-dev

<Updating_Docs_How-to.html>
_______________________________________________
grass-dev mailing list
grass-dev@grass.itc.it
http://grass.itc.it/mailman/listinfo/grass-dev

3

Eric wrote:

Borrowing heavily from my conversations with Maciek, I have written a
step-by-step how-to for improving Grass documentation, specifically
man pages. I welcome any feedback and suggestions for improvement. My
knowledge of html is pretty basic, hopefully there aren't too many
errors. It looks OK to me in Firefox. I was thinking perhaps this page
could be linked/inserted into the main Grass GDP page, so it can be
easily found for those who are interested in improving the
documentation.

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. Can you put this up on the wiki? (probably in
the development section) The sooner the GDP is migrated out of the web
site CVS and into the wiki and truely group maintained the better for
everyone IMO. [ps. -- is the wiki being backed up? available as .zip
for burning to a CD for access to help when in the field?]

Let me know what you think,

Add a link to help page translation efforts?

To begin, you must obtain the latest Grass source code from the CVS
repositories.

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.

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

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.

There's no reason you can't make a copy and work from that, and no
reason you have to be root. The CVS source doesn't need to have any
superuser access, it's proably very good advice that it isn't given such
rights. "cvs diff" may no longer work, but that's not the end of the
world if you hung on to the original.

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

thanks,
Hamish

4

On Mon, Oct 02, 2006 at 06:38:36PM +1300, Hamish wrote:

Eric wrote:

> Borrowing heavily from my conversations with Maciek, I have written a
> step-by-step how-to for improving Grass documentation, specifically
> man pages. I welcome any feedback and suggestions for improvement. My
> knowledge of html is pretty basic, hopefully there aren't too many
> errors. It looks OK to me in Firefox. I was thinking perhaps this page
> could be linked/inserted into the main Grass GDP page, so it can be
> easily found for those who are interested in improving the
> documentation.

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. Can you put this up on the wiki? (probably in
the development section)

Yes, please put it onto the Wiki.
The current CVS approach of maintaining the Web pages doesn't scale
up at all.

The sooner the GDP is migrated out of the web
site CVS and into the wiki and truely group maintained the better for
everyone IMO. [ps. -- is the wiki being backed up?

Yes, backup'ed.

available as .zip
for burning to a CD for access to help when in the field?]

Nice to have. How to implement it?

A related consideration:
Should we move to a Content Management System like Drupal or
Joomla? If yes, will folks participate to migrate the Web
site contents? The only major problem is how to feed the
mirror sites (make a static copy overnight and rsync that?).

Markus

5

Markus Neteler wrote:

> The sooner the GDP is migrated out of the web
> site CVS and into the wiki and truely group maintained the better
> for everyone IMO. [ps. -- is the wiki being backed up?

Yes, backup'ed.

> available as .zip
> for burning to a CD for access to help when in the field?]

Nice to have. How to implement it?

cron job on the wiki server, downloadable as an attachment from the wiki
server?

A related consideration:
Should we move to a Content Management System like Drupal or
Joomla? If yes, will folks participate to migrate the Web
site contents? The only major problem is how to feed the
mirror sites (make a static copy overnight and rsync that?).

what's the advantage over SVN with a wider range of folks with write
access? We want to keep some sort of control over who can edit the core
website pages, but not restrict it to programmers only.

Hamish

6

On Wed, Oct 04, 2006 at 06:48:27PM +1300, Hamish wrote:

Markus Neteler wrote:
> > The sooner the GDP is migrated out of the web
> > site CVS and into the wiki and truely group maintained the better
> > for everyone IMO. [ps. -- is the wiki being backed up?
>
> Yes, backup'ed.
>
> > available as .zip
> > for burning to a CD for access to help when in the field?]
>
> Nice to have. How to implement it?

cron job on the wiki server, downloadable as an attachment from the wiki
server?

You mean the MySQL DB? I would need a pointer how to do that.

> A related consideration:
> Should we move to a Content Management System like Drupal or
> Joomla? If yes, will folks participate to migrate the Web
> site contents? The only major problem is how to feed the
> mirror sites (make a static copy overnight and rsync that?).

what's the advantage over SVN with a wider range of folks with write
access? We want to keep some sort of control over who can edit the core
website pages, but not restrict it to programmers only.

After 4-5 years of Web pages in CVS, I don't think that a change
to SVN will make a big change.
Content Management Systems usually come with user roles, so that pages
could be maintained at various levels. But I see, interest in
CMS is also fairly low...

Markus