From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms11 with LMTPS id YJhgFexST18MRwAA0tVLHw (envelope-from ) for ; Wed, 02 Sep 2020 08:08:12 +0000 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id FTs4EexST19oFwAAB5/wlQ (envelope-from ) for ; Wed, 02 Sep 2020 08:08:12 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 30B85940309 for ; Wed, 2 Sep 2020 08:08:11 +0000 (UTC) Received: from localhost ([::1]:34764 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kDNoO-00059B-Hz for larch@yhetil.org; Wed, 02 Sep 2020 04:08:08 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:41448) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kDNoI-00058z-TS for guix-patches@gnu.org; Wed, 02 Sep 2020 04:08:02 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:46656) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kDNoI-0001fT-KJ for guix-patches@gnu.org; Wed, 02 Sep 2020 04:08:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1kDNoI-0003RV-Ch for guix-patches@gnu.org; Wed, 02 Sep 2020 04:08:02 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#43159] [PATCH 0/2] Make 'guix help' helpful Resent-From: Efraim Flashner Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Wed, 02 Sep 2020 08:08:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 43159 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: Ludovic =?UTF-8?Q?Court=C3=A8s?= Cc: 43159@debbugs.gnu.org Received: via spool by 43159-submit@debbugs.gnu.org id=B43159.159903402813104 (code B ref 43159); Wed, 02 Sep 2020 08:08:02 +0000 Received: (at 43159) by debbugs.gnu.org; 2 Sep 2020 08:07:08 +0000 Received: from localhost ([127.0.0.1]:58202 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDNnO-0003P9-G3 for submit@debbugs.gnu.org; Wed, 02 Sep 2020 04:07:07 -0400 Received: from flashner.co.il ([178.62.234.194]:41430) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kDNnJ-0003O5-HP for 43159@debbugs.gnu.org; Wed, 02 Sep 2020 04:07:05 -0400 Received: from localhost (unknown [31.210.181.177]) by flashner.co.il (Postfix) with ESMTPSA id 93CEA40087; Wed, 2 Sep 2020 08:06:55 +0000 (UTC) Date: Wed, 2 Sep 2020 11:06:22 +0300 From: Efraim Flashner Message-ID: <20200902080622.GI856@E5400> References: <20200901203520.21103-1-ludo@gnu.org> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="cN519qCC4CN1mUcX" Content-Disposition: inline In-Reply-To: <20200901203520.21103-1-ludo@gnu.org> X-PGP-Key-ID: 0x41AAE7DCCA3D8351 X-PGP-Key: https://flashner.co.il/~efraim/efraim_flashner.asc X-PGP-Fingerprint: A28B F40C 3E55 1372 662D 14F7 41AA E7DC CA3D 8351 X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-Spam-Score: -1.0 (-) X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+larch=yhetil.org@gnu.org Sender: "Guix-patches" X-Scanner: scn0 Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx1.migadu.com: domain of guix-patches-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=guix-patches-bounces@gnu.org X-Spam-Score: -1.11 X-TUID: kQ0p4whTS9Uj --cN519qCC4CN1mUcX Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Tue, Sep 01, 2020 at 10:35:20PM +0200, Ludovic Court=C3=A8s wrote: > Hey Guix! >=20 > Here=E2=80=99s another long-overdue change that was brought to my > attention: making =E2=80=98guix help=E2=80=99 show a synopsis of each com= mand. > While at it, it also groups them in categories (I more or > less followed the manual, but there=E2=80=99s prolly room for > improvement, like a =E2=80=98packaging=E2=80=99 category maybe?): >=20 I dislike the idea that some commands are only for developers and some commands are "too advanced for the common user" (my words, not yours). Before bikeshedding about where the options should be, how about: commands for developers -> commands related to building advanced usage -> commands related to verification This way they're still "commands for everybody" and they're more descriptive than just "advanced" "expert" and "debug" style headers. > --8<---------------cut here---------------start------------->8--- > $ ./pre-inst-env guix help > Usage: guix COMMAND ARGS... > Run COMMAND with ARGS. >=20 > COMMAND must be one of the sub-commands listed below: >=20 > main commands: > deploy deploy operating systems on a set of machines > describe describe the channel revisions currently used > gc invoke the garbage collector > install install packages > package manage packages and profiles > pull pull the latest revision of Guix > remove removed installed packages > search search for packages > show show information about packages > system build and deploy full operating systems > time-machine run commands from a different revision > upgrade upgrade packages to their latest version > weather report on the available of pre-built package binaries >=20 > commands for developers: > build build packages or derivations without installing them > container run code in containers created by 'guix environment -C' > edit view and edit package definitions > environment spawn one-off software environments > import import a package definition from an external repository > pack create application bundles > refresh update existing package definitions >=20 > advanced usage: > archive manipulate, export, and import normalized archives (nars) > challenge challenge substitute servers, comparing their binaries > copy copy store items remotely over SSH > download download a file to the store and print its hash > git operate on Git repositories > graph view and query package dependency graphs > hash compute the cryptographic hash of a file > lint validate package definitions > offload set up and operate build offloading > processes list currently running sessions > publish publish build results over HTTP > repl read-eval-print loop (REPL) for interactive programming > size profile the on-disk size of packages >=20 > Report bugs to: bug-guix@gnu.org. > GNU Guix home page: > General help using Guix and GNU software: > --8<---------------cut here---------------end--------------->8--- >=20 > Much more=E2=80=A6 helpful than what we currently have, no? :-) >=20 > This works by introducing a new =E2=80=98define-command=E2=80=99 macro th= at each > command now uses and where it defines its synopsis. =E2=80=98guix help= =E2=80=99 > actually reads files in search of =E2=80=98define-command=E2=80=99, which= is cheaper > than loading each module and doing some sort of introspection. >=20 > The URL shown at the end (=E2=80=9CGeneral help=E2=80=9D) is also changed= , as was > rightfully suggested by zimoun a while back. >=20 > Thoughts? >=20 > Ludo=E2=80=99. >=20 > PS: We can talk about categories, but make sure to turn on the > bikeshedding limitation mode of your mail client. :-) >=20 > Ludovic Court=C3=A8s (2): > scripts: Use 'define-command' and have 'guix help' use that. > ui: '--help' output links to . >=20 > guix/scripts.scm | 29 ++++++++++- > guix/scripts/archive.scm | 5 +- > guix/scripts/authenticate.scm | 8 ++- > guix/scripts/build.scm | 5 +- > guix/scripts/challenge.scm | 5 +- > guix/scripts/container.scm | 6 ++- > guix/scripts/copy.scm | 5 +- > guix/scripts/deploy.scm | 3 +- > guix/scripts/describe.scm | 3 +- > guix/scripts/download.scm | 5 +- > guix/scripts/edit.scm | 7 ++- > guix/scripts/environment.scm | 5 +- > guix/scripts/gc.scm | 4 +- > guix/scripts/git.scm | 6 ++- > guix/scripts/graph.scm | 5 +- > guix/scripts/hash.scm | 5 +- > guix/scripts/import.scm | 8 ++- > guix/scripts/install.scm | 6 ++- > guix/scripts/lint.scm | 5 +- > guix/scripts/offload.scm | 6 ++- > guix/scripts/pack.scm | 5 +- > guix/scripts/package.scm | 4 +- > guix/scripts/perform-download.scm | 18 ++++--- > guix/scripts/processes.scm | 4 +- > guix/scripts/publish.scm | 5 +- > guix/scripts/pull.scm | 4 +- > guix/scripts/refresh.scm | 7 ++- > guix/scripts/remove.scm | 6 ++- > guix/scripts/repl.scm | 5 +- > guix/scripts/search.scm | 6 ++- > guix/scripts/show.scm | 4 +- > guix/scripts/size.scm | 7 ++- > guix/scripts/substitute.scm | 7 ++- > guix/scripts/system.scm | 4 +- > guix/scripts/time-machine.scm | 4 +- > guix/scripts/upgrade.scm | 6 ++- > guix/scripts/weather.scm | 4 +- > guix/ui.scm | 82 +++++++++++++++++++++++++++---- > 38 files changed, 249 insertions(+), 64 deletions(-) >=20 > --=20 > 2.28.0 >=20 >=20 >=20 >=20 --=20 Efraim Flashner =D7=90=D7=A4=D7=A8=D7=99=D7=9D = =D7=A4=D7=9C=D7=A9=D7=A0=D7=A8 GPG key =3D A28B F40C 3E55 1372 662D 14F7 41AA E7DC CA3D 8351 Confidentiality cannot be guaranteed on emails sent or received unencrypted --cN519qCC4CN1mUcX Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCgAdFiEEoov0DD5VE3JmLRT3Qarn3Mo9g1EFAl9PUnsACgkQQarn3Mo9 g1FDuxAAkbQQSp9tou8KxdrlxF2CoEKt+XsKsBaPwSf+jV0N6bneve9QuI8cvsRb dzjYdbOvF09t32HrDexCv/uytGrPxF/ldQHzejxevObqPJyPjnbc2KHaGg15FWZu yU12/SMkXLqIW+JRjjWFsLbH8gQlWmG4r6Q17RYY/IT22TExJWn7uHTUiwcWbh/p MeVc1KwLGx0TwEv5eU7n/jJNyoSg9ABB2c8njmqoAbCI+10f1NoTcKFIWFeOhq70 Bd1of3CXZ2MUm0TFVK8rLEs8IfuPVLkok6tbKZIKBKdOob3zuQaexFQQkI7hvCLL HTI85GeIj73rEZQni2DeLe/+4RkIIt1k1KrvC7HDVmXRNBd8QwMyJ3vF7YFE1NGZ am64YA6rJwwyYsrLLFD/WgvPW3Hf2HaprmiGSr4sup4lDjToCwQUJvYcbHQtNJjF S1tcqRKtlejKKEKi86cpDA1arCxgKPeXOTya9O593cz0KADz1AZ2kA/yP0Zx6W32 4G0485+3QzRtdVh3R3/94GEqXr0Fvd5ZqvNwgabweOwDIfYjkdKCkH9khS4XeNgL fLHSdEOnDQ/JOcAxKGHi3yThT0kf+BRkEj4zG5qi9j+No7Dv+mHEchiW3vDpWpY5 n6zHiPicgPiyaaGc//fOliwUAmUgfdYI9nuNBR73AJrVbN26Lrw= =xtBQ -----END PGP SIGNATURE----- --cN519qCC4CN1mUcX--