[bug#54220] [PATCH] doc: Add "Using TeX and LaTeX" chapter.

[bug#54220] [PATCH] doc: Add "Using TeX and LaTeX" chapter.

[Ludovic Courtès]

* doc/guix.texi (Using TeX and LaTeX): New node.
---
 doc/guix.texi | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 141 insertions(+)

Hello!

This patch documents the current state of TeX/LaTeX packaging and tips
and tricks to get things done with the modular package set.

I’m writing this as an eternal TeX/LaTeX newbie (and as a Lout refugee!)
not completely familiar with the intricacies of TeX Live packaging, so
this section might need corrections and improvements.

It’s a top-level chapter, because I couldn’t find any better place, but
I think it’s fine.

Thoughts?

Ludo’.

diff --git a/doc/guix.texi b/doc/guix.texi
index 1e8b23ad7e..1c11cc8d5a 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -175,6 +175,7 @@ Weblate} (@pxref{Translating Guix}).
 * Home Configuration::          Configuring the home environment.
 * Documentation::               Browsing software user manuals.
 * Installing Debugging Files::  Feeding the debugger.
+* Using TeX and LaTeX::         Typesetting.
 * Security Updates::            Deploying security fixes quickly.
 * Bootstrapping::               GNU/Linux built from scratch.
 * Porting::                     Targeting another platform or kernel.
@@ -38622,6 +38623,146 @@ Note that there can be packages for which @option{--with-debug-info}
 will not have the desired effect.  @xref{Package Transformation Options,
 @option{--with-debug-info}}, for more information.
 
+@node Using TeX and LaTeX
+@chapter Using @TeX{} and @LaTeX{}
+
+@cindex @TeX{} packages
+@cindex @LaTeX{} packages
+Guix provides packages for the @TeX{} and @LaTeX{} typesetting systems,
+taken from the @uref{https://www.tug.org/texlive/, @TeX{} Live
+distribution}.  However, because @TeX{} Live is so huge and because
+finding your way in this maze is tricky, we thought that you, dear user,
+would welcome guidance on how to deploy the relevant packages so you can
+compile your @TeX{} and @LaTeX{} documents.
+
+@TeX{} Live currently comes in two flavors in Guix:
+
+@itemize
+@item
+The ``monolithic'' @code{texlive} package: it comes with @emph{every
+single @TeX{} Live package} (more than 7,000 of them), but it is huge
+(more than 4@tie{}GiB for a single package!).
+
+@item
+The ``modular'' @code{texlive-} packages: you install
+@code{texlive-base}, which provides core functionality and the main
+commands---@command{pdflatex}, @command{dvips}, @command{luatex},
+@command{mf}, etc.---together with individual packages that provide just
+the features you need---@code{texlive-latex-listings} for the
+@code{listings} package, @code{texlive-hyperref} for @code{hyperref},
+@code{texlive-beamer} for Beamer, @code{texlive-latex-pgf} for PGF/TikZ,
+and so on.
+@end itemize
+
+We recommend using the modular package set because it is much less
+resource-hungry.  To build your documents, you would use commands such
+as:
+
+@example
+guix shell texlive-base texlive-latex-wrapfig \
+  texlive-hyperref texlive-cm-super -- pdflatex doc.tex
+@end example
+
+You can quickly end up with unreasonably long command lines though.  The
+solution is to instead write a manifest, for example like this one:
+
+@lisp
+(specifications->manifest
+ '("rubber"
+
+   "texlive-base"
+   "texlive-latex-wrapfig"
+
+   "texlive-microtype"
+   "texlive-latex-listings" "texlive-hyperref"
+
+   ;; PGF/TikZ
+   "texlive-latex-pgf"
+
+   ;; Additional fonts.
+   "texlive-cm-super" "texlive-amsfonts"
+   "texlive-times" "texlive-helvetic" "texlive-courier"))
+@end lisp
+
+You can then pass it to any command with the @option{-m} option:
+
+@example
+guix shell -m manifest.scm -- pdflatex doc.tex
+@end example
+
+@xref{Invoking guix package, @option{--manifest}}, for more on
+manifests.  In the future, we plan to provide packages for @TeX{} Live
+@dfn{collections}---``meta-packages'' such as @code{fontsrecommended},
+@code{humanities}, or @code{langarabic} that provide the set of packages
+needed in this particular domain.  That will allow you to list fewer
+packages.
+
+The main difficulty here is that using the modular package set forces
+you to select precisely the packages that you need.  You can use
+@command{guix search}, but finding the right package can prove to be
+tedious.  When a package is missing, @command{pdflatex} and similar
+commands fail with an obscure message along the lines of:
+
+@example
+doc.tex: File `tikz.sty' not found.
+doc.tex:7: Emergency stop.
+@end example
+
+@noindent
+or, for a missing font:
+
+@example
+kpathsea: Running mktexmf phvr7t
+! I can't find file `phvr7t'.
+@end example
+
+How do you determine what the missing package is?  In the first case,
+you'll find the answer by running:
+
+@example
+$ guix search texlive tikz
+name: texlive-latex-pgf
+version: 59745
+@dots{}
+@end example
+
+In the second case, @command{guix search} turns up nothing.  Instead,
+you can search the @TeX{} Live package database using the @command{tlmgr}
+command:
+
+@example
+$ guix shell texlive-base -- tlmgr info phvr7t
+tlmgr: cannot find package phvr7t, searching for other matches:
+
+Packages containing `phvr7t' in their title/description:
+
+Packages containing files matching `phvr7t':
+helvetic:
+        texmf-dist/fonts/tfm/adobe/helvetic/phvr7t.tfm
+        texmf-dist/fonts/tfm/adobe/helvetic/phvr7tn.tfm
+        texmf-dist/fonts/vf/adobe/helvetic/phvr7t.vf
+        texmf-dist/fonts/vf/adobe/helvetic/phvr7tn.vf
+tex4ht:
+        texmf-dist/tex4ht/ht-fonts/alias/adobe/helvetic/phvr7t.htf
+@end example
+
+The file is available in the @TeX{} Live @code{helvetic} package, which is
+known in Guix as @code{texlive-helvetic}.  Quite a ride, but we found
+it!
+
+There is one important limitation though: Guix currently provides a
+subset of the @TeX{} Live packages.  If you stumble upon a missing
+package, you can try and import it (@pxref{Invoking guix import}):
+
+@example
+guix import texlive @var{package}
+@end example
+
+@quotation Note
+@TeX{} Live packaging is still very much work in progress, but you can
+help!  @xref{Contributing}, for more information.
+@end quotation
+
 @node Security Updates
 @chapter Security Updates
 

base-commit: a53ea46bfc219a2c184fbf3ce8f3e3ba3f539a7d
-- 
2.34.0

[bug#54220] [PATCH] doc: Add "Using TeX and LaTeX" chapter.

[Ricardo Wurmus]

Ludovic Courtès <ludo@gnu.org> writes:

> * doc/guix.texi (Using TeX and LaTeX): New node.

Perfect!

> It’s a top-level chapter, because I couldn’t find any better place, but
> I think it’s fine.

Hmm, maybe in (possibly renamed) “Application Setup”?

> +@cindex @TeX{} packages
> +@cindex @LaTeX{} packages
> +Guix provides packages for the @TeX{} and @LaTeX{} typesetting systems,
> +taken from the @uref{https://www.tug.org/texlive/, @TeX{} Live
> +distribution}.  However, because @TeX{} Live is so huge and because
> +finding your way in this maze is tricky, we thought that you, dear user,
> +would welcome guidance on how to deploy the relevant packages so you can
> +compile your @TeX{} and @LaTeX{} documents.

Why single out TeX in particular?  TeX Live also includes ConTeXt,
Xe(La)TeX, Lua(La)TeX etc.  I guess LaTeX is the most widely known and
TeX is the common basis of them all, so maybe that’s good enough a
reason.

> +the features you need---@code{texlive-latex-listings} for the
> +@code{listings} package, @code{texlive-hyperref} for @code{hyperref},
> +@code{texlive-beamer} for Beamer, @code{texlive-latex-pgf} for PGF/TikZ,

I’d very much like to avoid giving the old names visibility.
“texlive-latex-listings” is old as is “texlive-latex-pgf”.  It really
should be “texlive-listings” and “texlive-pgf”.  Previously I had not
been aware of the tlpdb, so these packages were literally just an
arbitrary slice of the TeX Live SVN repository and thus had to be named
according to the directory name to disambiguate the package providing
“tex/generic/foo” from the one providing “tex/latex/foo”.

With the svn-multi fetch method we were finally able to fully specify
the source for any given TeX Live package by selecting more than one SVN
location.  Together with the tlpdb, which specifies all locations for a
given packgae name, this allowed us to finally include *all* expected
files in “texlive-” packages, and thus removing the need for
disambiguation through package name infixes.

In short: I’d prefer to deprecate all old names and only mention the new
names in the documentation to avoid confusion.

> +@xref{Invoking guix package, @option{--manifest}}, for more on
> +manifests.  In the future, we plan to provide packages for @TeX{} Live
> +@dfn{collections}---``meta-packages'' such as @code{fontsrecommended},
> +@code{humanities}, or @code{langarabic} that provide the set of packages
> +needed in this particular domain.  That will allow you to list fewer
> +packages.

Working on it!

> +@example
> +$ guix shell texlive-base -- tlmgr info phvr7t
> +tlmgr: cannot find package phvr7t, searching for other matches:
> +
> +Packages containing `phvr7t' in their title/description:
> +
> +Packages containing files matching `phvr7t':
> +helvetic:
> +        texmf-dist/fonts/tfm/adobe/helvetic/phvr7t.tfm
> +        texmf-dist/fonts/tfm/adobe/helvetic/phvr7tn.tfm
> +        texmf-dist/fonts/vf/adobe/helvetic/phvr7t.vf
> +        texmf-dist/fonts/vf/adobe/helvetic/phvr7tn.vf
> +tex4ht:
> +        texmf-dist/tex4ht/ht-fonts/alias/adobe/helvetic/phvr7t.htf
> +@end example
> +
> +The file is available in the @TeX{} Live @code{helvetic} package, which is
> +known in Guix as @code{texlive-helvetic}.  Quite a ride, but we found
> +it!

Perfect!

Thank you!

-- 
Ricardo

[bug#54220] [PATCH] doc: Add "Using TeX and LaTeX" chapter.

[Ludovic Courtès]

Hi!

Ricardo Wurmus <rekado@elephly.net> skribis:

> Ludovic Courtès <ludo@gnu.org> writes:

[...]

>> It’s a top-level chapter, because I couldn’t find any better place, but
>> I think it’s fine.
>
> Hmm, maybe in (possibly renamed) “Application Setup”?

“Application Setup” is about configuration on a foreign distro, so I
don’t think it’s the right place.

Perhaps we need a more general chapter on using things under Guix, where
we could also have (say) a “Working with Python” section, and perhaps we
could move “Installing Debugging Files” there?  I thought I’d leave that
for later.

>> +@cindex @TeX{} packages
>> +@cindex @LaTeX{} packages
>> +Guix provides packages for the @TeX{} and @LaTeX{} typesetting systems,
>> +taken from the @uref{https://www.tug.org/texlive/, @TeX{} Live
>> +distribution}.  However, because @TeX{} Live is so huge and because
>> +finding your way in this maze is tricky, we thought that you, dear user,
>> +would welcome guidance on how to deploy the relevant packages so you can
>> +compile your @TeX{} and @LaTeX{} documents.
>
> Why single out TeX in particular?

You mean LaTeX, right?

> TeX Live also includes ConTeXt, Xe(La)TeX, Lua(La)TeX etc.  I guess
> LaTeX is the most widely known and TeX is the common basis of them
> all, so maybe that’s good enough a reason.

Yeah, I think to most people it’s all the same :-) and LaTeX is by far
the most famous one.

Maybe we could phrase it differently, like “Using TeX, LaTeX, and
Related Tools”?

>> +the features you need---@code{texlive-latex-listings} for the
>> +@code{listings} package, @code{texlive-hyperref} for @code{hyperref},
>> +@code{texlive-beamer} for Beamer, @code{texlive-latex-pgf} for PGF/TikZ,
>
> I’d very much like to avoid giving the old names visibility.
> “texlive-latex-listings” is old as is “texlive-latex-pgf”.  It really
> should be “texlive-listings” and “texlive-pgf”.

[...]

Yeah, I can rename at least these two packages in a first patch (I will
have to check the number of rebuilds) and adjust the text to refer to
the new names.

>> +@xref{Invoking guix package, @option{--manifest}}, for more on
>> +manifests.  In the future, we plan to provide packages for @TeX{} Live
>> +@dfn{collections}---``meta-packages'' such as @code{fontsrecommended},
>> +@code{humanities}, or @code{langarabic} that provide the set of packages
>> +needed in this particular domain.  That will allow you to list fewer
>> +packages.
>
> Working on it!

Yay!

> Perfect!

Thanks, I’m glad it makes sense!

Ludo’.

[bug#54220] [PATCH] doc: Add "Using TeX and LaTeX" chapter.

[Ricardo Wurmus]

Ludovic Courtès <ludo@gnu.org> writes:

>>> It’s a top-level chapter, because I couldn’t find any better place, but
>>> I think it’s fine.
>>
>> Hmm, maybe in (possibly renamed) “Application Setup”?
>
> “Application Setup” is about configuration on a foreign distro, so I
> don’t think it’s the right place.
>
> Perhaps we need a more general chapter on using things under Guix, where
> we could also have (say) a “Working with Python” section, and perhaps we
> could move “Installing Debugging Files” there?  I thought I’d leave that
> for later.

Sounds good.

>>> +@cindex @TeX{} packages
>>> +@cindex @LaTeX{} packages
>>> +Guix provides packages for the @TeX{} and @LaTeX{} typesetting systems,
>>> +taken from the @uref{https://www.tug.org/texlive/, @TeX{} Live
>>> +distribution}.  However, because @TeX{} Live is so huge and because
>>> +finding your way in this maze is tricky, we thought that you, dear user,
>>> +would welcome guidance on how to deploy the relevant packages so you can
>>> +compile your @TeX{} and @LaTeX{} documents.
>>
>> Why single out TeX in particular?
>
> You mean LaTeX, right?

Heh, see: that shows how subjective it is :) No, I did mean TeX, because
in my experience it is extremely uncommon to use TeX directly.

>> TeX Live also includes ConTeXt, Xe(La)TeX, Lua(La)TeX etc.  I guess
>> LaTeX is the most widely known and TeX is the common basis of them
>> all, so maybe that’s good enough a reason.
>
> Yeah, I think to most people it’s all the same :-) and LaTeX is by far
> the most famous one.
>
> Maybe we could phrase it differently, like “Using TeX, LaTeX, and
> Related Tools”?

Nah, it’s fine.  By the time I wrote the last sentence you quoted above
I had convinced myself that it’s fine to mention TeX (because it’s the
foundation) and LaTeX (because it’s the most popular).

>>> +the features you need---@code{texlive-latex-listings} for the
>>> +@code{listings} package, @code{texlive-hyperref} for @code{hyperref},
>>> +@code{texlive-beamer} for Beamer, @code{texlive-latex-pgf} for PGF/TikZ,
>>
>> I’d very much like to avoid giving the old names visibility.
>> “texlive-latex-listings” is old as is “texlive-latex-pgf”.  It really
>> should be “texlive-listings” and “texlive-pgf”.
>
> [...]
>
> Yeah, I can rename at least these two packages in a first patch (I will
> have to check the number of rebuilds) and adjust the text to refer to
> the new names.

Thanks.

-- 
Ricardo

[bug#54220] [PATCH] doc: Add "Using TeX and LaTeX" chapter.

[zimoun]

On Wed, 2 Mar 2022 at 14:31, Ricardo Wurmus <rekado@elephly.net> wrote:

> >> Why single out TeX in particular?
> >
> > You mean LaTeX, right?
>
> Heh, see: that shows how subjective it is :) No, I did mean TeX, because
> in my experience it is extremely uncommon to use TeX directly.

I propose to use "TeX system or its variants" and provides elsewhere
in the text the list of these variants (ConTeX, LuaTeX, etc.) and in
future patch provides more explanations on how to use these variants.


Cheers,
simon

bug#54220: [PATCH] doc: Add "Using TeX and LaTeX" chapter.

[Ludovic Courtès]

Ricardo Wurmus <rekado@elephly.net> skribis:

> Ludovic Courtès <ludo@gnu.org> writes:

[...]

>>> Why single out TeX in particular?
>>
>> You mean LaTeX, right?
>
> Heh, see: that shows how subjective it is :) No, I did mean TeX, because
> in my experience it is extremely uncommon to use TeX directly.

Ah!  I mentioned TeX because technically it’s the basis of everything.

> Nah, it’s fine.  By the time I wrote the last sentence you quoted above
> I had convinced myself that it’s fine to mention TeX (because it’s the
> foundation) and LaTeX (because it’s the most popular).

Alright.

I went ahead and pushed an updated version as
f0efa6afc5f180f778eb320631a71f42bf1b211f.  I kept the section title, but
explicitly mentioned ConTeXt and LuaTeX in the first paragraph.

This is a starting point anyway, so everyone please feel free to update
it as you see fit or when things change.

Thanks for the quick feedback!

Ludo’.

[bug#54220] [PATCH] doc: Add "Using TeX and LaTeX" chapter.

[zimoun]

Hi,

Cool!  It is better than pinging Ricardo on IRC. ;-)

On Wed, 2 Mar 2022 at 11:27, Ricardo Wurmus <rekado@elephly.net> wrote:


> > It’s a top-level chapter, because I couldn’t find any better place, but
> > I think it’s fine.
>
> Hmm, maybe in (possibly renamed) “Application Setup”?

This section starts with:

        When using Guix on top of GNU/Linux distribution other than Guix
        System—a so-called foreign distro—a few additional steps are
        needed to get everything in place. Here are some of them.

and the TeX/LaTeX is not foreign distro specific.  Therefore, some
tweaks are necessary to clearly state what is foreign-distro specific
and what is generic with Guix.


> > +@cindex @TeX{} packages
> > +@cindex @LaTeX{} packages
> > +Guix provides packages for the @TeX{} and @LaTeX{} typesetting systems,
> > +taken from the @uref{https://www.tug.org/texlive/, @TeX{} Live
> > +distribution}.  However, because @TeX{} Live is so huge and because
> > +finding your way in this maze is tricky, we thought that you, dear user,
> > +would welcome guidance on how to deploy the relevant packages so you can
> > +compile your @TeX{} and @LaTeX{} documents.
>
> Why single out TeX in particular?  TeX Live also includes ConTeXt,
> Xe(La)TeX, Lua(La)TeX etc.  I guess LaTeX is the most widely known and
> TeX is the common basis of them all, so maybe that’s good enough a
> reason.

I propose "and LaTeX" -> "and variants".  Or something along that.
And probably adds a list with all the variant since it is not
straightforward to know how to get these TeX system variants.



Cheers,
simon