[GRASS-dev] Re: Call for documentation help

GRASS GIS GRASS GIS developer
1

WRT documentation standards, I ran a few small scripts on the source directory tree for the display, general, raster, and vector commands to see how much variation there is in the use of different headings and sections within the description.html pages.

I've attached the listing for the raster commands; as you can see, there's a fair bit of variation in the wording of sections in the html pages. If the goal is to use a uniform documentation style, we should probably figure out which headings are going to be accepted. I know it's not the most pressing issue, but a common style could save a lot of work in re-writes in the future.

OTOH, it may be deemed more important to allow flexibility in the use of headings for each module's html page.

Ideas?

~ Eric.

(attachments)

Raster_Command_description.html_headings.txt (16.4 KB)

2

Eric wrote:

WRT documentation standards, I ran a few small scripts on the source
directory tree for the display, general, raster, and vector commands to see
how much variation there is in the use of different headings and sections
within the description.html pages.

I've attached the listing for the raster commands; as you can see, there's a
fair bit of variation in the wording of sections in the html pages. If the
goal is to use a uniform documentation style, we should probably figure out
which headings are going to be accepted. I know it's not the most pressing
issue, but a common style could save a lot of work in re-writes in the
future.

OTOH, it may be deemed more important to allow flexibility in the use of
headings for each module's html page.

Ideas?

Auto-generated (usually)

<H2>NAME</H2>
<H2>KEYWORDS</H2>
<H2>SYNOPSIS</H2>

* = Required
! = Suggested
. = Optional

In recommended order
--------------------

* <H2>DESCRIPTION</H2>
! <H2>NOTE</H2>, <H2>NOTES</H2>
! <H2>EXAMPLE</H2>, <H2>EXAMPLES</H2>
. <H2>TODO</H2>
. <H2>BUGS</H2>
. <H2>REFERENCE</H2>, <H2>REFERENCES</H2>
* <H2>SEE ALSO</H2>
* <H2>AUTHOR</H2>, <H2>AUTHORS</H2>

more in this added to the wiki page:
http://grass.gdf-hannover.de/wiki/Updating_GRASS_Documentation

Hamish

__________________________________________________
Do You Yahoo!?
Tired of spam? Yahoo! Mail has the best spam protection around
http://mail.yahoo.com

3

Eric:

If the goal is to use a uniform documentation style, we should probably figure out
which headings are going to be accepted. I know it's not the most pressing
issue, but a common style could save a lot of work in re-writes in the
future.

Hamish:

Auto-generated (usually)

<H2>NAME</H2>
<H2>KEYWORDS</H2>
<H2>SYNOPSIS</H2>

* = Required
! = Suggested
. = Optional

In recommended order
--------------------

* <H2>DESCRIPTION</H2>
! <H2>NOTE</H2>, <H2>NOTES</H2>
! <H2>EXAMPLE</H2>, <H2>EXAMPLES</H2>
. <H2>TODO</H2>
. <H2>BUGS</H2>
. <H2>REFERENCE</H2>, <H2>REFERENCES</H2>
* <H2>SEE ALSO</H2>
* <H2>AUTHOR</H2>, <H2>AUTHORS</H2>

more in this added to the wiki page:
http://grass.gdf-hannover.de/wiki/Updating_GRASS_Documentation

Hamish

Thanks for the feedback. This will form a good base to build on. The wiki page is much improved, too!

~ Eric.

4

Hi,

I am a bit out of the loop and don't know what is going on for translations of
the help pages .. the task seems to me too huge + a moving target to worry
about doing formally with our available peoplepower. They'd always be a little
out of date.

I don't know how AltaVista feels about live linking, but on the wiki I've added
experimental links to the Babelfish translator for the 6.3 online help pages:

  http://grass.gdf-hannover.de/wiki/Updating_GRASS_Documentation#Translations

They support the following languages:

Chinese - Simplified
Chinese - Traditional
Dutch
French
German
Greek
Italian
Japanese
Korean
Portuguese
Russian
Spanish

Hamish

__________________________________________________
Do You Yahoo!?
Tired of spam? Yahoo! Mail has the best spam protection around
http://mail.yahoo.com

5

On 09/11/07 04:27, Hamish wrote:

Hi,

I am a bit out of the loop and don't know what is going on for translations of
the help pages .. the task seems to me too huge + a moving target to worry
about doing formally with our available peoplepower. They'd always be a little
out of date.

I agree, but I think that even a man page slightly out of date can be of use to someone who really doesn't understand the English version.

I don't know how AltaVista feels about live linking, but on the wiki I've added
experimental links to the Babelfish translator for the 6.3 online help pages:

  http://grass.gdf-hannover.de/wiki/Updating_GRASS_Documentation#Translations

Nice idea, with some interesting results (e.g. postscript becomes post-scriptum in the French version and - my favourite - GEM becomes "Directeur De Prolongements d'HERBE", meaning something like the director for the extension of grass/herbs ;-)).

One more serious issue though: the different options to commands are also translated, making them more or less useless:

v.clean [ -b] entré=outil nomméde rendement= de nom[type=corde [,corde... ] ][erreur=nom ]=corde[,corde... ] [battez=flotteur[,flotteur... ] ] [ - -recouvrez] [ - -bavard] [ - -tranquillité]

and the choice of tools:

outil=string[,corde... ]
     Outil de nettoyage
     Options : coupure, rupture, rmdangle, chdangle, rmbridge, chbridge, rmdupl, rmdac, bpol, pruneau, rmarea, rmline, rmsa
     coupure: lignes de coupure à chaque intersection
     rupture: lignes instantanées au sommet dans le seuil
     rmdangle: enlevez balance, seuil ignoré si < 0
     chdangle: changez le type de frontière balancent pour rayer, seuil ignoré si < 0, input line type is ignored

[...]

Moritz