Rework --help output

1 files changed, 198 insertions, 148 deletions

diff --git a/src/scm/webid-oidc/program.scm b/src/scm/webid-oidc/program.scm
index b613717..79f13cb 100644
--- a/src/scm/webid-oidc/program.scm
+++ b/src/scm/webid-oidc/program.scm
@@ -263,102 +263,177 @@
       (cond
        ((option-ref options help-sym #f)
         (format #t (G_ "Usage: ~a COMMAND [OPTIONS]...
+")
+                (car (command-line)))
 
-Run the webid-oidc COMMAND.
-
+        (format #t (G_ "
+Run the webid-oidc COMMAND."))
+        (format #t "\n")
+        (format #t (G_ "
 This program is covered by the GNU Affero GPL, version 3 or
 later. This license requires you to provide a way for any user over
 the network to download the complete corresponding source code (with
 your modifications) at no cost. The server adds a \"Source:\" header
-to all responses.
-
-Available commands:
+to all responses."))
+        (format #t "\n")
+        (format #t (G_ "
+Available commands:"))
+        (format #t (G_ "
   ~a:
-    run an authenticating reverse proxy.
+      run an authenticating reverse proxy.")
+                (G_ "command-line|command|reverse-proxy"))
+        (format #t (G_ "
   ~a:
-    run an identity provider.
+      run an identity provider.")
+                (G_ "command-line|command|identity-provider"))
+        (format #t (G_ "
   ~a:
-    serve the pages for a public application.
+      serve the pages for a public application.")
+                (G_ "command-line|command|client-service"))
+        (format #t (G_ "
   ~a:
-    run a full server, with identity provider and resource storage
-    facility.
-
-General options:
+      run a full server, with identity provider and resource storage
+      facility.")
+                (G_ "command-line|command|server"))
+        (format #t "\n")
+        (format #t (G_ "
+General options:"))
+        (format #t (G_ "
   -S MEANS, --~a=MEANS:
-    specify a way to download the complete corresponding source
-    code. For instance, this would be an URI pointing to a tarball.
+      specify a way to download the complete corresponding source
+      code. For instance, this would be an URI pointing to a tarball.")
+                complete-corresponding-source-sym)
+        (format #t (G_ "
   -h, --~a:
-    display a short help message and exit.
+      display a short help message and exit.")
+                help-sym)
+        (format #t (G_ "
   -v, --~a:
-    display the version information (~a) and exit.
+      display the version information (~a) and exit.")
+                version-sym
+                cfg:version)
+        (format #t (G_ "
   -l FILE.log, --~a=FILE.log:
-    redirect the program standard output to FILE.log.
+      redirect the program standard output to FILE.log.")
+                log-file-sym)
+        (format #t (G_ "
   -e FILE.err, --~a=FILE.err:
-    redirect the program errors to FILE.err.
-
-General server-side options:
+      redirect the program errors to FILE.err.")
+                error-file-sym)
+        (format #t "\n")
+        (format #t (G_ "
+General server-side options:"))
+        (format #t (G_ "
   -p PORT, --~a=PORT:
-    set the server port to bind, 8080 by default.
+      set the server port to bind, 8080 by default.")
+                port-sym)
+        (format #t (G_ "
   -n URI, --~a=URI:
-    set the public server URI (scheme, userinfo, host, and port).
-
-Options for the resource server:
+      set the public server URI (scheme, userinfo, host, and port).")
+                server-name-sym)
+        (format #t "\n")
+        (format #t (G_ "
+Options for the resource server:"))
+        (format #t (G_ "
   -H HEADER, --~a=HEADER:
-    the HEADER field contains the webid of the authenticated user,
-    XXX-Agent by default. For the full server, disable webid-oidc
-    authentication.
+      the HEADER field contains the webid of the authenticated user,
+      XXX-Agent by default. For the full server, disable webid-oidc
+      authentication.")
+                header-sym)
+        (format #t (G_ "
   -b URI, --~a=URI:
-    set the backend URI for the reverse proxy, only for the
-    reverse-proxy command.
-
-Options for the identity provider:
+      set the backend URI for the reverse proxy, only for the
+      reverse-proxy command.")
+                backend-uri-sym)
+        (format #t "\n")
+        (format #t (G_ "
+Options for the identity provider:"))
+        (format #t (G_ "
   -k FILE, --~a=FILE.jwk:
       set the file name of the key file. If it does not exist, a new
-      key is generated.
+      key is generated. The server does not offer an HTTPS service.")
+                key-file-sym)
+        (format #t (G_ "
   -s WEBID, --~a=WEBID:
-      set the identity of the subject.
+      set the identity of the subject.")
+                subject-sym)
+        (format #t (G_ "
   -w ENCRYPTED_PASSWORD, --~a=ENCRYPTED_PASSWORD:
-      set the encrypted password to recognize the user.
+      set the encrypted password to recognize the user.")
+                encrypted-password-sym)
+        (format #t (G_ "
   -j URI, --~a=URI:
-      set the URI to query the key of the server.
+      set the URI to query the key of the server.")
+                jwks-uri-sym)
+        (format #t (G_ "
   -a URI, --~a=URI:
-      set the authorization endpoint of the issuer.
+      set the authorization endpoint of the issuer.")
+                authorization-endpoint-uri-sym)
+        (format #t (G_ "
   -t URI, --~a=URI:
-      set the token endpoint of the issuer.
-
-Options for the client service:
+      set the token endpoint of the issuer.")
+                token-endpoint-uri-sym)
+        (format #t "\n")
+        (format #t (G_ "
+Options for the client service:"))
+        (format #t (G_ "
   -c URI, --~a=URI:
       set the web identifier of the client application, which is
-      dereferenced to a semantic resource.
+      dereferenced to a semantic resource.")
+                client-id-sym)
+        (format #t (G_ "
   -r URI, --~a=URI:
       set the redirection URI to get the authorization code back. The
-      page is presented with the code to paste in the application.
+      page is presented with the code to paste in the application.")
+                redirect-uri-sym)
+        (format #t (G_ "
   -C NAME, --~a=NAME:
-      set the user-visible application name (may be misleading...).
+      set the user-visible application name (may be misleading...).")
+                client-name-sym)
+        (format #t (G_ "
   -u URI, --~a=URI:
       set an URI where someone would find more information about the
-      application (again, may be misleading).
-
-Environment variables:
-
+      application (again, may be misleading).")
+                client-uri-sym)
+        (format #t "\n")
+        (format #t (G_ "
+Environment variables:"))
+        (format #t (G_ "
   LANG: set the locale of the user interface (for the server commands,
-the user is the system administrator).~a
-
+      the user is the system administrator)."))
+        (when (getenv "LANG")
+          (format #t (G_ "the-environment-variable|
+      It is currently set to ~s.")
+                  (getenv "LANG")))
+        (format #t (G_ "
   XDG_DATA_HOME: where the program stores persistent data. The
-identity provider stores the refresh tokens. The full server stores
-the resources there. For a system service, it is recommended to set it
-to /var/lib.~a
-
+      identity provider stores the refresh tokens. The full server
+      stores the resources there. For a system service, it is
+      recommended to set it to /var/lib."))
+        (when (getenv "XDG_DATA_HOME")
+          (format #t (G_ "the-environment-variable|
+      It is currently set to ~s.")
+                  (getenv "XDG_DATA_HOME")))
+        (format #t (G_ "
   XDG_CACHE_HOME: where the program stores and updates the seed file,
-and the web client cache. You can remove this directory at any
-time. The seed file will be initialized from /dev/random.~a
-
+      and the web client cache. You can remove this directory at any
+      time. The seed file will be initialized from /dev/random."))
+        (when (getenv "XDG_CACHE_HOME")
+          (format #t (G_ "the-environment-variable|
+      It is currently set to ~s.")
+                  (getenv "XDG_CACHE_HOME")))
+        (format #t (G_ "
   HOME: if XDG_DATA_HOME or XDG_CACHE_HOME is not set, they are
-computed from the value of the HOME environment variable. It is not
-used otherwise.~a
-
-Running a reverse proxy
-
+      computed from the value of the HOME environment variable. It is
+      not used otherwise."))
+        (when (getenv "HOME")
+          (format #t (G_ "the-environment-variable|
+      It is currently set to ~s.")
+                  (getenv "HOME")))
+        (format #t "\n")
+        (format #t (G_ "
+Running a reverse proxy"))
+        (format #t (G_ "
 Suppose that you operate data.provider.com. You want to run an
 authenticating reverse proxy, that will receive incoming requests
 through http://localhost:8080, and forward them to
@@ -366,8 +441,9 @@ https://private.data.provider.com. The backend will look for the
 XXX-Agent header, and if it is found, then its value will be
 considered the webid of the authenticated
 user. https://private.data.provider.com should only accept requests
-from this reverse proxy.
-
+from this reverse proxy."))
+        (format #t "\n")
+        (format #t (G_ "
     ~a ~a \\
       --~a 'https://data.provider.com/server-source-code.tar.gz' \\
       --~a 8080 \\
@@ -375,13 +451,20 @@ from this reverse proxy.
       --~a 'https://private.data.provider.com' \\
       --~a 'XXX-Agent' \\
       --~a '/var/log/proxy.log' \\
-      --~a '/var/log/proxy.err'
-
-Running an identity provider
-
+      --~a '/var/log/proxy.err'")
+                (car (command-line))
+                (G_ "command-line|command|reverse-proxy")
+                complete-corresponding-source-sym
+                port-sym server-name-sym backend-uri-sym header-sym
+                log-file-sym error-file-sym)
+        (format #t "\n")
+        (format #t (G_ "
+Running an identity provider"))
+        (format #t (G_ "
 The identity provider running at webid-oidc-demo.planete-kraus.eu is
-invoked with the following options:
-
+invoked with the following options:"))
+        (format #t "\n")
+        (format #t (G_ "
     export XDG_DATA_HOME=/var/lib
     export XDG_CACHE_HOME=/var/cache
     ~a ~a \\
@@ -393,103 +476,70 @@ invoked with the following options:
       --~a 'https://webid-oidc-demo.planete-kraus.eu/keys' \\
       --~a 'https://webid-oidc-demo.planete-kraus.eu/authorize' \\
       --~a 'https://webid-oidc-demo.planete-kraus.eu/token' \\
-      --~a $PORT
-
-Running the public pages for an application
-
-webid-oidc-demo.planete-kraus.eu is configured this way:
-
+      --~a $PORT")
+                (car (command-line))
+                (G_ "command-line|command|identity-provider")
+                complete-corresponding-source-sym
+                server-name-sym key-file-sym subject-sym encrypted-password-sym
+                jwks-uri-sym authorization-endpoint-uri-sym
+                token-endpoint-uri-sym port-sym)
+        (format #t "\n")
+        (format #t (G_ "
+Running the public pages for an application"))
+        (format #t (G_ "
+The example client application pages for
+webid-oidc-demo.planete-kraus.eu are served this way:"))
+        (format #t "\n")
+        (format #t (G_ "
     ~a ~a \\
       --~a 'https://webid-oidc.planete-kraus.eu/complete-corresponding-source.tar.gz' \\
       --~a 'https://webid-oidc-demo.planete-kraus.eu/example-application#id' \\
       --~a 'https://webid-oidc-demo.planete-kraus.eu/authorized' \\
       --~a 'Example Solid Application' \\
       --~a 'https://webid-oidc.planete-kraus.eu/Running-a-client.html#Running-a-client' \\
-      --~a $PORT
-
-If you find a bug, then please send a report to ~a.
-")
-                ;; Usage:
+      --~a $PORT")
                 (car (command-line))
-                ;; Available commands:
-                (G_ "command-line|command|reverse-proxy")
-                (G_ "command-line|command|identity-provider")
                 (G_ "command-line|command|client-service")
+                complete-corresponding-source-sym
+                client-id-sym redirect-uri-sym client-name-sym client-uri-sym
+                port-sym)
+        (format #t "\n")
+        (format #t (G_ "
+Running a full server"))
+        (format #t "\n")
+        (format #t (G_ "
+To run the server with identity provider and
+resource server for one particular user, you need to combine the
+options for the parts."))
+        (format #t (G_ "
+    export XDG_DATA_HOME=/var/lib
+    export XDG_CACHE_HOME=/var/cache
+    ~a ~a \\
+      --~a 'https://webid-oidc.planete-kraus.eu/complete-corresponding-source.tar.gz' \\
+      --~a 'https://data.planete-kraus.eu' \\
+      --~a '/var/lib/webid-oidc/server/key.jwk' \\
+      --~a 'https://data.planete-kraus.eu/vivien#me' \\
+      --~a '$...alg...$...salt...$...hash...' \\
+      --~a 'https://data.planete-kraus.eu/keys' \\
+      --~a 'https://data.planete-kraus.eu/authorize' \\
+      --~a 'https://data.planete-kraus.eu/token' \\
+      --~a '...port...'")
+                (car (command-line))
                 (G_ "command-line|command|server")
-                ;; General options
                 complete-corresponding-source-sym
-                ;; help
-                help-sym
-                ;; version
-                version-sym
-                cfg:version
-                ;; log-file
-                log-file-sym
-                ;; error-file
-                error-file-sym
-                ;; General server-side options
-                ;; port
-                port-sym
-                ;; server-name
                 server-name-sym
-                ;; Options for the reverse proxy
-                ;; header
-                header-sym
-                ;; backend-uri
-                backend-uri-sym
-                ;; Options for the identity provider
                 key-file-sym
                 subject-sym
                 encrypted-password-sym
                 jwks-uri-sym
                 authorization-endpoint-uri-sym
                 token-endpoint-uri-sym
-                ;; Options for the client service
-                client-id-sym
-                redirect-uri-sym
-                client-name-sym
-                client-uri-sym
-                ;; Environment variables
-                (if (getenv "LANG")
-                    (format #f (G_ "an environment variable| It is currently set to ~s.")
-                            (getenv "LANG"))
-                    (G_ "an environment variable| It is currently unset."))
-                (if (getenv "XDG_DATA_HOME")
-                    (format #f (G_ "an environment variable| It is currently set to ~s.")
-                            (getenv "XDG_DATA_HOME"))
-                    (G_ "an environment variable| It is currently unset."))
-                (if (getenv "XDG_CACHE_HOME")
-                    (format #f (G_ "an environment variable| It is currently set to ~s.")
-                            (getenv "XDG_CACHE_HOME"))
-                    (G_ "an environment variable| It is currently unset."))
-                (if (getenv "HOME")
-                    (format #f (G_ "an environment variable| It is currently set to ~s.")
-                            (getenv "HOME"))
-                    (G_ "an environment variable| It is currently unset."))
-                ;; Running a reverse proxy
-                ;; Program name
-                (car (command-line))
-                ;; command
-                (G_ "command-line|command|reverse-proxy")
-                ;; options
-                complete-corresponding-source-sym
-                port-sym server-name-sym backend-uri-sym header-sym
-                log-file-sym error-file-sym
-                ;; Running an identity provider
-                (car (command-line))
-                (G_ "command-line|command|identity-provider")
-                complete-corresponding-source-sym
-                server-name-sym key-file-sym subject-sym encrypted-password-sym
-                jwks-uri-sym authorization-endpoint-uri-sym
-                token-endpoint-uri-sym port-sym
-                ;; Running the public pages for an application
-                (car (command-line))
-                (G_ "command-line|command|client-service")
-                complete-corresponding-source-sym
-                client-id-sym redirect-uri-sym client-name-sym client-uri-sym
-                port-sym
-                ;; Bug report
-                cfg:package-bugreport))
+                port-sym)
+        (format #t "\n")
+        (format #t (G_ "
+If you find a bug, then please send a report to ~a.")
+                cfg:package-bugreport)
+        (format #t "\n"))
        ((option-ref options version-sym #f)
         (format #t (G_ "~a version ~a\n")
                 cfg:package cfg:version))