From 2e831b2bb763d3a1892a395c43f8b8248936b9dd Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Wed, 15 Jul 2020 03:01:32 +0000 Subject: CTAN sync 202007150301 --- macros/latex/contrib/aeb_mlink/README.md | 22 +- macros/latex/contrib/aeb_mlink/aeb_mlink.dtx | 68 +- macros/latex/contrib/aeb_mlink/doc/aeb_mlink.pdf | Bin 160605 -> 0 bytes .../latex/contrib/aeb_mlink/doc/aebmlink_man.pdf | Bin 335247 -> 0 bytes .../latex/contrib/aeb_mlink/doc/aebmlink_man.tex | 930 ------------------- macros/latex/contrib/aeb_mlink/docs/aeb_mlink.pdf | Bin 0 -> 4241282 bytes .../latex/contrib/aeb_mlink/docs/aebmlink_man.pdf | Bin 0 -> 336663 bytes .../latex/contrib/aeb_mlink/docs/aebmlink_man.tex | 943 ++++++++++++++++++++ .../latex/contrib/aeb_mlink/examples/mlink_tst.pdf | Bin 66970 -> 83880 bytes .../latex/contrib/aeb_mlink/examples/mlink_tst.tex | 5 +- .../contrib/aeb_mlink/examples/mlink_tst_url.pdf | Bin 35662 -> 36137 bytes .../contrib/aeb_mlink/examples/mlink_tst_url.tex | 3 + macros/latex/contrib/edichokey/README.md | 36 + .../latex/contrib/edichokey/edichokey-doc-en.pdf | Bin 0 -> 63825 bytes .../latex/contrib/edichokey/edichokey-doc-en.tex | 160 ++++ macros/latex/contrib/edichokey/edichokey-ex.pdf | Bin 0 -> 54358 bytes macros/latex/contrib/edichokey/edichokey-ex.tex | 377 ++++++++ macros/latex/contrib/edichokey/edichokey.sty | 89 ++ macros/latex/contrib/elpres/README | 20 - macros/latex/contrib/elpres/README.md | 39 + macros/latex/contrib/elpres/elpres-example.pdf | Bin 0 -> 52814 bytes macros/latex/contrib/elpres/elpres-example.tex | 82 +- macros/latex/contrib/elpres/elpres-manual.pdf | Bin 209590 -> 255477 bytes macros/latex/contrib/elpres/elpres-manual.tex | 317 +++++-- macros/latex/contrib/elpres/elpres.cls | 46 +- macros/latex/contrib/polytable/README | 4 +- macros/latex/contrib/polytable/polytable.dtx | 99 ++- macros/latex/contrib/polytable/polytable.pdf | Bin 288334 -> 447964 bytes macros/latex/contrib/schooldocs/README.md | 31 + .../contrib/schooldocs/schooldocs-examples.pdf | Bin 0 -> 348408 bytes macros/latex/contrib/schooldocs/schooldocs.dtx | 987 +++++++++++++++++++++ macros/latex/contrib/schooldocs/schooldocs.ins | 55 ++ macros/latex/contrib/schooldocs/schooldocs.pdf | Bin 0 -> 567470 bytes 33 files changed, 3214 insertions(+), 1099 deletions(-) delete mode 100644 macros/latex/contrib/aeb_mlink/doc/aeb_mlink.pdf delete mode 100644 macros/latex/contrib/aeb_mlink/doc/aebmlink_man.pdf delete mode 100644 macros/latex/contrib/aeb_mlink/doc/aebmlink_man.tex create mode 100644 macros/latex/contrib/aeb_mlink/docs/aeb_mlink.pdf create mode 100644 macros/latex/contrib/aeb_mlink/docs/aebmlink_man.pdf create mode 100644 macros/latex/contrib/aeb_mlink/docs/aebmlink_man.tex create mode 100644 macros/latex/contrib/edichokey/README.md create mode 100644 macros/latex/contrib/edichokey/edichokey-doc-en.pdf create mode 100644 macros/latex/contrib/edichokey/edichokey-doc-en.tex create mode 100644 macros/latex/contrib/edichokey/edichokey-ex.pdf create mode 100644 macros/latex/contrib/edichokey/edichokey-ex.tex create mode 100644 macros/latex/contrib/edichokey/edichokey.sty delete mode 100644 macros/latex/contrib/elpres/README create mode 100644 macros/latex/contrib/elpres/README.md create mode 100644 macros/latex/contrib/elpres/elpres-example.pdf create mode 100644 macros/latex/contrib/schooldocs/README.md create mode 100644 macros/latex/contrib/schooldocs/schooldocs-examples.pdf create mode 100644 macros/latex/contrib/schooldocs/schooldocs.dtx create mode 100644 macros/latex/contrib/schooldocs/schooldocs.ins create mode 100644 macros/latex/contrib/schooldocs/schooldocs.pdf (limited to 'macros') diff --git a/macros/latex/contrib/aeb_mlink/README.md b/macros/latex/contrib/aeb_mlink/README.md index 47fdf7879c..f9717bf8dd 100644 --- a/macros/latex/contrib/aeb_mlink/README.md +++ b/macros/latex/contrib/aeb_mlink/README.md @@ -1,28 +1,30 @@ Package: aeb_mlink Author: D. P. Story -Dated: 2020-01-06 +Dated: 2020-07-12 The aeb_mlink package defines new link commands to create multi-line links. The new commands are \mlhypertext, \mlhyperlink, \mlhyperref, \mlnameref, \mlNameref, \mlhref, and \mlurl. -PDF Creators: Adobe Distiller or ps2pdf +PDF Creators: Adobe Distiller or ps2pdf. -What's New (2020-01-06) This package reads web.cfg (web package, -if available). The web.cfg has changed format slightly, this -update now conforms to that format. Defined new option urlOpts to -pass options to the url package. +What's New (2020-07-12): An aeb_mlink document can now be compiled with +pdflatex, lualatex, or xelatex. In this case, no links are created and +only the link text is typeset. In this way, in theory, document authors +can use their favorite PDF creator and view the document in their favorite +PDF previewer (SumatraPDF). To create multi-line links, compile with a +dvips->(distiller|ps2pdf) workflow. -What's New (2018/08/18): Created \turnSyllbCntOn (\turnSyllbCntOff) to turn +What's New (2018-08-18): Created \turnSyllbCntOn (\turnSyllbCntOff) to turn on (resp., off) the viewing of syllable numbers. Reorganize core program to accommodate the use of \mlhypertext command within the program code of annot_pro. (This is to implement text markup annotations in that package.) -What's New (2018/04/26): Included a 'dummy' package named aeb-mlink. The +What's New (2018-04-26): Included a 'dummy' package named aeb-mlink. The aeb_mlink package is listed on CTAN as aeb-mlink, though there is no such package by that name. Well, now there is. -What's New (2018/04/20): Previously, the links created by aeb_mlink consisted +What's New (2018-04-20): Previously, the links created by aeb_mlink consisted of a series of rectangles around each of the syllables of the hypertext or url; the little rectangles responded in unison when any one of them were clicked. In this version, Postscript procedures are used to combine the @@ -35,7 +37,7 @@ a link apart, breaking it into two links. The second link is free to move to the next page. This package requires the latest version of AeB, in particular, the eforms -package required is dated 2018/03/22 or later. See ctan.org/pkg/acrotex. +package required is dated 2018-03-22 or later. See ctan.org/pkg/acrotex. In addition to the demo files distributed with the package, there are two new demo files available from the AcroTeX Blog webiste: diff --git a/macros/latex/contrib/aeb_mlink/aeb_mlink.dtx b/macros/latex/contrib/aeb_mlink/aeb_mlink.dtx index 2061df662e..749fc41905 100644 --- a/macros/latex/contrib/aeb_mlink/aeb_mlink.dtx +++ b/macros/latex/contrib/aeb_mlink/aeb_mlink.dtx @@ -14,11 +14,12 @@ % %\NeedsTeXFormat{LaTeX2e} %\ProvidesPackage{aeb_mlink} -% [2020/01/06 v2.3.5 AeB MLink (dps)] +% [2020/07/12 v2.3.6 AeB MLink (dps)] %<*driver> \documentclass{ltxdoc} \usepackage{xcolor} -\usepackage[colorlinks,hyperindex=false]{hyperref} +\usepackage[colorlinks,hyperindex=false,pdfpagemode=UseNone]{hyperref} +\let\bWebCustomize\endinput \usepackage{aeb_mlink} \pdfstringdefDisableCommands{\let\\\textbackslash}% \OnlyDescription % comment out for implementation details @@ -121,12 +122,64 @@ % \section{Package Requirements and Options} % After having established the alternate of this package, we now work on the package itself. % \changes{v2.3}{2018/04/26}{Added \string\pkg{aeb-mlink} as an alternate name for this package} +% \changes{v2.3.6}{2020/07/12}{Added some safeguards against using a driver other than dvips} % \begin{macrocode} % Begin Package %<*package> \RequirePackage{xkeyval} \RequirePackage{ifpdf}[2006/02/20] \RequirePackage{ifxetex}[2006/08/21] +% \end{macrocode} +% (2020/07/12) We test for non-pdfmark drivers, if present, we make minimal +% package definitions, define all relevant commands to display their \ameta{text} +% argument. In this way, \app{pdflatex}, \app{lualatex}, and \app{xelatex} can be used +% to preview the document, perhaps viewing the results in \app{SumatraPDF}. +% \begin{macrocode} +\ifpdf + \let\ML@action\endinput +\else + \ifxetex + \let\ML@action\endinput + \else + \let\ML@action\relax + \fi +\fi +\ifx\ML@action\endinput +% \end{macrocode} +% \paragraph*{Begin the minimal version of the package.} Designed for when +% a non-pdfmark driver is used: \texttt{latex\,->\,dvips\,->\ameta{\upshape{distiller\string|ps2pdf}}} +% \begin{macrocode} +\RequirePackage{hyperref} +%\RequirePackage{refcount} +\RequirePackage{eforms}[2018/08/16] +% \end{macrocode} +% Make all commands of this package to do nothing other +% then to reproduce their \ameta{text} argument. +% \begin{macrocode} +\@ifundefined{mlhypertext}{\newcommand}{\renewcommand}% +\mlhypertext[2][]{#2} +\newcommand\mlhyperlink[3][]{#3} +\newcommand\mlhyperref[3][]{#3} +\newcommand\mlNameref[2][]{#2} +\newcommand\mlnameref[2][]{#2} +\newcommand\mlhref[3][]{#3} +\newcommand\mlurl[2][]{\expandafter\Hurl\expandafter{#2}} +\let\mlMarksOn\relax +\let\mlMarksOff\relax +\let\turnSyllbCntOn\relax +\let\turnSyllbCntOff\relax +\def\mlcs#1{\texttt{\@backslashchar#1}} +\def\mlMaxNSylls{30} +\PackageWarningNoLine{aeb_mlink} + {PDF creation requires Adobe Distiller.\MessageBreak + Workflow is latex > dvips > distiller; otherwise,\MessageBreak + this package does nothing} +\fi +\ML@action % \endinput or \relax +% \end{macrocode} +% \paragraph*{Begin the pdfmark version of the package}\leavevmode\\[6pt] +% Set the driver for \texttt{dvips} +% \begin{macrocode} \newif\if@ml@dvips \@ml@dvipstrue \def\mlcsarg#1#2{\expandafter#1\csname#2\endcsname} % \end{macrocode} @@ -559,11 +612,12 @@ gMrk 0 0 put^^J% % We finished searching for line breaks and are now going to work on combining % contiguous quads. Contiguous quads are the ones between the offsets recorded % in the \texttt{gMrk} array. Now, if there are now line breaks, the length -% of \texttt{gMrk} is one +% of \texttt{gMrk} is one. % % \texttt{gAry} is a temporary array that holds all the quads \emph{corresponding to % one line}. Each syllable generates an quad of length 8. Here, we assume any given -% line has at most \cs{mlMaxNSylls} syllables, (currently set to \mlMaxNSylls, but may be revised). The array \texttt{gAry} is declared +% line has at most \cs{mlMaxNSylls} syllables, (currently set to \cs{mlMaxNSylls}, +% but may be revised). The array \texttt{gAry} is declared % inside the next loop, so it is redeclared at each iteration of the loop. If \app{Distiller} of \app{ps2pdf} % fails, it may be due to \cs{mlMaxNSylls} being too small for some of your sentences; in this case, redefine % \cs{mlMaxNSylls} to a larger value. @@ -741,7 +795,7 @@ yMin 20 string cvs pf(]\string\n)pf^^J}% } def }} % \end{macrocode} -% \leavevmode\DescribeMacro{\mlMarksOn} +% \DescribeMacro{\mlMarksOn} % Added tracking marks. Turn them on with \cs{mlMarksOn} and off again % with \DescribeMacro{\mlMarksOff}\cs{mlMarksOff}. % \changes{v2.1.8}{2018/03/19}{Added tracking marks} @@ -1515,6 +1569,10 @@ yMin 20 string cvs pf(]\string\n)pf^^J}% \let\eq@@mlhyph\@empty \def\ml@typset@syl#1{\raisebox{\ml@raiseamt} {\smash{\normalfont\normalcolor\tiny\strut\llap{\the#1}}}} +% \end{macrocode} +% \DescribeMacro\turnSyllbCntOn Turns on the counting of the syllables, +% while \DescribeMacro\turnSyllbCntOff\cmd{\turnSyllbCntOff} counting marks off. +% \begin{macrocode} \def\turnSyllbCntOn{\mlMarksOn\let\ml@typeset@@syl\ml@typset@syl} \def\turnSyllbCntOff{\let\ml@typeset@@syl\@gobble} \turnSyllbCntOff diff --git a/macros/latex/contrib/aeb_mlink/doc/aeb_mlink.pdf b/macros/latex/contrib/aeb_mlink/doc/aeb_mlink.pdf deleted file mode 100644 index 755abb2edb..0000000000 Binary files a/macros/latex/contrib/aeb_mlink/doc/aeb_mlink.pdf and /dev/null differ diff --git a/macros/latex/contrib/aeb_mlink/doc/aebmlink_man.pdf b/macros/latex/contrib/aeb_mlink/doc/aebmlink_man.pdf deleted file mode 100644 index 94c613d8ef..0000000000 Binary files a/macros/latex/contrib/aeb_mlink/doc/aebmlink_man.pdf and /dev/null differ diff --git a/macros/latex/contrib/aeb_mlink/doc/aebmlink_man.tex b/macros/latex/contrib/aeb_mlink/doc/aebmlink_man.tex deleted file mode 100644 index db47d32ead..0000000000 --- a/macros/latex/contrib/aeb_mlink/doc/aebmlink_man.tex +++ /dev/null @@ -1,930 +0,0 @@ -% makeindex < aebpro_man.idx > aebpro_man.ind -\documentclass{article} -%\usepackage[fleqn]{amsmath} -\usepackage[ - web={centertitlepage,designv,forcolorpaper, - tight*,latextoc,pro,usetemplates}, - eforms={useui}, - aebxmp -]{aeb_pro} -\usepackage[dblevel=1]{aeb_mlink} - -%\usepackage{myriadpro} -\usepackage[altbullet]{lucidbry} -\usepackage{xbmks} - -\DeclareInitView{layoutmag={navitab:UseOutlines}} -\xbmksetup{colors={int=red},styles={intbf}} - - -\usepackage{acroman} - -%\def\amtIndent{15pt} -\edef\amtIndent{\the\leftmargini} - -\usepackage[active]{srcltx} - -\DeclareDocInfo -{ - university={\AcroTeX.Net}, - title={The \textsf{aeb\_mlink} Package\texorpdfstring{\\[1em]}{: }AeB Pro Family}, - author={D. P. Story}, - email={dpstory@acrotex.net}, - subject={Wrapping links around to the next line}, - keywords={multi-line links, quad points, latex, pdf, aeb}, - talksite={\url{www.acrotex.net}}, - version={2.3.5, 2020/01/06}, - copyrightStatus={True}, - copyrightNotice={Copyright (C) 2006-\the\year, D. P. Story}, - copyrightInfoURL={http://www.acrotex.net} -} -\nocopyright -\DeclareInitView{windowoptions=showtitle} - -\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}% - \kern-.6em \hbox{$\mathcal S$}}$} - - - -\def\AcroTeX{Acro\negthinspace\TeX} - -\def\unskipparskip{\vskip-\parskip} -\renewenvironment{sverbatim} -{\parskip0pt\noindent\small\verbatim}{\endverbatim\par\aftergroup\unskipparskip} -\renewenvironment{ssverbatim} -{\parskip0pt\noindent\footnotesize\verbatim}{\endverbatim\par\aftergroup\unskipparskip} - -\def\anglemeta#1{$\langle\textit{\texttt{#1}}\rangle$} -\let\ameta\anglemeta -\def\meta#1{\textit{\texttt{#1}}} -\def\darg#1{\texttt{\{#1\}}} -\def\takeMeasure{\bgroup\obeyspaces\takeMeasurei} -\def\takeMeasurei#1{\global\setbox\webtempboxi\hbox{\ttfamily#1}\egroup} -\def\bxSize{\wd\webtempboxi+2\fboxsep+2\fboxrule} -\let\pkg\textsf -\let\env\texttt -\let\opt\texttt -\let\app\textsf - -%\let\amtIndent\leftmargini -%\let\amtIndent\parindent -\def\SUB#1{${}_{\text{#1}}$} - -\newdimen\aebdimen \aebdimen 0pt %\advance\aebdimen\partopsep -\newcommand\bVerb[1][]{\begingroup#1\vskip\aebdimen\parindent0pt}% -\def\eVerb{\vskip\aebdimen\endgroup\noindent} - -\def\cmdtitle#1{\texorpdfstring{\protect\cs{#1}}{\textbackslash{#1}}} - -\renewcommand\hproportionwebauthor{.5} -\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}} - -\makeatletter -\def\cs#1{\texttt{\@backslashchar#1}} -\renewcommand{\paragraph} - {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\bfseries}} -\renewcommand{\subparagraph} - {\@startsection{subparagraph}{5}{15pt}{6pt}{-3pt}{\bfseries}} -\makeatother - -%\parindent0pt\parskip\medskipamount - - -%\definePath\bgPath{"C:/Users/Public/Documents/% -% ManualBGs/Manual_BG_Print_AeB.pdf"} -%\begin{docassembly} -%\addWatermarkFromFile({% -% bOnTop: false, -% cDIPath: \bgPath -%}) -%\executeSave() -%\end{docassembly} - -\chngDocObjectTo{\newDO}{doc} -\begin{docassembly} -var titleOfManual="The AeB mLink Manual"; -var manualfilename="Manual_BG_Print_mlink.pdf"; -var manualtemplate="Manual_BG_Blue.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} - -\reversemarginpar - -%\mlMarksOn - - -\begin{document} - -\maketitle - -\pdfbookmarkx[1]{Title Page}[action={\Named{FirstPage}}]{TitlePage} -\pdfbookmarkx[1]{Links to AcroTeX.Net}[action={/S/GoTo/D(undefined)},% - color=magenta,style={bf}]{acrotex} -\belowpdfbookmarkx{http://www.acrotex.net}[action={\URI{http://www.acrotex.net}},% - color=magenta,style={bf}]{home} -\belowpdfbookmarkx{http://blog.acrotex.net}[action={\URI{http://blog.acrotex.net}},% - color=magenta,style={bf}]{blog} - - -\selectColors{linkColor=black} - -\tableofcontents - -\selectColors{linkColor=webgreen} - -\section{Introduction} - -This package creates \underbar{m}ulti-line \underbar{link}s, a dream of mine -for a number of years. The package \pkg{hyperref} does create links, -but generally these links cannot be broken across lines, unless the -application \app{pdflatex} (or \app{xelatex}) is used to create a PDF; -however, since my workflow is primarily through \app{Acrobat Distiller}, this -does me little good. - -This package uses the \texttt{QuadPoints} entry of the link annotation -dictionary to create a bounding region; consequently, this package -requires\marginpar{\small\raggedright\flushright \app{Distiller} or -\app{ps2pdf} required} \app{Acrobat Distiller} or the \app{ps2pdf.exe} -converter to create a PDF. The \texttt{QuadPoints} entry in the link -annotation is a PDF 1.6 feature, so these multi-line links will work in -\app{Adobe Reader} 7.0 or later. If viewed in a version of \app{Adobe Reader} -previous to 7.0, the viewer will use the underlying bounding box, which is the -smallest rectangle containing the link text. - -\section{Alternate package name: \texorpdfstring{\protect\pkg{aeb-mlink}}{aeb-mlink}} - -This package is known on CTAN as \pkg{aeb-mlink} -(\href{http://www.ctan.org/pkg/aeb-mlink}{ctan.org/pkg/aeb-mlink}), even -though there is no such package by that name, until now. Included within this distrubution -is the `dummy' package \pkg{aeb-mlink} which loads \pkg{aeb\_mlink} and passes all options -to it. - -\section{Requirements} - -The following {\LaTeX} packages are the major ones required by \texttt{aeb\_mlink}. -\begin{itemize} - \item \pkg{eforms} provides form and link support, \`a la - {Acro\negthinspace\TeX} (\href{http://www.ctan.org/pkg/acrotex}{ctan.org/pkg/acrotex}). - \item \pkg{hyperref} provides link support, including the - commands \cs{hyperref}, \cs{hyperlink}, \cs{href}, \cs{nameref}, - \cs{Nameref}, and \cs{href}. - \item \pkg{soul} a very nice package by Melchior FRANZ, used by - \pkg{aeb\_mlink} to break the text of a link into its syllables (\href{http://www.ctan.org/pkg/soul}{ctan.org/pkg/soul}). -% \nolinkurl{CTAN: tex-archive/macros/latex/contrib/soul/}} - -\end{itemize} - -\section{Package options} - -There are only two package options---the name of the dvi-to-ps converter application to be used---, -these are \opt{dvips} and \opt{dvipsone}.\footnote{\app{dvipsone.exe} is the dvi-to-ps converter -of the Y\&Y {\TeX} System, no longer available, but is used by this author.} The default is \opt{dvips}. - -%\Hy@colorlinksfalse - -\bVerb[\aebdimen=6pt] -\begin{minipage}[t]{.5\linewidth} -\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!(),fontsize=\small] -\documentclass{article} -\usepackage{xcolor} -\usepackage[colorlinks]{hyperref} -\usepackage[!anglemeta(options)]{aeb_mlink} -\end{Verbatim} -\end{minipage}\quad\begin{minipage}[t]{.4\linewidth} -\begin{Verbatim}[commandchars=!(),fontsize=\small] -\documentclass{article} -\usepackage[designi]{web} -\usepackage[!anglemeta(options)]{aeb_mlink} -\end{Verbatim} -\end{minipage} -\eVerb Above are two typical preambles for the use of \pkg{aeb\_mlink}: -\begin{itemize} - \item The one on the left inputs \pkg{xcolor} (recommended) and - \pkg{hyperref} explicitly. The \opt{colorlinks} option is - recommended for \pkg{hyperref}. These two are followed by - \pkg{aeb\_mlink}. - \item The preamble representation on the right uses the \pkg{web} - package, which internally inputs both \pkg{xcolor} (if available) and - \pkg{hyperref} (with \opt{colorlinks} option). Again, \pkg{aeb\_mlink} - comes last. -\end{itemize} - -\paragraph*{Options of \pkg{aeb\_mlinks}.} The following are the options of this package. -\begin{description} - \item[\normalfont\texttt{dvips}] Use this option when the \textsf{dvips} application is used - to create the Postscript file. - \item[\normalfont\texttt{dvipsone}] Use this option when the \textsf{dvipsone} application is used - to create the Post\-script file. (Only a few people worldwide use this option.) - \item[\normalfont\texttt{dblevel=\ameta{\upshape{0|1|2}}}] To obtain information on the multi-line links being - created. Each value gives more information about what is going on. Used for development. - \item[\normalfont\texttt{urlOpts=\ameta{url-options}}] Use the key \opt{urlOpts} to pass options to the - \pkg{url} package; for example \opt{urlOpts=hyphens} enables URLs to be broken at hyphens. See the - \pkg{url} documentation for a list of options. - \item[\normalfont\ameta{eforms-options}] Any options other than the ones listed above are passed to the - \pkg{eforms} package. -\end{description} -Since \pkg{eforms} is a required package, the \pkg{acrotex} bundle -(\pkg{AeB}) is installed; consequently, if you've set up the \texttt{web.cfg} -configuration file (that accompanies \pkg{AeB}) with either -\cs{ExecuteOptions\darg{dvips}} or \cs{ExecuteOptions\darg{dvipsone}}, the -specification of the driver (\opt{dvips} or \opt{dvipsone}) is not normally -needed. - -\section{Multi-line link commands} - -We define seven multi-line hypertext link commands: \cs{mlhypertext}, -\cs{mlhyperlink}, \cs{mlhyperref}, \cs{mlnameref}, \cs{mlNameref}, -\cs{href}, and \cs{mlurl}. The first is a basic command that is used in the definitions of -the other six. - -%\newtopic\noindent\textbf{Note:} Because of the way the bounding boxes are -%constructed, it is best that the bounding rectangle is set on invisible, that -%is, the line width of the boundary line is zero. The \opt{colorlinks} option -%of \app{hyperref} should be taken. - -\exSrc{mlink_tst}The demo file is \texttt{mlink\_tst.tex}, it illustrates all -the commands -- with the exception of \cs{mlurl} -- of this package. The -demo file for \cs{mlurl} is a separate file and is mentioned in -\hyperref[ss:mlrul]{Section~\ref*{ss:mlrul}}. - -\subsection{\cmdtitle{mlhypertext} (\cmdtitle{mlsetLink})} A general purpose multi-line link command. - -\bVerb[\aebdimen=8pt]\takeMeasure{\string\mlhypertext[\#1]\darg{\#2}}% -\begin{minipage}{\bxSize} -\begin{Verbatim}[frame=single,rulecolor=\color{webblue}] -\mlhypertext[#1]{#2} -\end{Verbatim} -\end{minipage}\quad\takeMeasure{\string\mlsetLink[\#1]\darg{\#2}}% -\begin{minipage}{\bxSize} -\begin{Verbatim}[frame=single,rulecolor=\color{webblue}] -\mlsetLink[#1]{#2} -\end{Verbatim} -\end{minipage} -\endgroup - - -\PD The first parameter is optional, and is used to set the appearance and the actions of the link. -The second parameter is the text around which the link is constructed. - -\CmdDescription The \pkg{eforms} package defines \cs{mlsetLink} to -\cs{mlhypertext} (this is to conform to the naming conventions of -\pkg{eforms}). Either command sets a hypertext link having a default -appearance, and no action. The default appearance is the same as that of -\cs{hyperlink}, the command from \pkg{hyperref}. If \opt{colorlinks} -option was taken in the hyperref package, the text is colored \cs{@linkcolor} -(usually red); otherwise, the text is the default color at the time, and a -boundary rectangle is created by AcroForms with color \cs{@linkbordercolor} -(usually red).\footnote{The \pkg{web} package changes the default coloring of \pkg{hyperref}.} - -\newtopic -For example, the following link is constructed using -\cs{mlhypertext}: \mlhypertext[\A{\JS{app.alert("AcroTeX rocks!")}}]% -{Acrobat Distiller, version~7.0 or greater} was used to -create this PDF document. - -\bVerb\takeMeasure{\string\mlhypertext[\string\A\darg{\string\JS\darg{app.alert("AcroTeX rocks!")}}]\%}% -\begin{dCmd*}{\bxSize} -\mlhypertext[\A{\JS{app.alert("AcroTeX rocks!")}}]% - {Acrobat Distiller, version~7.0 or greater} -\end{dCmd*} -\eVerb In the above example, the link, shown in \textcolor{webgreen}{green} -is broken across lines. Though is not shown in this example, these links -can break a line at a hyphenation point as well. The optional argument is -used to create an alert box that appears when the link is clicked. - -\subsection{\cmdtitle{mlhyperlink}} A multi-line version of the \cs{hyperlink} command. - -\bVerb\takeMeasure{\string\mlhyperlink[\#1]\darg{\#2}\darg{\#3}}% -\begin{dCmd}{\bxSize} -\mlhyperlink[#1]{#2}{#3} -\end{dCmd} -\endgroup - -\PD The first parameter is optional, and is used to set the appearance, but \textit{not the actions} of the link. -The second parameter is a named destination, perhaps created by the \cs{hypertarget} command of -\pkg{hyperref}. The third parameter is the text around which the link is constructed. - -\CmdDescription This command is the multi-line version of the \pkg{hyperref} command \cs{hyperlink}. -The default appearance is the same as \cs{hyperlink}, as described above in \cs{mlhypertext}. -The action of this link is to jump to a named destination; the action cannot be changed by defining -a different action through the first parameter. - -This link uses the \cs{mlhyperlink} command: -\so{Welcome!} \mlhyperlink{retire}{Welcome, $\dots$ to my humble retirement residence, such as it is!} -\bVerb\takeMeasure{\string\mlhyperlink\darg{retire}\{Welcome, \$\string\dots\$ to my humble}% -\begin{dCmd*}{\bxSize} -\mlhyperlink{retire}{Welcome, $\dots$ to my humble -retirement residence, such as it is!} -\end{dCmd*} -\eVerb In this example, the line is broken at a hyphenation, cool! We jump to -the named destination, \texttt{retire}. On the last page, -the following text appears -\begin{quote} -\verb!My humble retirement \hypertarget{retire}{home}.! -\end{quote} -creating the named destination of \texttt{retire}. - -\subsection{\cmdtitle{mlhyperref}}\label{ss:mlhyperref} -A multi-line version of the \cs{hyperref} command. - -\bVerb\takeMeasure{\string\mlhyperref[\#1]\darg{\#2}\darg{\#3}}% -\begin{dCmd}{\bxSize} -\mlhyperref[#1]{#2}{#3} -\end{dCmd} -\endgroup -\PD The first parameter is optional, and is used to set the -appearance, but \textit{not the actions} of the link. The second -parameter is a label name created by the \cs{label} command of -\LaTeX. The third parameter is the text around which the link is -constructed. - -\CmdDescription This is the multi-line version of \cs{hyperref}, the command -defined by the \pkg{hyperref} package. The default appearance is the same -as \cs{hyperref}. The action of this link is to jump to a destination created -by the \cs{label} command of the cross-referencing system of \LaTeX; the -action cannot be changed by defining a different action through the first -parameter. - -\newtopic -This link uses the \cs{mlhyperref} command: \mlhyperref[\ui{linktxtcolor=red}]{retirement} -{Welcome! Welcome to my humble retirement residence, such as it is!} - -\bVerb\takeMeasure{\string\mlhyperref[\string\ui\darg{linktxtcolor=red}]\darg{retirement}}% -\begin{dCmd*}{\bxSize} -\mlhyperref[\ui{linktxtcolor=red}]{retirement} -{Welcome! Welcome to my humble retirement -residence, such as it is!} -\end{dCmd*} -\eVerb The user-friendly interface is used to change the appearance of the -color of the link text. The second argument is \texttt{retirement}, which is -the label -affixed to the last section of this document, -\begin{quote} -\verb!\section{My \textbf{Retirement} Home}\label{retirement}! -\end{quote} -See \mlNameref{retirement}. - - -\subsection{\cmdtitle{mlnameref}} A multi-line version of the \cs{nameref} command. - -\bVerb\takeMeasure{\string\mlnameref[\#1]\darg{\#2}}% -\begin{dCmd}{\bxSize} -\mlnameref[#1]{#2} -\end{dCmd} -\endgroup - -\PD The first parameter is optional, and is used to set the appearance, but - \textit{not the actions} of the link. The second parameter is a name of - a {\LaTeX} label. - -\CmdDescription This is the multi-line version of the -\pkg{hyperref} (\pkg{nameref}) command, \cs{nameref}. The default appearance is -the same as \cs{hyperref}. The action of this link is to jump to a -destination created by the \cs{label} command of the -cross-referencing system of \LaTeX; the action cannot be changed by -defining a different action through the first parameter. - -\newtopic -This link uses the \cs{mlnameref} command: Click the link to witness \mlnameref{retirement}. -The code for this link is seen below: -\bVerb\takeMeasure{\string\mlnameref\darg{retirement}}% -\begin{dCmd*}{\bxSize} -\mlnameref{retirement} -\end{dCmd*} -\endgroup - -\subsection{\cmdtitle{mlNameref}} A multi-line version of the -\pkg{hyperref} command, \cs{Nameref}. - -\bVerb\takeMeasure{\string\mlNameref[\#1]\darg{\#2}}% -\begin{dCmd}{\bxSize} -\mlNameref[#1]{#2} -\end{dCmd} -\endgroup -\PD The first parameter is optional, and is used to set the - appearance, but \textit{not the actions} of the link. The second - parameter is a name of a {\LaTeX} label. - -\CmdDescription This is the multi-line version of the \pkg{hyperref} -(\pkg{nameref}) command, \cs{Nameref}. The default appearance is the same as -\cs{hyperref}. The action of this link is to jump to a destination created by -the \cs{label} command of the cross-referencing system of \LaTeX; the action -cannot be changed by defining a different action through the first parameter. - -\newtopic -This link uses the \cs{mlNameref} command: Click the link or go to -the page, \mlNameref{retirement}. The code for the link is seen below: -\bVerb\takeMeasure{\string\mlNameref\darg{retirement}}% -\begin{dCmd*}{\bxSize} -\mlNameref{retirement} -\end{dCmd*} -\endgroup - -\subsection{\cmdtitle{mlhref}} A multi-line version of the -\pkg{hyperref} command, \cs{href}. -\bVerb\takeMeasure{\string\mlhref[\#1]\darg{\#2}\darg{\#3}}% -\begin{dCmd}{\bxSize} -\mlhref[#1]{#2}{#3} -\end{dCmd} -\endgroup - -\PD The first parameter is optional, and is used to set the - appearance, but \textit{not the actions} of the link. The - second parameter is a URL, while the third parameter is the link text. - -\CmdDescription This is the multi-line version of the -\pkg{hyperref} command, \cs{href}. The default appearance is -the same as \cs{hyperref}. There is one of three actions, depending on the -third argument, just as with \cs{href}. The action cannot be changed by -defining a different action through the first parameter. - -%\begingroup -%\makeatletter -%\def\Hy@temp#1{\expandafter\Hy@@temp\csname @#1color\endcsname{#1}} -%\Hy@temp{link}{red} -%\Hy@temp{anchor}{black} -%\Hy@temp{cite}{green} -%\Hy@temp{file}{cyan} -%\Hy@temp{url}{magenta} -%\Hy@temp{menu}{red} -%\makeatother - -\newtopic -The next link uses the \cs{mlhref} command with URL: \mlhref{% -http://www.math.uakron.edu/~dpstory/acrotex.html#educational} -{See the educational offerings of the {Acro\negthinspace{\TeX}} Web -Site at the University of Akron} -\bVerb\takeMeasure{\{See the educational offerings of the \darg{Acro\string\negthinspace\darg{\string\TeX}} Web}% -\begin{dCmd*}{\bxSize} -\mlhref{% -http://www.math.uakron.edu/~dpstory/acrotex.html#educational} -{See the educational offerings of the {Acro\negthinspace{\TeX}} Web -Site at the University of Akron} -\end{dCmd*} -\eVerb -Use the \cs{mlhref} command with mailto URL: My email address at Acro\negthinspace\TeX.Net, -\mlhref{mailto:dpstory@acrotex.net}{dpstory at acrotex dot net}. -\bVerb\takeMeasure{\string\mlhref\darg{mailto:dpstory@acrotex.net}\darg{dpstory at acrotex dot net}}% -\begin{dCmd*}{\bxSize} -\mlhref{mailto:dpstory@acrotex.net}{dpstory at acrotex dot net} -\end{dCmd*} -\eVerb -If the second argument is a PDF file, the PDF viewer will open it from your local file system, -or if you are in a browser, will open it from the web, provided it can find the relative path -\bVerb\takeMeasure{shameless advertisement for Acro\string\negthinspace\string\TeX\}.}% -\begin{dCmd*}{\bxSize} -\mlhref{shameless_ad.pdf}{Here is a -shameless advertisement for Acro\negthinspace\TeX}. -\end{dCmd*} -\eVerb If the key word `\texttt{run:}' is used, the link is set up to launch -an application. The PDF viewer will attempt to open the file with the -application associated with the extension of the file provided. -\bVerb\takeMeasure{\string\mlhref\darg{run:\string\jobname.tex}\darg{This is the source file of this document}.}% -\begin{dCmd*}{\bxSize} -\mlhref{run:\jobname.tex}{This is the source file of this document}. -\end{dCmd*} -\endgroup - -\subsection{\cmdtitle{mlurl}}\label{ss:mlrul} - -A multi-line version of the \cs{url} command of the \pkg{url} package. -The \pkg{hyperref} modifies this command to make it into an unbreakable link (at least for those -using \app{Distiller}). -\bVerb\takeMeasure{\string\mlurl[\#1]\darg{\#2}}% -\begin{dCmd}{\bxSize} -\mlurl[#1]{#2} -\end{dCmd} -\endgroup - -\PD The first parameter is optional, and is used to set the - appearance, but \textit{not the actions} of the link. The - second parameter is a URL, the text of the link is the same as the URL. - -\CmdDescription This is the multi-line version of the -\pkg{url}/\pkg{hyperref} command, \cs{hurl}. The default appearance is -the same as set by \cs{hyperref}. - -\newtopic -The next link is an example of \cs{mlurl}: -\mlurl{http://www.math.uakron.edu/~dpstory/acrotex.html#educational}. The code for this link is found below: -\bVerb\takeMeasure{\string\mlurl\darg{http://www.math.uakron.edu/\string~dpstory/acrotex.html\#educational}}% -\begin{dCmd*}{\bxSize} -\mlurl{http://www.math.uakron.edu/~dpstory/acrotex.html#educational} -\end{dCmd*} -\eVerb The \pkg{url} package typesets the URL in math mode, which makes it -very difficult to wrap it to the next line with a hypertext link around it. -In math mode, spaces are ignored; consequently, if the URL contains spaces, -use \verb!\%20! (with backslash), the URL encoding for the space character. -See the Internet reference -\mlurl{http://www.w3schools.com/tags/ref_urlencode.asp} for a discussion of -the \textbf{\caps{HTML URL Encoding Reference}}. - - -\exSrc{mlink_tst_url}The demo file that illustrate all the commands to -follow is \texttt{mlink\_tst\_url.tex}. Additional details and examples are found in this -example file. - -\section{Setting the appearance and action} - -The appearance and the action (at least for \cs{mlhypertex}) can be set through the first -optional parameter. The optional parameter takes key-value pairs of two types: -\paragraph*{Key-value Pairs.} The optional first parameter of each of the form and link commands take -two styles of key-values: -\begin{enumerate} - \item eForms KVP: This is the key-value system originally developed, where each KVP has the form - \cs{\anglemeta{key}\darg{\anglemeta{val}}}. Through these keys, the appearance - and action of a link---if otherwise not restricted---may be set. - For example, \mlhypertext[\S{U}\W{1}\Color{0 0.6 0} - \linktxtcolor{webgreen} \A{\JS{app.alert("AcroTeX - rocks!")}}]{AcroTeX can be found at - \texttt{www.acrotex.net}, as close as your nearest web - browser.} -\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] -\mlhypertext[\S{U}\W{1}\Color{0 0.6 0}\linktxtcolor{webgreen} -\A{\JS{app.alert("AcroTeX rocks!")}}]{AcroTeX...browser.} -\end{Verbatim} - - An alternative link format is to provide a visible rectangle; \mlhypertext[\W1\linktxtcolor{} - \Color{red}\A{\JS{app.alert("Wrap the link!")}}]{Use a link with a non-zero boundary size along - with {\protect\cs{S\string{S\string}}}, which is the default.} -\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] -\mlhypertext[\W1\linktxtcolor{}\Color{red} -\A{\JS{app.alert("Wrap the link!")}}]{Use a ... boundary size.} -\end{Verbatim} - - The eForms KVP system is explained in the eforms manual, - \textsl{\mlhref{http://www.math.uakron.edu/~dpstory/acrotex/eformman.pdf}{Support for AcroForms and Links, and for Document JavaScript and Open Page Events}},\footnote - {\url{http://www.math.uakron.edu/~dpstory/acrotex/eformman.pdf}} - where a complete listing of all supported KVPs is found in the appendices. - - - \item \pkg{xkeyval} KVP: When the \opt{useui} option is taken of the eforms package, key-value pairs are - defined of the form \texttt{\anglemeta{key}[\,=\,\anglemeta{value}]}. The key-value pairs are actually a value of - a special eForms key, \cs{ui}. The value of \cs{ui} consists of a comma-delimited list of - \pkg{xkeyval} key-value pairs. For example, - \mlsetLink[\ui{% - border=visible, - linestyle=underlined, - bordercolor={0 0.6 0}, - linktxtcolor=webgreen, - js={app.alert("AcroTeX rocks!")}}]{AcroTeX - can be found at \texttt{www.acrotex.net}, as - close as your nearest web browser.} -\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] -\mlsetLink[\ui{% - border=visible, - linestyle=underlined, - bordercolor={0 0.6 0}, - linktxtcolor=webgreen, - js={app.alert("AcroTeX rocks!")}}]{AcroTeX...browser.} -\end{Verbatim} - \item[] The \pkg{xkeyval} KVP system is described in the document - \textsl{\mlhref{http://www.math.uakron.edu/~dpstory/acrotex/eformman.pdf}{Support for AcroForms and Links, and for Document JavaScript and Open Page Events}}.\footnote - {ibid.} -\end{enumerate} - -\paragraph*{Keys special to the \pkg{aeb\_mlink} package.} The following links are defined -within \pkg{eforms}, but are only obeyed from within the option list of one of the -\cs{ml\ameta{cmdname}} commands. -\begin{itemize} -\item \cs{mlfix\darg{\ameta{\upshape{y|n}}}} (\pkg{xkeyval} KVP: \texttt{mlfix=\ameta{\upshape{yes|no}}})\\ - If \cs{mlfix\darg{y}} is specified, contiguous bounding rectangles are combined; otherwise they are not. - See Section~\ref{s:FixQuads} for more information. -\item \cs{mlstrut\darg{\ameta{some-strut}}} (\pkg{xkeyval} KVP: \texttt{mlstrut=\ameta{some-strut}})\\ - The value of this key sets the height of the bounding rectangles; the default is \cs{strut}. See - Section~\ref{s:FixQuads} for detains and examples. -\item \cs{mlcrackat\darg{\ameta{num}}} (\pkg{xkeyval} KVP: \texttt{mlcrackat=\ameta{num}})\\ - This key is use to crack (or break) an hypertext or url into two links. - The application is to enable the link to break across a page boundary. Refer - to the paragraph \textbf{\mlnameref{para:xpage}}, beginning on page~\pageref{para:xpage} - for more information on \cs{mlcrackat}. -\item \cs{mlhyph\darg{\ameta{\upshape{y|n}}}} (\pkg{xkeyval} KVP: \texttt{mlhyph=\ameta{\upshape{yes|no}}})\\ - When the \cs{mlcrackat} option is used, an hyphen is inserted provided \cs{mlhyph{y}}, otherwise, no hypen - is inserted. Refer to the paragraph \textbf{\mlnameref{spara:fixxpage}}, page~\pageref{spara:fixxpage}, for - an example. -\item \cs{mlcrackinsat\darg{\ameta{text}}} (\pkg{xkeyval} KVP: \texttt{mlcrackinsat=\ameta{text}})\\ - The value \ameta{text} of this key is inserted after the break point, when - \cs{mlcrackat} is used. Normally, nothing is inserted after the brake point. -\end{itemize} - -\section{Fixing the quad points}\label{s:FixQuads} - -In versions of \pkg{aeb\_mlink} prior to 2018/03/19, the each syllable -(possible break point) of multi-line text was enclosed in a bounding -rectangle (described by the coordinates of its four corners). For example, it -is well known that \mlhypertext[\A{\JS{app.alert("And so it -is");}}\mlfix{n}\linktxtcolor{}\W1\H{O}\S{S}\Color{red}]{the acrotex website -is free to all who dare to enter.} Now you see the individual bounding -rectangles; they are all linked together, if you click on one of them, they -all react. - -Beginning with the version of \pkg{aeb\_mlink} dated 2018/03/19, Postscript -code was introduced to fix up these bounding boxes so that all syllables -\emph{on the same line} are enclosed in a single bounding rectangle. -\mlhypertext[\A{\JS{app.alert("And so it is");}}\linktxtcolor{}\W1\H{O}\S{S}\Color{red}]{If we turn on this feature -and declare the acrotex website is free to all who dare to enter.} Very cool! - -\exAeBBlogPDF{p=1377} The demonstration document for these feature is found on the -\href{\urlAcroTeXBlog}{{\AcroTeX} Blog} web site. Refer to the article -titled \textsl{\href{\urlAcroTeXBlog?p=1377}{Fixing multi-line link boxes}}. - - -\paragraph*{Turning the fix on and off.} The feature of fixing up these -little rectangles into one rectangle per line is controlled by the commands -\cs{mlfixOn} and \cs{mlfixOff}; the first turns on the fix up, the second -turns it off. The default is \cs{mlfixOn}. These two commands turn on or off -the fix up for the document (or within a group), to turn the fix on or off -for an individual link, use the key-value pairs \verb~\mlfix{y}~ to turn on -the fix and \verb~\mlfix{n}~ to turn it off. These key-values are placed as -an optional argument of any of the \cs{ml\ameta{cmdname}} commands. For -example, -\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars={!@^}] -\mlhypertext[!textbf@\mlfix{n}^\A{\JS{app.alert("And so it is");}} -\linktxtcolor{}\W1\H{O}\S{S}\Color{red}]{the acrotex website is -free to all} -\end{Verbatim} -The user-friendly counterpart is \texttt{mlfix=\ameta{\upshape{yes|no}}}. - -\paragraph*{Changing the vertical size of the rectangles.} The default height -and depth of the boxes are determined by \cs{strut}, in the current font -size. A \emph{new key is introduced}, \cs{mlstrut\darg{\ameta{some-strut}}}. -You can simple increase the vertical dimensions of the boxes by -\verb~\mlstrut{\large\strut}~ or \verb~\mlstrut{\huge\strut}~. -\mlhypertext[\A{\JS{app.alert("And so it is");}}\mlstrut{\large\strut}\linktxtcolor{}\W1\H{O}\S{S}\Color{red}] -{The acrotex website is free to all} link should have vertically expanded rectangles. -\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars={!@^}] -\mlhypertext[!textbf@\mlstrut{\large\strut}^ -\A{\JS{app.alert("And so it is");}} -\linktxtcolor{}\W1\H{O}\S{S}\Color{red}]{The acrotex website -is free to all} -\end{Verbatim} -When the link is underlined (\verb~\S{U}~) the depth is set to 1bp. These -changes to the vertical size of the rectangles do not affect any text -positioning of the content, only the bounding boxes. - -\texttt{mlstrut=\ameta{some-strut}} is the counterpart to - \cs{mlstrut\darg{\ameta{some-strut}}} in the user-friendly key-value system. - -The \ameta{some-strut} argument can be anything that takes up vertical space, any horizontal space is ignored. -For example, \mlhypertext[\mlstrut{$\displaystyle\int_0^\pi$}\linktxtcolor{}\W1\H{O}\S{S}\Color{red} -\A{\JS{app.alert("No action defined, other than this one.")}}]{``The integral -{$\displaystyle\int_0^\pi \sin(x)\,dx$} has a value of a crummy little $2$.''} -\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] -\mlhypertext[\mlstrut{$\displaystyle\int_0^\pi$}\linktxtcolor{}\W1\H{O} -\S{S}\Color{red}]{``The integral {$\displaystyle\int_0^\pi \sin(x)\,dx$} -... $2$.''} -\end{Verbatim} - -\paragraph*{Important:} When the feature of fixing the -rectangles is active (with \cs{mlfixOn} or locally with \cs{mlfix\darg{y}}), -you need to \emph{compile the document at least three times} before -distilling the document; otherwise distiller fails. There are commands -written to the \textsf{AUX} file that needs to be up to date. This is only -needed after you modify any of the multi-line hypertext links. There are -{\LaTeX} warning messages written to the {\TeX} log to inform you if the -links are not fully formed; there are also messages in the distiller log. -Setting the package option \texttt{dblevel=1} can increase the amount of -feedback you get through the distiller log. - -\paragraph*{Marking the links.} You can run into trouble with one or more of the links. There -may be tex log or distiller log messages referring to the link number (e.g., -\texttt{mLink30}), but where is this link? By expanding \cs{mlMarksOn}, you -turn on the marking of the links. I'm turning on link marking for the rest of -the document. Look for `L\ameta{num}' beginning in section~\ref{ss:probs}. -Turn marking back off with \cs{mlMarksOff}. Above the starting point of each -link will be a tiny `L\ameta{num}'. The format for this little `L\ameta{num}' -is determined by the internal command \cs{ml@MrkLnk}; it may redefined as -desired. - - -\paragraph*{Viewing the syllable numbers.} You can display the syllable numbers of multi-line -hypertext by expanding \cs{turnSyllbCntOn}; \cs{turnSyllbCntOff} turns off this feature again. -For example, we expand \cs{turnSyllbCntOn} in a group: -\begin{quote} -\turnSyllbCntOn\mlhypertext{We have set {\cs{turnSyllbCntOn}} -in a group so the effects are not felt after the group}. -\end{quote} -\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] -\begin{quote}\turnSyllbCntOn -\mlhypertext{We have set {\cs{turnSyllbCntOn}} in a -group so the effects are not felt after the group}. -\end{quote} -\end{Verbatim} -The sentence has 10 syllables, as counted by \pkg{soul} and \pkg{aeb\_mlink}. It should be noted that -\cs{turnSyllbCntOn} also executes \cs{mlMarksOn}. This feature may be useful for determining where to -break a link across pages, see the next paragraph. - -Notice we've enclose \verb~\cs{turnSyllbCntOn}~ in braces, as a reault, \pkg{soul} treats the contents -as a single syllable. If we want to break this long command across a line (or page), we would have to register -the command \cs{cs} with \cs{soulregister}: -\begin{quote}\turnSyllbCntOn\soulregister{\cs}{1} -\mlhypertext[\A{\JS{app.alert("...and it was so")}}]{Register \cs{cs} with \cs{soulregister} to have the command name \cs{turnSyllbCntOn} -break across lines (or pages).} -\end{quote} -\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] -\begin{quote}\turnSyllbCntOn\soulregister{\cs}{1} % global declaration -\mlhypertext{Register \cs{cs} with \cs{soulregister} to have -the command name \cs{turnSyllbCntOn} break across lines (or pages).} -\end{quote} -\end{Verbatim} - - -\mlMarksOn - -\paragraph*{Multi-line links that break across pages.}\label{para:xpage} This phenomenon is not -supported by the PDF Reference. These kinds of links can be created by -{\LaTeX} when the link is near the bottom of the page and {\LaTeX} moves a -portion of it to the next page. \pkg{aeb\_mlinks} detects this when the -document is distilled and places a message in the distiller (or \app{ps2pdf}) log. If you have -a link that crosses page boundaries, you need to reword the paragraph to -avoid this. The message reads,\goodbreak -\begin{Verbatim}[fontsize=\small] -Beginning of page: 3 -!!------------------------------------------------------------------ -Warning: -The text of mLink4 has crossed a page boundary from page 2 to 3. -Cross page links are not supported by the PDF Specification. -This link is not constructed, please fix it. -Break point is after syllable number 4. -Use the \mlcrackat{4} option with this link. -!!------------------------------------------------------------------ -\end{Verbatim} -and can't be missed. The link is not constructed. You can see here, there is a reference -to \texttt{mLink4}. You need to turn on link marking (\cs{mlMarksOn}) or just go to page~2 -and look at the bottom of the page. - -\subparagraph*{Fixing a cross-page link.}\label{spara:fixxpage} There are a couple of action choices you can -take to fix a link that has crossed a page boundary: (1) rewrite the -paragraph so the link does not cross the page boundary; (2) manually break the link; (3) do as the log file suggests, you -can use the \cs{mlcrackat\darg{4}} option. In this latter case, for example, -\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] -\mlhypertext[\mlcrackat{4}\mlhyph{y}!ameta(other-opts)] - {Doctor Story created the acrotex website.} -\end{Verbatim} -\begin{quote}\turnSyllbCntOn\def\pb{\penalty-10 \\\rule[2pt]{\linewidth-\widthof{\ (page break)}}{.4pt}\ \makebox[0pt][l]{(page break)}\\[3pt]}% -\ameta{latex-content}\dotfill\mlhypertext[\mlcrackat{4}\mlhyph{y}\mlcrackinsat{\pb}] - {Doctor Story created the acrotex website.} -\end{quote} -Two links are created, the first consisting of the text `Doctor Story cre-' -and the second on `ated the acrotex website.'; the second link (should) be -inserted on the next page. The link option \cs{mlhyp\darg{y}} inserts a -hyphen at the break point; for URLs, a hyphen may not be appropriate. -\textbf{Question:} What is the missing \ameta{other-opts} in the above example? - -%\kern7pt - -\exAeBBlogPDF{p=1383}\textbf{ A working document:} The demonstration document -for breaking links across pages is found on the -\href{\urlAcroTeXBlog}{{\AcroTeX} Blog} web site. Please refer to the -article titled -\textsl{\mlhref{\urlAcroTeXBlog?p=1377}{Crossing page -boundaries with multi-line links}}. Many other articles on {\AEB} and {\PDF} -can be found at the \href{\urlAcroTeXBlog}{{\AcroTeX} Blog} web site, as -well. - -%\normalcolor - -\paragraph*{Reverting to the old style.} -The restriction of having to compile multiple times before -distillation may be a burden when it comes to developing a document. You can -declare \cs{OldStyleBoxesOn} in the preamble to revert to the old style that -does not use the information written to the auxiliary file. After document -development and the text of all links are stable, you can then say -\cs{OldStyleBoxesOff} (or comment out \cs{OldStyleBoxesOn}) in the preamble. -Compiling then yields the better formed and combined bounding rectangles. - -\paragraph*{Minimally sized \texttt{/Rect}.} For multi-line links, the link -annotation contains two entries containing dimensions of rectangles, the -\texttt{/Rect} and \texttt{/QuadPoints} entries. Our focus in this paragraph -is on \texttt{/Rect}; there are two possible values for \texttt{/Rect}: (1) -the dimensions of the entire page, which has been the default value since the -inception of this package, or (2) the dimensions of the smallest rectangle -containing all the hypertext, the new default.\smallskip - -\noindent\strut{\fboxsep0pt\fcolorbox{blue}{white}{\parbox{\linewidth} -{\hskip\amtIndent For example, the following link is constructed using -\cs{mlhypertext}: \mlhypertext[\A{\JS{app.alert("AcroTeX rocks with minimal rectangles!")}}]% -{Acrobat Distiller, version~7.0 or greater} was used to -create this PDF document. The blue rectangle}}} is a representation of the `unseen' \texttt{/Rect} -dimensions. It is the smallest rectangle that contains the hypertext. You can revert to the old -default (the whole page) by expanding \cs{useSmallRectOff}, the default is \cs{useSmallRectOn}.\medskip - -\textbf{The importance of small rectangles.} In the current age we live in, -web browsers have their own `native' PDF viewers. These viewers generally do -not obey JavaScript actions but they do recognize basic actions such as -jumping to the destination in the document; however, they ignore the -\texttt{/QuadPoints} entry in a link, and respect only the \texttt{/Rect} -entry. In a `native' viewer, following a multi-line link may be problem when -the \texttt{/Rect} entry is set the whole page. Now, the \texttt{/Rect} is -the minimal rectangle, and following a link should not be an issue as long as -\emph{one rectangle is not contained within another}. Multi-line links are -fully supported by \app{Adobe Acrobat Reader}. - -\paragraph*{Tricky bits.} The use of \cs{mlnameref} and \cs{mlNameref} can be tricky when -the referenced label contains special commands or font changes. Two tricks -are to enclose the bad bits in braces (\texttt{\darg{}}) and/or \cs{protect} -commands. Section or paragraph commands that end up as PDF bookmark need to use -the \pkg{hyperref} command \cs{texorpdfstring}. To illustrate, an dummy subsection -is introduced, and the discussion on this topic is continued there. - - -\subsection{Discussion of \texorpdfstring - {{\protect\cs{mlnameref}}, {\protect\cs{mlNameref}}, and {\protect\cs{mlhypertext}}} - {\textbackslash{mlnameref}, \textbackslash{mlNameref}, and \textbackslash{mlhypertext}}}\label{ss:probs} - -To illustrate, we reference the section title ``\mlnameref{ss:probs}.'' The verbatim listing of this subsection is -\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] -\subsection{Discussion of problems with \texorpdfstring - {{\protect\cs{mlnameref}}, {\protect\cs{mlNameref}}, - and {\protect\cs{mlhypertext}}} - {\textbackslash{mlnameref}, \textbackslash{mlNameref}, - and \textbackslash{mlhypertext}}}\label{ss:probs} -\end{Verbatim} -Observe the use of \cs{texorpdfstring}, the first argument is typeset, the second -one is placed in the bookmarks. -\begin{itemize} - \item On the first argument of \cs{texorpdfstring}, we focus our comments - on the first \verb~{\protect\cs{mlnameref}}~ of the three commands - referenced. Note that it is enclosed in braces that signals the - \opt{soul} package, which does the parsing, to treat it as an - unbreakable unit. The control sequence \cs{cs} is protected by - \cs{protect}. Finally \cs{cs} is a command that produces a backslash in - front of its argument in monospace font. - - There are two `common' definitions of \cs{cs}-style commands: - \begin{itemize} - \item \verb~\def\cs#1{\texttt{\char`\\#1}}~ - \item \verb~\def\cs#1{\texttt{\@backslashchar#1}}~ (used in this manual) - \end{itemize} - The latter definition must be the one used within a section title, not the first one. - - The \pkg{aeb\_mlinks} defines \cs{mlcs} using the second version; that - is \begin{flushleft}\hskip\amtIndent\verb~\def\mlcs#1{\texttt{\@backslashchar#1}}~\end{flushleft} is defined. In - this way both definitions for \cs{cs} are available. The \cs{mlcs} - version must be used in text that can be referenced by \mlcs{mlnameref} - or \mlcs{mlNameref}. -\end{itemize} -In the above title declaration, if any of the components (the braces, the \cs{protect}, and the special -definition of \cs{cs}) {\LaTeX} compilation errors occur. - -Similar comments are made for \cs{mlhypertext}, \cs{mlhyperref}, and \cs{mlhyperlink}. These three take -a text phrase as its `hypertext' string. For example, -``\mlhyperref[\linktxtcolor{}\Color{red}\S{S}\W1]{ss:mlhyperref}{The exciting world of {\protect\mlcs{mlhyperref}} is average wonderful.}'' -\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] -\mlhyperref[\linktxtcolor{}\Color{red}\S{S}\W1]{ss:mlhyperref}{The - exciting world of {\protect\mlcs{mlhyperref}} is average wonderful.} -\end{Verbatim} -Notice the braces, the \cs{protect}, and the use of \cs{mlcs}; they work -together for a successful link construction. - -\newpage - -\section{My \textbf{Retirement} Home}\label{retirement} - -My humble retirement \hypertarget{retire}{home}. -\begin{flushleft} -\setLink[\H{N}\A{\Named{GoBack}}]{\includegraphics[scale=.5]{DSC01404}}\quad \raisebox{75pt}{\textbf{Click image to return from jump}} -\end{flushleft} - - -\newtopic\noindent -Now, I simply must get back to my retirement. \dps - -\end{document} - -\def\mlMaxNSylls{30} diff --git a/macros/latex/contrib/aeb_mlink/docs/aeb_mlink.pdf b/macros/latex/contrib/aeb_mlink/docs/aeb_mlink.pdf new file mode 100644 index 0000000000..378738d3ea Binary files /dev/null and b/macros/latex/contrib/aeb_mlink/docs/aeb_mlink.pdf differ diff --git a/macros/latex/contrib/aeb_mlink/docs/aebmlink_man.pdf b/macros/latex/contrib/aeb_mlink/docs/aebmlink_man.pdf new file mode 100644 index 0000000000..069d9bb66e Binary files /dev/null and b/macros/latex/contrib/aeb_mlink/docs/aebmlink_man.pdf differ diff --git a/macros/latex/contrib/aeb_mlink/docs/aebmlink_man.tex b/macros/latex/contrib/aeb_mlink/docs/aebmlink_man.tex new file mode 100644 index 0000000000..eab753c4b8 --- /dev/null +++ b/macros/latex/contrib/aeb_mlink/docs/aebmlink_man.tex @@ -0,0 +1,943 @@ +% makeindex < aebpro_man.idx > aebpro_man.ind +\documentclass{article} +%\usepackage[fleqn]{amsmath} +\usepackage[ + web={centertitlepage,designv,forcolorpaper, + tight*,latextoc,pro,usetemplates}, + eforms={useui}, + aebxmp +]{aeb_pro} +\usepackage[dblevel=1]{aeb_mlink} + +%\usepackage{myriadpro} +\usepackage[altbullet]{lucidbry} +\usepackage{xbmks} + +\DeclareInitView{layoutmag={navitab:UseOutlines}} +\xbmksetup{colors={int=red},styles={intbf}} + + +\usepackage{acroman} + +%\def\amtIndent{15pt} +\edef\amtIndent{\the\parindent} + +\usepackage[active]{srcltx} + +\DeclareDocInfo +{ + university={\AcroTeX.Net}, + title={The \textsf{aeb\_mlink} Package\texorpdfstring{\\[1em]}{: }AeB Pro Family}, + author={D. P. Story}, + email={dpstory@acrotex.net}, + subject={Wrapping links around to the next line}, + keywords={multi-line links, quad points, latex, pdf, aeb}, + talksite={\url{www.acrotex.net}}, + version={2.3.6, 2020/07/12}, + copyrightStatus={True}, + copyrightNotice={Copyright (C) 2006-\the\year, D. P. Story}, + copyrightInfoURL={http://www.acrotex.net} +} +\nocopyright +\DeclareInitView{windowoptions=showtitle} + +\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}% + \kern-.6em \hbox{$\mathcal S$}}$} + + + +\def\AcroTeX{Acro\negthinspace\TeX} + +\def\unskipparskip{\vskip-\parskip} +\renewenvironment{sverbatim} +{\parskip0pt\noindent\small\verbatim}{\endverbatim\par\aftergroup\unskipparskip} +\renewenvironment{ssverbatim} +{\parskip0pt\noindent\footnotesize\verbatim}{\endverbatim\par\aftergroup\unskipparskip} + +\def\anglemeta#1{$\langle\textit{\texttt{#1}}\rangle$} +\let\ameta\anglemeta +\def\meta#1{\textit{\texttt{#1}}} +\def\darg#1{\texttt{\{#1\}}} +\def\takeMeasure{\bgroup\obeyspaces\takeMeasurei} +\def\takeMeasurei#1{\global\setbox\webtempboxi\hbox{\ttfamily#1}\egroup} +\def\bxSize{\wd\webtempboxi+2\fboxsep+2\fboxrule} +\let\pkg\textsf +\let\env\texttt +\let\opt\texttt +\let\app\textsf + +%\let\amtIndent\leftmargini +%\let\amtIndent\parindent +\def\SUB#1{${}_{\text{#1}}$} + +\newdimen\aebdimen \aebdimen 0pt %\advance\aebdimen\partopsep +\newcommand\bVerb[1][]{\begingroup#1\vskip\aebdimen\parindent0pt}% +\def\eVerb{\vskip\aebdimen\endgroup\noindent} + +\def\cmdtitle#1{\texorpdfstring{\protect\cs{#1}}{\textbackslash{#1}}} + +\renewcommand\hproportionwebauthor{.5} +\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}} + +\makeatletter +\def\cs#1{\texttt{\@backslashchar#1}} +\renewcommand{\paragraph} + {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\bfseries}} +\renewcommand{\subparagraph} + {\@startsection{subparagraph}{5}{15pt}{6pt}{-3pt}{\bfseries}} +\makeatother + +%\parindent0pt\parskip\medskipamount + + +%\definePath\bgPath{"C:/Users/Public/Documents/% +% ManualBGs/Manual_BG_Print_AeB.pdf"} +%\begin{docassembly} +%\addWatermarkFromFile({% +% bOnTop: false, +% cDIPath: \bgPath +%}) +%\executeSave() +%\end{docassembly} + +\chngDocObjectTo{\newDO}{doc} +\begin{docassembly} +var titleOfManual="The AeB mLink Manual"; +var manualfilename="Manual_BG_Print_mlink.pdf"; +var manualtemplate="Manual_BG_Blue.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} + +\reversemarginpar + +%\mlMarksOn + + +\begin{document} + +\maketitle + +\pdfbookmarkx[1]{Title Page}[action={\Named{FirstPage}}]{TitlePage} +\pdfbookmarkx[1]{Links to AcroTeX.Net}[action={/S/GoTo/D(undefined)},% + color=magenta,style={bf}]{acrotex} +\belowpdfbookmarkx{http://www.acrotex.net}[action={\URI{http://www.acrotex.net}},% + color=magenta,style={bf}]{home} +\belowpdfbookmarkx{http://blog.acrotex.net}[action={\URI{http://blog.acrotex.net}},% + color=magenta,style={bf}]{blog} + + +\selectColors{linkColor=black} + +\tableofcontents + +\selectColors{linkColor=webgreen} + +\section{Introduction} + +This package creates \underbar{m}ulti-line \underbar{link}s, a dream of mine +for a number of years. The package \pkg{hyperref} does create links, +but generally these links cannot be broken across lines, unless the +application \app{pdflatex} (or \app{xelatex}) is used to create a PDF; +however, since my workflow is primarily through \app{Acrobat Distiller}, this +does me little good. + +This package uses the \texttt{QuadPoints} entry of the link annotation +dictionary to create a bounding region; consequently, this package +requires\marginpar{\small\raggedright\flushright \app{Distiller} or +\app{ps2pdf} required} \app{Acrobat Distiller} or the \app{ps2pdf} +converter to create a PDF. The \texttt{QuadPoints} entry in the link +annotation is a PDF 1.6 feature, so these multi-line links will work in +\app{Adobe Reader} 7.0 or later. If viewed in a version of \app{Adobe Reader} +previous to 7.0, the viewer will use the underlying bounding box, which is the +smallest rectangle containing the link text. + +\newtopic\noindent +Version 2.3.6 (dated 2020/07/12 or later) now allows an \pkg{aeb\_mlink} +document to be compiled by \app{pdflatex}, \app{lualatex}, and \app{xelatex} +without errors; however, all commands defined in the package do nothing other +then to display their \ameta{text} with no links created. This makes it nice +for the lovers of these drivers to compile the document with their favorite +driver and view the PDF in their favorite PDF previewer, such as +\app{SumatraPDF}. Later, the document author can switch over to a +\app{latex\,->\,dvips\,->\ameta{\upshape{distiler\string|ps2pdf}}} workflow +to acquire the multi-line link version. + +\section{Alternate package name: \texorpdfstring{\protect\pkg{aeb-mlink}}{aeb-mlink}} + +This package is known on CTAN as \pkg{aeb-mlink} +(\href{http://www.ctan.org/pkg/aeb-mlink}{ctan.org/pkg/aeb-mlink}), even +though there is no such package by that name, until now. Included within this distrubution +is the `dummy' package \pkg{aeb-mlink} which loads \pkg{aeb\_mlink} and passes all options +to it. + +\section{Requirements} + +The following {\LaTeX} packages are the major ones required by \texttt{aeb\_mlink}. +\begin{itemize} + \item \pkg{eforms} provides form and link support, \`a la + {Acro\negthinspace\TeX} (\href{http://www.ctan.org/pkg/acrotex}{ctan.org/pkg/acrotex}). + \item \pkg{hyperref} provides link support, including the + commands \cs{hyperref}, \cs{hyperlink}, \cs{href}, \cs{nameref}, + \cs{Nameref}, and \cs{href}. + \item \pkg{soul} a very nice package by Melchior FRANZ, used by + \pkg{aeb\_mlink} to break the text of a link into its syllables (\href{http://www.ctan.org/pkg/soul}{ctan.org/pkg/soul}). +% \nolinkurl{CTAN: tex-archive/macros/latex/contrib/soul/}} + +\end{itemize} + +\section{Package options} + +There are only two package options---the name of the dvi-to-ps converter application to be used---, +these are \opt{dvips} and \opt{dvipsone}.\footnote{\app{dvipsone.exe} is the dvi-to-ps converter +of the Y\&Y {\TeX} System, no longer available, but is used by this author.} The default is \opt{dvips}. + +%\Hy@colorlinksfalse + +\bVerb[\aebdimen=6pt] +\begin{minipage}[t]{.5\linewidth} +\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!(),fontsize=\small] +\documentclass{article} +\usepackage{xcolor} +\usepackage[colorlinks]{hyperref} +\usepackage[!anglemeta(options)]{aeb_mlink} +\end{Verbatim} +\end{minipage}\quad\begin{minipage}[t]{.4\linewidth} +\begin{Verbatim}[commandchars=!(),fontsize=\small] +\documentclass{article} +\usepackage[designi]{web} +\usepackage[!anglemeta(options)]{aeb_mlink} +\end{Verbatim} +\end{minipage} +\eVerb Above are two typical preambles for the use of \pkg{aeb\_mlink}: +\begin{itemize} + \item The one on the left inputs \pkg{xcolor} (recommended) and + \pkg{hyperref} explicitly. The \opt{colorlinks} option is + recommended for \pkg{hyperref}. These two are followed by + \pkg{aeb\_mlink}. + \item The preamble representation on the right uses the \pkg{web} + package, which internally inputs both \pkg{xcolor} (if available) and + \pkg{hyperref} (with \opt{colorlinks} option). Again, \pkg{aeb\_mlink} + comes last. +\end{itemize} + +\paragraph*{Options of \pkg{aeb\_mlinks}.} These are, +\begin{description} + \item[\normalfont\texttt{dvips}] Use this option when the \textsf{dvips} application is used + to create the Postscript file. + \item[\normalfont\texttt{dvipsone}] Use this option when the \textsf{dvipsone} application is used + to create the Post\-script file. (Only a few people worldwide use this option, it could be as small as two.) + \item[\normalfont\texttt{dblevel=\ameta{\upshape{0|1|2}}}] To obtain information on the multi-line links being + created. Each value gives more information about what is going on. Used for development. + \item[\normalfont\ameta{eforms-options}] Any options other than the ones listed above are passed to the + \pkg{eforms} package. +\end{description} +Since \pkg{eforms} is a required package, the \pkg{acrotex} bundle +(\pkg{AeB}) is installed; consequently, if you've set up the \texttt{web.cfg} +configuration file (that accompanies \pkg{AeB}) with either +\cs{ExecuteOptions\darg{dvips}} or \cs{ExecuteOptions\darg{dvipsone}}, the +specification of the driver (\opt{dvips} or \opt{dvipsone}) is not normally +needed. + +\section{Multi-line link commands} + +We define seven multi-line hypertext link commands: \cs{mlhypertext}, +\cs{mlhyperlink}, \cs{mlhyperref}, \cs{mlnameref}, \cs{mlNameref}, +\cs{href}, and \cs{mlurl}. The first is a basic command that is used in the definitions of +the other six. + +%\newtopic\noindent\textbf{Note:} Because of the way the bounding boxes are +%constructed, it is best that the bounding rectangle is set on invisible, that +%is, the line width of the boundary line is zero. The \opt{colorlinks} option +%of \app{hyperref} should be taken. +%\exSrc{mlink_tst} + +The demo file is \texttt{mlink\_tst.tex}, it illustrates all +the commands -- with the exception of \cs{mlurl} -- of this package. The +demo file for \cs{mlurl} is a separate file and is mentioned in +\hyperref[ss:mlrul]{Section~\ref*{ss:mlrul}}. + +\subsection{\cmdtitle{mlhypertext} (\cmdtitle{mlsetLink})} A general purpose multi-line link command. + +\bVerb[\aebdimen=8pt]\takeMeasure{\string\mlhypertext[\ameta{opts}]\darg{\ameta{text}}}% +\begin{minipage}{\bxSize} +\begin{Verbatim}[frame=single,rulecolor=\color{webblue},commandchars=!()] +\mlhypertext[!ameta(opts)]{!ameta(text)} +\end{Verbatim} +\end{minipage}\quad\takeMeasure{\string\mlsetLink[\ameta{opts}]\darg{\ameta{text}}}% +\begin{minipage}{\bxSize} +\begin{Verbatim}[frame=single,rulecolor=\color{webblue},commandchars=!()] +\mlsetLink[!ameta(opts)]{!ameta(text)} +\end{Verbatim} +\end{minipage} +\endgroup + + +\PD The first parameter is optional, and is used to set the appearance and the actions of the link. +The second parameter is the text around which the link is constructed. + +\CmdDescription The \pkg{eforms} package defines \cs{mlsetLink} to +\cs{mlhypertext} (this is to conform to the naming conventions of +\pkg{eforms}). Either command sets a hypertext link having a default +appearance, and no action. The default appearance is the same as that of +\cs{hyperlink}, the command from \pkg{hyperref}. If \opt{colorlinks} +option was taken in the hyperref package, the text is colored \cs{@linkcolor} +(usually red); otherwise, the text is the default color at the time, and a +boundary rectangle is created by AcroForms with color \cs{@linkbordercolor} +(usually red).\footnote{The \pkg{web} package changes the default coloring of \pkg{hyperref}.} + +\newtopic +For example, the following link is constructed using +\cs{mlhypertext}: \mlhypertext[\A{\JS{app.alert("AcroTeX rocks!")}}]% +{Acrobat Distiller, version~7.0 or greater} was used to +create this PDF document. + +\bVerb\takeMeasure{\string\mlhypertext[\string\A\darg{\string\JS\darg{app.alert("AcroTeX rocks!")}}]\%}% +\begin{dCmd*}{\bxSize} +\mlhypertext[\A{\JS{app.alert("AcroTeX rocks!")}}]% + {Acrobat Distiller, version~7.0 or greater} +\end{dCmd*} +\eVerb In the above example, the link, shown in \textcolor{webgreen}{green} +is broken across lines. Though is not shown in this example, these links +can break a line at a hyphenation point as well. The optional argument is +used to create an alert box that appears when the link is clicked. + +\subsection{\cmdtitle{mlhyperlink}} A multi-line version of the \cs{hyperlink} command. + +\bVerb\takeMeasure{\string\mlhyperlink[\ameta{opts}]\darg{\ameta{named-dest}}\darg{\ameta{text}}}% +\begin{dCmd}[commandchars=!()]{\bxSize} +\mlhyperlink[!ameta(opts)]{!ameta(named-dest)}{!ameta(text)} +\end{dCmd} +\endgroup + +%[\ameta{opts}]\darg{\ameta{named-dest}}\darg{\ameta{text} +%[!ameta(opts)]{!ameta(text)}[\ameta{opts}]\darg{\ameta{text}} + +\PD The first parameter is optional, and is used to set the appearance, but \textit{not the actions} of the link. +The second parameter is a named destination, perhaps created by the \cs{hypertarget} command of +\pkg{hyperref}. The third parameter is the text around which the link is constructed. + +\CmdDescription This command is the multi-line version of the \pkg{hyperref} command \cs{hyperlink}. +The default appearance is the same as \cs{hyperlink}, as described above in \cs{mlhypertext}. +The action of this link is to jump to a named destination; the action cannot be changed by defining +a different action through the first parameter. + +This link uses the \cs{mlhyperlink} command: +\so{Welcome!} \mlhyperlink{retire}{Welcome, $\dots$ to my humble retirement residence, such as it is!} +\bVerb\takeMeasure{\string\mlhyperlink\darg{retire}\{Welcome, \$\string\dots\$ to my humble}% +\begin{dCmd*}{\bxSize} +\mlhyperlink{retire}{Welcome, $\dots$ to my humble +retirement residence, such as it is!} +\end{dCmd*} +\eVerb In this example, the line is broken at a hyphenation, cool! We jump to +the named destination, \texttt{retire}. On the last page, +the following text appears +\begin{quote} +\verb!My humble retirement \hypertarget{retire}{home}.! +\end{quote} +creating the named destination of \texttt{retire}. + +\subsection{\cmdtitle{mlhyperref}}\label{ss:mlhyperref} +A multi-line version of the \cs{hyperref} command. + +\bVerb\takeMeasure{\string\mlhyperref[\ameta{opts}]\darg{\ameta{label}}\darg{\ameta{text}}}% +\begin{dCmd}[commandchars=!()]{\bxSize} +\mlhyperref[!ameta(opts)]{!ameta(label)}{!ameta(text)} +\end{dCmd} +\endgroup +\PD The first parameter is optional, and is used to set the +appearance, but \textit{not the actions} of the link. The second +parameter is a label name created by the \cs{label} command of +\LaTeX. The third parameter is the text around which the link is +constructed. + +\CmdDescription This is the multi-line version of \cs{hyperref}, the command +defined by the \pkg{hyperref} package. The default appearance is the same +as \cs{hyperref}. The action of this link is to jump to a destination created +by the \cs{label} command of the cross-referencing system of \LaTeX; the +action cannot be changed by defining a different action through the first +parameter. + +\newtopic +This link uses the \cs{mlhyperref} command: \mlhyperref[\ui{linktxtcolor=red}]{retirement} +{Welcome! Welcome to my humble retirement residence, such as it is!} + +\bVerb\takeMeasure{\string\mlhyperref[\string\ui\darg{linktxtcolor=red}]\darg{retirement}}% +\begin{dCmd*}{\bxSize} +\mlhyperref[\ui{linktxtcolor=red}]{retirement} +{Welcome! Welcome to my humble retirement +residence, such as it is!} +\end{dCmd*} +\eVerb The user-friendly interface is used to change the appearance of the +color of the link text. The second argument is \texttt{retirement}, which is +the label +affixed to the last section of this document, +\begin{quote} +\verb!\section{My \textbf{Retirement} Home}\label{retirement}! +\end{quote} +See \mlNameref{retirement}. + + +\subsection{\cmdtitle{mlnameref}} A multi-line version of the \cs{nameref} command. + +\bVerb\takeMeasure{\string\mlnameref[\ameta{opts}]\darg{\ameta{label}}}% +\begin{dCmd}[commandchars=!()]{\bxSize} +\mlnameref[!ameta(opts)]{!ameta(label)} +\end{dCmd} +\endgroup + +\PD The first parameter is optional, and is used to set the appearance, but + \textit{not the actions} of the link. The second parameter is a name of + a {\LaTeX} label. + +\CmdDescription This is the multi-line version of the +\pkg{hyperref} (\pkg{nameref}) command, \cs{nameref}. The default appearance is +the same as \cs{hyperref}. The action of this link is to jump to a +destination created by the \cs{label} command of the +cross-referencing system of \LaTeX; the action cannot be changed by +defining a different action through the first parameter. + +\newtopic +This link uses the \cs{mlnameref} command: Click the link to witness \mlnameref{retirement}. +The code for this link is seen below: +\bVerb\takeMeasure{\string\mlnameref\darg{retirement}}% +\begin{dCmd*}{\bxSize} +\mlnameref{retirement} +\end{dCmd*} +\endgroup + +\subsection{\cmdtitle{mlNameref}} A multi-line version of the +\pkg{hyperref} command, \cs{Nameref}. + +\bVerb\takeMeasure{\string\mlNameref[\ameta{opts}]\darg{\ameta{label}}}% +\begin{dCmd}[commandchars=!()]{\bxSize} +\mlNameref[!ameta(opts)]{!ameta(label)} +\end{dCmd} +\endgroup +\PD The first parameter is optional, and is used to set the + appearance, but \textit{not the actions} of the link. The second + parameter is a name of a {\LaTeX} label. + +\CmdDescription This is the multi-line version of the \pkg{hyperref} +(\pkg{nameref}) command, \cs{Nameref}. The default appearance is the same as +\cs{hyperref}. The action of this link is to jump to a destination created by +the \cs{label} command of the cross-referencing system of \LaTeX; the action +cannot be changed by defining a different action through the first parameter. + +\newtopic +This link uses the \cs{mlNameref} command: Click the link or go to +the page, \mlNameref{retirement}. The code for the link is seen below: +\bVerb\takeMeasure{\string\mlNameref\darg{retirement}}% +\begin{dCmd*}{\bxSize} +\mlNameref{retirement} +\end{dCmd*} +\endgroup + +\subsection{\cmdtitle{mlhref}} A multi-line version of the +\pkg{hyperref} command, \cs{href}. +\bVerb\takeMeasure{\string\mlhref[\ameta{opts}]\darg{\ameta{url}}\darg{\ameta{text}}}% +\begin{dCmd}[commandchars=!()]{\bxSize} +\mlhref[!ameta(opts)]{!ameta(url)}{!ameta(text)} +\end{dCmd} +\endgroup + +\PD The first parameter is optional, and is used to set the + appearance, but \textit{not the actions} of the link. The + second parameter is an URL, while the third parameter is the link text. + +\CmdDescription This is the multi-line version of the +\pkg{hyperref} command, \cs{href}. The default appearance is +the same as \cs{hyperref}. There is one of three actions, depending on the +third argument, just as with \cs{href}. The action cannot be changed by +defining a different action through the first parameter. + +%\begingroup +%\makeatletter +%\def\Hy@temp#1{\expandafter\Hy@@temp\csname @#1color\endcsname{#1}} +%\Hy@temp{link}{red} +%\Hy@temp{anchor}{black} +%\Hy@temp{cite}{green} +%\Hy@temp{file}{cyan} +%\Hy@temp{url}{magenta} +%\Hy@temp{menu}{red} +%\makeatother + +\newtopic +The next link uses the \cs{mlhref} command with URL: \mlhref{% +http://www.math.uakron.edu/~dpstory/acrotex.html#educational} +{See the educational offerings of the {Acro\negthinspace{\TeX}} Web +Site at the University of Akron}. +\bVerb\takeMeasure{\{See the educational offerings of the \darg{Acro\string\negthinspace\darg{\string\TeX}} Web}% +\begin{dCmd*}{\bxSize} +\mlhref{% +http://www.math.uakron.edu/~dpstory/acrotex.html#educational} +{See the educational offerings of the {Acro\negthinspace{\TeX}} Web +Site at the University of Akron}. +\end{dCmd*} +\eVerb +Use the \cs{mlhref} command with mailto URL: My email address at Acro\negthinspace\TeX.Net, +\mlhref{mailto:dpstory@acrotex.net}{dpstory at acrotex dot net}. +\bVerb\takeMeasure{\string\mlhref\darg{mailto:dpstory@acrotex.net}\darg{dpstory at acrotex dot net}}% +\begin{dCmd*}{\bxSize} +\mlhref{mailto:dpstory@acrotex.net}{dpstory at acrotex dot net} +\end{dCmd*} +\eVerb +If the second argument is a PDF file, the PDF viewer will open it from your local file system, +or if you are in a browser, will open it from the web, provided it can find the relative path +\bVerb\takeMeasure{shameless advertisement for Acro\string\negthinspace\string\TeX\}.}% +\begin{dCmd*}{\bxSize} +\mlhref{shameless_ad.pdf}{Here is a +shameless advertisement for Acro\negthinspace\TeX}. +\end{dCmd*} +\eVerb If the key word `\texttt{run:}' is used, the link is set up to launch +an application. The PDF viewer will attempt to open the file with the +application associated with the extension of the file provided. +\bVerb\takeMeasure{\string\mlhref\darg{run:\string\jobname.tex}\darg{This is the source file of this document}.}% +\begin{dCmd*}{\bxSize} +\mlhref{run:\jobname.tex}{This is the source file of this document}. +\end{dCmd*} +\endgroup + +\subsection{\cmdtitle{mlurl}}\label{ss:mlrul} + +A multi-line version of the \cs{url} command of the \pkg{url} package. +The \pkg{hyperref} modifies this command to make it into an unbreakable link (at least for those +using \app{Distiller}). +\bVerb\takeMeasure{\string\mlurl[\ameta{opts}]\darg{\ameta{url}}}% +\begin{dCmd}[commandchars=!()]{\bxSize} +\mlurl[!ameta(opts)]{!ameta(url)} +\end{dCmd} +\endgroup + +\PD The first parameter is optional, and is used to set the + appearance, but \textit{not the actions} of the link. The + second parameter is a URL, the text of the link is the same as the URL. + +\CmdDescription This is the multi-line version of the +\pkg{url}/\pkg{hyperref} command, \cs{hurl}. The default appearance is +the same as set by \cs{hyperref}. + +\newtopic +The next link is an example of \cs{mlurl}: +\mlurl{http://www.math.uakron.edu/~dpstory/acrotex.html#educational}. The code for this link is found below: +\bVerb\takeMeasure{\string\mlurl\darg{http://www.math.uakron.edu/\string~dpstory/acrotex.html\#educational}}% +\begin{dCmd*}{\bxSize} +\mlurl{http://www.math.uakron.edu/~dpstory/acrotex.html#educational} +\end{dCmd*} +\eVerb The \pkg{url} package typesets the URL in math mode, which makes it +very difficult to wrap it to the next line with a hypertext link around it. +In math mode, spaces are ignored; consequently, if the URL contains spaces, +use \verb!\%20! (with backslash), the URL encoding for the space character. +See the Internet reference +\mlurl{http://www.w3schools.com/tags/ref_urlencode.asp} for a discussion of +the \textbf{\caps{HTML URL Encoding Reference}}. + +% \exSrc{mlink_tst_url} + +The demo file that illustrate all the commands to +follow is \texttt{mlink\_tst\_url.tex}. Additional details and examples are found in this +example file. + +\section{Setting the appearance and action} + +The appearance and the action (at least for \cs{mlhypertex}) can be set through the first +optional parameter. The optional parameter takes key-value pairs of two types: +\paragraph*{Key-value Pairs.} The optional first parameter of each of the form and link commands take +two styles of key-values: +\begin{enumerate} + \item eForms KVP: This is the key-value system originally developed, where each KVP has the form + \cs{\anglemeta{key}\darg{\anglemeta{val}}}. Through these keys, the appearance + and action of a link---if otherwise not restricted---may be set. + For example, \mlhypertext[\S{U}\W{1}\Color{0 0.6 0} + \linktxtcolor{webgreen} \A{\JS{app.alert("AcroTeX + rocks!")}}]{AcroTeX can be found at + \texttt{www.acrotex.net}, as close as your nearest web + browser.} +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] +\mlhypertext[\S{U}\W{1}\Color{0 0.6 0}\linktxtcolor{webgreen} +\A{\JS{app.alert("AcroTeX rocks!")}}]{AcroTeX...browser.} +\end{Verbatim} + + An alternative link format is to provide a visible rectangle; \mlhypertext[\W1\linktxtcolor{} + \Color{red}\A{\JS{app.alert("Wrap the link!")}}]{Use a link with a non-zero boundary size along + with {\protect\cs{S\string{S\string}}}, which is the default.} +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] +\mlhypertext[\W1\linktxtcolor{}\Color{red} +\A{\JS{app.alert("Wrap the link!")}}]{Use a ... boundary size.} +\end{Verbatim} + + The eForms KVP system is explained in the eforms manual, + \textsl{\mlhref{http://www.math.uakron.edu/~dpstory/acrotex/eformman.pdf}{Support for AcroForms and Links, and for Document JavaScript and Open Page Events}},\footnote + {\url{http://www.math.uakron.edu/~dpstory/acrotex/eformman.pdf}} + where a complete listing of all supported KVPs is found in the appendices. + + + \item \pkg{xkeyval} KVP: When the \opt{useui} option is taken of the eforms package, key-value pairs are + defined of the form \texttt{\anglemeta{key}[\,=\,\anglemeta{value}]}. The key-value pairs are actually a value of + a special eForms key, \cs{ui}. The value of \cs{ui} consists of a comma-delimited list of + \pkg{xkeyval} key-value pairs. For example, + \mlsetLink[\ui{% + border=visible, + linestyle=underlined, + bordercolor={0 0.6 0}, + linktxtcolor=webgreen, + js={app.alert("AcroTeX rocks!")}}]{AcroTeX + can be found at \texttt{www.acrotex.net}, as + close as your nearest web browser.} +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars={!@^}] +\mlsetLink[\ui{% +!quad@border=visible,^ +!quad@linestyle=underlined,^ +!quad@bordercolor={0 0.6 0},^ +!quad@linktxtcolor=webgreen,^ +!quad@js={app.alert("AcroTeX rocks!")}}]{AcroTeX...browser.}^ +\end{Verbatim} + \item[] The \pkg{xkeyval} KVP system is described in the document + \textsl{\mlhref{http://www.math.uakron.edu/~dpstory/acrotex/eformman.pdf}{Support for AcroForms and Links, and for Document JavaScript and Open Page Events}}.\footnote + {ibid.} +\end{enumerate} + +\paragraph*{Keys special to the \pkg{aeb\_mlink} package.} The following links are defined +within \pkg{eforms}, but are only obeyed from within the option list of one of the +\cs{ml\ameta{cmdname}} commands. +\begin{itemize} +\item \cs{mlfix\darg{\ameta{\upshape{y|n}}}} (\pkg{xkeyval} KVP: \texttt{mlfix=\ameta{\upshape{yes|no}}})\\ + If \cs{mlfix\darg{y}} is specified, contiguous bounding rectangles are combined; otherwise they are not. + See Section~\ref{s:FixQuads} for more information. +\item \cs{mlstrut\darg{\ameta{some-strut}}} (\pkg{xkeyval} KVP: \texttt{mlstrut=\ameta{some-strut}})\\ + The value of this key sets the height of the bounding rectangles; the default is \cs{strut}. See + Section~\ref{s:FixQuads} for detains and examples. +\item \cs{mlcrackat\darg{\ameta{num}}} (\pkg{xkeyval} KVP: \texttt{mlcrackat=\ameta{num}})\\ + This key is use to crack (or break) an hypertext or url into two links. + The application is to enable the link to break across a page boundary. Refer + to the paragraph \textbf{\mlnameref{para:xpage}}, beginning on page~\pageref{para:xpage} + for more information on \cs{mlcrackat}. +\item \cs{mlhyph\darg{\ameta{\upshape{y|n}}}} (\pkg{xkeyval} KVP: \texttt{mlhyph=\ameta{\upshape{yes|no}}})\\ + When the \cs{mlcrackat} option is used, an hyphen is inserted provided \cs{mlhyph{y}}, otherwise, no hypen + is inserted. Refer to the paragraph \textbf{\mlnameref{spara:fixxpage}}, page~\pageref{spara:fixxpage}, for + an example. +\item \cs{mlcrackinsat\darg{\ameta{text}}} (\pkg{xkeyval} KVP: \texttt{mlcrackinsat=\ameta{text}})\\ + The value \ameta{text} of this key is inserted after the break point, when + \cs{mlcrackat} is used. Normally, nothing is inserted after the brake point. +\end{itemize} + +\section{Fixing the quad points}\label{s:FixQuads} + +In versions of \pkg{aeb\_mlink} prior to 2018/03/19, the each syllable +(possible break point) of multi-line text was enclosed in a bounding +rectangle (described by the coordinates of its four corners). For example, it +is well known that \mlhypertext[\A{\JS{app.alert("And so it +is");}}\mlfix{n}\linktxtcolor{}\W1\H{O}\S{S}\Color{red}]{the acrotex website +is free to all who dare to enter.} Now you see the individual bounding +rectangles; they are all linked together, if you click on one of them, they +all react. + +Beginning with the version of \pkg{aeb\_mlink} dated 2018/03/19, Postscript +code was introduced to fix up these bounding boxes so that all syllables +\emph{on the same line} are enclosed in a single bounding rectangle. +\mlhypertext[\A{\JS{app.alert("And so it is");}}\linktxtcolor{}\W1\H{O}\S{S}\Color{red}]{If we turn on this feature +and declare the acrotex website is free to all who dare to enter.} Very cool! + +\exAeBBlogPDF{p=1377} The demonstration document for these feature is found on the +\href{\urlAcroTeXBlog}{{\AcroTeX} Blog} web site. Refer to the article +titled \textsl{\href{\urlAcroTeXBlog?p=1377}{Fixing multi-line link boxes}}. + + +\paragraph*{Turning the fix on and off.} The feature of fixing up these +little rectangles into one rectangle per line is controlled by the commands +\cs{mlfixOn} and \cs{mlfixOff}; the first turns on the fix up, the second +turns it off. The default is \cs{mlfixOn}. These two commands turn on or off +the fix up for the document (or within a group), to turn the fix on or off +for an individual link, use the key-value pairs \verb~\mlfix{y}~ to turn on +the fix and \verb~\mlfix{n}~ to turn it off. These key-values are placed as +an optional argument of any of the \cs{ml\ameta{cmdname}} commands. For +example, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars={!@^}] +\mlhypertext[!textbf@\mlfix{n}^\A{\JS{app.alert("And so it is");}} +\linktxtcolor{}\W1\H{O}\S{S}\Color{red}]{the acrotex website is +free to all} +\end{Verbatim} +The user-friendly counterpart is \texttt{mlfix=\ameta{\upshape{yes|no}}}. + +\paragraph*{Changing the vertical size of the rectangles.} The default height +and depth of the boxes are determined by \cs{strut}, in the current font +size. A \emph{new key is introduced}, \cs{mlstrut\darg{\ameta{some-strut}}}. +You can simple increase the vertical dimensions of the boxes by +\verb~\mlstrut{\large\strut}~ or \verb~\mlstrut{\huge\strut}~. +\mlhypertext[\A{\JS{app.alert("And so it is");}}\mlstrut{\large\strut}\linktxtcolor{}\W1\H{O}\S{S}\Color{red}] +{The acrotex website is free to all} link should have vertically expanded rectangles. +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars={!@^}] +\mlhypertext[!textbf@\mlstrut{\large\strut}^ +\A{\JS{app.alert("And so it is");}} +\linktxtcolor{}\W1\H{O}\S{S}\Color{red}]{The acrotex website +is free to all} +\end{Verbatim} +When the link is underlined (\verb~\S{U}~) the depth is set to 1bp. These +changes to the vertical size of the rectangles do not affect any text +positioning of the content, only the bounding boxes. + +\texttt{mlstrut=\ameta{some-strut}} is the counterpart to + \cs{mlstrut\darg{\ameta{some-strut}}} in the user-friendly key-value system. + +The \ameta{some-strut} argument can be anything that takes up vertical space, any horizontal space is ignored. +For example, \mlhypertext[\mlstrut{$\displaystyle\int_0^\pi$}\linktxtcolor{}\W1\H{O}\S{S}\Color{red} +\A{\JS{app.alert("No action defined, other than this one.")}}]{``The integral +{$\displaystyle\int_0^\pi \sin(x)\,dx$} has a value of a crummy little $2$.''} +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +\mlhypertext[\mlstrut{$\displaystyle\int_0^\pi$}\linktxtcolor{}\W1\H{O} +\S{S}\Color{red}]{``The integral {$\displaystyle\int_0^\pi \sin(x)\,dx$} +... $2$.''} +\end{Verbatim} + +\paragraph*{Important:} When the feature of fixing the +rectangles is active (with \cs{mlfixOn} or locally with \cs{mlfix\darg{y}}), +you need to \emph{compile the document at least three times} before +distilling the document; otherwise distiller fails. There are commands +written to the \textsf{AUX} file that needs to be up to date. This is only +needed after you modify any of the multi-line hypertext links. There are +{\LaTeX} warning messages written to the {\TeX} log to inform you if the +links are not fully formed; there are also messages in the distiller log. +Setting the package option \texttt{dblevel=1} can increase the amount of +feedback you get through the distiller log. + +\paragraph*{Marking the links.} You can run into trouble with one or more of the links. There +may be tex log or distiller log messages referring to the link number (e.g., +\texttt{mLink30}), but where is this link? By expanding \cs{mlMarksOn}, you +turn on the marking of the links. I'm turning on link marking for the rest of +the document. Look for `L\ameta{num}' beginning in section~\ref{ss:probs}. +Turn marking back off with \cs{mlMarksOff}. Above the starting point of each +link will be a tiny `L\ameta{num}'. The format for this little `L\ameta{num}' +is determined by the internal command \cs{ml@MrkLnk}; it may redefined as +desired. + + +\paragraph*{Viewing the syllable numbers.} You can display the syllable numbers of multi-line +hypertext by expanding \cs{turnSyllbCntOn}; \cs{turnSyllbCntOff} turns off this feature again. +For example, we expand \cs{turnSyllbCntOn} in a group: +\begin{quote} +\turnSyllbCntOn\mlhypertext{We have set {\cs{turnSyllbCntOn}} +in a group so the effects are not felt after the group}. +\end{quote} +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] +\begin{quote}\turnSyllbCntOn +\mlhypertext{We have set {\cs{turnSyllbCntOn}} in a +group so the effects are not felt after the group}. +\end{quote} +\end{Verbatim} +The sentence has 10 syllables, as counted by \pkg{soul} and \pkg{aeb\_mlink}. It should be noted that +\cs{turnSyllbCntOn} also executes \cs{mlMarksOn}. This feature may be useful for determining where to +break a link across pages, see the next paragraph. + +Notice we've enclose \verb~\cs{turnSyllbCntOn}~ in braces, as a reault, \pkg{soul} treats the contents +as a single syllable. If we want to break this long command across a line (or page), we would have to register +the command \cs{cs} with \cs{soulregister}: +\begin{quote}\turnSyllbCntOn\soulregister{\cs}{1} +\mlhypertext[\A{\JS{app.alert("...and it was so")}}]{Register \cs{cs} with \cs{soulregister} to have the command name \cs{turnSyllbCntOn} +break across lines (or pages).} +\end{quote} +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] +\begin{quote}\turnSyllbCntOn\soulregister{\cs}{1} % global declaration +\mlhypertext{Register \cs{cs} with \cs{soulregister} to have +the command name \cs{turnSyllbCntOn} break across lines (or pages).} +\end{quote} +\end{Verbatim} + + +\mlMarksOn + +\paragraph*{Multi-line links that break across pages.}\label{para:xpage} This phenomenon is not +supported by the PDF Reference. These kinds of links can be created by +{\LaTeX} when the link is near the bottom of the page and {\LaTeX} moves a +portion of it to the next page. \pkg{aeb\_mlinks} detects this when the +document is distilled and places a message in the distiller (or \app{ps2pdf}) log. If you have +a link that crosses page boundaries, you need to reword the paragraph to +avoid this. The message reads,\goodbreak +\begin{Verbatim}[fontsize=\small] +Beginning of page: 3 +!!------------------------------------------------------------------ +Warning: +The text of mLink4 has crossed a page boundary from page 2 to 3. +Cross page links are not supported by the PDF Specification. +This link is not constructed, please fix it. +Break point is after syllable number 4. +Use the \mlcrackat{4} option with this link. +!!------------------------------------------------------------------ +\end{Verbatim} +and can't be missed. The link is not constructed. You can see here, there is a reference +to \texttt{mLink4}. You need to turn on link marking (\cs{mlMarksOn}) or just go to page~2 +and look at the bottom of the page. + +\subparagraph*{Fixing a cross-page link.}\label{spara:fixxpage} There are a couple of action choices you can +take to fix a link that has crossed a page boundary: (1) rewrite the +paragraph so the link does not cross the page boundary; (2) manually break the link; (3) do as the log file suggests, you +can use the \cs{mlcrackat\darg{4}} option. In this latter case, for example, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +\mlhypertext[\mlcrackat{4}\mlhyph{y}!ameta(other-opts)] + {Doctor Story created the acrotex website.} +\end{Verbatim} +\begin{quote}\turnSyllbCntOn\def\pb{\penalty-10 \\\rule[2pt]{\linewidth-\widthof{\ (page break)}}{.4pt}\ \makebox[0pt][l]{(page break)}\\[3pt]}% +\ameta{latex-content}\dotfill\mlhypertext[\mlcrackat{4}\mlhyph{y}\mlcrackinsat{\pb}] + {Doctor Story created the acrotex website.} +\end{quote} +Two links are created, the first consisting of the text `Doctor Story cre-' +and the second on `ated the acrotex website.'; the second link (should) be +inserted on the next page. The link option \cs{mlhyp\darg{y}} inserts a +hyphen at the break point; for URLs, a hyphen may not be appropriate. +\textbf{Question:} What is the missing \ameta{other-opts} in the above example? + +%\kern7pt + +\exAeBBlogPDF{p=1383}\textbf{ A working document:} The demonstration document +for breaking links across pages is found on the +\href{\urlAcroTeXBlog}{{\AcroTeX} Blog} web site. Please refer to the +article titled +\textsl{\mlhref{\urlAcroTeXBlog?p=1377}{Crossing page +boundaries with multi-line links}}. Many other articles on {\AEB} and {\PDF} +can be found at the \href{\urlAcroTeXBlog}{{\AcroTeX} Blog} web site, as +well. + +%\normalcolor + +\paragraph*{Reverting to the old style.} +The restriction of having to compile multiple times before +distillation may be a burden when it comes to developing a document. You can +declare \cs{OldStyleBoxesOn} in the preamble to revert to the old style that +does not use the information written to the auxiliary file. After document +development and the text of all links are stable, you can then say +\cs{OldStyleBoxesOff} (or comment out \cs{OldStyleBoxesOn}) in the preamble. +Compiling then yields the better formed and combined bounding rectangles. + +\paragraph*{Minimally sized \texttt{/Rect}.} For multi-line links, the link +annotation contains two entries containing dimensions of rectangles, the +\texttt{/Rect} and \texttt{/QuadPoints} entries. Our focus in this paragraph +is on \texttt{/Rect}; there are two possible values for \texttt{/Rect}: (1) +the dimensions of the entire page, which has been the default value since the +inception of this package, or (2) the dimensions of the smallest rectangle +containing all the hypertext, the new default.\smallskip + +\noindent\strut{\fboxsep0pt\fcolorbox{blue}{white}{\parbox{\linewidth} +{\hskip\amtIndent For example, the following link is constructed using +\cs{mlhypertext}: \mlhypertext[\A{\JS{app.alert("AcroTeX rocks with minimal rectangles!")}}]% +{Acrobat Distiller, version~7.0 or greater} was used to +create this PDF document. The blue rectangle}}} is a representation of the `unseen' \texttt{/Rect} +dimensions. It is the smallest rectangle that contains the hypertext. You can revert to the old +default (the whole page) by expanding \cs{useSmallRectOff}, the default is \cs{useSmallRectOn}.\medskip + +\textbf{The importance of small rectangles.} In the current age we live in, +web browsers have their own `native' PDF viewers. These viewers generally do +not obey JavaScript actions but they do recognize basic actions such as +jumping to the destination in the document; however, they ignore the +\texttt{/QuadPoints} entry in a link, and respect only the \texttt{/Rect} +entry. In a `native' viewer, following a multi-line link may be problem when +the \texttt{/Rect} entry is set the whole page. Now, the \texttt{/Rect} is +the minimal rectangle, and following a link should not be an issue as long as +\emph{one rectangle is not contained within another}. Multi-line links are +fully supported by \app{Adobe Acrobat Reader}. + +\paragraph*{Tricky bits.} The use of \cs{mlnameref} and \cs{mlNameref} can be tricky when +the referenced label contains special commands or font changes. Two tricks +are to enclose the bad bits in braces (\texttt{\darg{}}) and/or \cs{protect} +commands. Section or paragraph commands that end up as PDF bookmark need to use +the \pkg{hyperref} command \cs{texorpdfstring}. To illustrate, an dummy subsection +is introduced, and the discussion on this topic is continued there. + + +\subsection{Discussion of \texorpdfstring + {{\protect\cs{mlnameref}}, {\protect\cs{mlNameref}}, and {\protect\cs{mlhypertext}}} + {\textbackslash{mlnameref}, \textbackslash{mlNameref}, and \textbackslash{mlhypertext}}}\label{ss:probs} + +To illustrate, we reference the section title ``\mlnameref{ss:probs}.'' The verbatim listing of this subsection is +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +\subsection{Discussion of problems with \texorpdfstring + {{\protect\cs{mlnameref}}, {\protect\cs{mlNameref}}, + and {\protect\cs{mlhypertext}}} + {\textbackslash{mlnameref}, \textbackslash{mlNameref}, + and \textbackslash{mlhypertext}}}\label{ss:probs} +\end{Verbatim} +Observe the use of \cs{texorpdfstring}, the first argument is typeset, the second +one is placed in the bookmarks. +\begin{itemize} + \item On the first argument of \cs{texorpdfstring}, we focus our comments + on the first \verb~{\protect\cs{mlnameref}}~ of the three commands + referenced. Note that it is enclosed in braces that signals the + \opt{soul} package, which does the parsing, to treat it as an + unbreakable unit. The control sequence \cs{cs} is protected by + \cs{protect}. Finally \cs{cs} is a command that produces a backslash in + front of its argument in monospace font. + + There are two `common' definitions of \cs{cs}-style commands: + \begin{itemize} + \item \verb~\def\cs#1{\texttt{\char`\\#1}}~ + \item \verb~\def\cs#1{\texttt{\@backslashchar#1}}~ (used in this manual) + \end{itemize} + The latter definition must be the one used within a section title, not the first one. + + The \pkg{aeb\_mlinks} defines \cs{mlcs} using the second version; that + is \begin{flushleft}\hskip\amtIndent\verb~\def\mlcs#1{\texttt{\@backslashchar#1}}~\end{flushleft} is defined. In + this way both definitions for \cs{cs} are available. The \cs{mlcs} + version must be used in text that can be referenced by \mlcs{mlnameref} + or \mlcs{mlNameref}. +\end{itemize} +In the above title declaration, if any of the components (the braces, the \cs{protect}, and the special +definition of \cs{cs}) {\LaTeX} compilation errors occur. + +Similar comments are made for \cs{mlhypertext}, \cs{mlhyperref}, and \cs{mlhyperlink}. These three take +a text phrase as its `hypertext' string. For example, +``\mlhyperref[\linktxtcolor{}\Color{red}\S{S}\W1]{ss:mlhyperref}{The exciting world of {\protect\mlcs{mlhyperref}} is average wonderful.}'' +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +\mlhyperref[\linktxtcolor{}\Color{red}\S{S}\W1]{ss:mlhyperref}{The + exciting world of {\protect\mlcs{mlhyperref}} is average wonderful.} +\end{Verbatim} +Notice the braces, the \cs{protect}, and the use of \cs{mlcs}; they work +together for a successful link construction. + +\newpage + +\section{My \textbf{Retirement} Home}\label{retirement} + +My humble retirement \hypertarget{retire}{home}. +\begin{flushleft} +\setLink[\H{N}\A{\Named{GoBack}}]{\includegraphics[scale=.5]{DSC01404}}\quad \raisebox{75pt}{\textbf{Click image to return from jump}} +\end{flushleft} + + +\newtopic\noindent +Now, I simply must get back to my retirement. \dps + +\end{document} + +\def\mlMaxNSylls{30} diff --git a/macros/latex/contrib/aeb_mlink/examples/mlink_tst.pdf b/macros/latex/contrib/aeb_mlink/examples/mlink_tst.pdf index cafe43e474..ebe8e0a45f 100644 Binary files a/macros/latex/contrib/aeb_mlink/examples/mlink_tst.pdf and b/macros/latex/contrib/aeb_mlink/examples/mlink_tst.pdf differ diff --git a/macros/latex/contrib/aeb_mlink/examples/mlink_tst.tex b/macros/latex/contrib/aeb_mlink/examples/mlink_tst.tex index e2a2a4ec43..9f87286c48 100644 --- a/macros/latex/contrib/aeb_mlink/examples/mlink_tst.tex +++ b/macros/latex/contrib/aeb_mlink/examples/mlink_tst.tex @@ -9,6 +9,7 @@ \renewcommand{\titleauthorproportion}{.5} + \title{Demonstrating the \textsf{aeb\_mlink} Package\texorpdfstring{\\[3pt]}{: }A member of AeB Pro} \author{D. P. Story} \subject{Multi-line links using the AcroTeX eDucation Bundle} @@ -26,8 +27,8 @@ \flJSStr\Msgii{Success! Multi-line links with hyphenation!\\n\\nCongrats, J\\u00FCrgen} \flJSStr\Msgiii{I said, \\"No, they won't work.\\"...I'm wrong again.} -% \mlMarksOn - +\mlMarksOn +\turnSyllbCntOn \begin{document} diff --git a/macros/latex/contrib/aeb_mlink/examples/mlink_tst_url.pdf b/macros/latex/contrib/aeb_mlink/examples/mlink_tst_url.pdf index b8467599ab..069ba1d4fc 100644 Binary files a/macros/latex/contrib/aeb_mlink/examples/mlink_tst_url.pdf and b/macros/latex/contrib/aeb_mlink/examples/mlink_tst_url.pdf differ diff --git a/macros/latex/contrib/aeb_mlink/examples/mlink_tst_url.tex b/macros/latex/contrib/aeb_mlink/examples/mlink_tst_url.tex index 926dda1b14..b5d566f908 100644 --- a/macros/latex/contrib/aeb_mlink/examples/mlink_tst_url.tex +++ b/macros/latex/contrib/aeb_mlink/examples/mlink_tst_url.tex @@ -4,6 +4,8 @@ \usepackage[colorlinks]{hyperref} \usepackage{aeb_mlink} +\hypersetup{pdfpagemode=UseNone} + \definePath{\urlAcroTeXBlog}{http://www.acrotex.net/blog} \definecolor{webgreen}{rgb}{0,.6,0} @@ -11,6 +13,7 @@ \begin{document} + In this demo file we test the \verb~\mlurl~ command. OK, let's see if we still wrap around the line diff --git a/macros/latex/contrib/edichokey/README.md b/macros/latex/contrib/edichokey/README.md new file mode 100644 index 0000000000..343e1a0ce6 --- /dev/null +++ b/macros/latex/contrib/edichokey/README.md @@ -0,0 +1,36 @@ +edichokey +======= + +`edichokey` is a LaTeX package for typesetting dichotomous identification key in +indented style. It can be considered as an extended version of package `dichokey`, +as `edichokey` is more capable of dealing with complex keys. + +Contributing +------------ + +This package is authored and maintained by Yuchang Yang < yang.yc.allium@gmail.com >. + +Discussions and questions are welcome. + +Copyright and Licence +--------------------- + + Copyright (C) 2017--2020 Yuchang Yang < yang.yc.allium@gmail.com > + ---------------------------------------------------------------------- + + This work may be distributed and/or modified under the + conditions of the LaTeX Project Public License, either version 1.3c + of this license or (at your option) any later version. + The latest version of this license is in + http://www.latex-project.org/lppl.txt + and version 1.3c or later is part of all distributions of LaTeX + version 2005/12/01 or later. + + This work has the LPPL maintenance status `maintained'. + + The Current Maintainer of this work is Yuchang Yang. + + This work consists of: + - the style file: [edichokey.sty]; + - the manual files: [edichokey-doc-en.tex, edichokey-doc-en.pdf, README.md]; + - the example files: [edichokey-ex.tex, edichokey-ex.pdf]. diff --git a/macros/latex/contrib/edichokey/edichokey-doc-en.pdf b/macros/latex/contrib/edichokey/edichokey-doc-en.pdf new file mode 100644 index 0000000000..a5c89f264d Binary files /dev/null and b/macros/latex/contrib/edichokey/edichokey-doc-en.pdf differ diff --git a/macros/latex/contrib/edichokey/edichokey-doc-en.tex b/macros/latex/contrib/edichokey/edichokey-doc-en.tex new file mode 100644 index 0000000000..211fbbeb26 --- /dev/null +++ b/macros/latex/contrib/edichokey/edichokey-doc-en.tex @@ -0,0 +1,160 @@ +%% edichokey-doc-en.tex +%% Copyright 2017--2020 Yuchang Yang < yang.yc.allium@gmail.com > +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3c +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Yuchang Yang. +% +% This work consists of: +% - the style file: [edichokey.sty]; +% - the manual files: [edichokey-doc-en.tex, edichokey-doc-en.pdf, README.md]; +% - the example files: [edichokey-ex.tex, edichokey-ex.pdf]. +%% + +% arara: xelatex + +\documentclass[a4paper]{article} + +\usepackage[top=32mm,bottom=32mm,textwidth=39em]{geometry} +\usepackage{marvosym} +\usepackage{fontspec} +\usepackage{nth} +\usepackage{color} + \definecolor{mikudark}{RGB}{19,149,139} +\usepackage{edichokey} +\usepackage{enumitem} + \setlist[description]{font=\color{mikudark}\bfseries,leftmargin=2em} + +\makeatletter +\def\@fnsymbol#1{\ifcase#1\or*\or\Letter\fi} +\makeatother + +\let\pkgname\textsf +\def\zh#1{{\fontspec{SimSun}#1}} +\def\url#1{\texttt{#1}\rlap{\char00}} +\def\param#1{\textrm{\ensuremath{\langle}\textit{#1}\ensuremath{\rangle}}} +\catcode`<\active %> +\def<#1>{\param{#1}} +\def\cmd#1{{\ttfamily\color{mikudark}#1}} +\catcode`\$=\active +\def$#1${\cmd{#1}} +\title{Package \pkgname{edichokey}% + \footnote{Github repository: \url{https://github.com/Mikumikunisiteageru/edichokey}.} + \ for dichotomous identification keys} +\author{\zh{杨宇昌} (Yuchang \textsc{Yang})% + \footnote{Email address: \url{yang.yc.allium@gmail.com}.}} +\date{July \nth{14}, 2020\qquad ver.~2.00} + +\frenchspacing + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{document} + +\maketitle + +\parskip=1ex\relax + +\emph{Identification key} is a distinctive component of taxonomic literature. Traditional identification keys are \emph{single-access}, which consist of groups of alternatives, each alternative leading to another group or ending at a taxon, following which the user can distinguish the taxa and then identify specimens. In a \emph{dichotomous identification key}, each group has exactly two alternatives, which makes the key isomorphic to a binary tree. + +There are mainly three ways to present a dichotomous key:\par +\smallskip +\fboxsep=10pt +\centerline{\fbox{\parbox{\dimexpr\linewidth-24pt\relax}{% +\kern-4pt +\def\edknamestyle{\itshape} +\begin{Key} + \alter Conjugated alternatives seperated by subsequent groups of alternatives if present. + \alter Subsequent groups indented more deeply; conjugated alternatives using the same number (possibly with different suffixes) + \name{Nested style} + \alter Depth of indentation identical for all groups; conjugated alternatives using different numbers (but annotating each other) + \name{Indented style} + \alter Conjugated alternatives always adjacent + \name{Linked style} +\end{Key}\kern-4pt}}} +\smallskip + +\pkgname{edichokey} typesets dichotomous identification keys in indented style, just as Nico Dam's package \pkgname{dichokey}\footnote{This package is available on CTAN: \url{https://ctan.org/pkg/dichokey}.}. The latter one, last updated on Dec. \nth{17}, 1999, uses a 4-byte integer counter $binarycounter$ to save the current position on (a subtree of) the binary tree, one bit for one node. However, the value of a \TeX{} counter cannot be arbitrarily large, so such mechanism may result in an arithmetic overflow, especially when the key is complex. The package \pkgname{edichokey}, as an extended version of \pkgname{dichokey}, applies a less elegant but more robust algorithm, making it capable of dealing with complicated keys with more groups of alternatives. The ease-of-use has been inherited from \pkgname{dichokey} --- the tree structure is still taken care of automatically, so there is no need to manually begin or end groups --- provided that the key is \emph{strictly} dichotomous. For those who insist on making polychotomous keys in indented style, the package \pkgname{biokey} may be a better choice (see the ``leveled keys" section in its documentation). + +\pkgname{edichokey} is distributed under the terms of \LaTeX{} Project Public License (LPPL) 1.3c\footnote{Details of the license are available on \url{http://www.latex-project.org/lppl.txt}.}. + +\section{Usage} + +An identification key should be made within a $Key$ environment, i.e. between $\string\begin\{Key\}\allowbreak[]$ and $\string\end\{Key\}$. The optional parameter $$ can be applied when typesetting a key for species in a genus, say, \textit{Allium}; in that case, all species share the same genus part (usually abbreviated) ``\textit{A.}", thus the $$ should be $A.$ ($A.\textvisiblespace$ and $A.\textasciitilde$ are also okay; there will always be a space no matter given explicitly or not, unless the parameter is omitted). To be compatible with \pkgname{dichokey}, starting the environment with $\string\begin\{Key\}\{\}$ is also acceptable. + +Within a key, every alternative should follow an $\string\alter$ macro. When a taxon is keyed out after an alternative, it should be written as $\string\name[]\{\}$. Here $$ is still an optional parameter, which will be used before this $$ instead of the parameter of the $Key$ environment. + +Every $$ and $$ use the font style defined by $\string\edknamestyle$, or by default $\string\bfseries\string\itshape$. The user can redefine $\string\edknamestyle$ to customize the style. + +Here a simple demo is presented, showing how to use the package \pkgname{edichokey}: + +\medskip +\noindent +\begin{minipage}{0.6\linewidth} +\color{mikudark} +\begin{verbatim} + \begin{Key}[P.] + \alter Leaves large \name{macrophyllus} + \alter Leaves small. + \alter Flower solitary. + \alter Fruits white \name{leucocarpus} + \alter Fruits black \name{melanocarpus} + \alter Flowers many \name{pleianthus} + \end{Key} +\end{verbatim} +\end{minipage}% +\hskip -1000pt plus 1fill +\begin{minipage}{0.42\linewidth} + \begin{Key}[P.] + \alter Leaves large \name{macrophyllus} + \alter Leaves small. + \alter Flower solitary. + \alter Fruits white \name{leucocarpus} + \alter Fruits black \name{melanocarpus} + \alter Flowers many \name{pleianthus} + \end{Key} +\end{minipage}% +\par +\medskip + +A larger example key containing 107 \textit{Allium} species is provided separatedly in the package as file \texttt{edichokey-ex.tex}, which was taken almost verbatim from \textit{Flora of North America} (see the file for full citation; reusable under CC BY license\footnote{Re-use terms of FNA: \url{http://beta.floranorthamerica.org/Copyright}.}), except that the two branches at the base (led by alternatives with number 1) were exchanged (but its meaning stayed the same). This example, in the given order, cannot be constructed with \pkgname{dichokey}. + +Apart from the modification on the algorithm, \pkgname{edichokey} behaves differently from \pkgname{dichokey} in two more aspects: +{\parskip-5pt +\begin{itemize} + \parskip0pt\itemsep2pt + \item Dots connecting an alternative and a taxon can be wrapped into two lines; + \item All alternatives (maybe with following dots) are wrapped at $\string\righttaxonskip$ length (by default $2em$) from the right margin, leaving only the keyed out taxa reaching the true right boundary. +\end{itemize}} + +\section{Change history} + +\begingroup +\parskip=0pt +\parindent=0pt +\begin{description}[style=nextline] + \item[ver. 2.00 (2020.7.14)] + Package renamed as \pkgname{edichokey}. \\ + Documentation in English finished. \\ + Example key from \textit{Flora of North America} provided. \\ + All codes rewritten. \\ + Environment name changed from $Key*$ to $Key$. \\ + Paragraph shape handled more carefully to be compatible with \pkgname{changepage}. \\ + First distribution on CTAN (Comprehensive \TeX{} Archive Network). + \item[ver. 1.01 (2017.12.14)] + Some minimal changes. + \item[ver. 1.00 (2017.12.13)] + First implementation, named as \pkgname{qdichokey} temporarily. \\ + Distributed on Github. +\end{description} +\endgroup + +\end{document} diff --git a/macros/latex/contrib/edichokey/edichokey-ex.pdf b/macros/latex/contrib/edichokey/edichokey-ex.pdf new file mode 100644 index 0000000000..9711e1c6df Binary files /dev/null and b/macros/latex/contrib/edichokey/edichokey-ex.pdf differ diff --git a/macros/latex/contrib/edichokey/edichokey-ex.tex b/macros/latex/contrib/edichokey/edichokey-ex.tex new file mode 100644 index 0000000000..25d0c8b51e --- /dev/null +++ b/macros/latex/contrib/edichokey/edichokey-ex.tex @@ -0,0 +1,377 @@ +%% edichokey-ex.tex +%% Copyright 2017--2020 Yuchang Yang < yang.yc.allium@gmail.com > +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3c +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Yuchang Yang. +% +% This work consists of: +% - the style file: [edichokey.sty]; +% - the manual files: [edichokey-doc-en.tex, edichokey-doc-en.pdf, README.md]; +% - the example files: [edichokey-ex.tex, edichokey-ex.pdf]. +% +%% Note: the key used in this file is credited to Dale W. McNeal Jr. +%% and T. D. Jacobson, from Flora of North America edited by Flora of +%% North America Editorial Committee, which is reusable under the terms +%% of CC BY license. See the text for full citation. +%% Their original work is available in +%% http://beta.floranorthamerica.org/Allium +%% or in +%% http://www.efloras.org/florataxon.aspx?flora_id=1&taxon_id=101086 +%% and the full content of the CC BY license is in +%% https://creativecommons.org/licenses/by/3.0/ +%% In this file, the two basic branches in the key were exchanged. +%% See the manual edichokey-doc-en.tex for details of modification. + +\documentclass[a4paper]{article} + +\usepackage[margin=25mm]{geometry} +\usepackage{edichokey} + +\def\var{\textup{var.} } +\frenchspacing +\tolerance2000 + +\begin{document} + +\vspace*{1cm} +\centerline{\Large Identification key to \textit{Allium} species in North America} +\vskip8mm + +\begingroup +\leftskip1em\rightskip1em +\noindent Source: \textsc{McNeal Jr., Dale W., \& Jacobsen, T. D.} 2002. \textit{Allium} Linnaeus. \textit{Pages 224--275 of:} \textsc{Flora of North America Editorial Committee} (ed), \textit{Flora of North America North of Mexico}, vol. 26. New York and Oxford: Oxford University Press.\par\endgroup + +\vskip8mm + +\begin{Key}{A. } +\alter Leaf blade flat, channeled, or ± terete, never more than 30 mm wide, (never petiolate). +\alter Flowering pedicels mostly or completely replaced by bulbils. +\alter Outer bulb coats persisting as fibrous reticulum; leaf sheaths not extending more than 1/4 scape; spathe bract beakless or beak much shorter than base. +\alter Ovary, when present, crestless; spathe bracts 3--7-veined; east of 103rd meridian +\name{canadense} +\alter Ovary, when present, obscurely crested with 6, low, central processes; spathe bracts 1-veined; west of 105th meridian +\name{geyeri} +\alter Outer bulb coats membranous, if with fibers these not forming reticulum; leaf sheaths extending to midscape or above; spathe bract with beak equaling or longer than base. +\alter Spathe bract 1, caducous. +\alter Bulbs 1--2 cm diam.; leaf blade 2--4 mm diam., cylindric or filiform, not carinate, hollow below middle +\name{vineale} +\alter Bulbs (1.5--)3--8 cm diam.; leaf blade 5--20 mm wide, flat, carinate, solid +\name{sativum \var sativum} +\alter Spathe bracts 2--5, persistent. +\alter Spathe bracts 2--5, 4--9-veined, beak to 20 cm +\name{oleraceum} +\alter Spathe bracts 3--5, 2--3-veined, beak to 10 cm +\name{ampeloprasum} +\alter Flowering pedicels floriferous, bulbils almost unknown. +\alter Outer bulb coats persisting as fibrous reticulum. +\alter Ovary usually crestless; if obscurely crested, with 3 or 6 processes; east of 103rd meridian. +\alter Spathe bracts usually 1-veined. +\alter Spaces between bulb coat fibers filled in proximal 1/2 bulb; tepals white, pink, or red, rarely greenish yellow; central plains from N Mexico to Nebraska +\name{drummondii} +\alter Spaces between bulb coat fibers open; tepals yellow; W Texas +\name{coryi} +\alter Spathe bracts 3--7-veined. +\alter Umbel compact; pedicels much shorter than flowers +\name{schoenoprasum} +\alter Umbel loose; pedicels longer than flowers. +\alter Flowers substellate to urceolate-campanulate, ultimately withering somewhat and exposing capsule; reticula of bulbs finely or only moderately coarsely meshed. +\alter Bulbs 1--3, narrowly cylindric, attached to ± horizontal primary rhizome, often missing or not visible on herbarium specimens; leaf blade carinate; cells of seed coat smooth, shiny; occasional introduction +\name{tuberosum} +\alter Bulbs 1--4+, ovoid, not attached to rhizome; leaf blades not carinate, channeled; cells of seed coat each with minute, central papilla; native east of 103rd meridian +\name{canadense} +\alter Flowers urceolate, permanently investing capsule; reticula of bulbs usually very coarsely meshed. +\alter Flowering bulbs with cluster of stalked, basal bulbels; cells of innermost bulb coats contorted, with sinuous walls; extreme S Texas +\name{runyonii} +\alter Flowering bulbs without basal bulbels; cells of innermost bulb coats vertically elongate, without sinuous walls; W Texas and E New Mexico to C South Dakota +\name{perdulce} +\alter Ovary usually crested with 3 or 6 processes; if crestless, from west of 105th meridian. +\alter Ovary and capsule conspicuously crested with 6 contorted or horizontally spreading, ± lateral processes; tepals widely spreading to reflexed, SE United States. +\alter Spathe bracts usually 5--7-veined; ovary crests conspicuously contorted; tepals spreading to reflexed +\name{cuthbertii} +\alter Spathe bracts 1-veined; ovary crests flattened, horizontally spreading, not contorted; tepals widely spreading +\name{speculae} +\alter Ovary crested with 6 ± erect, often obscure central processes; tepals erect to widely spreading; W North America. +\alter Leaves 3+ per scape; cells of seed coat each with minute, central papilla. +\alter Bulbs often short-rhizomatous basally; spathe bracts 3--5-veined; ovary conspicuously crested with 6 flattened, lacerate central processes; tepals spreading or reflexed, withering in fruit, not investing capsule +\name{plummerae} +\alter Bulbs not short-rhizomatous; spathe bracts usually 1-veined; ovary obscurely crested with 6 rounded central processes; tepals erect, not withering in fruit, permanently investing capsule. +\alter Leaf blade flat, ± falcate, usually 3--6 mm wide; Box Elder County, Utah +\name{passeyi} +\alter Leaf blade channeled, ± straight, usually less than 5 mm wide; widespread, N Great Plains and W North America +\name{geyeri} +\alter Leaves usually 2 per scape; cells of seed coat ± smooth, with or without central papillae. +\alter Spathe bracts 3--5-veined; tepals becoming papery in fruit, midrib scarcely thickened, not investing capsule; ovary usually conspicuously crested with 6 flattened central processes, often to 2 mm +\name{macropetalum} +\alter Spathe bracts 1-veined; tepals becoming callous-keeled, permanently investing capsule; ovary inconspicuously crested with 6 rounded central processes, to 1 mm. +\alter Leaf blade flat, ± falcate, usually 3--6 mm wide; cells of seed coat with minute central papilla; Box Elder County, Utah +\name{passeyi} +\alter Leaf blade semiterete, channeled, ± straight, usually 1--3(--5) mm wide; cells of seed coat smooth; N Great Plains and W North America +\name{textile} +\alter Outer bulb coats membranous to chartaceous, with or without distinct cellular markings (reticulation); without fibers or with some parallel fibers. +\alter Scape fistulose, 3--25 mm diam., not flattened and winged; leaves 2--10, blade flat and solid, or fistulose. +\alter Leaf blade flat, solid. +\alter Leaves not or scarcely sheathing base of scape +\name{nigrum} +\alter Leaves sheathing 1/3--1/2 scape +\name{ampeloprasum} +\alter Leaf blade fistulose. +\alter Bulbs 1--3, to 10 cm diam., ± globose, not rhizomatous; leaf blade semicircular in cross section; occasional escape from cultivation +\name{cepa} +\alter Bulbs 1--2, 5 cm diam., cylindric, clustered on short rhizome (this often missing or not visible on herbarium specimens); leaf blade circular in cross section; native or introduced. +\alter Flowers 8--18 mm; tepals lilac to pale purple; native or introduced +\name{schoenoprasum} +\alter Flowers 6--9 mm; tepals pale yellowish white; introduced +\name{fistulosum} +\alter Scape solid, exceeding 5 mm wide only if flattened and winged; leaves 1--several, leaf blade solid. +\alter Leaves (3--)5--40 mm wide, basal sheaths extending 1/3--1/2 scape. +\alter Filaments unappendaged; leaf blade terete to semiterete; bulbels, if present, light brown +\name{paniculatum} +\alter Inner filaments appendaged with prominent tooth on each side of anther; leaf blade flat, channeled; bulbels very dark purple +\name{rotundum} +\alter Leaves 1--25 mm wide, basal sheaths never extending much above soil level. +\alter Bulbs oblong, elongate, or ovoid, clustered on stout, primary rhizome, or short-rhizomatous; bulb coats membranous or chartaceous, finely striate with narrow, vertically elongate cells. +\alter Bulbs on stout, iris-like rhizome; ovary crestless. +\alter Tepals elliptic, apex obtuse; stamens ± equaling tepals; EC Arizona and adjacent New Mexico, and Santa Catalina Mountains, S Arizona +\name{gooddingii} +\alter Tepals narrowly lanceolate to lanceolate, apex acuminate; stamens much shorter than tepals or definitely exserted; widespread in W North America, not occurring in Arizona. +\alter Stamens and style exserted; stigma capitate; Cascades and Sierras E to NE Nevada, E Oregon, W Idaho +\name{validum} +\alter Stamens and style ca. 1/2 tepals; stigma 3-lobed; Rocky Mountains from C Montana and NE Idaho to Wyoming, NE Utah, Colorado, and New Mexico +\name{brevistylum} +\alter Bulbs short-rhizomatous at base, rhizome not stout and iris-like; ovary strongly crested with 6 processes. +\alter Stamens and styles included; outer bulb coats ± reddish brown, inner coats deep red to white; ovary crested with 6 short, rounded, densely papillose processes +\name{haematochiton} +\alter Stamens and styles exserted; outer bulb coats gray or brown, inner coats white to pink or reddish; ovary crested with 6 flattened, ± triangular processes, margins entire or toothed. +\alter Flowers campanulate; tepals ± erect; scape nodding +\name{cernuum} +\alter Flowers stellate; tepals spreading; scape erect, or, if nodding at anthesis, becoming erect +\name{stellatum} +\alter Bulbs ovoid to subglobose, not clustered on stout, primary rhizome; rhizomes, if present, secondary, arising from bulbs, ± slender, terminated by new bulbs; bulb coats without reticulation or with ± isodiametric or transversely elongate cells that are sometimes intricately contorted. +\alter Leaf 1 per scape; leaf blade terete; ovary prominently crested with 6 ± triangular processes. +\alter Stigma unlobed or minutely 3-lobed, lobes ± stout, erect or spreading. +\alter Scape 18--60 cm; flowers 5--9 mm; tepals unequal, inner whorl 1/4--1/3 longer than outer, margins entire or irregular to erose; stamens exserted +\name{sanbornii} +\alter Scape less than 25 cm; flowers 7--20 mm; tepals ± equal, margins entire; stamens included. +\alter Outer bulb coat reticulate with ± elongate, contorted meshes +\name{nevadense} +\alter Outer bulb coat lacking reticulation, or meshes very indistinct, square or polygonal. +\alter Pedicels slender, longer than flowers; flowers 8--12 mm +\name{atrorubens} +\alter Pedicels stout, generally shorter than flowers; flowers 12--20 mm. +\alter Tepals lanceolate to lance-linear, apex acute; lacking stalked, basal increase bulbs; rocky, sandy desert slopes, S California to W Arizona +\name{parishii} +\alter Tepals lance-linear to lanceolate, apex long-acuminate; with 1--2 stalked basal increase bulbs; alpine ridges and talus, S California mountains +\name{monticola} +\alter Stigma distinctly 3-lobed, lobes often slender and recurved. +\alter Stamens equaling tepals or exserted. +\alter Tepals unequal, inner 1/3--1/2 longer than outer +\name{sanbornii} +\alter Tepals ± equal +\name{howellii} +\alter Stamens included. +\alter Tepal (at least inner whorl) margins denticulate to erose. +\alter Scape 25--40 cm +\name{jepsonii} +\alter Scape 5--20 cm. +\alter Outer bulb coats reddish brown; tepals erect, ± straight at tip; inner whorl margins denticulate +\name{denticulatum} +\alter Outer bulb coats brown to gray; tepals erect, ± spreading-reflexed at tip; inner whorl margins denticulate to erose +\name{abramsii} +\alter Tepal margins all ± entire. +\alter Margins of ovarian crest processes entire or notched at tip, outer margins sometimes irregular but never dentate or laciniate. +\alter Flowers 10--18 mm; tepals maroon or deep reddish purple. +\alter Tepals deep reddish purple, all reflexed at tip; Mount Hamilton Range, C California +\name{sharsmithiae} +\alter Tepals maroon, outer curled back at tip, inner reflexed; Spanish Needle Peak, S Sierra Nevada, and Horse Canyon, Tehachapi Mountains, California +\name{shevockii} +\alter Flowers 6--9 mm; tepals white to pink, darkening in age. +\alter Inflorescence loose; pedicels flexuous in fruit; tepals lanceolate to lance-ovate, apex acuminate +\name{parryi} +\alter Inflorescence compact; pedicels straight; tepals ovate to nearly round, apex obtuse (rarely acute) to shallowly emarginate +\name{munzii} +\alter Margins of ovarian crest processes dentate to laciniate. +\alter Tepals deep reddish purple, erect, usually conspicuously recurved at tip +\name{fimbriatum} +\alter Tepals white or flushed to pale lavender with darker midveins, spreading or erect, not conspicuously recurved at tip. +\alter Flowers usually 6--12 mm +\name{fimbriatum} +\alter Flowers usually 6--8(--10) mm. +\alter Scape 25--50 cm; tepals spreading from base; serpentine soil, Rawhide Hill and Red Hills, foothills of Sierra Nevada, C California +\name{tuolumnense} +\alter Scape 7--20(--30) cm; tepals erect; serpentine clay soils, S Coast Ranges and W Transverse Ranges, California +\name{diabolense} +\alter Leaves usually 2 or more, if 1, blade flattened or broadly channeled; ovary crestless or variously crested. +\alter Bulbs generally with numerous increase bulbs, these much smaller than parent bulb, enclosed by bulb coats, in basal cluster or on threadlike rhizomes to 10 cm. +\alter Ovary crestless or obscurely crested with 3 low central processes. +\alter Larger bulbs each with cluster of bulbels surrounding roots; S Texas +\name{elmendorfii} +\alter Larger bulbs each with cluster of small, basal bulbels on one side; NE Oregon and WC Idaho +\name{madidum} +\alter Ovary prominently crested with 6 triangular central processes, margins finely papillose or denticulate. +\alter Leaves usually beginning to wither from tip by anthesis; tepals rigid (not papery), ± shiny in fruit, strongly involute at tip, carinate +\name{campanulatum} +\alter Leaves usually green at anthesis; tepals papery (not rigid and shiny) in fruit, not strongly involute, not carinate. +\alter Tepals ovate to elliptic, apex acute to acuminate; foot\-hills of Sierra Nevada, N, C California +\name{membranaceum} +\alter Tepals lanceolate, apex acuminate; Sierra Nevada, California, and intermountain region N to Oregon, Idaho +\name{bisceptrum} +\alter Increase bulbs absent or 1--4, ± equaling parent bulbs, enclosed by parental bulb coats, never appearing as basal cluster, not rhizomatous or rhizomes 2+ mm thick (not threadlike). +\alter Leaf blade channeled to subterete, if flat, not falcate. +\alter Bulb coats lacking reticulation or reticulum delicate, very obscure under hand lens. +\alter Bulbs ovoid to subglobose; rhizomes absent, renewal bulbs formed within coats of parent bulb; native or introduced. +\alter Scape terete throughout, 1--3 mm diam.; leaf blade 1--3 mm wide; native to W Texas to SE Arizona +\name{kunthii} +\alter Scape triquetrous, 2-edged or slightly winged proximally, if terete only proximally so, 1--10 mm wide; introduced in California and Oregon near the Pacific coast. +\alter Umbel erect, ± hemispheric; flowers ± erect; tepals broadly elliptic, apex obtuse +\name{neapolitanum} +\alter Umbel lax, ± 1-sided; flowers pendent; tepals lanceolate, apex acute +\name{triquetrum} +\alter Bulbs oblique or oblique-ovoid, renewal bulbs borne terminally on rhizomes outside coats of parent bulbs; native. +\alter Rhizomes conspicuous, 2 cm or more, including renewal bulbs. +\alter Rhizomes smooth, parent bulb disappearing by anthesis except for still-functional roots and bulb coat; leaf blade broadly concave-convex or ± flattened, carinate; tepals obovate to ovate, apex acute to obtuse or emarginate; Coast Ranges, California, Oregon +\name{unifolium} +\alter Rhizomes scaly, sometimes absent, often missing in herbarium specimens, parent bulb persisting after anthesis; leaf blade flat, not carinate; tepals lanceolate to oblong, apex acute to acuminate; trans- Pecos Texas to SE Arizona +\name{rhizomatum} +\alter Rhizomes inconspicuous, 2 cm or less, including renewal bulb. +\alter Tepals erect, red-purple, rarely pure white, at least inner tepal margins serrulate; NW California, SW Oregon +\name{bolanderi} +\alter Tepals ± spreading, white to pale pink, margins entire; W Texas to SE Arizona +\name{kunthii} +\alter Bulb coats obviously reticulate with prominent meshes under hand lens. +\alter Cells of outer bulb coat square or polygonal. +\alter Ovary with 6 prominent, flat, ± triangular crest processes +\name{bigelovii} +\alter Ovary with 3 or 6 minute, rounded crest processes, or crest obscure. +\alter Flowers 4--9 mm; tepals erect or spreading from base, margins entire +\name{lacunosum} +\alter Flowers 8--16 mm; tepals spreading at tip, inner tepal margins denticulate. +\alter Bulb forming 1--3 renewal bulbs borne terminally on rhizomes outside coats of parent bulb; parent bulb disappearing by anthesis except for still-functional roots and shriveled bulb coats; near Weller Butte, Blue Mountains, SE Washington +\name{dictuon} +\alter Bulbs not forming rhizomes, renewal bulbs formed within coats of parent bulb; widespread W of Rocky Mountains +\name{acuminatum} +\alter Cells of bulb coat transversely elongate, V-shaped, arranged in ± vertical rows, forming herringbone pattern, or ± contorted. +\alter Cells of bulb coat in wavy, transverse rows, forming indistinct herringbone pattern or ± contorted; tepals spreading, ± equal. +\alter Scape (3--)5--15(--17) cm; umbel persistent; tepals erect, not connivent over capsule in fruit +\name{hickmanii} +\alter Scape 15--60 cm; umbel shattering, each flower with its pedicel falling as unit; tepals connivent over capsule in fruit. +\alter Ovary crested with 6 ± rectangular lateral processes; umbel compact; pedicel 0.7--2 times perianth +\name{amplectens} +\alter Ovary crestless or crested with 3 minute, 2-lobed central processes; umbel loose; pedicel 1.5--4 times perianth. +\alter Leaf blade to 10 mm wide, channeled or flattened, carinate; inner bulb coats white; tepals becoming papery (not hyaline) after anthesis +\name{praecox} +\alter Leaf blade 1--3 mm wide, channeled or subterete, not carinate; inner bulb coats light yellow or white; tepals becoming hyaline (not papery) after anthesis +\name{hyalinum} +\alter Cells of bulb coat in sharply serrate, transverse rows, forming distinct herringbone pattern; tepals erect, inner shorter, narrower. +\alter Tepals connivent over capsule in fruit, not rigid; umbel shattering in fruit, each flower with its pedicel falling as a unit +\name{serra} +\alter Tepals not connivent over capsule, rigid in fruit; umbel persistent. +\alter Leaves 3--6, blade arcuate to tortuous; umbel compact; pedicels 5--20 mm; sea cliffs, N, C California +\name{dichlamydeum} +\alter Leaves 2--3, blade straight to arcuate; umbel loose; pedicels 10--40 mm; not on sea cliffs, California Floristic Province, extending south in coastal ranges. +\alter Inner tepal margins denticulate, crisped +\name{crispum} +\alter Inner tepal margins entire to denticulate, never crisped +\name{peninsulare} +\alter Leaf blade flat or broadly channeled, if flat, ± falcate. +\alter Scape and leaves persisting after seeds mature or on pressing, or only tardily deciduous. +\alter Stamens much shorter than tepals. +\alter Bulb coat cellular-reticulate with elongate, ± obscure, intricately contorted cells (resembling \textit{Allium madidum}, but never with cluster of basal bulbels) +\name{fibrillum} +\alter Bulb coat cellular-reticulate with ± narrowly hexagonal, transversely elongate cells +\name{brandegeei} +\alter Stamens equaling tepals or exserted. +\alter Scape expanded proximal to inflorescence; leaf blade (2--)5--8 mm wide +\name{columbianum} +\alter Scape thickest immediately proximal to inflorescence; leaf blade 1--5(--15) mm wide. +\alter Scape constricted just proximal to inflorescence, then expanded; leaf blade 1--3(--5) mm wide +\name{constrictum} +\alter Scape not expanded proximal to inflorescence; leaf blade 2--5(--15) mm wide. +\alter Leaf blade usually more than 5 mm wide, flat; umbel 25--50-flowered; spathe bracts 3 +\name{douglasii} +\alter Leaf blade 2--3 mm wide, flat to channeled; umbel 10--30-flowered; spathe bracts 2. +\alter Bulb coat with quadrate to polygonal reticulations; leaf blade ± equaling scape +\name{nevii} +\alter Bulb coat without reticulations or with 2--3 rows of ± quadrate cells just distal to roots; leaf blade exceeding scape +\name{macrum} +\alter Scape and leaves forming abcission layer at soil surface and deciduous when seeds mature, also frequently breaking at soil surface after pressing. +\alter Outer bulb coats cellular-reticulate throughout (often obscurely so in \textit{A. aaseae} and \textit{A. simillimum}). +\alter Bulb coats obscurely cellular-reticulate with ± contorted cells; tepal margins denticulate to erose. +\alter Tepals white with greenish or reddish veins, sometimes flushed pink; anthers purple or mottled purple and white; pollen white or gray +\name{simillimum} +\alter Tepals bright pink, rarely white; anthers yellow; pollen yellow +\name{aaseae} +\alter Bulb coats ± prominently cellular-reticulate; tepal margins entire. +\alter Bulb coats reticulate, cells irregularly arranged, ± polygonal, rectangular, or transversely elongate, ± curved. +\alter Cells of bulb coat irregularly arranged, ± transversely elongate, curved; Tuolumne County, C California +\name{tribracteatum} +\alter Cells of bulb coat irregularly arranged or in ± regular vertical rows, polygonal or ± rectangular; Sierra Nevada, California, and Nevada +\name{obtusum} +\alter Bulb coats reticulate, cells arranged in ± regular vertical rows, narrowly hexagonal to rectangular, transversely elongate. +\alter Tepals linear-lanceolate +\name{anceps} +\alter Tepals oblanceolate to ovate. +\alter Scape 3--10 cm; pedicel ± equaling perianth +\name{punctum} +\alter Scape 15--20 cm; pedicel 2--3 times perianth +\name{lemmonii} +\alter Outer bulb coats not cellular-reticulate or with 2--3 rows of cells just distal to roots. +\alter Scape terete or ± compressed, not winged. +\alter Stamens well included. +\alter Stamens ± equaling tepals or exserted. +\alter Leaf blade strongly falcate; umbel mostly 5--10-flowered +\name{parvum} +\alter Leaf blade linear or weakly falcate; umbel 20--30-flowered +\name{cratericola} +\alter Leaves 2 per scape. +\alter Leaf 1 per scape. +\alter Leaf blade ± equaling to 2 times scape; WC Idaho +\name{tolmiei} +\alter Leaf blade much longer than scape; C Sierra Nevada, California +\name{yosemitense} +\alter Filaments papillose proximally +\name{hoffmanii} +\alter Filaments smooth proximally +\name{burlewii} +\alter Scape flattened, 2-edged or usually winged distally. +\alter Bulbs oblique or oblique-ovoid, renewal bulbs borne terminally on rhizomes outside coats of parent bulb; parent bulb disappearing by anthesis except for still-functional roots and shriveled bulb coat. +\alter Pedicel ± equaling perianth; ovary obscurely 3-crested; barren, bald summits W of Cascade Mountains from Vancouver Island to SW Oregon, also at Jefferson Park, Oregon, and in Wenatchee Mountains, C Washington +\name{crenulatum} +\alter Pedicel 2--3 times perianth; ovary prominently 6-crested; mountains and scablands E of Cascade Mountains, Oregon +\name{tolmiei} +\alter Bulbs ovoid to subglobose, rhizomes absent, renewal bulbs formed within coats of parent bulb; parent bulbs persistent. +\alter Tepals narrowly lanceolate, apex long-acuminate; stamens exserted +\name{platycaule} +\alter Tepals lanceolate to ovate or elliptic, apex obtuse to acuminate; stamens included. +\alter Flowers 9--15 mm; tepal apex long-acuminate, inner margins usually denticulate +\name{falcifolium} +\alter Flowers 6--10(--12) mm; tepal apex obtuse to acute, or ± involute in age and appearing acuminate, inner margins denticulate or not. +\alter Inner bulb coats usually pink or red; inner tepal margins sometimes ± denticulate; Siskiyou Mountains of NW California and SW Oregon +\name{siskiyouense} +\alter Inner bulb coats white; inner tepal margins entire; W United States, E of Sierra--Cascade axis. +\alter Tepals becoming rigid (not papery), carinate in fruit. +\alter Tepals lanceolate, apex acute to acuminate, ± erect in fruit, involute at tip; ovary obscurely to prominently crested with 3 or 6 processes +\name{tolmiei} +\alter Tepals elliptic-oblong, apex obtuse, not involute at tip, connivent over ovary in fruit; ovary crestless or obscurely crested +\name{scilloides} +\alter Tepals becoming papery (not rigid), not carinate in fruit. +\alter Ovary distinctly crested with 3 or 6 low processes; sand and gravel deposits, along Columbia River from Ferry County, NE Washington, to mouth of John Day River, NC Oregon +\name{robinsonii} +\alter Ovary obscurely crested with 3 low, rounded processes; rocky, clay slopes and talus, E Oregon, Idaho, to C California, N Nevada, NW Utah +\name{parvum} +\alter Leaf blade flat, 15--90 mm wide, (tapering to base or distinctly petiolate). +\alter Leaves ephemeral, usually absent at anthesis; E North America +\name{tricoccum} +\alter Leaves present at anthesis; Attu and Unalaska islands, Alaska +\name{victorialis} +\end{Key} + +\end{document} diff --git a/macros/latex/contrib/edichokey/edichokey.sty b/macros/latex/contrib/edichokey/edichokey.sty new file mode 100644 index 0000000000..1b927eadaf --- /dev/null +++ b/macros/latex/contrib/edichokey/edichokey.sty @@ -0,0 +1,89 @@ +%% edichokey.sty +%% Copyright 2017--2020 Yuchang Yang < yang.yc.allium@gmail.com > +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3c +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Yuchang Yang. +% +% This work consists of: +% - the style file: [edichokey.sty]; +% - the manual files: [edichokey-doc-en.tex, edichokey-doc-en.pdf, README.md]; +% - the example files: [edichokey-ex.tex, edichokey-ex.pdf]. +%% +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{edichokey}[2020/07/14 v2.00 package edichokey] +\makeatletter +\def\edk@get@array#1{\csname edk@array@#1\endcsname} +\def\edk@set@array#1#2{\expandafter\xdef\csname edk@array@#1\endcsname{#2}} +\newif\if@edk@named@ +\newdimen\alterindent\alterindent1.2em +\newdimen\taxonrightskip\taxonrightskip2em +\newdimen\edk@leftskip +\newbox\edk@header +\newcount\edk@depth +\newcount\edk@couplet +\def\edknamestyle{\bfseries\itshape} +\def\edk@prefix{} +\def\@take@bracket[#1]{\def\edk@prefix{#1\unskip\space}} +\def\@take@brace#1{\@take@bracket[#1]} +\def\@take@arg{% + \ifx\@next@token[%] + \let\temp@\@take@bracket + \else + \ifx\@next@token\bgroup%\egroup + \let\temp@\@take@brace + \else + \let\temp@\relax + \fi + \fi + \temp@} +\def\take@arg{\futurelet\@next@token\@take@arg} +\def\dot@fill#1{\leavevmode\leaders\hb@xt@.44em{\hss.\hss}\hskip#1\kern\z@} +\def\dot@line{% + \unskip\dot@fill{0pt plus 1fil}\penalty150% + \null\nobreak\dot@fill{12pt plus 1fill}} +\newenvironment{Key} + {\edk@depth\z@ + \edk@couplet\z@ + \parindent\z@ + \advance\rightskip\taxonrightskip + \edk@leftskip\dimexpr\leftskip-\alterindent\relax + \global\@edk@named@false + \take@arg + }{\par} +\def\name@#1{% + \global\@edk@named@true + \dot@line + \mbox{\edknamestyle\edk@prefix#1}% + \kern-\taxonrightskip\par} +\def\name@@[#1]#2{% + {\@take@bracket[#1]\name@{#2}}} +\def\name{% + \@ifnextchar[%] + \name@@\name@} +\def\alter{% + \par + \if@edk@named@ + \@whilenum\edk@get@array{\the\edk@depth}=\z@\do{% + \advance\edk@depth-\@ne}% + \xdef\edk@number{\edk@get@array{\the\edk@depth}}% + \edk@set@array{\the\edk@depth}{0}% + \else + \advance\edk@couplet\@ne + \advance\edk@depth\@ne + \xdef\edk@number{\the\edk@couplet}% + \edk@set@array{\the\edk@depth}{\the\edk@couplet}% + \fi + \@edk@named@false + \sbox\edk@header{\edk@number.~}% + \leftskip\dimexpr\edk@leftskip+\edk@depth\alterindent+\wd\edk@header\relax + \indent\llap{\box\edk@header}} +\makeatother diff --git a/macros/latex/contrib/elpres/README b/macros/latex/contrib/elpres/README deleted file mode 100644 index 2997fbd372..0000000000 --- a/macros/latex/contrib/elpres/README +++ /dev/null @@ -1,20 +0,0 @@ -Document class: elpres - -Version: 0.4a - -License: LaTeX project public license (lppl) - -Short description: - -Elpres is a simple class for electronic presentations to be shown on a screen -or a beamer. Elpres is derived from article.cls and may be used with LaTeX or -pdfLaTeX. - -The elpres class requires the packages: ifthen, fancyhdr, geometry. - -For enhanced options, the packages ragged2e, overlays, wallpaper, eso-pic, -footmisc and hyperref are useful. - -Volker Kiefel -volker (dot) kiefel (at) freenet (dot) de - diff --git a/macros/latex/contrib/elpres/README.md b/macros/latex/contrib/elpres/README.md new file mode 100644 index 0000000000..a2730e2d3b --- /dev/null +++ b/macros/latex/contrib/elpres/README.md @@ -0,0 +1,39 @@ +Elpres v0.5 2020-07-12 + +Short description +================= + +The elpres class is intended to be used for presentations on a screen or +with a beamer/projector. It is derived from LaTeX’s article class and can +be used with with LaTeX, pdfLaTeX (and LuaLaTeX). The default "virtual +paper size" of presentations generated by this class corresponds to a 4:3 +(width:height) aspect ratio. Other aspect ratios for widescreen monitors +(16:9, 16x:0) may be selected. + +The elpres class requires: ifthen, fancyhdr, hyperref, graphicx, xcolor and +geometry. + +For enhanced features the packages ragged2e, overlays, wallpaper, eso-pic +and footmisc are useful. + +A homepage for the elpres project: http://vkiefel.de/elpres.html with +additional material. + +Changes in v0.5 +=============== + +New class options: *nofonts* (no font selection) and *navisymb* (inserts a +panel of symbols for navigation). New commands: *auvimm* (generates a link +to external audio, video files), *fromlinktext* and *totargettext* (create +links within a presentation). + +License +======= + +This work may be distributed and/or modified under the conditions of the +LaTeX Project Public License (LPPL). The latest version of this license is +available in the file: + + http://www.latex-project.org/lppl.txt + +Current maintainer is Volker Kiefel. diff --git a/macros/latex/contrib/elpres/elpres-example.pdf b/macros/latex/contrib/elpres/elpres-example.pdf new file mode 100644 index 0000000000..1c28afdc8c Binary files /dev/null and b/macros/latex/contrib/elpres/elpres-example.pdf differ diff --git a/macros/latex/contrib/elpres/elpres-example.tex b/macros/latex/contrib/elpres/elpres-example.tex index d081d125ca..bb25d110bb 100644 --- a/macros/latex/contrib/elpres/elpres-example.tex +++ b/macros/latex/contrib/elpres/elpres-example.tex @@ -1,56 +1,100 @@ -\documentclass[11pt,pdftex,helvetfont,4x3]{elpres} +\documentclass[12pt,pdftex,helvetfont,4x3]{elpres} \usepackage[latin1]{inputenc} -\usepackage{color} -\usepackage[perpage,para,symbol]{footmisc} +\usepackage[perpage,para,symbol,norule]{footmisc} \usepackage[document]{ragged2e} -\RaggedRight + +\definecolor{darkteal}{rgb}{0,0.34,0.34} +\definecolor{darkred}{rgb}{0.7,0.1,0.1} + +\newcommand{\ticolor}[1]{\textcolor{darkteal}{#1}} \begin{document} \begin{titlepage} \centering \distance{1} { - \Huge \bfseries \textcolor{blue}{Title of the presentation} \par + \Huge \bfseries \textcolor{darkred}{Title of presentation} \par } \vspace{1.3ex} \large Author\\[2ex]Date and place of presentation \distance{2} \end{titlepage} -\begin{psli}[Title of first page] -The first page +\begin{psli}[\ticolor{Title of first page}] +This is an example of a \LaTeX\ \texttt{itemize} list \begin{itemize} \item first line in an itemized list \item second line in an itemized list + \item third line in an itemized list \end{itemize} + + \end{psli} -\begin{psli}[Title of second page\footnote{footnotes are often not a good - idea for a presentation}] - -The second page with a nested, ``vertically compressed'' list +\begin{psli}[\ticolor{Title of second page\footnote{footnotes are often + not a good idea for a presentation}}] +% \raggedright +The second page with nested, ``vertically compressed'' lists using the +\texttt{citemize} and \texttt{cenumerate} environments. \begin{citemize} \item first line in an itemized list \item second line in an itemized list \begin{cenumerate} - \item first line of numbered list + \item first line of numbered list \item second line of numbered list \end{cenumerate} - \item final line in itemized list\footnote{\dots\ so there should be - good reasons to insert a second comment on the same page} + \item final line in itemized list\footnote{\dots\ it is therefore + useful to write comments into a single footnote paragraph in order + to save space} \end{citemize} -{\small For footnotes, the \texttt{footmisc} package, at least with the + +{\small For footnotes, the \texttt{footmisc} package, providing the options \texttt{perpage} and \texttt{symbol} is recommended. \par} \end{psli} +\begin{psli}[\ticolor{Title of third page}] + + \begin{cdescription} +\item[environment name:] \texttt{cdescription}, comparable to + \LaTeX s \texttt{description} environment + \item[used for:] vertically compressed lists with small ``titles'' +\end{cdescription} + +\end{psli} + \begin{rsli} -A final page for freely arranged text and -graphics\footnote{References to scientific publications may be added - as footnotes} +A final page with freely arranged text and +graphics using the \texttt{rsli} environment\footnote{References to the + source of figures or tables may be added as footnotes} + +{ \tiny +\begin{verbatim} + + + / \ + /---\ + / \ + / \ + / \ + / \ + + + + | | + | | + | | + | | + | | + | | + | | + +-------------+ +\end{verbatim} +\par} + +... guess, what is this?\\[0.6ex] +(A) House\\ +(B) Pencil + \end{rsli} \end{document} - diff --git a/macros/latex/contrib/elpres/elpres-manual.pdf b/macros/latex/contrib/elpres/elpres-manual.pdf index 045f8dd0c4..84953bc15c 100644 Binary files a/macros/latex/contrib/elpres/elpres-manual.pdf and b/macros/latex/contrib/elpres/elpres-manual.pdf differ diff --git a/macros/latex/contrib/elpres/elpres-manual.tex b/macros/latex/contrib/elpres/elpres-manual.tex index 3cbbd024ee..1fb50dddb6 100644 --- a/macros/latex/contrib/elpres/elpres-manual.tex +++ b/macros/latex/contrib/elpres/elpres-manual.tex @@ -8,12 +8,14 @@ \newcommand{\hoch}[1]{\raisebox{0.6ex}{#1}} \newcommand{\tief}[1]{\raisebox{-0.6ex}{#1}} \usepackage{url} +\usepackage{framed} +\usepackage{xcolor} -\title{\textsf{elpres} --- electronic presentations \\ with (PDF)\LaTeX} +\title{\textsf{elpres} --- electronic presentations \\ with (pdf)\LaTeX} \author{Volker Kiefel\thanks{volker dot kiefel at freenet dot de, http://vkiefel.de/elpres.html}} -\date{v0.4a\\[1.8ex] - January 24, 2018} +\date{v0.5\\[1.8ex] + July 12, 2020} \begin{document} \maketitle \thispagestyle{empty} @@ -25,25 +27,31 @@ \section{Introduction} -\textsf{Elpres} is a simple class for presentations to be shown on screen or -beamer. It is derived from \LaTeX's \texttt{article} class. \textsf{Elpres} -is primarily intended to be used with PDF\LaTeX{} or with \LaTeX, -\texttt{dvips} and Ghostview/Ghostscript. The default ``virtual paper size'' +The \textsf{elpres} class can be used for presentations on a screen, a +beamer or projector. It is derived from \LaTeX's \texttt{article} class and +may be used with \LaTeX{}, pdf\LaTeX{} (and Lua\LaTeX ). +The default ``virtual paper size'' of documents produced by this class: width=128mm, height=96mm corresponds to a -4:3 aspect ratio. Other aspect ratios for widescreen monitors may be selected -by class options. \textsf{Elpres} requires that the \texttt{ifthen}, -\texttt{fancyhdr} and \texttt{geometry} packages are available on the system. +4:3 (width:height) aspect ratio. Other aspect ratios for widescreen monitors +may be selected +by class options. The \textsf{elpres} class requires that the \texttt{ifthen}, +\texttt{fancyhdr}, +\texttt{hyperref}, +\texttt{graphicx}, +\texttt{xcolor} +and \texttt{geometry} packages are available on the system. Enhancements to \texttt{elpres} are easily made available by other packages, these include overlay support for incremental slides (package -\texttt{overlays}) hypertext elements (\texttt{hyperref} package) and slides +\texttt{overlays}) and slides with a background from a bitmap (\texttt{wallpaper}, \texttt{eso-pic} -packages). +packages). + \section{Installation} -Copy \texttt{elpres.cls} into a directory, where your \LaTeX-system can find -it and update the files database\footnote{e.\,g. by using the -\texttt{mktexlsr} or \texttt{texhash} command (TeXlive)}. +Copy \texttt{elpres.cls} into a directory, where +your \LaTeX-system can find it and update the files database\footnote{e.\,g. +by using the \texttt{mktexlsr} or \texttt{texhash} command (TeXlive)}. \section{Usage} @@ -54,13 +62,33 @@ The class is used with \documentclass[options]{elpres} \end{verbatim} -\textbf{Options of the \texttt{article} class} are also available to -\texttt{elpres}, e.\,g. \texttt{10pt}, \texttt{11pt}, \texttt{12pt} for -selection of font size. \textbf{\texttt{Elpres}-specific options} allow -selection of the font: \texttt{tmrfont} (Times Roman), \texttt{helvetfont} -(Helevetica), \texttt{cmfont} (Computer Modern), \texttt{sansfont} (Sans -Serif: default). Options for different screen aspect ratios: \texttt{4x3} -(default), \texttt{16x9}, \texttt{16x10}. +\textbf{\texttt{Elpres}-specific options}: for font selection + \texttt{tmrfont} (Times Roman), \texttt{helvetfont} +(Helvetica), \texttt{cmfont} (Computer Modern), \texttt{sansfont} (Sans +Serif: default) and \texttt{nofonts} (no font selection, +intended for use of \texttt{elpres} with Lua\LaTeX\ +with is own font selection mechanisms) are used. +Options for different screen aspect ratios: \texttt{4x3} +(default), \texttt{16x9}, \texttt{16x10}. The option \texttt{navisymb} +adds symbols for navigation to the presentation. +Options of the \texttt{article} class are also available for +\texttt{elpres} presentations, +e.\,g. \texttt{10pt}, \texttt{11pt}, \texttt{12pt} for +selection of font size. + +{ \sloppy +\textbf{\texttt{Elpres}-specific commands}: +\verb+\distance+ vertically adjusts text on a slide. +The \verb+\auvimm+\footnote{for \textbf{au}dio \textbf{vi}deo \textbf{m}edia} +command inserts a link to an external audio or video file. +Two commands: \verb+\fromlinktext+ and \verb+\totargettext+ +can be used for internal links within a presentation. + + +\textbf{\texttt{Elpres}-specific environments}: +the environments \texttt{psli} and \texttt{rsli} define ``slides'' in +\texttt{elpres}; \texttt{citemize}, \texttt{cenumerate} and +\texttt{cdescription} provide vertically compressed lists. A simple example document: @@ -98,19 +126,22 @@ A simple example document: \end{document} \end{verbatim} -%% Options to be used are \texttt{10pt}, \texttt{11pt}, \texttt{12pt} (font size), -%% \texttt{pdftex}, \texttt{dvips} -%% (if you use \texttt{graphicx} and/or \texttt{color} packages). -The title page can be created within the \texttt{titlepage} environment, the +%% Here a minimalistic example + +\subsection{Essential elements of an \texttt{elpres} presentation} + +The \textbf{title page} can be created within the \texttt{titlepage} environment, the \verb+\maketitle+ command is not available. -Slides may be created with the -\texttt{psli}-environment\footnote{\texttt{psli}: plain slide}, you may add +\textbf{Slides} may be created with the +\texttt{psli}-environment\footnote{\texttt{psli}: \textbf{pl}ain + \textbf{sl}ide}, you may add the title of the slide with the optional parameter. The contents of the slide are centered vertically. -Another environment generating a slide is -\texttt{rsli}\footnote{\texttt{rsli}: raw slide}: slides are written +Another environment generating a \textbf{slide} is +\texttt{rsli}\footnote{\texttt{rsli}: \textbf{ra}w \textbf{sl}ide}: +slides are written without title, contents are not vertically centered. @@ -126,21 +157,23 @@ option resets numbering for each new slide. For a presentation, the After inserting a new footnote, numbers or symbols are correctly inserted only after a second run of \LaTeX. -\subsection{Improving paragraph justification} +\subsection{Alternatives to \TeX's justified paragraphs} By default, \LaTeX\ produces justified paragraphs with lines of equal length, this may often not be appropriate for the usually very short lines of text in presentations. The \LaTeX\ \verb+\raggedright+ command has its own -deficiencies: by inhibiting hypenation, the text at the right margin will -often look too +deficiencies: by inhibiting hypenation in texts with rather short lines, +the right margin will often look too ragged. A solution is to use the \verb+\RaggedRight+ command of the -\texttt{ragged2e} package by Martin Schrder. +\texttt{ragged2e} package. -\subsection{Generate vertically compressed lists} +\subsection{Vertically compressed lists} -The \texttt{elpres} package provides a ``vertically compressed'' -\texttt{itemize}-environment: +As the spaces between lines may be too great with the \texttt{itemize} +environment, +the \texttt{elpres} package provides a ``vertically compressed'' +\texttt{citemize}-environment: \begin{verbatim} \begin{citemize} @@ -169,8 +202,7 @@ parameters can be added in the format: \end{itemize} \end{verbatim} -The ``vertically -compressed'' list can then be obtained with +The ``vertically compressed'' list can then be obtained with \begin{verbatim} \begin{itemize}[nosep] @@ -179,8 +211,8 @@ compressed'' list can then be obtained with \end{itemize} \end{verbatim} -The \texttt{enumitem} package is also able to modify the \texttt{enumerate} and -description \texttt{environments}. +Similarly, the \texttt{enumitem} package is also able to modify the +\texttt{enumerate} and description \texttt{environments}. @@ -326,54 +358,200 @@ yellow as background: For more details on \texttt{overlays}, see the documentation of the package. -\subsection{Create a ``handout'' from a presentation} + +\subsection{Navigation symbols} +\label{sec:NavigationSymbols} + +With the \texttt{navisymb} option a panel with navigation symbols +(colored in light gray) appears +in the right lower corner of the presentation:\\ + + +{ \setlength{\parindent}{2em} + \indent + \textbf{\texttt{$\ll$ $<$ $>$ $\gg$ $\leftarrow$ $\rightarrow$ [n]}} +}\\ + +These commands ($\ll$: jump to the first page, +$<$: go to the previous page, $>$: go to the next page, +$\gg$: jump to the last page, $\leftarrow$: +go back in history, $\rightarrow$: go forward in history, +\texttt{[n]}: prompt for a +page number) +work with Adobe Acrobat Reader (Windows), and (with the exception of +\texttt{$\leftarrow$}, \texttt{$\rightarrow$} and \verb+[n]+) +with \texttt{evince} (Linux). +Some of these functions also work in presentation-mode +of the ``internal'' PDF-viewer in recent versions of the +\texttt{Firefox}-browser (Linux, Windows). + + +\subsection{Call multimedia content from a presentation} +\label{sec:MultimediaContent} + + +The command \verb+\auvimm{text}{media-file}+ inserts \texttt{text} with +a link, which calls the default application for audio or video media files +\texttt{media-file}. +This seems to work with Adobe Acrobat Reader (Windows) and with +\texttt{evince} (Linux). +An example for using this command: + +\begin{verbatim} + \auvimm{[sound-file]}{./audiofile.mp3} +\end{verbatim} + +This produces the (text-based) ``button'' \texttt{[sound-file]}. If you +hit it with the mouse pointer it will call the default application for +audio files. This approach requires that you keep the presentation file +together with the multimedia files in the same folder, \textbf{also at + the time of + the presentation}. On an unknown computer system (where you have to show +your presentation) you should test this aspect of your presentation. Sometimes +a call to an external program might be blocked due security reasons in Acrobat +Reader. + +\begin{leftbar} +This \texttt{elpres}-command should be considered experimental. +Its behavior depends on the pdf-reader and the configuration of the OS. +\end{leftbar} +\subsection{Prepare a ``handout'' from a presentation} \label{secHandout} -If you wish to generate a handout from your presentation with more than one -pages on a printed page, you may process a PDF presentation file with -\texttt{pdfjam}\footnote{which regerettably is only available on -Linux or other Unix-like systems}. -The following command: + +In advance of a lecture it is often expected that you +prepare a ``handout'' from your presentation with more than one +pages on a printed page. Therefore +you have several options, two of them are described +here. + +\subsubsection{\LaTeX\ article document with a series of single-page pdf-files included} + +One solution to this problem is (1) to generate a series of single-page +pdf-files and (2) to create a pdf\LaTeX\ document with the single +pages included. + +\textbf{(1)} can be done with \texttt{gs} (the Ghostscript program): + +\begin{verbatim} + gs -dNOPAUSE -dBATCH -sDEVICE=pdfwrite -sOutputFile=page_%03d.pdf in.pdf +\end{verbatim} + +with \texttt{in.pdf} as the initial presentation. The syntax of \texttt{gs} +is described in detail on the ghostscript +website\footnote{\url{https://www.ghostscript.com/doc/current/Use.htm}}. +An alternative to \texttt{gs} is \texttt{pdftk} tool: \begin{verbatim} - pdfjam --nup 2x3 --scale 0.9 -o new.pdf presentation.pdf '1-4,7-17,22' + pdftk in.pdf burst output page_%02d.pdf +\end{verbatim} + +The syntax of \texttt{pdftk} is explained in the documentation +(\texttt{pdftk~--help}). + +\textbf{(2)} an example for a \LaTeX\ document which can serve as handout: + +\begin{verbatim} + \documentclass[12pt]{article} + \usepackage[pdftex]{graphicx} + \usepackage[latin1]{inputenc} + \usepackage[a4paper,hmargin=2.4cm,top=24mm,bottom=28mm]{geometry} + \newcommand{\PictScaleFact}{0.45} + + \begin{document} + \centering + \fbox{\includegraphics[width=\PictScaleFact\textwidth]{page_001.pdf}} + \hspace{5mm} + \fbox{\includegraphics[width=\PictScaleFact\textwidth]{page_002.pdf}} + \\[2ex] + \fbox{\includegraphics[width=\PictScaleFact\textwidth]{page_003.pdf}} + \hspace{5mm} + % ... + \fbox{\includegraphics[width=\PictScaleFact\textwidth]{page_008.pdf}} + % ... + \end{document} +\end{verbatim} + +\subsubsection{Convert presentation pdf-file directly into handout file with \texttt{pdfjam}} + +With the following command: + +\begin{verbatim} + pdfjam --nup 2x4 --frame true --scale 0.9 -o new.pdf in.pdf '1-4,6-22' \end{verbatim} \begin{sloppypar} -creates a ``handout'' PDF document (\texttt{new.pdf}) with the slides 1-4,7-17 -and 22 of \texttt{presentation.pdf} arranged in two columns and three rows. -With the additional option \texttt{--frame~true}, \texttt{pdfjam} draws a box +\texttt{pdfjam}\footnote{which regerettably is only available on +Linux or other Unix-like systems} +creates a ``handout'' PDF document (\texttt{new.pdf}) fom +\texttt{in.pdf} with the slides nr. 1-4,6-22 +arranged in two columns and four rows. +With the additional option ``\texttt{--frame~true}'', +\texttt{pdfjam} draws a box around each slide. More details can be found in the \texttt{pdfjam} -man page. On Windows systems Acrobat reader may be helpful to print -handout documents with more than one slide per printed page. +man page and the project +website\footnote{https://github.com/DavidFirth/pdfjam/blob/master/README.md}. \end{sloppypar} + + \subsection{Create presentations with hypertext elements} \label{secHypertext} -You may use the hyperref package. As you normally will not insert -\verb+\section{}+-like commands, it is easier to define links with +You may use two commands \verb+\fromlinktext{}{}+ and \verb+\totargettext{}{}+ +for ``hypertext features''. As an example: as you normally will not insert +\verb+\section{}+-like commands and therefore do not generate a ``table of +contents''-like page or a menu in \texttt{elpres}-presentations, you are able +define links with: \begin{verbatim} - \hypertarget{target-name}{text} + \totargettext{text}{link-label} \end{verbatim} +% \hypertarget{target-name}{text} + which can be addressed by \begin{verbatim} - \hyperlink{target-name}{text} + \fromlinktext{text}{link-label} \end{verbatim} -The hyperref package will produce a warning message, if you use the -titlepage-environment (this is inherited from the article class). To avoid -the warning you can use the \texttt{rsli}-environment for the titlepage and use -\verb+\thispagestyle{empty}+ to suppress the page number on the title. +% \hyperlink{target-name}{text} + +If you use these commands to generate a \textbf{menu page} (as a hyperlinked +table of contents) with items pointing to +specific slides: +\texttt{link-label} acts as label, \texttt{text} in the +\verb+\fromlinktext+ command is converted to a link (e.\,g. on a menu-page). +If you click on this text ``button'', you jump to +the \texttt{text} labelled with +\verb+\totargettext+; \texttt{link-label} has to be identical in a +\verb+\fromlinktext+ and \verb+\totargettext+ pair, +\texttt{text} in the link +and the target, of course need not to be identical. + +The default for the link border color is red, it may be changed with +\verb+\hypersetup{}+, a command from the \texttt{hyperref} +package\footnote{both, \texttt{\textbackslash totargettext} and +\texttt{\textbackslash fromlinktext} are +are redefinitions of commands from the \texttt{hyperref} package}. +The option for the color of the frame around the link is +\texttt{linkbordercolor}, +colors must be defined whith three figures \texttt{[0..1]} according to the RGB +color model: -\subsection{Fill background of a presentation with bitmaps} +\begin{verbatim} + \hypersetup{linkbordercolor={0.6 0.6 0.6}} +\end{verbatim} +This defines a light gray color for the link border, more details on +\verb+\hypersetup{}+ are +described in the documentation of the \texttt{hyperref} package. + +\subsection{Fill background of a presentation with bitmaps} \label{secBackgroundWallpaper} @@ -441,7 +619,7 @@ This class is distributed under the \textsl{\LaTeX{} Project Public License} \url{http://www.latex-project.org/lppl.txt}. No warranty is provided for this work (as stated in the LPPL). -\section{Versions} +\section{Version history} \textbf{v0.1} (19.6.2004): initial version. \textbf{v0.2} (1.9.2004): page numbers now changed to footnotesize, left and @@ -458,7 +636,7 @@ added). \textbf{v0.2e} (15.04.2005): Documentation completed (sections \ref{secBackgroundEsopic} and \ref{secHandout} added). \textbf{v0.3} (12.08.2005): new (class) options for font selection: -\texttt{tmrfont} (Times Roman), \texttt{helvetfont} (Helevetica), +\texttt{tmrfont} (Times Roman), \texttt{helvetfont} (Helvetica), \texttt{cmfont} (Computer Modern), \texttt{sansfont} (Sans Serif: default). Documentation updated, sections \ref{secInclGraphicsFiles} and \ref{secTwoColumns} added. @@ -468,8 +646,15 @@ environments modified; documentation completed: packages for use with \texttt{elpres}: \texttt{enumitem} (alternative list environments), \texttt{overlays} (overlay support: incremental slides); section \ref{secHandout} was completely rewritten. -\textbf{v0.4a} (24.01.2018): Documentation completed +\textbf{v0.4a} (24.01.2018): Documentation completed. +\textbf{v0.5} (12.07.2020): New class options: \texttt{nofonts} +(no font selection) and \texttt{navisymb} (inserts a panel of +symbols for navigation), new commands: \verb+auvimm+ (generates +a link to external audio, video files), \verb+\fromlinktext+ and +\verb+\totargettext+ (create links within a presentation). +Documentation has been partly rewritten. + \end{document} -% vim:set spell:set fileencoding=latin1: +% vim:spell:fileencoding=latin1:lines=55: diff --git a/macros/latex/contrib/elpres/elpres.cls b/macros/latex/contrib/elpres/elpres.cls index 11ccb14b62..b1786496d3 100644 --- a/macros/latex/contrib/elpres/elpres.cls +++ b/macros/latex/contrib/elpres/elpres.cls @@ -1,5 +1,5 @@ \NeedsTeXFormat{LaTeX2e} -\ProvidesClass{elpres}[2018/01/24 class for plain electronic presentations] +\ProvidesClass{elpres}[2020/07/12 class for plain electronic presentations] % % 2004/06/19 v0.1 - initial version % @@ -18,9 +18,19 @@ % % 2018/01/24 v0.4a - documentation completed % +% 2020/07/12 v0.5 - class option `navisymb' added; elpres now also requires +% the hyperref and xcolor packages. New commands: +% `auvimm', `fromlinktext' `totargettext'. +% new class option `nofonts' for use with lualatex. +% - documentation updated +% +% % Options: select fonts \newcommand{\fontna}{initialisiert} +\DeclareOption{nofonts}{% + \renewcommand{\fontna}{withoutfont}% +} \DeclareOption{tmrfont}{% \renewcommand{\familydefault}{\rmdefault}% \renewcommand{\fontna}{tmrfo}% @@ -54,12 +64,18 @@ } +% Option: navigation symbols +\newcommand{\navigation}{withoutnavigationsymb} +\DeclareOption{navisymb}{% + \renewcommand{\navigation}{withnavi}% +} + \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} \ProcessOptions\relax \LoadClass{article} - \RequirePackage{ifthen} +\RequirePackage{xcolor} \ifthenelse{\equal{\screenformat}{scr4x3}}{% \RequirePackage[foot=10.2pt,head=0pt,paperwidth=128mm,paperheight=96mm,left=5mm,top=5mm,right=7mm,bottom=8mm]{geometry}% @@ -73,7 +89,10 @@ \RequirePackage[foot=10.2pt,head=0pt,paperwidth=160mm,paperheight=100mm,left=5mm,top=5mm,right=7mm,bottom=8mm]{geometry}% }{} + +\RequirePackage[hyperfootnotes=false]{hyperref} \RequirePackage{fancyhdr} + \renewcommand{\headrulewidth}{0mm} %% \pagestyle{fancy} %% \rfoot{\thepage} @@ -85,6 +104,7 @@ {Please use ``titlepage'' environment instead}% } + \fancypagestyle{pres}{% \fancyhf{}% \fancyfoot[RO]{\footnotesize \thepage}% @@ -92,6 +112,22 @@ \pagestyle{pres} +%% menu for navigation symbols +\ifthenelse{\equal{\navigation}{withnavi}}{% +\hypersetup{menubordercolor=white}% +\rfoot{% + \scriptsize% + \textcolor[gray]{0.6}{% + \Acrobatmenu{FirstPage}{$\ll$}\hspace{0.5em}% + \Acrobatmenu{PrevPage}{$<$}\hspace{0.5em}% + \Acrobatmenu{NextPage}{$>$}\hspace{0.5em}% + \Acrobatmenu{LastPage}{$\gg$}\hspace{0.5em}% + \Acrobatmenu{GoBack}{$\leftarrow$}\hspace{0.5em}% + \Acrobatmenu{GoForward}{$\rightarrow$}\hspace{0.5em}% + \Acrobatmenu{GoToPage}{[n]}\hspace{1.2em}% + }\footnotesize \thepage}% +}{}% + \newcommand{\distance}[1]{\vspace*{\stretch{#1}}} \newcommand{\abstand}[1]{\vspace*{\stretch{#1}}} @@ -142,5 +178,11 @@ \ifthenelse{\equal{\fontna}{tmrfo}}{\RequirePackage{mathptmx}\RequirePackage{courier}}{} \ifthenelse{\equal{\fontna}{helvetfo}}{\RequirePackage[scaled=0.92]{helvet}\RequirePackage{courier}}{} \ifthenelse{\equal{\fontna}{initialisiert}}{\renewcommand{\familydefault}{\sfdefault}}{} +\ifthenelse{\equal{\fontna}{withoutfont}}{}{} + +\newcommand{\auvimm}[2]{\href{#2}{#1}} + +\newcommand{\fromlinktext}[2]{\hyperlink{#2}{#1}} +\newcommand{\totargettext}[2]{\hypertarget{#2}{#1}} % vim: syntax=tex tw=2048 ai diff --git a/macros/latex/contrib/polytable/README b/macros/latex/contrib/polytable/README index 88ba930183..59e501ab3e 100644 --- a/macros/latex/contrib/polytable/README +++ b/macros/latex/contrib/polytable/README @@ -1,6 +1,6 @@ This is the polytable package. The license is LPPL. -The package depends on lazylist.sty, as available from +The package depends on lazylist.sty, as available from "CTAN:/macros/latex/contrib/lazylist.sty". To install and get documentation, run the following commands: @@ -11,4 +11,4 @@ latex polytable.dtx Please report bugs to "polytable@andres-loeh.de". -Andres Loeh, November 2005 +Andres Löh, July 2020 diff --git a/macros/latex/contrib/polytable/polytable.dtx b/macros/latex/contrib/polytable/polytable.dtx index fb9219492b..e44bd03f57 100644 --- a/macros/latex/contrib/polytable/polytable.dtx +++ b/macros/latex/contrib/polytable/polytable.dtx @@ -2,18 +2,21 @@ %<*driver> \ProvidesFile{polytable.drv} \documentclass{ltxdoc} +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\usepackage{lmodern} \usepackage[info]{polytable} \begin{document} \DocInput{polytable.dtx} \end{document} % % -% Copyright (C) 2003--2013 by Andres Loeh +% Copyright (C) 2003--2020 by Andres Loeh % % \fi % % \ProvidesFile{polytable.dtx} -% [2013/07/08 v0.8.5 `polytable' package (Andres Loeh)] +% [2020/07/14 v0.8.6 `polytable' package (Andres Loeh)] % \GetFileInfo{polytable.dtx} % % \title{The \textsf{polytable} package} @@ -53,6 +56,7 @@ % \changes{v0.8.4}{2009/11/01}{Make ptb output more stable.} % \changes{v0.8.5}{2013/07/18}{Work around lazylist name clash % with unicode-math.} +% \changes{v0.8.6}{2020/07/14}{Fix bug with column command redefinitions.} % % \section{Introduction} % @@ -83,10 +87,10 @@ % The strength of this approach is that it implicitly handles % cases where different lines have different alignment properties. % Not all column names have to occur in all lines. -% +% % \section{A complete example} % -% Figure~\ref{tab:example} +% Figure~\ref{tab:example} % is an example that is designed to show the % capabilities of this package. In particular, it is \emph{not} % supposed to look beautiful. @@ -95,7 +99,7 @@ % \centering % \begin{ptboxed} % \defaultcolumn{l|}\column{.}{|l|} -% \> left +% \> left % \=3 first of three \> second of three \> third of three % \=r right \\ % \defaultcolumn{r|}\> left \=2 middle 1/2 \> middle 2/2 \=r right \\ @@ -112,8 +116,8 @@ % some text on the left and on the right, but the middle part % follows two different patterns: the first and the third line % have three middle columnss that should be aligned, the second -% and the fourth line have two (right-aligned) middle columns -% that should be aligned, but otherwise independent of the three +% and the fourth line have two (right-aligned) middle columns +% that should be aligned, but otherwise independent of the three % middle columns in the other lines. % % Vertical bars are used to clarify where one column ends and @@ -131,7 +135,7 @@ % \begin{verbatim} % \begin{ptboxed} % \defaultcolumn{l|}\column{.}{|l|} -% \> left +% \> left % \=3 first of three \> second of three \> third of three % \=r right \\ % \defaultcolumn{r|}\> left \=2 middle 1/2 \> middle 2/2 \=r right \\ @@ -144,7 +148,7 @@ % First, columns are declared, including the vertical lines. % Note that there is a final column |end| being declared % that is only used as the end column in the |\fromto| statements. -% A future version of this package +% A future version of this package % will probably get rid of the need to define % such a column. % After the column definitions, the lines are typeset by a @@ -265,7 +269,7 @@ % % With lhs2\TeX, there is now a preprocessor available that preserves % the source code's internal alignment by mapping the output onto -% \textsf{polytable}'s environments. +% \textsf{polytable}'s environments. % Figure~\ref{tab:haskell} is an example of how % the output of lhs2\TeX\ might look like. % @@ -308,7 +312,7 @@ % \column{rel}{c} % \column{rhs}{l} % \>[left] \CLASS\ (\Eq\TA)\Rightarrow\Ord\TA\WHERE \\ -% \>[left] \qquad\ +% \>[left] \qquad\ % \>[body] \HsVar{compare} % \>[rel] :: % \>[rhs] \TA\rightarrow\TA\rightarrow\HsCon{Ordering} \\ @@ -402,7 +406,7 @@ % \textsf{lazylist} package, which provides an implementation of % the lambda calculus using fully expandable control sequences. % Unfortunately, |lazylist.sty| is not included in most common -% \TeX\ distributions, so you might need to fetch it from CTAN +% \TeX\ distributions, so you might need to fetch it from CTAN % separately. % % \section{Reference} @@ -420,7 +424,7 @@ % must be declared. % % \DescribeMacro{\defaultcolumn} -% Using a statement of the form +% Using a statement of the form % |\defaultcolumn{|\meta{spec}|}|, implicit columns can % be activated. All undefined columns that are encountered % will be assumed to have format string \meta{spec}. @@ -438,7 +442,7 @@ % The environment |pboxed| % typesets the material in boxes of the calculated length, but in % normal paragraph mode. The advantage is that -% there can be page breaks within the table. +% there can be page breaks within the table. % Note that you should start a new (probably nonindented) % paragraph before beginning a |pboxed|. All lines that a |pboxed| % produces are of equal length, so it should be possible to center @@ -448,7 +452,7 @@ % pre-wrapped in a |tabular| or |array| environment, % respectively, and % thus not page-breakable but less fragile (or should I just -% say: easier to use) than the unwrapped |pboxed|. +% say: easier to use) than the unwrapped |pboxed|. % With those, there % is no need for |ptabular| and |parray| anymore -- % which were directly based on (and translated into) usual @@ -485,7 +489,7 @@ % document, and destroy your layout. % % \DescribeMacro{\column} -% With |\column[|\meta{dimen}|]{|\meta{columnid}|}{|\meta{spec}|}|, +% With |\column[|\meta{dimen}|]{|\meta{columnid}|}{|\meta{spec}|}|, % a new column % \meta{columnid} is specified. The name of the column can be % any sequence of alphanumerical characters. The \meta{spec} is @@ -493,12 +497,12 @@ % the same constructs that can be used in format strings of normal % tables or arrays. % However, it must only contain the description for \emph{one} -% column. +% column. % -% As long as the save/restore feature (explained below) is not used, +% As long as the save/restore feature (explained below) is not used, % |\column| definitions are local to one table. % One can define a column multiple times within one table: -% a warning will be produced, +% a warning will be produced, % and the second format string will be used for the complete table. % % Columns must be defined before use when implicit columns using @@ -565,7 +569,7 @@ % % \DescribeMacro{\\} % \DescribeMacro{\nextline} -% The command |\\| (or, now deprecated, |\nextline|) ends one line +% The command |\\| (or, now deprecated, |\nextline|) ends one line % and begins the next. % There is no need to end the last line. One can pass an optional % argument, as in |\\[|\meta{dimen}|]|, that will add @@ -576,11 +580,11 @@ % The contents of the table are processed multiple times because % the widths of the entries are measured. Global assignments that % modify registers and similar things can thus result in unexpected -% behaviour. +% behaviour. % New in v0.7: \LaTeX\ counters (i.e., counters defined by % |\newcounter|) are protected now. They will be reset after % each of the trial runs. -% +% % \subsection{Saving column width information} % % Sometimes, one might want to reuse not only the same column, but @@ -654,7 +658,7 @@ % \fromto{rel}{rhs}{::} % \fromto{rhs}{end}{\TA\rightarrow\TA\rightarrow\HsCon{Bool}} % \\[1ex] -% \fromto{body}{end}{\mbox{--- Minimal complete definition: +% \fromto{body}{end}{\mbox{--- Minimal complete definition: % $(\leq)$ or $\HsVar{compare}$}} % \\ % \fromto{body}{end}{\mbox{--- using $\HsVar{compare}$ can be more efficient @@ -667,7 +671,7 @@ % of the class methods have default definitions. First, we can % define $\HsVar{compare}$ in terms of $(\leq)$. The result type % of $\HsVar{compare}$ is an $\HsCon{Ordering}$, a type consisting -% of only three values: $\HsCon{EQ}$ for ``equality'', +% of only three values: $\HsCon{EQ}$ for ``equality'', % $\HsCon{LT}$ for ``less than'', and $\HsCon{GT}$ for ``greater % than''. % @@ -749,7 +753,7 @@ %<*package> \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{polytable}% - [2013/07/18 v0.8.5 `polytable' package (Andres Loeh)] + [2020/07/14 v0.8.6 `polytable' package (Andres Loeh)] % \end{macrocode} % New in v0.7.2: % The \textsf{amsmath} package clashes with \textsf{lazylist}: @@ -864,7 +868,7 @@ % \end{macro} % \end{macro} % \end{macro} -% +% % \begin{macro}{\PT@debug} % \begin{macro}{\PT@info} % \begin{macro}{\PT@debug@} @@ -909,7 +913,7 @@ \else \PT@aligndim@#1#2#3\space\space\space\space\space\space\space\space\@@ \fi} - + \def\PT@aligndim@#1.#2#3#4#5#6#7#8#9\@@{% \ifnum#1<10 \space\fi \ifnum#1<100 \space\fi @@ -964,7 +968,7 @@ \def\PT@listopmacro #1#2#3% #1 #3 to the list #2 {\def\PT@temp{#1{#3}}% \expandafter\expandafter\expandafter - \def\expandafter\expandafter\expandafter + \def\expandafter\expandafter\expandafter #2\expandafter\expandafter\expandafter {\expandafter\PT@temp\expandafter{#2}}} @@ -1156,7 +1160,7 @@ % \end{macrocode} % \end{macro} % \begin{macro}{\PT@getwidths} -% Here, we make as many test runs as are necessary to +% Here, we make as many test runs as are necessary to % determine the correct column widths. % \begin{macrocode} \def\PT@getwidths @@ -1210,7 +1214,7 @@ % After the first run, we print extra information. % We use the contents of the macro |\column| to check % whether we are in the first run, because it will be -% reset below for all other runs to do nothing. +% reset below for all other runs to do nothing. % \begin{macrocode} \ifx\column\PT@otherrun@column \else @@ -1225,7 +1229,16 @@ % Therefore, we make sure that the |\column| command % won't do much in the other runs. Also, saving and % restoring columns is no longer needed. +% +% Note that redefining just |\column| or just +% |\PT@firstrun@column| is not enough. In the former +% case, on the next trial run, |\PT@getwidths| will +% restore the old definition. In the latter case, if +% there is no additional trial run, the typesetting +% run will be performed with the wrong definition. +% TODO: I think similar issues exist with saving/restoring? % \begin{macrocode} + \let\column \PT@otherrun@column \let\PT@firstrun@column \PT@otherrun@column \let\savecolumns \PT@gobbleoptional \let\restorecolumns \PT@gobbleoptional @@ -1345,7 +1358,7 @@ % \end{macrocode} % The array environments keep each line in a group; therefore % |\PT@resetcolumn|, when executed during the linebreak, will -% not affect the current column counters. By having +% not affect the current column counters. By having % |\PT@resetcolumn| before entering the environment, we ensure % that the group reset will have the correct effect anyway. % \begin{macrocode} @@ -1353,7 +1366,7 @@ % \end{macrocode} % Now we start the tabular environment with the % computed preamble. We redefine the |\\| to whatever -% the environment dictates. +% the environment dictates. % \begin{macrocode} \PT@begin% % \end{macrocode} @@ -1362,7 +1375,7 @@ \the\PT@toks \PT@fill% new in 0.7.3: balance the last line % \end{macrocode} -% End the array, close the group, close the environment. +% End the array, close the group, close the environment. % We are done! % \begin{macrocode} \PT@finalize% finalize the queue (possibly close file) @@ -1384,7 +1397,7 @@ % The macro |\PT@from| is bound to |\=| in a polytable environment, % and used to move to the named column specified by its argument. The % previous column is closed. The variant |\PT@fromopt| is bound to -% |\>| and takes an optional argument instead of a mandatory, which defaults +% |\>| and takes an optional argument instead of a mandatory, which defaults % to the current column name followed by a single dot |.|. We use an % empty default which is then redefined to make it easier for the % user to use the default definition (TODO: explain better). @@ -1590,7 +1603,7 @@ % \begin{macrocode} \@ifundefined{PT@col@#2.max}% {\@namedef{PT@col@#2.max}{#1}% - \expandafter\let\csname PT@col@#2.trusted\endcsname\PT@true}{}% + \expandafter\let\csname PT@col@#2.trusted\endcsname\PT@true}{}% \ignorespaces} % \end{macrocode} % \end{macro} @@ -1809,7 +1822,7 @@ % \end{macro} % % \begin{macro}{\PT@TeXif} -% This is an improved version of \textsf{lazylist}'s |\TeXif|. +% This is an improved version of \textsf{lazylist}'s |\TeXif|. % It does have an additional |\relax| to terminate the condition. % The |\relax| is gobbled again to keep it fully expandable. % \begin{macrocode} @@ -1871,7 +1884,7 @@ \edef\PT@currentcol{\Head{\Tail\PT@sortedlist}}% \fi \edef\PT@currentcol@{\PT@StripColumn\PT@currentcol}% - \PT@typeout@{adding implicit fromto at eol from \PT@currentcol@ + \PT@typeout@{adding implicit fromto at eol from \PT@currentcol@ \space to \PT@lastcol@}% \PT@expanded{\PT@expanded\fromto\PT@currentcol@}\PT@lastcol@ \fi @@ -1958,8 +1971,8 @@ % we want it set normally dugin |\PT@preparescan|. % \begin{macrocode} \def\PT@preparescan#1#2% -% First, we check that both columns are defined. This will -% actually define the columns if implicit column definitions are +% First, we check that both columns are defined. This will +% actually define the columns if implicit column definitions are % enabled. % \begin{macrocode} {\PT@checkcoldefined{#1}% @@ -1996,7 +2009,7 @@ % We split the preamble at the position of the |\@sharp|, using % some tricks to make sure that there really is precisely one % occurrence of |\@sharp| in the resulting preamble code, and -% producing an error otherwise. The splitting defines +% producing an error otherwise. The splitting defines % |\PT@pre@preamble| and |\PT@post@preamble|. With those and % the computed |\PT@colwidth|, the scan is successfully prepared. % \begin{macrocode} @@ -2078,10 +2091,10 @@ % can check whether all untrusted widths are conditionally trusted. % % We write the final, the maximum widths, into the auxiliary file. -% We perform the +% We perform the % write operation when we are sure that a specific set is % no longer used. This is the case when we save a new set under the -% same name, or at the end of the document. The command +% same name, or at the end of the document. The command % |\PT@verifywidths| takes care of this procedure. % This command will also check if a rerun is necessary, and issue % an appropriate warning if that should be the case. @@ -2292,7 +2305,7 @@ \PT@typeout@{Verification for #2 successful.}} % \end{macrocode} % \end{macro} -% +% % \begin{macro}{\PT@save@table} % Here we prepare to write maximum column widths to the % |.aux| file. diff --git a/macros/latex/contrib/polytable/polytable.pdf b/macros/latex/contrib/polytable/polytable.pdf index 2f267be0e5..be39b82d82 100644 Binary files a/macros/latex/contrib/polytable/polytable.pdf and b/macros/latex/contrib/polytable/polytable.pdf differ diff --git a/macros/latex/contrib/schooldocs/README.md b/macros/latex/contrib/schooldocs/README.md new file mode 100644 index 0000000000..ecb91d93da --- /dev/null +++ b/macros/latex/contrib/schooldocs/README.md @@ -0,0 +1,31 @@ +# The schooldocs package - Various layout styles for school documents + + +## Presentation + +The purpose of this package is to provide several layout styles for school documents. +It is usefull for exercices sheets, exams, course materials. +The package sets the page geometry (dimensions of text and margins) +and the title typesetting; +the various styles define the header, footer and title formatting, +Many features are freely configurable. + + +## Installation + +- run LaTeX on schooldocs.ins, you obtain the file schoodocs.sty, +- if then you run pdfLaTeX on schooldocs.dtx you get the file schooldocs.pdf which is also in the archive, +- put the files schooldocs.sty and schooldocs.pdf in your TeX Directory Structure. + + +## Author + +Antoine Missier + +Email: antoine.missier@ac-toulouse.fr + + +## License + +Released under the LaTeX Project Public License v1.3 or later. +See http://www.latex-project.org/lppl.txt diff --git a/macros/latex/contrib/schooldocs/schooldocs-examples.pdf b/macros/latex/contrib/schooldocs/schooldocs-examples.pdf new file mode 100644 index 0000000000..96ca7b7836 Binary files /dev/null and b/macros/latex/contrib/schooldocs/schooldocs-examples.pdf differ diff --git a/macros/latex/contrib/schooldocs/schooldocs.dtx b/macros/latex/contrib/schooldocs/schooldocs.dtx new file mode 100644 index 0000000000..284d239bcd --- /dev/null +++ b/macros/latex/contrib/schooldocs/schooldocs.dtx @@ -0,0 +1,987 @@ +% \iffalse meta-comment +% +% Copyright (C) 2020 by Antoine Missier +% ---------------------------------------------------------------------- +% +% This file may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in: +% +% http://www.latex-project.org/lppl.txt +% +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% \fi +% +% \iffalse +%<*driver> +\ProvidesFile{schooldocs.dtx} +% +%\NeedsTeXFormat{LaTeX2e}[2005/12/01] +%\ProvidesPackage{schooldocs} +%<*package> + [2020/07/13 v1.0 .dtx schooldocs file] +% +% +%<*driver> +\documentclass{ltxdoc} +\usepackage[utf8]{inputenc} +\usepackage[T1]{fontenc} +\usepackage[english]{babel} +\usepackage{lmodern} +\usepackage{lipsum} +\usepackage{hyperref} +\usepackage{boxedminipage2e} +\usepackage{schooldocs} +%\usepackage{geometry} +\geometry{textwidth=355pt,vmarginratio=1:1,hmarginratio=3:2} +% modified by schoodocs loading, very close from the default geometry used by ltxdoc + +\newcommand{\bs}{\textbackslash} +\setlength{\fboxsep}{13pt} +\newlength{\mpwd} \setlength{\mpwd}{5.25cm} +\newenvironment{stylex}{\begin{boxedminipage}[c][1.3\mpwd][t]{\mpwd}\tiny + }{\end{boxedminipage}} +\newcommand*{\centered}[1]{{\setlength{\parskip}{0pt}\par\noindent\hfill + #1\hfill\mbox{}}} +\providecommand\headtitlestyle{\scshape} +\providecommand\headsubjectstyle{\scshape} +\providecommand\schoolstyle{\scshape} + +%\EnableCrossrefs +%\CodelineIndex +%\RecordChanges + +\title{The \textsf{schooldocs} package}%\thanks{This document +% corresponds to \textsf{schooldocs}~\fileversion, dated \filedate.}} +\subject{Antoine Missier \\ % + \texttt{antoine.missier@ac-toulouse.fr}} +\date{July 13, 2020, \fileversion} + +\hypersetup{% + colorlinks, + linkcolor=blue, + pdftitle={schoodocs}, + pdfsubject={LaTeX package}, + pdfauthor={Antoine Missier} + } + +\begin{document} + \DocInput{schooldocs.dtx} + \PrintChanges + \PrintIndex +\end{document} +% +% \fi +% +% \CheckSum{792} +% +% \CharacterTable +% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z +% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z +% Digits \0\1\2\3\4\5\6\7\8\9 +% Exclamation \! Double quote \" Hash (number) \# +% Dollar \$ Percent \% Ampersand \& +% Acute accent \' Left paren \( Right paren \) +% Asterisk \* Plus \+ Comma \, +% Minus \- Point \. Solidus \/ +% Colon \: Semicolon \; Less than \< +% Equals \= Greater than \> Question mark \? +% Commercial at \@ Left bracket \[ Backslash \\ +% Right bracket \] Circumflex \^ Underscore \_ +% Grave accent \` Left brace \{ Vertical bar \| +% Right brace \} Tilde \~} +% +% +% \changes{v0.0}{2010/09/01}{Initial personal version} +% \changes{v0.1}{2020/01/05}{Initial documentation in french} +% \changes{v0.2}{2020/05/04}{Examples file} +% \changes{v1.0}{2020/07/13}{Initial public version with documentation in english} +% +% \GetFileInfo{schooldocs.dtx} +% +% \maketitle +% +% \section{Introduction} +% +% The purpose of this package is to provide several layout styles for school documents. +% It can be used for exercices sheets, exams, course materials. +% The package sets the page geometry (dimensions of text and margins) +% and the title typesetting; +% the various \emph{styles} define the header, footer and title formatting, +% Many features are freely configurable. +% Six different styles are proposed which are named: +% \begin{center} \bfseries +% \hfill classic \hfill elegant \hfill modern \hfill soft +% \hfill exam \hfill collection \hfill \mbox{} +% \end{center} +% If the document is an exam subject to be completed and returned, +% we have a particular style, \textbf{identity}, in which +% left and center parts of the header are replaced by the words +% \textsf{\identityname} and \textsf{\identityforename}. +% +% \medskip +% The styles are presented in paragraph \ref{par:styles} +% and the file \href{run:schooldocs-examples.pdf}{\textsf{schooldocs-examples.pdf}} +% shows the result of each. +% +% \section{Usage} +% +% \subsection{Choosing a style} +% After loading the package with |\usepackage{schooldocs}|, +% we define the style by placing |\pagestyle|\marg{style} in the preamble. +% This command comes from the package \textsf{fancyhdr} by Piet van Oostrum. +% It can be placed before of after entering information described in the next subsection. +% +% \medskip +% In the text body, you can change the style of a particular page by placing +% |\thispagestyle|\marg{style} at the page you want. +% For example, you can place the command |\thispagestyle{identity}| +% in an appendix page to render. +% \subsection{Informations fields} +% +% \DescribeMacro{\title} +% Usually a \LaTeX\ document title is made up of information +% provided by the macros +% |\title|, |\date| and |\author|. +% The |\title| macro has been redefined with an enriched syntax: +% |\title|\oarg{head}\marg{title}. +% The optional parameter \meta{head} corresponds to the text displayed in the header +% instead of \meta{title}. +% When not provided, the mandatory argument \meta{title} will be used in headers. +% +% The macros |\date| and |\author| have not been redefined but the information provided +% is also used in titles, headers or footers +% (depending on the style used)\footnote{The macro \texttt{\bslash and}, +% sometimes used in \texttt{\bslash author} +% to typeset a title with several authors, doesn't work here, +% except in the \textbf{collection} style. It produced a compilation error. +% The macro \texttt{\bslash thanks} also doesn't work but without producing error.}. +% +% \pagebreak +% \medskip +% \DescribeMacro{\subject} \DescribeMacro{\school} \DescribeMacro{\institute} +% In addition to the previous ones, we provide two other information macros, +% used in the title, or the headers or the footers, depending on the style: +% |\subject| and |\school| (or its alias |\institute|). +% The macro |\subject| has an optional argument, like in |\title|: +% |\subject|\oarg{head}\marg{title} which allows to place an alternative text +% in header, different from the one displayed in the title. +% +% \medskip +% The information macros, that have to be called in the preamble\footnote{% +% Nevertheless, the macros \texttt{\bslash date} and \texttt{\bslash author} +% can be used in the document body.}, +% are optional. If omitted the corresponding field will be empty, +% except for the date which will display today's date. +% So, if you do not want any date, just write |\date{}|. +% When title elements like subject, date are missing, the title height will be reduced accordingly. +% +% Except |\date|, all these information macros accept multiline arguments, +% for example |\school{Royal College of Pataphysics\\London}|. +% To typeset the main title on two (or more) lines, use |\\[1ex]| +% for a good vertical spacing. +% +% When using the \textsf{hyperref} package (by Sebastian Rahtz and Heiko Oberdiek) +% to produce a pdf output, information provided by |\title|, |\subject| and |\author| +% (and |\school|\footnote{The \emph{author} field of the pdf properties will be filled +% like this: \textsf{author (school)}, +% but \texttt{\bs author} should be called before \texttt{\bs school} in the preamble. +% }) +% will be written in the pdf properties also. +% +% \medskip +% The file \textsf{schooldocs-examples.pdf} uses the examples of the following table. +% \begin{center} +% \begin{tabular}{ll} +% \hline +% macro & example \\ +% \hline +% |\title| & |\title[The classic style]{The classic style layout}| \\ +% |\subject| & |\subject[Pathography / M2A]{Pathography / Master 2A}| \\ +% |\author| & |\author{Antoine Missier}| \\ +% |\school| & |\school{Royal College of Pataphysics}| \\ +% |\date| & |\date{May 4, 2020}| \\ +% \hline +% \end{tabular} +% \end{center} +% +% \DescribeMacro{\subtitle} +% In the \textbf{exam} style, the title uses an additional field +% provided by the macro |\subtitle|\marg{text}. The parameter \meta{text} +% will be placed under the other title elements and before the separation rule, +% if there is one. For instance |\subtitle{Duration of the test: 2\,h}|. +% For a multi-line argument, the linebreak instruction must be +% |\par| and not |\\|. +% +% \subsection{Making the title} +% +% \DescribeMacro{\maketitle} +% As in \LaTeX\ standard classes, the title is produced +% by the macro |\maketitle|, which should be placed after |\begin{document}|. +% This command has been redefined by the package. +% Indeed, the standard title produced by the \LaTeX\ class \texttt{article}, +% seems inappropriate for school documents like an exercise sheet for example. +% The macro redefinition reduces the vertical space before the title +% and typesets an horizontal rule to separate the title from the following text. +% By default, the title is centered but we can change this, +% as presented in section \ref{par:title-set}, to get +% a left or right-aligned title (an also boxed). +% Various titles are presented in the file +% \href{run:schooldocs-examples.pdf}{\textsf{schooldocs-examples.pdf}}. +% +% The macro has on optional parameter |\maketitle|\oarg{rulelength} +% to set the length of the separation rule, by default 2.5\,cm. +% The rule can be totally removed by setting the +% optional argument to 0\,cm; we can also make a rule of +% whole line width with |\maketitle[\linewidth]| or |\maketitle[\textwidth]|. +% +% Each style has its own title formatting. Nevertheless the package provides +% a ``standard'' title when no style is loaded or with +% the \LaTeX\ styles \textbf{empty} or \textbf{plain}. +% The \textbf{elegant} style keeps also this ``standard'' style. +% +% \medskip +% \DescribeMacro{\seprule} +% As in the title, a rule can also be used in the text body to make separations. +% This is done by the macro |\seprule|\oarg{length} which +% produces an horizontal centered rule of (optional) \meta{length}, by default 2.5\,cm. +% +% \medskip +% \DescribeMacro{\correct} +% For typesetting a correct version of an exercise sheet, we provide the macro |\correct|, +% which adds \textsf{-- Correct Version} to the title. +% It should be placed in the preamble. +% Combined with packages that deal with multiple versions of a document, +% this macro avoids to define different titles for a an exercice sheet an its correct version. +% However in the \textbf{exam} style, the text \textsf{Correct version} +% will not be added in the title (except in headers), but will be substituted for +% the subtitle. +% +% \medskip +% \DescribeMacro{\makesmalltitle} +% As in the package \textsf{phfnote} by Philippe Faist, it seems wisely +% to propose a compact title, where information +% provided by |\title|, |\subject| and |\date| are presented +% on a single line (see \textsf{schooldocs-examples.pdf}). +% The rule is always displayed and expands on the whole line width. +% +% \subsection{Style layouts} \label{par:styles} +% +% According to good typographic practice, the header on the title page should be empty +% (see The \LaTeX\ Companion). +% This ``rule'' is seldom observed in school documents, +% and, on the first page, we find often information (author, school, etc.) +% on top left and the date on top right, as for a letter. +% Except for the \textbf{classic} style, that we present first, +% we wanted to comply with good practice, +% but we keep some information in the footer yet. +% +% We present below miniature views to show the layout of the different styles. +% The file \href{run:schooldocs-examples.pdf}{\textsf{schooldocs-examples.pdf}} +% gives a real view of them. +% The rule (width) under the header or over the footer +% is freely configurable, as well as the format of each element and +% also some space settings, see section \ref{par:head-settings}. +% +% \medskip +% \begin{stylex} +% {\schoolstyle School} \hfill {Author}\\[-0.3ex] +% {\headsubjectstyle Subject} \hfill {date}\\ +% \vspace{0.04\mpwd} +% \centered{\footnotesize\sffamily\bfseries The classic style} +% \vspace{-0.25ex}\centered{\rule{0.15\mpwd}{0.1pt}} +% \vspace{0.85\mpwd} +% \centered{1/2} +% \end{stylex} +% \qquad +% \begin{stylex} +% \mbox{}\\[1ex] +% {\headtitlestyle Title} \hfill {\headsubjectstyle Subject}\\ +% \vspace{0.97\mpwd} +% \centered{2/2} +% \end{stylex} +% \medskip +% +% \begin{stylex} +% \mbox{}\vspace{0.03\mpwd} +% \begin{center} +% {\footnotesize\sffamily\bfseries The elegant style}\\[1.7ex] +% {\scriptsize Subject} \\[0.5ex] +% {\scriptsize date} \\ +% \vspace{-0.5ex}\rule{0.15\mpwd}{0.1pt} +% \end{center} +% \vspace{0.72\mpwd} +% {\schoolstyle School} \hfill Author +% \end{stylex} +% \qquad +% \begin{stylex} +% {\headtitlestyle Title} \hfill Page +% \end{stylex} +% \medskip +% +% \begin{stylex} +% \mbox{}\vspace{0.03\mpwd} +% \begin{center} +% {\footnotesize\sffamily\bfseries The modern style}\\[1.7ex] +% {\scriptsize Subject} \\ +% \vspace{-0.5ex}\rule{0.15\mpwd}{0.1pt} +% \end{center} +% \vspace{0.75\mpwd} +% {\schoolstyle School} \hfill \begin{tabular}[c]{r@{}}Author\\[-0.5ex] date\end{tabular} +% \end{stylex} +% \qquad +% \begin{stylex} +% {\headtitlestyle Title} \hfill {\headsubjectstyle Subject} \par +% \vspace{-1.9ex}\rule{0.82\mpwd}{0.1pt} +% +% \vspace{1.01\mpwd} +% \centered{2/2} +% \end{stylex} +% \medskip +% +% \begin{stylex} +% \mbox{}\vspace{0.03\mpwd} +% \begin{center} +% {\footnotesize\sffamily\bfseries The soft style}\\ +% \vspace{-0.5ex}\rule{0.15\mpwd}{0.1pt} +% \end{center} +% \vspace{0.83\mpwd} +% {\schoolstyle School} \hfill {\headsubjectstyle Subject}\\ +% Author \hfill date +% \end{stylex} +% \qquad +% \begin{stylex} +% {\headtitlestyle Title} \hfill Page \par +% \vspace{-1.9ex}\rule{0.82\mpwd}{0.1pt} +% \vspace{0.97\mpwd} +% +% \schoolstyle School \hfill \headsubjectstyle Subject +% \end{stylex} +% \medskip +% +% \begin{stylex} +% \mbox{}\vspace{0.1\mpwd} +% \begin{center} +% {\footnotesize THE EXAM STYLE}\\[3.2ex] +% {\scriptsize\bfseries Subject} \\[2.8ex] +% {\scriptsize date} \\[2ex] +% {\scriptsize\slshape subtitle} \\ +% \rule{0.15\mpwd}{0.1pt} +% \end{center} +% \vspace{0.51\mpwd} +% \begin{tabular}[c]{@{}l}Author\\[-0.5ex] \schoolstyle School\end{tabular} \hfill {Page} +% \end{stylex} +% \qquad +% \begin{stylex} +% {\headtitlestyle TITLE} \hfill {\headsubjectstyle Subject} \par +% \vspace{-1.9ex}\rule{0.82\mpwd}{0.1pt} +% +% \vspace{1.01\mpwd} +% \begin{tabular}[c]{@{}l}Author\\[-0.5ex] \schoolstyle School\end{tabular} \hfill {Page} +% \end{stylex} +% \medskip +% +% \begin{stylex} +% \mbox{}\vspace{0.1\mpwd} +% \begin{center} +% {\footnotesize THE COLLECTION STYLE}\\[3.2ex] +% {\scriptsize\bfseries Subject} \\[2.8ex] +% {\scriptsize Author} \\[1.5ex] +% {\scriptsize School} \\[1.5ex] +% {\scriptsize date} \\ +% \rule{0.15\mpwd}{0.1pt} +% \end{center} +% \end{stylex} +% \qquad +% \begin{stylex} +% {\headtitlestyle TITLE} \hfill {\headsubjectstyle Section} \par +% \vspace{-1.9ex}\rule{0.82\mpwd}{0.1pt} +% +% \vspace{1.01\mpwd} +% {\schoolstyle School} \hfill {2} +% \end{stylex} +% \bigskip +% +% In the \textbf{collection} style, usefull for longer documents, +% the name of the current section appears in the right header +% and changes as things progress +% as in the \LaTeX\ \textbf{book} class. +% +% \section{Settings} +% +% \subsection{Page layout} +% +% The page layout is set in the same way, for all styles. +% It is defined by the macro |\geometry| of the package +% \textsf{geometry} (by Hideo Umeki and David Carlisle). +% According to good typographic practice (see the \LaTeX\ Companion, +% the \textsf{typearea} package or \textsf{KOMA-Script} bundle documentation) +% the ratio between the text body (the type area as named by typographs) +% and the page size must be the same horizontally and vertically. +% This ratio gauges the ``shades of grey'' of a page. +% The default scale in the \textsf{geometry} package is 0.7. +% For school documents, it seems that this setting leaves too much white space in the margins, thus this ratio has been set to 0.75. +% Of course, it can be freely redefined with the |\geometry| command. +% Furthermore, according to ``canons of page construction'', in a one-sided document, +% the ratio between the left and right margins should be 1:1, +% while the ratio between the top and bottom margins should be 1:2. +% It seems that this recommended ratio of 1:2 is seldom observed +% and it produces a very wide bottom margin. +% Besides, when loading the \textsf{geometry} package, the default vertical ratio is 2:3 and not 1:2. +% To get more balanced margins, we have prefer to set it at 3:4: +% |\geometry{scale=0.75,vmarginratio=3:4,heightrounded}|\footnote{The option +% \texttt{heightrounded} rounds text height to $n$-times ($n$ an integer) the height of a line, to avoid ``underfull vbox'' in some cases.}. +% +% \subsection{Title settings} \label{par:title-set} +% +% Several parameters allow to customize the title composition. +% They are presented in the following table with their default value. +% Colors are changed with |\definecolor|, macros with |\renewcommand| +% and lengths with |\setlength|. +% Most of command names are explicit enough to give some information about their use. +% +% Let us specifiy nevertheless that |\titleflush| manages the alignment: +% centered by default, it can be left-aligned with +% |\renewcommand{\titleflush}{flushleft}| or right-aligned with +% |\renewcommand{\titleflush}{flushright}|\footnote{This macro has no effect +% with the \textbf{exam} and \textbf{collection} styles, +% the title is always centered.}. +% +% The length |\titlesep| sets the vertical spacing between the fields \emph{title} +% and \emph{subject}, except for the \textbf{classic} and \textbf{soft} styles, +% witch contain only the field \emph{title}, or if the field \emph{subject} +% is not given. +% Vertical spaces between other title fields are defined in relation to +% |\titlesep| (|0.5\titlesep| for most). +% +% Unless otherwise stated, the column ``special settings'' of the following table +% applies to the \textbf{exam} and \textbf{collection} styles. +% +% \begin{center} \small +% \begin{tabular}{ccc} +% \hline +% parameter & default settings & special settings \\ +% \hline +% |titlecolor| & |black| & \\ +% |\titlestyle| & |\LARGE\sffamily\bfseries| & |\LARGE\MakeUppercase| \\ +% |\subjectstyle| & |\large| & |\Large\bfseries|\\ +% |\datestyle| & |\large| \\ +% |\smalltitledatestyle| & |\large\slshape| & \\ +% |\titleflush| & |center| & \\ +% |\titletopskip| & -1.32\,cm & -0.67\,cm (\textbf{classic}), 0.67\,cm \\ +% |\titlebottomskip| & |\medskipamount| \\ +% |\titlesep| & |2\medskipamount| & |2\bigskipamount| \\ +% |\seprulewidth| & 0.3\,pt &\\ +% |\seprulelength| & 2.5\,cm &\\ +% \hline +% \end{tabular} +% \end{center} +% +% \DescribeMacro{\subtitlestyle}\DescribeMacro{\titlecorrectstyle} +% The \textbf{exam} style has two additionnal setting macros: +% |\subtitlestyle|, set by default to |\large\slshape|, +% and |\titlecorrectstyle|, for the composition of \textsf{Correct Version} +% produced by |\correct|, set by default to |\color{red}\large\scshape|. +% +% In the \textbf{collection} style, the fields +% \emph{school} and \emph{author} are included into the title. Their features are then +% controlled by |\authorstyle|\footnote{For other styles, the macro +% \texttt{\bs authorstyle} belongs to headers or footers parameters.} set to |\Large|. +% +% If we want to create a separate page for the title, in particular for the +% \textbf{exam} or \textbf{collection} styles, we can place |\maketitle| into +% an environment |titlepage| provided by \LaTeX. +% +% \medskip +% \DescribeMacro{\boxedshape} +% A particular formatting has been predefined to produce a slighlty shaded box around the title: |\boxedshape|\marg{text} +% (thanks to the \textsf{fancybox} package by Timothy Van Zandt). +% It is not activated by default but it can be used within the +% command |\titlestyle| if we want to get this kind of effect, e.g. +% |\renewcommand{\titlestyle}{\LARGE\sffamily\bfseries\boxedshape}|. +% +% \subsection{Headers and footers} \label{par:head-settings} +% +% Headers and footers typeset is produced thanks to +% dedicated macros\footnote{The \textsf{fancyhdr} package +% provides the commands \texttt{\bs lhead}, \texttt{\bs chead}, \texttt{\bs rhead} +% for the left, center and right parts of the header, and the same for the footer: +% \texttt{\bs lfoot}, \texttt{\bs cfoot} and \texttt{\bs rfoot}.} +% of the \textsf{fancyhdr} package. +% As for the title, several macros allow to customize certain settings. +% They are presented in the table below. +% Let us specify that |\pagenamestyle| defines the format of the word \emph{page} +% used in front of the page number. +% +% The |\headstyle| and |\footstyle| commands are generic for all elements +% of headers and footers. They are combined with macros giving +% specific settings for each field. +% \begin{center} +% \begin{tabular}{cc} +% \hline +% parameter & default setting \\ +% \hline +% |headingcolor| & |black| \\ +% |\headstyle| & |\small\color{headingcolor}| \\ +% |\footstyle| & |\small\color{headingcolor}| \\ +% |\headtitlestyle| & |\scshape| \\ +% |\headsubjectstyle| & |\scshape| \\ +% |\schoolstyle| & |\scshape| \\ +% |\headdatestyle| & |\textnormal| \\ +% |\authorstyle| & |\textnormal| \\ +% |\pagenamestyle| & |\textnormal| \\ +% \hline +% \end{tabular} +% \end{center} +% +% The \textbf{exam} and \textbf{collection} styles have a specific setting for +% |\headtitlestyle|, defined by |\renewcommand{\headtitlestyle}{\MakeUppercase}|. +% +% \medskip +% Macros that allow to display (or remove) the rule in the header\footnote{Indeed +% we have redefined the \texttt{\bs headrule} macro +% such that the rule never appears +% on the first page.} +% or the footer +% come from the \textsf{fancyhdr} package. For example, in any style, +% we remove the rule in the header with: +% |\renewcommand{\headrulewidth}{0pt}|, +% and display it in the footer with: +% |\renewcommand\footrulewidth{0.4pt}| +% +% \subsection{Internationalization} +% Four keywords are used by the package: page, Correct version, Name and Forename, +% defined by the macros |\pagename|, |\correctname|, |\identityname| and |\identityforename|. +% |\pagename| is used in header or footer, |\correctname| by the macro |\correct| +% and both others by the \textbf{identity} style. +% These keywords get automatic translation in a few languages\footnote{Translation +% is currently integrated into the package for the following languages: +% French, German, Spanish, Italian, Portuguese.} +% when the \textsf{babel} package is loaded. +% They can be redefined, with |\renewcommand|, +% which should be placed \emph{after} |\begin{document}|, +% or else we can use macros from the \textsf{babel} package +% (allowing dynamic language change), e.g.\\ +% |\addto\captionsromanian{\def\pagename{pagin\u{a}}}| (in the preamble). +% +% +% \StopEventually{} +% +% \section{Implementation} +% +% \subsection{Required packages and geometry settings} +% +% \begin{macrocode} +\ProvidesPackage{schooldocs} +\NeedsTeXFormat{LaTeX2e} + +\RequirePackage{geometry} +\let\footruleskip\relax % because memoir class uses it +\RequirePackage{fancyhdr} +\RequirePackage{ifthen} +\RequirePackage{lastpage} +\RequirePackage{fancybox} +\RequirePackage{xcolor} + +\geometry{scale=0.75,vmarginratio=3:4,heightrounded} + +% \end{macrocode} +% It is recommended to define the settings with the command |\geometry| +% rather than as option when loading the package \textsf{geometry}, to avoid option clash. +% +% To change the scale factor, if the |\geometry| command doesn't work, use |\newgeometry|. +%\medskip +% \subsection{Internationalization} +% +% \begin{macrocode} +\providecommand{\pagename}{page} +\def\correctname{Correct version} +\def\identityname{Name:} +\def\identityforename{Forename:} + +\newcommand\schooldocstranslate{% + \@ifpackageloaded{babel}{% + \addto\captionsfrench{% + \def\correctname{Corrig\'e} + \def\identityname{Nom :} + \def\identityforename{Pr\'enom :} + } + \addto\captionsgerman{% + \def\pagename{Seite} + \def\correctname{Musterl\"osung} + \def\identityname{Name :} + \def\identityforename{Vorname :} + } + \addto\captionsspanish{% + \def\pagename{p\'agina} + \def\correctname{Correccion} + \def\identityname{Apellido:} + \def\identityforename{Nombre:} + } + \addto\captionsitalian{% + \def\pagename{Seite} + \def\correctname{Corretto} + \def\identityname{Nome :} + \def\identityforename{Conome :} + } + \addto\captionsportuges{% + \def\pagename{p\'agina} + \def\correctname{Corrigiu} + \def\identityname{Nome :} + \def\identityforename{Primeiro nome :} + } + }{} + } + +\AtBeginDocument{\schooldocstranslate} % if loaded before babel +\schooldocstranslate % necessary when loaded after babel + +% \end{macrocode} +% +% \subsection{Information fields} +% +% After being defined, information fields are set to empty, +% to make tests with them work well. +% +% \begin{macrocode} +\renewcommand{\title}[2][]{\long\def\@title{#2} + \ifthenelse{\equal{#1}{}}{\def\@headtitle{#2}}{\def\@headtitle{#1}} + \@ifpackageloaded{hyperref}{\hypersetup{pdftitle={\@headtitle}}}{} +} +\title{} +\author{} + +\newcommand\school[1]{\long\def\@school{#1} + \@ifpackageloaded{hyperref}{ + \hypersetup{pdfauthor={\@author\ (\@school)}}}{} +} +\school{} +\newcommand{\institute}{\school} + +\let\subject\relax +\newcommand{\subject}[2][]{\long\def\@subject{#2} + \ifthenelse{\equal{#1}{}}{\def\@headsubject{#2}}{\def\@headsubject{#1}} + \@ifpackageloaded{hyperref}{\hypersetup{pdfsubject={\@headsubject}}}{} +} +\def\@subject{} +\def\@headsubject{} +% \end{macrocode} +% Because \textsf{KOMA-Script} package also uses the |\subject| macro, +% we make a |\relax| on this command. +% +% |\subject{}| doesn't work with the |\@empty| test used below in |\maketitle|, thus +% we define |\@subject| and |\@headsubject| as empty by default. +% +% \subsection{Settings} +% +% First we present the title settings. +% \begin{macrocode} +\definecolor{titlecolor}{named}{black} +\newcommand{\titlestyle}{\LARGE\sffamily\bfseries} +\newcommand{\subjectstyle}{\large} +\newcommand{\datestyle}{\large} +\newcommand{\smalltitledatestyle}{\large\slshape} +\newcommand{\titleflush}{center} +\newlength{\titletopskip} \setlength{\titletopskip}{-1.32cm} +\newlength{\titlesep} \setlength{\titlesep}{2\medskipamount} +\newlength{\titlebottomskip} \setlength{\titlebottomskip}{\medskipamount} +\newlength{\seprulewidth} \setlength{\seprulewidth}{0.3pt} +\newlength{\seprulelength} \setlength{\seprulelength}{2.5cm} + +\newcommand{\boxedshape}[1]{% + \color{gray} % no effect + \setlength{\fboxsep}{4.5pt} + \setlength{\shadowsize}{3pt} + \shadowbox{\quad\textcolor{titlecolor}{\rule{0pt}{2ex}#1}\quad} +} + +% \end{macrocode} +% Default value for |\fboxsep| is 3\,pt and for |\shadowsize| is 4\,pt. +% These settings are local. +% +% \medskip +% Next the headers and footers settings. +% \begin{macrocode} +\definecolor{headingcolor}{named}{black} +\newcommand{\headstyle}{\small\color{headingcolor}} +\newcommand{\footstyle}{\small\color{headingcolor}} +\newcommand{\headtitlestyle}{\scshape} +\newcommand{\headsubjectstyle}{\scshape} +\newcommand{\schoolstyle}{\scshape} +\newcommand{\headdatestyle}{\textnormal} +\newcommand{\authorstyle}{\textnormal} +\newcommand{\pagenamestyle}{\textnormal} +\setlength{\headheight}{\baselineskip} +\renewcommand{\headrule}{\ifthenelse{\thepage=1}% + {\vspace{-2ex}\rule{\headwidth}{0pt}}% + {\vspace{-2ex}\rule{\headwidth}{\headrulewidth}} +} + +% \end{macrocode} +% The |\headrule| macro redefinition allow to remove the rule on the first page. +% +% The header height is set to |\baselineskip| to avoid +% error messages (``headheight too small'') when the text size is +% greater than or equal to |\small|. +% +% \subsection{Title composition} +% +% \begin{macrocode} +\renewcommand{\maketitle}[1][\seprulelength]{ + \mbox{}\par\vspace{\titletopskip} + \begin{\titleflush} + {\color{titlecolor} + {\titlestyle{\@title}} + \ifx\@subject\@empty\else + \par\vspace{\titlesep}\subjectstyle\@subject + \fi + \ifthenelse{\equal{\@date}{}}{}{% + \par\vspace{0.5\titlesep} \datestyle\@date} + \par\vspace{0.5\titlesep} + } + \ifthenelse{\lengthtest{#1 > 0cm}}{\rule{#1}{\seprulewidth}}{} + \end{\titleflush} + \vspace{\titlebottomskip} +} + +\newcommand{\makesmalltitle}{ + \mbox{}\par\vspace{1.5\titletopskip} + \begin{center} + {\color{titlecolor} + {\titlestyle{\@title}} + \hfill \subjectstyle\@subject + \ifthenelse{\equal{\@date}{}}{}{% + \enskip --\enskip \smalltitledatestyle\@date} + } + \rule{\linewidth}{\seprulewidth} + \end{center} + \vspace{\titlebottomskip} +} + +\newcommand\correct{% + \let\@originalheadtitle\@headtitle + \def\@headtitle{\@originalheadtitle ~--~\correctname} + \@ifpackageloaded{hyperref}{% + \AtBeginDocument{\hypersetup{pdftitle={\@headtitle}}}}{} + \let\@originaltitle\@title + \def\@title{\@originaltitle ~--~\correctname} +} + +\newcommand{\seprule}[1][\seprulelength]{\begin{center} + \raisebox{0.25\baselineskip}{\rule{#1}{\seprulewidth}}\end{center}} + +% \end{macrocode} +% |\AtBeginDocument| is necessary in the |\correct| macro because +%|\correctname| can be redefined by \textsf{babel} at |\begin{document}|. +% +% \medskip +% \subsection{The basic styles} +% +% The header in the \textbf{classic} style is displayed on two lines, therefore we have to increase the height +% |\headheight|. +% +% If we want to include header or footer in the total body, +% we can add the command |\geometry{includehead}| respectively +% |\geometry{includefoot}| in the preamble. +% \begin{macrocode} +\fancypagestyle{classic}{% + \renewcommand{\headrulewidth}{0pt} + \addtolength{\headheight}{\baselineskip} + \lhead{\headstyle\ifthenelse{\thepage=1}{\schoolstyle\@school\mbox{}\\ + \headsubjectstyle\@subject}{\headtitlestyle\@headtitle} } + \rhead{\headstyle\ifthenelse{\thepage=1}{\authorstyle\@author\mbox{}\\ + \headdatestyle\@date}{\headsubjectstyle\@headsubject}} + \cfoot{\footstyle \thepage /\pageref{LastPage}} + \setlength{\titletopskip}{-0.67cm} + \renewcommand{\maketitle}[1][\seprulelength]{% + \mbox{}\par\vspace{\titletopskip} + \begin{\titleflush} + {\color{titlecolor}\titlestyle{\@title}} + \par\vspace{0.5\titlesep} + \ifthenelse{\lengthtest{##1>0cm}}{\rule{##1}{\seprulewidth}}{} + \end{\titleflush} + \vspace{\titlebottomskip} + } +} + +\fancypagestyle{elegant}{% + \renewcommand{\headrulewidth}{0pt} + \lhead{\headstyle + \ifthenelse{\thepage=1}{}{\headtitlestyle\@headtitle}} + \rhead{\headstyle + \ifthenelse{\thepage=1}{}{% + \pagenamestyle\pagename~\thepage /\pageref{LastPage}}} + \lfoot{\ifthenelse{\thepage=1}{\footstyle\schoolstyle\@school}{}} + \cfoot{} + \rfoot{\ifthenelse{\thepage=1}{\footstyle\authorstyle\@author}{}} +} + +\fancypagestyle{modern}{% + \lhead{\headstyle + \ifthenelse{\thepage=1}{}{\headtitlestyle\@headtitle}} + \rhead{\headstyle + \ifthenelse{\thepage=1}{}{\headsubjectstyle\@headsubject}} + \lfoot{\ifthenelse{\thepage=1}{\footstyle\schoolstyle\@school}{}} + \cfoot{\ifthenelse{\thepage=1}{}{ + \footstyle\thepage /\pageref{LastPage}}} + \rfoot{\footstyle\ifthenelse{\thepage=1}{% + \authorstyle\@author + \ifx\@author\empty\else\\ \fi + \headdatestyle\@date\ignorespaces}{} + } + \renewcommand{\maketitle}[1][\seprulelength]{% + \mbox{}\par\vspace{\titletopskip} + \begin{\titleflush} + {\color{titlecolor} + {\titlestyle{\@title}} + \ifx\@subject\@empty\else + \par\vspace{\titlesep}\subjectstyle\@subject + \fi + \par\vspace{0.5\titlesep} + } + \ifthenelse{\lengthtest{##1>0cm}}{\rule{##1}{\seprulewidth}}{} + \end{\titleflush} + \vspace{\titlebottomskip} + } +} + +\fancypagestyle{soft}{% + \lhead{\headstyle + \ifthenelse{\thepage=1}{}{\headtitlestyle\@headtitle}} + \rhead{\headstyle + \ifthenelse{\thepage=1}{}{% + \pagenamestyle\pagename~\thepage /\pageref{LastPage}}} + \lfoot{\footstyle{\schoolstyle\@school} + \ifthenelse{\thepage=1}{\ifx\@author\empty\else\\ \fi + \authorstyle\@author}{} + } + \cfoot{} + \rfoot{\footstyle{\headsubjectstyle\@headsubject} + \ifthenelse{\thepage=1}{\ifx\@date\empty\else\\ \fi + \headdatestyle\@date\ignorespaces}{} + } + \setlength{\titletopskip}{-0.67cm} + \renewcommand{\maketitle}[1][\seprulelength]{% + \mbox{}\par\vspace{\titletopskip} + \begin{\titleflush} + {\color{titlecolor}\titlestyle{\@title}} + \par\vspace{0.5\titlesep} + \ifthenelse{\lengthtest{##1>0cm}}{\rule{##1}{\seprulewidth}}{} + \end{\titleflush} + \vspace{\titlebottomskip} + } +} + +\fancypagestyle{identity}{% + \lhead{\headstyle\headtitlestyle \identityname} + \chead{\headstyle\headtitlestyle \identityforename} + \rhead{} + } + +% \end{macrocode} +% +% \subsection{The extended styles} +% +% \begin{macrocode} +\fancypagestyle{exam}{% + \let\subtitle\relax % because KOMA-Script uses it + \newcommand\subtitle[1]{\long\def\@subtitle{##1}} + \subtitle{} + \renewcommand{\headtitlestyle}{\MakeUppercase} + \lhead{\headstyle + \ifthenelse{\thepage=1}{}{\headtitlestyle{\@headtitle}}} + \rhead{\headstyle + \ifthenelse{\thepage=1}{}{\headsubjectstyle\@headsubject}} + \lfoot{\footstyle + \authorstyle\@author + \ifx\@author\empty\else\\ \fi + \schoolstyle\@school + } + \cfoot{} + \rfoot{\footstyle \pagenamestyle\pagename~\thepage/\pageref{LastPage}} + \setlength{\titletopskip}{0.67cm} + \setlength{\titlesep}{2\bigskipamount} + \renewcommand{\titlestyle}{\LARGE\MakeUppercase} + \renewcommand{\subjectstyle}{\Large\bfseries} + \newcommand{\subtitlestyle}{\large\slshape} + \newcommand*{\titlecorrectstyle}{\color{red}\large\scshape} + \renewcommand\correct{% + \let\@originalheadtitle\@headtitle + \def\@headtitle{\@originalheadtitle ~--~\correctname} + \@ifpackageloaded{hyperref}{% + \AtBeginDocument{\hypersetup{pdftitle={\@headtitle}}}}{} + \renewcommand{\subtitlestyle}{\titlecorrectstyle} + \subtitle{\correctname} + } + \renewcommand{\maketitle}[1][\seprulelength]{% + \mbox{}\par\vspace{\titletopskip} + \begin{center} + {\color{titlecolor} + {\titlestyle{\@title}} + \par\vspace{\titlesep}{\subjectstyle \@subject} + \par\vspace{\titlesep} + \ifthenelse{\equal{\@date}{}}{}{% + \datestyle\@date\par\vspace{0.5\titlesep}} + \ifthenelse{\equal{\@subtitle}{}}{}{% + \subtitlestyle\@subtitle\par\vspace{0.5\titlesep} + } + } + \ifthenelse{\lengthtest{##1>0cm}}{\rule{##1}{\seprulewidth}}{} + \end{center} + \vspace{\titlebottomskip} + } +} + +\fancypagestyle{collection}{% + \renewcommand{\headtitlestyle}{\MakeUppercase} + \lhead{\headstyle\headtitlestyle\@headtitle} + \AtBeginDocument{\renewcommand{\sectionmark}[1]{\markboth{##1}{}}} + \rhead{\headstyle\headsubjectstyle\leftmark} %\@section + \lfoot{\footstyle\schoolstyle \@school} + \cfoot{} + \rfoot{\footstyle\thepage} + \setlength{\titletopskip}{0.67cm} + \setlength{\titlesep}{2\bigskipamount} + \renewcommand{\titlestyle}{\LARGE\MakeUppercase} + \renewcommand{\subjectstyle}{\Large\bfseries} + \renewcommand{\authorstyle}{\Large} + \renewcommand{\datestyle}{\Large} + \renewcommand{\maketitle}[1][\seprulelength]{% + \thispagestyle{empty} + \mbox{}\par\vspace{\titletopskip} + \begin{center} + {\color{titlecolor} + {\titlestyle{\@title}} + \par\vspace{\titlesep} {\subjectstyle{\@subject}} + \par\vspace{\titlesep} + \ifx\@author\empty + \else \authorstyle + \begin{tabular}[t]{c}\@author\end{tabular} + \ifx\@school\empty\else\par\vspace{1ex} \@school\fi + \par\vspace{0.5\titlesep} + \fi + \ifthenelse{\equal{\@date}{}}{}{% + \datestyle\@date \par\vspace{0.5\titlesep}} + } + \ifthenelse{\lengthtest{##1>0cm}}{\rule{##1}{\seprulewidth}}{} + \end{center} + \vspace{\titlebottomskip} + } +} +% \end{macrocode} +% +% In the \textbf{collection} style, +% we redefine |\sectionmark| with |\AtBeginDocument| to prevent |\MakeUppercase| +% from eliminating the section number +% (or you can use |\nouppercase| here). +% +% |\ifthenelse| doesn't work when |\and| is used within |\author|. +% +% Notice the |\pagestyle{empty}| in |\maketitle| which prevents +% any header on the first page. +% +% \Finale +\endinput diff --git a/macros/latex/contrib/schooldocs/schooldocs.ins b/macros/latex/contrib/schooldocs/schooldocs.ins new file mode 100644 index 0000000000..f764055184 --- /dev/null +++ b/macros/latex/contrib/schooldocs/schooldocs.ins @@ -0,0 +1,55 @@ +%% +%% Copyright (C) 2020 by Antoine Missier +%% +%% This file may be distributed and/or modified under the conditions of +%% the LaTeX Project Public License, either version 1.3 of this license +%% or (at your option) any later version. The latest version of this +%% license is in: +%% +%% http://www.latex-project.org/lppl.txt +%% +%% and version 1.3 or later is part of all distributions of LaTeX version +%% 2005/12/01 or later. +%% + +\input docstrip.tex +\keepsilent + +\usedir{tex/latex/schooldocs} + +\preamble + +This is a generated file. + +Copyright (C) 2020 by Antoine Missier + +This file may be distributed and/or modified under the conditions of +the LaTeX Project Public License, either version 1.3 of this license +or (at your option) any later version. The latest version of this +license is in: + + http://www.latex-project.org/lppl.txt + +and version 1.3 or later is part of all distributions of LaTeX version +2005/12/01 or later. + +\endpreamble + +\generate{\file{schooldocs.sty}{\from{schooldocs.dtx}{package}}} + +\obeyspaces +\Msg{*************************************************************} +\Msg{* *} +\Msg{* To finish the installation you have to move the following *} +\Msg{* file into a directory searched by TeX: *} +\Msg{* *} +\Msg{* schooldocs.sty *} +\Msg{* *} +\Msg{* To produce the documentation run the file schooldocs.dtx *} +\Msg{* through LaTeX. *} +\Msg{* *} +\Msg{* Happy TeXing! *} +\Msg{* *} +\Msg{*************************************************************} + +\endbatchfile diff --git a/macros/latex/contrib/schooldocs/schooldocs.pdf b/macros/latex/contrib/schooldocs/schooldocs.pdf new file mode 100644 index 0000000000..28eb97e8bd Binary files /dev/null and b/macros/latex/contrib/schooldocs/schooldocs.pdf differ -- cgit v1.2.3