search

openSUSE / docmanager

Manage DocBook 5 Meta Information
http://opensuse.github.io/docmanager/index.html
GNU General Public License v3.0
6 stars 6 forks source link

Some Correction Proposals for DocManager Help Texts #44

Closed taroth21 closed 9 years ago

taroth21 commented 9 years ago

set (s) Set key=value property (one or more) to delete the key let the value blank.

change to: Set key=value property (one or more). To delete the key leave the value empty.

query (q, analyze) Similar to get, but query can be given as pseudo SQL syntax. allowed keywords are SELECT, WHERE, and SORTBY. Output is formatted as table.

change to: Similar to get, but query can be given as pseudo SQL syntax. Allowed keywords are SELECT, WHERE, and SORTBY. Output is formatted as table.

Whereas the man page talks about "XML files", the help text talks about "XML documents" or "documents". Better unify to "XML files" as (IMHO), DocManager operates on a file basis (also, in my understanding, a "document" can be made up of several XML files).

Regarding the help texts for the command, the subcommands and the arguments, decide about the following (and stick to this decision for all of them):

  1. Either start all of them with a capital letter (I would probably do so) or use lowercase for all of them. Currently we have a mixture of both spellings, e.g. optional arguments: -h, --help show this help message and exit -v, --verbose Increase verbosity level
  2. Either use 3rd person singular or imperative for all. Currently we have a mixture of both, e.g. init (i) Initializes (3rd person singular) an XML document with predefined properties. get (g) Get (imperative) key and returns (3rd person singular) value
  3. Decide if to use a full stop at the end or not. Currently we have a mixture of both, e.g. init (i) Initializes an XML document with predefined properties. get (g) Get key and returns value