[GRASS-dev] Keywords in module descriptions

[Markus Neteler]

On Wed, Aug 23, 2006 at 07:32:16PM +1200, Hamish wrote:
> 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?

Call it "tag" for a modernized version :-)
Everybody is tagging nowadays.

> 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?

This is what could be completely automated.
 
> (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.

right, please submit!


> > 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.

yes, as suggested. 
 
> > 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).

Sorry, too late. 30 minutes ago I have submitted it. The main reason was to
not make backporting of changes from > 6.2 a continuous pain. I have already
submitted twice changes where the keywords creeped it (and then broke the release
branch). Now this cannot happen any more. And there weren't any negative
responses so far. Luckily the keyword search isn't implemented at all and
could be limited to 6.3. Also adding more in 6.2 isn't a big deal.

Feel free to revert.

> 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?

Example:
The HTML man pages could use the keyword as metatag which hopefully
improves the ranking. Things can grow in my opinion.


Markus


> 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)

-- 
Markus Neteler  <neteler itc it>  http://mpa.itc.it/markus/
ITC-irst -  Centro per la Ricerca Scientifica e Tecnologica
MPBA - Predictive Models for Biol. & Environ. Data Analysis
Via Sommarive, 18        -       38050 Povo (Trento), Italy