[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Should we start a Guix users wiki?
From: |
Ludovic Courtès |
Subject: |
Re: Should we start a Guix users wiki? |
Date: |
Thu, 10 Sep 2015 15:58:57 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.5 (gnu/linux) |
Craig Barnes <address@hidden> skribis:
> On 08/09/15 15:37, Mark H Weaver wrote:
>> address@hidden (Ludovic Courtès) writes:
[...]
>>> I have mixed feelings. There are several issues with a Wiki: one can
>>> hardly know which version of the software it’s talking about (whereas
>>> 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 ‘doc.am’ to
automatically check the examples. I think these wouldn’t be in-depth
tests. For example, for OS declarations, we could simply make sure that
‘guix system build EXAMPLE --dry-run’ passes. Likewise for the ‘guix
environment --load’ example.
WDYT?
I could add a couple of rules in ‘doc.am’ so that people have a template
to reuse when they add new examples.
(I do think we need VM- or container-based tests of complete systems,
but that’s 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’s a search facility at
<https://lists.gnu.org/archive/cgi-bin/namazu.cgi?idxname=guix-devel>
that is not perfect, but a good start.
Alternately there’s the GMane mirror at
<http://dir.gmane.org/gmane.comp.gnu.guix.devel>, 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’.