% ====================================================================== % introduction.tex % Copyright (c) Markus Kohm, 2001-2019 % % This file is part of the LaTeX2e KOMA-Script bundle. % % This work may be distributed and/or modified under the conditions of % the LaTeX Project Public License, version 1.3c of the license. % The latest version of this license is in % http://www.latex-project.org/lppl.txt % and version 1.3c or later is part of all distributions of LaTeX % version 2005/12/01 or later and of this work. % % This work has the LPPL maintenance status "author-maintained". % % The Current Maintainer and author of this work is Markus Kohm. % % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % introduction.tex % Copyright (c) Markus Kohm, 2001-2019 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. % Die neuste Version dieser Lizenz ist % http://www.latex-project.org/lppl.txt % und Version 1.3c ist Teil aller Verteilungen von LaTeX % Version 2005/12/01 oder spaeter und dieses Werks. % % Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" % (allein durch den Autor verwaltet). % % Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. % % Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. % ====================================================================== % % Introduction of the KOMA-Script guide % Maintained by Markus Kohm % % ---------------------------------------------------------------------- % % Einleitung der KOMA-Script-Anleitung % Verwaltet von Markus Kohm % % ====================================================================== \KOMAProvidesFile{introduction.tex} [$Date: 2019-10-21 10:41:13 +0200 (Mon, 21 Oct 2019) $ KOMA-Script guide introduction] \translator{Kevin Pfeiffer\and Gernot Hassenpflug\and Krickette Murabayashi\and Markus Kohm\and Karl Hagen} % Date of the translated German file: 2019-10-21 \chapter{Introduction} \labelbase{introduction} This chapter contains, among other things, important information about the structure of the manual and the history of {\KOMAScript}, which begins years before the first version. You will also find information on how to install {\KOMAScript} and what to do if you encounter errors. \section{Preface}\seclabel{preface} {\KOMAScript} is very complex. This is due to the fact that it consists of not just a single class or a single package but a bundle of many classes and packages. Although the classes are designed as counterparts to the standard classes, that does not mean they provide only the commands, environments, and settings of the standard classes, or that they imitate their appearance. The capabilities of {\KOMAScript} sometimes far surpass those of the standard classes. Some of them should be considered extensions to the basic capabilities of the \LaTeX{} kernel. The foregoing means that the documentation of {\KOMAScript} has to be extensive. In addition, {\KOMAScript} is not normally taught. That means there are no teachers who know their students and can therefore choose the teaching materials and adapt them accordingly. It would be easy to write documentation for a specific audience. The difficulty facing the author, however, is that the manual must serve all potential audiences. I have tried to create a guide that is equally suitable for the computer scientist and the fishmonger's secretary. I have tried, although this is actually an impossible task. The result is numerous compromises, and I would ask you to take this issue into account if you have any complaints or suggestions to help improve the current situation. Despite the length of this manual, I would ask you to consult the documentation first in case you have problems. You should start by referring to the multi-part index at the end of this document. In addition to this manual, documentation includes all the text documents that are part of the bundle. See \File{manifest.tex} for a complete list. \section{Structure of the Guide}\seclabel{structure} This manual is divided into several parts: There is a section for average users, one for advanced users and experts, and an appendix with further information and examples for those who want to understand {\KOMAScript} thoroughly. \autoref{part:forAuthors} is intended for all {\KOMAScript} users. This means that some information in this section is directed at newcomers to \LaTeX. In particular, this part contains many examples that are intended to clarify the explanations. Do not hesitate to try these examples yourself and discover how {\KOMAScript} works by modifying them. That said, the {\KOMAScript} user guide is not intended to be a {\LaTeX} primer. Those new to {\LaTeX} should look at \emph{The Not So Short Introduction to {\LaTeXe}} \cite{lshort} or \emph{{\LaTeXe} for Authors} \cite{latex:usrguide} or a {\LaTeX} reference book. You will also find useful information in the many {\LaTeX} FAQs, including the \emph{{\TeX} Frequently Asked Questions on the Web} \cite{UK:FAQ}. Although the length of the \emph{{\TeX} Frequently Asked Questions on the Web} is considerable, you should get at least a rough overview of it and consult it in case you have problems, as well as this \iffree{guide}{book}. \autoref{part:forExperts} is intended for advanced {\KOMAScript} users, those who are already familiar with \LaTeX{} or who have been working with {\KOMAScript} for a while and want to understand more about how {\KOMAScript} works, how it interacts with other packages, and how to perform more specialized tasks with it. For this purpose, we return to some aspects of the class descriptions from \autoref{part:forAuthors} and explain them in more detail. In addition we document some commands that are particularly intended for advanced users and experts. This is supplemented by the documentation of packages that are normally hidden from the user, insofar as they do their work beneath the surface of the classes and user packages. These packages are specifically designed to be used by authors of classes and packages. The appendix\iffree{, which can only be found in the German book version,}{} contains information beyond that which is covered in \autoref{part:forAuthors} and \autoref{part:forExperts}. Advanced users will find background information on issues of typography to give them a basis for their own decisions. In addition, the appendix provides examples for aspiring package authors. These examples are not intended simply to be copied. Rather, they provide information about planning and implementing projects, as well as some basic \LaTeX{} commands for package authors. The guide's layout should help you read only those parts that are actually of interest. Each class and package typically has its own chapter. Cross-references to another chapter are thus usually also references to another part of the overall package. However, since the three main classes (\Class{scrbook}, \Class{scrrprt}, and \Class{scrartcl}) largely agree, they are introduced together in \autoref{cha:maincls}. Differences between the classes, e.\,g., for something that only affects the class \Class{scrartcl}\OnlyAt{\Class{scrartcl}}, are clearly highlighted in the margin, as shown here with \Class{scrartcl}. \begin{Explain} The primary documentation for {\KOMAScript} is in German and has been translated for your convenience; like most of the {\LaTeX} world, its commands, environments, options, etc., are in English. In a few cases, the name of a command may sound a little strange, but even so, we hope and believe that with the help of this guide, {\KOMAScript} will be usable and useful to you. \end{Explain} At this point you should know enough to understand the guide. It might, however, still be worth reading the rest of this chapter. \section{History of {\KOMAScript}}\seclabel{history} %\begin{Explain} In the early 1990s, Frank Neukam needed a method to publish an instructor's lecture notes. At that time {\LaTeX} was {\LaTeX}2.09 and there was no distinction between classes and packages\,---\,there were only \emph{styles}. Frank felt that the standard document styles were not good enough for his work; he wanted additional commands and environments. At the same time he was interested in typography and, after reading Tschichold's \emph{Ausgew\"ahlte Aufs\"atze \"uber Fragen der Gestalt des Buches und der Typographie} (Selected Articles on the Problems of Book Design and Typography) \cite{JTsch87}, he decided to write his own document style\,---\,and not just a one-time solution to his lecture notes, but an entire style family, one specifically designed for European and German typography. Thus {\Script} was born. Markus Kohm, the developer of {\KOMAScript}, came across {\Script} in December 1992 and added an option to use the A5 paper format. At that time neither the standard style nor {\Script} provided support for A5 paper. Therefore it did not take long until Markus made the first changes to {\Script}. This and other changes were then incorporated into {\ScriptII}, released by Frank in December 1993. In mid-1994, {\LaTeXe} became available and brought with it many changes. Users of {\ScriptII} were faced with either limiting their usage to {\LaTeXe}'s compatibility mode or giving up {\Script} altogether. This situation led Markus to put together a new {\LaTeXe} package, released on 7~July 1994 as {\KOMAScript}. A few months later, Frank declared {\KOMAScript} to be the official successor to {\Script}. {\KOMAScript} originally provided no \emph{letter} class, but this deficiency was soon remedied by Axel Kielhorn, and the result became part of {\KOMAScript} in December 1994. Axel also wrote the first true German-language user guide, which was followed by an English-language guide by Werner Lemberg. Since then much time has passed. {\LaTeX} has changed in only minor ways, but the {\LaTeX} landscape has changed a great deal; many new packages and classes are now available and {\KOMAScript} itself has grown far beyond what it was in 1994. The initial goal was to provide good {\LaTeX} classes for German-language authors, but today its primary purpose is to provide more-flexible alternatives to the standard classes. {\KOMAScript}'s success has led to e-mail from users all over the world, and this has led to many new macros\,---\,all needing documentation; hence this ``small guide.'' %\end{Explain} \section{Special Thanks} \seclabel{thanks} Acknowledgements in the introduction? No, the proper acknowledgements can be found in the addendum. My comments here are not intended for the authors of this guide\,---\,and those thanks should rightly come from you, the reader, anyhow. I, the author of {\KOMAScript}, would like to extend my personal thanks to Frank Neukam. Without his {\Script} family, {\KOMAScript} would not have come about. I am indebted to the many persons who have contributed to {\KOMAScript}, but with their indulgence, I would like to specifically mention Jens-Uwe Morawski and Torsten Kr\"uger. The English translation of the guide is, among many other things, due to Jens's untiring commitment. Torsten was the best beta-tester I ever had. His work has particularly enhanced the usability of \Class{scrlttr2} and \Class{scrpage2}. Many thanks to all who encouraged me to go on, to make things better and less error-prone, or to implement additional features. Special thanks go as well to the founders and members of DANTE, Deutschsprachige Anwendervereinigung {\TeX}~e.V\kern-.18em, (the German-Language {\TeX} User Group). Without the DANTE server, {\KOMAScript} could not have been released and distributed. Thanks as well to everybody on the {\TeX} newsgroups and mailing lists who answer questions and have helped me provide support for {\KOMAScript}. My thanks also go to all those who have always encouraged me to go further and to implement this or that feature better, with fewer flaws, or simply as an extension. I would also like to thank the very generous donor who has given me the most significant amount of money I have ever been paid for the work done so far on \KOMAScript{}. \section{Legal Notes} \seclabel{legal} {\KOMAScript} is released under the {\LaTeX} Project Public License. You will find it in the file \File{lppl.txt}. An unofficial German-language translation is also available in \File{lppl-de.txt} and is valid for all German-speaking countries. \iffree{This document and the {\KOMAScript} bundle are provided ``as is'' and without warranty of any kind.}% {Please note: the printed version of this guide is not free under the conditions of the {\LaTeX} Project Public Licence. If you need a free version of this guide, use the version that is provided as part of the {\KOMAScript} bundle.} \section{Installation} \seclabel{installation} The three most important \TeX{} distributions, Mac\TeX, MiK\TeX, and \TeX{}~Live, make {\KOMAScript} available through their package management software. You should install and update {\KOMAScript} using these tools, if possible. Manual installation without using the package managers is described in the file \File{INSTALL.txt}, which is part of every {\KOMAScript} distribution. You should also read the documentation that comes with the {\TeX} distribution you are using. \section{Bug Reports and Other Requests} \seclabel{errors} If you think you have found an error in the documentation or a bug in one of the {\KOMAScript} classes, packages, or another part of {\KOMAScript}, please do the following: First check on CTAN to see if a newer version of {\KOMAScript} has been released. If a newer version is available, install this new version and check if the problem persists. If the bug still occurs and your installation is fully up to date, please provide a short {\LaTeX} file that demonstrates the problem. Such a file is known as a minimal working example (MWE). You should include only minimal text and use only the packages and definitions essential to demonstrate the problem. Avoid using any unusual packages as much as possible. By preparing such an example it often becomes clear whether the problem is truly a {\KOMAScript} bug or caused by something else. To check if another package or class is actually causing the problem, you can also test your example with the corresponding standard class instead of a {\KOMAScript} class. If your problem still occurs, you should address your error report to the author of the appropriate package than to the author of {\KOMAScript}. Finally, you should carefully review the instructions for the appropriate package, classes, and {\KOMAScript} component. A solution to your problem may already exist, in which case an error report is unnecessary. If you think you have found a previously unreported error, or if for some other reason you need to contact the author of {\KOMAScript}, don't forget the following: \begin{itemize} \item Does the problem also occur if a standard class is used instead of a {\KOMAScript} class? In this case, the error is most likely not with {\KOMAScript}, and it makes more sense to ask your question in a public forum, a mailing list, or Usenet. \item Which {\KOMAScript} version do you use? For related information, see the \File{log} file of the \LaTeX{} run of any document that uses a {\KOMAScript} class. \item Which operating system and which \TeX{} distribution do you use? This information might seem rather superfluous for a system-independent package like {\KOMAScript} or {\LaTeX}, but time and again they have certainly been shown to play a role. \item What exactly is the problem or the error? Describe the problem. It's better to be too detailed than too short. Often it makes sense to explain the background. \item What does a minimal working example look like? You can easily create one by commenting out content and packages from the document step by step. The result is a document that only contains the packages and parts necessary to reproduce the problem. In addition, all loaded images should be replaced by \Macro{rule} statements of the appropriate size. Before sending your MWE,remove the commented-out parts, insert the command \Macro{listfiles} in the preamble, and perform another {\LaTeX} run. At the end of the \File{log} file, you will see an overview of the packages used. Add the MWE and the log file to the end of your description of the problem. \end{itemize} Do not send packages, PDF, PS, or DVI files. If the entire issue or bug description, including the minimal example and the \File{log} file is larger than a few tens of kilobytes, you're likely doing something wrong. If you've followed all these steps, please send your {\KOMAScript} (only) bug report to \href{mailto:komascript@gmx.info}{komascript@gmx.info}. If you want to ask your question in a Usenet group, mailing list, or Internet forum, you should follow the procedures mentioned above and include a minimal working example as part of your question, but usually you don't need to provide the \File{log}-file. Instead, just add the list of packages and package versions from the \File{log}-file and, if your MWE compiles with errors, you should quote those messages from the \File{log} file. Please note that default settings which are not typographically optimal do not represent errors. For reasons of compatibility, defaults are preserved whenever possible in new versions of {\KOMAScript}. Furthermore, typographical best practices are partly a matter of language and culture, and so the default settings of {\KOMAScript} are necessarily a compromise. \section{Additional Information} \seclabel{moreinfos} Once you become familiar with {\KOMAScript}, you may want examples that show how to accomplish more difficult tasks. Such examples go beyond the basic instructional scope of this manual and so are not included. However, you will find more examples on the website of the {\KOMAScript} Documentation Project \cite{homepage}. These examples are designed for advanced {\LaTeX} users and are not particularly suitable for beginners. The main language of the site is German, but English is also welcome. \endinput %%% Local Variables: %%% mode: latex %%% coding: us-ascii %%% TeX-master: "../guide.tex" %%% End: