[latex3-commits] [git/LaTeX3-latex3-latex3] pdf_destination: improve documentation of keywords and fitr handling (34783c231)
Ulrike Fischer
fischer at troubleshooting-tex.de
Mon Jan 4 17:41:47 CET 2021
Repository : https://github.com/latex3/latex3
On branch : pdf_destination
Link : https://github.com/latex3/latex3/commit/34783c231382a9c1e5bcc5309dec1be9edbccd57
>---------------------------------------------------------------
commit 34783c231382a9c1e5bcc5309dec1be9edbccd57
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date: Mon Jan 4 17:41:47 2021 +0100
improve documentation of keywords and fitr handling
>---------------------------------------------------------------
34783c231382a9c1e5bcc5309dec1be9edbccd57
l3experimental/l3pdf/l3pdf.dtx | 53 ++++++++++++++++++++++++++++++++++++++----
1 file changed, 49 insertions(+), 4 deletions(-)
diff --git a/l3experimental/l3pdf/l3pdf.dtx b/l3experimental/l3pdf/l3pdf.dtx
index 722ac154c..536093e01 100644
--- a/l3experimental/l3pdf/l3pdf.dtx
+++ b/l3experimental/l3pdf/l3pdf.dtx
@@ -175,17 +175,61 @@
% initialised.
% \end{function}
% \subsection{Destinations}
-% % \begin{function}[added = 2021-01-03]
+% Destinations are the places a link jumped too.
+% Unlike the name may suggest they don't described
+% an exact location in the PDF. Instead a destination contains a reference to
+% a page along with an instruction how to display this page.
+% The normally used \enquote{XYZ \textit{top left zoom}} for example instructs
+% the viewer to show the page with the given \textit{zoom} and
+% the top left corner at the \textit{top left} coordinates---which then gives
+% the impression that there is an anchor at this position.
+%
+% If an instruction takes a coordinate, it is calculated by the following
+% commands relative to the location the command is issued.
+% So to get a specific coordinate one has to move the command to the right place.
+%
+% \begin{function}[added = 2021-01-03]
% {\pdf_destination:nn}
% \begin{syntax}
% \cs{pdf_destination:nn} \Arg{name} \Arg{type or integer}
% \end{syntax}
-% This creates a destination. \Arg{type or Integer} can be one of |fit|, |fith|,
+% This creates a destination. \Arg{type or integer} can be one of |fit|, |fith|,
% |fitv|, |fitb|, |fitbh|, |fitbv|, |fitr|, |xyz|
% or an integer representing a scale factor in percent.
+% |fitr| here gives only a lightweight version of |/FitR|:
% The backend code defines |fitr| so that it will with pdflatex and
% lualatex use the coordinates of the surrounding box,
-% with dvips and dvipdfmx it falls back to |fit|.
+% with dvips and dvipdfmx it falls back to |fit|. For full control use
+% \cs{pdf_destination_box:nn}.
+%
+% The keywords match to the PDF names as described in the following tabular.
+%
+% \medskip
+% \noindent\begin{tabular}{ll>{\raggedright\arraybackslash}p{6cm}}
+% \toprule
+% Keyword & PDF & Remarks \\ \midrule
+% |fit| & |/Fit|
+% & Fits the page to the window\\
+% |fith| & |/FitH| \textit{top}
+% & Fits the width of the page to the window \\
+% |fitv| & |/FitV| \textit{left}
+% & Fits the height of the page to the window \\
+% |fitb| & |/FitB|
+% & Fits the page bounding box to the window \\
+% |fitbh|& |/FitBH| \textit{top}
+% & Fits the width of the page bounding box to the window. \\
+% |fitbv|& |/FitBV| \textit{left}
+% & Fits the height of the page bounding box to the window. \\
+% |fitr| & |/FitR| \textit{left bottom right top}
+% & Fits the rectangle specified by the four coordinates to the window
+% (see above for the restrictions)\\
+% |xyz| & |/XYZ| \textit{left top} null
+% & Sets a coordinate but doesn't change the zoom.\\
+% \Arg{integer} & |/XYZ| \textit{left top zoom}
+% & Sets a coordinate and a zoom meaning \Arg{integer}\%.
+% \\\bottomrule
+% \end{tabular}
+%
% \end{function}
% \begin{function}[added = 2020-01-03]
% {\pdf_destination_box:nn}
@@ -193,7 +237,8 @@
% \cs{pdf_destination_box:nn} \Arg{name} \Arg{content}
% \end{syntax}
% This stores the content in a hbox, outputs the box and
-% creates a destination with |FitR| type encompassing this box.
+% creates a destination with |/FitR| type encompassing this box. This works for
+% all drivers so is the preferred method to create a |/FitR| destination.
% \end{function}
%
% \end{documentation}
More information about the latex3-commits
mailing list.