diff options
author | Karl Berry <karl@freefriends.org> | 2021-10-20 21:16:12 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2021-10-20 21:16:12 +0000 |
commit | 94c93aab885d39a26d41dbfff06d9d33a0f69c81 (patch) | |
tree | 6b8bc1c21ae49029563871b2be55ba17631fe685 /Master/texmf-dist/doc/latex/incgraph/incgraph.tex | |
parent | 6d535a56ce6233ff32ceb654cc7bdf0dea37b663 (diff) |
incgraph (20oct21)
git-svn-id: svn://tug.org/texlive/trunk@60810 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/incgraph/incgraph.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/incgraph/incgraph.tex | 419 |
1 files changed, 239 insertions, 180 deletions
diff --git a/Master/texmf-dist/doc/latex/incgraph/incgraph.tex b/Master/texmf-dist/doc/latex/incgraph/incgraph.tex index 7425a75ab2b..1b739cfaf8c 100644 --- a/Master/texmf-dist/doc/latex/incgraph/incgraph.tex +++ b/Master/texmf-dist/doc/latex/incgraph/incgraph.tex @@ -1,9 +1,10 @@ % \LaTeX-Main\ -%% The LaTeX package incgraph - version 1.12 (2015/03/12) +% !TeX encoding=UTF-8 +%% The LaTeX package incgraph - version 1.2.0 (2021/10/20) %% incgraph.tex: Manual %% %% ------------------------------------------------------------------------------------------- -%% Copyright (c) 2012-2013 by Prof. Dr. Dr. Thomas F. Sturm <thomas dot sturm at unibw dot de> +%% Copyright (c) 2012-2021 by Prof. Dr. Dr. Thomas F. Sturm <thomas dot sturm at unibw dot de> %% ------------------------------------------------------------------------------------------- %% %% This work may be distributed and/or modified under the @@ -20,111 +21,7 @@ %% \documentclass[a4paper,11pt]{ltxdoc} -\usepackage[T1]{fontenc} -\usepackage[latin1]{inputenc} -\usepackage[english]{babel} -\usepackage{lmodern,parskip,array,ifthen,calc,makeidx} -\usepackage{amsmath,amssymb} -\usepackage[svgnames,table,hyperref]{xcolor} -\usepackage{tikz} -\usepackage[pdftex,bookmarks,raiselinks,pageanchor,hyperindex,colorlinks]{hyperref} -\urlstyle{sf} - -\usepackage[a4paper,left=2.5cm,right=2.5cm,top=1.5cm,bottom=1.5cm, - marginparsep=3mm,marginparwidth=18mm, - headheight=0mm,headsep=0cm, - footskip=1.5cm,includeheadfoot]{geometry} -\usepackage{fancyhdr} -\fancyhf{} -\fancyfoot[C]{\thepage}% -\renewcommand{\headrulewidth}{0pt} -\renewcommand{\footrulewidth}{0pt} -\pagestyle{fancy} -\tolerance=2000% -\setlength{\emergencystretch}{20pt}% - -\RequirePackage{csquotes} -\RequirePackage[style=numeric-comp,sorting=nyt, - maxnames=8,minnames=8,abbreviate=false,backend=biber]{biblatex} -\DeclareFieldFormat{url}{\newline\url{#1}}% -\DeclareListFormat{language}{}% -\setlength{\bibitemsep}{\smallskipamount} -\addbibresource{\jobname.bib} - -\usepackage[many,listings,documentation]{tcolorbox} - -\tcbset{skin=enhanced, - doc head={colback=yellow!10!white,interior style=fill}, - doc head key={colback=magenta!5!white,interior style=fill}, - color key=DarkViolet, - color value=Teal, - color color=Teal, - color counter=Orange!85!black, - color length=Orange!85!black, - index colorize, - index annotate, - %external/externalizer=tcolorbox.doc.externalizer, -} -\renewcommand*{\tcbdocnew}[1]{\textcolor{green!50!black}{\sffamily\bfseries N} #1} -\renewcommand*{\tcbdocupdated}[1]{\textcolor{blue!75!black}{\sffamily\bfseries U} #1} - -\usepackage{incgraph} - -\hypersetup{ - pdftitle={Manual for the incgraph package}, - pdfauthor={Thomas F. Sturm}, - pdfsubject={graphics inclusion}, - pdfkeywords={graphics inclusion page} -} - -\usepackage{tikz,multicol} - -\lstdefinestyle{mydocumentation}{style=tcbdocumentation, - classoffset=0, - texcsstyle=\color{blue}, - % LaTeX and other packages - moretexcs={arrayrulecolor,draw,path,fill,includegraphics,ifthenelse,isodd,lipsum,path,pgfkeysalso,foreach}, - classoffset=1, - moretexcs={% - incgraph,incmultigraph,n,ni,nn,nt,igrset,igrpage,igrcenter,igrcenterfit, - igrtargetset,igrboxset,igrboxcenter,igrpagestyle,igrboxtikz,igrboxtikzpage, - igrboxtikzcenter,igrsetmatchvalue,igrsetmatches,igrifmatch,igrmakezerofill, - }, - texcsstyle=\color{Definition}\bfseries, - classoffset=2, - keywordstyle=\color{Option}\bfseries, - % option list - morekeywords={% - }, - classoffset=0% restore default - } - -\tcbset{documentation listing style=mydocumentation,% - docexample/.style={enhanced,colframe=Navy!50!ExampleFrame,colback=Navy!5!ExampleBack,fontlower=\footnotesize, - bicolor,colbacklower=ExampleBack!5!white,drop fuzzy shadow}, -} - -\tcbmakedocSubKey{docIgrKey}{igr} - -\newcounter{texexp} - -\tcbset{ - example/.code 2 args={\refstepcounter{texexp}% - \pgfkeysalso{label={#2},docexample,listing style=mydocumentation,fonttitle=\bfseries,title={Example \thetexexp: #1}}}, -} - -\newenvironment{texexptitled}[3][]{% - \hypersetup{linkcolor=white}% - \tcbset{example={#2}{#3},listing file={\jobname.\thetexexp.listing},#1}% - \tcblisting{}}{\endtcblisting} - - -\newcommand{\inputlisting}[1]{\input{\jobname.#1.listing}} -\newcommand{\inputlastlisting}{\inputlisting{\thetexexp}} - -\def\version{1.12}% -\def\datum{2015/03/12}% -\makeindex +\usepackage{incgraph-doc} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -140,7 +37,10 @@ {\large Thomas F.~Sturm% \footnote{Prof.~Dr.~Dr.~Thomas F.~Sturm, Institut f\"{u}r Mathematik und Informatik, Universit\"{a}t der Bundeswehr M\"{u}nchen, D-85577 Neubiberg, Germany; - email: \href{mailto:thomas.sturm@unibw.de}{thomas.sturm@unibw.de}} } + email: \href{mailto:thomas.sturm@unibw.de}{thomas.sturm@unibw.de}}\par\medskip +\normalsize\url{https://www.ctan.org/pkg/incgraph}\par +\url{https://github.com/T-F-S/incgraph} +} \end{center} \bigskip \begin{absquote} @@ -185,11 +85,13 @@ An important use case for the package |incgraph| is to transform one or many sca or taken pictures to a PDF document. Optionally, the included graphics can be commented with bookmarks for the resulting PDF document. -The well-known |graphicx| package \cite{carlisle:1999a} allows the inclusion +The well-known |graphicx| package \cite{carlisle:graphics} allows the inclusion of several types of external graphics files. The convenience user interface of |incgraph| described in Section \ref{sec:interface} relies on this package and adds assistance for the described purpose. Note that the package is designed for and -tested with |pdflatex| to produce PDF directly. Some features like the paper +tested with |pdflatex| to produce PDF directly. Also, the package is +intended to harmonize with |lualatex|. +Some features like the paper resizing may not be applicable for other work-flows. Many of the features of the convenience user interface can be used directly @@ -197,7 +99,7 @@ with various basic macros. These are collected and described as a 'basic tool box' in Section \ref{sec:basictoolbox}. If this package does not aid your intended purpose, you may take a look -at the |pdfpages| package \cite{matthias:2012a} which also supports the insertion of +at the |pdfpages| package \cite{matthias:pdfpages} which also supports the insertion of external multi-page PDF documents. @@ -208,10 +110,10 @@ external multi-page PDF documents. \end{dispListing} The package |incgraph| loads the package -|pgfkeys| \cite{tantau:2013a}. If no options are given, it also -loads the packages |pgf|, |pgffor| \cite{tantau:2013a}, -the package |graphicx| \cite{carlisle:1999a}, and the -package |bookmark| \cite{oberdiek:2011a}. +|pgfkeys| \cite{tantau:tikz}. If no options are given, it also +loads the packages |pgf|, |pgffor| \cite{tantau:tikz}, +the package |graphicx| \cite{carlisle:graphics}, and the +package |bookmark| \cite{oberdiek:bookmark}. \begin{itemize} \item The option |nopgf| prevents the loading of |pgf| and |pgffor|.\\ @@ -231,13 +133,13 @@ Note that you can always load the mentioned packages yourself. This is intended to avoid possible option clashes the easy way. - +\clearpage %-------------------------------------- \section{User Interface}\label{sec:interface} \subsection{Inclusion Macros for External Graphics} The macros of this section rely on the |\includegraphics| command from -the package |graphicx| \cite{carlisle:1999a}. +the package |graphicx| \cite{carlisle:graphics}. %Section \ref{sec:basictoolbox} describes more basic commands. \begin{docCommand}{incgraph}{\oarg{options}\oarg{graphics options}\marg{file name}} @@ -247,22 +149,22 @@ the package |graphicx| \cite{carlisle:1999a}. The applicable \meta{options} are listed in Section \ref{sec:keys}. If \meta{graphics options} are given, these are added to the options for the underlying |\includegraphics| command. See the documentation of - |graphicx| \cite{carlisle:1999a} for a list of applicable \meta{graphics options}. + |graphicx| \cite{carlisle:graphics} for a list of applicable \meta{graphics options}. -\begin{texexptitled}[listing only,before={\par\medskip}]% +\begin{texexptitled}% {The hand-drawn example (centered); see page~\pageref{exacenter}}{exacenter.listing} \incgraph[paper=current,label={exacenter},overlay page number at bottom, bookmark={The hand-drawn example (centered)}]{example.jpg} \end{texexptitled} -\begin{texexptitled}[listing only,before={\par\medskip}]% +\begin{texexptitled}% {The hand-drawn example (resized page); see page~\pageref{exaresized}}{exaresized.listing} \incgraph[paper=graphics,label={exaresized}, bookmark={The hand-drawn example (resized page)}]{example.jpg} \end{texexptitled} -\begin{texexptitled}[listing only,before={\par\medskip}]% +\begin{texexptitled}% {The hand-drawn example (rotated and oversized); see page~\pageref{exarotated}}{exarotated.listing} \incgraph[paper=current,label={exarotated},target=oversized, bookmark={The hand-drawn example (rotated and oversized)}]% @@ -279,8 +181,8 @@ the package |graphicx| \cite{carlisle:1999a}. The applicable \meta{options} are listed in Section \ref{sec:keys}. If \meta{graphics options} are given, these are added to the options for the underlying |\includegraphics| command. See the documentation of - |graphicx| \cite{carlisle:1999a} for a list of applicable \meta{graphics options}.\\ - The \meta{list} may contain any construction allowed for the |\foreach| statement \cite{tantau:2013a}, + |graphicx| \cite{carlisle:graphics} for a list of applicable \meta{graphics options}.\\ + The \meta{list} may contain any construction allowed for the |\foreach| statement \cite{tantau:tikz}, especially a list of numbers. The elements of the list can be used inside the \meta{file name pattern} with the following macros: @@ -297,7 +199,7 @@ the package |graphicx| \cite{carlisle:1999a}. \end{itemize} In the default behavior, non existing files are ignored. -\begin{texexptitled}[listing only,before={\par\medskip}]% +\begin{texexptitled}% {A series of pictures; see from page~\pageref{exaseries.1}. The image files exaimage-0001.png to exaimage-0150.png are included but only three of them exist.}{exaseries.listing} @@ -315,7 +217,7 @@ the package |graphicx| \cite{carlisle:1999a}. The applicable \meta{options} are listed in Section \ref{sec:keys}. -\begin{texexptitled}[listing only,before={\par\medskip}]% +\begin{texexptitled}% {Some text on a shrunk paper; see page~\pageref{inctext1}}{inctext1.listing} \begin{inctext}[paper=graphics,label={inctext1},bookmark={A huge ABC}] \Huge ABC @@ -323,7 +225,7 @@ the package |graphicx| \cite{carlisle:1999a}. \end{texexptitled} -\begin{texexptitled}[listing only,before={\par\medskip}]% +\begin{texexptitled}% {A tikzpicture as text content; see page~\pageref{inctext2}}{inctext2.listing} \begin{inctext}[paper=a6,landscape,label={inctext2},bookmark={Graph}, overlay page number at bottom=8mm] @@ -397,7 +299,7 @@ the package |graphicx| \cite{carlisle:1999a}. |b0|, |b1|, |b2|, |b3|, |b4|, |b5|, |b6|, |b7|, |b8|, |b9|, |b10|, |c0|, |c1|, |c2|, |c3|, |c4|, |c5|, |c6|, |c7|, |c8|, |c9|, |c10|, |d0|, |d1|, |d2|, |d3|, |d4|, |d5|, |d6|, |d7|, - executive, letter, legal, ledger. + |executive|, |letter|, |legal|, |ledger|. \end{docIgrKey} \begin{docIgrKey}{landscape}{}{no value} @@ -437,10 +339,10 @@ the package |graphicx| \cite{carlisle:1999a}. \subsection{Graphics Inclusion} \begin{docIgrKey}{options}{=\marg{graphics options}}{no default, initially empty} - The \meta{graphics options} are applied to the underlying |\includegraphics| command. + The \meta{graphics options} are applied to the underlying \docAuxCommand*{includegraphics} command. See the documentation of - |graphicx| \cite{carlisle:1999a} for a list of applicable \meta{graphics options}. -\begin{texexptitled}[listing only,before={\par\medskip}]% + |graphicx| \cite{carlisle:graphics} for a list of applicable \meta{graphics options}. +\begin{texexptitled}% {A resized image; see page~\pageref{exagraphresize}}{exagraphresize.listing} \igrset{options={width=10cm,height=10cm}, paper=graphics, overlay page number at top=5mm @@ -453,31 +355,116 @@ the package |graphicx| \cite{carlisle:1999a}. \begin{docIgrKey}{options add}{=\marg{graphics options}}{no default, initially empty} The \meta{graphics options} are added to the current list of options - for the underlying |\includegraphics| command. + for the underlying \docAuxCommand*{includegraphics} command. \end{docIgrKey} \begin{docIgrKey}{include command}{\colOpt{=\meta{macro}}}{default and initially \cs{includegraphics}} - Replaces the internally used \cs{includegraphics} command by the given \meta{macro}. - Note that \meta{macro} has to have the same signature as \cs{includegraphics}, + Replaces the internally used \docAuxCommand*{includegraphics} command by the given \meta{macro}. + Note that \meta{macro} has to have the same signature as \docAuxCommand*{includegraphics}, i.\,e.\ it has to take two arguments where the first argument is optional. \end{docIgrKey} \begin{docIgrKey}{existence check}{=\meta{macro}}{no default} - Replaces the internally used \cs{IfFileExists} command by the given \meta{macro}. - Note that \meta{macro} has to have the same signature as \cs{IfFileExists}, + Replaces the internally used \docAuxCommand*{IfFileExists} + (in truth \docAuxCommand*{file_if_exist:nTF}) + command by the given \meta{macro}. + Note that \meta{macro} has to have the same signature as \docAuxCommand*{IfFileExists}, i.\,e.\ it has to take three arguments. \end{docIgrKey} -\begin{docIgrKey}{fail on not found}{}{no value} - Stops the compilation with an error if the included file does not exist. -\end{docIgrKey} +\begin{docIgrKeys}[ + doc parameter = {}, + doc description = {no value} + ] + { + { + doc name = no existence check, + doc new = 2021-10-16, + }, + { + doc name = fail on not found, + }, + } + Omits any existence checks by the package, i.e. the underlying + \docAuxCommand*{includegraphics} is called directly any may + stop the compilation with an error if the included file does not exist. + Both options are equal, but the newer \refKey{/igr/no existence check} + is considered to be more comprehensible. +\end{docIgrKeys} \begin{docIgrKey}{ignore on not found}{}{no value, initially set} - Not existing included files are ignored without warning. + Not existing included files are ignored without warning. This is the default + setting and is intended to be used with fragmentary file lists. +\end{docIgrKey} + +\clearpage + +\begin{docIgrKeys}[ + doc parameter = \colOpt{=\marg{extension list}}, + doc description = {initially unset}, + doc new = 2021-10-16, + ] + { + { + doc name = ignore on not found with extensions, + }, + { + doc name = ignore on not found with extensions*, + }, + } + Tests, if the included file with an added \emph{extension} exists and + performs the inclusion on existence. Otherwise, included files are ignored without warning. + Tested \emph{extensions} are taken from the optional comma separated \meta{extension list} + or (exclusively) from the configured list from \refKey{/igr/extensions} and friends + (only, if \meta{extension list} is not given).\par + \refKey{/igr/ignore on not found with extensions*} also tests, if the included + file without added \emph{extension} exists and takes it on existence.\par + Note that if a file is included with a given extension, this extension is not + replaced by the listed extension, but prolonged with it.\par + These options are intended for mixed file lists, e.g. |.jpg| and |.png|, or + unkown type file lists. + Note that if you \emph{know} the (singular) extension of your files, you are + encouraged to use \refKey{/igr/ignore on not found} instead for performance reasons. +\begin{dispListing} +\incmultigraph[ignore on not found with extensions={.jpg,.png}]{myfile\n}{1,...,100} + % includes e.g. `myfile1.jpg`, `myfile2.png`, `myfile42.jpg`, ... +\incmultigraph[ignore on not found with extensions={.jpg,.png}]{myfile\n.xy}{1,...,100} + % includes e.g. `myfile1.xy.jpg`, `myfile2.xy.png`, `myfile42.xy.jpg`, ... +\incgraph[ignore on not found with extensions={.jpg,.png}]{myfile} + % tests `myfile.jpg` and `myfile.png` for existence (and inclusion) +\incgraph[ignore on not found with extensions*={.jpg,.png}]{myfile} + % tests `myfile`, `myfile.jpg`, and `myfile.png` for existence (and inclusion) +\incmultigraph[ignore on not found with extensions]{myfile\n}{1,...,100} + % includes files with extensions given by /igr/extensions +\end{dispListing} +\end{docIgrKeys} + + +\begin{docIgrKey}[][doc new=2021-10-16]{extensions}{=\marg{extension list}}{initially |.jpg,.png|} + Specifies a comma separated \meta{extension list} to be used in combination with + \refKey{/igr/ignore on not found with extensions}. +\end{docIgrKey} + + +\begin{docIgrKey}[][doc new=2021-10-16]{extensions add}{=\marg{extension list}}{initially unset} + Adds a comma separated \meta{extension list} to an already defined list from + \refKey{/igr/extensions}. \end{docIgrKey} +\begin{docIgrKey}[][doc new=2021-10-16]{extensions from graphics}{}{initially unset} + Takes the list of extensions from \docAuxCommand*{DeclareGraphicsExtensions} + of the |graphics| \cite{carlisle:graphics} package as setup for \refKey{/igr/extensions}. + While this looks like the most comfortable options, this can significantely + increase compilation time when used for fragmentary file lists, because + every non-existing file from the file list will induce a lot of existence checks. + Also note that this options uses internals from |graphics| and is not + guaranteed to work with future versions of |graphics|. +\end{docIgrKey} + + +\clearpage \subsection{Hypertargets, Labels, and Bookmarks} \begin{docIgrKey}{hyper}{}{no value, initially set} @@ -515,8 +502,8 @@ see page~\pageref{exarotated.listing}. \begin{docIgrKey}{bookmark options}{=\marg{bookmark options}}{no default, initially empty} Sets the options for a bookmark. See the documentation of - |bookmark| \cite{oberdiek:2011a} for a list of applicable \meta{bookmark options}. -\begin{texexptitled}[listing only,before={\par\medskip}]% + |bookmark| \cite{oberdiek:bookmark} for a list of applicable \meta{bookmark options}. +\begin{texexptitled}% {Bookmark options; see page~\pageref{exabookmark}}{exabookmark.listing} % not every PDF reader will show the effect! \igrset{bookmark options={bold,color={red}},currentpaper} @@ -528,7 +515,7 @@ see page~\pageref{exarotated.listing}. \begin{docIgrKey}{bookmark heading}{=\meta{text}}{no default, initially empty} For \refCom{incmultigraph}, an additional bookmark with the given \meta{text} is set as a heading before the images are included. -\begin{texexptitled}[listing only,before={\par\medskip}]% +\begin{texexptitled}% {A series of pictures; see from page~\pageref{exaheading.1}}{exaheading.listing} \incmultigraph[zerofill=4,currentpaper, bookmark heading={A series of pictures}, @@ -542,7 +529,7 @@ see page~\pageref{exarotated.listing}. \begin{docIgrKey}{bookmark heading options}{=\marg{bookmark options}}{no default, initially empty} Sets the options for a \refKey{/igr/bookmark heading}. See the documentation of - |bookmark| \cite{oberdiek:2011a} for a list of applicable \meta{bookmark options}. + |bookmark| \cite{oberdiek:bookmark} for a list of applicable \meta{bookmark options}. \end{docIgrKey} \clearpage @@ -593,15 +580,15 @@ Adds a space of \meta{length} at all four sides. \refKey{/igr/if match set}, and \refKey{/igr/if match set bookmark}. -\begin{tcblisting}{docexample,listing only} +\begin{dispListing} \igrset{set matches={ foo = bar, 1 = A very red image, 37 = A not so centered number, 123 = A greenish example}} -\end{tcblisting} +\end{dispListing} \end{docIgrKey} -\tcbuselistingtext +\tcbusetemp \begin{docIgrKey}{if match code}{=\marg{key}\marg{then}\marg{else}}{no default} If the \meta{key} was defined by \refKey{/igr/set matches}, @@ -626,7 +613,7 @@ Adds a space of \meta{length} at all four sides. the corresponding value is put in the macro |\igrmatchvalue| and the current PDF bookmark is set to \meta{then}. If the \meta{key} is unknown, the current PDF bookmark is set to \meta{else}. -\begin{texexptitled}[listing only,before={\par\medskip}]% +\begin{texexptitled}% {Map and match example; see from page~\pageref{examatch.1}}{examatch.listing} \incmultigraph[zerofill=4,paper=graphics, bookmark heading={Map and match example}, @@ -651,12 +638,12 @@ Adds a space of \meta{length} at all four sides. \begin{docIgrKey}{overlay}{=\marg{tikz code}}{no default, initially unset} Introduces arbitrary \meta{tikz code} to be drawn over the included image. - Note that the |tikz| package \cite{tantau:2013a} has to be loaded separately. + Note that the \tikzname\ package \cite{tantau:tikz} has to be loaded separately. To support positioning inside the picture, two |tikz| nodes named |box| and |page| are defined. |box| takes the dimensions of the included image and |page| takes the dimensions of the image or of the page depending on the usage of \refKey{/igr/paper}. -\begin{texexptitled}[listing only,before={\par\medskip}]% +\begin{texexptitled}% {Overlay; see page~\pageref{overlay}}{overlay.listing} \igrset{bookmark options={level=subsection}, paper=current} \incgraph[bookmark={Picture with overlay},label={overlay}, @@ -694,11 +681,21 @@ Adds a space of \meta{length} at all four sides. and the result on page~\pageref{exagraphresize}. \end{docIgrKey} + +\begin{docIgrKey}[][doc new=2021-10-11]{overlay page number options}{=\marg{tikz options}}{no default, initially\\ + \texttt{fill opacity=0.35,draw opacity=0.5,text opacity=1,inner xsep=1em,\\ + rounded corners,fill=white,draw=black}} + Defines the \tikzname\ node style for drawing the page number with one + of the options above, e.g. \refKey{/igr/overlay page number at} +\end{docIgrKey} + + \begin{docIgrKey}{no overlay}{}{no value, initially set} Removes the overlay setting. \end{docIgrKey} +\clearpage \subsection{Miscellaneous} @@ -742,9 +739,12 @@ Here, the images |example.jpg|, All included images are automatically bookmarked with the page number and the file name of the source image. -\def\thecurrentexample{\jobname-example-a.tex} -\tcbinputlisting{listing file=\thecurrentexample,listing only, - example={\texttt{\thecurrentexample}}{somescans}} + +\inputexamplelisting{\jobname-example-a.tex}{somescans} + +%\def\thecurrentexample{\jobname-example-a.tex} +%\tcbinputlisting{listing file=\thecurrentexample,listing only, +% example={\texttt{\thecurrentexample}}{somescans}} The compiled result of this stand-alone source code is not found in this document but as a separate file in the documentation directory of the package. @@ -769,9 +769,12 @@ The example shows a mixed usage of the macros. Note that the bookmarks of the multi-page part are matched with the numbers contained in the file names of |exaimage-0001.png| to |exaimage-0150.png|. -\def\thecurrentexample{\jobname-example-b.tex} -\tcbinputlisting{listing file=\thecurrentexample,listing only, - example={\texttt{\thecurrentexample}}{picturebook}} + +\inputexamplelisting{\jobname-example-b.tex}{picturebook} + +%\def\thecurrentexample{\jobname-example-b.tex} +%\tcbinputlisting{listing file=\thecurrentexample,listing only, +% example={\texttt{\thecurrentexample}}{picturebook}} The compiled result of this stand-alone source code is not found in this document but as a separate file in the documentation directory of the package. @@ -780,7 +783,7 @@ a separate file in the documentation directory of the package. \clearpage \subsection{Reformatting from Letter to DIN A4 (and vice versa)} In this scenario, we assume to have a PDF document with the 'wrong' paper size. -Here, |incgraph-example-a.pdf| has the letter format, but DIN A4 paper +Here, |incgraph-example-a.pdf| has the letter format, but A4 paper is needed. |incgraph| is used to reformat to the desired paper size. Of course, it also works the other way around. @@ -793,9 +796,12 @@ shrunk or enlarged easily by adding a |scale| option for the underlying |\includegraphics| macro. -\def\thecurrentexample{\jobname-example-c.tex} -\tcbinputlisting{listing file=\thecurrentexample,listing only, - example={\texttt{\thecurrentexample}}{reformatting}} +\inputexamplelisting{\jobname-example-c.tex}{reformatting} + +%\def\thecurrentexample{\jobname-example-c.tex} +%\tcbinputlisting{listing file=\thecurrentexample,listing only, +% example={\texttt{\thecurrentexample}}{reformatting}} + The compiled result of this stand-alone source code is not found in this document but as a separate file in the documentation directory of the package. @@ -817,7 +823,7 @@ In Example \ref{fullpaperdrawing1}, a |tikzpicture| is drawn. The whole picture is put inside an \refEnv{inctext} environment which puts the drawing on a separate page which gets the dimensions of the drawing. -\begin{texexptitled}[listing only]{Creation of a special text page (resized)}{fullpaperdrawing1} +\begin{texexptitled}{Creation of a special text page (resized)}{fullpaperdrawing1} \begin{inctext}[paper=graphics, bookmark=My special text page (resized)] \begin{tikzpicture}% \coordinate (A) at (0,0); \coordinate (B) at (16,16); @@ -848,7 +854,7 @@ To draw seamlessly, the document paper size of 21cm to 29.7cm is used directly inside the |tikzpicture|. -\begin{texexptitled}[listing only]{Creation of a special text page (fitted)}{fullpaperdrawing2} +\begin{texexptitled}{Creation of a special text page (fitted)}{fullpaperdrawing2} \begin{inctext}[paper=current, target=mytarget, bookmark=My special text page (fitted)] \begin{tikzpicture}% @@ -885,6 +891,59 @@ It is assumed that most users will only need the macros from the user interface described in Section \ref{sec:interface} and Section \ref{sec:keys}. +\subsection{Page Size Commands} + +The following macros are auxiliary tools which wrap corresponding length registers +from |pdflatex| and |lualatex|. + +\begin{docCommand}[doc new=2021-10-12]{igrGetPageSize}{} + Reads the current page dimensions and stores them into the macros + \refCom{igrPageWidth} and \refCom{igrPageHeight}. +\end{docCommand} + +\begin{docCommand}[doc new=2021-10-12]{igrPageWidth}{} + After using \refCom{igrGetPageSize}, \refCom{igrPageWidth} contains + the current page width. This is |\pdfpagewidth| for |pdflatex|, + |\pagewidth| for |lualatex| and a choice of |\pdfpagewidth| or |\paperwidth| + for other engines. +\end{docCommand} + +\begin{docCommand}[doc new=2021-10-12]{igrPageHeight}{} + After using \refCom{igrGetPageSize}, \refCom{igrPageHeight} contains + the current page height. This is |\pdfpageheight| for |pdflatex|, + |\pageheight| for |lualatex| and a choice of |\pdfpageheight| or |\paperheight| + for other engines. +\end{docCommand} + + +\begin{docCommand}[doc new=2021-10-12]{igrSetPageSize}{\marg{width}\marg{height}} + Sets the current page dimensions to \meta{width} and \meta{height}. + In depends on the used engine, if a call to this command has success or + not. This should work for |pdflatex| and |lualatex|. +\end{docCommand} + + +\subsection{Last Page Commands (Number of Pages)} + +The following macros are auxiliary tools which wrap corresponding functions +from |pdflatex| and |lualatex|. + +\begin{docCommand}[doc new=2021-10-18]{igrGetLastPage}{\marg{file}} + Reads the last page (page count) from the given (PDF-)\meta{file} + and stores it into the macro \refCom{igrLastPage}. +\end{docCommand} + + +\begin{docCommand}[doc new=2021-10-18]{igrLastPage}{} + After using \refCom{igrGetLastPage}, \refCom{igrLastPage} contains + the last page of the currently tested file. + This is |\pdflastximagepages| for |pdflatex|, + |\lastsavedimageresourcepages| for |lualatex| and simply $1$ + for other engines. +\end{docCommand} + + +\clearpage \subsection{Full Page Commands} \begin{docCommand}{igrpage}{\marg{text}} @@ -967,7 +1026,7 @@ user interface described in Section \ref{sec:interface} and Section \ref{sec:key \clearpage \begin{docCommand}{igrboxtikz}{} The current content of the |\igrbox| is embedded into a |\node| command - from the |tikz| package \cite{tantau:2013a} which has to be loaded separately. + from the |tikz| package \cite{tantau:tikz} which has to be loaded separately. Also, the bounding box is adjusted to the |\igrbox|.\\ To support positioning inside the picture, two |tikz| nodes named |box| and |page| are defined which both take the dimensions of the |\igrbox|. @@ -1002,7 +1061,7 @@ The boxing macros can also be used nested (see the result on the following page) \begin{docCommand}{igrboxtikzcenter}{} The current content of the |\igrbox| is embedded into a |\node| command - from the |tikz| package \cite{tantau:2013a} which has to be loaded separately. + from the |tikz| package \cite{tantau:tikz} which has to be loaded separately. This node is placed in the center of a bounding box which takes the current page dimensions. Afterwards, |\igrBoxWidth| and |\igrBoxHeight| are redefined to the dimensions of the total page.\\ @@ -1037,7 +1096,7 @@ See the result on the following page. \igrsetmatchvalue{my key A}{my value A} \def\keytester#1{\igrifmatch{#1}{Hurray: '\igrmatchvalue'}{'#1' unknown}} -\keytester{foo}\\ +\keytester{something}\\ \keytester{my key A} \end{dispExample} \end{docCommand} @@ -1050,7 +1109,7 @@ See the result on the following page. \igrsetmatches{my key A = my value A, bar = Shakespeare} \def\keytester#1{\igrifmatch{#1}{Hurray: '\igrmatchvalue'}{'#1' unknown}} -\keytester{foo}\\ +\keytester{something}\\ \keytester{bar}\\ \keytester{my key A} \end{dispExample} @@ -1117,33 +1176,33 @@ See the result on the following page. % Do not follow this bad example ... \begin{tcbverbatimwrite}{\jobname.bib} -@manual{tantau:2013a, +@manual{tantau:tikz, author = {Till Tantau}, title = {The TikZ and PGF Packages}, - subtitle = {Manual for version 3.0.0}, - url = {http://sourceforge.net/projects/pgf/}, - date = {2013-12-20}, + subtitle = {Manual for version 3.1.9a}, + url = {https://mirrors.ctan.org/graphics/pgf/base/doc/pgfmanual.pdf}, + date = {2021-05-15}, } -@manual{carlisle:1999a, - author = {D. P. Carlisle and S. P. Q. Rahtz}, - title = {The graphicx package}, - url = {http://mirror.ctan.org/macros/latex/required/graphics/}, - date = {1999-02-16}, +@manual{carlisle:graphics, + author = {D. P. Carlisle}, + title = {Packages in the ‘graphics’ bundle}, + url = {https://mirrors.ctan.org/macros/latex/required/graphics/grfguide.pdf}, + date = {2021-03-05}, } -@manual{matthias:2012a, +@manual{matthias:pdfpages, author = {Andreas Matthias}, title = {The pdfpages Package}, - url = {http://mirror.ctan.org/macros/latex/contrib/pdfpages/pdfpages.pdf}, - date = {2012-04-03}, + url = {https://mirrors.ctan.org/macros/latex/contrib/pdfpages/pdfpages.pdf}, + date = {2021-03-06}, } -@manual{oberdiek:2011a, +@manual{oberdiek:bookmark, author = {Heiko Oberdiek}, title = {The bookmark Package}, - url = {http://mirror.ctan.org/macros/latex/contrib/oberdiek/bookmark.pdf}, - date = {2011-12-02}, + url = {https://mirrors.ctan.org/macros/latex/contrib/bookmark/bookmark.pdf}, + date = {2020-11-06}, } \end{tcbverbatimwrite} |