pdftex[819] branches/stable/doc/manual: improve \pdfmdfivsum and
commits+karl at tug.org
commits+karl at tug.org
Wed Dec 25 20:23:18 CET 2019
Revision: 819
http://tug.org/svn/pdftex?view=revision&revision=819
Author: karl
Date: 2019-12-25 20:23:17 +0100 (Wed, 25 Dec 2019)
Log Message:
-----------
improve \pdfmdfivsum and \pdffiledump descriptions
Modified Paths:
--------------
branches/stable/doc/manual/ChangeLog
branches/stable/doc/manual/pdftex-t.tex
Modified: branches/stable/doc/manual/ChangeLog
===================================================================
--- branches/stable/doc/manual/ChangeLog 2019-12-12 19:13:30 UTC (rev 818)
+++ branches/stable/doc/manual/ChangeLog 2019-12-25 19:23:17 UTC (rev 819)
@@ -1,3 +1,17 @@
+2019-12-25 Karl Berry <karl at freefriends.org>
+
+ * pdftex-t.tex (\pdfmdfivesum): explain the non-file (string) form too.
+ (\pdffiledump): explain that length defaults to zero.
+ Report from Bruno Le Floch,
+ https://tug.org/pipermail/pdftex/2015-July/008948.html.
+
+ Also:
+ (\MDFIVE): avoid oldstyle numbers.
+ (\Syntax): don't swallow spaces after final \kern.
+ (\Whatever): \kern.75em before, for more separation.
+ (\Somethingtext): new \Something that keeps surrounding spaces in
+ input, to be used in text (vs. syntax lines).
+
2019-11-25 Karl Berry <karl at freefriends.org>
* pdftex-t.tex: document \pdfmajorversion. Besides the new
Modified: branches/stable/doc/manual/pdftex-t.tex
===================================================================
--- branches/stable/doc/manual/pdftex-t.tex 2019-12-12 19:13:30 UTC (rev 818)
+++ branches/stable/doc/manual/pdftex-t.tex 2019-12-25 19:23:17 UTC (rev 819)
@@ -47,6 +47,7 @@
\def\eTeX{{$\varepsilon$}-\kern-.125em\TeX}
\def\eg{e.g.}
\def\Eg{E.g.}
+\def\MDFIVE{MD5} % not oldstyle 5, capital MD
\def\PDFReference{{\sl PDF Reference}} % PDF with capital letters
\abbreviation [AFM] {afm} {Adobe Font Metrics}
@@ -74,7 +75,6 @@
\abbreviation [MAC] {Macintosh} {Macintosh hardware platform}
\abbreviation [MACOSX] {Mac\,OS\,X} {Macintosh operating system version 10}
\abbreviation [MACTEX] {Mac\TeX} {\MAC\ \WEBC\ distribution}
-\abbreviation [MDFIVE] {md5} {MD5 message-digest algorithm}
\abbreviation [METAFONT] {\MetaFont} {graphic programming environment, bitmap output}
\abbreviation [METAPOST] {\MetaPost} {graphic programming environment, vector output}
\abbreviation [MIKTEX] {MiK\TeX} {\WIN\ distribution}
@@ -152,7 +152,7 @@
\let\ifpdfabsnum\relax
\let\ifpdfabsdim\relax
-\def\Syntax #1{\strut\kern-.25em{#1}\kern-.25em}
+\def\Syntax #1{\strut\kern-.25em{#1}\kern-.25em\relax}
\def\Next {\crlf\hbox to 2em{}\nobreak}
\def\Sugar #1{\unskip\unskip\unskip\kern.25em{#1}\kern.25em\ignorespaces}
%
@@ -164,11 +164,17 @@
\def\Or {\Sugar{\mathematics{\vert}}}
\def\Rbrace {\Sugar{\tttf\rightargument}}
\def\Tex #1{\Sugar{\type{#1}}}
-\def\Whatever #1{\Sugar{\mathematics{(\hbox{#1})}}}
+\def\Whatever #1{\Sugar{\kern.75em\mathematics{(\hbox{#1})}}} % parens
+ % a full quad before, more of a separator on
+ % syntax lines.
-% hyphenates
+% hyphenates, angle brackets
\def\Something#1{\Sugar{\mathematics{\langle}\prewordbreak
{#1}\prewordbreak\mathematics{\rangle}}}
+%
+% undoes the .25em spacing of \Sugar, letting before and after spaces in
+% the input stand.
+\def\Somethingtext#1{\Syntax{\Something{#1}}}
\hbadness=10000 % don't care
@@ -4231,25 +4237,32 @@
\pdffilesize {./pdftex-t.tex}} for the source of this manual.
\introduced{1.30.0}
-\pdftexprimitive{\Syntax{\Tex{\pdfmdfivesum} file \Something{general text}
- \Whatever{expandable}}}
+\pdftexprimitive{\Syntax{\Tex{\pdfmdfivesum}
+ \Optional{\Literal{file}}
+ \Something{general text} \Whatever{expandable}}}
\bookmark{\tex{pdfmdfivesum\ file}}
-Expands to the \MDFIVE\ of file \Something{general text} in uppercase
-hexadecimal format (same as \type{\pdfescapehex}), \eg\ it's {\tt
-\pdfmdfivesum file {./pdftex-t.tex}} for the source of this manual.
+If the keyword \type{file} is given, expands to the \MDFIVE\ of file
+\Somethingtext{general text} in uppercase hexadecimal format (same as
+\type{\pdfescapehex}). Without \type{file}, expands to the \MDFIVE\ of
+the \Somethingtext{generaltext} taken as a string. For example, it's
+{\tt \pdfmdfivesum file {./pdftex-t.tex}} for the source of this manual.
\introduced{1.30.0}
-\pdftexprimitive{\Syntax{\Tex{\pdffiledump} \Optional{\Literal{offset}
- \Something{number}} \Optional{\Literal{length}
- \Something{number}} \Something{general text} \Whatever{expandable}}}
+\pdftexprimitive{\Syntax{\Tex{\pdffiledump}
+ \Optional{\Literal{offset} \Something{integer}}
+ \Optional{\Literal{length} \Something{integer}}
+ \Something{general text} \Whatever{expandable}}}
\bookmark{\tex{pdffiledump}}
-Expands to the dump of the file \Something{general text} in uppercase
-hexadecimal format (same as \type{\pdfescapehex}), starting at offset
-\Something{number} or 0 with length \Something{number}, if given. The first ten
-bytes of the source of this manual are {\tt \pdffiledump length 10
-{./pdftex-t.tex}}. \introduced{1.30.0}
+Expands to the dump of the first \type{length} \Somethingtext{integer}
+bytes of the file \Somethingtext{general text}, in uppercase hexadecimal
+format (same as \type{\pdfescapehex}), starting at offset
+\type{offset}~\Somethingtext{number}, or the beginning of the file if
+\type{offset}. If \type{length} is not given, the default is zero, so
+expands to nothing. Both \Somethingtext{integer}s must be $\ge0$. For
+example, the first ten bytes of the source of this manual are {\tt
+\pdffiledump length 10 {./pdftex-t.tex}}. \introduced{1.30.0}
%***********************************************************************
More information about the pdftex-commits
mailing list