\documentclass{ltxdoc}
\usepackage[ngerman]{babel}
\usepackage{tikz,geometry,minted,fontspec,luacode,csquotes}
\MakeOuterQuote{"}
\geometry{a4paper,margin=2cm}
% font definition (same as cccbform.cls)
\setmainfont[
	Renderer=HarfBuzz,
	ItalicFont=Recursive,
	BoldFont=Recursive,
	BoldItalicFont=Recursive,
	Scale=0.9,
	UprightFeatures={
		RawFeature={+ss01,+ss02,+ss08,+case},
		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,
	Scale=0.9,
	UprightFeatures={
		RawFeature={+ss01,+ss02,+ss08,+case},
		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}
\newfontfamily\titlefont[
	Renderer=HarfBuzz,
	ItalicFont=Recursive,
	BoldFont=Recursive,
	BoldItalicFont=Recursive,
	Scale=0.9,
	UprightFeatures={
		RawFeature={+ss01,+ss02,+ss08,+case},
		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}

% set up example build directory
\directlua{ os.execute "mkdir -p cccbform-examples" }
\directlua{ os.execute "cp cccbform.cls cccbform-examples/" }
\directlua{ os.execute "cp 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*}

\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" }

\NewDocumentEnvironment{ShortExample}{O{} m m}{
	\addvspace{1em}
	\directlua{ShortExampleStart()}
}{
	\directlua{ EndExample( ShortExampleEnd, "#1", "#2" ) }
	\par
	\vbox{
		\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/#2.tex}
				\end{minipage}
			};
			\node[anchor=north west, draw=black!50] (output) at (0.5ex,0) {
				\begin{minipage}[t]{0.5\textwidth - 2ex}
					\includegraphics[width=\linewidth]{cccbform-examples/#2.pdf}
				\end{minipage}
			};
		\end{tikzpicture}
		\par
		\vspace{-2ex}
		{\null\hfill\bfseries #3 \hfill\null}
	}
	\par
	\addvspace{4ex}
}

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

\sloppy
\raggedbottom

\title{\texttt{cccbform} -- Formulare für den CCCB}
\author{Frank Nord}
\begin{document}
\maketitle
\tableofcontents

\section{Ü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 mit PDF-Formularen und definiert
Hilfsbefehle zur rein semantischen Erstellung von Formularen.  Mit einer Reihe
von Befehlen kann dann recht bequem ein Formular definiert werden.

\subsection{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 \texttt{\%} einen Zeilenkommentar.  Bei den meisten Symbolen reicht es,
einen Backslash (\texttt{\textbackslash}) davorzusetzen, aber der Backslash
selbst wird z.~B. durch \texttt{\textbackslash textbackslash} und nicht
\texttt{\textbackslash\textbackslash} 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.)

Zu Leerzeichen und Zeilenumbrüchen noch folgendes: Einfache Zeilenumbrüche
werden von \TeX{} generell ignoriert bzw. wie ein Leerzeichen zwischen Worten
behandelt.  Eine leere Zeile (also (mindestens) zwei aufeinanderfolgende
Zeilenumbrüche) beginnt einen neuen Absatz. (Das geht auch mit
\texttt{\textbackslash par}.)  \texttt{\textbackslash\textbackslash} ist
ein "einfacher" Zeilenumbruch in der Ausgabe (ohne den Absatz zu beenden), der
hier aber möglichst vermieden werden sollte.  Ein oder mehrere Leerzeichen
werden wie ein einzelnes Leerzeichen gelesen, erlauben aber generell
Zeilenumbrüche wenn die Zeile voll ist.  \texttt{\textasciitilde} erzeugt
geschützte Leerzeichen, die nicht umbrechen dürfen (und z.~B.
(\texttt{z.\textasciitilde B.}) bei Abkürzungen oder Zahlen mit Einheiten
verwendet werden sollten.)  Nach Befehlen (\texttt{\textbackslash irgendwas})
werden Leerzeichen generell als Trenner des Namens von nachfolgenden Zeichen
ignoriert und ein Verdoppeln des Leerzeichen bringt ebenfalls nichts.
Stattdessen kann man entweder leere Argumente angeben
(\texttt{\textbackslash TeX\{\} test}) oder das Leerzeichen ebenfalls mit einem
Backslash schützen (\texttt{\textbackslash TeX\textbackslash\ test}.)

\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
\mintinline{tex}|\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.

\section{Struktur}

Bereitgestellte Befehle fallen grob in 4 Kategorien -- Titel, Inhalt, Struktur, Hervorhebung.

\subsection{Titel}

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

Bei langen Titeln ist ein manueller Zeilenumbruch
(\texttt{\textbackslash\textbackslash}) 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.)

\subsubsection{\texttt{\textbackslash LogoTitle\{Titel\}}}

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

\subsubsection{\texttt{\textbackslash AddressTitle\{Titel\}}}

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

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

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

\subsection{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 \texttt{\textbackslash 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 \texttt{\textbackslash 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}

\subsubsection{Textfelder}

Die vermutlich wichtigste Komponente, entsprechend viele Varianten gibt es.

\paragraph{\texttt{\textbackslash 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}

Wird die volle Breite benötigt gibt es auch die Variante mit Stern:

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

\paragraph{\texttt{\textbackslash 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}

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}

\paragraph{\texttt{\textbackslash 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}
%%% FIXME bug in preview (works in doc)
\Text{}
\MultilineTextField[2cm]{Kringel}
\Text{}
\end{ShortExample}

\begin{ShortExample}{multilinetextfieldbad}{einzeiliges mehrzeiliges Textfeld}
%%% FIXME bug in preview (works in doc)
\Text{}
\MultilineTextField{Kringel}
\Text{}
\end{ShortExample}

Auch hier gibt es wieder die Variante mit Stern für volle Breite:

\begin{ShortExample}{multilinetextfieldstar}{breites mehrzeiliges Textfeld}
%%% FIXME bug in preview (works in doc)
\Text{}
\MultilineTextField*[2cm]{Kringel}
\Text{}
\end{ShortExample}

\paragraph{Spezialfälle}  Unterschriften sollen üblicherweise händisch gesetzt
werden, hierfür gibt es daher ein Feld was nur ein "falsches" Formularfeld ist.

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

Ebenfalls gibt es ein etwas größeres Feld für Notizen oder Vermerke.

\begin{ShortExample}{notes}{großes Feld}
%%% FIXME bug in preview (works in doc)
\Notes
\Text{}
\end{ShortExample}

Auch hier kann optional das Label geändert werden.

\begin{ShortExample}{notesopt}{großes Feld}
%%% FIXME bug in preview (works in doc)
\Notes[Platz zum Malen]
\Text{}
\end{ShortExample}

\subsubsection{Checkboxen}

\paragraph{Normale Verwendung}  Gibt es eigentlich nicht viel dazu zu sagen --
\texttt{\textbackslash 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}

Für Freitextfelder als "Sonstige:" gibt es
\texttt{\textbackslash 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}

\goodbreak

\paragraph{Spezielle Zwecke}

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} \texttt{\{\}} oder
\texttt{\textbackslash}-\nobreak Leerzeichen 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}

\subsection{Struktur}



% Environment: Indented {O{}}
% \RuleSection {m}
% \Rule {}

\subsubsection{"klassische" Struktur}

% \Section {m}
% \Subsection {m}

\subsubsection{mehrspaltige Bereiche}

% \TwoColumns {+m +m}
% \ThreeColumns {+m +m +m}
% \FiveColumns {+m +m +m +m +m}

\subsection{Hervorhebung}

% \details {m}
% \ul {m}

\end{document}