[latex3-commits] [git/LaTeX3-latex3-pdfresources] develop, testlink: update documentation (e5d2381)
Ulrike Fischer
fischer at troubleshooting-tex.de
Wed Mar 17 20:17:49 CET 2021
Repository : https://github.com/latex3/pdfresources
On branches: develop,testlink
Link : https://github.com/latex3/pdfresources/commit/e5d23817d779ad9aacd3f572721278dde7d0d262
>---------------------------------------------------------------
commit e5d23817d779ad9aacd3f572721278dde7d0d262
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date: Wed Mar 17 20:17:49 2021 +0100
update documentation
>---------------------------------------------------------------
e5d23817d779ad9aacd3f572721278dde7d0d262
CHANGELOG.md | 7 +--
experiments/linkinput.tex | 31 ++++++-----
hyperref-generic.dtx | 131 ++++++++++++++++++++++++++++++++++++++++++----
hyperref-generic.pdf | Bin 873009 -> 892276 bytes
4 files changed, 141 insertions(+), 28 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 534a44f..48fa80c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,9 +12,10 @@ this project uses date-based 'snapshot' version identifiers.
### Changed
- \pdf_name_from_unicode_e:n: use cvn operator with dvips
-- \url: it has an optional argument and protocol, formatting command and encoding
- can be changed.
-- \hyper at linkfile (GoToR links) now use a filespec dictionary. This improves the
+- \url: it has an optional argument through which protocol, formatting command and encoding
+ can be changed
+- \href can use the url arguments too.
+- \hyper at linkfile (GoToR links) now uses a filespec dictionary. This improves the
support for non-ascii files names.
### Added
diff --git a/experiments/linkinput.tex b/experiments/linkinput.tex
index c14a57d..78e22dc 100644
--- a/experiments/linkinput.tex
+++ b/experiments/linkinput.tex
@@ -173,7 +173,7 @@ See
\hrefurl{\ltmpastr}{blub}
\hrefpdf{\ltmpastr}{blub}
\ExplSyntaxOff
-\end{document}
+
\section{parentheses}
These are correctly escaped
@@ -201,7 +201,6 @@ zzzlinebreak.de}{xxx}
\url{https://www.xyz%
zzzlinebreak.de}
-%\end{document}
\section{tilde}
%\makeatletter \def\hyper at tilde{X}\makeatother
@@ -215,7 +214,7 @@ zzzlinebreak.de}
\href{https://www.xyz.de\textasciitilde blub}{xxx}
\url{https://www.xyz.de\textasciitilde blub}
\makeatother
-%\end{document}
+
\section{space}
@@ -223,30 +222,34 @@ Print output is wrong, uri in pdf too (but this works with pdfmanagement).
\href{https://www.xyz.de blub}{xxx}
\url{https://www.xyz.de blub}
-\href{https://www.xyz.de\space blub}{xxx}
-\url{https://www.xyz.de\space blub}
+\href[urlencode]{https://www.xyz.de blub}{xxx}
+\url[urlencode]{https://www.xyz.de blub}
+
+\hrefurl[urlencode]{https://www.spacehrefurl.de blub}{xxx}
\parbox{5cm}{\url{https://www.xyz.de\space blub}}
-%\end{document}
+
\section{percentchar}
The percent is not escaped, but in pdfmanagement it is!!
-\href{https://www.xyz.de%blub}{xxx}
-\href{https://www.xyz.de\%blub}{xxx}
-\url{https://www.xyz.de%blub}
-\url{https://www.xyz.de\%blub}
+\href{https://www.testpercent.de%blub}{xxx}
+\href{https://www.testpercentcmd.de\%blub}{xxx}
+\url{https://www.testpercent.de%blub}
+\url{https://www.testpercentcmd.de\%blub}
+\hrefurl{https://www.testpercent.de%blub}{xxx}
+\hrefurl{https://www.testpercentcmd.de\%blub}{xxx}
+
\makeatletter
\href{https://www.xyz.de\@percentchar blub}{xxx}
\url{https://www.xyz.de\@percentchar blub}
\parbox{3cm}{\url{https://www.xyz.de\@percentchar blub}}
-
-
\makeatother
+
\section{non ascii}
Is expanded to commands
-%\href{https://www.xyz.deöxxx}{xxx}
-%\href{filewithnonasciiöäüxxx}{xxx}
+\href[urlencode]{https://www.nonascii.deöxxx}{xxx}
+\href{filewithnonasciiöäüxxx}{xxx}
%\url{https://www.xyz.deöxxx}
%loops
diff --git a/hyperref-generic.dtx b/hyperref-generic.dtx
index e3fa0cc..12fe7cc 100644
--- a/hyperref-generic.dtx
+++ b/hyperref-generic.dtx
@@ -172,7 +172,7 @@
% The current handling of the metadata is problematic:
% \begin{itemize}
% \item External package like \pkg{hyperxmp} wants to access them too and for
-% this had to patch an number of internal hyperref commands---which is a problem
+% this had to patch an number of internal \pkg{hyperref} commands---which is a problem
% if the internal commands change (as happens with this new driver)
% \item \pkg {hyperref} (and also \pkg{hyperxmp})
% tries to deduce some datas from document commands like
@@ -212,7 +212,7 @@
%
% \end{itemize}
% \section{Dates}
-% \pkg{hyperref has a few keys to set dates}. They typically expect the date
+% \pkg{hyperref} has a few keys to set dates. They typically expect the date
% in \enquote{PDF} format: |D:YYYYMMDDhhmmss+01'00'|.
%
% One should be aware that \pkg{hyperxmp} will sometimes
@@ -243,6 +243,115 @@
% So if the PDF page size is wrong: load one of the other packages setting it
% e.g. the \pkg{color} or the \pkg{graphicx} package.
%
+% \section{Commands to create \enquote{external} references}
+% \pkg{hyperref} has three commands related to external references like
+% URL and file: \cs{url},
+% \cs{nolinkurl} and \cs{href}. The first two take one argument,
+% while the last has two: the url and some free text.
+%
+%
+% \cs{url} and \cs{href} create link annotations. \cs{url} creates always an URI
+% type, \cs{href} creates URI, GoToR and Launch
+% depending on the structure of the argument.
+%
+% \cs{href} has to create a (in the PDF) valid url or file name from its first argument.
+% \cs{url} has to create a (in the PDF) valid url from its only argument and has also to print
+% this argument as url. \cs{nolinkurl} only prints the url.
+%
+% For the printing \cs{url} and \cs{nolinkurl} rely on the url package and its \cs{Url} command.
+%
+% (Expandable) commands are expanded and special chars can also be input by commands but
+% beside this no conversion is done: for all input \pkg{hyperref} basically assumes that
+% the input is already a valid percent encoded url or a valid file name. \pkg{hyperref} also
+% doesn't extend or add protocols.
+%
+% As nowadays everyone is used to copy and paste links with all sorts of unicode into a browser and
+% they work the \pkg{hyperref} input is clearly rather restricted.
+%
+% So the new driver tries to extend the input and print options. Both \cs{href} and \cs{url}
+% can now be told to accept non-ascii url's and to convert them internally to
+% percent encoding. It is possible to define a standard protocol and so to avoid to
+% have to type it all the time.
+%
+% But extending the \emph{print} options for \cs{url} and \cs{nolinkurl} while still
+% using the url-package is hard to impossible in pdf\LaTeX{} due to the way the url package works.
+% Some chars can be added with the help of \cs{UrlSpecial} (at the cost of warnings)
+% but it doesn't work for every input and documenting and explaining all the edge cases is no joy.
+% So instead the new driver offers here the option to use different commands to format
+% the printed output. It must be noted that this disable the special \enquote{hyphenation} method of
+% url's.
+%
+%
+% \subsection{Special problem: links to files}
+%
+% When a file is linked with \cs{href} than normally it is added as URI link. The exceptions are PDF's:
+% for them PDF has the special type GoToR which allows also to link to a destination or a special page.
+%
+% After a number of tests with various PDF viewer established that non-ascii files names don't
+% work at all with a simple file name specification GoToR links now use a full
+% filespec dictionary. This works better, but still no every PDF viewer support this correctly.
+% on various system.
+%
+% The following can be used to test viewers. It assumes that a \texttt{test.pdf},
+% a \texttt{grüßpdf.pdf} and a \texttt{grüße.txt} are in the current folder.
+%
+% \hrefpdf{test.pdf}{test-ascii}
+%
+% \hrefpdf{grüßpdf.pdf}{test grüßpdf.pdf}
+%
+% \hrefurl[urlencode]{grüße.txt}{test grüße.txt}
+%
+%
+% \subsection{Splits}
+%
+% \cs{href} tries to be clever and to detect from the argument
+% if a url or a file link or a launch command should be created.
+%
+% The rules are not trivial, and they make the code complicated.
+% This detection also makes it more difficult to handle special cases
+% like non-ascii input for the link types.
+%
+% For this reason three new commands have been create:
+%
+% \begin{itemize}
+% \item \cs{hrefurl} for standard urls (and non-pdf files)
+% \item \cs{hrefpdf} for references to pdf files
+% \item \cs{hrefrun} for launch links
+% \end{itemize}
+%
+% The new commands don't use prefixes like \cs{href}.
+% Their argument should be the real content.
+%
+% \subsection{Options}
+% All \cs{href} commands and \cs{url} have an option argument for keyval syntax.
+% It accepts the following keys. Not all keys make sense for all keys, but they don't
+% error, they are silently ignored.
+%
+% \begin{tabular}{llp{6cm}}
+% key & applicable commands & note\\\hline
+% urlencode & \cs{hrefurl} & if set the code will convert the argument to percent encoding. This allows non-ascii input.\\
+% protocol & \cs{hrefurl}, \cs{url} & This sets a prefix/protocol that is added to the url, see below. \\
+% format & \cs{url} & a command used to format the printed text. It replaces the standard \cs{Url}. This can improve non-ascii
+% typesetting at the cost of losing the special line breaking.\\
+% destination & \cs{href}, \cs{hrefpdf} & A destination name in the PDF\\
+% page & \cs{href}, \cs{hrefpdf} & destination page, default: 1\\
+% pdfremotestartview &\cs{href}, \cs{hrefpdf} & start view, default: Fit\\
+% ismap & \cs{href}, \cs{hrefurl} & see PDF reference\\
+% afrelationship & \cs{href}, \cs{hrefpdf} & Changes the /AFRelationship key of the filespec dictionary. The value should be a PDF name without the starting slash.\\
+% run-parameter & \cs{hreflaunch} & run parameter (see the PDF reference)\\
+% nextactionraw & various & puts a /Next entry in the action dictionary (see the PDF reference)\\
+% \end{tabular}
+%
+%
+% The first four keys can be set also in \cs{hypersetup} for all following commands in
+% the current group through the keys
+% \texttt{href/urlencode}, \texttt{href/protocol}, \texttt{href/destination}, \texttt{href/format}.
+%
+% It is possible to define own url commands with specific options e.g. with
+%
+% \begin{verbatim}
+% \NewDocumentCommand\myurl{O{}}{\url[protocol=https://,format=\textsc,#1]}
+% \end{verbatim}
%
% \section{Link decorations: border, color, OCG-color, \ldots}
% Some main changes are
@@ -329,7 +438,7 @@
%
% The new key |colorscheme| allows to switch the colors (both for text and borders)
% with a key word. It takes one of the values
-% |orginal| (the colors as hyperref uses normally), |phelype|, |daleif|,
+% |orginal| (the colors as \pkg{hyperref} uses normally), |phelype|, |daleif|,
% |szabolcsA|, |szabolcsB|, |tivv|, |julian|, |henryford|.
%
% The names refer to the authors in answers and comments in
@@ -396,7 +505,7 @@
% to pdftex and luatex driver, but a change for the xetex and dvips driver.
% The (undocumentated) command \cs{setpdflinkmargin} does nothing.
% Use either the key |pdflinkmargin| or \cs{pdfannot_link_margin:n} to change the margin.
-% See also the description in section~\ref{sec:keydesc} and in the hyperref manual.
+% See also the description in section~\ref{sec:keydesc} and in the \pkg{hyperref} manual.
% \end{description}
%
% \section{PDF strings}
@@ -483,7 +592,7 @@
% in \cs{hypersetup} and disable links and anchors completely.
% The new driver passes the options also to the \pkg{bookmark} package if
% \pkg{bookmark} hasn't been loaded yet as bookmarks can't work properly if
-% the anchors from hyperref are missing.
+% the anchors from \pkg{hyperref} are missing.
%
% \DescribeHypkey{link}%
% \DescribeHypkey{url}%
@@ -992,7 +1101,7 @@
\cs_generate_variant:Nn\pdf_object_ref:n {e}
% \end{macrocode}
% \section{Overwriting/providing commands from hyperref}
-% hyperref checks driver version, we need to suppress this during the development
+% \pkg{hyperref} checks driver version, we need to suppress this during the development
% \begin{macrocode}
\chardef\Hy at VersionChecked=1 %don't check the version!
% \end{macrocode}
@@ -1750,7 +1859,7 @@
% \end{macrocode}
% \end{macro}
% \section {Core Hyperref Commands}
-% Every hyperref has to define eight core command:
+% Every \pkg{hyperref} has to define eight core command:
% \begin{verbatim}
% \hyper at anchor
% \hyper at anchorstart
@@ -1878,7 +1987,7 @@
}
% \end{macrocode}
%
-% Now the three hyperref commands.
+% Now the three \pkg{hyperref} commands.
% The splitted commands \cs{hyper at linkstart} and \cs{hyper at linkend} are used for
% footnotemarks, toc and natbib-cites.
% \begin{function}{\hyper at link}
@@ -2112,7 +2221,7 @@
{{\let\protect\relax#2}}
}
% \end{macrocode}
-% The actually command used by hyperref is \cs{@hyper at launch} which uses a delimited
+% The actually command used by \pkg{hyperref} is \cs{@hyper at launch} which uses a delimited
% argument, because of the color the definition is a bit convoluted.
% \begin{macrocode}
\use:x
@@ -2269,7 +2378,7 @@
% \end{macro}
% \subsection{Textcolor of links}
% colors are added in the hooks. This means that they can also be removed if needed.
-% They add a group---this isn't needed with hyperref code, but could be relevant
+% They add a group---this isn't needed with \pkg{hyperref} code, but could be relevant
% with low-level annotations.
% \begin{macrocode}
\prop_map_inline:Nn \c_@@_map_hyp_annot_prop
@@ -3830,7 +3939,7 @@
% set in the preamble for all pages or in the document for the current and the
% following pages. Due to the asynchronous page breaking one has to be careful
% to set it on the right page, e.g. only after a |\newpage|.
-% The generic driver uses a different syntax than the other hyperref drivers:
+% The generic driver uses a different syntax than the other \pkg{hyperref} drivers:
% various transition options can be set by a keyval syntax in the value of
% |pdfpagetransition|. A typical setting looks e.g. like this\\
% |\hypersetup{pdfpagetransition={style=Fly,duration=2,direction=90,opaque=false}}|
diff --git a/hyperref-generic.pdf b/hyperref-generic.pdf
index 49fbd11..81f32ff 100644
Binary files a/hyperref-generic.pdf and b/hyperref-generic.pdf differ
More information about the latex3-commits
mailing list.