xbmks (11jun18)

git-svn-id: svn://tug.org/texlive/trunk@47991 c570f23f-e606-0410-a88d-b1316a301751

9 files changed, 503 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/xbmks/README.md b/Master/texmf-dist/doc/latex/xbmks/README.md
new file mode 100644
index 00000000000..cab5c8ab91d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/xbmks/README.md
@@ -0,0 +1,25 @@
+The xbmks Package
+Author: D. P. Story 
+Dated: 2018/06/11
+
+Short description: Create a cross-document bookmark tree. 
+
+The package defines the concept of a document bundle, which is a collection 
+of documents that are to be build separately, but have a common bookmark 
+tree. 
+
+This package takes the bookmarks of each file in doc bundle and merges them. 
+The merged bookmarks are listed in all the documents of the document bundle. 
+In this way, a sort of 'table of contents' is available to all documents in 
+the bundle.
+
+PDF Creator: no restrictions, use dvips->distiller|ps2pdf, pdflatex, 
+lualatex, or xelatex.
+ 
+
+Now, I simply must get back to my retirement.
+
+D. P. Story
+www.acrotex.net
+dpstory@uakron.edu
+dpstory@acrotex.net
diff --git a/Master/texmf-dist/doc/latex/xbmks/docs/xbmksman.pdf b/Master/texmf-dist/doc/latex/xbmks/docs/xbmksman.pdf
new file mode 100644
index 00000000000..178da6d808a
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/xbmks/docs/xbmksman.pdf
diff --git a/Master/texmf-dist/doc/latex/xbmks/docs/xbmksman.tex b/Master/texmf-dist/doc/latex/xbmks/docs/xbmksman.tex
new file mode 100644
index 00000000000..bff6b09c411
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/xbmks/docs/xbmksman.tex
@@ -0,0 +1,337 @@
+%
+% Need some discussion on workflow
+%
+% makeindex < aebpro_man.idx > aebpro_man.ind
+\documentclass[10pt]{article}
+\usepackage[fleqn]{amsmath}
+\usepackage[
+    web={centertitlepage,designv,forcolorpaper,latextoc,pro,addtoHyOpts={pagebackref=false}},
+    eforms,
+%    linktoattachments,
+    aebxmp
+]{aeb_pro}
+\usepackage{aeb_mlink}
+\usepackage{graphicx,array}
+%\usepackage{myriadpro}
+%\usepackage{calibri}
+\usepackage[altbullet]{lucidbry}
+
+%\previewtrue
+%\usepackage{makeidx}
+%\makeindex
+\usepackage{acroman}
+\usepackage[active]{srcltx}
+
+\setcounter{secnumdepth}{4}
+\setcounter{tocdepth}{5}
+\makeatletter
+\renewcommand*{\theparagraph}{\texorpdfstring{\protect\P\protect\ }{\textparagraph}}
+\renewcommand{\paragraph}
+    {\renewcommand{\@seccntformat}[1]{\theparagraph}%
+    \@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\color{\aeb@subsubsectioncolor}\bfseries}}
+\renewcommand*\l@paragraph{\@dottedtocline{4}{5.0em}{1em}} %{7.0em}{4.1em}}
+\def\chgCurrLblName#1{\def\@currentlabelname{#1}}
+\def\echgCurrLblName#1{\edef\@currentlabelname{#1}}
+\makeatother
+
+\getDimsFromGraphic{graphics/dpsweb}{\dpswebW}{\dpswebH}
+
+
+%\urlstyle{rm}
+\urlstyle{sf}
+\let\uif\textsf
+\let\app\textsf
+\def\psf#1{\textbf{\textsf{#1}}}
+\let\amtIndent\leftmargini
+
+\renewcommand*\descriptionlabel[1]{\hspace\labelsep
+    \normalfont #1}
+
+
+\DeclareDocInfo
+{
+    university={Acro\negthinspace\TeX.Net},
+    title={The \textsf{xbmks} package\texorpdfstring{\\}{:}Cross-document bookmarks},
+    author={D. P. Story},
+    email={dpstory@acrotex.net},
+    subject={Documentation for the richtext package from AcroTeX},
+    talksite={\url{www.acrotex.net}},
+    version={1.0, 2018/06/11},
+    keywords={AcroTeX, rich text strings},
+    copyrightStatus=True,
+    copyrightNotice={Copyright (C) \the\year, D. P. Story},
+    copyrightInfoURL={http://www.acrotex.net}
+}
+
+\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}%
+   \kern-.6em \hbox{$\mathcal S$}}$}
+
+\universityLayout{fontsize=Large}
+\titleLayout{fontsize=LARGE}
+\authorLayout{fontsize=Large}
+\tocLayout{fontsize=Large,color=aeb}
+\sectionLayout{indent=-62.5pt,fontsize=large,color=aeb}
+\subsectionLayout{indent=-31.25pt,color=aeb}
+\subsubsectionLayout{indent=0pt,color=aeb}
+\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}}
+
+\widestNumber{0.00.}
+%\pagestyle{empty}
+%\parindent0pt\parskip\medskipamount
+
+\def\dps{$\mbox{$\mathfrak D$\kern-.3em\mbox{$\mathfrak P$}%
+   \kern-.6em \hbox{$\mathcal S$}}$}
+
+\newcount\fldCnt \fldCnt=0
+\def\incFldCnt{\global\advance\fldCnt1\relax}
+
+\frenchspacing
+
+\chngDocObjectTo{\newDO}{doc}
+\begin{docassembly}
+var titleOfManual="The xbmks package MANUAL";
+var manualfilename="Manual_BG_Print_xbmks.pdf";
+var manualtemplate="Manual_BG_Brown.pdf"; // Blue, Green, Brown
+var _pathToBlank="C:/Users/Public/Documents/ManualBGs/"+manualtemplate;
+var doc;
+var buildIt=false;
+if ( buildIt ) {
+    console.println("Creating new " + manualfilename + " file.");
+    doc = \appopenDoc({cPath: _pathToBlank, bHidden: true});
+    var _path=this.path;
+    var pos=_path.lastIndexOf("/");
+    _path=_path.substring(0,pos)+"/"+manualfilename;
+    \docSaveAs\newDO ({ cPath: _path });
+    doc.closeDoc();
+    doc = \appopenDoc({cPath: manualfilename, oDoc:this, bHidden: true});
+    f=doc.getField("ManualTitle");
+    f.value=titleOfManual;
+    doc.flattenPages();
+    \docSaveAs\newDO({ cPath: manualfilename });
+    doc.closeDoc();
+} else {
+    console.println("Using the current "+manualfilename+" file.");
+}
+var _path=this.path;
+var pos=_path.lastIndexOf("/");
+_path=_path.substring(0,pos)+"/"+manualfilename;
+\addWatermarkFromFile({
+    bOnTop:false,
+    bOnPrint:false,
+    cDIPath:_path
+});
+\executeSave();
+\end{docassembly}
+
+\begin{document}
+
+\maketitle
+
+\selectColors{linkColor=black}
+\tableofcontents
+\selectColors{linkColor=webgreen}
+
+\def\AcroT{Acro\!\TeX}\def\cAcroT{\textcolor{blue}{\AcroT}}
+\def\AcroEB{\AcroT{} eDucation Bundle}\def\cAcroEB{\textcolor{blue}{\AcroEB}}
+\def\AcroB{\AcroT{} Bundle}\def\cAcroB{\textcolor{blue}{\AcroB}}
+\def\bUrl{http://www.math.uakron.edu/~dpstory}
+
+\hypersetup{linktocpage}
+
+
+\section{Introduction}
+
+It has been more than a couple decades ago (counting back from 2018), I wrote
+two mathematics tutorials:
+\textsl{\href{http://www.math.uakron.edu/~dpstory/e-calculus.html}{eCalculus}}
+and
+\textsl{\mlhref{http://www.math.uakron.edu/~dpstory/mpt_home.html}{Algebra
+Review in Ten Lessons}}. The tutorials consisted of a number of lessons, each
+lesson was in a separate PDF. The bookmarks of each lesson contained the
+table of contents \emph{for the whole tutorial}. A student, in theory, could
+then jump from one lesson to another by selecting a topic of interest from
+the bookmarks. In the intervening years I have not seen a {\LaTeX} package
+for merging the table of contents of a set of PDFs and merge them in this
+each member of the set. The \pkg{xbmks} package attempts to reproduce this
+feature.
+
+\section{Required packages and options}
+
+The only requirement is the \pkg{hyperref} package; there is a negative
+requirement, the \pkg{bookmark} package is not supported. If it is detected
+within a \pkg{xbmks} document, normal non-cross-document bookmarks are
+produced.
+
+The only options are driver options, these are \opt{dvips} (\app{Acrobat
+Distiller} or \app{ps2pdf} can be used as the PDF creator), \opt{pdftex} (and
+\opt{luatex}, which is treated the same as \opt{pdftex}), and \opt{xetex}. Of
+course, this is a {\LaTeX} package, so the `la' versions of these applications
+need to be used. The package auto-detects \app{pdftex} and \app{xetex}, and
+\opt{dvips} is the default, so there is actually  no need to pass the driver
+option.
+
+\section{The preamble command \texorpdfstring{\protect\cs{xbmksetup}}{\textbackslash{xbmksetup}}}
+
+The only user command is \cs{xbmksetup}:
+\bVerb\def\1{\qquad}\takeMeasure{\1colors=\darg{intdoc=\ameta{color},extdoc=\ameta{color}},}%
+\begin{dCmd}[commandchars=!()]{\bxSize}
+\xbmksetup{%
+!1docbundle={!ameta(doc!SUB1),!ameta(doc!SUB2),...,!ameta(doc!SUB(n))},
+!1colors={intdoc=!ameta(color),extdoc=!ameta(color)},
+!1style={intbf,extbf,intit,extit}
+}
+\end{dCmd}
+\eVerb You have a collection of files (as specified by the \texttt{docbundle}
+key) that you want to merge the bookmarks together so they appear in all the
+files. However, the \cs{xbmksetup} only appears \textbf{in one and only one
+of the documents}, perhaps the one that you think of as the main file.\footnote{The main file is the first one
+listed in the value of the \texttt{docbundle} key.} The
+argument of \cs{xbmksetup} are written to the file \texttt{xbmks.cfg} and
+input back into each of the files as they are compiled. This is needed so
+that across all files in the document bundle, they all obey the very same
+options.
+
+\paragraph*{Description of the key-values}
+\begin{description}
+  \item[\texttt{docbundle}] (Required) The value of this key, \emph{which
+      is required to be nonempty}, is a comma-delimited list of base names
+      that are a part of this document collection, or bundle. For example,
+\begin{Verbatim}[xleftmargin=\amtIndent]
+docbundle={lesson1,lesson2,lesson3,lesson4}
+\end{Verbatim}
+The order the bookmarks are listed in each file of the document bundle is the same order
+the files are listed in \texttt{docbundle}; in this above example, the bookmarks for
+\texttt{lesson1} are listed first, than those of \texttt{lesson2}, and so on.
+
+The first document listed (\texttt{lesson1}) is where the \cs{xbmksetup}
+commend is placed. This file might be thought of as the `main' file.
+
+\textbf{\textcolor{red}{Important:}} It is extremely important to list the
+base names the using the same spelling and case as the \cs{jobname} command
+returns in each of the bundle collection. When each file is compiled,
+\pkg{xbmks} tries to determine which in the list of \texttt{docbundle}
+files is the one currently being compiled; it is necessary in order to
+create a internal jump or an external jump. If anything goes wrong, be sure
+to check the spelling of each file listed.
+
+  \item[\texttt{colors}] (Optional) For any given document in the bundle,
+      there are two types of links in the bookmarks, a link to an item in
+      the current (or internal) document, or a link to an external document
+      (within the bundle of documents).
+  \begin{itemize}
+      \item \texttt{intdoc=\ameta{color}}, where \ameta{color} is an rgb
+          color. This specifies the color of the link for an internal
+          jump within the current document. Specify the color
+          using the syntax \texttt{\darg{[rgb]{\ameta{r},\ameta{g},\ameta{b}}}};
+          for example,
+\begin{Verbatim}[xleftmargin=\amtIndent]
+colors={intdoc={[rgb]{0,.6,0}}
+\end{Verbatim}
+or, if the \pkg{xcolor} package is loaded, \emph{named colors} may be used.
+    \item\texttt{extdoc=\ameta{color}}, where \ameta{color} is an rgb
+        color. This specifies the color of the link for an external jump
+          to another member of the document bundle. Color specification is the
+          same as for \texttt{intdoc}:
+\begin{Verbatim}[xleftmargin=\amtIndent]
+colors={intdoc=red,extdoc=blue}
+\end{Verbatim}
+In the above example, we assume \pkg{xcolor} is loaded and specify the
+colors accordingly.
+
+\textbf{The default color.} If you declare \texttt{intdoc} (or
+\texttt{extdoc}) without a value, you get the default, which is the color
+key is not specified within the PDF document. The \texttt{color} key is
+optional, in which case, you get the default color. What is the default
+color? Well, its either white or black, depending on the \textsf{Display
+Theme}. The PDF viewer (\app{Acrobat} and \app{Acrobat Reader DC}
+automatically switch colors when the theme is changed).
+
+When you specify a color, be aware that what looks good in the \emph{light
+theme} may not be so visible in a \emph{dark theme}.
+  \end{itemize}
+  \item[\texttt{style}] (Optional) The Adobe PDF viewer applications also
+      support a bold and italics style. These can be specified for the
+      internal and external documents.
+  \begin{itemize}
+    \item Internal style (valueless) keys are \texttt{intbf} and \texttt{intit}; zero, one, or
+    two of these may be specified,
+\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
+style={intbf}         % !normalfont(bold font)
+style={intit}         % !normalfont(italics font)
+style={intbf,intit}   % !normalfont(bold and italics font)
+\end{Verbatim}
+  \item External style (valueless) keys are \texttt{extbf} and \texttt{extit}; zero, one, or
+    two of these may be specified,
+\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
+style={extbf}         % !normalfont(bold font)
+style={extit}         % !normalfont(italics font)
+style={extbf,extit}   % !normalfont(bold and italics font)
+\end{Verbatim}
+  \end{itemize}
+Of course, all these keys are specified or not, in the \texttt{style} key:
+\begin{Verbatim}[xleftmargin=\amtIndent]
+style={intbf,extit}
+\end{Verbatim}
+Here, we specify bold font for the current document and an italics for an
+internal document.
+\end{description}
+
+
+\newtopic\noindent\textbf{Point of personal preference.} After experimenting with
+various combinations of colors and styles with combinations of themes
+(light and dark) I prefer no color specified with bold font for the current
+document and plain font for any external document. I think it's important to
+make it clear in the bookmark panel which are internal and which are
+external. The bold font tells the same story independent of theme. Thus,\def\1{\qquad}%
+\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
+\xbmksetup{%
+!1docbundle={!ameta(doc!SUB1),!ameta(doc!SUB2),...,!ameta(doc!SUB(n))},
+!1style={intbf}
+}
+\end{Verbatim}
+seems to be a reasonable choice of key-values.
+
+\section{Workflow}
+
+Given that you have a collection of files that are to contain a common set of
+bookmarks, how exactly do you do this? Basically, you treat them the same way
+as you would when you use the \pkg{xy-hyper} package, used for creating cross
+document links.
+
+\paragraph*{Steps to build the document bundle}\leavevmode
+
+\begin{enumerate}
+    \item Compile each document at least twice without deleting any
+        auxiliary files, more if you are using \pkg{xr-hyper}; in
+        particular, without deleting any \textsf{OUT} outline files created
+        by \pkg{hyperref}.
+
+        In terms of order of compilation, compile the main file first (the
+        one that contains the \cs{xbmksetup} command); this will write the
+        \texttt{xbmks.cfg} file and it will be available to the other files
+        in the bundle as you compile them.
+
+    \item All files have been compiled twice, now compile them one more
+        time so they can input the updated \textsf{OUT} files of the
+        collection and the \texttt{xbmks.cfg} configuration file that
+        contains your setup options for the whole collection.
+    \item If you are using \app{pdflatex}, \app{lualatex}, or
+        \app{xelatex}, you are done; otherwise, covert each DVI file to PS
+        using \app{dvips}. Finally, convert each PS file in the collection
+        to PDF using \app{Acrobat Distiller} or \app{ps2pdf}.
+    \item Delete all auxiliary file, including \texttt{xbmks.cfg} if you wish.
+\end{enumerate}
+If you are on \app{Windows OS}, you can use the
+\app{\href{http://www.acrotex.net/builders/}{AeB Builder}}
+utility.\footnote{\url{http://www.acrotex.net/builders/}} In that utility, you would select the
+\app{External cross-references} option, found on the user-interface.
+
+\paragraph*{Sample files.} The demonstration files are found in the \texttt{examples} folder. The
+\pkg{xcolor} package is used, otherwise, the packages used are minimal.
+
+
+\newtopic\noindent Now, back to my retirement. \dps
+
+
+
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/xbmks/examples/doc1.pdf b/Master/texmf-dist/doc/latex/xbmks/examples/doc1.pdf
new file mode 100644
index 00000000000..351354a5363
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/xbmks/examples/doc1.pdf
diff --git a/Master/texmf-dist/doc/latex/xbmks/examples/doc1.tex b/Master/texmf-dist/doc/latex/xbmks/examples/doc1.tex
new file mode 100644
index 00000000000..10dda228034
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/xbmks/examples/doc1.tex
@@ -0,0 +1,43 @@
+\documentclass{article}
+\usepackage{xcolor}
+\usepackage[bookmarksopen]{hyperref}
+\usepackage{xbmks}
+
+% the xr-hyper package may also be used if you have
+% cross document links within the body of the doc
+%\usepackage{xr-hyper}
+%\externaldocument[m-]{master}
+%\externaldocument[d2-]{doc2}
+
+
+
+\begin{document}
+
+\section{Doc 1: Sec 1}\label{sec1}
+
+Some content goes here.
+
+\newpage
+
+\subsection{Doc 1: subSec 1}
+
+Some content goes here.
+
+\newpage
+
+\subsection{Doc 1: subSec 2}
+
+Some content goes here.
+
+\newpage
+
+\section{Doc 1: Sec 2}
+
+Some content goes here.: go to Section~\ref{sec1}
+
+\newpage
+
+\subsection{Doc 1: subSec 1}
+
+
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/xbmks/examples/doc2.pdf b/Master/texmf-dist/doc/latex/xbmks/examples/doc2.pdf
new file mode 100644
index 00000000000..494fa06b274
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/xbmks/examples/doc2.pdf
diff --git a/Master/texmf-dist/doc/latex/xbmks/examples/doc2.tex b/Master/texmf-dist/doc/latex/xbmks/examples/doc2.tex
new file mode 100644
index 00000000000..9229cb1473e
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/xbmks/examples/doc2.tex
@@ -0,0 +1,41 @@
+\documentclass{article}
+\usepackage{xcolor}
+\usepackage[bookmarksopen]{hyperref}
+\usepackage{xbmks}
+
+% the xr-hyper package may also be used if you have
+% cross document links within the body of the doc
+%\usepackage{xr-hyper}
+%\externaldocument[m-]{master}
+%\externaldocument[d1-]{doc1}
+
+\begin{document}
+
+\section{Doc 2: Sec 1}
+
+Some content goes here.
+
+\newpage
+
+\subsection{Doc 2: subSec 1}
+
+Some content goes here.
+
+\section{Doc 2: Sec 2}
+
+\subsection{Doc 2: subSec 1}
+
+Some content goes here.
+
+\newpage
+
+\subsection{Doc 2: subSec 2}
+
+Some content goes here.
+
+\subsection{Doc 2: subSec 3}
+
+Some content goes here.
+
+
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/xbmks/examples/master.pdf b/Master/texmf-dist/doc/latex/xbmks/examples/master.pdf
new file mode 100644
index 00000000000..f82fe27dc2d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/xbmks/examples/master.pdf
diff --git a/Master/texmf-dist/doc/latex/xbmks/examples/master.tex b/Master/texmf-dist/doc/latex/xbmks/examples/master.tex
new file mode 100644
index 00000000000..21bd1f47927
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/xbmks/examples/master.tex
@@ -0,0 +1,57 @@
+\documentclass{article}
+\usepackage{xcolor}
+\usepackage[bookmarksopen]{hyperref}
+\usepackage{xbmks}
+
+% the xr-hyper package may also be used if you have
+% cross document links within the body of the doc
+%\usepackage{xr-hyper}
+%\externaldocument[d1-]{doc1}
+%\externaldocument[d2-]{doc2}
+
+\title{On merging bookmarks for several documents}
+\author{D. P. Story}
+
+% The \xbmksetup command is placed in only 
+% one of the collection. It is written to xbmks.cfg
+% in input by the other files to obtain uniformity
+% of option choices.
+\xbmksetup{%
+  docbundle={master,doc1,doc2},
+%  colors={intdoc=red,extdoc},
+  style={intbf}
+}
+
+\begin{document}
+
+\maketitle
+
+\section{Master One}
+
+Some content goes here.
+
+\subsection{Master One: subSec 1}
+
+Some content goes here.
+
+\newpage
+
+
+\section{Master Two}
+
+Some content goes here.
+
+
+\subsection{Master Two: subSec 1}
+
+Some content goes here.
+
+\newpage
+
+\subsection{Master Two: subSec 2}
+
+Some content goes here.
+
+
+\end{document}
+