Craig Barnes <[email protected]> skribis: > On 08/09/15 15:37, Mark H Weaver wrote: >> [email protected] (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’.
