summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/koma-script/doc/introduction-en.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/koma-script/doc/introduction-en.tex')
-rw-r--r--macros/latex/contrib/koma-script/doc/introduction-en.tex315
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: