diff options
Diffstat (limited to 'macros/latex/contrib/pmdb/docs/pmdb-man.tex')
-rw-r--r-- | macros/latex/contrib/pmdb/docs/pmdb-man.tex | 508 |
1 files changed, 508 insertions, 0 deletions
diff --git a/macros/latex/contrib/pmdb/docs/pmdb-man.tex b/macros/latex/contrib/pmdb/docs/pmdb-man.tex new file mode 100644 index 0000000000..d9e387e55c --- /dev/null +++ b/macros/latex/contrib/pmdb/docs/pmdb-man.tex @@ -0,0 +1,508 @@ +\documentclass{article} +\usepackage{amstext} +\usepackage[ + web={centertitlepage,designv,forcolorpaper,tight*,latextoc,extended}, +% exerquiz, +% eforms={usealtadobe,setcorder}, + aebxmp +]{aeb_pro} +\usepackage[ImplMulti]{dljslib} +\usepackage{graphicx,array,fancyvrb} +\usepackage{aeb_mlink} +%\usepackage{myriadpro} +%\usepackage{calibri} +\usepackage[altbullet]{lucidbry} +\usepackage[dbmode]{pmdb} + +%\previewOn\pmpvOn + +\pmCBPresets{\textColor{red}} + +\reversemarginpar + +\makeatletter +\renewcommand*\l@section[2]{% + \ifnum \c@tocdepth >\z@ + \addpenalty\@secpenalty + \addvspace{.75em \@plus\p@}% make less space + \setlength\@tempdima{1.5em}% + \begingroup + \parindent \z@ \rightskip \@pnumwidth + \parfillskip -\@pnumwidth + \leavevmode \bfseries + \advance\leftskip\@tempdima + \hskip -\leftskip + #1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par + \endgroup + \fi} +\makeatother + +\let\tops\texorpdfstring + + +\def\FmtMP#1{\marginpar{\small\itshape\raggedleft#1}} + +\hfuzz2pt +%\makePDasXOn + +%\previewOn\pmpvOn + +\def\hardspace{{\fontfamily{cmtt}\selectfont\symbol{32}}} +\let\uif\textsf + +\advance\marginparwidth12pt + +\usepackage{acroman} +\usepackage[active]{srcltx} + +\edef\amtIndent{\the\parindent} + +\addtolength{\marginparwidth}{2pt} + +\urlstyle{tt} + +\def\STRUT{\rule{0pt}{14pt}} + +\makeatletter +\newcount\hesheCnt \hesheCnt=-1 +\def\heshe{\@ifstar{\heshei}{\global\advance\hesheCnt1\relax\heshei}} +\def\heshei{\ifodd\hesheCnt she\else he\fi} +\def\HeShe{\@ifstar{\HeShei}{\global\advance\hesheCnt1\relax\HeShei}} +\def\HeShei{\ifodd\hesheCnt She\else He\fi} +\def\hisher{\@ifstar{\hisheri}{\global\advance\hesheCnt1\relax\hisheri}} +\def\hisheri{\ifodd\hesheCnt her\else his\fi} +\def\himher{\@ifstar{\himheri}{\global\advance\hesheCnt1\relax\himheri}} +\def\himheri{\ifodd\hesheCnt her\else him\fi} +\makeatother + +\DeclareDocInfo +{ + university={\AcroTeX.Net}, + title={The \textsf{pmdb} Package}, + author={D. P. Story}, + email={dpstory@acrotex.net}, + subject=Documentation for the pmdb package, + talksite={\url{www.acrotex.net}}, + version={0.4, 2019/12/09}, + Keywords={DB, LaTeX, AcroTeX}, + copyrightStatus=True, + copyrightNotice={Copyright (C) \the\year, D. P. Story}, + copyrightInfoURL={http://www.acrotex.net} +} + +\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{\tops{$\bullet$}{\textrm\textbullet}} + +\def\fnJS{aeb-reader.js} + +\chngDocObjectTo{\newDO}{doc} +\begin{docassembly} +var titleOfManual="The pmdb Package"; +var manualfilename="Manual_BG_Print_pmdb.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} + +%\section{Acknowledgements} +% +%The author would like to acknowledge Thorsten G. (a.k.a., Thor) who proposed +%this workflow and who contributed many ideas, the proposed workflow I found +%to be interesting and worth my time developing the idea; and to J\"{u}rgen G. +%(a.k.a., Loki) who also contributed many good ideas, enthusiasm, questions, +%bug detection, and motivation. High regards and respect to both. +%\begin{flushright} +%D. P. Story (a.k.a., Odon) +%\end{flushright} +% +%\begin{center} +% \fbox{% +% \parbox{.67\linewidth}{\textbf{\textcolor{red}{Warning!}} The workflow of the \textsf{thorshammer} +% package requires the instructor to use \textbf{\textsf{Adobe Acrobat +% XI}}, or later to build the quizzes for distribution. Only \app{Adobe +% Reader} is required for the students. Of course, this is the +% full-featured \app{Adobe Reader} of a desktop or laptop, not the +% \app{Adobe Reader} found on tablets, smartphones, and such. +% }} +%\end{center} + +\section{Introduction} + +This package addresses the issue of a poor-man's database +(\pkg{pmdb}).\footnote{The basic concept for this package was suggested to my +by Thorsten G.} Educators who use {\LaTeX} to construct exams and homework +sometimes have a collection of problems. Each problem is in its own TEX file. +When the educator creates a new exam or homework document, a ``common'' +workflow is to \cs{input} several of these prepared questions. This package +attempts to provide a visual ``user interface'' to the questions and to +provide a mechanism for viewing and selecting questions that are to be +included in the document. + +\paragraph*{How does this package operate?} For a document that inputs content +using the {\LaTeX} command \cs{input}, the same content can be input using +the command \cs{pmInput}\FmtMP{\cs{pmInput\darg{\ameta{path}}}}, a command +defined in this package. When content is input by \cs{pmInput}, a checkbox is +created in the margin at the insertion point of the content. The checkboxes +so created can be checked (to select the associated content) or cleared (to +de-select the content). When the user clicks on a push button provided by +this package, a list of all \emph{selected} \cs{input} statements is +displayed in the JavaScript console. This list can then be copied and pasted +into another document the author is developing. If you +\uif{Ctrl+Click}\FmtMP{\uif{Ctrl+Click}} on a checkbox, the associated +content is opened in the default TEX editor. For this workflow, the document +author can see a typeset of the content and decide whether the content should +be included in the developing document, and can optionally, view the source +file to edit it. + +\section{Requirements and options} + +\paragraph*{Folder JavaScript.} The `\uif{Ctrl+Click}' action feature +requires the installation of the folder JavaScript file +\texttt{\fnJS}\FmtMP{\texttt{\fnJS}},\footnote{If you don't see a need for +this feature, the installation of \texttt{\fnJS} is not essential.} found in +the \texttt{folder-js} folder of this distribution. This file comes with the +distribution of the \pkg{pmdb} package. If you already have the +\pkg{aeb\_pro} package, you've already installed the file +\texttt{aeb\_pro.js}, which includes the special JavaScript functions use by +\pkg{pmbd}; however, version 1.7\FmtMP{Version 1.7 required} or later of +\texttt{aeb\_pro.js} is required. Download the latest version of +\pkg{aeb\_pro} if Version 1.7 is not on your system already. The installation +procedure of folder JavaScript files is described in the file +\texttt{docs/install\_jsfiles.pdf}. The folder JS file \texttt{\fnJS} (or +\texttt{aeb\_pro.js}) enables the `\uif{Ctrl+Click}' to be operational for +both \app{Adobe Acrobat} (\app{AA}) and \app{Adobe Acrobat Reader} +(\app{AR})\FmtMP{\app{AA} and \app{AR}}. + +\paragraph*{Options.} There are four options: \opt{dbmode} and \opt{!dbmode}\FmtMP{\opt{dbmode}\\\relax\opt{!dbmode}}, +and \opt{tight} and +\opt{!tight}\FmtMP{\opt{tight}\\\relax\opt{!tight}}.\footnote{These options +set Boolean switches, \cs{ifpmdbmode} and \cs{ifpmdbtight}, the state of +these switches can be changed within the body of the document.} The default +options are \opt{dbmode} and \opt{!tight}. When \opt{dbmode} is in effect, +checkboxes appear in the margins at each \cs{pmInput} point; for the option +\opt{!dbmode}, the checkboxes are not produced. The use of an exclamation +point (!) makes it convenient to turn on or off the creation of the marginal +checkboxes. The default location of the checkboxes are flush left. The +\opt{tight} option places the checkboxes ``tight'' up against the text area. +Refer to the \textbf{\nameref{para:CB}} paragraph for more information. + +\paragraph*{Requirements.} The \pkg{eforms} package is required for the creation of +checkboxes and push buttons. + +\section{The DB stage} + +When you have a collection of questions (or content) in various files, this +package enables you to build a document that displays these questions (or +content) in a single `DB' document. Once your DB document is build, you can +use the checkboxes in the margin to select content you want to include in +another document; you can use the \uif{Ctrl+Click} feature to view the source +file of that content as well. + +\newtopic +The following comments are apropos to the creation of a DB document: +\begin{itemize} +\item\textbf{PDF creators:} Any PDF creator current in the {\LaTeX} world +is valid for use with this package. + +\item\textbf{PDF viewers:} The ideal viewer is \app{AA}; however, \app{AR} + and \app{PDF-XChange Editor} can also be used. In the case of + \app{Adobe Reader}, there is an annoying security dialog box that + appears each time you use the \uif{Ctrl+Click} feature of the check + box;\footnote{This assumes the file \texttt{\fnJS} is properly + installed.} the \uif{Ctrl+Click} feature \emph{does not work} with + \app{PDF-XChange Editor}. + +For \uif{AR}\FmtMP{To remove the security warning}, the annoying security +dialog mentioned above is emitted when \app{AR} is in \uif{Protected View}. +To avoid the security dialog, exit \uif{Protected View} as follows: +(1)~open \uif{Preferences} (\uif{Ctrl+K}) of \app{AR}; (2) select +\uif{Security (Enhanced)} from the left panel; and (3) clear the +\uif{Enable Protected Mode at startup} checkbox. For \uif{AA}, +\uif{Protected View} set to \uif{Off} by default. +\end{itemize} + +\paragraph*{Outline of a DB file.} A DB file is just a {\LaTeX} document that +uses the \pkg{pmdb} package. The document itself uses \cs{pmInput} to input +its content. +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +\documentclass{article} +\usepackage[forcolorpaper]{web} % optional +% !sffamily Additional packages that may be required by any content +% !sffamily that is !texttt(\pmInput). For example, ... +\usepackage{exerquiz} % if needed +\usepackage[dbmode]{pmdb} +... +\begin{document} + +% Declares input for quiz items +%\InputQuizItems +% Declares input paragraph content +%\InputParas +% Declares input items +%\InputItems + +\pmInput{!ameta(path!SUB1)} + +\pmInput{!ameta(path!SUB2)} + +... + +\pmInput{!ameta(path!SUB(n))} + +\displayChoices\quad\clrChoices +\end{document} +\end{Verbatim} +Descriptions of the various commands \cs{pmInput}, \cs{InputQuizItems}, +\cs{InputParas}, \cs{InputItems}, \cs{displayChocies}, and \cs{clrChoices} +appear later in this documentation.\medskip + +\pmInput{sample-para.tex} + +\paragraph*{Sample files.} +The four sample files are found in the \texttt{examples} folder: +\begin{itemize} +\item \texttt{tst-qzdb.tex}: The example that motivated the creation of this + package. Input various quiz questions into an \env{quiz} environment of + \pkg{exerquiz}. +\item\texttt{tst-paras.tex}: For the \pkg{book} class, we input chapters of + the book using the command \cs{pmInput}. +\item\texttt{tst-qzdb-paras.tex}: A combination of the two example files + above, were we declare \cs{InputQuizItems} to input content of a quiz, + and \cs{InputParas} to input chapters. +\item\texttt{tst-items}: An example that demonstrates the \cs{InputItems} + input mode. +\end{itemize} + +\section{The production stage} + +After your DB document has been assembled (using \pkg{pmdb}), you are ready +to use your DB document to select questions (for quizzes) or other content +for insertion into a new document. + +Open your DB document in \app{AA} or \app{AR}, and open the source file of +your developing document in your {\LaTeX} editor. Within the DB document, select +questions or content by checking any of the checkboxes in the margin. Now press +the \cs{displayChoices} push button. The \uif{AA} (\app{AR}) console window opens +and displays your choices; for example, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] +\input{probs/prob1.tex} +\input{probs/prob4.tex} +\input{probs/prob5.tex} +\end{Verbatim} +These can be copied and pasted into your document. Use the \uif{Ctrl+Click} +feature to view the sources of your choices. It may be you want to modify the +source for your document; (1) edit the DB source snippet you are inputting; +or (2) copy and paste the whole content into your document and make the +needed changes there. Once all content has been referenced by your developing +document, you can compile into a PDF. Done! + +\section{Package commands} + +The package defines several commands and these are discussed now. +\bVerb\small\takeMeasure{\string\pmInput[\ameta{arg}]\darg{\ameta{path}}}% +\begin{dCmd}[fontsize=\small,commandchars=!()]{\bxSize} +\pmInput[!ameta(arg)]{!ameta(path)} +\end{dCmd} +\eVerb Within a DB source document, content is inserted using \cs{pmInput}. This +command both inputs the referenced \ameta{path} (using the {\LaTeX} command +\cs{input}) and places a checkbox in the margin. The \ameta{path} can be a +relative or full path reference. If the \ameta{path}\FmtMP{spaces in \ameta{path} discussed} contains any spaces, the +path needs to be enclosed in \emph{double quotes} (\texttt"); for example, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] +\pmInput{"C:/Users/Public/Documents/My TeX Files/tex/% + latex/aeb/pmdb/examples/chapters/doc2.tex"} +\end{Verbatim} +The optional argument \ameta{arg} is only obeyed when \cs{InputItems} is active and \cs{pmInput} is expanded +within a list environment. + +\paragraph*{Important requirement:} Unlike the normal \cs{input} command\FmtMP{extension required}, we require the file name to include +the extension, `\texttt{.tex}' in the above example. + +\paragraph{Input modes.} There are three `input modes':%\vskip-6pt\par +\bVerb\small\takeMeasure{\string\InputQuizItems}% +\setlength{\eflength}{\widthof{\sffamily(\cs{thQuizName})}}% +\edef\x{\the\eflength}% +\setlength{\eflength}{\bxSize}% +%\def\1{\rlap{\hskip\eflength\rlap{\hskip\x\relax\qquad\cs{def}\cs{thqzname\darg{\ameta{text}}}}\sffamily(\cs{theQuizName})}} +\def\1{\rlap{\hskip\eflength\sffamily(the default)}} +\begin{dCmd}[fontsize=\small,commandchars=!()]{\bxSize} +!1\InputParas +\InputQuizItems +\InputItems +\end{dCmd} +\eVerb A brief description of each follows. +\begin{description} + \item [\cs{InputParas}:] Sets the input mode to input `paragraph + content'. This input mode is suitable for exercises created by the + \env{exercise} environment of \pkg{exerquiz}, whole paragraphs, or + whole chapters. + \item [\cs{InputQuizItems}:] Sets the input mode to input items in a quiz + (as created by the \env{quiz} environment). + \item [\cs{InputItems}:] Sets the input mode to input items in a list + environment. +\end{description} +In all cases, the {\LaTeX} command \cs{marginpar}\FmtMP{\cs{marginpar} used} is used; as a result, the +checkbox appears in the margins when the \cs{marginpar} command is supported; in +particular, \cs{marginpar} does not work in a \env{tabular} environment or a +\env{multicols} environment, for example. + +\newtopic\noindent +Below is an example of \cs{InputItems} + + +\begin{itemize}\pmdbtighttrue\InputItems %\normalmarginpar +\pmInput{sample-item.tex} +\item Another item, not input by \cs{pmInput} +\pmInput[*]{sample-item.tex} +\end{itemize} +The verbatim listing is, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +\begin{itemize}!textbf(\pmdbtighttrue\InputItems) +\pmInput{sample-item.tex} +\item Another item, not input by \verb|\pmInput|. +\pmInput[*]{sample-item.tex} +\end{itemize} +\end{Verbatim} +Note the use of the optional argument for the last \cs{pmInput}. Note also +that both \cs{pmdbtighttrue} and \cs{InputItems} are expanded locally. When +\cs{pmdbtighttrue}, the checkboxes appear ``tight'' against the text box +margin (flush right, in this case). You can (locally) move the checkboxes to +the right margin by expanding \cs{normalmarginpar} within the \env{itemize} +environment group. + + +\paragraph*{Checkboxes.}\label{para:CB} The document produces checkboxes in the margins, you can set +the appearance of the checkboxes using the \cs{pmCBPresets} command +\bVerb\small\takeMeasure{\string\pmCBPresets\darg{\ameta{opts}}}% +\begin{dCmd}[fontsize=\small,commandchars=!()]{\bxSize} +\pmCBPresets{!ameta(opts)} +\end{dCmd} +\eVerb Pass \pkg{eforms} key-value pairs to the checkboxes through the +argument \ameta{opts}; for example, this document was compiled with +\verb~\pmCBPresets{\textColor{red}}~ declared in the preamble, as a result, +the checks are colored red. + +The checkboxes are placed in the margins and hopefully correctly aligned at +the insertion point. For \texttt{article} class-type documents, use of +\cs{reversemarginpar} is recommended. In this case, the checkboxes appear in +the left margin at the extreme left (as seen above). For \texttt{book} +class-type document, the checkboxes alternate between the left and right +margins. The option \opt{tight} can be used to move the checkboxes to the +inner margins of the text block. + +\paragraph*{Push buttons.} The package defines two push buttons that should be utilized +in your DB document. They can be placed at the end of the document, or in a +running footer. + +\bVerb\small\takeMeasure{\string\displayChoices[\ameta{opts}]\darg{\ameta{wd}}\darg{\ameta{ht}}}% +\begin{dCmd}[fontsize=\small,commandchars=!()]{\bxSize} +\displayChoices[!ameta(opts)]{!ameta(wd)}{!ameta(ht)} +\clrChoices[!ameta(opts)]{!ameta(wd)}{!ameta(ht)} +\end{dCmd} +\eVerb \cs{displayChoices} displays the choices made in the console window of \app{AA/AR}, while +\cs{clrChoices} clears all the marginal checkboxes. For example, +\begin{quote} +\begin{tabular}{@{}ll} +\displayChoices{}{11bp}&\clrChoices{}{11bp}\\ +\footnotesize\cs{displayChoices\darg{}\darg{11bp}}& +\footnotesize\cs{clrChoices\darg{}\darg{11bp}} +\end{tabular} +\end{quote} +The \ameta{opts} argument is to modify the appearance of the buttons. There are several supporting, +convenience commands associate with \cs{displayChoices} and \cs{clrChoices}: +\bVerb\small\takeMeasure{\string\displayChoiceCA\darg{\ameta{string}}}% +%\setlength{\eflength}{\widthof{\sffamily(\cs{thQuizName})}}% +%\edef\x{\the\eflength}% +\setlength{\eflength}{\bxSize}% +\def\1{\rlap{\hskip\eflength\sffamily(Display Choices)}} +\def\2{\rlap{\hskip\eflength\sffamily(Lists all choices in the console window)}} +\def\3{\rlap{\hskip\eflength\sffamily(Clear Choices)}} +\def\4{\rlap{\hskip\eflength\sffamily(Clears all checkboxes created by pmdb)}} +%{Display Choices} +%{Lists all choices in the console window} +%{Clear Choices} +%{Clears all checkboxes created by pmdb} +\begin{dCmd}[fontsize=\small,commandchars=!()]{\bxSize} +!1\displayChoiceCA{!ameta(string)} +!2\displayChoiceTU{!ameta(string)} +!3\clrChoicesCA{!ameta(string)} +!4\clrChoicesTU{!ameta(string)} +\end{dCmd} +\eVerb The `CA' commands place captions on the buttons; the `TU' commands +defines tool tips for the buttons. The strings shown in parentheses to the +right are the default declarations for each of the commands. + +\section{Comments on portability} + +The functionality of the document (with the exception of the \uif{Ctrl+Click} +feature) is platform independent; however, to be of any value, the DB files +must accompany the DB document. As long as all references to DB files are +\emph{relative paths} the DB document can be ported elsewhere along with the +supporting DB files. Just ZIP the whole folder containing the DB document and +all DB files. They can now be moved to another computer system, unzipped, and +total functionality attained. For the \uif{Ctrl+Click} feature to work, the +\texttt{\fnJS} file must also be installed. + +\section{Final comments} + +The method of producing the checkboxes in the margins work for many of the +situations that arise in producing a {\LaTeX} document; however, the three +`input modes' \cs{InputParas}, \cs{InputQuizItems}, and \cs{InputItems} may +fail in some situations. By studying the DTX file perhaps you can create more +input modes that solve your problem. + +\newtopic\noindent +It was lovely, but now I must return to my retirement. \dps + +\end{document} + +\bVerb\small\takeMeasure{\string\distrQuizzes\darg{\darg{*\ameta{path\SUB1}}\darg{*\ameta{path\SUB2}}...\darg{*\ameta{path\SUB{num}}}}}% +\begin{dCmd}[fontsize=\small,commandchars=!()]{\bxSize} +\useNameToCustomize +\enumQuizzes{!ameta(num)} +\instrPath{!ameta(path)} +\classPath{!ameta(path)} +\distrQuizzes{{*!ameta(path!SUB1)}{*!ameta(path!SUB2)}...{*!ameta(path!SUB(num))}} +\end{dCmd} +\eVerb |