Opened 11 years ago

Closed 11 years ago

#385 closed enhancement (fixed)

description for v.db.reconnect.all

Reported by: nikos Owned by: grass-dev@…
Priority: minor Milestone: 6.4.0
Component: Default Version: unspecified
Keywords: Cc: nikos
CPU: Unspecified Platform: Unspecified

Description


Attachments (1)

v.db.reconnect.all_description.diff (1.9 KB) - added by nikos 11 years ago.

Download all attachments as: .zip

Change History (9)

Changed 11 years ago by nikos

comment:1 Changed 11 years ago by 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

comment:2 in reply to:  1 ; Changed 11 years ago by 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.

comment:3 in reply to:  2 ; Changed 11 years ago by 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

comment:4 in reply to:  3 ; Changed 11 years ago by 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.

comment:5 in reply to:  4 ; Changed 11 years ago by 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

comment:6 in reply to:  5 ; Changed 11 years ago by 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

comment:7 in reply to:  6 Changed 11 years ago by 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.

comment:8 Changed 11 years ago by hamish

Resolution: fixed
Status: newclosed
Note: See TracTickets for help on using tickets.