quality management

[johannesbottcher]

Wie hoch schätzt du die Qualität deiner Vorlage ein?

[StefanMacke]

Was genau meinst du damit? Ich denke, die Vorlage ist (gemessen an den Reaktionen, die ich bisher bekommen habe) recht gut gelungen. Die Inhalte sind sinnvoll auf Dateien verteilt, alle Befehle sind kommentiert, viele Inhaltselemente sind als Beispiel enthalten. Die Vorlage ist natürlich schon ein paar Jahre alt, also wenn du Verbesserungsvorschläge hast, dann immer her damit!

[moewew]

Ich würde gerne ein paar Kleinigkeiten teilen, die mir bei der Betrachtung des Quellcodes aufgefallen sind.

Zunächst ist die Vorlage über viele Dateien verteilt. Das kann einen interessierten Anfänger natürlich etwas verwirren, wenn man fünf verschiedene Dateien durchsuchen muss, allerdings bleiben die einzelnen Dateien so thematisch getrennt und erfreulich kurz.

Befehle.tex

Die Abkürzungsbefehle bringen jeweils ihr eigenes Leerzeichen am Ende mit (\). Das finde ich aus zwei Gründen bedenklich.
Zunächst könnte es ja sein, dass ich nach einer Abkürzung gleich ein Satzzeichen, das ohne Leerraum angeschlossen werden muss, setzten möchte. Das funktioniert so nicht.
Zum zweiten, und das ist der für mich entscheidende Grund, führt es zu einer Inkonsistenz, die besonders LaTeX-Anfänger verwirren kann. Normalerweise verschlucken in Buchstaben endende Kontrollsequenzen die nachfolgenden Leerzeichen; die Abkürzungsbefehle aus Befehle.tex scheinen dies nicht zu tun. Dies kann dazu führen, dass Anfänger erwarten, dass alle Befehle "die Leerzeichen erhalten". Besser fände ich es, Anfänger gleich auf \foo{} und \foo\ zu stoßen, als sie es später durch Zufall erfahren zu lassen.

\newcommand{\abbildung}[1]{Abbildung~\ref{fig:#1}} könnte man gleich durch die Nutzung des Pakets cleveref unnötig machen. Das Paket stellt den Befehl \cref bereit, der das richtige Präfix automatisch hinzufügt. Siehe auch TeX.SX: Cross-reference packages: which to use, which conflict?.

\newcommand{\bs}{$\backslash$} kann im Mathematikmodus für Probleme sorgen. Aber es gibt ja auch \textbackslash. Ich würde eher davon abraten, den Mathematikmodus in ein Makro fest einzuprogrammieren (es mag aber legitime Ausnahmen geben).

\newcommand{\Zitat}[2][\empty]{\ifthenelse{\equal{#1}{\empty}}{\citep{#2}}{\citep[#1]{#2}}} halte ich für unnötig. Entweder Du zeigst den Benutzern gleich die verfügbaren \cite-Befehle oder Du machst den Alias kürzer mit \newcommand{\Zitat}{\citep} (bei biblatex würde das auch die Prenote-Fähigkeit erhalten; Deine Definition würde weitere optionale Argumente, wie biblatex sie hat, nicht unterstützen).

\newcommand{\Autor}[1]{\AutorName{\citeauthor{#1}}} sieht man vom Namen nicht an, was es tut. Ich hätte niemals erwartet, dass es ein citekey als Argument benötigt. Mit biblatex sollte es möglich sein, das Autornamensformat so anzupassen, dass das nicht notwendig ist \AutorName auf \citeauthor loszulassen.

Packages.tex

Ich meine mitgenommen zu haben, dass das Paket scrpage2 inzwischen veraltet ist und stattdessen scrlayer-scrpage genutzt werden sollte.

Ich finde es etwas unglücklich, die Zeichenkodierung in einer Extradatei zu verstecken, diese sollte der Nutzer meiner Meinung nach direkt in der Hauptdatei selbst leicht ändern können. (Am besten mit einem prominenten Kommentar dazu.) Außerdem würde ich ruhig UTF8 nutzen.

Das Paket textcomp sehe ich häufiger, habe es selbst noch nie benutzt, die CTAN-Seite sagt "obsolet" aber siehe auch Latest advice on the euro symbol, die sich nicht dagegen ausspricht.

\graphicspath{{Bilder/}} sollte vielleicht besser in einer Datei liegen, die für die direkte Inspektion und für Änderungen des Nutzers gedacht ist. Für mich ist Packages.tex eine Datei, die der User nicht verändern sollte, und vielleicht noch nicht einmal angesehen haben muss.

Statt amsfonts würde ich gleich amssymb laden. What does each AMS package do?

Du kannst auch darüber nachdenken, von dem etwas in die Jahre gekommenen natbib auf das sehr aktiv entwickelte und leichter anzupassende biblatex umzusteigen.

Zuletzt lädst Du noch das Paket xspace. Soweit ich sehen kann nutzt Du den Befehl \xpsace aber nirgendwo (die Suche hat nichts ausgegeben). Außerdem gibt es einige Diskussion über den Nutzen dieses Pakets Drawbacks of xspace, dort schreibt der Autor, dass das Paket fast aus einem Versehen heraus entstanden ist und endet mit "But personally I wouldn't recommend it."

Die Einstellungen für das listings-Paket sind etwas verstreut sowohl in Packages.tex als auch ein paar in Seitenstil.tex zu finden.

natdin.bst

Wenn die natdin.bst aus diesem Repository mit dem "Original" auf CTAN übereinstimmt, sehe ich keinen Grund, sie hier mitzugeben. Wenn sie verändert wurde, sollte sie unbedingt umbenannt werden und ein deutlich sichtbarer Hinweis angebracht werden.

Bibliographie.bib

Das Feld timestamp ist so eine Unsitte von den automatischen Literaturverwaltungsprogrammen. In einer Beispieldatei, die auch als Vorbild dienen soll, ist dieses Feld überflüssig. Ebenso wie das owner-Feld, das von allen Stilen, die ich so benutze geflissentlich ignoriert wird. Auch das file-Feld wird normalerweise ignoriert.

[moewew]

Die Anmerkung zu natdin.bst trifft genau so natürlich auch auf die im Ressourcen-Ordner residierenden Pakete chngcntr und floatflt zu.

AufzaehlungenTabellen.tex

Zu Tabellen kannst Du übrigens auch das wunderbare Paket booktabs laden. In der Dokumentation dazu wirst Du erfahren, dass vertikale Striche in Tabellen verpönt sind.

Da Du in Befehle.tex so schön semantische Befehle definiert hast, ist es ein bisschen ernüchternd, dass Du dann für die Beispiele für Tätigkeiten wieder \textit nutzt. (\textit sehe ich übrigens sehr wenig, ich nutze auch eher \emph wegen der Eigenschaften beim Schachteln.)

Eine \hline vor dem Label wie in

\caption{Elemente der Ereignisgesteuerten Prozesskette} \\
\hline
\label{tab:ElementeDerEreignisgesteuertenProzesskette}

finde ich auch verwirrend. Schreib das Label lieber direkt hinter die \caption oder gleich in die Caption mit rein Warum muss in einer table- oder figure-Umgebung \label nach \caption gesetzt werden?.

Es kann auch nicht verkehrt sein, \includegraphics in einer Gleitumgebung (figure) zu zeigen. Normalerweise würde ich vorschlagen, figure zu verwenden und es zu ertragen, dass LaTeX Gleitumgebungen verschiebt. Aber es kann auch Anwendungen geben, bei denen es sinnvoll ist, keine Gleitumgebung zu nutzen.

Statt der \itemd-Kombination gibt es die von der Idee ähnliche (nicht ganz gleich aussehende) description-Umgebung.

BPELAktivitaeten.tex

Hier sind irgendwie ein bisschen viele \smalls. Soweit ich das sehe sind die auch in gar keiner Gruppe und schalten sehr weitreichend die Größe um (vielleicht wird das nur durch ein kluges \include im Zaum gehalten).

ZitateReferenzen.tex

Statt "</code> und Co. würde ich das wunderbare Paket csquotes` empfehlen, damit können Anführungszeichen ganz einfach und angenehm gesetzt werden. Außerdem bietet es sehr intelligente Block-Zitat-Umgebungen an.

[johannesbottcher]

Jetzt hat @moewew natürlich bereits vieles gesagt, was ich auch gesagt (geschrieben) hätte.

Was mir noch auffällt: In einem normalen Dokument gliedern sich Titelseite und Abstract/Danksagung oder ähnliches mit ein, das bedeutet sie werden mitgezählt; auch wenn die Seitenzahl unter Umständen nicht ausgegeben wird. Dazu auch interessant: Welche Seitenzahl hat das Inhaltsverzeichnis?

Den changefont Befehl sieht man gerade im deutschsprachigen Support immer wieder. Wo kommt denn das nur her? usefont ist das zu nutzende Interface. Besser noch wären semantische Befehle/Schalter.

Das definieren von Befehlen wie \Datei und co finde ich sehr gut, leider nutzt du nicht durchgängig semantisches Markup. Das wurde ja aber bereits angesprochen.

Die globale Option DIV10 ist veraltet, und sollte durch DIV=10 ersetzt werden.

Die Option dvips -- egal ob global, bei hyperref oder graphicx -- macht maximal Schaden, aber nichts gutes.

Das Setzen von nomlabelwidth sollte erst mit Beginn des Dokumentes erfolgen (Warum ragt die Nomenklatur über den Rand?)

Das Paket hyperref sollte im Normalfall als letztes Paket geladen werden.

\large, \small und co sind Schalter und erwarten kein Argument. (Was ist an \Large{Text} falsch?)

Platzierungsparameter für Gleitumgebungen würde ich grundsätzlich erst am Schluss für den Feinschliff angeben. Nun ist das in einem Template natürlich so eine Sache. Leider scheinen sehr sehr viele Nutzer grundsätzlich [htbp] (oder sogar nur [h]) zu verwenden. Leider verstehen auch viele das Prinzip Gleitumgebung nicht.

[StefanMacke]

Wow, danke für die ganzen Hinweise. Da sind Sachen dabei, auf die ich nicht gekommen wäre. Es wird aber wohl einen Moment dauern, bis ich alles abgearbeitet habe. Vielen Dank für die Mühe!

[moewew]

Ähnliche Anmerkungen gelten auch für die https://github.com/StefanMacke/latex-vorlage-fiae/, dort wird aber xspace tatsächlich zum Einsatz gebracht, die Zeichencodierung ist UTF8 und wird im Hauptdokument gesetzt (die letzten beiden Punkte sind meiner Meinung nach gut, der erste eher nicht so, siehe oben).

Allerdings wird dort auch das Paket graphics geladen, was beim Laden von graphicx (wieder mit der dvips-Option, vor der Johannes gewarnt hatte) eigentlich unnötig ist: Packages: graphics vs graphicx.

Ferner weiß ich nicht, ob es den Effekt von \includegraphicstotab nicht etwas günstiger gibt.

[rgarcia89]

Wann kann mit einer aktualisierten Version gerechnet werden?
Würde Ihre Vorlage gerne für ein wissenschaftliche Arbeit nutzen.

[StefanMacke]

@rgarcia89 In nächster Zeit werde ich nicht dazu kommen. Aber du kannst die Anpassungen ja gerne selbst machen und mir einen Pull Request schicken. Oder du nutzt die Vorlage einfach so wie sie ist. Hat bei mir damals auch gereicht ;-)

[StefanMacke]

Meinst du die Option backref beim Paket hyperref? Die verlinkt die Quellen mit ihren Zitaten im Text.

Am 25. Februar 2016 14:36:58 MEZ, schrieb rgarcia89 notifications@github.com:

Servus Stefan, wie hast du es umgesetzt, dass im Literaturverzeichnis
der Index der jeweiligen Einträge angezeigt wird? Handelt es sich
hierbei um ein package oder hast du dafür ein Befehl umgeschrieben?

---

Reply to this email directly or view it on GitHub:
#1 (comment)

http://blog.macke.it
@StefanMacke