Documentation error for -G API flag #125

New issue

Closed

opened 2018-03-13 14:48:07 +00:00 by philm · 2 comments

philm commented

2018-03-13 14:48:07 +00:00

(Migrated from gitlab2.manjaro.org)

Created by: petsam

G flag and possibly others about branch, are supposed to be used in conjuction with -a (API). In the help intro, they are not clear or mention this, neither in the Summary nor in the Sections.
This led me to run a not existed flag, instead of getting the Branch name. And helped uncover another bug.
Expected layout should be all API sub-flags to be under the API section of help and to be clear they need to be run together with -a
I remember other programs handle it like this.

$ pacman-mirrors 
Version 4.7.6
USAGE:
 pacman-mirrors [-h] [-f [NUMBER]] [-i [-d]] [-m METHOD]
		[-c COUNTRY [COUNTRY...]] [--geoip] [-l]
		[-b BRANCH | -G | -S/-B BRANCH] [-a] [-p PREFIX]
		[-P PROTO [PROTO...]] [-R] [-U URL]
		[-q] [-t SECONDS] [-v] [-n]

METHODS:
  -i, --interactive     Generate custom mirrorlist
  -f, --fasttrack [NUMBER]
                        Generate mirrorlist with a number of up-to-date
                        mirrors. Overrides : --geoip, --method
  -c, --country COUNTRY [COUNTRY ...]
                        Comma separated list of countries, from which mirrors
                        will be used
  --geoip               Get current country using geolocation

BRANCH:
  -b, --branch {stable,testing,unstable}
                        Branch name
  -G, --get-branch      API: Return branch from configuration
  -S, -B, --set-branch {stable,testing,unstable}
                        API: Replace branch in configuration

API:
  -a, --api             [-p PREFIX][-R][-S/-B|-G BRANCH][-P PROTO [PROTO ...]]
  -p, --prefix PREFIX   API: Set prefix to : $mnt | /mnt/install
  -P, --proto, --protocols {all,http,https,ftp,ftps} [{all,http,https,ftp,ftps} ...]
                        API: Replace protocols in configuration
  -R, --re-branch       API: Replace branch in mirrorlist
  -U, --url URL         API: Replace mirror url in mirrorlist

MISC:
  -d, --default         INTERACTIVE: Load default mirror file
  -h, --help
  -l, --list, --country-list
                        List all available countries
  -m, --method {rank,random}
                        Generation method
  -q, --quiet           Quiet mode - less verbose output
  -t, --timeout SECONDS
                        Maximum waiting time for server response
  -v, --version         Print the pacman-mirrors version
  -n, --no-mirrorlist   Use to skip generation of mirrorlist

*Created by: petsam* G flag and possibly others about branch, are supposed to be used in conjuction with -a (API). In the help intro, they are not clear or mention this, neither in the Summary nor in the Sections. This led me to run a not existed flag, instead of getting the Branch name. And helped uncover [another bug](https://github.com/manjaro/pacman-mirrors/issues/124). Expected layout should be all API sub-flags to be under the API section of help and to be clear they need to be run together with -a I remember other programs handle it like this. ``` $ pacman-mirrors Version 4.7.6 USAGE: pacman-mirrors [-h] [-f [NUMBER]] [-i [-d]] [-m METHOD] [-c COUNTRY [COUNTRY...]] [--geoip] [-l] [-b BRANCH | -G | -S/-B BRANCH] [-a] [-p PREFIX] [-P PROTO [PROTO...]] [-R] [-U URL] [-q] [-t SECONDS] [-v] [-n] METHODS: -i, --interactive Generate custom mirrorlist -f, --fasttrack [NUMBER] Generate mirrorlist with a number of up-to-date mirrors. Overrides : --geoip, --method -c, --country COUNTRY [COUNTRY ...] Comma separated list of countries, from which mirrors will be used --geoip Get current country using geolocation BRANCH: -b, --branch {stable,testing,unstable} Branch name -G, --get-branch API: Return branch from configuration -S, -B, --set-branch {stable,testing,unstable} API: Replace branch in configuration API: -a, --api [-p PREFIX][-R][-S/-B|-G BRANCH][-P PROTO [PROTO ...]] -p, --prefix PREFIX API: Set prefix to : $mnt | /mnt/install -P, --proto, --protocols {all,http,https,ftp,ftps} [{all,http,https,ftp,ftps} ...] API: Replace protocols in configuration -R, --re-branch API: Replace branch in mirrorlist -U, --url URL API: Replace mirror url in mirrorlist MISC: -d, --default INTERACTIVE: Load default mirror file -h, --help -l, --list, --country-list List all available countries -m, --method {rank,random} Generation method -q, --quiet Quiet mode - less verbose output -t, --timeout SECONDS Maximum waiting time for server response -v, --version Print the pacman-mirrors version -n, --no-mirrorlist Use to skip generation of mirrorlist ```

philm commented

2018-03-19 06:59:47 +00:00

(Migrated from gitlab2.manjaro.org)

Created by: fhdk

I agree.

The nature of handling conflicting arguments within pythons argparser module makes it difficult to create a usage page which groups the arguments in a strictly logical way.

The next best solution was to label all api related arguments with API:.

I will mark this issue with an enhancement label - and at some point I might do something about it but for the time being it is not a priority.

*Created by: fhdk* I agree. The nature of handling conflicting arguments within pythons argparser module makes it difficult to create a usage page which groups the arguments in a strictly logical way. The next best solution was to label all api related arguments with **API:**. I will mark this issue with an enhancement label - and at some point I might do something about it but for the time being it is not a priority.

philm commented

2018-03-19 12:52:03 +00:00

(Migrated from gitlab2.manjaro.org)

Created by: fhdk

github.com/manjaro/pacman-mirrors@5eda817fbc

*Created by: fhdk* https://github.com/manjaro/pacman-mirrors/commit/5eda817fbc7362a30bf23b1913eaa78944b14ba7