diff options
Diffstat (limited to 'macros/latex/contrib/koma-script/doc/introduction-en.tex')
-rw-r--r-- | macros/latex/contrib/koma-script/doc/introduction-en.tex | 315 |
1 files changed, 315 insertions, 0 deletions
diff --git a/macros/latex/contrib/koma-script/doc/introduction-en.tex b/macros/latex/contrib/koma-script/doc/introduction-en.tex new file mode 100644 index 0000000000..d840cfe64f --- /dev/null +++ b/macros/latex/contrib/koma-script/doc/introduction-en.tex @@ -0,0 +1,315 @@ +% ====================================================================== +% introduction-en.tex +% Copyright (c) Markus Kohm, 2001-2022 +% +% 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.md. +% ====================================================================== +% +% Introduction of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{introduction-en.tex} + [$Date: 2022-06-05 12:40:11 +0200 (So, 05. Jun 2022) $ + KOMA-Script guide introduction] +\translator{Kevin Pfeiffer\and Gernot Hassenpflug\and + Krickette Murabayashi\and Markus Kohm\and Karl Hagen} + +\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{Preliminary Note}\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: +\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 If you do not use an up-to-date \KOMAScript{} version, please consider + to install a new \KOMAScript{} release. If the problem does not occur with + an updated \KOMAScript, you've already found a solution. +\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 or by an example image from + package \Package{mwe} \cite{package:mwe}. Before sending your minimal + working example,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 minimal working example 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 create a new ticket in the +\KOMAScript{} ticket system at \url{https://sf.net/p/koma-script/tickets}. If +you are not able to do so, you may alternatively 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 minimal working example +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 +%%% TeX-master: "scrguide-en.tex" +%%% coding: utf-8 +%%% ispell-local-dictionary: "en_GB" +%%% eval: (flyspell-mode 1) +%%% End: |