diff options
Diffstat (limited to 'support/texblend/intro.tex')
-rw-r--r-- | support/texblend/intro.tex | 153 |
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. + |