As part of my Pythonification of grass project, I'd like to add to our
GRASS 7 workload:
Would it be useful to have metadata about our scripts and programs?
Basically, what I propose is a simple text file that describes each
command and script in a standard format. I like the format that
g.parser uses in sh scripts today. I would extend it to include a
short help and long help description and a sort-of 'magic cookie'
which describes how to launch the script/program.
g.parser would be adjusted to read the resource file so there would be
no user-visible changes. HTML documentation would be built using the
resource file and an HTML template. GUI's could build their GUI code
based on the resource file.
The format should be quick and easy so that script coders can add a
resource file for their program with a minimum of fuss. (Copy and
paste a template from the wiki for example).
As part of my Pythonification of grass project, I'd like to add to our
GRASS 7 workload:
Would it be useful to have metadata about our scripts and programs?
Basically, what I propose is a simple text file that describes each
command and script in a standard format. I like the format that
g.parser uses in sh scripts today. I would extend it to include a
short help and long help description and a sort-of 'magic cookie'
which describes how to launch the script/program.
g.parser would be adjusted to read the resource file so there would be
no user-visible changes. HTML documentation would be built using the
resource file and an HTML template. GUI's could build their GUI code
based on the resource file.
The format should be quick and easy so that script coders can add a
resource file for their program with a minimum of fuss. (Copy and
paste a template from the wiki for example).
What do you think?
maybe something to add to the "development sandbox" part of the wiki?
As part of my Pythonification of grass project, I'd like to add to our
GRASS 7 workload:
Would it be useful to have metadata about our scripts and programs?
Basically, what I propose is a simple text file that describes each
command and script in a standard format. I like the format that
g.parser uses in sh scripts today. I would extend it to include a
short help and long help description and a sort-of 'magic cookie'
which describes how to launch the script/program.
g.parser would be adjusted to read the resource file so there would be
no user-visible changes. HTML documentation would be built using the
resource file and an HTML template. GUI's could build their GUI code
based on the resource file.
If you need more information about a module, extend the Module, Flag,
or Option structures to contain the relevant information, and update
the relevant functions in lib/gis/parser.c to use that information.
Having separate metadata files creates a risk of those files getting
out of sync with the actual modules.
Something like this was suggested in the GUI roadmap discussions last fall
and winter. It will make upkeep easier in the long run.
Michael
__________________________________________
Michael Barton, Professor of Anthropology
School of Human Evolution & Social Change
Center for Social Dynamics & Complexity
Arizona State University
From: David Finlayson <david.p.finlayson@gmail.com>
Date: Thu, 15 Jun 2006 10:12:34 -0700
To: GRASS developers list <grass-dev@grass.itc.it>
Subject: [GRASS-dev] GRASS7 wish
As part of my Pythonification of grass project, I'd like to add to our
GRASS 7 workload:
Would it be useful to have metadata about our scripts and programs?
Basically, what I propose is a simple text file that describes each
command and script in a standard format. I like the format that
g.parser uses in sh scripts today. I would extend it to include a
short help and long help description and a sort-of 'magic cookie'
which describes how to launch the script/program.
g.parser would be adjusted to read the resource file so there would be
no user-visible changes. HTML documentation would be built using the
resource file and an HTML template. GUI's could build their GUI code
based on the resource file.
The format should be quick and easy so that script coders can add a
resource file for their program with a minimum of fuss. (Copy and
paste a template from the wiki for example).
I think we misunderstood each other. What I want is a simple method
for a grass program to describe itself to ANOTHER program.
Ideally, the user-interface (whether GUI or Text) of each binary and
script would be built by parsing the resource file for input and
output requirements (flags, etc.). Also, the console help and HTML
manual pages would be built directly from the resource file.
I think if the resource file were tightly integrated to both the user
interface of the program and the derivative products like console help
and html manual pages, we would get better synchronization rather than
the reverse.
I think the format used by g.parser is pretty good. It just needs a
few extra fields for storing the long help (what would go in the
manual page). On the other hand, if we used some kind of xml file, we
might be able to slap a stylesheet on top and display the resource
file directly as the manual page. That would be a great
synchronization benefit.
David
On 6/15/06, Glynn Clements <glynn@gclements.plus.com> wrote:
David Finlayson wrote:
> As part of my Pythonification of grass project, I'd like to add to our
> GRASS 7 workload:
>
> Would it be useful to have metadata about our scripts and programs?
> Basically, what I propose is a simple text file that describes each
> command and script in a standard format. I like the format that
> g.parser uses in sh scripts today. I would extend it to include a
> short help and long help description and a sort-of 'magic cookie'
> which describes how to launch the script/program.
>
> g.parser would be adjusted to read the resource file so there would be
> no user-visible changes. HTML documentation would be built using the
> resource file and an HTML template. GUI's could build their GUI code
> based on the resource file.
If you need more information about a module, extend the Module, Flag,
or Option structures to contain the relevant information, and update
the relevant functions in lib/gis/parser.c to use that information.
Having separate metadata files creates a risk of those files getting
out of sync with the actual modules.
> > As part of my Pythonification of grass project, I'd like to add to our
> > GRASS 7 workload:
> >
> > Would it be useful to have metadata about our scripts and programs?
> > Basically, what I propose is a simple text file that describes each
> > command and script in a standard format. I like the format that
> > g.parser uses in sh scripts today. I would extend it to include a
> > short help and long help description and a sort-of 'magic cookie'
> > which describes how to launch the script/program.
> >
> > g.parser would be adjusted to read the resource file so there would be
> > no user-visible changes. HTML documentation would be built using the
> > resource file and an HTML template. GUI's could build their GUI code
> > based on the resource file.
>
> If you need more information about a module, extend the Module, Flag,
> or Option structures to contain the relevant information, and update
> the relevant functions in lib/gis/parser.c to use that information.
>
> Having separate metadata files creates a risk of those files getting
> out of sync with the actual modules.
I think we misunderstood each other. What I want is a simple method
for a grass program to describe itself to ANOTHER program.
Ideally, the user-interface (whether GUI or Text) of each binary and
script would be built by parsing the resource file for input and
output requirements (flags, etc.). Also, the console help and HTML
manual pages would be built directly from the resource file.
Are you proposing generating the code for the
G_define_{module,flag,option} calls from a text file?
Apart from being a lot of work to convert all of the modules, working
with machine-generated code is frequently a pain. And you still have
to include some per-flag/option code to associate each option with a
specific variable. IOW, if you want to add, remove or change an
option, you have to modify both the description file and main.c,
rather than just main.c.
I don't see any advantage to storing the description in an external
file compared to including it in the module/flag/option description
and having G_parser() generate the external representation for
situations which require it (as we already do for the HTML manual
pages and the Tcl/Tk GUI).
What I want is a simple method for a grass program to describe itself
to ANOTHER program.
such as the existing XML description:
m.proj --interface-description
?
Ideally, the user-interface (whether GUI or Text) of each binary and
script would be built by parsing the resource file for input and
output requirements (flags, etc.). Also, the console help and HTML
manual pages would be built directly from the resource file.
This is already the case, just the G_parser() does it from the C or
g.parser shell code.
I think if the resource file were tightly integrated to both the user
interface of the program and the derivative products like console help
and html manual pages, we would get better synchronization rather than
the reverse.
This is already what happens? (and compared to GRASS 5 maintaining the
man pages is wonderful)
I think the format used by g.parser is pretty good. It just needs a
few extra fields for storing the long help (what would go in the
manual page). On the other hand, if we used some kind of xml file, we
might be able to slap a stylesheet on top and display the resource
file directly as the manual page. That would be a great
synchronization benefit.
As part of the build process, along with building the help pages, build
an XML description of the module including the description.html file?