summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/standalone/standalone.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/standalone/standalone.dtx')
-rw-r--r--macros/latex/contrib/standalone/standalone.dtx483
1 files changed, 331 insertions, 152 deletions
diff --git a/macros/latex/contrib/standalone/standalone.dtx b/macros/latex/contrib/standalone/standalone.dtx
index 322797c310..708a6b4e82 100644
--- a/macros/latex/contrib/standalone/standalone.dtx
+++ b/macros/latex/contrib/standalone/standalone.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%<=*COPYRIGHT>
-%% Copyright (C) 2010-2022 by Martin Scharrer <martin.scharrer@web.de>
+%% Copyright (C) 2010-2025 by Martin Scharrer <martin.scharrer@web.de>
%% ---------------------------------------------------------------------------
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3
@@ -26,10 +26,10 @@
\NeedsTeXFormat{LaTeX2e}
\ProvidesFile{standalone.dtx}[%
%<=*DATE>
- 2022/10/10
+ 2025/02/21
%<=/DATE>
%<=*VERSION>
- v1.3b
+ v1.5
%<=/VERSION>
DTX file of the standalone bundle]
\documentclass[a4paper,11pt]{ydoc}
@@ -61,7 +61,7 @@
%</driver>
% \fi
%
-% \CheckSum{3934}
+% \CheckSum{3944}
%
% \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
@@ -95,6 +95,8 @@
% Changed filemodedate code to support LuaTeX.
% Fixes for option combination multi,convert.}
% \changes{v1.3b}{2022/10/10}{Fixed incorrect/unwanted messages for conversion feature. Updated project URLs in documentation. Added dependency list file.}
+% \changes{v1.4}{2022/11/11}{Updated conversion feature.}
+% \changes{v1.5}{2025/02/21}{Set papersize special for lualatex/xelatex. Some corrections to the manual.}
%
% \GetFileInfo{\jobname.dtx}
%
@@ -236,8 +238,8 @@
% The package \cls{standalone} can be used in the main document to skip all extra preambles in included files. The main file must load all packages
% and settings required by the sub-files. Several package options are provided to collect the preambles of the sub-files automatically and execute them from the main file.
%
-% A \cls{standalone} class is also provided to minimise the extra preamble code needed in this files.
-% It's usage is optional, but simplifies and standardises how picture files are compiled standalone.
+% A \cls{standalone} class is also provided to minimise the extra preamble code needed in these files.
+% Its usage is optional, but simplifies and standardises how picture files are compiled standalone.
% The class uses by default the \opt{crop} option to create an output file which only contains the picture with no extra
% margins, page numbers or anything else.
% A configuration file \file{standalone.cfg} read by the class allows the user to adjust settings and macros easily
@@ -318,7 +320,7 @@
% Page number and other header or footer material will be suppressed.
%
% For pictures drawn with TikZ a dedicated \opt{tikz} option is provided which loads the \pkg{tikz} package and also configures the \env{tikzpicture} environment to create a single cropped page.
-% For PSTricks pictures an corresponding \opt{pstricks} option is provided.
+% For PSTricks pictures a corresponding \opt{pstricks} option is provided.
%
% \par\noindent
% \begin{minipage}{\textwidth}
@@ -368,7 +370,7 @@
% \DescribeKey{preview}'=true|false'
% If enabled this option loads the \pkg{preview} package with the \opt{tightpage} option
% and wraps the content into a \env{preview} environment. This crops the content to its natural size plus a specified border.
-% Issues with the \pkg{preview} options and TikZ shadings under \XeLaTeX have been reported. In this cases the \opt{crop} option should be used instead.
+% Issues with the \pkg{preview} option and TikZ shadings under \XeLaTeX{} have been reported. In this cases the \opt{crop} option should be used instead.
% Note that this option was enabled by default for versions before v1.0, but since then \opt{crop} is enabled by
% default.
%
@@ -405,7 +407,7 @@
% will not affect later code. Code in the preamble is not affected.
% It is recommended to keep this option disabled and only use it if really required.
% It should be noted that which \opt{preview} such material is always ignored while not affecting local settings.
-% Therefore the \opt{ignorrest} option can be seen as a compatibility setting to make \opt{crop} act more like \opt{preview}, if this is required by the user.
+% Therefore the \opt{ignorerest} option can be seen as a compatibility setting to make \opt{crop} act more like \opt{preview}, if this is required by the user.
%
%
% \DescribeKey{multido}'=true|false'
@@ -432,7 +434,7 @@
% but will always use the natural width of the content if it is smaller than the given maximum width.
% The resulting effect is that the created paragraph will not cause any additional width and that multiple paragraphs can be included as part of the content.
% The used maximal width (which is provided to the underlying \env{minipage} environment) is \Macro\linewidth by default, but can be set
-% by provided a width as value to the option. Doing so will also switch the option on.
+% by providing a width as value to the option. Doing so will also switch the option on.
%
% If the \opt{crop} option is used the content is placed in restricted horizontal mode which ignores paragraph breaks.
% Using the \opt{varwidth} option paragraph breaks are enabled again.
@@ -468,6 +470,10 @@
%
% \DescribeKey{convert}'='{<conversion options>}
% \DescribeKey{png}'='{<conversion options>}
+% \DescribeKey{jpg}'='{<conversion options>}
+% \DescribeKey{gif}'='{<conversion options>}
+% \DescribeKey{svg}'='{<conversion options>}
+% \DescribeKey{emf}'='{<conversion options>}
% These options allow to enable and configure the conversion feature. See \autoref{sec:convert} for the full description.
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -606,13 +612,85 @@
% Because it can be assumed that the bundle configuration file resides inside a \file{standalone} directory, therefore it can be loaded from a user configuration file using
% \Macro\input{standalone/standalone.cfg}.
%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% \subsection{Simple TeX File}
+% A simple \file{standalone.tex} file is provided together with the bundle, which may be useful in special occasions.
+% It will set the \cs{ifstandalone} switch to \emph{true} when compiled standalone but to \emph{false}
+% when loaded after any |\documentclass| macro, as long the switch isn't defined yet.
+% It must be used if this switch is required before the |\documentclass| of a standalone file.
+%
+% \noindent
+% \begin{minipage}{\textwidth}\noindent
+% \begin{lstlisting}[language={[latex]tex},gobble=4,frame=lines,numbers=none,caption={Usage of 'standalone.tex'.}]
+% \input{standalone} % use before any '\documentclass'
+% \ifstandalone
+% % Used only if compiled standalone
+% \fi
+% \end{lstlisting}
+% \end{minipage}
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% \subsection{Conversion to images}\label{sec:convert}
+% \subsection{FAQ / Troubleshooting}\label{sec:classfaq}
+% This section expands some issues and their solution which can arise with the \cls{standalone} class.
+%
+% \subsubsection*{Large white space / border at the right side}
+% A large white space / border on the right side occurs when the content is placed inside a paragraph.
+% This causes the content to be \Macro\linewidth wide and so smaller pictures will contain now a white space at the right.
+% A common cause for this is that there was is a empty line between the content and \Macro\end{document} which causes a paragraph break.
+%
+% This issue can be solved by either removing any trailing lines or other paragraph breaks, or by using the \opt{varwidth} option which suppresses the extra added width.
+% It is also possible to use the \opt{multi} option and \Macro\standaloneenv{<environment name>} to declare certain environments as page content.
+% The \opt{tikz} option does this for \env{tikzpictures} and the \opt{pstricks} option for \env{pspicture}. See the descriptions of these options for more details.
+%
+% \subsubsection*{Some amount of the content on the right side is missing}
+% If the content is cropped to much on the right side, check if the \opt{varwidth} option is used. In this case the used maximum width (\Macro\linewidth by default) is too small.
+% A larger width can be set using \hbox{\opt{varwidth}\MacroArgs'='<length>} or the option can be disabled altogether using \hbox{\opt{varwidth}|=false|}.
+% The largest width possible is given by \Macro\maxdimen, which however might cause internal overflows.
+%
+% This can also be caused with \cls{beamer} content (i.e.\ when the \opt{beamer} option is used). In this case no cropping or \env{varwidth} environment is used at all,
+% but the content is simply to large to fit on a \cls{beamer} \env{frame}. To avoid this rescale the content to do fit. This can be realised by either using
+% scaling facilities of the used picture environment (like |scale| with \env{environment}, but this only scales coordinates) or using \Macro\scalebox or \Macro\resizebox from \pkg{graphicx}.
+% For complicated code which contains verbatim or other catcode changing code either the \Macro\Resizebox from the \pkg{realboxes} package
+% or the \MacroArgs{adjustbox}{scale=<factor>} environment from the \pkg{adjustbox} package should be used.
+%
+% \subsubsection*{A multi-page document contains some pages with unwanted content}
+% This is caused while \opt{multi}|=true| and \opt{crop}|=true| are set but \opt{ignorerest}|=false| \emph{and} the document contains
+% typeset material outside of environments declared with \Macro\standaloneenv. To avoid that this extra material should be removed or \opt{ignorerest} should be set to |true|.
+% This will also ignore all settings inside the document body which are not inside a declared environment. These can be moved to the preamble instead.
+% See the description of the \opt{ignorerest} option for more details.
+%
+% \subsubsection*{In a multi-page document using DVI/PS mode all pages except the first have a vertical offset}
+% The vertical reference points in PostScript could does not change when the pages are resized to fit the individual content of every page.
+% Therefore an offset is added to compensate for this, which shifts the content to the appropriate vertical position.
+% Should this not work as expected please inform the package author and provide a small example which causes this issue, together with the version number of the used |latex| compiler and tools (like |dvips|, |ps2pdf|)
+% as well as the used \cls{standalone} bundle.
+%
+% \subsubsection*{Issues with cropped files in DVI mode}
+% The \opt{crop} option uses PostScript commans in DVI mode, i.e.\ when |latex| not |pdflatex| (or others) is used as a compiler.
+% This PostScript commands will only work once the DVI is converted to PS or EPS.
+% Currently this cropping code is experimental and might not produce a full (E)PS standard compatible file.
+% This can lead to wrong bounding boxes and wrong orientations or, dependent on the used PostScript tool, even to PostScript compiler errors.
+% Some issues can be overcome by converting the the (E)PS file to a (more) standard compatible version using tools like |eps2eps| or Ghostscript.
+%
+% \subsubsection*{Errors ``Float(s) lost'' or ``not in outer par mode''}
+% Floating environments like \env{figure} or \env{table} can not be used while \Key{float}'=true' and either \Key{crop}'=true' or \Key{preview}'=true' is set.
+% The last two options will try to store the float into a box which is not allowed (because it can't the float any longer).
+% Usually \Key{float}'=false' will solve this error, because it turns these environments into non-floating alternatives.
+% Because both the \Key{crop} and \Key{preview} option will set \Key{float}'=false' themselves, this issue can only arise when the \Key{float} option is manually set afterwards.
+%
+% \subsubsection*{Image conversion does not work}
+% In order for the image conversion to work an external conversion software must be installed. By default either Image Magkick or GhostScript is used. Please insure that either or both of these softwares are installed.
+% Installation guide for your operating system should be easily available on the Internet. The \LaTeX\ compiler option |-shell-escape| must be used to allow this external software to be executed from within the \LaTeX\ code.
+% If this two points are fulfilled but the conversion does still not work, please check the log file. The lines in question start with `|runsystem|' (at least with \TeX\ Live 2011).
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% \section{Conversion to images}\label{sec:convert}
% Using the \opt{convert} class option the standalone file can be easily converted to an raster image. This is done by executing an external program to convert the output file (PDF or PS) to
% an image (recommended is the lossless PNG format, but also others are supported).
%
-% \subsubsection{Conversion settings}
+% \subsection{Conversion settings}
% Conversion settings can be given as the value of the \Key{convert}'='{<settings>} option.
% By default conversion is disabled (\Key{convert}'=false'). If enabled without providing own settings (\Key{convert}, \Key{convert}'=true')
% the following default settings are used: PNG format, a density of 300dpi, no explicit size and the output file name is given by \Macro\jobname, i.e.\ the name of the \LaTeX\ document.
@@ -634,22 +712,39 @@
% true & Conversion enabled (with default settings if no other options are given) & (no value) \\
% false & Conversion disabled & (no value) \\
% \midrule
+% png & Selects PNG output format & \\
+% jpg & Selects JPG output format & \\
+% gif & Selects GIF output format using \emph{ImageMagick}. & \\
+% svg & Selects SVG output format using \emph{Inkscape}. & \\
+% emf & Selects EMF output format using \emph{Inkscape}. & \\
+% \midrule
% density & Sets the density in dots-per-inch (dpi). Can be a single numerical value or `\meta{X}|x|\meta{Y}'. & |300| \\
% size & Sets the size of the image. Can be a single numerical value or `\meta{X}|x|\meta{Y}'. If empty the size is determined by the density setting and the size of the PDF. & (empty) \\
% subjobname & The jobname used for the internal \LaTeX\ run & |\jobname| \\
% inext & Input file extension including the leading dot & |.pdf| or |.ps| \\
% inname & Name base of input file (i.e.\ file name without extension) & |\subjobname| \\
-% infile & Input file name & |\inname\inext| \\
+% infile & Input file name & |\indir\inname\inext| \\
% outext & Output file extension including the leading dot & |.png| \\
% outname & Name base of output file & |\inname| \\
-% outfile & Output file name & |\outname\outext| \\
+% outfile & Output file name & |\outdir\outname\outext| \\
+% \midrule
+% outputdir & Directory to be used for the \LaTeX\ compilers |-output-directory| option.
+% This will cause that all \LaTeX\ output files from the internal run will be created and read-back from the given directory.
+% This option shall be set if the main \LaTeX\ compiler run is called with the |-output-directory| option but can also be used on its own.
+% If not empty the directory must end with a slash `/'. & (empty) \\
+% outdir & Output directory where the conversion result shall be created. If not empty the directory must end with a slash `/'. & |\outputdir| \\
+% indir & Input directory, e.g.\ where the PDF is created. If not empty the directory must end with a slash `/'. & |\outputdir| \\
% \bottomrule\noalign{\smallskip}
% \multicolumn{3}{l}{%
% \strut Note: the settings (except 'true' and 'false') can also be used as macros in other settings.
% }%
-% \end{tabular}
-% \hss}
-% \medskip
+% \end{tabular}%
+% \hss}%
+% \end{table}
+%
+% \begin{table}
+% \vspace*{-10ex}%
+% \belowcaptionskip=\abovecaptionskip
% \caption{Advanced Conversion Options}\label{tab:advconvopt}
% \hbox to \textwidth{\hss%
% \begin{tabular}{>{\ttfamily}lp{\dimexpr.6\textwidth\relax}l}
@@ -657,6 +752,7 @@
% \multicolumn{1}{l}{Sub-Option} & Description & Default value \\
% \midrule
% command & Command line used for conversion. & (see |imagemagick|) \\
+% perpage & Boolean value. If set to |true| (default if used without a value) the conversion command is called once per page. Needs the \opt{multi} option to be enabled. \\
% imagemagick & Sets the convert command to use Image Magick: \newline\bigskip
% \hspace*{-5em}\hbox{\vtop{\hbox{\strut|command=\unexpanded{{\convertexe\space -density \density\space |\vrule height 2\ht\strutbox width 0pt{}}%
% \hbox{\strut| \infile\space \ifx\size\empty\else |}%
@@ -666,42 +762,46 @@
% \hspace*{-5em}\hbox{\vtop{\hbox{\strut|command=\unexpanded{{\gsexe\space -dSAFER -dBATCH -dNOPAUSE|\vrule height 2\ht\strutbox width 0pt{}}%
% \hbox{\strut| -sDEVICE=\gsdevice\space -r\density\space|}%
% \hbox{\strut| -sOutputFile=\outfile\space \infile}}|}}\hss} \\
+% ghostscript32 & Sets the convert command to use Ghostscript and |gsexe| to the 32-bit executable. \\
+% ghostscript64 & Sets the convert command to use Ghostscript and |gsexe| to the 64-bit executable. \\
% gsexe & Name of the executable of Ghostscript. & (see \autoref{sec:convprogs}) \\
-% precommand & Command to be executed before the actual conversion command. & {\tabular[t]{@{}l@{}}|dvips \subjobname| (DVI/PS),\\empty (PDF)\endtabular} \\
% gsdevice & The output device to be used for ghostscript. Already set up for PNG and JPG output. & \parbox[t]{15em}{Uses known device if defined for output format, otherwise the output format itself.}\\
+% precommand & Command to be executed before the actual conversion command. & {\tabular[t]{@{}l@{}}|dvips \subjobname| (DVI/PS),\\empty (PDF)\endtabular} \\
% onfailure & Sets if an type of `message' which should be triggered on conversion failure: |error|, |warning|, |info| or |ignore|. & |warning| \\
+%
% \bottomrule
-% \end{tabular}
-% \hss}
+% \end{tabular}%
+% \hss}%
% \end{table}
%
-% \subsubsection{Conversion software}\label{sec:convprogs}
-% The conversion requires an external image converter program to be installed. By default the two following tools are supported and either of them must be installed in order to use the conversion feature.
+% \subsection{Conversion software}\label{sec:convprogs}
+% The conversion requires an external image converter program to be installed. The two following tools are supported.
% In order for an external program to be executed the \texttt{-shell-escape} option\footnote{Maybe named differently depending on the used \LaTeX\ distribution} must be used for the
-% compiler executable, e.g.\ \texttt{pdflatex -shell-escape filename}. Without this option no conversion is possible.
+% compiler executable, e.g.\ \texttt{pdflatex -shell-escape filename}. Without this option no conversion is possible as \LaTeX\ will block calls to the shell.
%
-% By default the conversion program of \href{http://www.imagemagick.org/}{Image Magick} is used for PDF \LaTeX\ files, which is freely available for Unix/Linux, Mac and MS Windows.
-% Under Ubuntu Linux it can be installed using the shell command `\texttt{sudo apt-get install imagemagick}'.
-% The conversion executable is simply called `|convert|'. However, there is another program with the same name provided by MS Windows itself which
-% converts old FAT filesystems to NTFS! It has been suggested to rename the Image Magick executable to `|imgconvert|' instead.
-% By default \cls{standalone} uses `|imgconvert|' as executable if MS Windows is detected and `|convert|' otherwise.
-% The executable name can be change manually using the `|convertexe|' conversion option or by using
-% \codeline{\AlsoMacro\standaloneconfig{'convert='{'convertexe='{convert}}}}
-% in the configuration file `|standalone.cfg|'.
-%
-% Another conversion program is \href{http://pages.cs.wisc.edu/~ghost/}{Ghostscript} which is a very common PostScript interpreter which also supports PDF.
-% It is used by default for DVI/PS files.
-% Under Ubuntu Linux it is most likely already installed but otherwise can be installed using `|sudo apt-get install ghostscript|' or
-% `|sudo apt-get install gs|'.
+% By default the conversion program \href{https://pages.cs.wisc.edu/~ghost/}{Ghostscript} is used, which is a very common PostScript interpreter which also supports PDF.
+% Under Ubuntu Linux it is most likely already installed but otherwise can be installed using `\texttt{sudo apt-get install ghostscript}' or
+% `\texttt{sudo apt-get install gs}'.
% It can convert both to various output formats and is freely available for Unix/Linux, Max OS X and MS Windows.
% It requires to set the correct output device which is not always fully identical to the output format (e.g.\ `|png16m|' for a PNG (with 16 million colors)).
% The devices for PNG and JPG are already configured.
% Other devices can be configured using the \Key{defgsdevice}'='{<.extension>}{<device>} conversion setting.
-% The Ghostscript executable is usually named `|gs|' under Linux/Unix and `|gswin32c|' under MS Windows and configured this way by default,
-% but this may be changed using the |gsexe| setting.
+% The Ghostscript executable is usually named `|gs|' under Linux/Unix and `|gswin64c|' (32-bit version: `|gswin32c|') under MS Windows and configured this way by default,
+% but this may be changed using the |gsexe| setting. By default the 64-bit version is used, which can be changed to the 32-bit version using the \opt{ghostscript32} convert option.
+%
+% Also supported is the conversion program \href{https://www.imagemagick.org/}{Image Magick}, which is freely available for Unix/Linux, Mac and MS Windows.
+% For PDF input it will however use \emph{Ghostscript} internally, but adds more output filetypes like the GIF format.
+% Under Ubuntu Linux it can be installed using the shell command `\texttt{sudo apt-get install imagemagick}'.
+% The conversion executable was orinally called `|convert|', which clashed with a MS Windows FAT-to-NTFS converter.
+% Newer version name the executable `|magick|' where the convert command must be given as an argument: `|magick convert|'.
+% If needed the executable name can be change manually using the `|convertexe|' conversion option or by using
+% \codeline{\AlsoMacro\standaloneconfig{'convert='{'convertexe='{...}}}} in the configuration file `|standalone.cfg|'.
%
+% Furthermore the vector graphics software \href{https://inkscape.org/}{Inkscape} is supported.
+% It allows the conversion from PDF files to SVG, useful for web publishing, and to EMF, which is useful for including the diagrams in MS Office.
+% It is also freely available for MS Windows, Linux and macOS.
%
-% \subsubsection{Conversion process}
+% \subsection{Conversion process}
% The conversion process is currently implemented in the following way to allow the normal compilation and subsequent conversion using only one (manual) compiler run.
% Because the document must be fully compiled before the conversion can occur the \cls{standalone} executes the same \LaTeX\ compiler (e.g.\ texttt{pdflatex}) again as
% a sub-process which compiles the current document fully. This is done when the \cls{standalone} class is loaded, so that the main compiler instance is still at \Macro\documentclass
@@ -711,9 +811,34 @@
% A drawback of this implementation is that the log file created by the sub-process is overwritten by the main process and does not hold meaningful information.
% This can be compensated by setting a different jobname for the sub-process using the \Key{subjobname} conversion setting.
%
-% \subsubsection{Conversion examples}
+% \subsection{Conversion examples}
+%
+% \par\medskip\noindent
+% Produces PNG (default) with a size of 640px (suitable to be uploaded on StackExchange sites without the image getting downscaled):\\*[\smallskipamount]
+% | \documentclass[convert={size=640}]{standalone}|
+%
+% \par\medskip\noindent
+% Produces EMF, a vector format suitable for inclusion in MS Word or other MS Office software. Text content will be rendered as curves and will not be able to be copied
+% as text. This needs \emph{Inkscape} to be installed as other conversion softwares do not support this output format.\\*[\smallskipamount]
+% | \documentclass[emf]{standalone}|\\
+% or \\
+% | \documentclass[convert={emf}]{standalone}|
+%
+% \par\medskip\noindent
+% Produces SVG, a vector format suitable for inclusion in websites. Text content will be rendered as curves and will not be able to be copied
+% as text. This needs \emph{Inkscape} to be installed as other conversion softwares do not support this output format.\\*[\smallskipamount]
+% | \documentclass[svg]{standalone}|\\
+% or \\
+% | \documentclass[convert={svg}]{standalone}|
+%
+% \par\medskip\noindent
+% Produces GIF with a size of 640px. This needs \emph{ImageMagick} to be installed as other conversion softwares do not support this output format.\\*[\smallskipamount]
+% | \documentclass[gif={size=640}]{standalone}|\\
+% or \\
+% | \documentclass[convert={gif,size=640}]{standalone}|
%
-% PDF/PS is rastered with 600x100dpi and then converted to JPG:\\*[\smallskipamount]
+% \par\medskip\noindent
+% PDF/PS is rastered with 600x100dpi and then converted to JPG (not recommended):\\*[\smallskipamount]
% | \documentclass[convert={density=600x100,outext=.jpg}]{standalone}|
%
% \par\medskip\noindent
@@ -725,82 +850,6 @@
% | \documentclass[convert={ghostscript,gsdevice=tiffg4,|\\*
% | outext=.tiff,density=72}]{standalone}|
%
-% \par\medskip\noindent
-% Produces PNG (default) with a size of 640px (suitable to be uploaded on StackExchange sites without the image getting downscaled):\\*[\smallskipamount]
-% | \documentclass[convert={size=640}]{standalone}|
-%
-%
-% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%
-% \subsection{Simple TeX File}
-% A simple \file{standalone.tex} file is provided together with the bundle, which may be useful in special occasions.
-% It will set the \cs{ifstandalone} switch to \emph{true} when compiled standalone but to \emph{false}
-% when loaded after any |\documentclass| macro, as long the switch isn't defined yet.
-% It must be used if this switch is required before the |\documentclass| of a standalone file.
-%
-% \noindent
-% \begin{minipage}{\textwidth}\noindent
-% \begin{lstlisting}[language={[latex]tex},gobble=4,frame=lines,numbers=none,caption={Usage of 'standalone.tex'.}]
-% \input{standalone} % use before any '\documentclass'
-% \ifstandalone
-% % Used only if compiled standalone
-% \fi
-% \end{lstlisting}
-% \end{minipage}
-%
-% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% \subsection{FAQ / Troubleshooting}\label{sec:classfaq}
-% This section expands some issues and their solution which can arise with the \cls{standalone} class.
-%
-% \subsubsection*{Large white space / border at the right side}
-% A large white space / border on the right side occurs when the content is placed inside a paragraph.
-% This causes the content to be \Macro\linewidth wide and so smaller pictures will contain now a white space at the right.
-% A common cause for this is that there was is a empty line between the content and \Macro\end{document} which causes a paragraph break.
-%
-% This issue can be solved by either removing any trailing lines or other paragraph breaks, or by using the \opt{varwidth} option which suppresses the extra added width.
-% It is also possible to use the \opt{multi} option and \Macro\standaloneenv{<environment name>} to declare certain environments as page content.
-% The \opt{tikz} option does this for \env{tikzpictures} and the \opt{pstricks} option for \env{pspicture}. See the descriptions of these options for more details.
-%
-% \subsubsection*{Some amount of the content on the right side is missing}
-% If the content is cropped to much on the right side, check if the \opt{varwidth} option is used. In this case the used maximum width (\Macro\linewidth by default) is too small.
-% A larger width can be set using \hbox{\opt{varwidth}\MacroArgs'='<length>} or the option can be disabled altogether using \hbox{\opt{varwidth}|=false|}.
-% The largest width possible is given by \Macro\maxdimen, which however might cause internal overflows.
-%
-% This can also be caused with \cls{beamer} content (i.e.\ when the \opt{beamer} option is used). In this case no cropping or \env{varwidth} environment is used at all,
-% but the content is simply to large to fit on a \cls{beamer} \env{frame}. To avoid this rescale the content to do fit. This can be realised by either using
-% scaling facilities of the used picture environment (like |scale| with \env{environment}, but this only scales coordinates) or using \Macro\scalebox or \Macro\resizebox from \pkg{graphicx}.
-% For complicated code which contains verbatim or other catcode changing code either the \Macro\Resizebox from the \pkg{realboxes} package
-% or the \MacroArgs{adjustbox}{scale=<factor>} environment from the \pkg{adjustbox} package should be used.
-%
-% \subsubsection*{A multi-page document contains some pages with unwanted content}
-% This is caused while \opt{multi}|=true| and \opt{crop}|=true| are set but \opt{ignorerest}|=false| \emph{and} the document contains
-% typeset material outside of environments declared with \Macro\standaloneenv. To avoid that this extra material should be removed or \opt{ignorerest} should be set to |true|.
-% This will also ignore all settings inside the document body which are not inside a declared environment. These can be moved to the preamble instead.
-% See the description of the \opt{ignorerest} option for more details.
-%
-% \subsubsection*{In a multi-page document using DVI/PS mode all pages except the first have a vertical offset}
-% The vertical reference points in PostScript could does not change when the pages are resized to fit the individual content of every page.
-% Therefore an offset is added to compensate for this, which shifts the content to the appropriate vertical position.
-% Should this not work as expected please inform the package author and provide a small example which causes this issue, together with the version number of the used |latex| compiler and tools (like |dvips|, |ps2pdf|)
-% as well as the used \cls{standalone} bundle.
-%
-% \subsubsection*{Issues with cropped files in DVI mode}
-% The \opt{crop} option uses PostScript commans in DVI mode, i.e.\ when |latex| not |pdflatex| (or others) is used as a compiler.
-% This PostScript commands will only work once the DVI is converted to PS or EPS.
-% Currently this cropping code is experimental and might not produce a full (E)PS standard compatible file.
-% This can lead to wrong bounding boxes and wrong orientations or, dependent on the used PostScript tool, even to PostScript compiler errors.
-% Some issues can be overcome by converting the the (E)PS file to a (more) standard compatible version using tools like |eps2eps| or Ghostscript.
-%
-% \subsubsection*{Errors ``Float(s) lost'' or ``not in outer par mode''}
-% Floating environments like \env{figure} or \env{table} can not be used while \Key{float}'=true' and either \Key{crop}'=true' or \Key{preview}'=true' is set.
-% The last two options will try to store the float into a box which is not allowed (because it can't the float any longer).
-% Usually \Key{float}'=false' will solve this error, because it turns these environments into non-floating alternatives.
-% Because both the \Key{crop} and \Key{preview} option will set \Key{float}'=false' themselves, this issue can only arise when the \Key{float} option is manually set afterwards.
-%
-% \subsubsection*{Image conversion does not work}
-% In order for the image conversion to work an external conversion software must be installed. By default either Image Magkick or GhostScript is used. Please insure that either or both of these softwares are installed.
-% Installation guide for your operating system should be easily available on the Internet. The \LaTeX\ compiler option |-shell-escape| must be used to allow this external software to be executed from within the \LaTeX\ code.
-% If this two points are fulfilled but the conversion does still not work, please check the log file. The lines in question start with `|runsystem|' (at least with \TeX\ Live 2011).
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -1325,6 +1374,7 @@
\newif\ifsa@convert
\newif\ifsa@float
\newif\ifsa@math
+\newif\ifsa@convert@perpage
% \end{macrocode}
%
% The \cs{ifstandalonebeamer} switch is in the user-level.
@@ -1708,6 +1758,17 @@
% \end{macrocode}
% \end{key}
%
+% \begin{key}{standalone.cls/convert}{realmainfile}
+% \begin{macrocode}
+\sa@convertoption{realmainfile}[]{%
+ \RequirePackage{currfile-abspath}%
+ \getmainfile
+ \let\sa@convert@mainfile\themainfile
+}
+% \end{macrocode}
+% \end{key}
+%
+%
% \begin{key}{standalone.cls/convert}{png}
% \begin{macrocode}
\sa@convertoption{png}[]{%
@@ -1724,16 +1785,6 @@
% \end{macrocode}
% \end{key}
%
-% \begin{key}{standalone.cls/convert}{realmainfile}
-% \begin{macrocode}
-\sa@convertoption{realmainfile}[]{%
- \RequirePackage{currfile-abspath}%
- \getmainfile
- \let\sa@convert@mainfile\themainfile
-}
-% \end{macrocode}
-% \end{key}
-%
%
% \begin{key}{standalone.cls/convert}{jpg}
% \begin{macrocode}
@@ -1755,7 +1806,7 @@
% \begin{key}{standalone.cls/convert}{gif}
% \begin{macrocode}
\sa@convertoption{gif}[]{%
- \setkeys{standalone.cls/convert}{true,outext={.gif}}%
+ \setkeys{standalone.cls/convert}{true,imagemagick,outext={.gif}}%
}
% \end{macrocode}
% \end{key}
@@ -1769,6 +1820,40 @@
% \end{key}
%
%
+% \begin{key}{standalone.cls/convert}{svg}
+% \begin{macrocode}
+\sa@convertoption{svg}[]{%
+ \setkeys{standalone.cls/convert}{true,inkscape,outext={.svg}}%
+}
+% \end{macrocode}
+% \end{key}
+%
+% \begin{key}{standalone.cls}{svg}
+% \begin{macrocode}
+\sa@clsoption{svg}[]{%
+ \setkeys{standalone.cls/convert}{svg,#1}%
+}
+% \end{macrocode}
+% \end{key}
+%
+%
+% \begin{key}{standalone.cls/convert}{emf}
+% \begin{macrocode}
+\sa@convertoption{emf}[]{%
+ \setkeys{standalone.cls/convert}{true,inkscape,outext={.emf}}%
+}
+% \end{macrocode}
+% \end{key}
+%
+% \begin{key}{standalone.cls}{emf}
+% \begin{macrocode}
+\sa@clsoption{emf}[]{%
+ \setkeys{standalone.cls/convert}{emf,#1}%
+}
+% \end{macrocode}
+% \end{key}
+%
+%
% \begin{key}{standalone.cls/convert}{onfailure}
% \begin{macrocode}
\sa@convertoption{onfailure}{%
@@ -1806,6 +1891,14 @@
% \end{macrocode}
% \end{key}
%
+% \begin{key}{standalone.cls/convert}{perpage}
+% Boolean key to indicate to run the convert command once per page.
+% \begin{macrocode}
+\sa@convertoption{perpage}[true]{%
+ \sa@boolean{convert@perpage}{#1}%
+}
+% \end{macrocode}
+% \end{key}
%
% \begin{key}{standalone.cls/convert}{gsdevice}
% \begin{macrocode}
@@ -1840,8 +1933,13 @@
% \begin{key}{standalone.cls/convert}{imagemagick}
% \begin{macrocode}
\sa@convertoption{imagemagick}[]{%
- \def\sa@convert@command{\convertexe\space -density \density\space -units PixelsPerInch \infile\space \ifx\size\empty\else -resize \size\fi\space -quality 90 \outfile}%
- \let\sa@convert@pageoffset\m@ne
+ \def\sa@convert@command{\convertexe\space
+ -density \density\space
+ -units PixelsPerInch
+ \infile\ifsa@convert@perpage[\prevpagenum]\fi\space
+ -scene 1
+ \ifx\size\empty\else -resize \size\fi\space
+ -quality 90 \outfile}%
}
% \end{macrocode}
% \end{key}
@@ -1849,26 +1947,66 @@
% \begin{key}{standalone.cls/convert}{ghostscript}
% \begin{macrocode}
\sa@convertoption{ghostscript}[]{%
- \def\sa@convert@command{\gsexe\space -dSAFER -dBATCH -dNOPAUSE -sDEVICE=\gsdevice\space -r\density\space -sOutputFile=\outfile\space \infile}%
- \let\sa@convert@pageoffset\z@
+ \def\sa@convert@command{\gsexe\space -dSAFER -dBATCH -dNOPAUSE
+ \ifsa@convert@perpage-sPageList=\pagenum\fi\space
+ -sDEVICE=\gsdevice\space
+ -r\density\space
+ -sOutputFile=\outfile\space \infile
+ }%
+}
+% \end{macrocode}
+% \end{key}
+%
+% \begin{key}{standalone.cls/convert}{ghostscript32}
+% \begin{macrocode}
+\sa@convertoption{ghostscript32}[]{%
+ \setkeys{standalone.cls/convert}{ghostscript,gsexe=\@nameuse{sa@convert@gsexe32}}%
+}
+% \end{macrocode}
+% \end{key}
+%
+% \begin{key}{standalone.cls/convert}{ghostscript64}
+% \begin{macrocode}
+\sa@convertoption{ghostscript64}[]{%
+ \setkeys{standalone.cls/convert}{ghostscript,gsexe=\@nameuse{sa@convert@gsexe64}}%
}
% \end{macrocode}
% \end{key}
%
+% \begin{key}{standalone.cls/convert}{inkscape}
% \begin{macrocode}
-\sa@convertvar{latexoptions}{ -shell-escape }
+\sa@convertoption{inkscape}[]{%
+ \def\sa@convert@command{\inkscapeexe\space
+ --pdf-poppler \sa@inkscape@bgcolor\space
+ --export-type="\expandafter\@gobble\outext"
+ --pdf-page=\pagenum\space
+ -o \outfile\space \infile}
+ \sa@convert@perpagetrue
+ \def\sa@multi@pagemark{\pagenum}%
+}
+\def\sa@inkscape@bgcolor{\ifx\sa@convert@bgcolor\@empty\else--actions="export-background:\sa@convert@bgcolor"\fi}
+% \end{macrocode}
+% \end{key}
+%
+% \begin{macrocode}
+\sa@convertvar{latexoptions}{ -shell-escape \ifx\outputdir\empty\else-output-directory \sa@convert@quote\outputdir\sa@convert@quote\fi\space}
\sa@convertvar{subjobname}{\jobname}
\sa@convertvar{mainfile}{\jobname}
\sa@convertvar{quote}{}
\let\sa@convert@quote\relax
\sa@convertvar{size}{}
\sa@convertvar{inname}{\subjobname}
-\sa@convertvar{infile}{\inname\inext}
+\sa@convertvar{infile}{\indir\inname\inext}
+\sa@convertvar{outputdir}{}
+\sa@convertvar{indir}{\outputdir}
+\sa@convertvar{outdir}{\outputdir}
\sa@convertvar{outext}{.png}
\sa@convertvar{outname}{\inname}
-\sa@convertvar{outfile}{\outname\ifsa@multi\sa@multi@pagemark\fi\outext}
-\def\sa@multi@pagemark{-\percent0d}%
+\sa@convertvar{outfile}{\outdir\outname\ifsa@multi\sa@multi@pagemark\fi\outext}
+\def\sa@multi@pagemark{-\percent0d}
+\def\sa@convert@pagenum{1}
\sa@convertvar{density}{300}
+\sa@convertvar{bgcolor}{}
\sa@convertvar{gsdevice}{%
\expandafter\ifx\csname sa@gsdevice@\outext\endcsname\relax
\expandafter\@gobble\outext
@@ -1880,19 +2018,19 @@
\sa@convertvar{latex}{lualatex}
\sa@convertvar{inext}{.pdf}
\sa@convertvar{precommand}{}
- \setkeys{standalone.cls/convert}{imagemagick}
+ \setkeys{standalone.cls/convert}{ghostscript}
\else
\ifpdf
\sa@convertvar{latex}{pdflatex}
\sa@convertvar{inext}{.pdf}
\sa@convertvar{precommand}{}
- \setkeys{standalone.cls/convert}{imagemagick}
+ \setkeys{standalone.cls/convert}{ghostscript}
\else
\ifxetex
\sa@convertvar{latex}{xelatex}
\sa@convertvar{inext}{.pdf}
\sa@convertvar{precommand}{}
- \setkeys{standalone.cls/convert}{imagemagick}
+ \setkeys{standalone.cls/convert}{ghostscript}
\else
\sa@convertvar{latex}{latex}
\sa@convertvar{inext}{.ps}
@@ -1901,8 +2039,7 @@
\fi\fi\fi
% \end{macrocode}
%
-% Test for windows to avoid using the 'convert' executable there.
-% It is also the FAT-to-NTFS conversion tool!
+% Test for windows to set executable correctly.
% \begin{macrocode}
\begingroup
\ifluatex
@@ -1918,16 +2055,20 @@
\fi
\if@tempswa
\endgroup
- \sa@convertvar{convertexe}{imgconvert}
- \sa@convertvar{gsexe}{gswin32c}
+ \@namedef{sa@convert@gsexe32}{gswin32c}
+ \@namedef{sa@convert@gsexe64}{gswin64c}
\else
\endgroup
- \sa@convertvar{convertexe}{convert}
- \sa@convertvar{gsexe}{gs}
+ \@namedef{sa@convert@gsexe32}{gs}
+ \@namedef{sa@convert@gsexe64}{gs}
\fi
+\sa@convertvar{gsexe}{\@nameuse{sa@convert@gsexe64}}
+\sa@convertvar{convertexe}{magick convert}
+\sa@convertvar{inkscapeexe}{inkscape}
% \end{macrocode}
%
%
+%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \subsubsection{General macros}
%
@@ -2438,6 +2579,7 @@
\fi
\global\paperwidth=\wd\sa@box
\global\paperheight=\ht\sa@box
+ \special{papersize=\the\paperwidth,\the\paperheight}
\global\hsize=\wd\sa@box
\global\vsize=\ht\sa@box
\global\@colht=\ht\sa@box
@@ -2449,6 +2591,7 @@
\def\sa@placebox{%
\global\paperwidth=\wd\sa@box
\global\paperheight=\ht\sa@box
+ \special{papersize=\the\paperwidth,\the\paperheight}
\global\@colht=\maxdimen
\global\@colroom=\maxdimen
\global\hsize=\maxdimen
@@ -2598,6 +2741,13 @@
\ifsa@convert
% \end{macrocode}
%
+% Disable \Macro\sa@convert@perpage if 'multi' option is not set.
+% \begin{macrocode}
+\ifsa@multi\else
+\sa@convert@perpagefalse
+\fi
+% \end{macrocode}
+%
% \begin{macrocode}
\def\sa@convert@stop{\csname fi\endcsname\stop}%
\begingroup
@@ -2660,7 +2810,9 @@
\endgroup
%
\@tempcnta\sa@multi@numpages\relax
- \advance\@tempcnta\sa@convert@pageoffset\relax
+ \ifsa@convert@perpage
+ \def\sa@multi@pagemark{-\pagenum}%
+ \else
\ifnum\@tempcnta=\z@
\def\sa@multi@pagemark{}%
\edef\sa@lastoutfile{\outfile}%
@@ -2676,6 +2828,7 @@
\repeat
\edef\sa@multi@pagemark{-\percent0\the\@tempcntb d}%
\fi
+ \fi
%
\if@tempswa
\edef\infile@filemodafter{\csname pdf\ifluatex @\fi filemoddate\endcsname{\infile}}%
@@ -2690,20 +2843,40 @@
\message{Executing precommand:^^J\sa@convert@precommand^^J^^J}%
\ShellEscape{\sa@convert@precommand}%
\fi
+ \ifsa@convert@perpage
+ \begingroup
+ \@tempcnta\sa@multi@numpages\relax
+ \@tempcntb\z@
+ \def\pagenum{\the\@tempcntb}%
+ \loop\ifnum\@tempcntb<\@tempcnta
+ \edef\prevpagenum{\pagenum}%
+ \advance\@tempcntb\@ne
+ \sa@execute@convert@command
+ \sa@checkoutfile{\outfile}{#1}%
+ \repeat
+ \endgroup
+ \else
+ \sa@execute@convert@command
+ \sa@checkoutfile{\sa@lastoutfile}{#1}%
+ \fi
+ \@tempswafalse
+}
+\def\sa@execute@convert@command{%
\message{Executing command:^^J\sa@convert@command^^J^^J}%
\ShellEscape{\sa@convert@command}%
- \@tempswafalse
- \IfFileExists{\sa@lastoutfile}{%
- \edef\filemodafter{\csname pdf\ifluatex @\fi filemoddate\endcsname{\sa@lastoutfile}}%
+}
+\def\sa@checkoutfile#1#2{%
+ \IfFileExists{#1}{%
+ \edef\filemodafter{\csname pdf\ifluatex @\fi filemoddate\endcsname{#1}}%
\ifx\filemodbefore\filemodafter
\expandafter\ifx\csname pdf\ifluatex @\fi filemoddate\endcsname\relax\else
- \sa@convert@failuremsg{standalone}{#1}{}%
+ \sa@convert@failuremsg{standalone}{#2}{}%
\fi
\else
- \typeout{Class standalone:^^JOutput written on \sa@lastoutfile.}%
+ \typeout{Class standalone:^^JOutput written on #1.}%
\fi
}{%
- \sa@convert@failuremsg{standalone}{#1}{}%
+ \sa@convert@failuremsg{standalone}{#2}{}%
}%
}
% \end{macrocode}
@@ -2716,14 +2889,20 @@
\let\infile\sa@convert@infile
\let\inext\sa@convert@inext
\let\inname\sa@convert@inname
+\let\indir\sa@convert@indir
+\let\outdir\sa@convert@outdir
+\let\outputdir\sa@convert@outputdir
\let\gsdevice\sa@convert@gsdevice
\let\convertexe\sa@convert@convertexe
\let\gsexe\sa@convert@gsexe
+\let\inkscapeexe\sa@convert@inkscapeexe
+\let\gsexe\sa@convert@gsexe
\let\density\sa@convert@density
\let\size\sa@convert@size
\let\outext\sa@convert@outext
\let\outname\sa@convert@outname
\let\outfile\sa@convert@outfile
+\let\pagenum\sa@convert@pagenum
\let\percent\@percentchar
\let\quote\sa@convert@quote
% \end{macrocode}