[GRASS-dev] Standard options label vs description

[Huidae Cho]

Hi,

The Option and Flag structures have label and description. If label is
missing, description is used as the main description. Otherwise, label
becomes the main description and description becomes an indented
explanation.

When we want to add examples or explanations to some standard options, we
have to assign both label and description even if the standard description
is enough as label because those standard options only have description. We
cannot simply assign description in this case. Some other standard options
have both label and description, so it's not clear when to assign
description only and when to assign both label and description. Also, it
takes additional effort to copy the standard description to the label.

IMHO, we have to always use the label for the first description and the
description for additional examples or clarifications. This way, when the
developer wants to override or add more details, s/he can simply assign
description if s/he wants to use the standard label. Maybe forcing to use
the label (G_fatal_error on an empty label) can be too much and break
backward compatibility.

I propose to change description to label for description-only standard
options. E.g., G_OPT_DB_TABLE, G_OPT_F_INPUT, ...

This proposed change shouldn't affect existing modules, but will ease
writing new ones.

I'm not sure about --interface/html-description. For now, it's mixed with
label & description. Some options have label and description, and others
only have description. It looks like label is not required and g.gui can
handle both cases. One problem with this mixed approach is that we cannot
simply extract labels only to collect the main option descriptions. We have
to parse the output and determine when to use label and when to use
description for the main description. Standardizing the use of label and
description will also help in this regard.

Thanks.
Huidae
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/grass-dev/attachments/20140604/d3f4037e/attachment.html>