pdftex[937] branches/stable/doc/manual: \pdfstartlink: url example;
commits+karl at tug.org
commits+karl at tug.org
Tue Aug 20 18:44:44 CEST 2024
Revision: 937
https://tug.org/svn/pdftex?view=revision&revision=937
Author: karl
Date: 2024-08-20 18:44:44 +0200 (Tue, 20 Aug 2024)
Log Message:
-----------
\pdfstartlink: url example; whatsit "item", not "node"
Modified Paths:
--------------
branches/stable/doc/manual/ChangeLog
branches/stable/doc/manual/pdftex.tex
Modified: branches/stable/doc/manual/ChangeLog
===================================================================
--- branches/stable/doc/manual/ChangeLog 2024-08-04 08:38:19 UTC (rev 936)
+++ branches/stable/doc/manual/ChangeLog 2024-08-20 16:44:44 UTC (rev 937)
@@ -1,3 +1,8 @@
+2024-08-20 Karl Berry <karl at freefriends.org>
+
+ * pdftex.tex (\pdfstartlink): give complete url example.
+ (thoughout): use whatsit
+
2024-07-21 Karl Berry <karl at freefriends.org>
* pdftex.tex (\pdfuseptexuseunderscore): new section.
Modified: branches/stable/doc/manual/pdftex.tex
===================================================================
--- branches/stable/doc/manual/pdftex.tex 2024-08-04 08:38:19 UTC (rev 936)
+++ branches/stable/doc/manual/pdftex.tex 2024-08-20 16:44:44 UTC (rev 937)
@@ -1578,7 +1578,7 @@
\pdftexprimitive{\Syntax{\cs{pdfinterwordspaceoff}}}
\pdftexprimitive{\Syntax{\cs{pdfspacefont} \Something{general text}}}
-The first two commands insert corresponding whatsit nodes which turn
+The first two commands insert corresponding whatsit items which turn
on/off generation of faked interword spaces in the \PDF\ output (they
cause errors in \DVI\ output). This allows for better reflowing of text
on the fly by \PDF\ readers, better extraction of textual content, and
@@ -2046,10 +2046,10 @@
\pdftexprimitive{\Syntax{\cs{pdfrefobj} \Something{object number}
\Modelist{h, v, m}}}
-This command appends a whatsit node to the list being built. When the whatsit
-node is searched at shipout time, \PDFTEX\ will write the object
-\Something{object number}
-to the \PDF\ output if it has not been written yet.
+This command appends a whatsit item to the list being built. When the
+whatsit is searched at shipout time, \PDFTEX\ will write the object
+\Something{object number} to the \PDF\ output if it has not been written
+yet.
\subsection{\cs{pdfretval}}
\pdftexprimitive{\Syntax{\cs{pdfretval} \Whatever{read-only integer}}}
@@ -2174,8 +2174,8 @@
appended to the list being built. The number of the most recently created
form XObject is accessible via \cs{pdflastxform}.
-When issued, \cs{pdfrefxform} appends a whatsit node to the list being
-built. When the whatsit node is searched at shipout time, \PDFTEX\ will
+When issued, \cs{pdfrefxform} appends a whatsit item to the list being
+built. When the whatsit item is searched at shipout time, \PDFTEX\ will
write the form \Something{object number} to the \PDF\ output if it is
not written yet.
@@ -2290,8 +2290,8 @@
\subsection{\cs{pdfrefximage}}
\pdftexprimitive{\Syntax{\cs{pdfrefximage} \Something{object number}}}
-\cs{pdfrefximage} appends a whatsit node to the list being built. When
-the whatsit node is searched at shipout time, \PDFTEX\ will write the image
+\cs{pdfrefximage} appends a whatsit item to the list being built. When
+the whatsit item is searched at shipout time, \PDFTEX\ will write the image
with number \Something{object number} to the \PDF\ output if it has not been
written yet.
@@ -2554,14 +2554,15 @@
\pdftexprimitive{\Syntax{\cs{pdfannot} \Something{annot type spec}
\Modelist{h, v, m}}}
-This command appends a whatsit node corresponding to an annotation to
+\label{pdfannot}
+This command appends a whatsit item corresponding to an annotation to
the list being built. The dimensions of the annotation can be controlled
via the \Something{rule spec}. The default values are ``running'' for
all width, height and depth. When an annotation is written out, running
dimensions will take the corresponding values from the box containing
-the whatsit node representing the annotation. The \Something{general
+the whatsit item representing the annotation. The \Something{general
text} is inserted as raw \PDF\ code to the contents of annotation. The
-annotation is written only if the corresponding whatsit node is searched
+annotation is written only if the corresponding whatsit item is searched
at shipout time.
\subsection{\cs{pdflastannot}}
@@ -2585,7 +2586,7 @@
\pdftexprimitive{\Syntax{\cs{pdfdest} \Something{dest spec}
\Modelist{h, v, m}}}
-This primitive appends a whatsit node which establishes a destination
+This primitive appends a whatsit item which establishes a destination
for links and bookmark outlines; the link is identified by either a
number or a symbolic name, and the way the viewer is to display the page
is specified in \Something{dest spec}, which must be one of those
@@ -2622,7 +2623,7 @@
a separate namespace and therefore may have the same identifiers as a
regular destination.
-The destination is written out only if the corresponding whatsit node is
+The destination is written out only if the corresponding whatsit item is
searched at shipout time.
\subsection{\cs{pdfstartlink}}
@@ -2633,42 +2634,77 @@
\Modelist{h, m}
}}
-This primitive is used along with \cs{pdfendlink} and appends
-a whatsit node corresponding to the start of a hyperlink. The whatsit
-node representing the end of the hyperlink is created by
-\cs{pdfendlink}. The dimensions of the link are handled in the
-similar way as in \cs{pdfannot}. Both \cs{pdfstartlink} and
-\cs{pdfendlink} must be in the same level of box nesting. A hyperlink
-with running width can be multi\hyph line or even multi\hyph page, in which case
-all horizontal boxes with the same nesting level as the boxes containing
-\cs{pdfstartlink} and \cs{pdfendlink} will be treated as part of
-the hyperlink. The hyperlink is written out only if the corresponding
-whatsit node is searched at shipout time.
+\noindent \Syntax{
+\Something{attr spec} \Means
+ \Literal{attr} \Something{general text}
+}
+\noindent \Syntax{
+\Something{action spec} \Means
+ \Literal{user} \Something{user-action spec}
+ \Or \Literal{goto} \Something{goto-action spec}
+ \Or \Literal{thread} \Something{thread-action spec}
+}
-Additional attributes, which are explained in great detail in the
-\PDFReference, can be given via \Something{attr spec}. Typically, the
-attributes specify the color and thickness of any border around the
-link. As a simple example, \verb|/C [0.9 0 0] /Border [0 0 2]| specifies
-a color (in \RGB) of dark red, and a border thickness of 2~points.
+This primitive is used along with \cs{pdfendlink} and appends a whatsit
+item corresponding to the start of a hyperlink. Another whatsit
+representing the end of the hyperlink is created by \cs{pdfendlink}.
+Some salient points about PDF links:
-While all graphics and text in a \PDF\ document have relative positions,
+\begin{itemize}
+\item The dimensions of the link are handled in the similar way as in
+\cs{pdfannot} (p.~\pageref{pdfannot}).
+
+\item A \cs{pdfstartlink} and its corresponding \cs{pdfendlink} must be
+at the same level of box nesting.
+
+\item The hyperlink is written to the final output only if the
+corresponding whatsit is searched at shipout time.
+
+\item A hyperlink with running width can be multi\hyph line or even multi\hyph
+page, in which case all horizontal boxes with the same nesting level as
+the boxes containing \cs{pdfstartlink} and \cs{pdfendlink} will be
+treated as part of the hyperlink.
+
+\item While all graphics and text in a \PDF\ document have relative positions,
annotations have internally hard\hyph coded absolute positions. Again
this is for the sake of speed optimization. The main disadvantage is
that these annotations do \emph{not} obey transformations issued by
\type{\pdfliteral}.
+\end{itemize}
+
+The \Something{attr spec} allows specifying numerous additional
+attributes for the link, which are explained in great detail in the
+\PDFReference. Typically, the attributes specify the color and thickness
+of any border around the link. As a simple example,
+\verb|attr{/C [0.9 0 0] /Border [0 0 2]}|
+specifies a color (in \RGB) of dark red, and a border thickness of 2
+(PostScript) points.
+
The \Something{action spec} specifies the action that should be
-performed when the hyperlink is activated, one of (see the syntax
-rules): \Literal{user} \Something{user-action spec},
-\Literal{goto} \Something{goto-action spec},
-\Literal{thread} \Something{thread-action spec}.
+performed when the hyperlink is activated. The data inside the
+\Something{action spec}s is typically PostScript dictionaries and
+variable settings, as defined by the \PDFReference. The different
+\Something{action spec} possibilities are:
\begin{itemize}
\item A \Something{user-action spec} (\type{user{...}}) performs a
-user\hyph defined action. Examples:
-a \URL, as in \verb|/S /URI /URI (https://tug.org/)|;
-a named action, as in \verb|/S /Named /N /NextPage|.
+user\hyph defined action, such as jumping to another
+location in the document or opening a url (see the ``Actions'' section
+in the \PDFReference, \S12.6). Here's a complete example for making a
+link to a url:
+\begin{verbatim}
+\pdfstartlink
+ attr{/Border [0 0 0]}
+ user{/Subtype /Link
+ /A << /S /URI /URI (https://tug.org/) >>}%
+TUG home page%
+\pdfendlink
+\end{verbatim}
+\noindent The \type{/Border} value in the \type{attr} line eliminates
+the default box around the link displayed by viewers.
+
\item A \Something{goto-action spec} (\type{goto...}) performs various
goto actions, and is by far the most complex action. Here is a copy of
the syntax, for easier reference:
@@ -2759,7 +2795,7 @@
\pdftexprimitive{\Syntax{\cs{pdfrunninglinkoff}}}
\pdftexprimitive{\Syntax{\cs{pdfrunninglinkon}}}
-These commands create corresponding whatsit nodes which turn off/on
+These commands create corresponding whatsit items which turn off/on
generation of running links. Their typical usage is to turn off
generation of running links in the header or footer of a page.
Generation of running links is on when the shipout routine begins.
@@ -2771,7 +2807,7 @@
top entry in \type{pdf_link_stack}; if so, that box would become a link,
too.
-The whatsit nodes created by the above primitives turn off/on a flag
+The whatsit items created by the above primitives turn off/on a flag
which controls if a hbox being shipped can become a link, in addition to
the previous condition.
@@ -2861,14 +2897,14 @@
}}
Analogous to \cs{special} in the original \TEX, this command inserts
-raw \PDF\ code into the output, appending a whatsit node to the list
+raw \PDF\ code into the output, appending a whatsit item to the list
being built. This allows support of color and text transformation, among
other things.
By default, \Something{general text} is expanded immediately, when the
-whatsit node is created, as with \cs{special}. Starting with \PDFTEX\
+whatsit item is created, as with \cs{special}. Starting with \PDFTEX\
1.40.25, the optional keyword \Literal{shipout} can be used to delay
-expansion of \Something{general text} until the whatsit node is shipped
+expansion of \Something{general text} until the whatsit item is shipped
out, as with non-\cs{immediate} \cs{write}.
Normally, \PDFTEX\ ends a text section in the \PDF\ output and sets the
@@ -4208,7 +4244,7 @@
\Something{action spec} \Means
\Literal{user} \Something{user-action spec}
\Or \Literal{goto} \Something{goto-action spec}
- \Or \Next \Literal{thread} \Something{thread-action spec}
+ \Or \Literal{thread} \Something{thread-action spec}
}
\Syntax{
More information about the pdftex-commits
mailing list.