\documentclass[DIV=13,%
BCOR=0mm,%
headinclude=false,%
footinclude=false,open=any,%
fontsize=10pt,%
oneside,%
paper=a5]%
{scrbook}
\usepackage[noautomatic]{imakeidx}
\usepackage{microtype}
\usepackage{graphicx}
\usepackage{alltt}
\usepackage{verbatim}
\usepackage[shortlabels]{enumitem}
\usepackage{tabularx}
\usepackage[normalem]{ulem}
\def\hsout{\bgroup \ULdepth=-.55ex \ULset}
% https://tex.stackexchange.com/questions/22410/strikethrough-in-section-title
% Unclear if \protect \hsout is needed. Doesn't looks so
\DeclareRobustCommand{\sout}[1]{\texorpdfstring{\hsout{#1}}{#1}}
\usepackage{wrapfig}
% avoid breakage on multiple
and avoid the next [] to be eaten
\newcommand*{\forcelinebreak}{\strut\\*{}}
\newcommand*{\hairline}{%
\bigskip%
\noindent \hrulefill%
\bigskip%
}
% reverse indentation for biblio and play
\newenvironment*{amusebiblio}{
\leftskip=\parindent
\parindent=-\parindent
\smallskip
\indent
}{\smallskip}
\newenvironment*{amuseplay}{
\leftskip=\parindent
\parindent=-\parindent
\smallskip
\indent
}{\smallskip}
\newcommand*{\Slash}{\slash\hspace{0pt}}
% http://tex.stackexchange.com/questions/3033/forcing-linebreaks-in-url
\PassOptionsToPackage{hyphens}{url}\usepackage[hyperfootnotes=false,hidelinks,breaklinks=true]{hyperref}
\usepackage{bookmark}
\usepackage{fontspec}
\usepackage{polyglossia}
\setmainlanguage{english}
\setmainfont{texgyrepagella-regular.otf}[Script=Latin,%
Ligatures=TeX,%
Path=/usr/share/texmf/fonts/opentype/public/tex-gyre/,%
BoldFont=texgyrepagella-bold.otf,%
BoldItalicFont=texgyrepagella-bolditalic.otf,%
ItalicFont=texgyrepagella-italic.otf]
\setmonofont{cmuntt.ttf}[Script=Latin,%
Ligatures=TeX,%
Scale=MatchLowercase,%
Path=/usr/share/fonts/truetype/cmu/,%
BoldFont=cmuntb.ttf,%
BoldItalicFont=cmuntx.ttf,%
ItalicFont=cmunit.ttf]
\setsansfont{cmunss.ttf}[Script=Latin,%
Ligatures=TeX,%
Scale=MatchLowercase,%
Path=/usr/share/fonts/truetype/cmu/,%
BoldFont=cmunsx.ttf,%
BoldItalicFont=cmunso.ttf,%
ItalicFont=cmunsi.ttf]
\newfontfamily\englishfont{texgyrepagella-regular.otf}[Script=Latin,%
Ligatures=TeX,%
Path=/usr/share/texmf/fonts/opentype/public/tex-gyre/,%
BoldFont=texgyrepagella-bold.otf,%
BoldItalicFont=texgyrepagella-bolditalic.otf,%
ItalicFont=texgyrepagella-italic.otf]
\renewcommand*{\partpagestyle}{empty}
% global style
\pagestyle{plain}
\usepackage{indentfirst}
% remove the numbering
\setcounter{secnumdepth}{-2}
% remove labels from the captions
\renewcommand*{\captionformat}{}
\renewcommand*{\figureformat}{}
\renewcommand*{\tableformat}{}
\KOMAoption{captions}{belowfigure,nooneline}
\addtokomafont{caption}{\centering}
\deffootnote[3em]{0em}{4em}{\textsuperscript{\thefootnotemark}~}
\addtokomafont{disposition}{\rmfamily}
\addtokomafont{descriptionlabel}{\rmfamily}
\frenchspacing
% avoid vertical glue
\raggedbottom
% this will generate overfull boxes, so we need to set a tolerance
% \pretolerance=1000
% pretolerance is what is accepted for a paragraph without
% hyphenation, so it makes sense to be strict here and let the user
% accept tweak the tolerance instead.
\tolerance=200
% Additional tolerance for bad paragraphs only
\setlength{\emergencystretch}{30pt}
% (try to) forbid widows/orphans
\clubpenalty=10000
\widowpenalty=10000
% given that we said footinclude=false, this should be safe
\setlength{\footskip}{2\baselineskip}
\title{File inclusion in documents}
\date{}
\author{}
\subtitle{}
% https://groups.google.com/d/topic/comp.text.tex/6fYmcVMbSbQ/discussion
\hypersetup{%
pdfencoding=auto,
pdftitle={File inclusion in documents},%
pdfauthor={},%
pdfsubject={},%
pdfkeywords={howto}%
}
\begin{document}
\begin{titlepage}
\strut\vskip 2em
\begin{center}
{\usekomafont{title}{\huge File inclusion in documents\par}}%
\vskip 1em
\vskip 2em
\vskip 1.5em
\vfill
\strut\par
\end{center}
\end{titlepage}
\cleardoublepage
\tableofcontents
% start a new right-handed page
\cleardoublepage
Starting with version 2.500, Amusewiki can be setup to include other
files.
\section{Syntax}
The syntax is (with no leading space):
\begin{alltt}
\#include path/to/file
\end{alltt}
The directive can be placed anywhere in the muse body (\emph{not} in the
header, where it would be just a custom header line).
The file content is included as is \emph{before} any parsing, and will be
transparently parsed after being included.
To include a muse document you would just do:
\begin{alltt}
Here starts the body....
\#include path/to/muse-document
Here it continues....
\end{alltt}
And to include, e.g., a configuration file:
\begin{alltt}
\{\{\{
\#include examples/file.conf
\}\}\}
\end{alltt}
The markup surrounding the inclusion will include it as a verbatim
snippet.
Please note that including files with a \texttt{.muse} extension will likely
trigger a harmless warning, suggesting to place it in another path.
For this reason the suggestion is to avoid the use of the \texttt{.muse}
extension for inclusion, while reserving it for full documents.
Anything else (like \texttt{.txt} or \texttt{.muse.inc}) or no extension at all will
do.
\section{Path}
Included paths are \emph{searched} in the directories (possibly multiple)
set site-wide, just like a binary is searched in the \texttt{PATH} variable,
and the first match is used.
If the site sets, e.g. \texttt{/etc} as a include path (which for sure is \emph{not}
a good idea), this would include \texttt{/etc/passwd} and \texttt{/etc/apt/sources.list}
\begin{alltt}
\{\{\{
\#include passwd
\}\}\}
\{\{\{
\#include apt/sources.list
\}\}\}
\end{alltt}
\section{Enabling}
This feature needs to be explicitly enabled on the CLI with the
provided command \texttt{amusewiki-include-path}. On Debian this can be
called with \texttt{amusewiki include-path}, while when installed from Git it
can be called, e.g., as:
\begin{alltt}
carton exec "script/amusewiki-include-path --help"
\end{alltt}
The typical usage would be:
\begin{alltt}
amusewiki-include-path --site testsite --repo
\end{alltt}
Which will add the site repository itself to the include paths, so you
could have a \texttt{include} directory where you can keep the shared files.
On a git pull, included files are checked for freshness and a rebuild
is triggered if needed.
% begin final page
\clearpage
% new page for the colophon
\thispagestyle{empty}
\begin{center}
\bigskip
\includegraphics[width=0.25\textwidth]{logo-amw.pdf}
\bigskip
\end{center}
\strut
\vfill
\begin{center}
File inclusion in documents
\bigskip
\bigskip
\textbf{amusewiki.org}
\end{center}
% end final page with colophon
\end{document}
% No format ID passed.