projekt kivitendo

 <sect2 id="Aufbau des marei Vorlagensatzes">

  <title>Aufbau des marei Vorlagensatzes</title>

  <sect3 id="Quickstart – Wo kann was angepasst werden?">

    <title>Quickstart – Wo kann was angepasst werden?</title>

    <para>In keinem Fall sollten Dateien mit der Endung <filename>*.cls</filename> oder <filename>*.sty</filename> geändert werden. Durch Änderungen an diesen Dateien verhindert man Updates auf neuer Versionen.

    Zwar kopiert kivitendo die Datei und bearbeitet diese beim Update nicht. Allerdings sind sämtliche Änderungen über die Konfigurationsdateien möglich und erhöhen die Wartbarkeit.</para>

    <itemizedlist>

      <listitem>

        <para><filename>insettings.tex</filename> :</para>

      </listitem>

        <itemizedlist>

        <listitem>

          <para>Pfad zu Angaben über Mandant*innen (default: firma)</para>

        </listitem>

        <listitem>

          <para>Logo/Briefpapier, falls für alle Mandant*innen in gleicher Struktur. Sonst in der <filename>ident.tex</filename>.</para>

        </listitem>

        <listitem>

          <para>Layout der Kopf/Fußzeile</para>

        </listitem>

        <listitem>

          <para>innerhalb dieser Datei werden auch die folgenden Dateien geladen:</para>

        </listitem>

        <listitem>

          <para><filename>firma/ident.tex</filename> Mandant*innenspezifische Konfiguration, Adressdaten</para>

        </listitem>

        <listitem>

          <para><filename>firma/$währungskürzel_account.tex</filename></para>

        </listitem>

        </itemizedlist>

      <listitem>

        <para>Sprache/Übersetzungen.\\Es muss mindestens eine Sprache angelegt werden!</para>

      </listitem>

        <programlisting>

        \begin{description}

        \item[deutsch.tex] Textschnipsel für Deutsch\\

                              Dafür eine Sprache mit Vorlagenkürzel DE anlegen

        \item[english.tex] Textschnipsel für Englisch\\

                              Dafür eine Sprache mit Vorlagenkürzel EN anlegen

        \end{description}

        </programlisting>

    </itemizedlist>

    <para>Alle dokumententypspezifischen Einstellungen müssen in der jeweiligen Template-Datei modifiziert werden.</para>

  </sect3>

  <sect3 id="Aufbau">

    <title>Aufbau</title>

    <para>Die Grundstruktur besteht je Dokumententyp aus einer Basisdatei und verschiedenen Setup-Dateien.</para>

    <para>Die Basis wurde so überarbeitet, dass Dokumente nun generell auf

    der Dokumentenklasse <filename>scrartcl.cls</filename> basieren und

    das Paket <filename>kiviletter.sty</filename> benutzen.</para>

    <para>Mandant*innenspezifische Konfiguration findet sich in der Datei <filename>insettings.tex</filename> und

    dem Ordner eines spezifischen Mandant*innen (default=*firma/*).</para>

    <!-- <sect2 id="Struktur der Basisdatei (je Dokumententyp eine)">

    <title>Struktur der Basisdatei (je Dokumententyp eine)</title>

      <orderedlist>

        <listitem>

        <para>Dokumentenklasse</para>

        </listitem>

        <listitem>

        <para><filename>kiviletter.sty</filename></para>

        </listitem>

        <listitem>

        <para>Einstellungen, die über Variablen gesetzt werden: Mandant, Währung, Sprache</para>

        </listitem>

        <listitem>

        <para><filename>insettings.tex</filename> wird geladen. Anteil der spezifischen Anpassungen, die von den Variablen unter 2. abhängig sind.

        Geladen werden darin die Dateien:</para>

        </listitem>

        <itemizedlist>

          <listitem>

              <para>Sprache: lädt die entsprechende Sprachdatei <filename>deutsch.tex</filename> (DE) oder  <filename>englisch.tex</filename> (EN) und setzt die babel Optionen.

              Die Datei enthält Übersetzungen von Einzelbegriffen und Textbausteinen.</para>

            </listitem>

          <listitem>

              <para>Lädt die Konfigurationsdatei, ohne spezielle Mandant*innen ist der Suchpfad zur Konfiguration der Unterordner <filename>firma/</filename></para>

            </listitem>

            <listitem>

            <para>Lädt die Datei <filename>ident.tex</filename> welche Mandant*innenspezifische Anpassungen enthält.</para>

            </listitem>

        </itemizedlist>

      </orderedlist>

    -->

  </sect3>

  <sect3 id="Mandant*innen / Firma">

    <title>Mandant*innen / Firma</title>

    <para>Um gleiche Vorlagen für verschiedene Firmen verwenden zu können, wird je

    nach dem Wert der Kivitendo-Variablen \kivivar{kivicompany} ein

    Firmenverzeichnis ausgewählt (siehe <filename>insettings.tex</filename>), in dem Briefkopf,

    Identitäten und Währungs-/Kontoeinstellungen hinterlegt sind.

    \kivivar{kivicompany} enthält den Namen des verwendeten Mandant*innendaten.

    Ist kein Firmenname eingetragen, so wird das

    generische Unterverzeichnis *firma* verwendet.</para>

  </sect3>

  <sect3 id="Identitäten">

    <title>Identitäten</title>

    <para>In jedem Firmen-Unterverzeichnis soll eine Datei <filename>ident.tex</filename>

    vorhanden sein, die mit |\newcommand| Werte für |\telefon|, |\fax|,

    |\firma|, |\strasse|, |\ort|, |\ustid|, |\email| und |\homepage| definiert.</para>

  </sect3>

  <sect3 id="Währungen/Konten">

    <title>Währungen/Konten</title>

    <para>Für jede Währung (siehe <filename>insettings.tex</filename>) soll eine Datei vorhanden

    sein, die das Währungssymbol (|\currency|) und folgende Angaben für

    ein Konto in dieser Währung enthält |\kontonummer|, |\bank|,

    |\bankleitzahl|, |\bic| und |\iban|.

    So kann in den Dokumenten je nach Währung ein anderes Konto

    angegeben werden.

    Nach demselben Schema können auch weitere, alternative Bankverbindungen

    angelegt werden, die dann in <filename>insettings.tex</filename> als Variable in der Fußzeile eingefügt werden.</para>

    <para>Als Fallback (falls kivitendo keine Währung an das Druckvorlagen-System übergibt)

    ist Euro eingestellt. Dies lässt sich in der <filename>insettings.tex</filename> über das optionale Argument

    von |\setupCurrencyConfig| anpassen, z.B.</para>

    <programlisting>

    \setupCurrencyConfig[chf]{\identpath}{\lxcurrency}

    </programlisting>

    <para>für Schweizer Franken als Standardwährung.</para>

  </sect3>

  <sect3 id="Briefbogen/Logos">

    <title>Briefbogen/Logos</title>

    <para>Eine Hintergrundgrafik oder ein Logo kann in Abhängigkeit vom

    Medium (z.B. nur beim Verschicken mit E-Mail) eingebunden

    werden.</para>

    <para>Desweiteren sind (auskommentierte) Beispiele enthalten für eine

    Grafik als Briefkopf, nur ein Logo, oder ein komplettes A4-PDF

    als Briefpapier.</para>

    <para>Absolute Positionierung innerhalb des Brief-Layouts ist über die entsprechende Dokumentation des scrlayer-Paketes möglich.

    Da die Voreinstellungen bereits einige Sonderfälle automatisch berücksichtigen ist mit den Anpassungen Vorsicht geboten.

    Sämtliche Einstellungen sollten jedoch außerhalb der *.sty-Dateien vorgenommen werden.

    Anpassungen der <filename>insettings.tex</filename> betreffen hierbei alle Mandant*innen. Spezifischere Einstellungen sind über die zugehörige Konfigurationsdatei (<filename>ident.tex</filename>) möglich.

    In diesem Fall kann zum Ende der insettings eine weitere Konfigurationsdatei über die Verwendung von |\identpath| geladen werden. Ein Beispiel ist in der <filename>insettings.tex</filename> enthalten.</para>

  </sect3>

  <sect3 id="Fußzeile">

    <title>Fußzeile</title>

    <para>Die Tabelle im Fuß verwendet die Angaben aus <filename>firma/ident.tex</filename> und

    *firma/<filename>\_account.tex</filename>. Ihre Struktur wird in der <filename>insettings.tex</filename> definiert.

    Sie kann anschließend auch Mandant*innenspezifisch überschrieben werden.</para>

  </sect3>

  <sect3 id="Seitenstil/Basislayout">

    <title>Seitenstil/Basislayout</title>

    <para>Das Seitenlayout wird über \pck{scrlayer-scrpage} bestimmt. Die ausführliche Dokumentation findet sich in \cite{scrguide}.

    Es existieren in der Datei <filename>insettings.tex</filename> einige Hinweise zu den Anpassungen. Die Basiskonfiguration ist ebenfalls dort eingetragen.</para>

    <para>Neben den in Abschnitt \ref{sec:options}  beschriebenen Optionen zum Abschalten der Fußzeile kann

    der Inhalt der Fußzeile über die \pck{scrlayer-scrpage} Makros, wie</para>

    <programlisting>

      \cfoot[|\meta{Inhalt auf der ersten Briefseite}|]{|\meta{Inhalt auf folgenden Briefseiten}|}

    </programlisting>

    <para>geändert werden.</para>

    <para>Die Kopfzeile unterscheidet sich von Dokumententyp zu Dokumententyp leicht, da diese über Datenbankvariablen befüllt wird.

    Hierfür wird das Makro |\ourhead| in der <filename>insettings.tex</filename> definiert.</para>

    <programlisting>

      \DescribeMacro{\ourhead}\marg{Bezeichner}\marg{Eintrag}\marg{Titel}\marg{Nummer}\marg{Datum}

    </programlisting>

    <para>Diese Definition kann ebenfalls über die <filename>insettings.tex</filename> angepasst oder auch nachträglich überschrieben werden:</para>

    <programlisting>

      \newcommand{\ourhead}[5] {%

        \chead{%

          \makebox[\textwidth]{%

            \Ifstr{#1}{}{}{#1: #2 \hspace{0.7cm}}%

            #3%

            \Ifstr{#4}{}{}{~\nr: #4}%

            \Ifstr{#5}{}{}{\vom ~ #5}%

            \hspace{0.7cm} - \seite ~ \thepage/\letterlastpage  ~-%

          }%

        }%

      }

    </programlisting>

    <para>In der Standard-Einstellung sieht eine Kopfzeile mit obigen Aufruf dann folgendermaßen aus:</para>

    <programlisting>

      \newcommand{\ourhead}[5] {%

          \makebox[\textwidth]{%

            \Ifstr{#1}{}{}{#1: #2 \hspace{0.7cm}}%

            #3%

            \Ifstr{#4}{}{}{~\nr: #4}%

            \Ifstr{#5}{}{}{\vom ~ #5}%

            \hspace{0.7cm} - \seite ~ \thepage/\letterlastpage  ~-%

          }%

      }

      \begingroup

      \def\letterlastpage{50}

      \ourhead{arg1}{arg2}{arg3}{arg4}{arg5}

      \smallskip

      Erzeugt mit dem Aufruf

      \ourhead{arg1}{arg2}{arg3}{arg4}{arg5}

      \endgroup

    </programlisting>

  </sect3>

  <sect3 id="Absenderergänzung">

    <title>Absenderergänzung</title>

    <para>Die Absenderergänzung wird über die Variable |location| in der |kiviletter.sty| folgendermaßen belegt:</para>

    <programlisting>

      \setkomavar{location}{

        \Ifkomavarempty{transaction}{}{{

              \usekomafont{transaction}

              \usekomavar{transaction}

            }

        }

        \par

        \medskip

        \parbox{\useplength{locwidth}}{

          \locationentry{date}

          \locationentry{myref}

          \locationentry{customer}

          \locationentry{yourref}

          \locationentry{delivery}

          \locationentry{quote}

          \locationentry{orderID}

          \locationentry{projectID}

          \locationentry{taxpoint}

          \locationentry[\ansprechpartner]{fromname}

          \locationentry{fromphone}

          \locationentry*{fromemail}

        }

      }

    </programlisting>

    <para>Um die Reihenfolge der Variablenausgabe zu verändern, kann diese Definition als Basis in

    die <filename>insettings.tex</filename> oder <filename>ident.tex</filename> (Falls nur für eine Firma) kopiert und dort entsprechend modifiziert werden.</para>

    <para>Das Vorgehen geht für alle vorbelegten Variablen analog.</para>

  </sect3>

</sect2>

<sect2 id="Allgemeine TeXnische Hinweise">

  <title>Allgemeine TeXnische Hinweise</title>

  <sect3 id="Änderung der Basisschriftart">

    <title>Änderung der Basisschriftart</title>

    <para>\LaTeX{} kann grundsätzlich beliebige Schriftarten verwenden. Hierfür sollte allerdings immer darauf geachtet werden,

    dass die Lizenz der Schriftart das einbetten von Glyphen erlaubt. Dies liegt in der Verantwortung der Anwender*innen.

    Darüber hinaus ist wichtig, welches Kompilierungsprogramm verwendet werden muss. Um TrueType oder OpenType Schriftarten

    zu nutzen sollte |lualatex| verwendet werden. Bei Type1 Schriftarten, die speziell für \LaTeX{} installiert wurden, ist pdfLaTeX möglich.

    Da man heutzutage nur noch moderne Schriftformate Verwenden sollte, wird hier lediglich die Variante für |lualatex| aufgelistet.</para>

    <para>Die Konfiguration läuft hierbei über das \pck{fontspec} Paket (Doku siehe \cite{fontspec}).

    Dann hängt es davon ab, ob die Basisschriftart eine Serifenschriftart ist oder nicht.

    In jedem Fall wird die Änderung entweder in der <filename>insettings.tex</filename>, sofern sie für alle

    Mandant*innen gelten soll oder in der Mantant*innenspezifischen Konfigurationsdatei gsesetzt.</para>

    <sect4>

      <title>Änderung, falls es ein Schriftpaket gibt</title>

      <para>Wenn möglich sollte die Schriftart über ein entsprechendes Konfigurationspaket gesetzt werden.

        Ob ein solches existiert kann man sehr leicht über eine Suche nach dem Namen unter \url{ctan.org} herausfinden.</para>

    </sect4>

    <sect4>

      <title>Änderung der Basisschriftart auf eine Schriftart mit Serifen</title>

    <programlisting>

      \setmainfont{|\meta{Name der Schriftart, z.B. SourceSerifPro}|}

    </programlisting>

    </sect4>

    <sect4>

      <title>Änderung der Basisschriftart auf eine Schriftart ohne Serifen</title>

    <programlisting>

      \setsansfont{|\meta{Name der Schriftart, z.B. SourceSansPro}|}

      \renewcommand*{\familydefault}{\sfdefault}

    </programlisting>

    </sect4>

  </sect3>

  <sect3 id="Unterscheidungen durch String-Vergleich">

    <title>Unterscheidungen durch String-Vergleich</title>

    <programlisting>

    \Ifstr{\lxmedia}{printer}{Falls gedruckt werden soll} {sonst}

    </programlisting>

  </sect3>

</sect2>