Re: [PATCH] doc: Clarify need to update search paths on foreign distro (was Re: Feedback of the GNU Guix manual)
Hello Matt, Vagrant and all. As I understand, we should not advice all users to add these exports to .bashrc, because users with guix-install.sh’s sys_create_init_profile or Debian’s /etc/profile.d/guix.sh do not need it. Instead, there already is advice for .config/guix/current documented in the Guix manual’s Getting Started section. The advice should be a cross-reference that users should follow the steps from Getting Started, so search paths are set up properly instead of advising to set PATH and INFOPATH. The advice of setting PATH really should go away. Regards, Florian
Re: [PATCH] doc: Clarify need to update search paths on foreign distro (was Re: Feedback of the GNU Guix manual)
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?
Re: [PATCH] doc: Clarify need to update search paths on foreign distro (was Re: Feedback of the GNU Guix manual)
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. live well, vagrant signature.asc Description: PGP signature
[PATCH] doc: Clarify need to update search paths on foreign distro (was Re: Feedback of the GNU Guix manual)
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
Re: [PATCH] Fix typo (Re: Feedback of the GNU Guix manual)
Pushed as b8ccbc942e0ec7baf695d383e575991289c6e033. Thank you for trudging on through the list. Regards, Florian
[PATCH] Fix typo (Re: Feedback of the GNU Guix manual)
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)
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: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
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.) Regards, Florian
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
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: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
Hi Matt, Matt writes: > 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. :) Awesome! Definitely a superpower in my book. Thanks for following it through with the Emacs folks! I'm sure I was bothered by that inconsistency before but couldn't put my finger on the culprit. -- Thanks, Maxim
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
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. or is there more that should go in this patch? Matt writes: > On Mon, 15 Apr 2024 14:58:50 +0200 pelzflorian (Florian Pelz) wrote > --- > > 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. […] Ohh thank you and them for the fix. Regards, Florian
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
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 writes: > The problem is that the Emacs Info reader incorrectly renders > cross-references by default. I was reading the Texinfo documentation > in Emacs. 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. Again thank you for tediously working through deficiencies in Guix’ docs. 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. Regards, Florian
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
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 writes: > The attached change updates "Libera Chat" to the "Libera.Chat" stylization. Pushed as df7b569b464c05036871f23d37ba319be78e5f64. Thanks! Regards, Florian
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
Hello, I just want to mention that I am still in CC and my mail server is going offline. Need to optimize my budget and don't have any time for GNU anymore because of university. -- Christian Miller Am 10/04/2024 um 16:05 schrieb 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?
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
Matt writes: > #+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". Currently Libera Chat is written using a non-breaking space. We could also use @tie{} instead of the special char . I do agree with your Libera.Chat stylization, will push it later. It will not matter to search engines, I think. Regards, Florian
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
Hello Matt. Thank you for fixing the oversight. However: Matt writes: > From: Matthew Trzcinski > Date: Sat, 13 Apr 2024 10:12:05 +0200 > Subject: [PATCH] doc: Fix cross-references > > * doc/guix.texi (Setting Up the Daemon): use @xref to start sentence. > (Build Systems): capitalize "python" and start parenthesized reference with > @pxref. > (Linux Services): use @xref to start phrase. @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. > (Configuring the Shell): use @xref to start phrase. This should be @pxref. 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. Regards, Florian
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
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)
Hi, Matt skribis: > 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 Thanks for reporting these issues! Ludo’.
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
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
Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
Pushed as cd557e2d1c83839dd587016279900d31f053efc8. Matt writes: > 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). […] I believe the rendering of @ref was an issue with Emacs that is gone in latest Emacs. > 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? I believe guix-devel is OK for such changes. Regards, Florian
Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
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: Removing much of Binary Installation (was: Feedback of the GNU Guix manual)
On 2024-03-06, pelzflorian (Florian Pelz) wrote: > 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] > > The reason of existence for these distribution packages is probably > similar to the reason why the Binary Installation section exists. Indeed, after the first guix pull, most of the packaged files are no longer used. As the one who packaged and maintains guix in Debian, my main motivation was and is to have a trust path from debian; mainly not having to manually verify the signatures of the manual installation method (I would hazard to guess that the percentage of people who actually do manually verify signatures is disturbingly small). 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 cannot say I have done a *great* job at maintaining guix in Debian, but hopefully at least a passable job. Although there are some annoying things that probably need to be fixed: https://bugs.debian.org/1064748 a.k.a. https://issues.guix.gnu.org/69518 ... or backported to Debian stable: https://bugs.debian.org/1036304 https://bugs.debian.org/1038916 I have found a fair number of issues (especially typos!) to fix in upstream guix as a result of packaging it for Debian, so if nothing else, it is some quality assurance! :) live well, vagrant signature.asc Description: PGP signature
Re: doc: Removing much of Binary Installation (was: Feedback of the GNU Guix manual)
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
doc: Removing much of Binary Installation (was: Feedback of the GNU Guix manual)
Thank you Matt for the suggested diff. Yes, I agree some simplification as you suggested would be beneficial, so that the description of Binary Installation looks as simple as it really is. (In particular, I have witnessed people, to whom I had suggested Guix, fail at trying Guix because they tried Guix System on a not libre-friendly laptop, when they could/should have tried Binary Installation.) > - 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] 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. Regards, Florian [0] https://wiki.archlinux.org/title/Guix
Re: Feedback of the GNU Guix manual
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: Feedback of the GNU Guix manual
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
Hi Matt, Matt writes: > 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. 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). Thank you for your efforts! -- Maxim
Re: Feedback of the GNU Guix manual
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
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
Hi Matt, Thanks for the follow-up. Matt writes: [...] > #+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. 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). As for the Linux or Hurd-based system, that seems like a good idea to make things explicit. I've pushed your adjusted suggestions with commit ec9c8b0c1a. Thank you! -- Maxim
Re: Feedback of the GNU Guix manual
Hi Matt, Matt writes: > 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. 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. Best, -- Josselin Poiret signature.asc Description: PGP signature
Re: Feedback of the GNU Guix manual
Friendly bump. Awaiting feedback or guidance.
Re: Feedback of the GNU Guix manual
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
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: Feedback of the GNU Guix manual
Hi Matt! Matt writes: > I care about this. How can I help? > > - Convert the notes into patches? > - Proofread any patches that derive from Christian's efforts? 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). -- Thanks, Maxim
Re: Feedback of the GNU Guix manual
> I care about this. How can I help? I don't know. I would also create patches but don't know if it should be a huge patch or multiple ones, or maybe even it's own branch. > What's TTY mode? M-x tty reveals nothing for me. Mode is probably the wrong word. It basically is just running "emacsclient --tty". I sometimes use Emacs in a Linux console, since I like how it looks (also helps in learning the keybindings and actually using them, since it forces me to not use the mouse). I mentioned it, since it changes how the documentation is rendered. For example, there will be no pictures since there is no graphics in a Linux console. > I appreciate you taking the time to write them all up. Thanks. -- Christian Miller
Re: Feedback of the GNU Guix manual
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
Feedback of the GNU Guix manual
Hello, I read through the GNU Guix manual on revision ee7c9d254117fa470686210ad2ef5e7f1ba4fefc with Emacs in TTY mode. 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). Overall it was a better experience than reading the Emacs manual. The Emacs manual may have a better consistent style but it was hard to understand. Felt like it assumed people would know stuff which I did not do. 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. I will mention lot's of style issues since at that time I did not know it is in such a bad state. Here are some things I noticed: ** Binary installation L73 Guix system should be Guix System ** Binary Installation L88 and L95 ~root is weird. Should be root or simply ~ for the user profile which would be root as root user. ** 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. ** 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 ** 3.8 Installing Guix in a Virtual Machine L25 in an vm should be in a vm ** 6.4 L60 packages should be package The outputs of a packages are listed in the third column of the output of ‘guix package --list-available’ (*note Invoking guix package::). ** 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" ** 6.8 Maybe just mention the actual movie for people that never have seen or heard of it (1) If you don’t know what a DeLorean is, consider traveling back to the 1980’s. (Back to the Future (1985)) ** 7.1 should be variant-packages (not sure anymore, those notices I made are several weeks old) The output of ‘guix describe’ above shows that we’re now running Generation 19 and that it includes both Guix and packages from the ‘variant-personal-packages’ channel (*note Invoking guix describe::). ** 8.1 See https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?h=v6.7=6eb3c3d0a52dca337e327ae8868ca1f44a712e02 You may pass any ‘guix shell’ option, but there’s one caveat: the Linux kernel has a limit of 127 bytes on shebang length. ** 8.1 this is done automatically on Guix System. Should be mentioned? ‘guix shell’ defines the ‘GUIX_ENVIRONMENT’ variable in the shell it spawns; its value is the file name of the profile of this environment. This allows users to, say, define a specific prompt for development environments in their ‘.bashrc’ (*note (bash)Bash Startup Files::): if [ -n "$GUIX_ENVIRONMENT" ] then export PS1="\u@\h \w [dev]\$ " fi ... or to browse the profile: $ ls "$GUIX_ENVIRONMENT/bin" ** 8.2 Time to remove? Being deprecated, ‘guix environment’ is slated for eventual removal, but the Guix project is committed to keeping it until May 1st, 2023. Please get in touch with us at if you would like to discuss it. ** 8.3 L47 they they What if the recipient of your pack does not have root privileges on their machine, and thus cannot unpack it in the root file system? In that case, you will want to use the ‘--relocatable’ option (see below). This option produces “relocatable binaries”, meaning they they can be placed anywhere in the file system hierarchy: in the example above, users can unpack your tarball in their home directory and directly run ** 9 missing application word for apis. GNU Guix provides several Scheme programming interfaces (APIs) to define, build, and query packages. The first interface allows users to write high-level package definitions. These definitions refer to familiar packaging concepts, such as the name and version of a package, its build system, and its dependencies. These definitions can then be turned into concrete build actions. ** 9.5 build system texlive-build-system located in located in It also generates font metrics (i.e., ‘.tfm’ files) out of Metafont files whenever possible. Likewise, it can also create TeX formats (i.e., ‘.fmt’ files) listed in the ‘#:create-formats’