From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:36774) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eO1dJ-0007Dw-Ao for guix-patches@gnu.org; Sun, 10 Dec 2017 08:27:06 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eO1dG-0008UR-4p for guix-patches@gnu.org; Sun, 10 Dec 2017 08:27:05 -0500 Received: from debbugs.gnu.org ([208.118.235.43]:45907) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1eO1dG-0008U8-23 for guix-patches@gnu.org; Sun, 10 Dec 2017 08:27:02 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1eO1dF-0003xq-Pn for guix-patches@gnu.org; Sun, 10 Dec 2017 08:27:01 -0500 Subject: [bug#29438] [PATCH 2/2] services: configuration: Show default values of list types. Resent-Message-ID: References: <20171125150531.26769-1-clement@lassieur.org> <87d145vw5z.fsf@gnu.org> From: =?UTF-8?Q?Cl=C3=A9ment?= Lassieur In-reply-to: <87d145vw5z.fsf@gnu.org> Date: Sun, 10 Dec 2017 14:26:39 +0100 Message-ID: <87shciogs0.fsf@lassieur.org> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+kyle=kyleam.com@gnu.org Sender: "Guix-patches" To: Ludovic =?UTF-8?Q?Court=C3=A8s?= Cc: 29438@debbugs.gnu.org Ludovic Courtès writes: > Clément Lassieur skribis: > >> * doc/guix.texi (Messaging Services): Regenerate it. >> * gnu/services/configuration.scm (show-default?): Fix recursion. >> * gnu/services/messaging.scm (show-default?): Fix recursion. > > Rather “Check VAL rather than DEFAULT.” > >> (prosody-configuration)[modules-enabled]: Remove default value from docstring. > > LGTM, though I’m afraid we’ll have a hard time keep guix.texi in sync, > at least until we have an automated mechanism to regenerate those bits. Thank you for reviewing! It's a bit sad that most services' docstrings are not in sync with the .texi file, it would be great to have an automated mechanism to update the documentation. I use a hackish Emacs snippet to maintain Prosody documentation, but something like "make generate-documentation " would be much better. I'll think about it. --8<---------------cut here---------------start------------->8--- @c The following documentation was initially generated by @c (generate-documentation) in (gnu services messaging). Manually maintained @c documentation is better, so we shouldn't hesitate to edit below as @c needed. However if the change you want to make to this documentation @c can be done in an automated way, it's probably easier to change @c (generate-documentation) than to make it below and have to deal with @c the churn as Prosody updates. --8<---------------cut here---------------end--------------->8--- I don't really agree with this comment that can be found in several places in our documentation. I believe that when there is a (generate-documentation) procedure, manual edits shouldn't be encouraged. But it's probably not worth updating it while there is no easy way to automatically generate the documentation. > Also, I was thinking that ‘guix system search’ could display > field/default-value pairs. I’m not 100% sure it’s a good idea because > that could be very verbose. > > Thoughts? It would be verbose indeed, and if people want to have details about fields and default values, they can search the manual.