[GRASS-dev] Keywords in module descriptions

[Hamish]

Markus wrote:
> I have added the keywords now in GRASS 6.3-CVS.
> Each command has at least 1 keyword.

Sorry if I am thick, but in the age of Google what's the point of
defining keywords?

Dynamic self-organization of menu items (even if that's a good idea)
should probably get their own hinting mechanism.


Is giving each r.* module the "raster" keyword really needed?
Or giving each "*.in.*" an "input" keyword?

(answering self) I guess GUI users often don't see the module names or
know the m.in.* meanings.

one that comes to mind is the "Thiessen polygons" for v.voronoi.


> We need to add more of course, but they should be selected from a list
> or so to avoid that identical things get different keywords. Here the
> Wiki may be of use.

For keywords to be useful, the list needs to be well planned and tightly
enforced, IMO.


> Question: Should I apply the patch to GRASS 6.2-release branch
> as well?

My vote would be "no". A lot of work to backport and result will be
only slightly finished by the time 6.2 is released, which looks bad and
a half-done list isn't nearly as useful (can't trust a keyword search).
I don't mind them in 6.3 if others think they are useful.. I'd just like
to hear a real example of how they would be used. e.g. could they help
with a Google ranking so a man page comes before a mailing list question?



Hamish


> > a proposal for a better navigatable documentation of GRASS:
> > I would like to add
> > 
> >     module->keywords = _("a, b, c, d");
> > 
> > to each command. These keywords would then
> > - automatically appear in each HTML/MAN page
> > - be content of the XML output by --interface-description
> >   (maybe parsable then <keywords>a, b, c, d</keywords> for
> >    automated GUI arranging?)
> > - probably made visible in the TclTk GUI if we want that
> > - visible in the "help" text, example:
> > 
> > r.cost help
> > 
> > Description:
> >  Outputs a raster map layer showing the cumulative cost of moving
> >  between different geographic locations on an input raster map layer
> >  whose cell category values represent cost.
> > 
> > Keywords:
> >  raster map, cost surface, cumulative costs
> > 
> > Usage:
> >  r.cost [-vknr] input=name output=name [start_points=string]
> >    [stop_points=string] [start_rast=string]
> >    [coordinate=x,y[,x,y,...]] [stop_coordinate=x,y[,x,y,...]]
> >    [max_cost=cost] [null_cost=null cost] [percent_memory=percent
> >    memory] [--overwrite]
> > 
> > ...
> > 
> > I have it running on my PC for r.cost.
> > With a sed job I could substitute all 
> >    module->description = ...
> > 
> > by
> >    module->keywords = _("a, b, c, d");
> >    module->description = ...
> > automatically.
> > 
> > Maybe we could make a Web application to visualize the keywords
> > like a navigatable tree or "TouchGraph" [1] or whatever appropriate.
> > 
> > Any objections?
> > 
> > Markus
> > 
> > [1] Just as an selfish example (needs Java):
> >     http://www.citeulike.org/nocrawl/touchgraph_applet.adp?article_id=172900
> >     (double click on the floating objects to navigate)