summaryrefslogtreecommitdiff
path: root/support/texblend/intro.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/texblend/intro.tex')
-rw-r--r--support/texblend/intro.tex153
1 files changed, 153 insertions, 0 deletions
diff --git a/support/texblend/intro.tex b/support/texblend/intro.tex
new file mode 100644
index 0000000000..5f41e8dc66
--- /dev/null
+++ b/support/texblend/intro.tex
@@ -0,0 +1,153 @@
+% !TEX root = texblend-doc.tex
+% !TEX TS-program = lualatex
+
+\section{Introduction}
+This tool compiles individual files that are included as parts of larger documents.
+It utilizes the preamble of the main document but disregards all other included files.
+
+The main purpose is to allow fast compilation of particular chapters or sections,
+eliminating the need to recompile the entire document.
+This facilitates an efficient way to check for formatting or syntax errors in
+the particular part of the document being worked on.
+
+\section{Structure of \TeX\ Files}
+
+The basic usage is as follows: consider a main document that includes files for
+individual chapters, named for example \texttt{main.tex}:
+
+
+\begin{verbatim}
+\documentclass{article}
+\author{John Doe}
+\title{Sample Document}
+\usepackage{upquote}
+\usepackage{microtype}
+\usepackage{hyperref}
+\begin{document}
+\maketitle
+\tableofcontents
+\input{intro}
+\input{usage}
+\end{document}
+\end{verbatim}
+
+We can compile this document to obtain a PDF file containing the text of all
+chapters. However, by using \TeX Blend, we can generate separate PDFs for each
+chapter. The advantage is that all commands defined in the packages used in the
+main document will be available.
+
+In the included files, we can use special directives that indicate the main
+file and the engine to be used for compilation. Similar directives are employed
+by various \TeX\ editors, such as \TeX Shop or \TeX Works.
+
+For instance, a file like \texttt{intro.tex}, which is included in the main document,
+might look like this:
+
+\begin{verbatim}
+% !TEX root = main.tex
+% !TEX TS-program = lualatex
+
+\section{Introduction}
+This tool compiles individual files that are included
+as parts of larger documents.
+\end{verbatim}
+
+Notice the comments at the beginning of the file. These are
+directives, indicating the main document and the engine to be used for
+compilation. Many \TeX\ editors support these directives, and we utilize them in
+\TeX Blend to effectively control the compilation process too.
+
+These directives follow a specific format, requiring placement at the beginning
+of the file and commencing with a percentage sign. Subsequently, there is a
+space followed by either the marker \texttt{!TEX} or \texttt{!TeX},
+both of which are recognized formats.
+The next element is the property name with an optional \texttt{TS-} prefix
+(in line with the TeX Shop editor), followed by an equals sign and, finally, the
+value.
+
+Two crucial properties are \texttt{root}, indicating the name of the main file, and
+\texttt{program}, through which we can select the program for compiling the document.
+However, it is possible to specify additional properties, which can then be
+utilized in template documents.
+
+\subsection{Placement of the Main Document and Templates}
+\label{sec:placement}
+
+You can specify the full path to the main document in the \verb|root| property.
+\TeX Blend can also be used to compile documents using a universal template.
+The path to this template can be specified in full or can leverage the directory
+structure of TeX by placing it in a directory recognized by the KPSE library.
+This directory is typically designated for user packages, commonly found at
+\verb|~/texmf/tex/latex|, although it may vary on different systems.
+You can identify its location on your system using the command:
+
+\begin{verbatim}
+$ kpsewhich --var-value TEXMFHOME
+\end{verbatim}
+
+This command typically outputs a path similar to this: \texttt{/home/username/texmf}.
+If this directory does not exist, create it. Further, within this directory,
+create the subdirectories \texttt{tex/latex/templates}:
+
+\begin{verbatim}
+$ mkdir -p ~/texmf/tex/latex/templates
+\end{verbatim}
+
+You can then place your templates in this directory.
+To test the availability of the template, run the following command:
+
+\begin{verbatim}
+$ kpsewhich templatename.tex
+\end{verbatim}
+
+It should print path of the template document.
+
+\subsection{Custom Variables in Templates}\label{sec:variables}
+
+As templates are intended to be universal across various projects, it is
+possible to incorporate variables into them. These variables can be populated
+from properties in the directives, such as the document title.
+
+To include variables for expansion in the template, you can use the notation
+\verb|{{variableName}}|. For example, to set the document title, you can use
+\texttt{\textbackslash title\{\{\{title\}\}\}}. The double curly braces around
+the variable will be replaced with its value, while the third pair of curly braces will remain in the
+document.
+
+Say that you have a following template saved in \url{~/texmf/tex/latex/templates/mytemplate.tex}:
+
+\begin{verbatim}
+\documentclass{article}
+\title{{{title}}}
+\author{Michal}
+\usepackage{microtype}
+\begin{document}
+\end{document}
+\end{verbatim}
+
+
+A document that utilizes this template may look like the following:
+
+\begin{verbatim}
+% !TEX root = mytemplate.tex
+% !TEX title = hello world
+\maketitle
+\end{verbatim}
+
+
+This produces a following document with variables expanded:
+
+\begin{verbatim}
+\documentclass{article}
+\title{hello world}
+\author{Michal}
+\usepackage{microtype}
+\begin{document}
+% !TEX root = mytemplate.tex
+% !TEX title = hello world
+\maketitle
+\end{document}
+\end{verbatim}
+
+You can require expansion of variables using the \verb|--expand| command line option.
+