From mboxrd@z Thu Jan 1 00:00:00 1970 From: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=) Subject: Re: Should we start a Guix users wiki? Date: Thu, 10 Sep 2015 15:58:57 +0200 Message-ID: <877fny4bq6.fsf@gnu.org> References: <55EE0ADD.9050701@gmail.com> <87pp1tnsna.fsf@gnu.org> <87613l6kq4.fsf@netris.org> <55F15FB8.1010000@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:50053) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Za2NW-0005Dv-K7 for guix-devel@gnu.org; Thu, 10 Sep 2015 09:59:07 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Za2NQ-0004EE-16 for guix-devel@gnu.org; Thu, 10 Sep 2015 09:59:06 -0400 In-Reply-To: <55F15FB8.1010000@gmail.com> (Craig Barnes's message of "Thu, 10 Sep 2015 11:47:20 +0100") List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org To: Craig Barnes Cc: guix-devel@gnu.org Craig Barnes skribis: > On 08/09/15 15:37, Mark H Weaver wrote: >> ludo@gnu.org (Ludovic Court=C3=A8s) writes: [...] >>> I have mixed feelings. There are several issues with a Wiki: one can >>> hardly know which version of the software it=E2=80=99s talking about (w= hereas >>> the installed Info pages of PDFs necessarily match the installed >>> version), and more importantly, it tends to be disorganized, >>> unmaintained, and often misleading. > In order to make sure that examples in the manual aren't broken, > wouldn't something equivalent to python doctests be necessary to ensure > this? I think it would be worse to have a broken example in the manual > than somewhere else. If the number of examples grow this could be > equally unmaintainable. Good point. Examples that were added lately have been put in separate files so that we can at least manually test that they work as advertised. Now, I think it would be good to add targets in =E2=80=98doc.am=E2=80=99 to automatically check the examples. I think these wouldn=E2=80=99t be in-dep= th tests. For example, for OS declarations, we could simply make sure that =E2=80=98guix system build EXAMPLE --dry-run=E2=80=99 passes. Likewise for= the =E2=80=98guix environment --load=E2=80=99 example. WDYT? I could add a couple of rules in =E2=80=98doc.am=E2=80=99 so that people ha= ve a template to reuse when they add new examples. (I do think we need VM- or container-based tests of complete systems, but that=E2=80=99s a separate issue IMO.) > Going back to my original problem of finding information that isn't > currently in the manual, it would be great if there where an easier way > to search / browse the mailing list archives. This would make > extracting great examples to add to the manual easier. Any suggestions > would be appreciated. There=E2=80=99s a search facility at that is not perfect, but a good start. Alternately there=E2=80=99s the GMane mirror at , which supports both searching and browsing. The email client that I use, Gnus, also provides handy search facility and the ability to browse the complete history of a GMane group over NNTP. HTH, Ludo=E2=80=99.