[latex3-commits] [git/LaTeX3-latex3-latex3] pdf_destination: improve documentation of keywords and fitr handling (34783c231)

[Ulrike Fischer]

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}