Isolate optional arguments in docs

Closes: #282 [via git-merge-pr]

2 files changed, 88 insertions, 39 deletions

diff --git a/README b/README
index a625c77..1e4f172 100644
--- a/README
+++ b/README
@@ -10,7 +10,7 @@ COMMANDS
      xbuildbarf [arch]
         – Spy on current buildbot output
 
-     xbulk [-n [-k [xbps-src flags pkgs ...]]]
+     xbulk [-n] [-k] [xbps-src flags] pkgs ...
         – simple XBPS bulk builder
           -n  dry-run mode
           -k  keep going on errors
@@ -34,7 +34,7 @@ COMMANDS
      xdbg pkgs ...
         – list debugging packages for pkgs and recursive dependencies
 
-     xdiff [-u | -l [basedir]]
+     xdiff [-u | -l] [basedir]
         – merge/diff/list XBPS .new-* files
           -l  list .new files
           -u  print unified diffs
@@ -48,11 +48,12 @@ COMMANDS
      xetcchanges
         – show diff of /etc against binary packages
 
-     xgensum [-f [-c [-i template]]]
+     xgensum [-f] [-c] [-i] [-H hostdir] template
         – update SHA256 sum in templates
           -f  force (re-)download of distfiles
           -c  use content checksum
           -i  replace checksum in-place
+          -H  absolute path to hostdir
 
      xgrep pattern pkgs ...
         – search files limited to XBPS package contents
@@ -71,11 +72,11 @@ COMMANDS
 
      xlint template | pkgname | :pkgname | :
         – scan XBPS template for common mistakes
-        - use ':pkgname' to lint template as staged in the git index
-        - use ':' to lint all templates staged in the git index
+        - use ‘:pkgname’ to lint template as staged in the git index
+        - use ‘:’ to lint all templates staged in the git index
 
-     xlocate
-        [-g | -S | pattern] – locate files in all XBPS packages
+     xlocate -g | -S | pattern
+        – locate files in all XBPS packages
           -g  Update a git based xlocate database, useful for local
               repositories
           -S  Sync with the official git based xlocate database, which is
@@ -96,28 +97,22 @@ COMMANDS
      xmypkgs [email]
         – list all pkgs maintained by you
 
-     xnew [-a pkg [subpkgs ...]]
+     xnew [-a] pkg [subpkgs ...]
         – create XBPS template
           -a  append subpkgs to existing pkg
 
-
      xnodev
         – list not installed -devel packages for installed packages
 
-
-     xoptdiff [-q [pkgs ...]]
+     xoptdiff [-q] [pkgs ...]
         – show template options which differ from binary package
           -q  quiet mode, show package names only
 
      xpcdeps pcfile ...
         – finds package matching the Requires: section of pkg-config files
 
-     xpkg [-R repo [-r rootdir [-amOHDvV]]]
+     xpkg [-amOHDvV] [-r rootdir] [-R repo]
         – convenient package lister
-          -R repo
-              consider only packages from repo
-          -r rootdir
-              specifies a full path for the target root directory
           -a  list all packages (default: only installed)
           -m  list manual packages
           -O  list orphaned packages
@@ -126,19 +121,43 @@ COMMANDS
           -L  list installed packages not from remote repos
           -v  show version numbers
           -V  show version numbers and description
+          -r rootdir
+              specifies a full path for the target root directory
+          -R repo
+              consider only packages from repo
+
+     xpkgdiff [-Sfrxt] [-a arch] [-R url] [-c file] [-p prop,...] pkg
+        – compare a package in the repositories to the locally-built version
+        - run from within a void-packages checkout
+        - set DIFF to change the diff program used
+          -S  compare package metadata
+          -f  compare package file lists
+          -r  reverse diff (compare local to remote)
+          -x  compare package dependencies
+          -t  compare the full package dependency tree. Only used with -x
+              (equivalent to xbps-query --fulldeptree -x)
+          -a arch
+              set architecture for comparison
+          -R url
+              set remote repository url
+          -c file
+              compare a file from the package (equivalent to xbps-query --cat)
+          -p prop,...
+              compare properties of the package
 
      xpstree
         – display tree view of xbps-src processes
 
-     xq [-R pkg ...]
+     xq [-R] pkg ...
         – query information about XBPS package
           -R  query remote repos
 
      xrecent [repourl | arch]
         – list packages in repo ordered by build date
 
-     xrevbump message templates ...
-        – increase template revision and commit
+     xrevbump message templates ... [-- git commit options]
+        – increase template revision and commit. Use ‘-’ to read templates
+        from stdin.
 
      xrevshlib package
         – list packages shlib-dependent on package or its subpackages
@@ -149,7 +168,7 @@ COMMANDS
      xsrc pkg
         – list source files for XBPS template
 
-     xsubpkg [-m pkg]
+     xsubpkg [-m] pkg
         – list all subpackages of a package
           -m  only print main package
 
diff --git a/xtools.1 b/xtools.1
index cc1e97e..053439e 100644
--- a/xtools.1
+++ b/xtools.1
@@ -10,7 +10,11 @@
 .Nd Display build logs of last build
 .It Nm xbuildbarf Op Ar arch
 .Nd Spy on current buildbot output
-.It Nm xbulk Op Fl n Op Fl k Op Ar xbps-src\ flags Ar pkgs ...
+.It Nm xbulk \
+Oo Fl n Oc \
+Oo Fl k Oc \
+Oo Ar xbps-src\ flags Oc \
+Ar pkgs ...
 .Nd simple XBPS bulk builder
 .Bl -tag -offset 2n -width 2n -compact
 .It Fl n
@@ -34,7 +38,9 @@ verbose mode, also print the library names
 .Nd detect file conflicts between XBPS packages
 .It Nm xdbg Ar pkgs ...
 .Nd list debugging packages for pkgs and recursive dependencies
-.It Nm xdiff Op Fl u | l Op Ar basedir
+.It Nm xdiff \
+Oo Fl u | l Oc \
+Op Ar basedir
 .Nd merge/diff/list XBPS .new-* files
 .Bl -tag -offset 2n -width 2n -compact
 .It Fl l
@@ -51,7 +57,12 @@ print unified diffs
 .Nd show diff of
 .Pa /etc
 against binary packages
-.It Nm xgensum Op Fl f Op Fl c Op Fl i Ar template
+.It Nm xgensum \
+Oo Fl f Oc \
+Oo Fl c Oc \
+Oo Fl i Oc \
+Oo Fl H Ar hostdir Oc \
+Ar template
 .Nd update SHA256 sum in templates
 .Bl -tag -offset 2n -width 2n -compact
 .It Fl f
@@ -60,6 +71,8 @@ force (re-)download of distfiles
 use content checksum
 .It Fl i
 replace checksum in-place
+.It Fl H
+absolute path to hostdir
 .El
 .It Nm xgrep Ar pattern Ar pkgs ...
 .Nd search files limited to XBPS package contents
@@ -104,7 +117,10 @@ Sync with the official git based xlocate database, which is recommended before u
 .Nd create new runit service templates
 .It Nm xmypkgs Op Ar email
 .Nd list all pkgs maintained by you
-.It Nm xnew Op Fl a Ar pkg Op Ar subpkgs ...
+.It Nm xnew \
+Oo Fl a Oc \
+Ar pkg \
+Op Ar subpkgs ...
 .Nd create XBPS template
 .Bl -tag -offset 2n -width 2n -compact
 .It Fl a
@@ -112,7 +128,9 @@ append subpkgs to existing pkg
 .El
 .It Nm xnodev
 .Nd list not installed -devel packages for installed packages
-.It Nm xoptdiff Op Fl q Op Ar pkgs ...
+.It Nm xoptdiff \
+Oo Fl q Oc \
+Op Ar pkgs ...
 .Nd show template options which differ from binary package
 .Bl -tag -offset 2n -width 2n -compact
 .It Fl q
@@ -120,14 +138,12 @@ quiet mode, show package names only
 .El
 .It Nm xpcdeps Ar pcfile ...
 .Nd finds package matching the Requires: section of pkg-config files
-.It Nm xpkg Op Fl R Ar repo Op Fl r Ar rootdir Op Fl amOHDvV
+.It Nm xpkg \
+Oo Fl amOHDvV Oc \
+Oo Fl r Ar rootdir Oc \
+Oo Fl R Ar repo Oc
 .Nd convenient package lister
 .Bl -tag -offset 2n -width 2n -compact
-.It Fl R Ar repo
-consider only packages from
-.Ar repo
-.It Fl r Ar rootdir
-specifies a full path for the target root directory
 .It Fl a
 list all packages (default: only installed)
 .It Fl m
@@ -144,8 +160,19 @@ list installed packages not from remote repos
 show version numbers
 .It Fl V
 show version numbers and description
+.It Fl r Ar rootdir
+specifies a full path for the target root directory
+.It Fl R Ar repo
+consider only packages from
+.Ar repo
 .El
-.It Nm xpkgdiff Op Fl Sfrxt Op Fl a Ar arch Op Fl R Ar url Op Fl c Ar file Op Fl p Ar prop,... Ar pkg
+.It Nm xpkgdiff \
+Oo Fl Sfrxt Oc \
+Oo Fl a Ar arch Oc \
+Oo Fl R Ar url Oc \
+Oo Fl c Ar file Oc \
+Oo Fl p Ar prop,... Oc \
+Ar pkg
 .Nd compare a package in the repositories to the locally-built version
 .Bl -dash -offset 0n -width 0n -compact
 .It
@@ -164,18 +191,20 @@ reverse diff (compare local to remote)
 compare package dependencies
 .It Fl t
 compare the full package dependency tree. Only used with -x (equivalent to xbps-query --fulldeptree -x)
-.It Fl c Ar file
-compare a file from the package (equivalent to xbps-query --cat)
-.It Fl p Ar prop,...
-compare properties of the package
 .It Fl a Ar arch
 set architecture for comparison
 .It Fl R Ar url
 set remote repository url
+.It Fl c Ar file
+compare a file from the package (equivalent to xbps-query --cat)
+.It Fl p Ar prop,...
+compare properties of the package
 .El
 .It Nm xpstree
 .Nd display tree view of xbps-src processes
-.It Nm xq Op Fl R Ar pkg ...
+.It Nm xq \
+Oo Fl R Oc \
+Ar pkg ...
 .Nd query information about XBPS package
 .Bl -tag -offset 2n -width 2n -compact
 .It Fl R
@@ -193,7 +222,9 @@ to read templates from stdin.
 .Nd like xbps-query -Rs, but take cwd repo into account
 .It Nm xsrc Ar pkg
 .Nd list source files for XBPS template
-.It Nm xsubpkg Op Fl m Ar pkg
+.It Nm xsubpkg \
+Oo Fl m Oc \
+Ar pkg
 .Nd list all subpackages of a package
 .Bl -tag -offset 2n -width 2n -compact
 .It Fl m
@@ -203,7 +234,6 @@ only print main package
 .Nd display system info relevant for debugging Void
 .It Nm xvoidstrap Ar dir Op Ar packages
 .Nd bootstrap a new Void installation
-.El
 .Sh DESCRIPTION
 Tools working on the void-packages tree use
 .Nm xdistdir