[latex3-commits] [git/LaTeX3-latex3-pdfresources] rename-coredict: reviewing docu (885fa9a)

[Ulrike Fischer]

Repository : https://github.com/latex3/pdfresources
On branch  : rename-coredict
Link       : https://github.com/latex3/pdfresources/commit/885fa9aed9639a9681ecad56cc41772e2cfacd85

>---------------------------------------------------------------

commit 885fa9aed9639a9681ecad56cc41772e2cfacd85
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date:   Tue Dec 1 20:53:30 2020 +0100

    reviewing docu


>---------------------------------------------------------------

885fa9aed9639a9681ecad56cc41772e2cfacd85
 l3pdfmanagement.dtx | 31 +++++++++++++------------------
 pdfresources.dtx    |  4 ++--
 2 files changed, 15 insertions(+), 20 deletions(-)

diff --git a/l3pdfmanagement.dtx b/l3pdfmanagement.dtx
index fe50158..49d757d 100644
--- a/l3pdfmanagement.dtx
+++ b/l3pdfmanagement.dtx
@@ -57,7 +57,8 @@
 %
 % The commands in this module offer interfaces to this core PDF dictionaries
 % They unify a number of primitives like the pdftex
-% registers \cs{pdfcatalog}, \cs{pdfpagesattr}, \cs{pdfinfo}, \cs{pdfpageresources}
+% registers and commands \cs{pdfcatalog}, \cs{pdfpageattr},
+% \cs{pdfpagesattr}, \cs{pdfinfo}, \cs{pdfpageresources}
 % and similar commands of the other backends in a backend independant way.
 %
 % The supported backends are pdflatex, lualatex, (x)dvipdfmx (latex, xelatex)
@@ -74,8 +75,8 @@
 % The dictionaries and resources handled by this module are inserted only
 % once in a PDF or only once per page. Examples are the Catalog dictionary,
 % the Info dictionary, the page resources. For these dictionaries and resources
-% management by the
-% \LaTeX{} kernel is necessary to avoid that packages overwrite settings from
+% management by the \LaTeX{} kernel is necessary to avoid
+% that packages overwrite settings from
 % other packages which would lead to clashes and incompatibilities.
 % It is therefore necessary that all packages which want to add content to this
 % dictionaries and resources use the interface provided by this module.
@@ -110,6 +111,7 @@
 %  There is no \texttt{Page/Resources/Properties} dictionary in the list
 %  as this dictionary is not filled directly but
 %  managed through side effects when setting BDC-marks.
+%
 %  \subsection{User Commands}
 %  To avoid problems with older documents the resource management of this
 %  module is not activated unconditionally. The values are pushed out to the
@@ -125,21 +127,16 @@
 %   \begin{syntax}
 %     \cs{pdfmanagement_add:nnn} \Arg{resource path} \Arg{name} \Arg{value}
 %   \end{syntax}
-% This function puts \Arg{name} \Arg{value} globally in an internal
-% property lists and writes it later into the PDF dictionary\footnote{Currently all
-% resources are PDF dictionaries, so resource and dictionary mean the same.} described by
-% \Arg{resource path}.
-% \Arg{resource path} is a symbolic name for a concrete PDF dictionary to
-% which the content of these property lists will be written by the PDF
-% resource management code.
+% This function puts \Arg{name} \Arg{value} in the PDF resource described by
+% the symbolic name \Arg{resource path}. Technically it stores it globally in an internal
+% property lists and writes it later into the right PDF dictionary\footnote{Currently all
+% resources are PDF dictionaries, so resource and dictionary mean the same.}
+% Which values for \Arg{resource path} exist is described in the following.
 % \Arg{name} should be a valid PDF Name without
 % the starting slash.
 % \Arg{value} should be a valid PDF value for this Name in the
 % target dictionary.
 %
-% The PDF resource management code predefines a large number of
-% symbolic names for important core dictionaries and will write the stored values
-% at the right time to the PDF. The predefined symbolic names are described below.
 %
 % The code works with all major engines but not necessarily
 % in the same way. Most importantly
@@ -162,9 +159,7 @@
 %   This shows the content of the dictionary targetted by
 %   \Arg{resource path} in the log and on the terminal if possible.
 %
-%   It can't show some subdictionaries of the catalog which have arrays as values
-%   as these are filled only at the end of the document. It is also not reliable for
-%   page resources as these are filled at shipout.
+%   It is not reliable for page resources as these are filled at shipout.
 %\end{function}
 % \begin{function}[added = 2020-04-07]
 %   {
@@ -179,8 +174,8 @@
 %   If \meta{name} is not found no change occurs,
 %   \emph{i.e}~there is no need to test for the existence of a name before
 %   trying to remove it.
-%   Values from the special Catalog entries with arrays as values can not be
-%   removed.
+%   Values from the special Catalog entries where the values are collected in arrays
+%   can't be removed (but should ever a use case appear it could be added).
 % \end{function}
 % \subsection{Description of the resource pathes}
 % \subsubsection{Info: The Info dictionary}
diff --git a/pdfresources.dtx b/pdfresources.dtx
index 9da3f59..abbc964 100644
--- a/pdfresources.dtx
+++ b/pdfresources.dtx
@@ -284,8 +284,8 @@
 % It is then viewer dependent which one is showed, so it is better to avoid this.
 % We therefore setup a property which is filled and written to the info
 % directory in one go. According to hyperref a few odd drivers (hvtex, dvipsone, dviwind)
-% don't support arbitrary keys, but this should be handle elsewhere. Most entries are
-% strings so there is a special command for this. As entries with empty content
+% don't support arbitrary keys, but this should be handle elsewhere.
+% As entries with empty content
 % should be omitted we add a test. The string command should perhaps escape the argument,
 % but for now we are assuming that the argument is pdf safe.
 % hyperref writes to the info dictionary at the shipout of the first page --