cccb-formulare/doku.tex

%% NB: Dieses Dokument baut beim ersten Mal so 3-10 Minuten je nach
%%     Dateisystem-Performance… (Sehr viele Beispiele die jeweils komplette
%%     eigenständige Dokumente sind.)  Danach sollte es gehen.
% header <<<
\documentclass[ngerman,10pt]{scrreprt}
\setcounter{secnumdepth}{\subsubsectionnumdepth}
\setcounter{tocdepth}{\subsubsectiontocdepth}
\KOMAoptions{BCOR=1cm,DIV=10,open=any}
\usepackage{calc,tikz,minted,fontspec,luacode,babel,csquotes,hyperref}
\usetikzlibrary{calc}
\hypersetup{colorlinks,urlcolor={magenta!75!black},linkcolor={green!50!black}}
\linespread{1.10}
% font definition (same as cccbform.cls)
%% FIXME: [RawFeature +case] x [microtype] fixes
%% see https://github.com/schlcht/microtype/issues/33 for fix notes
%% see https://fontdrop.info/?darkmode=true for character lookup
% fonts <<<
\setmainfont[
	Renderer=HarfBuzz,
	ItalicFont=Recursive,
	BoldFont=Recursive,
	BoldItalicFont=Recursive,
	UprightFeatures={
		RawFeature={+ss01,+ss02,+ss08},
		RawFeature={+axis={MONO=0.0,CASL=0.2,slnt=0,CRSV=0,wght=400}}
	},
	BoldFeatures={RawFeature={+axis={MONO=0.0,CASL=0.2,slnt=0,CRSV=0,wght=700}}},
	BoldItalicFeatures={RawFeature={+axis={MONO=0.0,CASL=0.2,slnt=-15,CRSV=1,wght=700}}},
	ItalicFeatures={RawFeature={+axis={MONO=0.0,CASL=0.2,slnt=-15,CRSV=1,wght=400}}}
	]{Recursive}
\setmonofont[
	Renderer=HarfBuzz,
	ItalicFont=Recursive,
	BoldFont=Recursive,
	BoldItalicFont=Recursive,
	UprightFeatures={
		RawFeature={+ss01,+ss02,+ss08},
		RawFeature={+axis={MONO=1.0,CASL=0.2,slnt=0,CRSV=0,wght=400}}
	},
	BoldFeatures={RawFeature={+axis={MONO=1.0,CASL=0.2,slnt=0,CRSV=0,wght=700}}},
	BoldItalicFeatures={RawFeature={+axis={MONO=1.0,CASL=0.2,slnt=-15,CRSV=1,wght=700}}},
	ItalicFeatures={RawFeature={+axis={MONO=1.0,CASL=0.2,slnt=-15,CRSV=1,wght=400}}}
	]{Recursive}
\renewfontfamily\titlefont[
	Renderer=HarfBuzz,
	ItalicFont=Recursive,
	BoldFont=Recursive,
	BoldItalicFont=Recursive,
	UprightFeatures={
		RawFeature={+ss01,+ss02,+ss08},
		RawFeature={+axis={MONO=0.0,CASL=0.4,slnt=0,CRSV=1,wght=500}}
	},
	BoldFeatures={RawFeature={+axis={MONO=0.0,CASL=0.4,slnt=0,CRSV=1,wght=800}}},
	BoldItalicFeatures={RawFeature={+axis={MONO=0.0,CASL=0.4,slnt=-15,CRSV=1,wght=800}}},
	ItalicFeatures={RawFeature={+axis={MONO=0.0,CASL=0.4,slnt=-15,CRSV=1,wght=500}}}
	]{Recursive}
\setkomafont{disposition}{\titlefont}
% >>>
\usepackage{microtype}

% embedded examples <<<

% set up example build directory
\directlua{ os.execute "mkdir -p ./cccbform-examples/" }
\directlua{ os.execute "cp cccbform.cls logo.pdf cccbform-examples/" }
% stuff to add before/after examples to form a full document
\begin{luacode*}
HEADER1 = [[
\documentclass[shortexample]{cccbform}
]]
HEADER2 = [[
\begin{document}
]]
FOOTER = [[
\end{document}
]]
\end{luacode*}

% crinkly paper tears <<<
\begin{luacode*}
-- PARAM: number of layers, resulting in 2^LAYERS points
local LAYERS = 7
-- PARAM: per layer, multiply component by (1/(2^K))^weight
-- (1 = default, larger = smoother, smaller = rougher)
local weight = 1.00

N = 1 << LAYERS

function smoothstep( a, b, t )
	local t = t*t*(3-2*t)
	return a + (b-a)*t
end

function REFRESH_POINTS()
	POINTS = { }
	for i = 1, N do
		POINTS[i] = (2*math.random()-1)/N^weight -- + 0.125*math.sin( 2*math.pi*i/N )
	end

	for l = 2, LAYERS-1 do
		local K = 1<<l
		local len = N//K

		local RNG = { }
		for i = 1, K do  RNG[i] = 2*math.random()-1  end
		RNG[0] = RNG[K]

		for seg = 1, K do
			local lseg, rseg = (seg-1)*len, seg*len
			local lRNG, rRNG = RNG[seg-1], RNG[seg]
			for j = lseg+1, rseg do
				local t = (j-lseg)/len
				POINTS[j] = POINTS[j] + smoothstep(lRNG, rRNG, t)/K^weight
			end
		end
	end
	POINTS[0] = POINTS[N]
end

function getPoints()
	REFRESH_POINTS()
	local buf = { }
	for i = 0, #POINTS do  buf[i+1] = ("%.4fcm"):format( POINTS[i]/4 )  end
	buf = table.concat( buf, ", " )
	tex.print( [[\def\perturbationPoints{ ]]..buf.." }" )
	tex.print( [[\def\numPoints{ ]]..(#POINTS+1).." }" )
end

function plotPoints( x1, x2, y1, y2, smooth_top )
	x1, x2 = tonumber( (x1:sub(1,-3)) ), tonumber( (x2:sub(1,-3)) )
	y1, y2 = tonumber( (y1:sub(1,-3)) ), tonumber( (y2:sub(1,-3)) )
	local dx = (x2-x1)/(N)
	local buf = { }
	local SCALE = 10
	local P0 = 0
	if smooth_top then
		SCALE = SCALE * 2.5
		buf[#buf+1] = ("(%.4fpt, %.4fpt)"):format( x1, y1 )
		buf[#buf+1] = ("(%.4fpt, %.4fpt)"):format( x2, y1 )
	else
		REFRESH_POINTS()
		for i = 0, #POINTS do
			buf[#buf+1] = ("(%.4fpt, %.4fpt)"):format( x1 + i*dx, y1 + POINTS[i]*SCALE )
		end
		P0 = POINTS[0]
	end
	REFRESH_POINTS()
	for i = #POINTS, 0, -1 do
		buf[#buf+1] = ("(%.4fpt, %.4fpt)"):format( x1 + i*dx, y2 + POINTS[N-i]*SCALE )
	end
	buf[#buf+1] = ("(%.4fpt, %.4fpt)"):format( x1, y1 + P0*SCALE )
	buf = table.concat( buf, " -- " )
	tex.print( buf )
end
\end{luacode*}
% >>>

\begin{luacode*}
	function makeVerb( envname )
		local buf
		local function bufread( chunk )
			if chunk:find( "\\end{"..envname.."}" ) then  return nil  end
			buf[#buf+1] = chunk
			return ""
		end
		local function luaverbstart( )
			buf = { }
			luatexbase.add_to_callback( "process_input_buffer", bufread, "bufread" )
		end
		local function luaverbend( )
			luatexbase.remove_from_callback( "process_input_buffer", "bufread" )
			buf[#buf+1] = ""
			buf = table.concat( buf, "\n" )
			return buf
		end
		return luaverbstart, luaverbend
	end
\end{luacode*}

\begin{luacode*}
	function CMD(name)  return "\\"..name  end
	LF = "\n"

	function EndExample( EndFun, x1, x2 )
		CONTENT = EndFun( )
		if x1 ~= "" then
			EXTRALINES, EXTRASTUFF = 1, "\\geometry{paperheight="..x1.."}\n"
		else
			EXTRALINES, EXTRASTUFF = 0, ""
		end
		local f = io.open( "cccbform-examples/"..x2..".tex", "w" )
		f:write( HEADER1, EXTRASTUFF, HEADER2, CONTENT, FOOTER )
		f:close( )
		os.execute( "cd cccbform-examples ; latexmk -pdflua "..x2..".tex" )
		local n, f = 0, io.open( "cccbform-examples/"..x2..".tex" )
		for l in f:lines( ) do  n = n + 1  end
		tex.print( "\\def\\lc{"..(n - 1).."}" )
		tex.print( "\\def\\ls{"..(3 + EXTRALINES).."}" )
	end
\end{luacode*}

\directlua{ ShortExampleStart, ShortExampleEnd = makeVerb "ShortExample" }

\makeatletter
\newcommand{\gettikzxy}[3]{%
  \tikz@scan@one@point\pgfutil@firstofone#1\relax
  \edef#2{\the\pgf@x}%
  \edef#3{\the\pgf@y}%
}
\makeatother

\NewDocumentEnvironment{ShortExample}{s O{} m m}{
	\addvspace{1em}
	\directlua{ShortExampleStart()}
}{
	\directlua{ EndExample( ShortExampleEnd, "#2", "#3" ) }
	\par\noindent
	\null\hspace*{-2cm}
	\rlap{
		\begin{minipage}[t]{\textwidth + 4cm}
			\noindent
			\begin{tikzpicture}
				\node[anchor=north east] (code) at (-0.5ex,0) {
					\begin{minipage}[t]{0.5\textwidth - 3ex}
						\vspace{-2ex}
						\inputminted[firstline=\ls,lastline=\lc]{tex}{cccbform-examples/#3.tex}
					\end{minipage}
				};
				\node[anchor=north west] (output) at (0.5ex,0) {
					\begin{minipage}[t]{0.5\textwidth - 2ex}
						\includegraphics[width=\linewidth]{cccbform-examples/#3.pdf}
					\end{minipage}
				};
				\gettikzxy{(output.north west)}{\xl}{\yt}
				\gettikzxy{(output.south east)}{\xr}{\yb}
				\IfBooleanTF{#1}{
					\draw \directlua{ plotPoints( "\xl", "\xr", "\yt", "\yb", true ) };
				}{
					\draw \directlua{ plotPoints( "\xl", "\xr", "\yt", "\yb", false ) };
				}
			\end{tikzpicture}
			\par
			\vspace{-2ex}
			{\null\hfill\bfseries #4 \hfill\null}
		\end{minipage}
	}
	\par
	\addvspace{4ex}
}

% XXX now unused… keep while things are in flux and just delete if we don't add
% complete examples
\NewDocumentEnvironment{StandaloneExample}{m}{
	\VerbatimEnvironment%
	\begin{VerbatimOut}{cccbform-examples/#1.tex}}%
	{\end{VerbatimOut}%
	\directlua{ os.execute "cd cccbform-examples ; latexmk -pdflua #1.tex" }
	\directlua{
		local n, f = 0, io.open( "cccbform-examples/#1.tex" )
		for l in f:lines( ) do  n = n + 1  end
		tex.print( CMD"def"..CMD"lc".."{" .. (n-1) .. "}" )
	}
	\begin{tikzpicture}
		\node[anchor=north west, inner sep=1ex, draw] (code) {
			\begin{minipage}[t]{0.45\textwidth}
				\inputminted[firstline=3,lastline=\lc]{tex}{cccbform-examples/#1.tex}
			\end{minipage}
		};
		\node[anchor=north west, right=2mm of code, draw] (output) {
			\begin{minipage}[t]{0.45\textwidth}
				\includegraphics[width=\linewidth]{cccbform-examples/#1.pdf}
			\end{minipage}
		};
	\end{tikzpicture}
}

% >>>

\setminted{autogobble,bgcolor=black!10,frame=lines,framesep=1ex,tabsize=4,fontsize=\small}
% bgcolorvphantom is too new
\setmintedinline{frame=none,framesep=0pt,fontsize=\footnotesize}
\newmintinline[texcode]{tex}{}

\sloppy
\raggedbottom

\MakeOuterQuote{"}
\title{\texttt{cccbform} – Formulare für den CCCB}
\author{Frank Nord}
\begin{document}
\maketitle
\tableofcontents
% >>>

\chapter{Übersicht} % <<<

Die Grundstruktur für Formulare ist folgende:

\begin{center}
	\begin{minipage}{0.5\textwidth}
		\begin{minted}{tex}
			\documentclass{cccbform}
			\begin{document}
			% Inhalt hier
			\end{document}
		\end{minted}
	\end{minipage}
\end{center}

\texttt{cccbform} kümmert sich um die Details und definiert Hilfsbefehle zur
rein semantischen Erstellung von PDF-Formularen.  Mit einer Reihe
von Befehlen kann dann recht bequem ein Formular definiert werden.
Dieses Dokument gibt eine Übersicht über alles, was hilfreich sein könnte.
Allein schon existierende Formulare anzusehen oder zu kopieren und anzupassen
sollte jedoch für die meisten Zwecke ausreichen.

\section{Voraussetzungen} % <<<

Eine aktuelle \TeX-Distribution (auf den meisten Systemen vermutlich \TeX~Live)
inklusive ggf. dem \texttt{luatex}-Unterpaket, zusätzlich \texttt{latexmk} und
-- sofern noch nicht vorhanden -- \texttt{make} sollten auf der Programmseite
ausreichen.

Auf Debian heißen die konkreten Pakete:\\[1ex]
\null\hfill\begin{minipage}[t]{0.75\textwidth}
\texttt{make} \texttt{texlive} \texttt{texlive-pictures}
\texttt{texlive-latex-extra} \texttt{texlive-luatex}
\texttt{texlive-lang-german} \texttt{latexmk}
\end{minipage}\hfill\null\\[1ex]
auf anderen Systemen heißen sie hoffentlich ähnlich\dots{} ansonsten: viel Spaß
beim Suchen!

Die verwendete Schrift heißt "Recursive" und kann auf
\url{https://recursive.design} oder Google Fonts gefunden werden.  Wir brauchen
nur die "Variable Font", die entweder \texttt{*\_VF\_*}
oder \texttt{*-VariableFont\_*} heißt, alle anderen Einzelschriften sind
unnötig.\footnote{Direktlink auf GitHub (ohne Gewähr):
\url{https://github.com/arrowtype/recursive/raw/refs/heads/main/fonts/ArrowType-Recursive-1.085/Recursive_Desktop/Recursive_VF_1.085.ttf}}
Die Schrift muss an einem Ort installiert werden, wo die
\texttt{luatex}-Font-Suche sie findet -- die meisten Standard-Ordner sollten
funktionieren, z.~B. auch \texttt{\$\{HOME\}/.local/share/fonts}.

% >>>

\section{Für \TeX-Neulinge} % <<<

Das meiste sollte auch ohne \TeX-Kenntnisse gehen, es gibt jedoch eine Reihe
von Sonderzeichen, die besondere Bedeutung haben.  Als eines der wichtigeren
beginnt \texcode|%| einen Zeilenkommentar.  Bei den meisten Symbolen
reicht es, einen Backslash (\texttt{\textbackslash}) davorzusetzen, aber der
Backslash selbst wird z.~B. durch \texcode{\textbackslash} und nicht
\texcode{\\} erzeugt.  Bei Unsicherheit hilft auch
\url{http://detexify.kirelabs.org/classify.html}.  (Dort kann man
Symbole malen und bekommt eine Liste möglicher Übereinstimmungen und wie man
diese jeweils erzeugt. Das Symbol sollte generell ohne
\texttt{\textbackslash usepackage} auskommen und im \texttt{textmode}
funktionieren -- diese Infos stehen ggf. über/unter dem Zeichen.)

\subsection{Leerzeichen \& Umbrüche} % <<<

Zu Leerzeichen und Zeilenumbrüchen noch folgendes: \emph{Einfache
Zeilenumbrüche} werden wie in Markdown und anderen Formaten als einfaches
Leerzeichen interpretiert und \emph{nicht} als Umbruch.  Separate Absätze
werden erzeugt, wenn mindestens zwei Zeilenumbrüche aufeinander folgen (d.~h.
auch im Text visuell eine Lücke entsteht), alternativ auch mit dem
\texcode{\par}-Makro.  Einen Zeilenumbruch innerhalb eines Absatzes erzeugt man
mit \texcode{\\}, das ist aber meistens das falsche Werkzeug.

Ein oder mehrere Leerzeichen werden wie ein einzelnes Leerzeichen gelesen,
erlauben aber generell Zeilenumbrüche wenn die Zeile voll ist.
\texcode{~} erzeugt geschützte Leerzeichen, die nicht umbrechen dürfen
(und z.~B. bei Abkürzungen (\texcode{z.~B.}) oder Zahlen mit Einheiten
verwendet werden sollten.)

Nach Befehlen (\texcode{\foo}) werden (beliebig viele) Leerzeichen
generell als Token-Trenner ignoriert und entfernt (\texcode{\TeX test}
= \TeX test), ein Verdoppeln des Leerzeichen bringt ebenfalls nichts.
Stattdessen kann man entweder leere Argumente angeben
(\texcode{\TeX{} test} = \TeX{} test) oder das Leerzeichen ebenfalls mit einem
Backslash schützen (\texcode{\TeX\ test} = \TeX\ test.)

% >>>

\subsection{Befehlsstruktur} % <<<

\TeX\ ist eine sehr flexible Makro-Sprache, aber sowohl \LaTeX\ als auch diese
Klasse geben sich Mühe, das meiste davon zu verstecken und sehr einheitliche
Struktur vorzugeben.  Befehlsaufrufe haben hier generell die Form
\texcode{\Befehl{Arg1}{Arg2}...{ArgN}}, wobei Argumente in geschweiften
Klammern immer angegeben werden müssen.  Einige Befehle akzeptieren auch
\emph{optionale Argumente}, welche als Konvention eckige Klammern benutzen --
diese können entweder angegeben oder komplett weggelassen werden
(\texcode{\Foo{Baz}} oder \texcode{\Foo[Bar]{Baz}}.)
Zusätzlich gibt es manchmal auch "gesternte" Varianten, wo ein \texttt{*}
unmittelbar auf den Namen folgt (\texcode{\Fnord{23}} oder
\texcode{\Fnord*{23}}.)  Konzeptuell ist das ein optionales
true/false-Argument, nur mit anderer Schreibweise.

% >>>

\subsection{Erzeugen von PDFs} % <<<

Sind alle Tools installiert, so sollte ein \texttt{make} ausreichen.  (Das
Makefile findet automatisch alle neuen \texttt{.tex}-Dateien.)  Soll nur ein
einzelnes Dokument gebaut werden, so sollte \texttt{make foo.pdf} zu einem
\texttt{foo.tex} genau dieses eine Dokument bauen.

Wirklich \emph{alle} Dokumente zu bauen dürfte beim ersten Mal mehrere Minuten
dauern.  (Diese Dokumentation hier enthält viele Beispiele, die tatsächlich
eigenständige Dokumente sind.  Der Overhead für alle je 2× \texttt{lualatex} zu
starten, mehrere temporäre Dateien zu schreiben, etc. etc. kann gut 3--10
Minuten fressen.)  Danach erkennen \texttt{make} bzw. \texttt{latexmk}, dass
sich in den meisten Dateien nichts verändert hat und es geht bei zukünftigen
Durchläufen deutlich schneller (solange nicht die Klasse verändert wird -- was
wieder alles neu bauen würde -- braucht das wenige Sekunden bis ca. eine
Minute.)

% >>>

% >>>

% >>>

\chapter{Befehle} % <<<

Bereitgestellte Befehle fallen grob in 4 Kategorien -- Titel, Inhalt, Struktur,
Hervorhebung.  Zusätzlich hat die Klasse selbst ein paar Optionen.

\section{Klassen-Optionen} % <<<

PDF-Formulare haben eine ganze Reihe von Problemen.  Das wichtigste ist, dass
viele Viewer PDF-Formulare nicht mitdrucken.  Die Elemente wie sie hier erzeugt
werden sind also in Wirklichkeit ein Bild, was wie ein Formularfeld aussieht und
dann ein "echtes" Feld direkt darüber platziert. \emph{Manche} Viewer hingegen
drucken die Elemente mit, was dann wiederum anders komisch aussehen kann\dots

\subsection{\texttt{noform}}

Wird das Dokument also stattdessen mit
\texcode|\documentclass[noform]{cccbform}| begonnen, werden keine
PDF-Formular-Felder erzeugt sondern nur die "falschen" als Bilder erzeugt. Das
stellt sicher, dass reine Druckvorlagen (die eh nicht ausgefüllt werden sollen)
mit allen Viewern fehlerfrei gedruckt werden können.

\subsection{\texttt{example} und \texttt{shortexample}}

Diese sind lediglich für Beispiele -- wie hier in dieser Doku -- gedacht.
\texttt{example} wählt A6 als Format aus, reduziert die Ränder auf fast nichts,
und passt ein paar Befehle an das kleinere Format an. \texttt{shortexample}
macht das gleiche, berechnet aber am Ende die tatsächliche Höhe und verkürzt
das ausgegebene Dokument.  Fast alle Beispiele hier sind
\texttt{[shortexample]}s.

% >>>

\section{Titel} % <<<

Aktuell gibt es zwei Arten von Titeln.  In jedem Fall sollte genau einer und
unmittelbar in der Zeile hinter dem \texcode{\begin{document}} verwendet
werden.

Bei langen Titeln ist ein manueller Zeilenumbruch (\texcode{\\}) im Titel ggf.
sinnvoll, da der Text sonst über das Logo bis zum Seitenrand laufen kann.  (Das
Logo und ggf. die Adresse werden nachträglich platziert, \TeX\ "sieht" diese
also nicht beim verarbeiten des restlichen Inhalts.)

\subsection{\texcode{\LogoTitle{Titel}}} % <<<

\begin{ShortExample}*[4.953cm]{logotitle}{Die einfache Variante -- Titel links, Logo rechts.}
\LogoTitle{Beispieltitel}
\Text{(...und hier geht's weiter.)}
\end{ShortExample}

% >>>

\subsection{\texcode{\AddressTitle{Titel}}} % <<<

\begin{ShortExample}*[8.865cm]{addresstitle}{Titel und Adresse}
\AddressTitle{Beispieltitel}
\Text{(...und hier geht's weiter.)}
\end{ShortExample}

\filbreak
\subsubsection{\texcode{\AddressTitle*{Titel}}}

Es gibt auch die Variante mit \texttt{*}, welche zusätzlich das Logo einbettet.
\nopagebreak[2]

\begin{ShortExample}*[8.865cm]{addresstitlestar}{Titel, Adresse und Logo}
\AddressTitle*{Beispieltitel}
\Text{(...und hier geht's weiter.)}
\end{ShortExample}

% >>>

% >>>

\section{Inhalt} % <<<

Hier gibt es größtenteils Befehle für Formularfelder. Anders als in normalen
\TeX-Dokumenten ist es hier jedoch wichtig, für korrekte Abstände \emph{allen}
"losen" Text explizit als \texcode{\Text} auszuzeichnen.  Der Befehl kümmert
sich um korrekte Abstände, ohne diesen liegen Dinge zu eng beieinander.
Vergleiche:

\begin{ShortExample}{textgood}{Text mit korrekten Abständen}
\Text{Dieser Satz kein Verb.}
\TextField{Lachhubel}
\Text{Die blöden Ösen!}
\end{ShortExample}

\begin{ShortExample}{textbad}{lose Worte -- nicht gut!}
Dieser Satz kein Verb.
\TextField{Lachhubel}
Die blöden Ösen!
\end{ShortExample}

Auch lange Texte mit mehreren Absätzen können in \texcode{\Text} verwendet
werden.

\begin{ShortExample}{textlong}{langer Text ist kein Problem}
\Text{
	Lorem ipsum dolor sit amet,
	consectetuer adipiscing elit.
	Aenean commodo ligula eget dolor.
}
\TextField{Aenean massa.}
\Text{
	Cum sociis natoque penatibus et
	magnis dis parturient montes,
	nascetur ridiculus mus.

	Donec quam felis, ultricies nec,
	pellentesque eu, pretium quis, sem.
	Nulla consequat massa quis enim.
}
\end{ShortExample}

\subsection{Textfelder} % <<<

Die vermutlich wichtigste Komponente, entsprechend viele Varianten gibt es.

\subsubsection{\texcode{\TextField}} % <<<

Im Zweifel ist die einfachste Variante die richtige: Ein einzeiliges
Freitextfeld mit Label und einer für die meisten Zwecke angemessenen Breite
(welche auch z.~B. in mehrspaltigen Bereichen von allein angepasst wird).

\begin{ShortExample}{textfield}{normales Textfeld}
\TextField{Bezeichnung}
\end{ShortExample}

\paragraph{\texcode{\TextField*}} Wird die volle Breite benötigt gibt es auch
die Variante mit Stern:

\begin{ShortExample}{textfieldstar}{maximale Breite}
\TextField*{Bezeichnung}
\end{ShortExample}

% >>>

\subsubsection{\texcode{\ShortTextField}} % <<<

Wirkt die Breite hingegen zu hoch (z.~B.  für eine einzelne Zahl), so gibt es
auch ein explizit kurzes Textfeld.

\begin{ShortExample}{shorttextfield}{kurzes Textfeld}
\ShortTextField{Stromverbrauch (TWh)}
\end{ShortExample}

\paragraph{\texcode{\ShortTextField[width]}} Optional kann die Länge auch
explizit als Faktor relativ zur Textbreite angegeben werden.  Das Formular
sieht aber einheitlicher aus, wenn das \emph{nicht} gemacht wird, also bitte
zweimal überlegen, ob es das \emph{wirklich} braucht.

\begin{ShortExample}{shorttextfieldopt}{besonders kurzes Textfeld}
\ShortTextField[0.15]{Verbrauch (TWh)}
\end{ShortExample}

% >>>

\subsubsection{\texcode{\MultilineTextField}} % <<<

Für mehr Text gibt es auch mehrzeilige Textfelder.  Auch wenn die Höhe
technisch gesehen optional ist, sollte sie immer angegeben werden -- ansonsten
hat das Feld die Standard-Höhe von normalen Textfeldern.

\begin{ShortExample}{multilinetextfield}{mehrzeiliges Textfeld}
\MultilineTextField[2cm]{Kringel}
\end{ShortExample}

\begin{ShortExample}{multilinetextfieldbad}{einzeiliges mehrzeiliges Textfeld}
\MultilineTextField{Kringel}
\end{ShortExample}

\paragraph{\texcode{\MultilineTextField*}} Auch hier gibt es wieder die
Variante mit Stern für volle Breite:

\begin{ShortExample}{multilinetextfieldstar}{breites mehrzeiliges Textfeld}
\MultilineTextField*[2cm]{Kringel}
\end{ShortExample}

% >>>

\subsubsection{Spezialfälle} % <<<

Unterschriften sollen üblicherweise händisch gesetzt werden, hierfür gibt es
daher ein Feld was nur ein "falsches" Formularfeld ist und nicht digital
ausgefüllt werden kann.

(NB: Die Breite ist -- wie bei allem -- relativ zur Papierbreite definiert.  Da
diese bei diesen Beispielen deutlich schmaler als A4 ist, sieht das Feld hier
sehr schmal aus; im "richtigen" Formular wird es aber eine angemessene Größe
haben.)

\begin{ShortExample}{signature}{Feld für Unterschriften}
\Signature
\end{ShortExample}

Das Label kann optional geändert werden.

\begin{ShortExample}{signatureopt}{Unterschrift mit anderem Label}
\Signature[Unterschrift]
\end{ShortExample}

\paragraph{\texcode{\Notes}} Ebenfalls gibt es ein etwas größeres Feld für
Notizen oder Vermerke.

\begin{ShortExample}{notes}{großes Feld}
\Notes
\end{ShortExample}

Auch hier kann optional das Label geändert werden.

\begin{ShortExample}{notesopt}{großes Feld}
\Notes[Stirnabdruck]
\end{ShortExample}

\paragraph{\texcode{\InlineTextField}} Letztlich gibt es für Sonderfälle noch
Inline-Textfelder.

\begin{ShortExample}{inlinetextfield}{Sonderfall -- Inline}
\Text{Zur Fehlersuche wurden etwa
\InlineTextField[0.1]{} Stunden aufgewendet,
\InlineTextField[0.1]{} Gramm Koffein sowie
\InlineTextField{} konsumiert.
\formstrut % normierte Zeilenhöhe forcieren
}
\end{ShortExample}

Hierbei ist zu beachten, dass Textfelder höher sind als der umliegende Text.
Ohne das \texcode{\formstrut} würde die letzte Zeile \emph{deutlich} dichter an
der darüberliegenden kleben, was -- insbesondere wenn es stattdessen eine Zeile in der Mitte betrifft -- komisch aussehen würde.  Das muss also ggf. in ≈jede Zeile eingestreut werden.  Vergleiche auch nochmal:

\begin{ShortExample}{formstrutbad}{Wackeliger Text}
\Text{Zeile mit Feld \InlineTextField{} und
dann ganz viel Text, so dass dazwischen
mehrere Zeilen ohne Textfelder entstehen,
ein weiteres Feld \InlineTextField{}, mehr
Text der wieder etwas dichter beieinander
liegt, und dann irgendwann abschließend
nochmal eine Zeile mit noch einem Feld
\InlineTextField{} um den Unterschied zu
sehen.
}
\end{ShortExample}

\begin{ShortExample}{formstrutgood}{Gleichmäßiger Text}
\Text{Zeile mit Feld \InlineTextField{} und
dann ganz viel Text, so dass dazwischen
\formstrut
mehrere Zeilen ohne Textfelder entstehen,
ein weiteres Feld \InlineTextField{}, mehr
Text der wieder etwas dichter beieinander
\formstrut
liegt, und dann irgendwann abschließend
\formstrut
nochmal eine Zeile mit noch einem Feld
\InlineTextField{} um den Unterschied zu
sehen.\formstrut
}
\end{ShortExample}

Es wird hoffentlich deutlich, dass beide Varianten nicht ideal sind und
Inline-Felder nur in Ausnahmefällen die richtige Wahl sind.  Dabei sollte aber
nochmal darauf hingewiesen werden, dass dieses Problem bei nur einer Zeile
Text nicht relevant ist, da dann die Abstände um die Block-Elemente herum
sowieso für ein einheitliches Aussehen sorgen.

% >>>

% >>>

\subsection{Checkboxen} % <<<

\subsubsection{\texcode{\Checkbox} -- normale Verwendung} % <<<

Gibt es eigentlich nicht viel dazu zu sagen -- \texcode{\Checkbox{Label}} für
eine Checkbox (und das Label kann auch ein kompletter Absatz sein.)

\begin{ShortExample}{checkbox}{Checkboxen}
\Checkbox{Ich habe die AGB,
	Datenschmutzerklärung,
	Beitragsordnung, Satzung, Hausordnung
	(inklusive Durchführungsverordnung
	zur Pflanzenpflege im Treppenhaus),
	Geheimhaltungsvereinbarung, die
	Datenschutzgrundsätze in leichter
	Sprache (PDF, 451 Seiten), das
	Hygienekonzept, sowie die Anleitung
	zum Lesen von Anleitungen gelesen.}
\end{ShortExample}

% >>>

\subsubsection{\texcode{\CheckboxOther}} % <<<

Für Freitextfelder als "Sonstige:" gibt es
\texcode{\CheckboxOther[Breite]{Label}}, wieder mit optionaler Breitenangabe
(relativ zur Textbreite) für das Freitextfeld.

\begin{ShortExample}{othercheckbox}{"Sonstiges"}
\Text{Meine Lieblingstaste ist:}
\begin{Indented}
	\Checkbox{Escape}
	\Checkbox{Enter}
	\CheckboxOther[0.1]{Buchstabe}
	\CheckboxOther[0.1]{F\hspace{-1em}}
	\CheckboxOther{}
\end{Indented}
\end{ShortExample}

Auch hier gilt: umso weniger verschiedene Breiten verwendet werden, umso
einheitlicher sieht das Formular am Ende aus.  Bei dem Beispiel würde ein
einzelner Buchstabe auch in ein 0.05-er Feld passen, das wären dann aber 3
statt 2 verschiedener Breiten.

% >>>

\subsubsection{Spezielle Zwecke -- \texcode{\InlineCheckbox}} % <<<

In Sondersituationen könnten z.~B. in Aufzählungen innerhalb einer Zeile auch
Checkboxen benötigt sein.  Dafür gibt es die -- nur in Ausnahmefällen zu
verwendende -- Inline-Variante, welche sich (fast) gar nicht um die
Formatierung kümmert und nur die Box zur Verfügung stellt.  (Das Einzige: ein
Leerzeichen auf der rechten Seite wird sichergestellt, für gleichmäßige
Abstände sollte also genau \emph{nicht} \texcode{{}} oder \texcode{\ }
angehängt werden.)

\begin{ShortExample}{inlinecheckbox}{Sonderfall -- Inline}
\Text{Ich bin \InlineCheckbox groß,
	\InlineCheckbox grau, und/oder
	\InlineCheckbox unwichtig.
}
\begin{Indented}
	\Text{(Bearbeitungsvermerk: Bei
	Anwahl von zwei oder mehr ist der/die
	Ausfüllende möglicherweise ein
	Irrelefant und vor Aufnahme
	\ul{zwingend} eine
	Löschdiskussionsrecherche
	durchzuführen.)}
\end{Indented}
\end{ShortExample}

% >>>

% >>>

% >>>

\section{Struktur} % <<<

Drei Kategorien -- formularspezifisch, "klassische" Abschnitte, und mehrere Spalten.

\subsection{formularspezifisch angepasste Formen} % <<<

\subsubsection{\texcode{\begin{Indented} ... \end{Indented}}} % <<<

Visuelle Gruppierung durch Einrücken von zusammenhängenden bzw. untergeordneten
Abschnitten ist eine sehr gute Option, da ohne zusätzliche Tinte trotzdem klar
die Struktur vermittelt wird.  (Das wurde auch schon bei den Checkboxen
unmittelbar hier drüber verwendet.) Optional kann ein Faktor (nicht zwingend
ganzzahlig) für die Einrückungstiefe angegeben werden.

\begin{ShortExample}{indentation}{Einrückung, auch über mehrere Ebenen}
\Text{abc}
\begin{Indented}
	\Text{def}
	\begin{Indented}
		\Text{ghi}
	\end{Indented}
	\Text{jkl}
\end{Indented}
\Text{mno}
\begin{Indented}[2]
	\Text{pqr}
\end{Indented}
\begin{Indented}[1.4142]
	\Text{stu}
\end{Indented}
\end{ShortExample}

% >>>

\subsubsection{\texcode{\RuleSection}} % <<<

Dient zur Trennung von Formularabschnitten, die durch verschiedene
Personengruppen ausgefüllt werden.  Die Linie geht immer über die komplette
Formularbreite und kann z.~B. nicht innerhalb von mehrspaltigen Bereichen
verwendet werden.

\begin{ShortExample}{rulesection}{Mehrere klar getrennte Abschnitte}
\TextField{Name}
\TextField*{Anliegen}
\RuleSection{Bearbeiter}
\Checkbox{Antrag angenommen}
\CheckboxOther[0.5]{Abgelehnt, weil:}
\end{ShortExample}

% >>>

\subsubsection{\texcode{\Rule}} % <<<

Eine einfache Trennlinie, die an verschiedenen Stellen zur grafischen Trennung
eingesetzt werden kann.

\begin{ShortExample}{rule}{Mehr Trennlinien}
\RuleSection{Bearbeiter}
\CheckboxOther{Antrag eingegangen am:}
\Rule
\Checkbox{Antrag angenommen}
\begin{Indented}
\CheckboxOther{Bearbeitet am:}
\CheckboxOther{Antragsteller informiert:}
\end{Indented}
\Rule
\CheckboxOther[0.5]{Abgelehnt, weil:}
\end{ShortExample}

% >>>

% >>>

\subsection{"klassische" Struktur} % <<<

In \TeX\ üblich sind \texcode{\section}, \texcode{\subsection}, etc.; in
Analogie dazu gibt es für ggf.  längere Formulare \texcode{\Section} und
\texcode{\Subsection}.  Für die meisten Formulare ist das jedoch vermutlich
nicht nötig, insbesondere da ggf. per Einrückung via
\texcode|\begin{Indented} ... \end{Indented}| visuell schneller lesbare
Struktur geschaffen werden kann.

\begin{ShortExample}{sectioning}{Abschnittsunterteilung}
\Section{Allgemeines}
\TextField{Name}
\Section{Antragsinhalt}
\TextField*{Anliegen}
\Subsection{Details}
\Notes[]
\Section{Abschließendes}
\Checkbox{Die AGB werden akzeptiert.}
\Signature
\end{ShortExample}

% >>>

\subsection{mehrspaltige Bereiche} % <<<

Es gibt Unterstützung für 2, 3, und 5 Spalten (ggf. können diese auch
ineinander geschachtelt werden.)  Die Befehle heißen -- vermutlich wenig
überraschend -- \texcode{\TwoColumns}, \texcode{\ThreeColumns}, und
\texcode{\FiveColumns} und es sollten entsprechend viele \texcode{{}}-Gruppen
folgen.

\begin{ShortExample}{multicolumn}{Mehrspaltigkeit}
\TwoColumns{
	\TwoColumns{
		\Checkbox{Ja}
	}{
		\Checkbox{Nein}
	}
	\Rule
	\ThreeColumns{
		\Checkbox{A}
	}{
		\Checkbox{B}
	}{
		\Checkbox{C D E F G}
	}
	\Rule
	\ThreeColumns{
		\Checkbox{Foo}
	}{
		\Checkbox{Bar}
	}{
		\Checkbox{Baz}
	}
}{
\Notes
}
\end{ShortExample}

Bei zu vielen Spalten werden die Abstände unlesbar -- siehe hier die
Foo/Bar/Baz-Gruppierung. Auf A4 geht diese Schachtelung aber üblicherweise noch
problemlos.

% >>>

% >>>

\section{Hervorhebung} % <<<

Es gibt verschiedene in \TeX\ eingebaute Befehle, die ebenfalls verwendet
werden können\dots\ aber "weniger ist mehr" trifft insbesondere auch hier zu.
Die meisten sollten also nur bei ernsthaftem Bedarf verwendet werden.

Eine akzeptable Formatierungsmethode ist das Hervorheben von Text mit
\texcode{\emph}.  Üblicherweise typografisch eher verpönt, aber schon irgendwie
zum aktuellen Design passend, können mit \texcode{\ul} auch \emph{einzelne
Worte oder sehr kurze Passagen} unterstrichen werden, dabei ist jedoch zu
beachten, dass innerhalb unterstrichener Bereiche keine Zeilenumbrüche mehr
möglich sind. (Der Bereich wird als eine logische Box verpackt und kann nur
noch als Ganzes verschoben werden.)

Es gibt zwar eigentlich viele verschiedene Schriftgrößen, es ist jedoch keine
gute Idee, alle quer durcheinander zu verwenden.  Die Dokumentenklasse kümmert
sich ums meiste, als einzige Akzeptable gibt es \texcode{\details} (als
semantischen Namen), welche für untergeordnete Bemerkungen zur Verfügung steht.

\begin{ShortExample}{formatting}{Formatierungsbeispiele}
\Text{Die Formulare sind \ul{sofort}
nach Eingang zu kopieren und in
\emph{dreifacher} Ausfertigung
abzuheften!}
\Text{\details{Bei Ausfall des Kopierers
ist umgehend der Techniker zu informieren
und ersatzweise die Faxgeräte mit der -02
und der -05 \ul{(nicht die -07 bis -09
oder -12!)} zum Kopieren per Fax zu
verwenden.}}
% und nochmal umbrechbarer:
\Text{\details{Bei Ausfall des Kopierers
ist umgehend der Techniker zu informieren
und ersatzweise die Faxgeräte mit der -02
und der -05 (\ul{nicht} die -07 bis -09
oder -12!) zum Kopieren per Fax zu
verwenden.}}
\end{ShortExample}

% >>>

% >>>

\chapter{Hinweise zum Design} % <<<

Das aktuelle Design ist iterativ entstanden und vermutlich erstmal \emph{gut genug},
aber deutlich nicht komplett durchstrukturiert und -getestet.

\section{Schrift}

Die Schrift "Recursive" wird im Text mit \texttt{CASL=0.2} zwischen den
Extremen benutzt.  Die anderen Achsen halten sich an die Standard-Werte
(\texttt{wght=400/700} für normal/fett, \texttt{slnt=0/-15} und
\texttt{CRSV=0/1} für normal/kursiv, und \texttt{MONO=0.0/1.0} für
normal/festbreite.)  Für Titel wird sowohl das Gewicht leicht erhöht
(\texttt{wght=500/800}) als auch \texttt{CASL=0.4} verdoppelt.  (Das ist schon
ziemlich kräftig, \texttt{CASL=1.0} ist zu extrem.)

\section{Formularfelder}

Textfeldhöhe plus Abstand zusammen sollten für Handschrift groß genug sein.
Die Grautöne wurden mit dem Drucker getestet und sollten sowohl bei direktem
Druck als auch bei einfacher Kopie lesbar bleiben.  Mehr wurde da noch nicht
optimiert.

Die schrägen Label (um 1em rausgeschoben und um 4.20° rotiert) sind relativ gut
durchgetestet und sehen zusammen mit der Schrift chaotisch aus ohne tatsächlich
chaotisch zu sein.  Solange das Label nicht zu lang wird, ist es auch beim
Ausfüllen des Formulars nicht zu sehr im Weg.

Abstände etc. sind eher so Bauchgefühl und nicht komplett durchdacht.  Es gab
bisher noch keine offensichtlichen Probleme damit, aber müsste man mal nochmal
anschauen\dots

% >>>

\end{document}

% vim: set fdm=marker fmr=<<<,>>> :