path: root/macros/latex/contrib/gamebook/gamebook.dtx

% \iffalse meta-comment
%
% Copyright (C) 2011 by Andr\'e Miede, http://www.miede.de
% -------------------------------------------------------
% 
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in:
%
%    http://www.latex-project.org/lppl.txt
%
% and version 1.3 or later is part of all distributions of LaTeX 
% version 2005/12/01 or later.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{gamebook.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{gamebook}
%<*package>
    [2011/11/29 v1.0 Style for gamebooks/interactive novels]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage[debug]{gamebook}[2011/11/29]
\usepackage{hyperref}
\EnableCrossrefs         
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{gamebook.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{0}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{v1.0}{2011/06/12}{Initial version}
%
% \GetFileInfo{gamebook.dtx}
%
% \DoNotIndex{\newcommand,\newenvironment}
% 
%
% \title{The \textsf{gamebook} package\thanks{This document
%   corresponds to \textsf{gamebook}~\fileversion, dated \filedate.}}
% \author{Andr\'e Miede \\ \url{http://www.miede.de}}
%
% \maketitle
%
% \section*{Introduction}
%
% This package provides the means to layout gamebooks with \LaTeX. 
% If you do not know what a gamebook is, just have a look at the informative 
% Wikipedia article \url{http://en.wikipedia.org/wiki/Gamebook} or check 
% out Demian's very good overview website, where you can find tons of information 
% about gamebooks: \url{http://www.gamebooks.org}.
%
% A simple gamebook example is included with this package, teaching you how to 
% use the package in no time.
%
% If you created a gamebook using this package, please drop me an e-mail 
% (ideally, send an PDF of the gamebook along). Thanks in advance.
%
%
% \section*{Package Loading}
%
% You can load the |gamebook| package easily together with the typical 
% \LaTeX-classes: 
% \begin{center}
%  |\usepackage|\oarg{optional arguments}|{gamebook}|
% \end{center}
% With respect to the \emph{optional arguments}, you have the following ones 
% available:
%	\begin{itemize}
%		\item\texttt{debug}: Print the label ids of the referenced sections each
% 											 time you refer to a section.
%		\item\texttt{draft}: Print drafting information (time etc.) on each page.
%	\end{itemize}
%
% The available commands and environments are described in the following.
%
% \section*{Usage}
%	\DescribeMacro{\gbsection}
% The |\gbsection|\marg{id} macro is the core of the package, defining the different 
% (numbered) sections of the gamebook. It takes one mandatory argument that
% specifies the reference id (just as you would with a |\label| command.
% 
%	\DescribeMacro{\gbturn}
%  \noindent The |\gbturn|\marg{id} macro prints a link to a numbered section of the 
%  gamebook. 
%  It takes one mandatory argument that specifies the reference id of the respective 
%  section (as defined using the |\gbsection| macro). By default, there is a text 
%  before the link: ``turn~to''. You can change this text to your liking by using the 
%  following: 
%	\begin{center}
%	|\renewcommand{\gbturntext}|\marg{my new text}
%	\end{center}
%
%	\DescribeEnv{gbturnoptions}
%	\noindent If there are many options for the reader at the end of one section, you 
% can use the environment |gbturnoptions| for printing an indented list of these 
% options. Please note that the items of such a list are declared by using the 
% \DescribeMacro{\gbitem}  |\gbitem| macro. 
%	
%	\DescribeMacro{\gbvillain}
% As in any good gamebook, there is the need for villains and opponents. These are 
% typeset using the following command: 
%\begin{center}
%|\gbvillain|\marg{villain's name}\marg{skill}\marg{skill level}\marg{life}\marg{life level}
%\end{center}
%	
%	\DescribeMacro{\gbheader}
% In order to have both the first and the last numbered section in the headline of the 
% page, use the command |\gbheader|. This changes the page style accordingly. It is also 
% possible to put some text at the opposite side of the header (default ``Gamebook''): 
%\begin{center}
% |\renewcommand{\gbheadtext}|\marg{my new text}
%\end{center}
%
% This is only the formal documentation of the commands, a live example is included with 
% the package. Please refer to this for details.
% 
% \section*{Todo}
% It would be nice to have random figures in the text or fixed figures on a whole left 
% page (belonging to a certain section on the right page).
%
% Also, it would be good to customize the layout of sections and references to them 
% (|\fbox| etc.).
%
% 
% \StopEventually{}
% \section*{Implementation}
% This describes the source code for |gamebook.sty|. The first snippet deals with 
% the available options and how to process them. 
%    \begin{macrocode}
\RequirePackage{ifthen} 
    \newboolean{@debug}
    \newboolean{@drafting}

\DeclareOption{debug}{\setboolean{@debug}{true}}
\DeclareOption{draft}{\setboolean{@drafting}{true}}
\ProcessOptions\relax
%    \end{macrocode}
%
% \begin{macro}{\gbheader}
% The packages |fancyhdr| and |extramarks| are used to get the headlines 
% right, i.e., to print both the first and last numbered section for 
% navigation within the gamebook. |extramarks| is an add-on for 
% |fancyhdr| providing commands such as |\firstmark| etc. 
% |\gbheadtext| is printed on the opposite side of the section numbers 
% and can be changed as shown in the documentation above. 
%    \begin{macrocode}
\RequirePackage{fancyhdr} 
\RequirePackage{extramarks} 
\newcommand{\gbheadtext}{Gamebook}
\newcommand{\gbheader}{%
	\pagestyle{fancy}%
	\renewcommand{\sectionmark}[1]{\markboth{\thesection}{\thesection}}%
	\fancyhead{}% clear all header fields
	\fancyhead[LO,RE]{\small\gbheadtext}
	\fancyhead[RO,LE]{\small\ifthenelse{\equal{\firstleftmark}%
			{\leftmark}}{\leftmark}{\firstleftmark~--~\leftmark}}%
	%\fancyfoot{} % clear all footer fields
}
%    \end{macrocode}
% \end{macro}
%
%
% For debugging purposes, the reference ids of each section or 
% reference can be printed (using the |debug| option). This command 
% should only be used internally, |\gbdebugx| for section headers, 
% printing the reference id in the margin and |\gbdebug| for all 
% other places.
%    \begin{macrocode}
\newcommand{\gbdebug}[1]{\protect{\ifthenelse{\boolean{@debug}}%
		{~\texttt{\scriptsize(#1)}}{\relax}}}
\newcommand{\gbdebugx}[1]{\protect{\ifthenelse{\boolean{@debug}}%
		{\marginpar{\texttt{\scriptsize(#1)}}}{\relax}}}
%    \end{macrocode}
%
%
% \begin{macro}{\gbsection}
% The layout of the numbered sections is achieved using the |titlesec| 
% package. A section then starts with a boxed, bold number. If you would 
% like to change this, redefine |\titleformat{\section}| accordingly. 
% 
% Based on this, the command |\gbsection| is defined, consisting of an 
% empty, but numbered section that contains a label (which is the 
% mandatory parameter of |\gbsection|).
%    \begin{macrocode}
\RequirePackage{titlesec} 
	\titleformat{\section}[block]{%
		\centering\bfseries}{\fbox{\thesection}}{1em}{\relax}
\newcommand{\gbsection}[1]{\section{\label{#1}}\gbdebugx{#1}} 
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\gbturn}
% References to numbered sections are typeset using |\gbturn|, which puts the 
% text defined in |\gbturntext| before the reference. Change |\gbturntext| 
% for having a different or no text before the reference. The layout of these 
% references can be changed by redefining |\gbturn|.
%    \begin{macrocode}
\newcommand{\gbturntext}{turn~to~} 
\newcommand{\gbturn}[1]{\gbturntext{\bfseries\ref{#1}}\gbdebug{#1}}%\fbox
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\gbvillain}
% Villains and other kinds of opponents are typeset within a special 
% tabbing environment.
%    \begin{macrocode}
\newenvironment{gbtabbing}
  {\setlength{\topsep}{0pt}%
  \setlength{\tabbingsep}{0pt}%
   \setlength{\partopsep}{0pt}%
   \tabbing}%
  {\endtabbing}

\newcommand{\gbvillain}[5]{% 
	\hfill\begin{gbtabbing}%
		\hspace{\parindent}\= Sehr sehr langer Name %
		\= Sehr langer Skill + Wert \= Sehr langer Skill + Wert \kill%
		\> \textsc{#1} \> #2~#3 \> #4~#5 \\%
	\end{gbtabbing}%
}%
%    \end{macrocode}
% \end{macro}
%
%
% \begin{environment}{gbturnoptions}
% In order to offer multiple options as some kind of itemized list, a 
% special environment (including a dedicated item macro) is created.
%    \begin{macrocode}
\RequirePackage{enumitem} 
\newlist{gbturnoptions}{itemize}{1} 
\setlist[gbturnoptions]{%
		leftmargin=\parindent,labelindent=\parindent,label=} % noitemsep
\newcommand{\gbitem}[2]{\item #1\hfill\gbturn{#2}} 
%    \end{macrocode}
% \end{environment}
%
%
% In order to print drafting information on each page (if the option |draft| is
% enabled, certain configurations are made here. This is probably not useful 
% for most users and is likely to be removed in future versions.
%    \begin{macrocode}
\ifthenelse{\boolean{@drafting}}{% 
    \RequirePackage{draftwatermark}%
    	\SetWatermarkLightness{0.9}
			\SetWatermarkScale{.5}
%			\SetWatermarkText{\today\ at \thistime}
			\SetWatermarkText{Draft}
	\RequirePackage{scrtime} % time access
	\PassOptionsToPackage{draft}{prelim2e}
	\RequirePackage{prelim2e}
	\renewcommand{\PrelimWords}{\relax}
	\renewcommand{\PrelimText}%
		{\footnotesize[\,\today\ at \thistime\,]}}{\relax}
%    \end{macrocode}
% That's all, folks.
% \Finale
\endinput