refactoring documentation

template/preamble.tex

@@ -1,4 +1,4 @@
-%% Time-stamp: <2013-02-06 19:22:59 vk>
+%% Time-stamp: <2013-02-25 10:45:54 vk>
 %%%% === Disclaimer: =======================================================
 %% created by
 %%
@@ -90,6 +90,8 @@
 %doc% exciting experience with this template, you should definitely consider reading
 %doc% following sections which are also marked with the pencil symbol:\myinteresting
 %doc% \begin{itemize}
+%doc% \item Section~\ref{sec:extending-template}: extend the template with
+%doc%   your own usepackages, newcommands, and so forth
 %doc% \item Section~\ref{sec:mycommands}: pre-defined commands to make your life easier (e.g., including graphics)
 %doc% \item Section~\ref{sec:myacro}: how to do acronyms (like \myacro{ACME}) beautifully
 %doc% \item Section~\ref{sub:csquotes}: how to \enquote{quote} text and use parentheses correctly
@@ -100,9 +102,13 @@
 
 %doc% 
 %doc% \newpage
-%doc% \subsection{Modify this template for your requirements}\myimportant
+%doc% \subsection{Five Steps to Customize Your Document}\myimportant
 %doc% \label{sec:modifytemplate}
 %doc%
+%doc% This template is optimized to get to the first draft of your thesis
+%doc% very quickly. Follow these instructions and you get most of your
+%doc% customizing done in a few minutes:
+%doc% 
 %doc% \newcommand{\myfile}[1]{\texttt{\href{file:#1}{#1}}}
 %doc%
 %doc% \begin{enumerate}
@@ -147,7 +153,15 @@
 %doc% \subsection{How to compile this document}\myimportant
 %doc% \label{sec:howtocompile}
 %doc% 
-
+%doc% I assume that compiling \LaTeX{} documents within your software
+%doc% environment is something you have already learned. This template is
+%doc% almost like any other \LaTeX{} document except it uses
+%doc% state-of-the-art tools for generating things like the list of
+%doc% references using biblatex/biber (see
+%doc% Section~\ref{sec:references} for details). Unfortunately, some \LaTeX{} editors
+%doc% do not support this much better way of working with bibliography
+%doc% references yet. This section describes how to compile this template.
+%doc% 
 %doc% \subsubsection{Compiling Using a \LaTeX{} Editor}
 %doc% 
 %doc% Please do select \myfile{main.tex} as the \enquote{main project file} or make
@@ -244,7 +258,8 @@
 %doc% \verb#Template_Documentation.tex# (if it exists) in the main folder 
 %doc% of this template.
 %doc% 
-%doc% \subsection{What about modifying the template?}
+%doc% \subsection{What about modifying or extending the template?}\myinteresting
+%doc% \label{sec:extending-template}
 %doc% 
 %doc% This template provides an easy to start \LaTeX{} document template with sound
 %doc% default settings. You can modify each setting any time. It is recommended that