Re: Should we start a Guix users wiki?

[ludo@gnu.org (Ludovic Courtès)]

Craig Barnes <cjbarnes18@gmail.com> skribis:

> On 08/09/15 15:37, Mark H Weaver wrote:
>> ludo@gnu.org (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’.