[tex-live] Suggested corrections/improvements to TeX Live 2016 notes (texlive-en.pdf)

Wed Nov 30 07:23:12 CET 2016

Hello all,
As part of trying to understand why some platex/dvipdfmx workflows no
longer worked after transition from TeX Live 2015 to 2106 (wrong DVI
bounding box), I read through all the documentation for TeX Live,
PDFTeX and the graphicx package.

Here are some suggestions to fix errors/unclear portions (unless I
have misunderstood the meaning) in the texlive-en.{html,pdf}
documentation.

Please see the accompanying text file for the raw bug list and
suggestions for improvement.

I also attach a dvips debug output for reference (one of the bugs
relates to this), no need to repeat experiment for the hard-working
volunteers who undertake the corrections.

Below I paste the contents of the corrections (not the dvips output
though) in-line into this email.

Best regards,
Gernot Hassenpflug

1. Page 8 3.1.1 Unix

  (1) "To install in expert GUI mode (figure 3),"
  should be: "To install in expert GUI mode (Figure 3),"

2. Page 9 3.1.7 The simple wizard installer

  (1) "“wizard” installer (figure 4)."
  should be: "“wizard” installer (Figure 4)."

3. Page 10 3.2.2 Selecting what is to be installed

  (1) "(figure 7, shown in GUI mode"
  should be: "(Figure 7, shown in GUI mode"

4. Page 11 3.2.3

  (1) "is shown in figure 3."
  should be: "is shown in Figure 3."

5. Page 13 3.2.4 options

  Option explanation for installer are not so clear to me, hopefully I
  can help to improve the descriptions by some suggestions and
  clarifying questions:

  (1) install font/macro ... tree
  Maybe better as follows to clarify that unchecking is not
  recommended:
  "Downloads/installs the documentation and source files included in
  most packages. Unchecking is not recommended."

 (2) create symlinks in standard directories
  The first two sentences explaining the meaning of the option are
  fine for me. But the following sentences could maybe be improved.

  Problem text:
  "It is strongly advised not to overwrite a TEX system that came with
  your system with this option. It is intended primarily for accessing
  the TEX system through directories that are already known to users,
  such as /usr/local/bin, which don’t already contain any TEX files."

  Does "It" mean checking the option? And how would a user know for
  sure in any case? Let alone what would happen if the user installed
  system tex after installing TeX Live? I am not sure how to improve
  since I do not understand the explanation of the consequences as
  written, but perhaps something about what to do when not sure: e.g.,
  leave unchecked if not sure, and add paths later manually?

  Rough suggestion (and the last sentence could no doubt be improved,
  but I don't know how, as I do not understand it as it stands at
  present):

  "It is strongly advised to leave this option unchecked, so as not to
  overwrite a TEX system that came with your system. The option is
  intended primarily for accessing the TEX system through directories
  that are already known to users, such as /usr/local/bin, which
  don’t already contain any TEX files."

6. Page 14 3.4.1 Environment variables for Unix

  (1) "See figure 5 for the list"
  should be: "See Figure 5 for the list"

7. Page 16 3.4.5 ConTeXt Mark IV

  (1) "The resulting files are stored under TEXMFCACHE. whose default
  value in TEX Live is TEXMSYSVAR;TEXMFVAR."

  should be: "The resulting files are stored under TEXMFCACHE, whose default
  value in TEX Live is TEXMFSYSVAR;TEXMFVAR."
  Notes:
  (a) . -> ,
  (b) TEXMSYSVAR -> TEXMFSYSVAR

8. Page 19 4.1 Shared-user (or cross-machine) installations

  (1) "for e.g. SumatraPDF or some"
  should be: "for e.g., SumatraPDF or some"
  (and "e.g." not in italics I suspect.)

9. Page 25 7 A user’s guide to Web2C

  (1) "This library uses a combination of environment variables and a
  configuration files to ..."
  should be:
  "This library uses a combination of environment variables and
  configuration files to ..."

10. Page 25 7.1 Kpathsea path searching

  (1) "(if this was not forbidden by a specification starting with
‘!!’ and if the file being searched for must exist)."

  In the above, "must exist" seems to be the name of an option
  "file must exist" explanation is hard to follow.
  This seems to mean that a search with NOT be performed,
  for the reason that the file "may not exist". What that implies I am
  not sure: it is the responsibility of the program to create it
  regardless? I am sorry, is not clear to me with my limited
  understanding what to think here.

  Later, on page 29 (7.2.2 kpsewhich: Standalone path searching), an
  opposite definition seems to be given for the option "must-exist"
  used with kpsewhich:

  "--must-exist
  Do everything possible to find the files, notably including
  searching the disk. By default, only the ls-R database is checked,
  in the interest of efficiency."

  This seems to indicate the meaning of "force search". Are the two
  above phrase "must exist" (seems to be internally-defined behaviour)
  and option "--must-exist" (seems to be user-controlled behaviour)
  referring to the same behaviour? If so, then probably something in
  the above descriptions could be changed. On the other hand, if he
  behaviour indicated is not the same, that could be made clear with
  different wording?

11. Page 31 7.2.4 Debugging actions

  I checked that I get similar output on my Tex Live 2016 system. The
  figures have some typesetting problems: kdebug became debug on the
  first line, some lines are missing maybe, and some extra backslashes
  before underbars.

  Figures 14 and 15 are not referenced in the text, but duplicated
  in the text directly.

  I am not sure what was the original intention, but perhaps Figures
  14 and 15 should be deleted (since currently they are not
  referenced). Alternatively, they could be cleaned up and referenced,
  and the in-text (correctly typeset it appears to me) contents
  deleted.

  Figure 13 could be left or replaced with an in-text version to match
  what is best for Figuers 14 and 15.

12. Page 38 9.1.4 2006-2007

  (1) "As a result, there was been a surge of interest in TEX Live"
  should be: "As a result, there has been a surge of interest in TEX
  Live"

13. Page 39 9.1.7 2010

  (1) "These are commands are"
  should be: "These commands are"

  (2) "so broken packages updates can be"
  should be: "so broken package updates can be"

14. Page 40 9.1.9 2012

  (1) "can now exceed 2gb."
  Does that mean 2 Gigabits = 10^9 bits? And if so, is that really the
  convention, as opposed to Gbit or Gb? And if it should instead mean binary
  Gibagits, or 2^30 (i.e., 1024^3), then it would proababy best be
  written Gibit?
  On page 11, in section 3.2.3, gigabytes is written out, perhaps
  writing it out here (with whatever term fits) too would be clearer?

15. Page 40 9.1.10 2013

  (1) "The HarfBuzz library now used for font layout"
  should be: "The HarfBuzz library is now used for font layout"
-------------- next part --------------
Hello all,
As part of trying to understand why some platex/dvipdfmx workflows no
longer worked after transition from TeX Live 2015 to 2106 (wrong DVI
bounding box), I read through all the documentation for TeX Live,
PDFTeX and the graphicx package.
Here are some suggestions to fix errors in documentation, or clarify
(unless I have misunderstood the meaning) in the texlive-en.{html,pdf}
documentation.

Correction to send to:
tex-live at tug.org
http://tug.org/texlive

1. Page 8 3.1.1 Unix

  (1) "To install in expert GUI mode (figure 3),"
  should be: "To install in expert GUI mode (Figure 3),"

2. Page 9 3.1.7 The simple wizard installer

  (1) "“wizard” installer (figure 4)."
  should be: "“wizard” installer (Figure 4)."