[GRASS5] 5.1: --html-description to parser added

neteler · February 4, 2003, 3:10pm

Derived from the --interface-description there is now
--html-description
available in the 5.1 parser (CVS).

e.g.
d.erase --html-description > d.erase.html

will generate a valid HTML file containing parameter(s) and flag(s)
description in the well known style of the GRASS man pages.

It may be discussed if we add something like
option->longdescription = "long explanations";

to the modules to move extra explanations from the HTML files to
the module itself (now sometimes the parameter/flag descriptions
are identical to what the module's help text provides, sometimes
the descriptions differ which is no good solution).

Markus

neteler · February 4, 2003, 4:18pm

On Tue, Feb 04, 2003 at 04:10:20PM +0100, Markus Neteler wrote:

Derived from the --interface-description there is now
--html-description
available in the 5.1 parser (CVS).

A related question to this:

I would like to add a 'html' target to the 5.1 Makefiles.
Prerequisite:
- a file 'description.html' will contain further description, notes,
author etc, stored in the directory of module source code

Makefile 'html' target idea:
- generate first part of the man page on-the-fly with --html-description
- append 'description.html'
- write all as file 'module.html' into HTML target directory

Problem:
As G_gisinit() is used in every module, I cannot directly run
in the Makefile:

html:
        $(GISBASE)/etc/bin/cmd/$(PGM) --html-description <something>
  <add description.html>
  ...

unless there is a fake GRASS session.

Is there a better way than faking a GRASS session (hope so!)?

Markus

Glynn_Clements · February 4, 2003, 10:36pm

Markus Neteler wrote:

> Derived from the --interface-description there is now
> --html-description
> available in the 5.1 parser (CVS).

A related question to this:

I would like to add a 'html' target to the 5.1 Makefiles.
Prerequisite:
- a file 'description.html' will contain further description, notes,
   author etc, stored in the directory of module source code

Makefile 'html' target idea:
- generate first part of the man page on-the-fly with --html-description
- append 'description.html'
- write all as file 'module.html' into HTML target directory

Problem:
As G_gisinit() is used in every module, I cannot directly run
in the Makefile:

html:
        $(GISBASE)/etc/bin/cmd/$(PGM) --html-description <something>
  <add description.html>
  ...

unless there is a fake GRASS session.

... and you *aren't* cross-compiling.

Is there a better way than faking a GRASS session (hope so!)?

Ultimately most of G_gisinit() ought to be moved to G_parser(); but
that would require that everything actually used G_parser(), which
isn't the case at present.

There are some other problems. E.g. some modules call G_get_window(),
R_open_driver() etc and initialise the defaults based upon data from
the current region or the monitor. This is (arguably) OK if the user
is running "g.foo help" interactively, but it means that the defaults
in the HTML file will reflect the session which was used to generate
it.

--
Glynn Clements <glynn.clements@virgin.net>

Roger_Bivand · February 5, 2003, 7:26am

On Tue, 4 Feb 2003, Glynn Clements wrote:

Markus Neteler wrote:

> > Derived from the --interface-description there is now
> > --html-description
> > available in the 5.1 parser (CVS).
>
> A related question to this:
>
> I would like to add a 'html' target to the 5.1 Makefiles.
> Prerequisite:
> - a file 'description.html' will contain further description, notes,
> author etc, stored in the directory of module source code
>
> Makefile 'html' target idea:
> - generate first part of the man page on-the-fly with --html-description
> - append 'description.html'
> - write all as file 'module.html' into HTML target directory
>
> Problem:
> As G_gisinit() is used in every module, I cannot directly run
> in the Makefile:
>
> html:
> $(GISBASE)/etc/bin/cmd/$(PGM) --html-description <something>
> <add description.html>
> ...
>
> unless there is a fake GRASS session.

... and you *aren't* cross-compiling.

> Is there a better way than faking a GRASS session (hope so!)?

Ultimately most of G_gisinit() ought to be moved to G_parser(); but
that would require that everything actually used G_parser(), which
isn't the case at present.

The R/GRASS interface calls G_gisinit(), but doesn't need to parse
anything, however little of what G_gisinit() does is needed explicitly -
doesn't it mostly initialize static variables that other functions assume
are initialized?

Roger

There are some other problems. E.g. some modules call G_get_window(),
R_open_driver() etc and initialise the defaults based upon data from
the current region or the monitor. This is (arguably) OK if the user
is running "g.foo help" interactively, but it means that the defaults
in the HTML file will reflect the session which was used to generate
it.

--
Roger Bivand
Economic Geography Section, Department of Economics, Norwegian School of
Economics and Business Administration, Breiviksveien 40, N-5045 Bergen,
Norway. voice: +47 55 95 93 55; fax +47 55 95 93 93
e-mail: Roger.Bivand@nhh.no

neteler · February 6, 2003, 6:34pm

On Tue, Feb 04, 2003 at 10:36:53PM +0000, Glynn Clements wrote:

Markus Neteler wrote:

> > Derived from the --interface-description there is now
> > --html-description
> > available in the 5.1 parser (CVS).
>
> A related question to this:
>
> I would like to add a 'html' target to the 5.1 Makefiles.

[...]

> unless there is a fake GRASS session.
... and you *aren't* cross-compiling.

right - a fake GRASS session I don't like.

> Is there a better way than faking a GRASS session (hope so!)?

Ultimately most of G_gisinit() ought to be moved to G_parser(); but
that would require that everything actually used G_parser(), which
isn't the case at present.

Correct. In general it may be interesting to have 'parser'
as program for script usage (so that we don't have to build a
parser any more with shell commands) which provides parameters
and flags as
PARAM1
PARAM2 ..
FLAG1 ...

for further usage in a script.

Given that 99% (?) of the GRASS 5.1 commands could be using the parser.

There are some other problems. E.g. some modules call G_get_window(),
R_open_driver() etc and initialise the defaults based upon data from
the current region or the monitor. This is (arguably) OK if the user
is running "g.foo help" interactively, but it means that the defaults
in the HTML file will reflect the session which was used to generate
it.

That's another point against a fake session. If the (updated) parser
got a flag to run without a GRASS session, it could be used in
Makefile and above problem should be minimized.

Markus

Glynn_Clements · February 7, 2003, 1:46am

Markus Neteler wrote:

> > Is there a better way than faking a GRASS session (hope so!)?
>
> Ultimately most of G_gisinit() ought to be moved to G_parser(); but
> that would require that everything actually used G_parser(), which
> isn't the case at present.

Correct. In general it may be interesting to have 'parser'
as program for script usage (so that we don't have to build a
parser any more with shell commands) which provides parameters
and flags as
PARAM1
PARAM2 ..
FLAG1 ...

for further usage in a script.

See src/general/g.parser; it really needs some documentation, though.

> There are some other problems. E.g. some modules call G_get_window(),
> R_open_driver() etc and initialise the defaults based upon data from
> the current region or the monitor. This is (arguably) OK if the user
> is running "g.foo help" interactively, but it means that the defaults
> in the HTML file will reflect the session which was used to generate
> it.

That's another point against a fake session. If the (updated) parser
got a flag to run without a GRASS session, it could be used in
Makefile and above problem should be minimized.

Yes, but this requires finding and fixing all of the programs which
call GRASS functions prior to G_parser(). FWIW, I've discussed this
previously:

  From: Glynn Clements <glynn.clements@virgin.net>
  Message-ID: <15135.13549.677759.452840@cerise.nosuchdomain.co.uk>
  Date: Thu, 7 Jun 2001 09:01:49 +0100
  Subject: Re: [GRASS5] Darwin Pre1 gtty stty errors

This mentions the following programs as using raster/display functions
to initialise defaults (so they fail if no monitor is selected):

  d.colors - D_get_cell_name
  d.pan - D_get_cell_list, D_get_dig_list, D_get_site_list
  d.save - R_screen_{top,bot,left,rite}, R_pad_list, R_pad_select
  d.what.rast - D_get_cell_list
  d.what.sites - D_get_site_list
  d.what.vect - D_get_dig_list
  d.zoom - D_get_cell_list, D_get_dig_list, D_get_site_list

Also:

  From: Glynn Clements <glynn.clements@virgin.net>
  Message-ID: <15163.33358.71553.232455@cerise.nosuchdomain.co.uk>
  Date: Thu, 28 Jun 2001 20:15:26 +0100
  Subject: Re: [GRASS5] Interfaces ... (long)

This mentions specific classes of problem, but not the individual
programs:

  1. D_get_cell_name (d.colors), D_get_{cell,dig,site}_list (several
  programs) and other functions (d.save) to obtain state from the
  monitor.

  2. G_gisbase, G_mapset, G_projection, G_zone, G_get_window and
  G_get_set_window to obtain information about the current location.

  3. spheroid_list and datum_list. In the case of spheroid_list, many
  programs implement this function independently.

  4. G_{lat,lon}_format_string, D_color_list. These functions actually
  just return string literals.

  5. read_list (used by g.{copy,list,remove,rename} to parse
  etc/element_list).

1 and 2 are the real problems here; they won't work without a session,
1 won't work without a monitor, and both will produce
--interface-description (etc) messages which are specific to the
session in which they are run.

Some alternative mechanims were proposed in the messages referenced
above.

--
Glynn Clements <glynn.clements@virgin.net>

neteler · February 7, 2003, 8:26am

On Fri, Feb 07, 2003 at 01:46:55AM +0000, Glynn Clements wrote:

Markus Neteler wrote:

> > > Is there a better way than faking a GRASS session (hope so!)?
> >
> > Ultimately most of G_gisinit() ought to be moved to G_parser(); but
> > that would require that everything actually used G_parser(), which
> > isn't the case at present.
>
> Correct. In general it may be interesting to have 'parser'
> as program for script usage (so that we don't have to build a
> parser any more with shell commands) which provides parameters
> and flags as
> PARAM1
> PARAM2 ..
> FLAG1 ...
>
> for further usage in a script.

See src/general/g.parser; it really needs some documentation, though.

Oops. I can't believe that I was unaware of this

> > There are some other problems. E.g. some modules call G_get_window(),
> > R_open_driver() etc and initialise the defaults based upon data from
> > the current region or the monitor. This is (arguably) OK if the user
> > is running "g.foo help" interactively, but it means that the defaults
> > in the HTML file will reflect the session which was used to generate
> > it.
>
> That's another point against a fake session. If the (updated) parser
> got a flag to run without a GRASS session, it could be used in
> Makefile and above problem should be minimized.

Yes, but this requires finding and fixing all of the programs which
call GRASS functions prior to G_parser(). FWIW, I've discussed this
previously:

  From: Glynn Clements <glynn.clements@virgin.net>
  Message-ID: <15135.13549.677759.452840@cerise.nosuchdomain.co.uk>
  Date: Thu, 7 Jun 2001 09:01:49 +0100
  Subject: Re: [GRASS5] Darwin Pre1 gtty stty errors

http://grass.itc.it/pipermail/grass5/2001-June/000186.html

I remember the problem. As 5.1 is growing slowly, the developers can
easily take care of this problem.

This mentions the following programs as using raster/display functions
to initialise defaults (so they fail if no monitor is selected):

  d.colors - D_get_cell_name
  d.pan - D_get_cell_list, D_get_dig_list, D_get_site_list
  d.save - R_screen_{top,bot,left,rite}, R_pad_list, R_pad_select
  d.what.rast - D_get_cell_list
  d.what.sites - D_get_site_list
  d.what.vect - D_get_dig_list
  d.zoom - D_get_cell_list, D_get_dig_list, D_get_site_list

Also:

  From: Glynn Clements <glynn.clements@virgin.net>
  Message-ID: <15163.33358.71553.232455@cerise.nosuchdomain.co.uk>
  Date: Thu, 28 Jun 2001 20:15:26 +0100
  Subject: Re: [GRASS5] Interfaces ... (long)

http://grass.itc.it/pipermail/grass5/2001-June/000394.html

This mentions specific classes of problem, but not the individual
programs:

  1. D_get_cell_name (d.colors), D_get_{cell,dig,site}_list (several
  programs) and other functions (d.save) to obtain state from the
  monitor.

  2. G_gisbase, G_mapset, G_projection, G_zone, G_get_window and
  G_get_set_window to obtain information about the current location.

  3. spheroid_list and datum_list. In the case of spheroid_list, many
  programs implement this function independently.

  4. G_{lat,lon}_format_string, D_color_list. These functions actually
  just return string literals.

  5. read_list (used by g.{copy,list,remove,rename} to parse
  etc/element_list).

1 and 2 are the real problems here; they won't work without a session,
1 won't work without a monitor, and both will produce
--interface-description (etc) messages which are specific to the
session in which they are run.

Some alternative mechanims were proposed in the messages referenced
above.

So it is unfortunately less easy than expected. I still like the
idea to generate whatever possible automatically to reduce the workload
of the people documenting GRASS.

Markus