> Question: where should the "change" added? Not in the "tmp.html" file.
But then, in the description.html? Where?
Add a "notes" section at the end of description.html.
The "parameters" section is generated by running the script with the
--html-description option. The text is taken from the corresponding "#%
description:" line at the top of the script.
I note that the script already has that text; it should be removed. For
option descriptions, brevity is more important than exhaustively
documenting the option's semantics.
Replying to [comment:2 glynn]:
> The "parameters" section is generated by running the script
> with the --html-description option. The text is taken from the
> corresponding "#% description:" line at the top of the script.
> I note that the script already has that text; it should be
> removed. For option descriptions, brevity is more important
> than exhaustively documenting the option's semantics.
long description split into shorter #%label: and #%description: in SVN.
> > The "parameters" section is generated by running the script
> > with the --html-description option. The text is taken from the
> > corresponding "#% description:" line at the top of the script.
>
> > I note that the script already has that text; it should be
> > removed. For option descriptions, brevity is more important
> > than exhaustively documenting the option's semantics.
>
> long description split into shorter #%label: and #%description: in SVN.
I've just put it back to "Name of old database". Notes, details, caveats
and the like belong in the manual. The "help" output isn't intended to be
the complete manual.
Replying to [comment:4 glynn]:
> I've just put it back to "Name of old database". Notes, details,
> caveats and the like belong in the manual.
(if it belongs in the manual please move it into the manual instead of
just deleting it)
> The "help" output isn't intended to be the complete manual.
No, but the more things can be self documenting and obvious without having
to dig into the manual each time, the better. -- as long as the
tooltip/long desc. doesn't go multi-paragraph to include trivia.
Things like units and conventions (eg aspect is degrees CW from north vs.
radians CCW from east) surely belong in the param descr. In my mind a
terse summary of expected input format is conceptually not too far away
from units..
Replying to [comment:5 hamish]:
> Replying to [comment:4 glynn]:
> > I've just put it back to "Name of old database". Notes, details,
> > caveats and the like belong in the manual.
>
> (if it belongs in the manual please move it into the manual
> instead of just deleting it)
clearer- you didn't actually "put it back" ie revert r34627, you changed
it.
AFAICT Nikos's patch reduces to:
{{{
The name of '''old_database''' needs to be the exact string
which appears as the fourth field printed by 'v.db.connect -g',
i.e. with substituted variables.
}}}
does that mean you need to use the full path not $MAPSET/... ?
> (if it belongs in the manual please move it into the manual instead of
just deleting it)
Done in r34639.
> AFAICT Nikos's patch reduces to:
{{{
The name of '''old_database''' needs to be the exact string
which appears as the fourth field printed by 'v.db.connect -g',
i.e. with substituted variables.
}}}
> does that mean you need to use the full path not $MAPSET/... ?
The script calls "v.db.connect -g" on each map, parses the output, and
checks that the database field (4th column) is equal (by string
comparison) to the old_database= value. If the database reported by the
driver is a literal path, you need to use a literal path. If the database
reported by the driver includes a trailing backslash, you need to include
the trailing backslash, etc.
The script can't realistically "normalise" the database name, as the
format and semantics are driver-specific. For DBF, it's just a pathname;
for a client-server DBMS, it can include all manner of connection
parameters.
If you feel that it's necessary to clarify this in the option description
(rather than the manual), "as reported by v.db.connect" should suffice.