From f986f34bcdb3eadcd5c99c415ec92109e2fb423e Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 11 Jun 2018 22:22:36 +0000 Subject: xbmks (11jun18) git-svn-id: svn://tug.org/texlive/trunk@47991 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/xbmks/README.md | 25 ++ .../texmf-dist/doc/latex/xbmks/docs/xbmksman.pdf | Bin 0 -> 193947 bytes .../texmf-dist/doc/latex/xbmks/docs/xbmksman.tex | 337 +++++++++++++++++++++ .../texmf-dist/doc/latex/xbmks/examples/doc1.pdf | Bin 0 -> 31874 bytes .../texmf-dist/doc/latex/xbmks/examples/doc1.tex | 43 +++ .../texmf-dist/doc/latex/xbmks/examples/doc2.pdf | Bin 0 -> 30227 bytes .../texmf-dist/doc/latex/xbmks/examples/doc2.tex | 41 +++ .../texmf-dist/doc/latex/xbmks/examples/master.pdf | Bin 0 -> 53092 bytes .../texmf-dist/doc/latex/xbmks/examples/master.tex | 57 ++++ 9 files changed, 503 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/xbmks/README.md create mode 100644 Master/texmf-dist/doc/latex/xbmks/docs/xbmksman.pdf create mode 100644 Master/texmf-dist/doc/latex/xbmks/docs/xbmksman.tex create mode 100644 Master/texmf-dist/doc/latex/xbmks/examples/doc1.pdf create mode 100644 Master/texmf-dist/doc/latex/xbmks/examples/doc1.tex create mode 100644 Master/texmf-dist/doc/latex/xbmks/examples/doc2.pdf create mode 100644 Master/texmf-dist/doc/latex/xbmks/examples/doc2.tex create mode 100644 Master/texmf-dist/doc/latex/xbmks/examples/master.pdf create mode 100644 Master/texmf-dist/doc/latex/xbmks/examples/master.tex (limited to 'Master/texmf-dist/doc/latex/xbmks') 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 Binary files /dev/null and b/Master/texmf-dist/doc/latex/xbmks/docs/xbmksman.pdf differ 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 Binary files /dev/null and b/Master/texmf-dist/doc/latex/xbmks/examples/doc1.pdf differ 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 Binary files /dev/null and b/Master/texmf-dist/doc/latex/xbmks/examples/doc2.pdf differ 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 Binary files /dev/null and b/Master/texmf-dist/doc/latex/xbmks/examples/master.pdf differ 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} + -- cgit v1.2.3