# guix-domentation-meetup-notes-01-15-2022 -rw-r--r-- 4.8 KiB View raw 
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
*1. yesterday someone in the chan mentioned the lack of links to (guix licenses) in https://guix.gnu.org/manual/en/html_node/Software-Freedom.html#Software-Freedom so I wanted to add something regarding that 
(I'm working on it already. kind of)

*2. document bag

*3. Specific guix functionalities
++ Build utilities (helper functions)
make-file-writeable
https://guix.gnu.org/manual/en/html_node/Running-Guix-Before-It-Is-Installed.html#Running-Guix-Before-It-Is-Installed
++ search paths 
+++ what do they do [they are different from wrappers]
+++ vs native-search-paths
+++ should be mentioned in propagated inputs, profiles
++ service extension 
+++ defining an extension is often done with (compose list ...), i dont understand it

*****4. create proper glossary and make links to it

******5. Documenting the documentation process
Which file(s) to modify
Send documentation in plain text or markdown or orgfile, whatever
Canonical way to compile the documentation (Makefile?, running cli binary)

***6. Document Guile: something like 
  - Is this symbol from Guile or Guix (discoverability by using repl)?
  - What does it do?
  - How is it used? (`,describe` and `,apropos` in `guile`)
  - how to search for help (`$ info guile` or `$ info guix`)
  - contribute docstrings to guile (srfi-1, first, second)

7. guix home

8. More efficient ways to search the irc log 
lfam pointed this out

9. Mailing list Download archive (l2md)
Download the mbox archive for guix-devel or other mailing list

10. Buddy System mentioned by rekado https://lists.gnu.org/archive/html/guix-devel/2022-01/msg00216.html

11. Add link to gitlab documentation repo (tranlating guix)
-------------------------------------------

guix build --keep-going -e '\
      (begin \
        (import (guix packages) (gnu packages) (guix build-system python)) \
        (fold-packages \
          (lambda (item acc) \
            (if (eq? python-build-system (package-build-system item)) \
              (cons item acc) acc)) \
          (list)))'
          
https://issues.guix.gnu.org/52505

------------------------------------------------------------------

******5. Documenting the documentation process

- Send documentation in plain text or markdown or orgfile, whatever
Doing it the right way (using texinfo, compiling (see below), etc...)

Guix is documented using the Texinfo system. However, if you are not yet familiar with it, we accept contributions for documentation in most formats. That includes plain text, markdown, org-mode, etc...

Documentation contributions can be sent to @email{guix-patches@@gnu.org}. Prepend @code{[DOCUMENTATION]} to the subject.

- Which file(s) to modify: doc/guix.texi and doc/contributing.texi, doc/guix-cookbook.texi for the cookbook

When you need to make more than a simple addition to the documentation, we prefer that you send a proper patch as opposed to sending an email as described above. @pxref{Submitting Patches} for more information on how to send your patches.

To modify the documentation, you need to edit @file{doc/guix.texi} and @file{doc/contributing.texi} (which contains this documentation section), or @file{doc/guix-cookbook.texi} for the cookbook. If you compiled the Guix repository before, you will have many more @file{.texi} files that are translations of these documents. Do not modify them, the translation is managed through @uref{https://translate.fedoraproject.org/projects/guix, Weblate}, @xref{Translating Guix} for more information.

Make reference to cookbook somewhere?

- Canonical way to compile the documentation (Makefile?, running cli binary):`make doc/guix.info` or `make doc/guix.html` (same with cookbook)
some tags you need for description/synopsis

To render your documentation changes, we recommend to execute one of the following commands: @command{make doc/guix.info}, @command{make doc/guix.html} for the manual. Run @command{make doc/guix-cookbook.info} for the cookbook.

@itemize
@item @command{make doc/guix.info} to compile the info manual. You can check it with @command{info doc/guix.info}.
@item @command{make doc/guix.html} to compile the HTML version. You can point your browser to the relevant file in the @file{doc/guix.html} directory.
@item @command{make doc/guix-cookbook.info} for the cookbook info manual.
@item @command{make doc/guix-cookbook.html} for the cookbook HTML version.
@end itemize

(I tried to enter a guix shell --pure -D guix to make the documentation, and it yelled that it couldn't find po4a-translate
working from
Génération 25        11 janv. 2022 11:14:34        (actuelle)
  guix 4b8a520
    URL du dépôt : https://git.savannah.gnu.org/git/guix.git
    branche : master
    commit : 4b8a5205a6c2d1894be955bf934b29767e9ffd1e

)

Attribution:
    
    jgart <jgart@dismail.de>
    Julien Lepiller <julien@lepiller.eu>
    Matt Trzcinski <matt@excalamus.com>
Gabor Boskovits <boskovits@gmail.com>
    Fabio Natali <me@fabionatali.com>