\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 <br><br> 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[english,shorthands=off]{babel}
\babelfont{rm}[Path=/usr/share/texmf/fonts/opentype/public/tex-gyre/,%
 BoldFont=texgyrepagella-bold.otf,%
 BoldItalicFont=texgyrepagella-bolditalic.otf,%
 ItalicFont=texgyrepagella-italic.otf]{texgyrepagella-regular.otf}
\babelfont{tt}[Scale=MatchLowercase,%
 Path=/usr/share/fonts/truetype/cmu/,%
 BoldFont=cmuntb.ttf,%
 BoldItalicFont=cmuntx.ttf,%
 ItalicFont=cmunit.ttf]{cmuntt.ttf}
\babelfont{sf}[Scale=MatchLowercase,%
 Path=/usr/share/fonts/truetype/cmu/,%
 BoldFont=cmunsx.ttf,%
 BoldItalicFont=cmunso.ttf,%
 ItalicFont=cmunsi.ttf]{cmunss.ttf}



\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}
\setlength{\parindent}{15pt}

\title{Templates and custom formats}
\date{}
\author{}
\subtitle{}






% https://groups.google.com/d/topic/comp.text.tex/6fYmcVMbSbQ/discussion
\hypersetup{%
pdfencoding=auto,
pdftitle={Templates and custom formats},%
pdfauthor={},%
pdfsubject={},%
pdfkeywords={doc; howto}%
}


\begin{document}









  \begin{titlepage}


  \strut\vskip 2em
  \begin{center}

  {\usekomafont{title}{\huge Templates and custom formats\par}}%
  \vskip 1em
  
  \vskip 2em
  
  \vskip 1.5em



   
   \vfill



  
    \strut\par
  


  \end{center}


     \end{titlepage}
     
     \cleardoublepage





\tableofcontents
% start a new right-handed page

\cleardoublepage




Even if Amusewiki can be used as a blog or wiki engine, its prominent
feature is the production of camera-ready PDFs. There are various ways
you can affect the output. This article explains what to do if you
need more control on the output. Before you continue, please be sure
to have an up-to-date Amusewiki instance (2.411 at the time of
writing)


Let's first clarify the concepts:


\begin{description}

\item[{template}] 
this refers to an optional file with extension \texttt{.tt}.
Normally this file exists only in memory but you can use
it if you set the path in the admin (super-user only).


\item[{custom format}] 
this is the definition to produce a PDF\Slash{}EPUB output
file. You can have as many custom formats as you
want with a recent Amusewiki (in the past there were
only 3 of them, plain, A4 imposed and Letter imposed).


\end{description}
\chapter{Custom formats}


Normally you may want to use the Amusewiki facilities to format your
texts. A stock installation offers a couple of them but you can
add\Slash{}disable them at will. Please note that they have the same options
as the \href{bookbuilder-tutorial}{BookBuilder}, the only difference is
that the custom formats are site-wide, while the bookbuilder is on
request.


The list of custom formats is accessible in the main site
configuration panel, \texttt{/user/site}, and they can be managed at
\texttt{/settings/formats}.


\begin{figure}[htbp!]
\centering
\includegraphics[keepaspectratio=true,height=\textheight,width=\textwidth]{t-a-listing-1.png}
\end{figure}


By default, Amusewiki tries to build every active format for each text
in the archive.


On this page you can turn make them inactive and modify them. Please
note the "Code" field (\texttt{c1}, \texttt{c2}, etc), because we'll need that.


You can have as many custom formats you want. They will then appear in
the text infobox once they are ready (the building happens in the
background).


\begin{figure}[htbp!]
\centering
\includegraphics[keepaspectratio=true,height=\textheight,width=\textwidth]{t-a-listing-2.png}
\end{figure}


However, you may want to use only some of them in a text. To do so,
add to the muse header in the text:


\begin{alltt}
\#formats c1 c2
\end{alltt}


Where \texttt{c1} and \texttt{c2} are the wanted formats, by code, as shown at
\texttt{/settings/formats}. (Usually the code also appears in the file
suffix).


The site formats can also also be used as predefined settings in the
bookbuilder (right-hand top menu).


\begin{figure}[htbp!]
\centering
\includegraphics[keepaspectratio=true,height=\textheight,width=\textwidth]{t-a-listing-3.png}
\end{figure}


To suppress their generations for a given text, you can add to the
header:


\begin{alltt}
\#formats none
\end{alltt}


(as \texttt{none} is just a non-existing format). This will also hide the
standard formats.

\section{Leveraging the custom formats to correct the final PDFs}


Muse is an abstract markup. It tries to hide the complexities of
typesetting. Sooner or later, if you are going to print something, you
are going to need more control on the output. For that we are still
going to use the custom formats code (as a typesetting correction
would apply only on given format, not to all).


For that we have the magic comments.\footnote{This is an Amusewiki extension, it was not present in the original Emacs Muse implementation. List updated to \texttt{Text::Amuse::Compile} version 1.52, released on January 14, 2021} It allows the injection of a
limited set of LaTeX commands at an arbitrary position in the text.


The formal definition is:


\begin{itemize}
\item\relax 
start a line with a semicolon (normal Muse comment)



\item\relax 
colon - format code - colon (without spaces)



\item\relax 
LaTeX command




\end{itemize}

This is an example:


\begin{alltt}
My text starts...

; :c9: \textbackslash{}sloppy
; :c9: \textbackslash{}vskip 10mm
; :DEFAULT: \textbackslash{}fussy
; :c111: \textbackslash{}sloppy
; :ALL: \textbackslash{}newpage
; :*: \textbackslash{}newpage

My text continues...
\end{alltt}


The \texttt{DEFAULT} code is used when no custom format is used.


The \texttt{ALL} code (and its alias, an asterisk), \emph{always} trigger the
command, regardless of the custom format passed.\footnote{The \texttt{ALL} trigger was introduced with Text::Amuse::Compile 1.61, released on 2021-04-11.}


As you can see, commands for different formats can coexist without
problems.


The list of permitted commands is:


\begin{itemize}
\item\relax 
\texttt{\textbackslash{}thispagestyle\{STYLE\}}



\item\relax 
\texttt{\textbackslash{}pagestyle\{STYLE\}}



\item\relax 
\texttt{\textbackslash{}vskip DIMENSION}



\item\relax 
\texttt{\textbackslash{}strut}



\item\relax 
\texttt{\textbackslash{}newpage}



\item\relax 
\texttt{\textbackslash{}enlargethispage\{DIMENSION\}}



\item\relax 
\texttt{\textbackslash{}flushbottom}



\item\relax 
\texttt{\textbackslash{}raggedbottom}



\item\relax 
\texttt{\textbackslash{}markrigth\{TEXT\}}



\item\relax 
\texttt{\textbackslash{}markboth\{TEXT\}\{TEXT\}}



\item\relax 
\texttt{\textbackslash{}sloppy}



\item\relax 
\texttt{\textbackslash{}fussy}



\item\relax 
\texttt{\textbackslash{}vfill}



\item\relax 
\texttt{\textbackslash{}clearpage}



\item\relax 
\texttt{\textbackslash{}cleardoublepage}



\item\relax 
\texttt{\textbackslash{}looseness=INTEGER}




\end{itemize}

Possible arguments:


\begin{description}

\item[{\texttt{STYLE}}] 
One of \texttt{plain}, \texttt{empty}, \texttt{headings}, \texttt{myheadings}, \texttt{scrheadings}.


\item[{\texttt{TEXT}}] 
Plain text, without any of the reserved LaTeX characters.


\item[{\texttt{DIMENSION}}] 
regular TeX size in \texttt{mm}, \texttt{cm}, \texttt{pt}, \texttt{em}, e.g. \texttt{3mm}.


\item[{\texttt{INTEGER}}] 
An integer positive or negative


\end{description}

This assumes that you are comfortable with LaTeX and you know what
these commands do, but they should be enough to give you full control
on the page and to do some corrections. If you think that something
else should be added, please open a bug report against
\href{https://github.com/melmothx/text-amuse-compile}{\texttt{https://github.com/melmothx/text-amuse-compile}}


For maximum flexibility, you can define commands starting with
\texttt{\textbackslash{}amusewiki} in your template (without any argument) and use them in
the magic comments. This allows you to inject arbitrary (but still)
TeX commands in the body in a relatively safe fashion.

\chapter{Templates}



\begin{quote}


\emph{Beware, here you're entering an advanced topic, and assumes you're
comfortable both with LaTeX and with a template markup.}



\end{quote}


You should use the templates when you want to control the LaTeX
delegating to amusewiki only the text body.


In the archive root (e.g. \texttt{/var/lib/amusewiki/repo/MYSITE-ID/}) you
would do


\begin{alltt}
\$ muse-compile.pl --ttdir templates --output-templates
Using Text::Amuse 1.29, Text::Amuse::Compiler 1.33, PDF::Imposition 0.25
Creating ./templates/html.tt
Creating ./templates/minimal\_html.tt
Creating ./templates/bare\_html.tt
Creating ./templates/css.tt
Creating ./templates/latex.tt
Creating ./templates/bare\_latex.tt
\end{alltt}


This will populate the \texttt{templates} directory with the default
templates. Remove the ones you don't need and start editing the one
you need (usually \texttt{latex.tt})


Set this directory in super-user admin console:
\href{/admin/sites/edit/MYSITE-ID}{\texttt{/admin/sites/edit/MYSITE-ID}}


\begin{figure}[htbp!]
\centering
\includegraphics[keepaspectratio=true,height=\textheight,width=\textwidth]{t-a-listing-4.png}
\end{figure}


This is a subset of the Perl Template::Toolkit templating system, to
be exact \href{https://metacpan.org/pod/Template::Tiny}{Template::Tiny},
so don't expect to do crazy stuff there.


However, you can use conditionals like:


\begin{alltt}
    [\% IF safe\_options.format\_id.c122 \%]
    Here I'm in format c122
    [\% ELSE \%]
    [\% IF safe\_options.format\_id.c123 \%]
    Here I'm in format c123
    [\% ELSE \%]
    My Text
    [\% END \%]
\end{alltt}


I.e., you can test of the existence of \texttt{safe\_options.format\_id.CODE}
and branch the template to do different things depending on the
format.


Now, if you have a lot of formats, such approach can go out of hand
very easily.


Alternatively, you can use a template for a single format only, naming
it: code - hyphen - template name. E.g. \texttt{c11-latex.tt} (under the same
directory) which will be used only with the \texttt{c11} format, avoiding the
use of conditionals in the master template. I'd suggest this approach,
hardcoding all the LaTeX settings but binding to a single format,
instead of hacking the master template (which naturally will be used
in the BookBuilder and if you are not careful the results could be
very unexpected).









% 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}




Templates and custom formats






\bigskip



   

       

       

       

       

       

       

   



\bigskip
\textbf{amusewiki.org}


\end{center}

% end final page with colophon


% end closing pages



\end{document}


% No format ID passed.



