[latexrefman-commits] [SCM] latexrefman updated: r928 - trunk
Karl Berry
INVALID.NOREPLY at gnu.org.ua
Mon Jun 21 19:30:21 CEST 2021
Author: karl
Date: 2021-06-21 17:30:21 +0000 (Mon, 21 Jun 2021)
New Revision: 928
Modified:
trunk/ChangeLog
trunk/aspell.en.pws
trunk/latex2e.texi
trunk/writing.html
Log:
jobname updates
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2021-06-18 16:58:07 UTC (rev 927)
+++ trunk/ChangeLog 2021-06-21 17:30:21 UTC (rev 928)
@@ -1,3 +1,11 @@
+2021-06-21 Karl Berry <karl at freefriends.org>
+
+ * latex2e.texi (Jobname): updates; consistently use "jobname"
+ instead of "job name".
+ Change @cindex entries to start with lowercase.
+
+ * writing.html: mention index entries.
+
2021-06-18 Karl Berry <karl at freefriends.org>
* latex2e.texi: (minipage): avoid overfull boxes from comment lines.
Modified: trunk/aspell.en.pws
===================================================================
--- trunk/aspell.en.pws 2021-06-18 16:58:07 UTC (rev 927)
+++ trunk/aspell.en.pws 2021-06-21 17:30:21 UTC (rev 928)
@@ -274,3 +274,7 @@
Francorum
Respublica
muglue
+cicero
+didot
+texput
+xstring
Modified: trunk/latex2e.texi
===================================================================
--- trunk/latex2e.texi 2021-06-18 16:58:07 UTC (rev 927)
+++ trunk/latex2e.texi 2021-06-21 17:30:21 UTC (rev 928)
@@ -1503,7 +1503,7 @@
@node fontenc package
@section @code{fontenc} package
- at cindex Font encoding
+ at cindex font encoding
@cindex UTF-8, font support for
@cindex T1
@cindex OT1
@@ -1619,9 +1619,9 @@
@node \DeclareFontEncoding
@subsection @code{\DeclareFontEncoding}
- at cindex Font encoding
- at cindex Encoding, font
- at cindex Accents, defining
+ at cindex font encoding, declaring
+ at cindex encoding, font
+ at cindex accents, defining
@findex \DeclareFontEncoding
Synopsis:
@@ -1666,8 +1666,8 @@
@node \DeclareTextAccent
@subsection @code{\DeclareTextAccent}
- at cindex Font encoding
- at cindex Accents, defining
+ at cindex font encoding
+ at cindex accents, defining
@findex \DeclareTextAccent
Synopsis:
@@ -1698,8 +1698,7 @@
@node \DeclareTextAccentDefault
@subsection @code{\DeclareTextAccentDefault}
- at cindex Font encoding
- at cindex Accents, defining
+ at cindex accents, defining
@findex \DeclareTextAccent
@findex \DeclareTextAccentDefault
@@ -1741,7 +1740,6 @@
@node \DeclareTextCommand & \ProvideTextCommand
@subsection @code{\DeclareTextCommand} & @code{\ProvideTextCommand}
- at cindex Font encoding
@findex \DeclareTextCommand
@findex \DeclareTextCommandDefault
@findex \ProvideTextCommand
@@ -1807,7 +1805,7 @@
@node \DeclareTextCommandDefault & \ProvideTextCommandDefault
@subsection @code{\DeclareTextCommandDefault} & @code{\ProvideTextCommandDefault }
- at cindex Font encoding
+
@findex \DeclareTextCommand
@findex \DeclareTextCommandDefault
@findex \ProvideTextCommand
@@ -1852,8 +1850,7 @@
@node \DeclareTextComposite
@subsection @code{\DeclareTextComposite}
- at cindex Font encoding
- at cindex Accents, defining
+ at cindex accents, defining
@findex \DeclareTextComposite
Synopsis:
@@ -1886,8 +1883,7 @@
@node \DeclareTextCompositeCommand
@subsection @code{\DeclareTextCompositeCommand}
- at cindex Font encoding
- at cindex Accents, defining
+ at cindex accents, defining
@findex \DeclareTextCompositeCommand
Synopsis:
@@ -1914,8 +1910,7 @@
@node \DeclareTextSymbol
@subsection @code{\DeclareTextSymbol}
- at cindex Font encoding
- at cindex Symbol, defining
+ at cindex symbol, defining
@findex \DeclareTextSymbol
Synopsis:
@@ -1953,8 +1948,7 @@
@node \DeclareTextSymbolDefault
@subsection @code{\DeclareTextSymbolDefault}
- at cindex Font encoding
- at cindex Accents, defining
+ at cindex accents, defining
@findex \DeclareTextSymbol
@findex \DeclareTextSymbolDefault
@@ -1991,7 +1985,6 @@
@node \LastDeclaredEncoding
@subsection @code{\LastDeclaredEncoding}
- at cindex Font encoding
@findex \LastDeclaredEncoding
Synopsis:
@@ -2016,7 +2009,6 @@
@node \UseTextSymbol & \UseTextAccent
@subsection @code{\UseTextSymbol} & @code{\UseTextAccent}
- at cindex Font encoding
@findex \UseTextSymbol
@findex \UseTextAccent
@@ -7907,13 +7899,13 @@
Under the hood, @LaTeX{} remembers the @var{cite_key} and @var{label}
information because @code{\bibitem} writes it to the auxiliary file
- at file{@var{jobname}.aux} (@pxref{Jobname}). For instance, the above example causes
- at code{\bibcite@{latexdps@}@{Lamport, 1993@}} and
- at code{\bibcite@{texbook@}@{1@}} to appear in that file. The @file{.aux}
-file is read by the @code{\begin@{document@}} command and then the
-information is available for @code{\cite} commands. This explains why
-you need to run @LaTeX{} twice to resolve references: once to write it
-out and once to read it in.
+ at file{@var{jobname}.aux} (@pxref{Jobname}). For instance, the above
+example causes @code{\bibcite@{latexdps@}@{Lamport, 1993@}} and
+ at code{\bibcite@{texbook@}@{1@}} to appear in that file. The
+ at file{.aux} file is read by the @code{\begin@{document@}} command and
+then the information is available for @code{\cite} commands. This
+explains why you need to run @LaTeX{} twice to resolve references:
+once to write it out and once to read it in.
Because of this two-pass algorithm, when you add a @code{\bibitem} or
change its @var{cite_key} you may get @samp{LaTeX Warning: Label(s) may
@@ -9101,7 +9093,7 @@
paragraph mode; @pxref{Modes}). There are some workarounds; see
following sections.
- at cindex Footnotes, in a minipage
+ at cindex footnotes, in a minipage
@cindex mpfootnote counter
In a @code{minipage} environment the @code{\footnote} command uses the
@code{mpfootnote} counter instead of the @code{footnote} counter, so
@@ -10869,7 +10861,7 @@
@table @code
@item pt
@findex pt
- at cindex Point
+ at cindex point
@anchor{units of length pt}
Point, 1/72.27 inch. The conversion to metric units
is 1 at dmn{point} = 2.845 at dmn{mm} = .2845 at dmn{cm}.
@@ -10888,37 +10880,37 @@
@item bp
@findex bp
- at cindex Big point
+ at cindex big point
@anchor{units of length bp}
Big point, 1/72 inch. This length is the definition of a point in
PostScript and many desktop publishing systems.
@item cm
- at cindex Centimeter
+ at cindex centimeter
@findex cm
@anchor{units of length cm}
Centimeter
@item mm
- at cindex Millimeter
+ at cindex millimeter
@findex mm
@anchor{units of length mm}
Millimeter
@item dd
- at cindex Didot point
+ at cindex didot point
@findex dd
@anchor{units of length dd}
Didot point, 1.07 pt
@item cc
- at cindex Cicero
+ at cindex cicero
@findex cc
@anchor{units of length cc}
Cicero, 12 dd
@item sp
- at cindex Scaled point
+ at cindex scaled point
@findex sp
@anchor{units of length sp}
Scaled point, 1/65536 pt
@@ -12880,7 +12872,7 @@
@node Delimiters
@subsection Delimiters
- at cindex Delimiters
+ at cindex delimiters
@cindex parentheses
@cindex braces
@cindex curly braces
@@ -15113,8 +15105,9 @@
@findex ~
@cindex tie
- at cindex space, hard
@cindex space, unbreakable
+ at cindex hard space
+ at cindex unbreakable space
@cindex NBSP
Synopsis:
@@ -19143,7 +19136,7 @@
@node \contentsline
@subsection @code{\contentsline}
- at cindex Table of contents
+ at cindex table of contents
@findex \contentsline
@findex \tableofcontents
@findex .toc @r{file}
@@ -20941,7 +20934,8 @@
@chapter Command line interface
@anchor{Command line}@c old name
- at cindex command line
+ at cindex command line interface
+ at cindex interface, command line
@cindex CLI
Synopsis (from a terminal command line):
@@ -20950,9 +20944,10 @@
pdflatex @var{options} @var{argument}
@end example
-Run @LaTeX{} on @var{argument}. In place of @command{pdflatex} you can
-also use @command{xelatex}, or @code{lualatex}, or @code{dviluatex}, or
- at code{latex}.
+Run @LaTeX{} on @var{argument}. In place of @command{pdflatex} you
+can also use (for PDF output) @command{xelatex} or @code{lualatex}, or
+(for DVI output) @code{latex} or @code{dvilualatex}, among others
+(@pxref{@TeX{} engines}).
For example, this will run @LaTeX{} on the file @file{thesis.tex},
creating the output @file{thesis.pdf}.
@@ -21012,8 +21007,8 @@
command line.
With many implementations you can specify command line options by
-prefixing them with @samp{-} or @samp{--}. This is the case for
-both @TeX{} Live (and Mac at TeX{}) and MiK at TeX{}. We will use both
+prefixing them with @samp{-} or @samp{--}. This is the case for both
+ at TeX{} Live (including Mac at TeX{}) and MiK at TeX{}. We will use both
conventions interchangeably. If an option takes a value, it can be
specified either as a separate argument (@samp{--foo val}), or as one
argument with an @samp{=} sign (@samp{--foo=val}), but there can be no
@@ -21125,16 +21120,20 @@
@cindex input, on command line
-As part of the command line invocation @code{pdflatex @var{options}
- at var{argument}} you can specify arbitrary @LaTeX{} input by starting
- at var{argument} with a backslash. This allows you to do some special
-effects.
+As part of the command line invocation
- at PkgIndex{hyperref}
-For example, this file (which uses the @file{hyperref} package for
-hyperlinks) can produce two kinds of output, one for paper and one for a
-PDF.
+ at example
+ at var{latex-engine} @var{options} @var{argument}
+ at end example
+ at noindent you can specify arbitrary @LaTeX{} input by starting
+ at var{argument} with a backslash. (All the engines support this.) This
+allows you to do some special effects.
+
+ at PkgIndex{hyperref} For example, this file (which uses the
+ at file{hyperref} package for hyperlinks) can produce two kinds of
+output, one to be read on physical paper and one to be read online.
+
@example
\ifdefined\paperversion % in preamble
\newcommand@{\urlcolor@}@{black@}
@@ -21150,11 +21149,18 @@
@noindent
Compiling this document @file{book.tex} with the command line
@code{pdflatex book} will give the @samp{CTAN} link in blue. But
-compiling it with @code{pdflatex "\def\paperversion@{@}\input book.tex"}
-has the link in black. (Note the use of double quotes to prevent
-interpretation of the symbols by the command line shell; your system may
-do this differently.)
+compiling it with
+ at example
+pdflatex "\def\paperversion@{@}\input book.tex"
+ at end example
+
+ at noindent has the link in black. We use double quotes to prevent
+interpretation of the symbols by the command line shell. (This
+usually works on both Unix and Windows systems, but there are many
+peculiarities to shell quoting, so read your system documentation if
+need be.)
+
In a similar way, from the single file @file{main.tex} you can compile
two different versions.
@@ -21166,9 +21172,11 @@
@noindent
The @code{jobname} option is there because otherwise both files would be
-called @file{main.pdf} and the second would overwrite the first.
+called @file{main.pdf} and the second would overwrite the first. (See
+the next section.)
-In this example, one passes the @code{draft} option to the @file{graphicx} package:
+In this example, we pass the @code{draft} option to the
+ at file{graphicx} package:
@example
pdflatex "\PassOptionsToPackage@{draft@}@{graphicx@}\input@{aa.tex@}"
@@ -21181,71 +21189,83 @@
@node Jobname
- at section Job name
+ at section Jobname
@findex @code{\jobname}
- at cindex Job name
+ at cindex jobname
+ at cindex document root name
+ at cindex name of document root
-Running @LaTeX{} creates a number of files, including the output but
-also including others. These files are named with the job name. The
-most common case is the simplest, where for instance the command
- at code{pdflatex thesis} creates @code{thesis.pdf} and also
- at code{thesis.log} and @code{thesis.aux}. Here the job name is
- at code{thesis}.
+Running @LaTeX{} creates a number of files, including the main PDF (or
+DVI) output but also including others. These files are named with the
+so-called @dfn{jobname}. The most common case is also the simplest,
+where for instance the command @code{pdflatex thesis} creates
+ at code{thesis.pdf} and also @code{thesis.log} and @code{thesis.aux}.
+Here the job name is @code{thesis}.
-In general, the command is @code{@var{latex-engine} @var{options}
- at var{argument}}, where @var{latex-engine} is one of @command{pdflatex},
- at command{xelatex}, or @code{lualatex}, or @code{dviluatex}, or
- at code{latex}. If @var{argument} does not start with a backslash, as
-above with @code{thesis}, then @TeX{} considers it the name of a file to
-input as the document root. The name of that root file, without the
- at file{.tex} extension, is the job name. If @var{argument} does start
-with a backslash, or if @TeX{} is in interactive mode, then it waits for
-the first @code{\input} instruction, and the job name is the name of the
-input file.
+In general, @LaTeX{} is invoked as @code{@var{latex-engine}
+ at var{options} @var{argument}}, where @var{latex-engine} is
+ at command{pdflatex}, @command{lualatex}, etc.@: (@pxref{@TeX{} engines}).
+If @var{argument} does not start with a backslash, as is the case
+above with @code{thesis}, then @TeX{} considers it to be the name of
+the file to input as the main document. The name of that root file,
+without the @file{.tex} extension, is the jobname. If @var{argument}
+does start with a backslash, or if @TeX{} is in interactive mode, then
+it waits for the first @code{\input} command, and the jobname is the
+argument to @code{\input}.
-There are two more possibilities for the job name. To directly specify
-it, use the @code{jobname} option. @ref{Command line input} has an
-example, generating the outputs @file{students.pdf} and
- at file{professors.pdf} from the same source, @file{principal.tex}.
+There are two more possibilities for the jobname. It can be directly
+specified with the @code{-jobname} option, as in @code{pdflatex
+-jobname=myname} (@pxref{Command line input} for a real example).
-The final possibility is that the default job name is @file{texput}. So
-for example, if there is no @code{jobname} option and the compilation
-stops before the first @code{\input}, then the product log will be named
- at file{texput.log}. A special case of this is that in recent versions of
- at LaTeX{} the job name is also @file{texput} if the first @code{\input}
-occurs by being indirectly called by either @code{\documentclass} or
- at code{\RequirePackage}. So this will produce a file named
- at file{texput.pdf}.
+ at findex texput at r{, jobname default}
+ at cindex fallback jobname
+The final possibility is @file{texput}, which is the final fallback
+default if no other name is available to @TeX{}. For example, if no
+ at code{-jobname} option was specified, and the compilation stops before
+there is any output, then the log file will be named
+ at file{texput.log}.
+ at findex \documentclass at r{, and @code{texput} jobname}
+ at findex \RequirePackage at r{, and @code{texput} jobname}
+A special case of this is that in @LaTeX{} versions of (approximately)
+2020 or later, the jobname is also @file{texput} if the first
+ at code{\input} occurs as a result of being called by either
+ at code{\documentclass} or @code{\RequirePackage}. So this will produce
+a file named @file{texput.pdf}:
+
@example
pdflatex "\documentclass@{minimal@}\begin@{document@}Hello!\end@{document@}"
@end example
-However, this special case only applies to those two commands. Here,
+However, this special case only applies to those two commands. Thus, with
@c credit Herbert Voss: https://tex.stackexchange.com/a/17236/121234
@example
pdflatex "\documentclass@{article@}\usepackage@{lipsum@}\input@{thesis@}"
@end example
+ at noindent
the output file is @file{lipsum.pdf}, as @code{\usepackage} calls
@code{\input}.
-Within the document, the macro @code{\jobname} expands to the job name.
+ at findex \jobname
+Within the document, the macro @code{\jobname} expands to the jobname.
(When you run @LaTeX{} on a file whose name contains spaces, the string
returned by @code{\jobname} contains matching start and end quotes.)
In the expansion of that macro, all characters are of
-catcode at tie{}12 (other) except that spaces are category at tie{}10.
-So printing the job name can cause problems if the file name contains
-non-ASCII characters.
+catcode at tie{}12 (other) except that spaces are category at tie{}10,
+including letters that are normally catcode at tie{}11.
-Because of this catcode restriction, to use the job name in a
-conditional, one solution is to use a macro of text from the
- at file{xtring} package in its star variant, which is insensitive to
-catcode. For example, in the following text the footnote ``Including
-Respublica Bananensis Francorum.''@: is only present if the task name
-starts with @file{my-doc}.
+ at findex \IfBeginWith*@r{ macro from @file{xstring}}
+ at PkgIndex xstring
+Because of this catcode situation, using the jobname in a conditional
+can become complicated. One solution is to use the macro
+ at code{\IfBeginWith} from the @file{xstring} package in its star
+variant, which is insensitive to catcode. For example, in the
+following text the footnote ``Including Respublica Bananensis
+Francorum.''@: is only present if the task name starts with
+ at file{my-doc}.
@example
If a democracy is just a regime where citizens vote then
@@ -21254,11 +21274,7 @@
democracies.
@end example
-The potential problem for the unstarred version of @code{\IfBeginWith}
-is that the @code{-} in @samp{my-doc} has catcode at tie{}11, while in
- at code{\jobname}, if a @code{-} is there then it has catcode at tie{}12.
-
-Manipulating the value of @code{\jobname} inside of a document cannot
+Manipulating the value of @code{\jobname} inside of a document does not
change the name of the output file or the log file.
Modified: trunk/writing.html
===================================================================
--- trunk/writing.html 2021-06-18 16:58:07 UTC (rev 927)
+++ trunk/writing.html 2021-06-21 17:30:21 UTC (rev 928)
@@ -166,6 +166,16 @@
<li><span class="listitem">Some entries end with more examples.</span>
Following the full explanation, you may want to give
examples of any fine points.</li>
+
+ <li>Define index entries, with <tt>@cindex</tt> for the general index
+ and <tt>@findex</tt> for macro and other code names. Start general
+ index entries with a lowercase letter (“<tt>font</tt>”,
+ unless the word would normally be capitalized
+ (“<tt>Knuth</tt>”). Code entries should be spelled exactly
+ like the identifier, in all cases (do not capitalize at the beginning
+ of a sentence). It's best to put index entries just after the
+ sectioning command, or at the beginning of the relevant paragraph for
+ more specific references.</li>
</ul>
<p>Examples are particularly important since they are what most people
More information about the latexrefman-commits
mailing list.