description for v.db.reconnect.all

[nikos]

Apologies for my mistake.

Glynn explained why I should not do this mistake (in the post entitled "Re: [GRASS-user] Best way to reconnect tables in grass' databse")

Question: where should the "change" added? Not in the "tmp.html" file. But then, in the description.html? Where?

I am not sure... !?

Thanks in advance, Nikos

[glynn]

Replying to nikos:

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.

[hamish]

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

Hamish

[glynn]

Replying to hamish:

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.

[hamish]

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

Hamish

[hamish]

Replying to hamish:

Replying to 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/... ?

Hamish

[glynn]

Replying to hamish:

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