Re: [PATCH] doc: Clarify need to update search paths on foreign distro (was Re: Feedback of the GNU Guix manual)

[Matt]

  On Tue, 07 May 2024 22:41:33 +0200  Vagrant Cascadian  wrote --- 
  On 2024-05-07, m...@excalamus.com wrote:
   #+begin_quote
   6.7 L37 true for Guix System as well?
   The result of running ‘guix pull’ is a “profile” available 
under
   ‘~/.config/guix/current’ containing the latest Guix. Thus, 
make sure to
   add it to the beginning of your search path so that you use 
the latest
   version, and similarly for the Info manual (*note 
Documentation::):
  
   export PATH="$HOME/.config/guix/current/bin:$PATH"
   export 
INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
   #+end_quote
  
   As far as I know, exporting like this is only necessary on 
foreign distros.
  
   The attached patch makes this explicit.  It also provides 
information
   for people unfamiliar with the concept of a "search path" or 
how
   shells work by suggesting the exports be added to .bashrc and 
tries to
   clarify the consequences of not doing this.
  
  If the foreign distro has /etc/profile.d/*guix.sh installed, as
  implemented in the binary guix-install.sh script and also 
implemented in
  the Debian packaging, manually adding this is also arguably not
  necessary, unless they are using a shell that does not respect
  /etc/profile.d ... which, to my knowledge, is no different from Guix
  System really.
  
  There is also the issue of logging out and back in again (or 
manually
  adding the variables for one session), but that seems a little
  tangential, and again, is no different for Guix System than on 
foreign
  distros.

Should we remove the advice to update search paths and instead explain 
(IIUC) how guix.sh is added to /etc/profile.d?  Basically, does the reader need 
to take some action or is there some information about the system that would be 
relevant for  the reader regarding its use or maintenance?

[PATCH] doc: Clarify need to update search paths on foreign distro (was Re: Feedback of the GNU Guix manual)

[Matt]

We're working through a list of feedback one item at a time:
https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html

We have completed the first five items.  The sixth item was fixed already in
https://git.savannah.gnu.org/cgit/guix.git/commit/?id=cb3f833aaa5326e653b128bfd7b13d553f7c2a47

The next item reported is:

#+begin_quote
6.7 L37 true for Guix System as well?
The result of running ‘guix pull’ is a “profile” available under
‘~/.config/guix/current’ containing the latest Guix. Thus, make sure to
add it to the beginning of your search path so that you use the latest
version, and similarly for the Info manual (*note Documentation::):

export PATH="$HOME/.config/guix/current/bin:$PATH"
export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
#+end_quote

As far as I know, exporting like this is only necessary on foreign distros.

The attached patch makes this explicit.  It also provides information for 
people unfamiliar with the concept of a "search path" or how shells work by 
suggesting the exports be added to .bashrc and tries to clarify the 
consequences of not doing this.

Unnecessary words were struck to reduce the overall word count.  According to 
M-x count-words-region, the patch adds only 6 words (which is less than the 7 
needed for "users of Guix on a foreign distro", itself hard to reduce).

0001-doc-Clarify-need-to-update-search-paths-on-foreign-d.patch
Description: Binary data

[PATCH] Fix typo (Re: Feedback of the GNU Guix manual)

[Matt]

We're working through a list of feedback one item at a time:
https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html

We have completed the first four items.

The next item reported is:

#+begin_quote
3.8 Installing Guix in a Virtual Machine

L25 in an vm should be in a vm
#+end_quote

This is a nice, easy fix, good for me to practice getting the commit formatting 
correct :)


0001-doc-Fix-typo.patch
Description: Binary data

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Matt]

  On Fri, 19 Apr 2024 22:56:13 +0200  pelzflorian (Florian Pelz)  wrote --- 
 > Hello Matt, pushed as 86fb0e039bf30cf85e2066401f9a384427c47ea8.
 > 
 > I was bold enough to retain the xref change in (Setting Up the Daemon)
 > prompted by Ludo, because starting a sentence with @xref is recommended
 > in the Texinfo manual and its examples, while @pxref at the start of a
 > phrase is not preferrable, according to the “info "(texinfo)@pxref"”.
 > 
 > Again, Texinfo cross-references are complicated.
 > 
 > (In the German translations, I always wrote only @ref, but only because
 > @xref is not properly translated; Emacs in particular is not
 > internationalized at all.)
 
Sounds good, thank you!

Re: Creating a documentation team?

[Matt]

  On Fri, 19 Apr 2024 16:09:53 +0200  Ludovic Courtès  wrote --- 
 > Hi Florian and all,
 > 
 > I figure you’ve been doing a lot of review and writing of the manual.
 > Should we create a documentation team, of which you could be a honorary
 > member?  :-)
 > 
 > I feel like ensuring doc consistency, be it regarding the content,
 > terminology, typography, or use of markup, is a job in its own that
 > could be best reviewed by people familiar with and interested in those
 > issues.
 
I'm in favor of this and would enjoy continuing to help with the docs.

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Matt]

  On Tue, 16 Apr 2024 08:43:23 +0200  pelzflorian (Florian Pelz)  wrote --- 
 > Hi Matt.  When triple checking, I read in “info "(texinfo)@pxref"”:
 > 
 >In past versions of Texinfo, it was not allowed to write punctuation
 > after a '@pxref', so it could be used _only_ before a right parenthesis.
 > This is no longer the case.  The effect of '@pxref{NODE-NAME}' is
 > similar to that of 'see @ref{NODE-NAME}'.  However, in many circumstance
 > the latter is preferrable, as this makes it clear in the Info output
 > that the word "see" should be present.
 > 
 > Because of this last sentence, my tendency would now be to use @pxref
 > only for parentheses.  (Texinfo is really confusing.)  Should I just cut
 > these changes:
 > 
 > (Linux Services): Use @pxref to start phrase.
 > (Configuring the Shell): Use @pxref to start phrase.

Yes, I agree that cutting those, and using the original "see @ref{}", is what 
the Texinfo manual says is correct.  We should also cut this change:

(Setting Up the Daemon): use @xref to start sentence.

The original was also correct.

The only change that should remain is:

(Build Systems): capitalize "python" and start parenthesized reference with
@pxref.

Thanks for checking that.  I had it wrong and I learned something!

Re: Online social and patch review session on Monday

[Matt]

I wasn't able to make it today, unfortunately.  Hope you're all having, or had, 
a good time.  I'm looking forward to joining you next time.  Thanks again for 
running these!

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Matt]

  On Mon, 15 Apr 2024 14:58:50 +0200  pelzflorian (Florian Pelz)  wrote --- 

 > Do you agree that I should commit your docs correction with @pxref?
 > I believe it is an improvement over current “see @ref”, even though it
 > looks different in the info reader.
 
Yes, I agree and thank you for double checking.  Sorry for not answering you 
more clearly before!  @pxref is the correct command to use within parentheses.

 > I believe the Emacs errors are historical; looking at Emacs 29.3 as
 > packaged in Guix, Emacs-Info displays xref properly as See.  Display
 > errors had existed, but in the past only.

I reported it to emacs-devel (it's addressed now) and the issue isn't 
technically @xrefs; it's the compilation of @xref and @ref, '*Note' and '*note' 
respectively.  Emacs looks at the context around these and renders them as 
'See' or 'see' according to what's nearby.  The trouble is that the Texinfo 
documentation intends to show '*Note' and '*note' literally which is an 
exception to the Emacs logic.
  
I looked it up and the related Emacs code had been there for like 18 years...I 
have a knack for finding these kinds of dumb things.  I can't decide if it's a 
superpower or a super-curse. :)

 > Again thank you for tediously working through deficiencies in Guix’ docs.

Like Richard Hamming asks, "If what you're working on is not important and it's 
not likely to lead to important things, why are you working on it?"  I think 
Guix is important!  Thanks for sticking with me :)

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Matt]

  On Sat, 13 Apr 2024 13:26:39 +0200  pelzflorian (Florian Pelz)  wrote --- 

 > @xref produces a capital See instead of see.  This should be @pxref.
 > See the Texinfo manual “info texinfo” or the Web manual Ludo points to.
 > 
 > In info, this will use the word *note instead of *see, but it’s still
 > right, if Matt you agree.

Yes, rereading the linked docs, it is as you say.  

The problem is that the Emacs Info reader incorrectly renders cross-references 
by default.  I was reading the Texinfo documentation in Emacs.

The default Emacs rendering of the Texinfo info file looks like:

#+begin_src info
‘@xref’
 Used to start a sentence with an Info cross-reference saying ‘see
 NAME.’ or with 'See ...' in other output formats.

‘@ref’
 Used within or, more often, at the end of a sentence; produces an
 Info cross-reference saying ‘see NAME.’, and just the
 reference in other output formats, without the preceding 'See'.
#+end_src

Specifically, it misleadingly replaces info file instances of "*Note", which 
correspond to @xref, with (lowercase 's') "see ".

A workaround is use (setq Info-hide-note-references nil)

I was unable to fix the issue in Emacs and have filed a bug report.

 > Additionally, the commit message’s first sentence should end with a
 > period.  The sentences in the commit message describing a section should
 > start with a capital letter.

Thank you for the reminder.  I have made a note to check this for my future 
submissions.

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Matt]

  On Fri, 12 Apr 2024 22:16:39 +0200  Ludovic Courtès  wrote --- 

 > > See @ref{Substitutes} for how to allow the daemon to download pre-built 
 > > binaries.
 > 
 > Nitpick: this works but I believe the recommended approach is
 > “@xref{Substitutes} for how…”.
 > 
 >   
 > https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Cross-Reference-Commands.html
 
Good catch!  I took the opportunity and found several similar issues elsewhere. 
 The attached patch tries to correct them.

 > Thanks for reporting these issues!

I appreciate your assistance with these details :)


0001-doc-Fix-cross-references.patch
Description: Binary data

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Matt]

We're working through a list of feedback one item at a time:
https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html

We have completed the first three items.

The next item reported is:

#+begin_quote
3.7 After System Installation
L27 Libera_Chat, why the underscore. It is colored as well for me so
I guess this is a special char. Should be anways just Libera Chat
#+end_quote

"Libera_Chat" is not, or no longer, in the docs (d3fe763fe3).  However, there 
are two variations present: "Libera Chat" and "Libera.Chat".

The attached change updates "Libera Chat" to the "Libera.Chat" stylization.

The network itself is inconsistent in self-reference and provides no guideline 
I could find on which form to use.  I opted for the "dot" version to make 
things consistent.  Because the URL is https://libera.chat, someone searching 
for the network by copy-paste may arrive at the homepage more directly than 
with the non-dot version.


0001-doc-Standardize-IRC-stylization.patch
Description: Binary data

Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Matt]

We're working through a list of feedback one item at a time:
https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html

We have completed the first two items.

The next item reported is:

#+begin_quote
2.4 Setting up the deamon

Seems like an issue with info.  Have seen this in the Emacs manual as well.  
There is also sometimes see see (doc)

L15 See also see Substitutes.
#+end_quote

This sounds like the use of an @xref instead of @ref.  However, I can't find it 
in the current version (5a95cf76) of the documentation, nor the reported 
version (ee7c9d25).  The last change to doc/guix.texi at that the reported time 
was in e5ed1712 (git log -n 1 ee7c9d25 -- doc/guix.texi).

The full reported sentence currently reads,

#+begin_quote
See also @ref{Substitutes}, for information on how to allow the daemon to 
download pre-built binaries.
#+end_quote

The use of the comma after "Substitutes" is inappropriate, if I have the 
terminology correct, because "See also Substitutes" is not a participial 
phrase.  "Also" and "information on" are also unnecessary.  I suggest the 
following:

#+begin_quote
See @ref{Substitutes} for how to allow the daemon to download pre-built 
binaries.
#+end_quote

Searching for "see also" turns up the following in 'Mail Services':

#+begin_quote
See also ssl=required setting.
#+end_quote

This needs "the" before "ssl=required" as it refers to a specific setting.  It 
should probably use the @option or @samp markup:

#+begin_quote
See also the @samp{ssl=required} setting.
#+end_quote

I have opted for @samp because it's used elsewhere for similar items.  In the 
same section is:

#+begin_quote
NOTE: See also @samp{disable-plaintext-auth} setting.
#+end_quote

This too should have "the" before the setting.  The "NOTE:" designation is also 
unnecessary.  I suggest:

#+begin_quote
See also the @samp{disable-plaintext-auth} setting.
#+end_quote

Included is a patch which makes these suggested changes.

It was advised to submit the previous patch to guix-patches.  I opted to submit 
this next patch here to keep the thread connected since it's part of a larger 
discussion (I suppose).  If we're agreed that guix-patches is more appropriate, 
I can submit the next item in a new thread there using the same message format 
I've been following.  Thoughts?


0001-doc-Fix-grammar-and-markup.patch
Description: Binary data

Re: doc: installation: fix ~root confusion (was Re: doc: Removing much of Binary Installation)

[Matt]

There are several actions which we have deferred and other topics
which still need to be addressed, such as those raised by Vagrant and
Suhail.  My hope is to 1) resolve and merge this immediate patch, as
we appear to be converging on a consensus, 2) discuss how we could
better handle documentation changes than how I've handled them here
(that is, in one ever evolving diff), 3) compile a list of deferred
actions, 4) compile a list of deferred topics, and 5) address points 3
and 4 according to 2.

 On Mon, 11 Mar 2024 16:54:01 +0100  pelzflorian (Florian Pelz)  wrote ---
> Hi Matt.  I would almost want to push your changes, but we still
> disagree on some wordings.

I'm glad to hear the suggested changes are more acceptable than not.
Let's do what we need to get things right.

> Yes, however the removal means that we should move the sections
>
> * 2.2 Requirements
> * 2.3 Running the Test Suite
>
> to the Contributing manual in doc/contributing.texi.  WDYT?  You said,
> it could be a separate discussion, but in my opinion it would be part of
> the same patch.

I was thinking of the opposite, of moving "Building from Git" into
Installation.  What you say makes more sense and I agree.  Since the
suggested patch is already quite complex, I have not added moving
Sections 2.2 and 2.3 to the changes.  I propose we make the move in a
separate commit.

> > +@cindex foreign distro
> > +@cindex Guix System
>
> “@cindex Guix System” is inappropriate, because instructions on Guix
> System are not here.

Removed.  Good catch!

> > +You can install the Guix package management tool on top of an existing
> > +GNU/Linux or GNU/Hurd system@footnote{Currently only the Linux-libre
> > +kernel is fully supported. […]
>
> No.
>
> First of all, using guix-install.sh as per your instructions, one
> installs the Guix distribution *and* package management tool.  Either
> say “You can install the Guix package management tool and distribution”
> or “You can install Guix”.

I'm afraid I don't follow.  Where do you see the suggested changes
confusing the installation process for Guix as a distribution and Guix
as a package management tool?

The sentence you quote is the suggested first sentence for the Chapter
2: Installation.  The complete sentence reads,

"You can install the Guix package management tool on top of an
existing GNU/Linux or GNU/Hurd system(1), referred to as a "foreign
distro", or as a standalone operating system distribution, the "Guix
System"."

It literally says Guix is a package manager or a distribution.  No
mention of 'guix-install.sh' is made on that page.

The current "introduction" to Chapter 2: Installation is this:

"Note: We recommend the use of this  to
install Guix on top of a running GNU/Linux system, thereafter called a
foreign distro. The script automates the download, installation, and
initial configuration of Guix. It should be run as the root user."

https://guix.gnu.org/en/manual/devel/en/html_node/Installation.html

Maybe the diff didn't apply correctly?  Maybe it's confusing how the
Texinfo syntax puts the footnote markup in the middle of the source
sentence, even though footnotes render at the bottom of the page?

> Next, I believe Guix cannot currently be built on existing GNU/Hurd
> systems, because guile-fibers does not work.  I do not really know
> enough, but I would not mention Hurd support.

The are two issues here, what is said and what should be said.

Regarding what is said, the section we're talking about is for
installing not building.  You *can* install the Guix package
management tool on top of an existing GNU/Hurd system.  This is
exactly what the suggested changes say, minus the emphasis.  As far as
I know, it's true:

1. 
https://guix.gnu.org/en/blog/2020/a-hello-world-virtual-machine-running-the-hurd/
2. https://guix.gnu.org/en/blog/2020/childhurds-and-substitutes/

Further, the manual already mentions Hurd support:
https://guix.gnu.org/en/manual/devel/en/html_node/operating_002dsystem-Reference.html

Beyond the manual, there are two blog posts (linked above) which have explicit
sections about why it makes sense to develop for Hurd.  Code for Hurd
is mainlined with 80 files in the master branch providing Hurd
support.

I get it, it's the Hurd.  Running Guix on Hurd was part of a joke.
Correct me if I'm wrong, though: Hurd support wasn't the punchline,
ending support for Linux was.  The part that said, "running on the
Hurd was always a goal for Guix" is sincere.

So, what should be said is that Hurd support is limited.  Any errors
are bugs, either for Guix or for upstream.

I've updated the footnote to warn that Hurd support is currently
limited.

> Additionally “only the Linux-libre kernel” is incorrect, because
> running Guix on non-libre Linux is fully supported.  Running Guix
> System there 

doc: installation: fix ~root confusion (was Re: doc: Removing much of Binary Installation)

[Matt]

I realigned the subject.  It was previously changed to "doc: Removing much of 
Binary Installation" which is misleading.  The topic is how to clarify 
installation based on reported confusion, not about removing text.  The 
reported confusion was on the use of '~root'.  Explicit mention of '~root' is 
only necessary when the manual details how 'guix-install.sh' works.  Since 
'guix-install.sh' is the recommended method of installation, such level of 
detail is unnecessary, inappropriate, and impractical.  The suggested changes 
address the issue, only incidentally, by removing text.

I respond to Suhail Singh, Vagrant Cascadian, and pelzflorian in order.

 On Wed, 06 Mar 2024 22:18:33 +0100  Suhail Singh  wrote ---
> Suhail Singh suhailsingh...@gmail.com> writes:
>
> > FWIW, as an openSUSE Tumbleweed user, I believe Tumbleweed users who don't 
> > care if there is an easy way to uninstall Guix would be better served by 
> > using =guix-install.sh= as opposed to =zypper=.
> Btw, for completeness, on Tumbleweed, the user needs to take some additional 
> steps to ensure that restoring a previous Tumbleweed snapshot doesn't revert 
> Guix state.  Unless I'm misremembering, these steps are needed regardless of 
> whether =zypper= or =guix-install.sh= was used to install Guix.

Thank you for this.  I want to follow up with Vagrant and Florian first before 
responding more fully.

 On Wed, 06 Mar 2024 22:29:23 +0100  Vagrant Cascadian  wrote ---
> As the one who packaged and maintains guix in Debian...

Thank you for doing this work!

> The guix-daemon should continue to work from the packaged version, although 
> as guix develops more and more features; how long an old version can be 
> expected to continue to work remains an open question.

I was under the impression that Guix installed through a foreign package 
manager is able to update with 'guix pull'.  This is what the current 
documentation says,

"If you’re running Debian or a derivative such as Ubuntu, you can instead 
install the package (it might be a version older than 0.0-git but you can 
update it afterwards by running ‘guix pull’):"

Is this correct?  Does 'guix pull' update Guix when installed through a foreign 
package manager?

 On Thu, 07 Mar 2024 18:03:50 +0100  pelzflorian (Florian Pelz)  wrote ---

> I first tried guix-install.sh on a Debian GNU/Hurd VM.  It fails, telling me:
>
> [1709825168.049]: [ INFO ] init system is: sysv-init
> [1709825168.059]: [ FAIL ] Unsupported CPU type: i686-AT386
>
> The script guix-install.sh cannot be used on any GNU/Hurd system.

Thanks for taking the time to test 'guix-install.sh' on Hurd.  This looks like 
a bug.

> Vagrant’s guix package is missing on Debian GNU/Hurd as well, which is fine 
> of course, but we should not claim otherwise.

Updated to specify "distributions" as "GNU/Linux distributions".

> Therefore, could you change it like the old instructions and only talk about 
> GNU/Linux?

I don't think that's appropriate.  Guix supports GNU/Linux and GNU/Hurd and the 
installation section needs to cover both.

There are two issues here:

1) Up to this point, the manual doesn't make clear that current GNU/Hurd 
support is limited

I've duplicated the footnote from the 'operating-system Reference' section 
which explains the current status of GNU/Hurd support: 
https://guix.gnu.org/en/manual/devel/en/html_node/operating_002dsystem-Reference.html

2) 'guix-install.sh' has a bug preventing installation on GNU/Hurd

Any takers?

> > If, instead, you want to install the complete GNU operating system, 
> > @pxref{System Installation}.
>
> Maybe better say “complete Guix operating system”?  *complete* GNU operating 
> system maybe should only be used for GNU/Hurd.

That line is directly copied from the current manual: 
https://guix.gnu.org/en/manual/en/html_node/Installation.html#FOOT4

I saw this and I agree with you.  It would be better stated as something like 
you suggest.  My intent was to do this in a separate patch.

> You suggested in your mail:
>
> Matt m...@excalamus.com> writes:
> > Readers interested in those details may read the code for 'guix-install.sh'.
>
> Could you add this suggestion to your diff?

I don't see that as relevant to the reader.  The ability to read the source is 
implicit in it being provided, which it is.

> IIRC, you are removing the manual installation.

Yes? No? I'm not sure how to respond.

The suggested changes remove superfluous commentary on the recommended binary 
installation process which create confusion.

The challenge in directly responding to your statement is there's not a clear 
cut-off between "install" and "configure."  To install, generally, means 
something like "situate artifacts so the user can make use of them".  Often, 
this is simply addi

Re: doc: Removing much of Binary Installation (was: Feedback of the GNU Guix manual)

[Matt]

  On Wed, 06 Mar 2024 18:15:05 +0100  pelzflorian (Florian Pelz)  wrote ---
 > Thank you Matt for the suggested diff.

Thank you for taking the time to review it!

 > > - Places directions for 'guix-install.sh' after directions to use 
 > > distribution-specific package managers, giving preference to those simpler 
 > > install processes over the more manual 'guix-install.sh' process
 >
 > I don’t feel qualified to judge, but is this the preference?  Arch wiki 
 > advises against the Arch AUR package: “Therefore, after updating Guix once, 
 > the AUR advantage really turns into a disadvantage, as there will be many 
 > unnecessary files in the /usr file tree that are part of the Guix AUR 
 > package but that are never used by Guix anymore.  Therefore, consider using 
 > the manual installation.” [0]
 >
 > [0] https://wiki.archlinux.org/title/Guix

Good question, I wondered about this after I submitted.

The current manual has instructions for using the Debian, Ubuntu, and openSUSE 
package managers.  These instructions are given after the recommendation for 
=guix-install.sh= along with the transition:

"If you’re running Debian or a derivative such as Ubuntu, you can instead 
install the package..."

"Instead" means "in place of something previously mentioned."  So, as written, 
installing with =guix-install.sh= and installing with those specific package 
managers have equal levels of recommendation.

Since users of foreign systems are likely familiar with the corresponding 
foreign package managers, in addition to their use being one step versus four, 
I vote that they appear first.

This is good information about the situation with Arch.  Maybe this is why Arch 
isn't mentioned?

I wonder if we should have similar concerns about the Debian and openSUSE 
packages?

 > The reason of existence for these distribution packages is probably similar 
 > to the reason why the Binary Installation section exists.
 >
 > As for the suggested diff where much of Binary Installation gets removed,
 >
 > > -@item
 > > -@cindex substitutes, authorization thereof
 > > -To use substitutes from @code{@value{SUBSTITUTE-SERVER-1}},
 > > -@code{@value{SUBSTITUTE-SERVER-2}} or a mirror (@pxref{Substitutes}),
 > > -authorize them:
 > > -
 > > -@example
 > > -# guix archive --authorize < \
 > > - ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
 > > -# guix archive --authorize < \
 > > - ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
 > > -@end example
 > > -
 > > -@quotation Note
 > > -If you do not enable substitutes, Guix will end up building
 > > -@emph{everything} from source on your machine, making each installation
 > > -and upgrade very expensive.  @xref{On Trusting Binaries}, for a
 > > -discussion of reasons why one might want do disable substitutes.
 > > -@end quotation
 >
 > I disagree with this chunk.  This must stay.  Not enabling substitutes is an 
 > option in guix-install.sh and the Guix System installer.  Users might want 
 > to enable substitutes later on.

Excellent point.

I have updated the patch with the following:

- Add commas in appropriate places; after "For...Ubuntu-based systems", 
"Likewise", and the 'or' within the list of substitutes
- Remove ')' from after 'guix pull'
- Clarify that 'guix-install.sh' guides users through the steps.  Previously, 
it was unclear if the script ran without user input.
- Add the substitute server setup with the following changes:
  + Make explicit that the default for binary installations is to build 
everything
  + Change "for a discussion of reasons why one might want do disable 
substitutes" (note the 'do' typo) to "for a discussion why this is the 
default".  This aims to state it positively and encourage people to consider 
the reasons.
- Emphasize that the substitute authorization code is an example and may need 
modification


v02-refactor-binary-installation-section.diff
Description: Binary data

Re: Feedback of the GNU Guix manual

[Matt]

We're working through a list of feedback one item at a time:
https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html

We have completed an item and are ready to work on the next one:

#+begin_quote
,** Binary Installation L88 and L95

~root is weird. Should be root or simply ~ for the user profile which would be 
root as root user.
#+end_quote

I agree.  I found it weird at first, too.

Two thoughts:

1. The use of "~root" is intentional
2. Section 2.1 Binary Install can be refactored to remove the reported 
confusion as well as the tarpit of shell related details

*1. The use of "~root" is intentional*

According to the Bash info and man pages, "~root" is a TILDE-PREFIX with "root" 
as the LOGIN NAME.  The TILDE-PREFIX is replaced with the home directory 
associated with the specified LOGIN NAME.

Using "~root" solves the problem of operations happening in the wrong location. 
 It ensures that commands reference the 'root' user's home directory.

- (original issue) 
https://lists.gnu.org/archive/html/guix-devel/2015-06/msg00085.html
- (separate issue) https://bugs.gnu.org/30728

*2. Section 2.1 Binary Install needs refactoring*

The Binary Installation section tries to solve the problem of guiding readers 
to install Guix as quickly and painlessly as possible.  This began as a 
step-by-step process which was later automated by 'guix-install.sh'.  Over 6 
years, 12 people have worked to make 'guix-install.sh' robust.  Because of 
these efforts, Section 2.1 Binary Installation has effectively become high 
level documentation for how 'guix-install.sh' works.

Like any code comment tends to drift out of sync with the source code, the 
current presentation of binary installations has become inconsistent and 
redundant.  Using 'guix-install.sh' is the recommended method for binary 
installation.  It's the first thing mentioned by Section 2 Installation and one 
of the first things mentioned by Section 2.1 Binary Installation.  It's 
inconsistent to say, "This is how to do it" and then proceed to explain how to 
*not* use the recommended method.

Key information, like the recommended installation method and the definition of 
"foreign distro", are improperly hidden inside notes.  Note blocks act as 
comments which, by definition, are secondary to the main point.  The main point 
is to use 'guix-install.sh' on foreign distros which don't provide their own 
packages for Guix.

The attached diff addresses these issues.  It fixes the root issue (pun 
intended) of whether or not to expect readers to understand '~root', as well as 
unmentioned issues also related to shell-specific knowledge like, "What does it 
mean to 'source'?"  Readers interested in those details may read the code for 
'guix-install.sh'.

The diff does the following:

- Clarifies at the top level that installing on a foreign distro has two 
methods: using packaged binaries and building from source
- Places the overwrite warning at the top level node and binary installation 
level node
- Moves the definition of "foreign distro" out of quotation
- Moves the foreign distro installation instructions out of quotation
- Summarizes the steps 'guix-install.sh' follows rather than trying to detail 
them
- Splits the requirements between system requirements for binary installations, 
GNU/Linux or GNU/Hurd, and requirements for running 'guix-install.sh', tar, 
wget, Xz
- Removes redundant instructions to use 'guix-install.sh'
- Places directions for 'guix-install.sh' after directions to use 
distribution-specific package managers, giving preference to those simpler 
install processes over the more manual 'guix-install.sh' process

v01-refactor-binary-installation-section.diff
Description: Binary data

Re: Guix Days: Patch flow discussion

[Matt]

  On Wed, 28 Feb 2024 18:51:16 +0100  Giovanni Biscuolo  wrote --- 
 
 > ...and apologise if I still cannot do more to help.

We do what we can when we can.  And you have done things to help.  Thank you 
for sharing your thoughts and perspective!  If there's nothing you can do at 
the moment, that's okay.  I have no doubt you'll step up again when you see an 
opportunity.  Who knows, someone may even delegate... ;)

Re: Google Season of Docs 2024

[Matt]

  On Fri, 23 Feb 2024 10:18:33 +0100  Adam McCartney  wrote --- 

 > > 2. Would one of you readers be interested by being technical writer?
 > > 3. Any for improving the documentation?

I'm always interested in improving the Guix documentation.

 > I'm quite new to guix, so reading through many docs for the first time and
 > trying out various workflows. I'm taking notes on the various things that 
 > work.

I like this approach of someone new reading through the documentation, taking 
notes on errors and challenges, and providing a list of findings.  I'm 
currently working through a thread where someone did just this and we're 
working through the points one at a time[1].

[1]: https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html

 > In the past I've enjoyed using tutorials like "vimtutor" or emacs' "M-x
 > help-with-tutorial" when trying to break the ice with a completely new piece 
 > of
 > software. Writing something similar for guix might be fun?
 
I think a series of case studies which walk through increasingly difficult 
packaging processes would be a good idea.  It would give new users insight into 
what the packaging process looks like, would identify common tricks that work 
across packages, and would highlight problems in the documentation.

I created a template a while back which uses GNU Hello: 
https://codeberg.org/excalamus/guix-packaging-tutorial/src/branch/master/guix-packaging-tutorial.org#user-content-headline-13

Last month, I started writing a case study for packaging posh, the 
Policy-compliant Ordinary SHell.  It's incomplete yet will hopefully will give 
a clearer idea of what I'm thinking.  I've attached it to this email.

guix-packaging-tutorial-posh.org
Description: Binary data

Re: Feedback of the GNU Guix manual

[Matt]

  On Fri, 23 Feb 2024 03:46:29 +0100  Maxim Cournoyer  wrote --- 

 > Great, sounds good.  I've checked your v2 update, but opted to keep
 > things as they are (following my own edition of your initial work, which
 > was committed).

No problem, I think what you did looks good.

 > Thank you for your efforts!
 
Likewise, excited to be working on this.

Re: Feedback of the GNU Guix manual

[Matt]

  On Wed, 21 Feb 2024 18:20:19 +0100  Maxim Cournoyer  wrote --- 

 > Thanks for the follow-up.

Thank you!  Seems like we were looking at it at about the same time :)

 > Like Josselin, I prefer to keep the mention that the tarball archive
 > includes the transitive dependencies of Guix (it's explicit; "archived
 > binaries" is a bit vague to my taste).

I tried to address that in the diff I wrote up before I saw your message.  I 
agree, "archived binaries" is awkward.  I changed it in my update.

 > I've pushed your adjusted suggestions with commit ec9c8b0c1a.
 
Cool.  I'll work on the next item in the list.  Please let me know if there's 
something more regarding this item based on the v2 update.

Re: Feedback of the GNU Guix manual

[Matt]

  On Sun, 18 Feb 2024 14:55:46 +0100  Josselin Poiret  wrote --- 

 > Matt m...@excalamus.com> writes:
 > 
 > > Specific mention of installing Guix's dependencies was removed.  Guix 
 > > being installed implies that its dependencies are also installed.
 > 
 > I don't agree here: it's often the case in Linux-land that binary
 > archives are provided without their dependencies included, assuming that
 > the user already has them, often by installing them via their own
 > package manager.  Keeping the mention that it is self-contained and that
 > the dependencies are also included might clarify the situation for some
 > users.

Thank you for the feedback.

I opted for only "self-contained" which seems to imply that dependencies are 
available, in addition to other things, perhaps like setting an environment or 
pathing.  If "self-contained" is distinct from "includes dependencies," we 
could append something like "...and includes all dependencies" to the last 
sentence.

I also tried to distinguish that it's the installation *process* which requires 
GNU-tar and Xz and not the final installation, since that's self-contained.

Otherwise, I tried to simplify the language:

- archived binaries -> a binary archive
- are often quicker -> often go faster
- which is described in the next sections -> described later

This version has fewer words and one more sentence.  However, each sentence has 
a single, hopefully clear, point:

1. What this section is about? Installing from a binary archive.
2. Why you might want this section? It's faster than building.
3. What's needed?  A Linux or Hurd-system with GNU-tar and Xz.
4. What do you get?  A self-contained Guix installation.

Original: Region has 5 lines, 3 sentences, 51 words, and 301 characters
v2:   Region has 5 lines, 4 sentences, 45 words, and 292 characters

If this is good, I can write up a commit message and format the change as a 
patch.

v2-0001-binary-installation.diff
Description: Binary data

Re: Feedback of the GNU Guix manual

[Matt]

Friendly bump.  Awaiting feedback or guidance.

Re: Feedback of the GNU Guix manual

[Matt]

Friendly bump.

Attached is a suggested diff.

A previous suggestion was made to change "system" to the proper noun "System", 
as in the "Guix System", within the Binary Installation section.  The change 
would occur in a warning that moving unpacked binary tarballs as directed on 
existing Guix installations will overwrite system files.

The suggested capitalization would be improper since the "system" referred to 
is "an arbitrary system" and not specifically the Guix System.

The broader context is that the change suggested occurs within the Binary 
Installation section.  Since, there is no apparent reason why a user of an 
existing Guix installation would need to perform a binary installation, this 
patch removes the warning sentence (containing the confusing usage of "system") 
and moves it to the beginning of the section so that readers may understand the 
risk at the start and to decide whether this section applies to them before 
reading further.

The change also corrects the overly broad term "arbitrary system" to the 
specific "Linux or Hurd-based system."  Guix does not work with BSD, Haiku, 
Windows, or Darwin systems.  While installing Guix on these systems may be 
possible, by some definitions of "install", doing so for an end-user would be 
silly, since it wouldn't function as expected.

The change also more accurately lists the requirements.  Previously, it was 
stated that only tar and Xz are required.  This is false since Guix requires a 
Linux or Hurd-based system.

The explanation of "a self-contained tarball providing binaries for Guix and 
for all its dependencies" was reduced to the simpler "archived binaries."  
Generally, "tarball" is imprecise, hence the need to explain what it contains 
in this context.  Further, it's jargon, may not be familiar to some readers, 
and isn't relevant to the point of the introduction, that Guix may be installed 
without needing to compile and why that might be desirable.

Specific mention of installing Guix's dependencies was removed.  Guix being 
installed implies that its dependencies are also installed.

The warning line was added in commit:
https://git.savannah.gnu.org/cgit/guix.git/commit/?id=5dc3ce5f6c7990f44143f8e9bb9a873a014a82e4.
The warning orginates from this commit:
https://git.savannah.gnu.org/cgit/guix.git/commit/?id=09722b11e5e618028051d5f6d14eb13529dc7100

I see no associated issue referenced in the commits.  I assume the warning is 
simply being cautious.

#+begin_src diff
diff --git a/doc/guix.texi b/doc/guix.texi
index 4af830aed7..16349d4ec1 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -732,14 +732,16 @@ ready to use it.

 @cindex installing Guix from binaries
 @cindex installer script
-This section describes how to install Guix on an arbitrary system from a
-self-contained tarball providing binaries for Guix and for all its
-dependencies.  This is often quicker than installing from source, which
-is described in the next sections.  The only requirement is to have
-GNU@tie{}tar and Xz.
+This section describes how to install Guix from archived binaries.  Such
+installations are often quicker than building from source, which is
+described in the next sections.  Binary installations require a Linux or
+Hurd-based system with GNU@tie{}tar and Xz.
+
+@quotation Important
+This section only applies to systems without Guix.  Following it for
+existing Guix installations will overwrite important system files.

 @c Note duplicated from the ``Installation'' node.
-@quotation Note
 We recommend the use of this
 @uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
 shell installer script}.  The script automates the download, installation, and
#+end_src


0001-binary-installation.diff
Description: Binary data

Re: Feedback of the GNU Guix manual

[Matt]

  On Thu, 18 Jan 2024 20:44:53 +0100  Maxim Cournoyer  wrote --- 

 > That would be a good way to help, yes!  It'll be easier to review if
 > each distinct problem is fixed in its own commit (patch).

Now that I've looked more closely at it, I completely agree.

I suggest we take them point-by-point and move on only after we've completed 
each one in turn. 

** Binary installation L73
Guix system should be Guix System

*** Comment
Line 73 in the info file, section "Binary Installation" corresponds to
line 825 in =doc/guix.texi=.

=15efd5a7f4:doc/guix.texi= reads,

#+begin_quote
Do _not_ unpack the tarball on a working Guix system since that would
overwrite its own essential files.
#+end_quote

I see several issues with this sentence.  In order of severity:

1. the sentence isn't necessary
2. the problem is moving, not unpacking
3. the sentence confuses the subject
4. (reported) the word "system" is unclear

At this point in the manual, the reader has downloaded a Guix tarball
and has just been instructed to unpack and move the extracted files.
The sentence warns that moving =/tmp/var/guix= to =/var/= and
=/tmp/gnu= to =/= will overwrite files already there from an existing
Guix installation.

 1. the sentence isn't necessary
Is there ever a circumstance where a Guix installation, from a binary
or as a System, would need to install Guix from the tarball?

Unless there's a reason for a Guix user to follow the steps in "Binary
Installation," I suggest we remove this sentence and revise the
introduction paragraph to make sure current Guix users skip this
section.

--
Matt Trzcinski
Emacs Org contributor (ob-shell)
Learn more about Org mode at https://orgmode.org
Support Org development at https://liberapay.com/org-mode

Re: Guix at 37C3 Chaos Communication Congress in late Dec?

[Matt]

  On Thu, 18 Jan 2024 14:25:19 +0100  Andreas Enge  wrote --- 

 > And my (admittedly dated) experience seems to indicate that there is not
 > much point in joining non-existant Lisp forces.

I'm not sure what you mean by this statement.

Re: Feedback of the GNU Guix cookbook manual

[Matt]

  On Sun, 14 Jan 2024 16:15:57 +0100  Christian Miller  wrote --- 

 > I read the cookbook on revision
 > ee7c9d254117fa470686210ad2ef5e7f1ba4fefc using Emacs in TTY mode.
 >
 > Here are some things I noticed:

Thank you for taking the time to write these up!

--
Matt Trzcinski
Emacs Org contributor (ob-shell)
Learn more about Org mode at https://orgmode.org
Support Org development at https://liberapay.com/org-mode

Re: Feedback of the GNU Guix manual

[Matt]

I care about this.  How can I help?

- Convert the notes into patches?
- Proofread any patches that derive from Christian's efforts?
 
  On Sun, 14 Jan 2024 16:01:58 +0100  Christian Miller  wrote --- 

 > I read through the GNU Guix manual on revision
 > ee7c9d254117fa470686210ad2ef5e7f1ba4fefc with Emacs in TTY mode.

What's TTY mode?  M-x tty  reveals nothing for me.
 
 > As a beginner, the manual was helpful and I learned lot's of stuff.
 > Though it felt heartless.  No consistency and sometimes the structure
 > is confusing (especially the contributing part, since it tries to get
 > GNU Guix System and GNU Guix under one section and it was kinda
 > confusing for me).

Thank you for sharing your experience.  I'm sorry it wasn't more positive.  
I've found it challenging to read as well.

 > It seems that there is no style guide.  Sometimes default values are
 > mentioned and sometimes not.  Also some use uppercase and other use
 > lowercase for type of variable.  There is also Scheme code which is
 > most of the time in the old style notation.  For me as a beginner,
 > this was confusing.

The GNU project has several:

- https://www.gnu.org/prep/standards/html_node/Documentation.html
- https://www.fsf.org/licensing/gnu-press/GNU-Press-styleguide.pdf

 > I will mention lot's of style issues since at that time I did not know
 > it is in such a bad state.

I respectfully disagree that it's in bad taste to mention them.  I find such 
feedback helpful towards correcting the problems you experience.  I appreciate 
you taking the time to write them all up.  It's nice to know someone reads the 
manual! :)

--
Matt Trzcinski
Emacs Org contributor (ob-shell)
Learn more about Org mode at https://orgmode.org
Support Org development at https://liberapay.com/org-mode

Re: Guix at 37C3 Chaos Communication Congress in late Dec?

[Matt]

I enjoyed reading the retrospective.  It sounds like people had fun.  I'm sure 
the ones who asked questions appreciated the opportunity to ask them in person 
and connect with others in the community.  Thanks for putting it together!  

Re: Guix at 37C3 Chaos Communication Congress in late Dec?

[Matt]

  On Tue, 12 Dec 2023 17:56:04 +0100  Fabio Natali  wrote --- 

 > If anyone has any idea/feedback - or is planning to also be at Congress
 > - I'd be delighted to know.

Hi, I'm new to Hamburg and would like to participate in one of your sessions.  
I also see that tickets are €175!  Whoa!  I'm really only interested in 
connecting with others on Guix.   Maybe there's another time  people in Hamburg 
could meet up?

Re: git send-email

[Matt]

  On Sun, 19 Nov 2023 17:22:47 +0100  Philip McGrath  wrote --- 

 >  2. I wish there were a Guix package I could install to read the HTML 
 > documentation locally.

This is probably the simplest way:

1. guix shell wget
2. wget https://guix.gnu.org/manual/en/guix.html

According to the docs 
(https://guix.gnu.org/en/manual/devel/en/html_node/Writing-Documentation.html), 
the following should work (but doesn't for me):

1. git clone https://git.savannah.gnu.org/git/guix.git
2. cd guix
3. guix shell -D guix --pure
4. ./bootstrap
5. ./configure --localstatedir=/var --sysconfdir=/etc
6. make doc/guix.html

It fails with:

 MAKEINFO doc/guix.html
guix.texi:16880: @include: could not find os-config-bare-bones.texi
guix.texi:17057: @include: could not find os-config-desktop.texi
guix.texi:17064: @include: could not find os-config-lightweight-desktop.texi
make: *** [Makefile:4988: doc/guix.html] Error 1

It's worth noting that the Writing Documentation page links to Running Guix 
Before It Is Installed 
(https://guix.gnu.org/en/manual/devel/en/html_node/Running-Guix-Before-It-Is-Installed.html)
 when it probably meant to link the previous section Building from Git 
(https://guix.gnu.org/en/manual/devel/en/html_node/Building-from-Git.html) 
since it mentions needing to run ./configure first.

My guess is that the above steps will work if you run make before running make 
doc/guix.html.

Re: Enabling contribution through documentation

[Matt]

  On Mon, 06 Nov 2023 23:43:07 +0100 Samuel Christie wrote ---
 >
 > Hello Matt; sorry, I've been distracted and almost missed your reply a few 
 > weeks ago.

Not a problem!  I've been distracted, too.  :)

 > Any thoughts on process? Maybe we could have a repo managed the same way 
 > Guix is, so I can learn that at the same time. (That is, emails for 
 > discussion and patches to the tutorial) How hard would that be to get or set 
 > up?

A central repo makes sense.  I'm open to exchanging patches over email rather 
than doing PRs.

If it's okay with the Guix mailing list, I would be happy to have that exchange 
here so that others may observe, comment, and contribute.

I've set up a repo here: 
https://codeberg.org/excalamus/guix-packaging-tutorial/src/branch/master/guix-packaging-tutorial.org

 > After that, I think the first step is picking an easy but non-trivial 
 > package to do. Maybe it should be one that's already been packaged... I went 
 > through a list of packages that I wished Guix had, and sadly none of them 
 > were easy enough for me to do. My first choice was INN (a Usenet server), 
 > but it has multiple service dependencies I wasn't sure how to handle. My 
 > other choices were apparently in Rust, which always has waaay too many deps. 
 > We could also do a better Hello tutorial. Thoughts?

I think we should do a more detailed Hello tutorial.  It is already referenced 
in the cookbook, it's non-trivial, and this is the use case it was created for. 
 The package definition already exists (gnu/packages/base.scm).

Some words on the document:

I'd like to see the finished tutorial included in the cookbook.  For that, it 
needs to be written in Texinfo.  It's currently in Org.  That's simply what I'm 
most familiar with and the format my notes were in.  Org exports to Texinfo and 
info.  While I'm sure the conversion is imprecise, sticking with Org allows me 
(at least) to write more easily.  It's familiar and generates an (approximate) 
info file.  My intent is to focus on explaining the topic and worry about the 
details of Texinfo later.

Otherwise, Org provides a practical benefit: it embeds "live" source blocks.  
We can run all our shell calls from the document.  My hope is that this will 
keep the source code and shell call snippets accurate.

For anyone unfamiliar with Org, I've heavily annotated the document with 
explanations about how to navigate, edit, and transform it to other formats.  
If that's too much, that's okay.  Just edit the text and we can take care of 
any markup syntax later.

I'm excited to work on this with you and anyone else.  I'm curious what your 
thoughts are :)

Useful Info related Emacs functions (was Re: more than 1,800 dependent packages: website out of date)

[Matt]

  On Wed, 18 Oct 2023 19:55:17 +0200  Simon Tournier  wrote --- 

 > On Sat, 14 Oct 2023 at 12:11, Maxim Cournoyer maxim.courno...@gmail.com> 
 > wrote:
 > 
 > > Not to preach, but I've spent some time looking at 'info info' once and
 > > I'm sold to it now.  I basically use these keys: 'g' to navigate to
 > > nodes, 'm' to select a menu, 'space' to page down and 'backspace' to
 > > page up.
 > 
 > Yeah the tutorial is really good!  Well, I did it several times over the
 > past 10 years and, as I said, my muscle memory has hard time with
 > keybindings.  Hum, let try once again. :-)
 > 
 > Well, I added this to my configuration:
 > 
 > --88---
 > (define-key Info-mode-map (kbd "W")
 > #'(lambda ()
 > "Stash the current node name as URL for online manual."
 > (interactive)
 > (Info-copy-current-node-name)
 > (let* ((node (pop kill-ring))
 >(that (if (string-match "(\\([[:alnum:]]+\\)) \\(.*\\)" node)
 >  (if (string= "guix" (match-string 1 node))
 >  (concat
 >   
 > "https://guix.gnu.org/manual/devel/en/guix.html#;
 >   (replace-regexp-in-string " " "-"
 > (match-string 2 
 > node)))
 >node)
 >node)))
 >   (kill-new that)
 >   (message "%s" that
 > --88---
 > 
 > Let see if I use it. ;-)

Three unasked for tips:

1. There is also 'i' to search index topics
2. In the Emacs info browser, there is the command 'info-apropos' which (as far 
as I know) isn't bound to anything by default.  I bind it to 'a'.  It searches 
across *all* manuals on your system for a regex and presents a menu of results.
3.  I have a similar function to yours that I've expanded over the years which 
you may appreciate.  It's set up to work with the Guix, Guile, and Emacs 
manuals and will format a link as a URL or an Org mode link and place it in the 
kill-ring.  There is also an option to open the web version with the default 
browser.

(defun xc/Info-link-to-current-node ( arg)
  "Format current info node as url.

With no prefix, place the url corresponding to the current Info
node into the kill ring.

With universal prefix, visit url with default web browser and do
not put url into the kill ring.

With numeric prefix, create Org link with node name as
description into the kill ring."
  (interactive "p")
  (unless Info-current-node
(user-error "No current Info node"))
  (let* ((info-file (if (stringp Info-current-file)
(file-name-sans-extension
 (file-name-nondirectory Info-current-file
 (node Info-current-node)
 (url (cond
   ((or (string= info-file "emacs") (string= info-file "org"))
(concat "https://www.gnu.org/software/emacs/manual/html_node/;
info-file "/"
(if (string= node "Top") ""
  (concat (replace-regexp-in-string " " "-" node t) 
".html"
   ((string= info-file "guile")
(concat "https://www.gnu.org/software/guile/manual/html_node/;
(if (string= node "Top") ""
  (concat (replace-regexp-in-string " " "-" node t) 
".html"
   ((string= info-file "guix")
(concat "https://guix.gnu.org/en/manual/devel/en/html_node/;
(if (string= node "Top") ""
  (concat (replace-regexp-in-string " " "-" node t) 
".html"
   )))
(cond
 ((eq arg 1)  ; no prefix
  (kill-new url)
  (message "%s" (car kill-ring)))
 ((eq arg 4)  ; universal prefix
  (browse-url-default-browser url))
 (t   ; any other prefix
  (kill-new (format "[[%s][%s]]" url node))
  (message "%s" (car kill-ring))

I have it bound as:

(general-def :keymaps 'Info-mode-map
  "a" 'info-apropos
  "U" 'xc/Info-link-to-current-node 
 ; [U]rl
  "G" '(lambda () (interactive) (xc/Info-link-to-current-node 4)) ; 
[G]o to web version
  "O" '(lambda () (interactive) (xc/Info-link-to-current-node 16))  ; [O]rg 
link formatted
  "h" 'nil  ; hitting 'h' by accident kills all window arrangement
  )

Re: Enabling contribution through documentation

[Matt]

One elephant was already spoken about.  Your message points toward another: the 
Guile documentation.  The Guile documentation needs significant editing.

This is a problem because Guix is forever bound to Guile.  For every benefit 
Guix gains from Guile, it also suffers by inheriting its shortcomings.

  On Mon, 25 Sep 2023 17:13:58 +0200  Samuel Christie via "Development of 
GNU Guix and the GNU System distribution."  wrote --- 

 > My recommendation consists of three parts:
 >   1. Write a clear tutorial
 >  ...
 > Such a tutorial would be helpful for onboarding new contributors 
 > because they don't have to know anything before getting started, 
 > just start at the beginning and follow the steps. The tutorial I 
 > was envisioning would work through the steps of writing a simple 
 > package, testing it, then submitting the patches.

I tried this and reached the conclusion that it's not possible without 
addressing shortcomings in the Guile documentation.  

Specifically, I tried to write a tutorial on packaging GNU Hello.  Really, if I 
were to look over the shoulder of someone packaging GNU Hello, what would it 
look like?  Why are they doing what they're doing in addition to what and how.  
It's not obvious at all.  The Cookbook touches on GNU Hello.  However, it's 
hard to see how someone new to the details of Guix packaging, such as myself, 
is supposed to go from 'Section 2.1.1 A “Hello World” package' to actually 
packaging something in the wild.  All paths inevitably lead to the Guile manual.

Packaging is inherently complex.  It requires *at least* knowing something 
about Unix-like systems, build systems, and details of software development 
ranging from general programming concepts to specific applications to all the 
surrounding tooling.  

A common assumption is that "they don't have to know anything before getting 
started".  Unfortunately, this is not true.  Fortunately, we can often abstract 
this away by giving only the necessary information (not easy to do!) for 
whatever we're explaining and handing off details to another resource.  This is 
where the Guile documentation fails Guix.

For example, trying to understand (source (origin (method url-fetch) ... )), I 
looked at the Guix documentation.  The Guix documentation says,

#+begin_quote
'method' A monadic procedure that handles the given URI.

https://guix.gnu.org/en/manual/devel/en/html_node/origin-Reference.html
#+end_quote

I mistook 'method' to be a procedure that takes a URI.  But, no, it's a data 
type.

Several problems jump out to me:

1. The documentation assumes you understand how it's laid out.  Unless I missed 
it, there's no section explaining conventions used by the manual.  For example, 
https://www.gnu.org/software/emacs/manual/html_node/elisp/Format-of-Descriptions.html

2. There is not a clear way, even within Emacs, to figure out what 'method' is. 
 You *must* read the Guix manual.  This is the other elephant, the shortcomings 
of editors.

3. How, really, does someone who doesn't know what is meant by "Data Type" in 
this context supposed to get that information?  How are they to understand 
what's significant and what's not?  Trying to answer this inevitably leads to 
the Guile documentation.

 > Would any of you more 
 > experienced developers be willing to "shepherd" me through this 
 > process, and help set up the test environment, etc.?

I'd be happy to work alongside you.  

I'd also be happy to discuss the Guile docs in that mailing list.

Re: Guix related things in Germany at the end of October/start of November

[Matt]

  On Tue, 05 Sep 2023 19:28:09 +0200  Christopher Baines  wrote --- 

 > Is anyone else planning to attend these events, or otherwise interested
 > in meeting up in Germany around these dates?

I recently moved to Hamburg.  Thank you for informing the list (and 
particularly me) of these events!  I'd like to attend, if my schedule permits.

Plover plugin manager not working

[Matt]

I use the plover package for input and its plugin manager stopped working 
sometime last month.  I've been getting by without it (the base application 
loads and functions fine), occasionly trying to find the cause of the problem.  
Unfortunately, I've had no success fixing it.

Going back in my package generations, the plugin manager last worked May 9th.  
I updated packages May 11th and the plugin manager hasn't loaded since.  The 
Plover project hasn't had a release since last year and reverting changes to 
the plover package definition had no effect.  If I recall correctly, updates 
were made to Qt packages around this time?

QtTextToSpeech

[Matt]

I'm trying to get Text-To-Speech included within the python-pyqt package.

It looks like the definition is simply missing a declaration for qtspeech 
(patch attached).  I updated the definition, the package builds, and I'm now 
able to import the QtTextToSpeech module.  However, I'm not able to find an 
engine, so I can't verify that it's working 100%.

To validate the new pyqt functionality, I'm trying to get TTS working using the 
python-pyside-2 package.  That definition already has qtspeech included and I 
assume it works.  Unfortunately, I can't get that to work either.

I've installed speech-dispatcher, espeak, espeak-ng, and festival.  I'm able to 
get TTS from the command-line (i.e. spd-say, speak, etc.).  However, no voices 
or engine are found by PyQt or PySide.  I've verified that the same program 
works on a separate Debian machine.  Is there some setup for speech-dispatcher 
that I'm missing?

import sys
from PySide2 import QtCore, QtWidgets, QtTextToSpeech


class MainWindow(QtWidgets.QMainWindow):

def __init__(self):
super().__init__()

self.engine = None
self.engine_name = None

text ='''Every effort has been made to replicate this text as 
faithfully as
possible, including inconsistencies in spelling and hyphenation.  Some
corrections of spelling and punctuation have been made. They are
listed at the end of the text.'''

self.text_edit = QtWidgets.QTextEdit()
self.text_edit.setText(text)

self.speak_button = QtWidgets.QPushButton('Speak once')
self.speak_button.clicked.connect(self.on_speak_button_clicked)

# Central widget
layout = QtWidgets.QVBoxLayout()
layout.addWidget(self.text_edit)
layout.addWidget(self.speak_button)

centralWidget = QtWidgets.QWidget()
centralWidget.setLayout(layout)
self.setCentralWidget(centralWidget)

engineNames = QtTextToSpeech.QTextToSpeech.availableEngines()

if len(engineNames) > 0:
self.engine_name = engineNames[0]
self.engine = QtTextToSpeech.QTextToSpeech(self.engine_name)

voice = self.engine.availableVoices()[0]
self.engine.setVoice(voice)
else:
self.speak_button.setEnabled(False)

def on_speak_button_clicked(self):
text = self.text_edit.toPlainText()
self.engine.say(text)



if __name__ == '__main__':
app = QtWidgets.QApplication(sys.argv)
mainWin = MainWindow()
mainWin.show()
sys.exit(app.exec_())


0001-Add-qtspeech-to-python-pyqt.patch
Description: Binary data

Re: Guix Plover package issue

[Matt]

  On Sun, 28 Aug 2022 13:47:47 -0400  Maxime Devos  wrote --- 

 > Given that it does not exist, maybe you need 'plover' instead of 
 > python-plover.

Ah, yes. That works. Thank you.

Guix Plover package issue

[Matt]

I'm trying to use plugins with the version of Plover packaged in Guix.
For some reason, Plover isn't showing the plugin interface.  There is
normally a button which says "plugins".  Within Guix, that button
isn't there.

The Plover documentation says that the plugin installer can be accessed through

  plover -s plover_plugins list

This returns an error "no such script: plover_plugins".  It would seem
that the plugin module isn't along with Plover.

AFAICT, plugins are managed by the PyPI package plover-plugins-manager
(https://pypi.org/project/plover-plugins-manager/).  I've run guix
import pypi plover-plugins-manager and tried installing with guix
package --install-from-file.  Trying to follow the errors, I've got:

(use-modules
 (guix build-system python)
 (guix packages)
 (guix download)
 (gnu packages python-xyz))

(package
  (name "python-plover-plugins-manager")
  (version "0.7.1")
  (source (origin
(method url-fetch)
(uri (pypi-uri "plover_plugins_manager" version))
(sha256
 (base32
  "1nwzgcysxcmd7a46w1mjmc2a5gjmhhbx5qhhkas6zdjgdin9c67x"
  (build-system python-build-system)
  (propagated-inputs (list python-pip
   python-pkginfo
   python-plover
   python-pygments
   python-readme-renderer
   python-requests
   python-requests-cache
   python-requests-futures
   python-setuptools
   python-wheel))
  (native-inputs (list python-pytest python-pytest-shutil))
  (home-page "https://github.com/benoit-pierre/plover_plugins_manager;)
  (synopsis "Plugins manager for Plover")
  (description "Plugins manager for Plover")
  (license #f))

However, this fails on

ice-9/boot-9.scm:1685:16: In procedure raise-exception:
error: python-plover: unbound variable

Including (gnu packages stenography) doesn't resolve it.  Using guix
edit plover, I see that the definition is in
gnu/packages/stenography.scm. Which module should I be using?

Thank you!

Re: WhereIsEveryone, Guix Packaging Meetup Tomorrow, April 24th

[Matt]

Dang, just seeing this now!  Hope y'all had fun.  I'll catch you on the next 
one.

Re: Interest in "guix lint" Meetup?

[Matt]

  On Thu, 17 Mar 2022 21:04:13 -0400 Vagrant Cascadian  
wrote 
 > I haven't really done this sort of thing virtually before; Where would
 > be a good place to host it?

As an FSF associate member, you get access to the FSF's Jitsi meet instance 
(https://www.fsf.org/associate/benefits). I use it regularly and it works well. 
I'd be happy to host it.

Re: Interest in "guix lint" Meetup?

[Matt]

  On Thu, 17 Mar 2022 21:04:13 -0400 Vagrant Cascadian  
wrote 
 > The description and synopsis fixes are generally pretty easy, so might
 > make for good first steps for someone wanting to get familiar with the
 > process of contributing without having to invest a whole lot of time and
 > energy.

I would like to look over the shoulder of or pair programming with someone 
working on Guixy things. Count me in. I think this is a great idea.

Re: Creating subtitles for the Guix Days videos!

[Matt]

  On Sat, 05 Mar 2022 13:23:22 -0500 Blake Shaw 
 wrote 
 > Thank you so much! Thats awesome work. I'll take a look at the parts
 > that were difficult... but I'm not sure what software I need to use this
 > file format. Lmk and I'll get you the corrections.

You're welcome.

I used aegisub to do the captioning. The file appears to be a text format.  
Noticed that mpv auto-detected the subtitles when placed in the same directory 
as the video.

Re: Creating subtitles for the Guix Days videos!

[Matt]

  On Sat, 05 Mar 2022 05:01:35 -0500 Oliver Propst 
 wrote 
 > On 2022-03-05 06:30, Matt wrote:
 > > I've started on the "Deep Dive into the Guile Docs & Makeover Proposal" 
 > > talk.
 >
 > I  might be interested to help with adding 
 > subtitles to some parts of talk at some point in a not to distant 
 > future.

Cool.  It took me ~30 minutes to get to 4:15 in the video. The video is about 
79 minutes long. If my math is right and I work at that rate, it would take 
about 10 hours to finish.  :O  Every little bit counts.  

It looks like the .ass format simply appends each line of dialogue to the file, 
along with a time stamp.  The default time increment for aegisub looks to be 2 
seconds:

Dialogue: 0,0:03:45.00,0:03:47.00,Default,,0,0,0,,it allows us to
Dialogue: 0,0:03:47.00,0:03:49.00,Default,,0,0,0,,paint videos on
Dialogue: 0,0:03:49.00,0:03:51.00,Default,,0,0,0,,walls and

I think if you were to start at the halfway point or 3/4 (or whatever you have 
time for) of the video, we could merge it easily.

I hope you don't mind me replying to you on list.  I figure that's the most 
visible way to coordinate, in case others also want to help.  It'd be a shame 
if someone duplicated our efforts!

Re: Creating subtitles for the Guix Days videos!

[Matt]

I've started on the "Deep Dive into the Guile Docs & Makeover Proposal" talk.

I'm only about 4:15 in and it's a long one, like 79 minutes. If any wants to 
split it up, let me know. Otherwise I'll just chip away at it in between life.


guix-days-2022-documentation.ass
Description: Binary data

Re: Creating subtitles for the Guix Days videos!

[Matt]

  On Tue, 01 Mar 2022 22:44:18 -0500 Matt  wrote 
 > 
 >   On Tue, 01 Mar 2022 18:18:42 -0500 Matt  wrote 
 > 
 >  > I've started working on the "Dreaming of better patch review".  This is 
 > great steno practice!

I'm (finally) done!

There were some things he said that I couldn't understand. I notated all of 
them using square brackets and three question marks, [like this???]. You should 
be able to search on "???" to find them. 

It was an interesting talk with good points and some smart ideas.  I'm happy to 
have been able to make it more accessible to others.  :)

guix-days-2022-patch-review.ass
Description: Binary data

Re: Creating subtitles for the Guix Days videos!

[Matt]

  On Tue, 01 Mar 2022 18:18:42 -0500 Matt  wrote 

 > I've started working on the "Dreaming of better patch review".  This is 
 > great steno practice!

Got to about the 9:21 mark. Putting my work so far here in case I get abducted 
by aliens before I can complete it.

Guix - Packaging tutorial-R8DtPnP4eL8.ass
Description: Binary data

Re: Creating subtitles for the Guix Days videos!

[Matt]

  On Tue, 01 Mar 2022 09:36:19 -0500 Julien Lepiller  
wrote 
 > Hi Guix!
 > 
 > I'm looking for volunteers to create English subtitles for the Guix Days
 > talks. It would be great for people who are not very good with spoken
 > English but who can still understand text.
 > 
 > We have created a pad with the list of videos and steps to coordinate
 > and make sure we don't all work on the same videos. Please add you name
 > in front of the video you want to create subtitles for:
 > 
 > https://mensuel.framapad.org/p/guixdays2022-videosubtitles-9stl
 > 
 > You can use aegisub to create the subtitles. Note that it's a lot of
 > work (typically 1 hour for ~10 minutes of video), so I'd be glad for any
 > work you can do, even if it's partial. Please send me the subtitles once
 > they are completed, I'll add them with the videos.
 > 
 
I've started working on the "Dreaming of better patch review".  This is great 
steno practice!

Aegisub kept crashing when setting hotkeys, but I was able to set some up that 
make navigation easier.  

In the "subtitle edit box", I added:
Alt-P audio/play/line
Ctrl-N time/next
Ctrl-P time/prev

This is allows me to navigate by lines, play the audio for that section, and 
then press Return to "commit" what I wrote for the subtitle.

Re: Documentation of what is appropriate for #guix?

[Matt]

  On Sun, 20 Feb 2022 13:36:30 -0500 Vagrant Cascadian  
wrote 

 > I admittedly forget to check the messages from chanserv for channels I
 > frequent regularly, having personally grown accustomed to the norms of
 > the channel...
 
In my opinion, it's easy to miss.  I had to actively look for it.  I use Emacs 
erc.  When I start that program and log in, I'm in a buffer for "Libera.Chat". 
I then do /join #guix. This opens a new buffer, hiding the "Libera.Chat" buffer 
and showing a new "#g...@libera.chat"   buffer. The ChanServ message is printed 
to the buried "Libera.Chat" buffer.  The "#g...@libera.chat" buffer on connect 
has a giant wall of text showing who's in the chat.  It causes the buffer to 
scroll to the bottom, hiding anything printed to the top.  Scrolling up, I see 
some links to various topics. I see no rules or guidelines there.
 
 > So yes, linking to the Free System Distribution Guidelines implies what
 > is off-topic, though is still maybe not targeted towards online
 > communications; it more appears to be written with the audience of
 > someone making a free software distribution or auditing one. It seems
 > like the most relevent passage is:
 > 
 >   "A free system distribution must not steer users towards obtaining any
 >   nonfree information for practical use, or encourage them to do so. The
 >   system should have no repositories for nonfree software and no
 >   specific recipes for installation of particular nonfree programs. Nor
 >   should the distribution refer to third-party repositories that are not
 >   committed to only including free software; even if they only have free
 >   software today, that may not be true tomorrow. Programs in the system
 >   should not suggest installing nonfree plugins, documentation, and so
 >   on."
 > 
 > People often miss the part about not indirectly referring to non-free
 > software. Even if pointed to the FSDG, it is admittedly a bit hard to
 > grasp at times just what exactly constitutes "steer users towards
 > obtaining any nonfree information for practical use" or how it applies
 > to, say IRC. Individuals in IRC are not "the distribution", though the
 > new and long-time community members obviously make up perhaps the most
 > imporant part of the distribution.

I agree, it's hard to miss within the FSDG. Aside from linked (and not on a 
main screen), it's several sections down within the FSDG. 

 > I only bring this up because I regularly see this come up in the IRC
 > channel, and if an issue frequently comes up, usually that is a sign
 > that something could be improved in documentation, website, tooling,
 > etc. ... and when asked for one, I didn't have a good summary to point
 > to in my toolbox.
 > 
 > 
 > Maybe it is now my job to propose something concrete, but I was
 > curious what others thought before diving into details. :)

I think your observation matches what I've seen and I think your suggestion to 
address the problem makes sense.  If you know how to and where to do this, 
great. I wish I could be of more help.  I'm only able to cheer you on and give 
opinions.

Re: Documentation of what is appropriate for #guix?

[Matt]

  On Sat, 19 Feb 2022 21:33:47 -0500 Vagrant Cascadian  
wrote 
 > Every now and then someone stumbles into #guix and ask questions that
 > I've gleaned over time are off-topic (e.g. non-free software). While I
 > have a pretty good idea what is appropriate for the channel, it is not
 > clear to me where that is documentated.

I see the following when I connect to #guix:

-ChanServ- [#guix] Welcome to #guix, home of the GNU Guix project! | Be kind
   to everyone. Ground rules:
    |
   Non-free software is off-topic:
   

   | Leave messages with sneek: /msg sneek help

Re: Profile definition, was Re: bug#53224: Cookbook recipe about profile collisions

[Matt]

  On Tue, 18 Jan 2022 10:36:20 -0500 Ludovic Courtès  wrote 

 > Hi,
 > 
 > Leo Famulari  skribis:
 > 
 > > On Mon, Jan 17, 2022 at 12:56:20PM -0500, Matt wrote:
 > >> Leo is 100% correct that my understanding is still rather weak. I'll do 
 > >> my best despite that to help make the documentation better.
 > >
 > > I hope you will not feel too bad about that. Remember, everyone begins
 > > by not knowing anything. Your situation is not unique at all. Rather,
 > > your energy for improving the documentation for yourself and others is
 > > exemplary, and will improve Guix in the long run.
 > 
 > I agree, and I apologize for throwing my own guess of what you did and
 > did not do, Matt.
 
Hey, thanks.  I accept your apology and really appreciate it.  Recent 
interactions had left me feeling unheard and wondering whether I was wasting my 
time with the Guix community.  I appreciate being seen. I'll continue working 
with Leo and jgart on documentation.

Profile definition, was Re: bug#53224: Cookbook recipe about profile collisions

[Matt]

  On Mon, 17 Jan 2022 09:16:28 -0500 Ludovic Courtès  wrote 


 > > This person spent a lot of time trying to understand the situation and
 > > writing the blog post, but their understanding is still rather weak.
 > 
 > To be fair, the person didn’t look for “profile” in the manual.  I’m not
 > blaming—mentioning it to clarify what it is we’re trying to fix.

With all respect, I *did* look at "profile" in the manual. I spent a lot of 
time looking and trying to understand things.  I hear you say you're not trying 
to blame me and I trust that's not your intent.  However, what was said *does* 
blame me.  It says what I did and did not do, independent of reality: you are 
not me and you were not present.  Unfortunately, what was said carries all 
sorts of judgments and implications (ouch!) which, opposite to your intent, is 
not fair. 

I see you want clarification on what we're trying to fix. May I suggest instead 
asking, "What problem are we trying to solve?"

I see several problems beyond what I've already said.  However, I'll try to 
stick to just one that I encountered with the documentation.  Leo is certainly 
working toward something specific which I suspect is different from what I see. 
I'll let them speak for themselves.

I'm going to assume that you probably wanted to ask something like, "It looks 
to me like the manual adequately explains profiles.  But, since I'm the main 
architect of this system, maybe I have knowledge that someone new doesn't have. 
Person who is confused, are you able to say where you're confused?"

I would reply:

There are several places I've been confused. Let me give you a specific example.

The manual has at least four places that "profile" is defined:

1.  
[[https://guix.gnu.org/en/manual/en/html_node/Getting-Started.html#Getting-Started][(guix)
 Getting Started]] says,

#+begin_quote
"A profile is a directory containing installed packages"
#+end_quote

2.  
[[https://guix.gnu.org/en/manual/en/html_node/Invoking-guix-package.html#Invoking-guix-package][(guix)
 Invoking guix package]] says,

#+begin_quote
"a directory of installed packages"
#+end_quote

and 3, yet in the guix package options:

#+begin_quote
'-p PROFILE'
 Use PROFILE instead of the user's default profile.

 PROFILE must be the name of a file that will be created upon
 completion.  Concretely, PROFILE will be a mere symbolic link
 ("symlink") pointing to the actual profile where packages are
 installed:

  #+begin_example
  $ guix install hello -p ~/code/my-profile
  ...
  $ ~/code/my-profile/bin/hello
  Hello, world!
  #+end_example
#+end_quote

Elsewhere in (guix) Features is a 4th which says,

#+begin_quote
users have their own “profile”, which points to the packages that they actually 
want to use
#+end_quote

So, is the profile a directory or a pointer file (e.g. symlink)?  I tend to 
think of a directory as a container, like a manilla folder that contains 
papers.  To me, something that points is a file that contains a path to another 
location.  I see that I used the word "contains" to describe both file and 
directory, so maybe that's a sign to me I'm missing something there.

Regardless, I hope you can see that it's not always clear whether a profile is 
a directory or a file.  Yes, on Unix-like systems, directories are files. But 
Guix throws an error if you call =guix package -p= with a directory:

: guix package: error: rename-file: Is a directory

If you follow the symlinks, the profile is indeed a directory; it is a 
directory in the store.  But the way users interact with profiles is

  GUIX_PROFILE="$HOME/.guix-profile"
  . "$GUIX_PROFILE/etc/profile"

which is a file. And there are a bunch of symlinks in general. Those appear to 
be implementation details. But I think it's reasonable to say the abstraction 
isn't airtight and that, as a user, I have to interact with the implementation 
details at some level. Certainly at the documentation level. 

Leo is 100% correct that my understanding is still rather weak. I'll do my best 
despite that to help make the documentation better.

Re: Document /homeless-shelter?

[Matt]

  On Sun, 16 Jan 2022 13:25:57 -0500 Leo Famulari  
wrote 
 > On Sun, Jan 16, 2022 at 12:38:52PM -0500, Matt wrote:
 > > Subject: [PATCH] Document /homeless-shelter
 > 
 > I pushed a simpler addition to the manual:
 > 
 > https://git.savannah.gnu.org/cgit/guix.git/tree/doc/guix.texi#n1181

That looks great. 

 > > +The @env{HOME} environment variable is set to @file{/homeless-shelter}
 > > +during the build process.  This ensures builds are determistic and
 > > +highlights all uses of @env{HOME}.  Packages should not depend on the
 > > +pathname of a home directory.  Instead, modify the build phase to set
 > > +@env{HOME} to @file{/tmp}:
 > > +
 > > +@lisp
 > > +(modify-phases %standard-phases
 > > +  (add-before 'check 'fix-home-directory
 > > +(lambda _
 > > +  (setenv "HOME" "/tmp"
 > > +@end lisp
 > 
 > This text is basically correct but we have to balance verbosity with
 > readability.
 > 
 > The important thing was to document /homeless-shelter, so that packagers
 > understand it comes from Guix, and to explain its rationale.
 > 
 > It's not 100% true that setting HOME=homeless-shelter ensures that
 > builds are deterministic and highlights all uses of $HOME, although it
 > does help with those goals.
 > 
 > I don't think we want to document the use of /tmp, or recommend it as an
 > authoritative workaround.
 > 
 > Rather, it's a common solution, but packagers must seek to understand
 > how the package build scripts are trying to use $HOME and make a
 > judgement.
 > 
 > Additionally, I don't think that Build Environment Setup is the right
 > place to document workarounds.
 
This all looks sound to me. Thanks for taking the time to work with me on this.

Re: Document /homeless-shelter?

[Matt]

  On Sun, 16 Jan 2022 00:20:49 -0500 Leo Famulari  
wrote 

 > It could be documented briefly in the manual section Build Environment
 > Setup.

How does this look?

>From 34fcd075efad1577aa139012c5d2fccf44e10058 Mon Sep 17 00:00:00 2001
From: Matt 
Date: Sun, 16 Jan 2022 12:30:37 -0500
Subject: [PATCH] Document /homeless-shelter

---
 doc/guix.texi | 13 +
 1 file changed, 13 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index 42691570ff..fd48a0dcd2 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -1193,6 +1193,19 @@ environment variables for HTTP and HTTPS downloads it 
performs, be it
 for fixed-output derivations (@pxref{Derivations}) or for substitutes
 (@pxref{Substitutes}).
 
+The @env{HOME} environment variable is set to @file{/homeless-shelter}
+during the build process.  This ensures builds are determistic and
+highlights all uses of @env{HOME}.  Packages should not depend on the
+pathname of a home directory.  Instead, modify the build phase to set
+@env{HOME} to @file{/tmp}:
+
+@lisp
+(modify-phases %standard-phases
+  (add-before 'check 'fix-home-directory
+(lambda _
+  (setenv "HOME" "/tmp"
+@end lisp
+
 If you are installing Guix as an unprivileged user, it is still possible
 to run @command{guix-daemon} provided you pass @option{--disable-chroot}.
 However, build processes will not be isolated from one another, and not
-- 
2.34.0




0001-Document-homeless-shelter.patch
Description: Binary data

Document /homeless-shelter?

[Matt]

In the IRC, someone asked about an error message:

PermissionError: [Errno 13] Permission denied: '/homeless-shelter'

This error happened when trying to build a Python package, python-libpysal.

The solution was to set HOME to /tmp:

(arguments
 `(#:phases
   (modify-phases %standard-phases
 (add-before 'check 'fix-home-directory
   (lambda _
 ;; Tests fail with "Permission denied: '/homeless-shelter'".
 (setenv "HOME" "/tmp"

Basically, some projects expect a $HOME to be defined and will fail because 
Guix sets $HOME to /homeless-shelter, which doesn't exist in the build 
environment.

As I understand it, $HOME is set to /homeless-shelter during build because 
that's how Nix does/did it and "there’s no home
directory in build environments, and perhaps Eelco Dolstra and others back then 
found that setting ‘HOME’ to a non-existing directory broke
fewer builds that leaving it unset."

Is my understanding correct?

Is this something that should be documented, and if so, where?

IRC log:
https://logs.guix.gnu.org/guix/2022-01-16.log#003312

Previous Guix discussion: 
https://lists.gnu.org/archive/html/guix-devel/2019-11/msg00311.html

Re: Guix Documentation Meetup

[Matt]

  On Wed, 12 Jan 2022 13:41:10 -0500 Leo Famulari  
wrote 
 > On Sun, Jan 09, 2022 at 04:12:57PM -0500, Matt wrote:
 > > I did.  Maybe you missed the two blog posts I linked in the previous 
 > > email?
 > 
 > Yeah, I did miss that you intended to contribute them.
 > 
 > There is another side of my advice about submitting your contributions
 > however you can: It's still important to try to communicate clearly.
 > Your message includes several paragraphs of meta-discussion before
 > mentioning that you have some things to contribute, rather than just a
 > desire to contribute in general. Based on that, both me and Ricardo did
 > not understand that your blog posts were potential contributions.
 > 
 > Sorry if that comes across as harsh, but it's always true that
 > successful collaboration is helped by clear and concise communication.
 > 
 > Maybe that's a good thing, maybe it's a bad thing. It's the reality in
 > any collaborative environment where people are busy.
 > 
 > So, if you have a goal, my advice is to state it clearly and concisely.
 > 
 > If you have both long-term goals (make it easier to contribute
 > documentation) and short-term goals (add some Cookbook recipes or wiki
 > pages), then you should present them separately, or else people will
 > only focus on one of them.
 > 

This is good advice. I will take it to heart. I see how the ways I approached 
things didn't set things up for success. Thank you.

Re: Guix wiki

[Matt]

  On Tue, 11 Jan 2022 10:30:22 -0500 Tobias Geerinckx-Rice  
wrote 
 > Hullo Matt,
 > 
 > Matt 写道：
 > > I feel like it also says that community isn't important to us.
 > 
 > I understand how you could reach a flawed conclusion from a flawed 
 > assumption:
 > 
 > > Wikis are synonymous with community.
 > 
 > But it's still circular, wrong, and frankly quite offensive.


I didn't mean to say that you or the broader Guix community doesn't care. I can 
see how what I said was unclear and accused people of that. I'm sorry for that.

What I tried to say was *not* if someone values community that they must have a 
wiki. Instead, that a wiki is inherently based around community. If there's a 
wiki, there is implied community.  Of course, it's technically possible for 
someone to create, host, and maintain a wiki just for themselves. But given the 
options of not hosting, or using some other format (e.g. blog), the choice of a 
wiki strongly implies collaboration (which is the essence of community).

I was under the impression that the wiki linked to from the main page was *not* 
editable by non-FSF members. I was mistaken about that. If that were the case 
(non-editable), then I think it would reflect poorly.

I  tried to make the wiki more clear. I still think it's confusing for it to be 
there.

 > Guix cares about community very much.  Many of us care very little 
 > for wikis, having seen how they attract much outdated and 
 > incorrect information and spam.  Wikis are high-maintenance.
 
Given this situation, I see why.

 > I must say, the proponents of wikis have done an exceptionally 
 > poor job of representing them.  Yet we're supposed to be convinced 
 > that we're missing countless valuable contributions by people who 
 > can't be bothered to send a mail.

The reality is that wikis can be helpful and they can be misleading. I don't 
think anyone is under the impression that they will write and maintain 
themselves.

I'm not advocating for a wiki.  I'm saying, there is one currently linked to 
from the homepage. What should be done with it?

I'm willing to help maintain it.

Re: Guix wiki

[Matt]

  On Tue, 11 Jan 2022 18:18:25 -0500 Ricardo Wurmus  
wrote 

 > This is where we disagree.  I’ve wasted so much time in my life
 > following outdated or wrong instructions on forums or wikis.  I really
 > don’t want to see anything half-baked anywhere near this project.  There
 > are few things that frustrate me more than well-meaning but misleading
 > advice.
 
Do you know that the libreplanet wiki is linked to from the main Guix page?  
https://guix.gnu.org/ > Help > Wiki

I believe it proves your point. I was misled by its information. I'm not 
advocating for a wiki so much as a clear and easy path to contributing.  A wiki 
happens to be a common choice for that.

I updated it to try to remove the confusing content.

If it's not official and not wanted, I request removing it from the main page.

Re: Guix Documentation Meetup

[Matt]

  On Tue, 11 Jan 2022 21:57:03 -0500 Matt  wrote 
 > 
 >   On Tue, 11 Jan 2022 20:20:30 -0500 jgart  wrote 
 > 
 >  > Have you read ambrevar's post called 'Guix Profiles in Practice'?
 > > 
 >  > Unfortunately ambrevar's blog seems to be down at the moment:
 >  > 
 >  > https://ambrevar.xyz/guix-profiles/index.html
 >  > 
 > 
 > No, I haven't. Thanks!
 > 
 > It's archived: 
 > https://web.archive.org/web/20210415041114/https://ambrevar.xyz/guix-profiles/index.html
 
Actually, I have.  It's in the cookbook, (guix-cookbook) Guix Profiles in 
Practice.  

Re: Guix Documentation Meetup

[Matt]

  On Tue, 11 Jan 2022 20:20:30 -0500 jgart  wrote 

 > Have you read ambrevar's post called 'Guix Profiles in Practice'?
> 
 > Unfortunately ambrevar's blog seems to be down at the moment:
 > 
 > https://ambrevar.xyz/guix-profiles/index.html
 > 

No, I haven't. Thanks!

It's archived: 
https://web.archive.org/web/20210415041114/https://ambrevar.xyz/guix-profiles/index.html

 > > Cohesion is a big point in my outline. Maybe I could check for that as
 > > regards profiles?  
 > 
 > > Otherwise, maybe look over the contribute section. It
 > > seems like I could use a rereading of it. If there's anything that's
 > > unclear, the meeting might be a good space to address it.
 > 
 > roptat made a nice guide for learning texinfo:
 > 
 > https://learnxinyminutes.com/docs/texinfo/
 
Cool, it's been a bit since I used texinfo

Re: Guix wiki

[Matt]

  On Tue, 11 Jan 2022 10:17:43 -0500 Ricardo Wurmus  
wrote 
 > 
 > Matt  writes:
 > 
 > > To me, it says something like, we don't actually care about your
 > > contribution: you have to literally buy in first.
 > 
 > No, you do not.
 
I stand corrected.  Luis Felipe kindly pointed out what I had overlooked.

https://lists.gnu.org/archive/html/guix-devel/2022-01/msg00194.html

 > I see a lot of emotional language here, but the fact is: you can
 > contribute to our documentation by sending your text.  It’s that
 > simple. 

I'm sorry if you felt accused. I can see how it might come across that way.  It 
would have been better for me to just ask if I was missing something (which I 
was).

 > Send an email to guix-devel or guix-patches with a suitable subject so
 > that it doesn’t get lost in a discussion and take it from there.
 > 
 > > I feel like it also
 > > says that community isn't important to us.
 > 
 > I do not share your interpretation of the situation.

I'm glad because that means we're in agreement now that I see my mistake. :)

Re: Guix wiki

[Matt]

  On Mon, 10 Jan 2022 03:29:35 -0500 Josua Stingelin  
wrote 

 > I've been following the gnunet for a while so I felt qualified to comment.
 > 
 > > Concern 1: guix will be soon be distributed over gnunet
 > Guix could provide an endpoint in the gnunet network for users that prefer to
 > use it. However there's no reason to prevent it from being accessible using 
 > the
 > current TCP/IP stack.
 > 
 > The goal of gnunet is to replace the TCP/IP stack. It is built as an overlay
 > and underlay network. It can run on TCP/IP but could also replace it. Every
 > application using TCP/IP would have to be converted to use gnunet or
 > gnunet would have to emulate TCP/IP. Until then they'll run in parallel.

Thanks for explaining.  

 > > Concern 5: having a wiki may confuse what the primary source of 
 > > documentation is (i.e. the manual)
 > > 
 > >   I'm not sure I understand why this is a problem. Of course,
 > >   confusion should be minimized.  But the primary source of
 > >   documentation should be the one that best helps the user.  Ideally,
 > >   that is the manual.  Is there a negative consequence for the primary
 > >   source not being the manual?  For example, how many of you have used
 > >   the Arch wiki to solve problems for something other than the Arch
 > >   system?  Is that a problem?
 > 
 > I suppose that depends on the user. As a new linux user I tended to only use
 > the information available for my distro. Only after knowing the differences
 > from the distros have I started to use a wider spectrum for information.
 > 
 > That may primarily be a question of the target audience for guix?

My guess, as Guix is a package manager, there are two audiences: package users 
(end users) and package maintainers. I'm curious what degree of separation 
between those should exist for Guix. 

 > > Concern 8: the manual should have all the examples necessary for people to 
 > > understand how to tweak things
 > > 
 > >   Agreed.  Contributing to documentation also shouldn't be as
 > >   difficult as it currently is, but here we are.  Let's figure it out
 > >   together. :)
 > 
 > What about an online editing interface (analogous to Wikipedia) where 
 > everyone
 > can make edit suggestions.  Optimally directly converted to a patch by the
 > software.  Changes to the cookbook would have to be merged by the maintainers
 > and the community based wiki could either have a group of editors or a
 > consensus based workflow.
 > 
 > 
 > Personally I believe having one resource for information to be the preferred
 > solution. Maybe the Gentoo wiki could be a source of inspiration on what we'd
 > like to achieve?  (https://wiki.gentoo.org/wiki/Main_Page)

There is currently a wiki.  I could see it being a sandbox for what the manual 
may need.  But I also see disdain towards wikis by some here that's not 
unreasonable.

Re: Planet of Guix-related posts?

[Matt]

  On Mon, 10 Jan 2022 10:21:51 -0500 zimoun  
wrote 

 > (On a side note between parenthesis, we should avoid to fall into the
 > "Package Definition" tutorial fallacy; as explained here for monads
 > https://byorgey.wordpress.com/2009/01/12/abstraction-intuition-and-the-monad-tutorial-fallacy/.
 > And I wrote one post about monad and another about Packaging. ;-)
 > However, I think the official documentation has enough materials for
 > starting to package. End of parenthesis.)

If many people feel inclined to write their own packaging tutorial, it's 
probably an indication that the manual isn't sufficient.  I would urge you and 
others to not fall into the "don't touch it because it's good enough for me 
fallacy".  Others may, and probably do, see things differently.  

This is where I should say precisely what I think is unclear. Only that way can 
we find what the source of confusion is and maybe address it in the 
documentation.  I can't do that now, but the documentation meeting might be a 
good place for that.

 > Last, we have to distinguish between "temporary" content and
 > well-maintained documentation.  We discussed many times the Cookbook
 > and I think what we are trying with a limited success that this
 > document fits too much goals at the same time.  For instance, if I
 > would have to send a patch for fixing Wikipedia typo or adding a quick
 > paragraph about preconditioner of linear system, I would never just do
 > one or the other.  The Cookbook is currently too rigid for quick
 > half-backed recipes.

This is a good observation. What problem is the cookbook trying to solve? Once 
that's clear, we can make judgements about whether it accomplishes that goal.

Re: Guix Documentation Meetup

[Matt]

  On Tue, 11 Jan 2022 11:24:20 -0500 jgart  wrote 

 > I'm looking forward to having you at the next docs meetup:
 > 
 > https://lists.gnu.org/archive/html/guix-devel/2022-01/msg00189.html
 > 
 > Are there any particular sections in the guix manual that you would like
 > to work on in the meetup?

I outlined some interests here:  
https://lists.gnu.org/archive/html/guix-devel/2022-01/msg00105.html

I was just learning about profiles and how to use them to install multiple 
versions of a software. So, my head is there at the moment.  Cohesion is a big 
point in my outline. Maybe I could check for that as regards profiles?  
Otherwise, maybe look over the contribute section. It seems like I could use a 
rereading of it. If there's anything that's unclear, the meeting might be a 
good space to address it.

Mainly, I'm interested in getting to meet you and others from the community and 
hear what they value.

Re: Guix Documentation Meetup

[Matt]

 > I don't know how many people in the community have
 > non-CS/Unix/programming backgrounds so I share some personal thoughts
 > below.  It's not that I want to share my life, but it might resonate
 > with the experiences of others.

Thank you for sharing your story. It resonates with me as mine is similar.  I 
have degrees in math and statistics,  and am a self-taught programmer. I've 
worked a lot with scientists and engineers and have experienced the divide you 
describe. It can be a hard gap to bridge.

It a sounds like one of the things that makes you feel disconnected from Guix 
is your current skill level with Guile, Geiser, and general Unix knowledge. I 
can sympathize.  I've had the same kinds of challenges as were described by 
people earlier in the thread.

Re: Planet of Guix-related posts?

[Matt]

 > Hi,
 > 
 > My two points are:
 > 
 >  1. we could have a Guix planet -- we should avoid the cathedral for
 > quick recipes
 >  2. too many different goals are directed to the Cookbook
 > 
 > 
 > Well, my point is: instead of cathedral with an authority accepting
 > patches after review, why not a web syndication (bazaar) as a Planet
 > collecting various blogs.  This would help to stay aware.  For
 > instance, I read,
 > 
 > https://planet.haskell.org/
 > https://ocaml.org/community/planet/
 > https://planet.emacslife.com/
 > https://planet.scheme.org/
 > 
 > and many others and for Guix-related, basically, I use Ludo's toots as
 > such Planet.  Thanks Ludo. ;-)
 > 
 > Bah, I do not know if many blogs about Guix are around and how
 > frequently they would be updated.
 > 
 > Similarly, some time ago, an "awesome list" had been started and now,
 > quickly searching, I find 2:
 > 
 > https://github.com/techenthusiastsorg/awesome-guix
 > https://sr.ht/~lle-bout/awesome-guix/
 > 
 > Therefore, doing so...
 > 
 > On Sat, 8 Jan 2022 at 17:25, Matt  wrote:
 > 
 > > I have two documents written in Org:
 > > 1. http://excalamus.com/test-guix-case-study-plover-python-dictionary.html
 > 
 > (On a side note between parenthesis, we should avoid to fall into the
 > "Package Definition" tutorial fallacy; as explained here for monads
 > https://byorgey.wordpress.com/2009/01/12/abstraction-intuition-and-the-monad-tutorial-fallacy/.
 > And I wrote one post about monad and another about Packaging. ;-)
 > However, I think the official documentation has enough materials for
 > starting to package. End of parenthesis.)
 > 
 > 
 > > 2. http://excalamus.com/2021-10-06-guix-debug.html
 > 
 > ...it is possible to individually write using our preferred tools and
 > managed our way.
 > 
 >  Moreover, for instance, times to times, I write entries to my "blog":
 > 
 > https://simon.tournier.info/posts/
 > 
 > For example, this edited
 > <http://hpc.guix.info/blog/2021/10/when-docker-images-become-fixed-point/>
 > had been published before there
 > <https://simon.tournier.info/posts/2021-09-17-guix-pack-docker.html>.
 > 
 > Therefore, maybe people not afraid to write to their own blog but
 > afraid (or not knowing how to) to submit patches would provide
 > material for the official blog post, who knows. :-)
 > 
 > 
 > Last, we have to distinguish between "temporary" content and
 > well-maintained documentation.  We discussed many times the Cookbook
 > and I think what we are trying with a limited success that this
 > document fits too much goals at the same time.  For instance, if I
 > would have to send a patch for fixing Wikipedia typo or adding a quick
 > paragraph about preconditioner of linear system, I would never just do
 > one or the other.  The Cookbook is currently too rigid for quick
 > half-backed recipes.
 > 
 > In my views, for what they are worth, I think the level of
 > documentation should be:
 > 
 >  - manual as it is now
 >  - cookbook turned into a step by step comprehensive tutorial
 >  - wiki being a how-to-quickly-fix, similar to Arch wiki for instance
 > 
 > We have Guix manual which is really great.  We have Guile manual which
 > is really great once you know what you want.  What is missing in a
 > document in the middle and something similar to a wiki where it is
 > easy to edit and change.
 > 
 > For what the analogy is worth, Emacs manual and Emacs Lisp manual are
 > doing their job as manual.  However, if one is new to programming, the
 > document An Introduction to Programming in Emacs Lisp [1] is a great
 > resource because it is in the middle, IMHO.  The Cookbook should act
 > similarly.  Something as an official kind-of tutorial.
 > 
 > 1: https://www.gnu.org/software/emacs/manual/eintr.html
 > 
 > And somewhere an easy to edit half-maintained not-really reviewed wiki
 > where anyone could provide their material.

+1

Documentation is fundamentally about teaching. Having different avenues is 
needed to help structure learning. I think using Emacs as a model here is a 
great idea.

Re: Guix wiki

[Matt]

 > There are definitely wikis which use fairly simple markup
 > (e.g. markdown) and can usefully be read and updated online via a web
 > interface and git offline or online. The one I'm most familiar with is
 > ikiwiki (available in guix), though don't have a lot of experience
 > updating it via the web interface.

It looks like the web interface is simple yet sufficient, basically a text box 
and then the buttons you'd expect: submit, preview, add/remove attachment.  It 
uses the usual markdown syntax and can support others using plugins.

https://ikiwiki.info/ikiwiki/formatting/

The default style is pretty bare bones, but I imagine it could be made to match 
the Guix theme.

Great suggestion!

Re: Guix wiki

[Matt]

 > There is something here:
 > https://libreplanet.org/wiki/Group:Guix

Good point and it's already linked from the Guix homepage. Trouble is, it only 
seems editable by FSF associate members (which costs $120 or $60 for students). 
Am I missing something?

While that meets the technical requirement for a wiki, I don't think it meets 
the spirit: to be easily editable by anyone.  What message does that send to 
would-be contributors?

To me, it says something like, we don't actually care about your contribution: 
you have to literally buy in first. I feel like it also says that community 
isn't important to us. As an FSF member, I could modify the wiki.  However, I 
know that most people can't. That's the opposite of community.  To me, the 
libreplanet wiki is a non-starter.  I was thrilled to see a wiki link on the 
homepage and disgusted to see that it didn't actually foster community. In 
fact, there's strife immediately within the "community" wiki, the simple fact 
it exists, let alone what it says.  I think it would be better to have nothing 
linked from the homepage because 1) the current wiki is useless and 2) linking 
endorses what's there, including how it appears hostile to community.

I'm able to rationalize and understand that these messages are probably not 
what's intended. However, I think it important to share those reactions.

Re: Guix Documentation Meetup

[Matt]

 > Please don't misinterpret the following comments.  But I don't see how the 
 > 1st one
 > could land in a cookbook.  

You're fine, I more or less agree with you. I think something like it with a 
different package would be helpful.  What I wrote probably isn't it.

 > Yes, I'm not a fan of wiki.  Regardless, the
 > efforts of such a wiki should perhaps land outside the scope of Guix
 > (i.e. it should be non-"official").

I started a thread to talk about a Guix wiki. I'd like to hear  more of your 
thoughts about it.

 > I'm not connected with Guix with any way - a mere enthusiast and
 > observer.

I'm not sure what you mean.  Being excited about something and taking the time 
to observe it, like listening to music, is a connection, right?  

This conversation is a great example of how documentation affects community and 
engagement.  Your perspective is valuable!  

I'm curious, what makes you feel not connected with Guix?

 > I hope you continue to write great articles like these!

I appreciate the encouragement.  Thank you.

Re: Guix Documentation Meetup

[Matt]

> Also if I understand things correctly there are 
 > actually plans to host a documentation meetup this Saturday (maybe at 
 > around 10:30 AM ET as the last ones).
 
Thank you!  I should be able to attend.

Is that January 15, at 10:30 am EST using 
https://meet.nixnet.services/b/jga-rtw-ahw-yky?

Was that announced anywhere?

> I'm sure your participation and potential contributions to the 
> documentation meetup would be very welcome at this point in time :)

I hope so. I look forward to meeting everyone and hearing their thoughts.

Guix wiki

[Matt]

The subject of a wiki came up in the  Guix Documentation Meetup thread.

The last time it seems a wiki was mentioned was in 2015[fn:1]. Since it's
been more than 5 years and the Guix community has grown, I feel it's
worth bringing up again.

The 2015 post expressed problems with the manual, that it lacks
exhaustive examples and that information is hard to find.

The following concerns were raised (not listed in the order they
appeared):

1. guix will be soon be distributed over gnunet
2. it's hard to know which version of software a wiki is talking about
3. the manual is stored in the same git repository as Guix itself, so
   they can be kept in sync at all times
4. wikis "tends to be disorganized, unmaintained, and often misleading"
5. having a wiki may confuse what the primary source of documentation
   is (i.e. the manual)
6. the manual would require far less work from our small pool of
   experts to maintain than a wiki
7. the manual can easily be read and modified while offline
8. the manual should have all the examples necessary for people to
   understand how to tweak things

Alternatives to the manual were given:

- search the mailing list at 

- search the mailing list at GMane 


Is that a fair summary?

Since both sides weren't examined, I don't think it right to call the
thread a discussion.  There was no ill-will or bad intent. The
concerns are valid and some may still be relevant. There simply didn't
seem to be general interest in a wiki.  I suspect that interest may
have changed.  I'm hoping others will join me in having an earnest,
goal focused, and respectful conversation about whether Guix should
have an official wiki.

Why a wiki?

Here are some benefits a wiki would provide:

1. lower the barrier of entry for would-be contributors
2. facilitate collaboration
3. allow contributions on the go (from mobile devices)
4. host content not suitable for Texinfo or for inclusion in a
   reference manual
5. foster community

Foremost, I believe a wiki is a good idea because community is central
to the GNU philosophy. Guix is at the forefront of the GNU system. It
offers something no other system does and, as such, has a unique
opportunity to engage people on the ideals of free software.  I trust
I'm not alone in hoping that the model of Guix package management and
reproduciblity, if not Guix itself, becomes the norm for computing.
For this to happen, there must be community.

Wikis are synonymous with community.

Addressing the concerns:

Concern 1: guix will be soon be distributed over gnunet

  I'm not familiar with gnunet.  Has this come to fruition? Are the
  two mutually exclusive? Is it not possible to host the same text
  using both gnunet and www? If the www wiki would mirror the gnunet
  wiki, is there something that prevents gnunet mirroring www?

Concern 2: it's hard to know which version of software a wiki is talking about

  I suspect this is still a potential problem. I also suspect Guix
  itself may help solve it. For example, it's possible to write
  documentation in such a way that examples use a particular version of
  Guix using guix time-machine and guix shell.

  What are examples of this being a problem?

Concern 3: the manual is stored in the same git repository as Guix itself, so 
they can be kept in sync at all times

  Pushing to the same repo certainly helps make it possible to submit
  documentation alongside a code change in the same commit. If commits
  are reviewed, such changes could be enforced as policy. What's the
  current practice for this?

  Being in the same repo, however, doesn't necessarily ensure the two
  are in sync. Unless the documentation is generated from the code
  itself, I see this more as facilitating documentation discipline.

Concern 4: a wiki "tends to be disorganized, unmaintained, and often misleading"

  This depends on what is meant by "tends to".

  If read as "often is", there is truth to that. However, I see it being
  true of documentation in general.

  The quality of documentation of a community project depends entirely
  on the community.

  Is there something about the Guix community that might encourage a
  wiki to be disorganized, unmaintained, or misleading?  How have
  other communities handled these concerns?

Concern 5: having a wiki may confuse what the primary source of documentation 
is (i.e. the manual)

  I'm not sure I understand why this is a problem. Of course,
  confusion should be minimized.  But the primary source of
  documentation should be the one that best helps the user.  Ideally,
  that is the manual.  Is there a negative consequence for the primary
  source not being the manual?  For example, how many of you have used
  the Arch wiki to solve problems for something other than the Arch
  system?  Is that a problem?

Concern 6: the manual would require far less work from our small pool of 

Re: Guix Documentation Meetup

[Matt]

 > I see that this all seems confusing. 

Thank you for your response and for acknowledging my perspective.  Yes, I find 
many things about the documentation process confusing. I can't speak for 
others, but I get the strong sense that I'm not alone in that feeling.  

> If you have something to
> contribute, you should just mail it to this list or guix-patches.
> Definitely, we prefer you send patches, but if that is too hard, you can
> send your contribution in *any* form.

I did.  Maybe you missed the two blog posts I linked in the previous email?

> I have two documents written in Org:
> 1. http://excalamus.com/test-guix-case-study-plover-python-dictionary.html
> 2. http://excalamus.com/2021-10-06-guix-debug.html

The first is a tutorial of creating a non-trivial Guix package.  The second 
analyzes the process of troubleshooting an issue.

I share them here for two reasons. 

First, the packaging tutorial is, I believe, a reasonable candidate for the 
cookbook.  It's ready for feedback toward inclusion, not direct inclusion.  The 
software being packaged isn't ideal as it involves concepts which may detract 
from the main subject of packaging, like stenography. It's also for a plugin 
and not standalone software.  Demonstrating the final package requires 
demonstrating the parent application which again detracts from the main subject 
of packaging.  Finally, it's written using active voice which conveys authority 
on the topic, authority I don't actually have. This was my first attempt at 
packaging.

Second, the troubleshooting post is not, in my option, suited for the cookbook. 
It is, however, a good candidate for a wiki page (similar to Arch wiki sections 
on troubleshooting).  The last time a wiki was talked about, it seems, was in 
2015. I'll start a thread for that.

Re: Guix Documentation Meetup

[Matt]

 > > I would like for Guix to host a community wiki (in addition to a more 
 > > discoverable official documentation).
 > 
 > That’s the purpose of the Cookbook, which is open to all contributors.

The cookbook is a great resource. I'd like to contribute to it.

Let me walk through what that looks like from my perspective.  I'm afraid, 
however, that it comes across as aggressive, ungrateful, or demanding.  None of 
those are my intent! I genuinely want to help but struggle to understand the 
process.  My goal is to outline a "user story".

>From my perspective, contributing to the cookbook looks as follows.  I've 
>tried to be factual and ask rhetorical questions. 

How do I contribute to the cookbook? I see no information in the cookbook about 
how to do that. I'm looking at 
https://guix.gnu.org/cookbook/en/guix-cookbook.html

The contribute page (https://guix.gnu.org/en/contribute/) links to this mailing 
list. I am willing and ready to contribute. Now what?

I see the manual has a section on contributing: 
https://guix.gnu.org/manual/en/html_node/Contributing.html#Contributing

I see nothing about how to contribute to documentation. 

Do I need to submit a patch? 
How do I submit a patch? 
Do I have to write in TexInfo?
What is the roadmap from me spending hours authoring something to it being 
available for review from experts or to being useful to others?

I see https://guix.gnu.org/manual/en/html_node/Commit-Access.html says I would 
need three people to vouche for me, have to apply for maintainership, and some 
other stuff I didn't read. 
Would anyone actually vouche for me at this point?

I have two documents written in Org:
1. http://excalamus.com/test-guix-case-study-plover-python-dictionary.html
2. http://excalamus.com/2021-10-06-guix-debug.html

Do I have to convert them to TexInfo?
Who will review them?
Is the layout and style appropriate for info distribution?
Are there any licensing concerns to be aware of?

To close, I apologise for how aggressive all the questions can feel. Reading 
over it is overwhelming, even for me.  I'm afraid it may come across as simply 
yelling "Why? Why? Why?"  I would like to help provide answers. However, it 
feels like myself and others are practically begging for direction on how to do 
that. Someone has the authority and means to address these issues. Who is that 
person and what is their gameplan for addressing the issues raised in this 
thread? How do I (and others) figure into that plan? How I and others fit into 
this community?

Thank you for your time and patience! (And for everyone, including you, 
Ricardo, who have contributed to making Guix something myself and others want 
to use and extend). 

Re: Guix Documentation Meetup

[Matt]

 > Someone was frustrated there was no wiki, so they started that, but it's not 
 > official at all. Miraheze hosts other wikis, like the bootstrappable wiki, I 
 > think it's ok, but if we had a wiki, it should rather be hosted on gnu or 
 > guix infrastructure.
 
Thank you for clarifying. I now see the footer says "unofficial". 

Re: Guix Documentation Meetup

[Matt]

 > I would like for Guix to host a community wiki

Agreed. 

Ironically, Guix already has two of them.

1. goto gnu.guix.org
2. Select wiki from the help menu
3. Discover that linked wiki is not a community wiki
4. Click the (supposed) community wiki: https://guix.miraheze.org/wiki/Main_Page

Is this the "official" Guix wiki? 
If so, why is it not a direct link from the home page.
Who hosts it? If I spend hours writing something, is it just going to disappear 
some day?

Re: Guix Documentation Meetup

[Matt]

I want to be a part of this.  I feel like I've been rubbing two sticks together 
while it seems some people out there have Zippo lighters. A real-time 
conversation, some paired programming, or simply looking over the shoulder of 
someone who knows what they're doing would go a long way.  I have been trying 
to learn and share by way of case studies: www.excalamus.com.  My hope is that 
these could one day be adapted for the manual, or at least prep me for making 
meaningful contributions to the official documentation.  I have several more 
studies that are unpublished.

I share many of the same challenges others have experienced, certainly with 
Guile.

These are things I'm interested in helping with:

* defining terms

  A glossary, improved indexing (which is there), and more references (also 
present), are things I want to help with.

  For example, I've spent the past few days' free time trying to understand how 
to install an old version of ungoogled-chromium, required for Jitsi. To do this 
required 1) knowing what a profile is and 2) knowing the syntax of "sourcing".  
First, a profile is mentioned in passing several times in the manual as a 
directory. Yet, the guix package --profile option requires a *file* be 
specified.  (yes, a directory is a file, but guix complains if you pass a 
directory). So, is a profile a file or a directory? After much poking around, I 
found that the file specified by the --profile option is a symlink. This 
symlink points to another symlink (specifying the generation?), which in turn 
appears to point to the directory of packages . So, a profile *is* a directory, 
but, depending on how you look at it, it may be a file. Second, to activate the 
profile requires "sourcing" $GUIX_PROFILE/etc/profile (again, is a profile a 
file or a directory?). Some parts of the documentation give this as:

GUIX_PROFILE="$HOME/.guix-profile" . "$GUIX_PROFILE/etc/profile"

  Nevermind having to look up what was meant by "sourcing", I did that. But it 
turns out that there are two syntaxes for it: the one above and the more clear 
`source "$GUIX_PROFILE/etc/profile"`. Of course, with my luck, that wasn't made 
clear with the resources I found. It took me far too long to see how what I 
found on the open web corresponded to the manual.

* meaning/consequences/significance

  Knowing words without understanding the consequences of their meaning is just 
memorizing jargon. A profile is a directory? So what? Is that significant or 
just trivia? I still don't know.  Sometimes I think I'm reading about the Turbo 
Encabulator (https://www.youtube.com/watch?v=Ac7G7xOG2Ag)

* context/workflows

  I want to help show what it means for Guix to be imperative and declarative.  
Each has a different workflow, it seems, and the manual mixes those together. 
The context isn't always clear.

  Guix is flexible.  It can be complicated, but isn't by necessity.  I've been 
able to get by for nearly a year doing, more or less, guix pull, guix package 
-u, and occasionally guix system reconfigure (with a few guix installs thrown 
in :) Almost all the complex stuff has been from my choice to learn and do more.

  The simple daily workflows aren't apparent to me from the documentation. I 
don't need to code a config or define packages or set up channels or profiles 
or do any of that unless I want to? It took a bit of reading for me to realize, 
that's it?  I think there's a big focus on what can be done with Guix and not 
much said about the boring routine stuff. As a new user (even as a somewhat 
less new user), that's what I need first: I need security that my system will 
work, not crash or destroy my data and not consume my life *unless I choose for 
it to*. Isn't that really what Guix has to offer? Show me.

* navigation/discoverablity

  Guix is described as "the Emacs of distros".  To me Emacs, besides embodying 
freedom, means self-documenting. I wouldn't be a professional programmer 
without Emacs. It nurtures me by answering questions, giving examples, and 
scaffolding learning.  Emacs expands the zone of proximal development 
(https://en.wikipedia.org/wiki/Zone_of_proximal_development) and ensures I can 
achieve what I couldn't before.

  Guix is poised to do the same. However, the documentation and my difficulty 
navigating it is a huge problem for me.

  Others have touched on it when talking about Guile.

  - Is this symbol from Guile or Guix?
  - What does it do?
  - How is it used?
  - How many steps are required for someone to answer these questions?
(answer: not one like, C-h f. Instead, it might be days searching the 
mailing list, getting familiar with IRC, and being lucky with timing and and 
experimenting)
  - Geiser seems great. How the f*** does it help me answer these
questions? Wait, what problem am I trying to solve again?

  I love the info system.  Google has nothing on the info reader.  Yet even the 
info system's ability to overcome the documentation trilemma 

Re: Guix on Purism's Librems?

[Matt Newport]

Purism mostly disables the Intel ME, at least in theory:

https://puri.sm/posts/purism-librem-laptops-completely-disable-intel-management-engine/

https://puri.sm/learn/intel-me/

Sent with ProtonMail Secure Email.

‐‐‐ Original Message ‐‐‐
On Friday, April 19, 2019 4:59 AM, Tobias Platen  
wrote:

> Am 18.04.2019 um 04:44 schrieb Katherine Cox-Buday:
>
> > Hey all,
> > I brought this up in IRC tonight, and I thought I'd cast a net on the
> > mailing list to collect experiences. I am considering purchasing a
> > Librem laptop, and I was curious how Guix runs on it. Would anyone who
> > has these laptops (especially if you have a version with the TPM and
> > head) care to write up an experience-report?
> > Also, would it make sense for us to have a package specifically for
> > hardware like this to make it easier to build install images for the
> > machines? Even if the packages don't do much, there is still value in
> > declaring that the specific configuration of hardware has been
> > investigated, and is supported.
>
> Guix runs on two of my coreboot machines: the ThinkPad X200 and the
> Vikings D16.
> Since the Librem laptop has Intel ME, it won't respect privacy and
> freedom. [1]
> The Talos II [2] and the upcoming PowerPC notebook [3] do not have that
> problem.
> Currently I am working on a port to Guix to PPC64EL so that I can use
> Guix on my Talos II.
>
> Tobias
>
> [1]
> https://www.fsf.org/blogs/sysadmin/the-management-engine-an-attack-on-computer-users-freedom
> [2] https://www.raptorcs.com/
> [3] https://www.powerpc-notebook.org/en/