summaryrefslogtreecommitdiff
path: root/support/texblend/usage.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/texblend/usage.tex')
-rw-r--r--support/texblend/usage.tex107
1 files changed, 107 insertions, 0 deletions
diff --git a/support/texblend/usage.tex b/support/texblend/usage.tex
new file mode 100644
index 0000000000..2289ecad98
--- /dev/null
+++ b/support/texblend/usage.tex
@@ -0,0 +1,107 @@
+% !TEX root = texblend-doc.tex
+% !TEX TS-program = lualatex
+\section{Usage}
+
+The basic usage of \TeX Blend is as follows:
+
+\begin{verbatim}
+$ texblend chapter.tex
+\end{verbatim}
+
+This command combines the text from the document \texttt{chapter.tex} with the preamble
+from the main document specified in the root directive and directly compiles
+the resulting document. The output will be saved as \texttt{chapter.pdf}.
+
+\subsection{Command Line Options}
+
+TeXBlend supports a variety of command-line options:
+
+\begin{verbatim}
+ texblend [options] filename
+
+Available options:
+-e,--expand Expand variables in the template
+-h,--help Print the help message
+-H,--HTML Compile to HTML using TeX4ht
+-l,--lualatex Select lualatex as compiler
+-o,--output (default "") Set the output file name
+-O,--texoptions (default "") Extra options that should be passed
+ to the LaTeX compiler
+-p,--pdflatex Select pdflatex as compiler
+-P,--print Don't compile the document,
+ print the expanded template instead
+-s,--shell-escape Enable execution of external
+ commands in LaTeX
+-t,--template (default "") Use explicit template instead of
+ the one provided in the input file
+-v,--version Print version info
+-x,--xelatex Select xelatex as compiler
+<filename> (string) Use "-" if you want to pass
+ document from the standard input
+\end{verbatim}
+
+You can join multiple short options, for example the following call uses separate short options:
+
+\begin{verbatim}
+$ texblend -e -l -o test chapter.tex
+\end{verbatim}
+
+It can be shortened to this form:
+
+\begin{verbatim}
+$ texblend -elo test chapter.tex
+\end{verbatim}
+
+
+
+\subsection{Compilation Options}
+
+You can override the \verb'program' directive, which specifies the \LaTeX\ engine
+used, with one of the options \verb|--lualatex|, \verb|--xelatex|, or \verb|--pdflatex|.
+The default program used when the document lacks a \verb'program' directive and none of these
+options is used is \verb|pdflatex|.
+
+If the document uses external commands, such as with the Minted or Imakeidx
+packages, you can utilize the \verb|--shell-escape| option.
+
+You can specify additional options for the LaTeX compiler using the \verb|--texoptions| option.
+
+Instead of compiling, you can print the assembled document to standard output
+using the option \verb|--print|.
+
+To change name of the generated PDF file, use the \verb|--output| option.
+
+
+\subsection{Usage of Templates}
+
+
+Instead of the main document specified in the \verb'root' directive, you can use
+another document as a template, chosen using the \verb|--template| option. You
+can use the entire file path or simply specify the file name, making use of the
+\verb'kpsewhich' command (see section~\ref{sec:placement}) to locate the file.
+
+If you are using variables in the template (see section~\ref{sec:variables}), use the
+\verb'--expand' option to expand them with the values specified in the document's
+directives.
+
+
+
+
+\subsection{HTML Support}
+
+\TeX Blend supports direct export to HTML using \TeX4ht. A note regarding the
+\verb|--texoptions| command line option: you can utilize this option to pass all
+command-line arguments to \verb|make4ht|. Ensure to include the \verb|-| character in place
+of the filename for proper execution.
+
+For example, if you want to use the \verb|fn-in| option for endnotes, use the following command:
+
+\begin{verbatim}
+$ texblend -HO '- "fn-in"' chapter.tex
+\end{verbatim}
+
+If you want to use a configuration file in addition, you will need this command:
+
+\begin{verbatim}
+$ texblend -HO '-c config.cfg - "fn-in"' chapter.tex
+\end{verbatim}