From 1610548529befd1cb7d72da00a3a889261436642 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 2 Apr 2018 21:16:13 +0000 Subject: koma-script (2apr18) git-svn-id: svn://tug.org/texlive/trunk@47249 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/koma-script/README | 404 +- .../texmf-dist/doc/latex/koma-script/manifest.txt | 2 +- .../texmf-dist/doc/latex/koma-script/scrguide.html | 1838 +++---- .../texmf-dist/doc/latex/koma-script/scrguide.pdf | Bin 3142588 -> 3142480 bytes .../texmf-dist/doc/latex/koma-script/scrguien.html | 1853 +++---- .../texmf-dist/doc/latex/koma-script/scrguien.pdf | Bin 2940370 -> 2991664 bytes .../texmf-dist/doc/latex/koma-script/scrhack.pdf | Bin 404334 -> 406935 bytes .../texmf-dist/doc/latex/koma-script/scrpage2.pdf | Bin 702645 -> 714231 bytes .../texmf-dist/doc/latex/koma-script/tocstyle.pdf | Bin 254904 -> 254904 bytes .../texmf-dist/source/latex/koma-script/ChangeLog | 2065 +++++++- .../source/latex/koma-script/doc/bin/genhtmlidx.pl | 6 +- .../latex/koma-script/doc/english/adrconvnote.tex | 44 +- .../latex/koma-script/doc/english/authorpart.tex | 38 +- .../doc/english/common-compatibility.tex | 190 +- .../koma-script/doc/english/common-dictum.tex | 192 +- .../koma-script/doc/english/common-draftmode.tex | 89 +- .../koma-script/doc/english/common-fontsize.tex | 175 +- .../koma-script/doc/english/common-footnotes.tex | 525 +- .../doc/english/common-headfootheight.tex | 137 +- .../doc/english/common-interleafpage.tex | 296 +- .../latex/koma-script/doc/english/common-lists.tex | 606 ++- .../koma-script/doc/english/common-marginpar.tex | 79 +- .../doc/english/common-oddorevenpage.tex | 80 +- .../koma-script/doc/english/common-options.tex | 260 +- .../doc/english/common-pagestylemanipulation.tex | 1086 ++-- .../koma-script/doc/english/common-parmarkup.tex | 209 +- .../koma-script/doc/english/common-textmarkup.tex | 612 ++- .../koma-script/doc/english/common-titles.tex | 608 ++- .../koma-script/doc/english/common-typearea.tex | 49 +- .../latex/koma-script/doc/english/expertpart.tex | 20 +- .../koma-script/doc/english/guide-english.tex | 70 +- .../source/latex/koma-script/doc/english/guide.tex | 10 +- .../latex/koma-script/doc/english/introduction.tex | 395 +- .../latex/koma-script/doc/english/japanlco.tex | 154 +- .../latex/koma-script/doc/english/linkalias.tex | 5 +- .../latex/koma-script/doc/english/preface.tex | 92 +- .../latex/koma-script/doc/english/scraddr.tex | 200 +- .../latex/koma-script/doc/english/scrbase.tex | 1673 +++--- .../doc/english/scrbookreportarticle-experts.tex | 1568 +++--- .../doc/english/scrbookreportarticle.tex | 5322 +++++++++++--------- .../latex/koma-script/doc/english/scrdatetime.tex | 346 +- .../latex/koma-script/doc/english/scrextend.tex | 162 +- .../latex/koma-script/doc/english/scrhack.tex | 330 +- .../latex/koma-script/doc/english/scrjura.tex | 978 ++-- .../koma-script/doc/english/scrjuraexample.tex | 141 +- .../doc/english/scrlayer-notecolumn-example.tex | 62 +- .../doc/english/scrlayer-notecolumn.tex | 904 ++-- .../doc/english/scrlayer-scrpage-experts.tex | 679 +-- .../koma-script/doc/english/scrlayer-scrpage.tex | 1271 ++--- .../latex/koma-script/doc/english/scrlayer.tex | 1911 +++---- .../latex/koma-script/doc/english/scrlfile.tex | 763 ++- .../koma-script/doc/english/scrlttr2-experts.tex | 2157 ++++---- .../latex/koma-script/doc/english/scrlttr2.tex | 3475 +++++++------ .../koma-script/doc/english/scrlttr2examples.dtx | 66 +- .../latex/koma-script/doc/english/scrwfile.tex | 314 +- .../latex/koma-script/doc/english/tocbasic.tex | 2479 ++++----- .../koma-script/doc/english/typearea-experts.tex | 232 +- .../latex/koma-script/doc/english/typearea.tex | 2232 ++++---- .../source/latex/koma-script/doc/guide.bib | 112 +- .../source/latex/koma-script/doc/guide.tex | 10 +- .../source/latex/koma-script/doc/linkalias.tex | 5 +- .../latex/koma-script/doc/ngerman/adrconvnote.tex | 8 +- .../latex/koma-script/doc/ngerman/authorpart.tex | 7 +- .../doc/ngerman/common-compatibility.tex | 81 +- .../koma-script/doc/ngerman/common-dictum.tex | 76 +- .../koma-script/doc/ngerman/common-draftmode.tex | 64 +- .../koma-script/doc/ngerman/common-fontsize.tex | 84 +- .../koma-script/doc/ngerman/common-footnotes.tex | 155 +- .../doc/ngerman/common-headfootheight.tex | 79 +- .../doc/ngerman/common-interleafpage.tex | 165 +- .../latex/koma-script/doc/ngerman/common-lists.tex | 191 +- .../koma-script/doc/ngerman/common-marginpar.tex | 19 +- .../doc/ngerman/common-oddorevenpage.tex | 10 +- .../koma-script/doc/ngerman/common-options.tex | 172 +- .../doc/ngerman/common-pagestylemanipulation.tex | 550 +- .../koma-script/doc/ngerman/common-parmarkup.tex | 86 +- .../koma-script/doc/ngerman/common-textmarkup.tex | 256 +- .../koma-script/doc/ngerman/common-titles.tex | 201 +- .../koma-script/doc/ngerman/common-typearea.tex | 24 +- .../latex/koma-script/doc/ngerman/expertpart.tex | 7 +- .../koma-script/doc/ngerman/guide-ngerman.tex | 14 +- .../source/latex/koma-script/doc/ngerman/guide.tex | 10 +- .../latex/koma-script/doc/ngerman/introduction.tex | 29 +- .../latex/koma-script/doc/ngerman/linkalias.tex | 5 +- .../latex/koma-script/doc/ngerman/preface.tex | 48 +- .../latex/koma-script/doc/ngerman/scraddr.tex | 72 +- .../latex/koma-script/doc/ngerman/scrbase.tex | 950 ++-- .../doc/ngerman/scrbookreportarticle-experts.tex | 814 +-- .../doc/ngerman/scrbookreportarticle.tex | 1897 ++++--- .../latex/koma-script/doc/ngerman/scrdatetime.tex | 32 +- .../latex/koma-script/doc/ngerman/scrextend.tex | 83 +- .../latex/koma-script/doc/ngerman/scrhack.tex | 93 +- .../latex/koma-script/doc/ngerman/scrjura.tex | 411 +- .../koma-script/doc/ngerman/scrjuraexample.tex | 2 +- .../doc/ngerman/scrlayer-notecolumn.tex | 317 +- .../doc/ngerman/scrlayer-scrpage-experts.tex | 410 +- .../koma-script/doc/ngerman/scrlayer-scrpage.tex | 659 +-- .../latex/koma-script/doc/ngerman/scrlayer.tex | 662 +-- .../latex/koma-script/doc/ngerman/scrlfile.tex | 180 +- .../koma-script/doc/ngerman/scrlttr2-experts.tex | 954 ++-- .../latex/koma-script/doc/ngerman/scrlttr2.tex | 1485 +++--- .../koma-script/doc/ngerman/scrlttr2examples.dtx | 102 +- .../latex/koma-script/doc/ngerman/scrwfile.tex | 88 +- .../latex/koma-script/doc/ngerman/tocbasic.tex | 1121 +++-- .../koma-script/doc/ngerman/typearea-experts.tex | 84 +- .../latex/koma-script/doc/ngerman/typearea.tex | 595 ++- .../source/latex/koma-script/doc/scrguide.cls | 298 +- .../source/latex/koma-script/doc/scrguide.html | 1838 +++---- .../source/latex/koma-script/doc/scrguide.pdf | Bin 3142588 -> 3142480 bytes .../source/latex/koma-script/doc/scrguien.html | 1853 +++---- .../source/latex/koma-script/doc/scrguien.pdf | Bin 2940370 -> 2991664 bytes .../source/latex/koma-script/doc/scrpage2.tex | 8 +- .../source/latex/koma-script/scrhack.dtx | 43 +- .../source/latex/koma-script/scrjura.dtx | 109 +- .../source/latex/koma-script/scrkernel-basics.dtx | 117 +- .../latex/koma-script/scrkernel-bibliography.dtx | 151 +- .../latex/koma-script/scrkernel-compatibility.dtx | 24 +- .../source/latex/koma-script/scrkernel-floats.dtx | 441 +- .../source/latex/koma-script/scrkernel-fonts.dtx | 56 +- .../source/latex/koma-script/scrkernel-index.dtx | 74 +- .../koma-script/scrkernel-letterclassoptions.dtx | 29 +- .../source/latex/koma-script/scrkernel-listsof.dtx | 126 +- .../latex/koma-script/scrkernel-miscellaneous.dtx | 235 +- .../latex/koma-script/scrkernel-notepaper.dtx | 78 +- .../latex/koma-script/scrkernel-paragraphs.dtx | 7 +- .../latex/koma-script/scrkernel-pseudolengths.dtx | 33 +- .../latex/koma-script/scrkernel-sections.dtx | 138 +- .../source/latex/koma-script/scrkernel-title.dtx | 155 +- .../latex/koma-script/scrkernel-tocstyle.dtx | 43 +- .../latex/koma-script/scrkernel-typearea.dtx | 44 +- .../source/latex/koma-script/scrkernel-version.dtx | 4 +- .../latex/koma-script/scrlayer-notecolumn.dtx | 91 +- .../source/latex/koma-script/scrlayer-scrpage.dtx | 84 +- .../source/latex/koma-script/scrlayer.dtx | 27 +- .../source/latex/koma-script/scrmain.ins | 3 + .../source/latex/koma-script/tocbasic.dtx | 95 +- Master/texmf-dist/tex/latex/koma-script/DIN.lco | 8 +- .../texmf-dist/tex/latex/koma-script/DINmtext.lco | 8 +- .../texmf-dist/tex/latex/koma-script/KOMAold.lco | 10 +- Master/texmf-dist/tex/latex/koma-script/KakuLL.lco | 4 +- Master/texmf-dist/tex/latex/koma-script/NF.lco | 8 +- .../texmf-dist/tex/latex/koma-script/NipponEH.lco | 4 +- .../texmf-dist/tex/latex/koma-script/NipponEL.lco | 4 +- .../texmf-dist/tex/latex/koma-script/NipponLH.lco | 4 +- .../texmf-dist/tex/latex/koma-script/NipponLL.lco | 4 +- .../texmf-dist/tex/latex/koma-script/NipponRL.lco | 4 +- Master/texmf-dist/tex/latex/koma-script/SN.lco | 8 +- Master/texmf-dist/tex/latex/koma-script/SNleft.lco | 8 +- .../tex/latex/koma-script/UScommercial9.lco | 8 +- .../tex/latex/koma-script/UScommercial9DW.lco | 8 +- Master/texmf-dist/tex/latex/koma-script/float.hak | 14 +- .../texmf-dist/tex/latex/koma-script/floatrow.hak | 16 +- .../texmf-dist/tex/latex/koma-script/hyperref.hak | 10 +- .../texmf-dist/tex/latex/koma-script/listings.hak | 10 +- Master/texmf-dist/tex/latex/koma-script/lscape.hak | 10 +- .../texmf-dist/tex/latex/koma-script/nomencl.hak | 10 +- .../texmf-dist/tex/latex/koma-script/scrartcl.cls | 674 ++- .../texmf-dist/tex/latex/koma-script/scrbase.sty | 65 +- .../texmf-dist/tex/latex/koma-script/scrbook.cls | 691 ++- .../texmf-dist/tex/latex/koma-script/scrdate.sty | 8 +- .../texmf-dist/tex/latex/koma-script/scrextend.sty | 149 +- .../tex/latex/koma-script/scrfontsizes.sty | 12 +- .../texmf-dist/tex/latex/koma-script/scrhack.sty | 14 +- .../texmf-dist/tex/latex/koma-script/scrjura.sty | 65 +- .../texmf-dist/tex/latex/koma-script/scrkbase.sty | 46 +- .../tex/latex/koma-script/scrlayer-notecolumn.sty | 82 +- .../tex/latex/koma-script/scrlayer-scrpage.sty | 75 +- .../texmf-dist/tex/latex/koma-script/scrlayer.sty | 12 +- .../texmf-dist/tex/latex/koma-script/scrletter.sty | 84 +- .../texmf-dist/tex/latex/koma-script/scrlfile.sty | 2 +- .../texmf-dist/tex/latex/koma-script/scrlttr2.cls | 138 +- .../texmf-dist/tex/latex/koma-script/scrpage2.sty | 2 +- .../texmf-dist/tex/latex/koma-script/scrreprt.cls | 691 ++- .../tex/latex/koma-script/scrsize10pt.clo | 8 +- .../tex/latex/koma-script/scrsize11pt.clo | 8 +- .../tex/latex/koma-script/scrsize12pt.clo | 8 +- .../texmf-dist/tex/latex/koma-script/scrtime.sty | 8 +- .../texmf-dist/tex/latex/koma-script/setspace.hak | 10 +- .../texmf-dist/tex/latex/koma-script/tocbasic.sty | 95 +- .../texmf-dist/tex/latex/koma-script/typearea.sty | 50 +- .../texmf-dist/tex/latex/koma-script/visualize.lco | 10 +- 181 files changed, 34967 insertions(+), 27337 deletions(-) diff --git a/Master/texmf-dist/doc/latex/koma-script/README b/Master/texmf-dist/doc/latex/koma-script/README index 11e8a6ae339..f31950cb627 100644 --- a/Master/texmf-dist/doc/latex/koma-script/README +++ b/Master/texmf-dist/doc/latex/koma-script/README @@ -1,6 +1,6 @@ -KOMA-Script 2017/09/07 v3.24 -Copyright (c) Markus Kohm , 1994-2017 +KOMA-Script 2018/03/30 v3.25 +Copyright (c) Markus Kohm , 1994-2018 This material is subject to the LaTeX Project Public License. See lppl.txt (english) or lppl-de.txt (german) for the details of that @@ -29,10 +29,10 @@ scraddr - Package to provide data from scrlttr2's adr-files Maintainer: Markus Kohm E-Mail: komascript at gmx info Abstract: scraddr is a LaTeX package of the KOMA-Script bundle. - scrlttr2 uses adr-files to provide circuit letters. Package - scraddr provides commands to read such files and to use the - data of the address entries not only with scrlttr2 class and - not only for circuit letters. + scrlttr2 uses adr-files to create form letters. The scraddr + package provides commands to read such files and to use the + data of the address entries not only with the scrlttr2 class + and not only for form letters. Requires: License: LPPL 1.3c or later State: Author maintained @@ -42,99 +42,101 @@ scrartcl - versatile class may be used as a drop-in replacement of article ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info -Abstract: scrartcl is a LaTeX class of the KOMA-Script bundle. It is - the KOMA-Script drop-in replacement of LaTeX standard class - article. It provides all options, environments, counters, - lengths and commands of the LaTeX standard class article, - but also several additional options, environments, commands - etc. to make it much more versatile. The default layout of - scrartcl differs from article with emphasis on typography. - Nevertheless by changing the defaults a layout very similar - to the layou of the standard class may be accomplished. +Abstract: scrartcl is a LaTeX class of the KOMA-Script bundle. It is + the KOMA-Script drop-in replacement for the standard LaTeX + article class. It provides all options, environments, + counters, lengths and commands of the standard LaTeX article + class, as well as several additional options, environments, + commands, etc. to make it much more versatile. The default + layout of scrartcl differs from article, with an emphasis on + good typography. Nevertheless, by changing the defaults, you + can achieve a layout very similar to that of the standard + class. Requires: scrkbase - internal KOMA-Script package tocbasic - KOMA-Script package typearea - KOMA-Script package +Recommended: scrlayer-scrpage - KOMA-Script package License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== scrbase - basic features for KOMA-Script, e.g. conditionals and key=value ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info Abstract: scrbase is a LaTeX package of the KOMA-Script bundle. It - provides some basic functions used by KOMA-Script, that may - be used as well by authors and users of other classes and + provides some basic functions used by KOMA-Script that can + also be used by authors and users of other classes and packages. - First of all it provides an extended key=value handling, - that may be used for run-time options of classes and - packages. Several packages of a family may share options - and all the options of one family may be changed with a + First, it provides extended handling of key=value pairs + that can be used for run-time options of classes and + packages. Several packages in a family can share options, + and all the options in a family can be changed with a single command. Additional conditions like \ifundefinedorrelax, \ifpdftex, - \ifVTeX, \ifpdfoutput, \ifstr etc. are provided. - Definition of most of them may be prevented from being - defined and have additional internal representations that - may be used by package or class authors. + \ifVTeX, \ifpdfoutput, \ifstr etc. are provided. Most of + them can be prevented from being defined and have + additional internal representations that can be used by + package or class authors. It also provides commands to easily define or change - language dependent terms and that work not only with babel - but with other packages like ngerman too. + language-dependent terms that work not only with babel but + with other packages like ngerman too. It provides some commands for package and class authors missing in the LaTeX kernel like \ClassInfoNoLine, \PackageInfoNoLine or \l@addto@macro. - Last but not least it provides commands for integer - division and integer modulo operation, that may be used, - e.g., inside \numexpr ...\relax or with \ifnum. + Last but not least, it provides commands for integer + division and integer modulo operation that can be used, + for example, inside \numexpr ...\relax or with \ifnum. Requires: keyval - key=value package from the graphics bundle scrlfile - KOMA-Script package for file loading manipulation License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== scrbook - versatile class may be used as a drop-in replacement of book ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info Abstract: scrbook is a LaTeX class of the KOMA-Script bundle and a - drop-in replacement of LaTeX standard class book. It + drop-in replacement for the standard LaTeX book class. It provides all options, environments, commands, etc. of the - LaTeX standard class book, but also several additional - options, environments, commands etc. to make it much more - versatile. The default layout of scrbook differs from book - with emphasis on typography. Nevertheless by changing the - defaults a layout very similar to the layou of the standard - class may be accomplished. + standard LaTeX book class, as well as several additional + options, environments, commands, etc. to make it much more + versatile. The default layout of scrbook differs from book, + with an emphasis on good typography. Nevertheless, by changing + the defaults, you can achieve a layout very similar to that + of the standard class. Requires: scrkbase - internal KOMA-Script package tocbasic - KOMA-Script package typearea - KOMA-Script package License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== scrdate - calender date operations, e.g. calculation of the day of the week ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info -Abstract: scrdate is a LaTeX package of the KOMA-Script bundle. It - provides several operations with calender dates, e.g. show +Abstract: scrdate is a LaTeX package of the KOMA-Script bundle. It + provides several operations with calender dates, e.g., show the century or the decade of a year, calculate the day of the week of a given calender date, show the current calender date in ISO form. It has support for several - languages, like English, German, French, Italian, Spanish, - Croatian, Finnish, Norsk, Swedish, Danish, Polish, Czech, - and Slovak. -Requires: scrbase - KOMA-Script package for some basic features. + languages, including English, German, French, Italian, + Spanish, Croatian, Finnish, Norsk, Swedish, Danish, Polish, + Czech, and Slovak. +Requires: scrkbase - KOMA-Script package for some basic features. scrlfile - KOMA-Script package for file loading manipulation License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== scrdoc - internal source documentation class of KOMA-Script ------------------------------------------------------------------------------ @@ -143,8 +145,8 @@ E-Mail: komascript at gmx info Abstract: scrdoc is an internal LaTeX class of the KOMA-Script bundle. It is an extension of ltxdoc. KOMA-Script uses scrdoc for the implementation documentation and the documentation of - packages, that aren't KOMA-Script core packages. Currently - there isn't any user manual for this class, because the + packages that aren't KOMA-Script core packages. Currently + there is no user manual for this class because the only user is the KOMA-Script maintainer. Requires: ltxdoc - the LaTeX2e source documentation class scrartcl - the KOMA-Script article class @@ -156,288 +158,285 @@ scrextend - make some features of the KOMA-Script classes available for others ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info -Abstract: scrextend is a LaTeX package of the KOMA-Script bundle. It - makes some features of the KOMA-Script classes available - for other classes, i.e., for the standard classes. +Abstract: scrextend is a LaTeX package of the KOMA-Script bundle. It + makes some features of the KOMA-Script classes available to + other classes, i.e., for the standard classes. Requires: scrkbase - internal package with some basics of KOMA-Script etoolbox - tool-box for LaTeX programming using e-TeX License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== scrfontsizes - package to generate a KOMA-Script font size file ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info Abstract: scrfontsizes is a LaTeX package of the KOMA-Script bundle. - It provides only a very simple interface to generate - KOMA-Script font size files. + It provides a simple interface to generate KOMA-Script + font-size files. Requires: scrextend - some KOMA-Script features for other classes License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== scrhack - patch some isues with other packages ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info -Abstract: scrhack is a LaTeX package of the KOMA-Script bundle. It - patches other packages to make them work better, add new - features to them and to improve their interaction with - KOMA-Script. One main feature is, to make them work with - tocbasic instead of the KOMA-Script's deprecated float list - interface. Currently patches for float.sty, floatrow.sty, - (old versions of) hyperref, listings, and setspace are - available. +Abstract: scrhack is a LaTeX package of the KOMA-Script bundle. It + patches other packages to make them work better and adds new + features to improve their interaction with KOMA-Script. One + main feature is to make them work with tocbasic instead of + KOMA-Script's deprecated float list interface. Currently, + patches for float.sty, floatrow.sty, (old versions of) + hyperref, listings, and setspace are available. Requires: scrkbase - internal KOMA-Script package with basics tocbasic - features for helper files and float environments xpatch - extending etoolbox patching commands License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== scrjura - contract environment for advocates and scholary persons in law ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info Abstract: scrjura is a LaTeX package of the KOMA-Script bundle. It - has been made on copperation with a German lawyer to + has been made in cooperation with a German lawyer to provide environments for contracts, laws, acts or other - juristic puposes. It supports automatic numbering of + legal purposes. It supports automatic numbering of paragraphs and semi-automatic numbering of sentences. - Currently German and English are supported, but - unfortunately there's only a German user manual. + Currently German and English are supported. Requires: scrkbase - internal KOMA-Script package with basics tocbasic - features for helper files and float environments License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== scrkbase - internal basic features for KOMA-Script classes and packages ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info -Abstract: scrkbase is an internal KOMA-Script packages, that provides - some features that are common for several KOMA-Script - classes and packages. Users and class or package authors - should not use the package directly. +Abstract: scrkbase is an internal KOMA-Script packages that provides + some features that are common to several KOMA-Script + classes and packages. Users and class or package authors + should not use this package directly. Requires: scrbase - KOMA-Script package for some basic features. scrlfile - KOMA-Script package for file loading manipulation License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== scrlayer-notecolumn - control note columns parallel to the main text ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info Abstract: scrlayer-notecolumn is a LaTeX package of the KOMA-Script - bundle. It provides a end user interface to above - scrlayer, to define and manage note columns. Those note - columns are somehow similar to margin note (see LaTeX + bundle. It provides an end-user interface to scrlayer to + define and manage note columns. Those note columns are + somewhat similar to marginal notes (see the LaTeX command \marginpar or packages like notecolumn), but you - may use several of them. The package provides page breaks + can use several of them. The package provides page breaks inside note columns and synchronization points between the main text and note columns. - Like most of the KOMA-Script packages you may use this - package not only with KOMA-Script classes but with several - other classes, e.g., the LaTeX standard classes too. + Like most of the KOMA-Script packages, you can use this + package not only with KOMA-Script classes but also with + several other classes, e.g., the standard LaTeX classes. Requires: scrlayer.sty License: LPPL 1.3c or later State: Author maintained, proof of concept -Version: 2017/08/11 v0.1.2670 +Version: 2018/02/02 v0.1.2928 ============================================================================== scrlayer-scrpage - controlling page headers and footers ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info Abstract: scrlayer-scrpage is a LaTeX package of the KOMA-Script - bundle. It provides a end user interface to above - scrlayer, to define and manage page styles. This end user - interface is as much compatible to scrpage2, that users - should easily be able to switch from the old scrpage2 - package to the new one. Nevertheless it provides several - new features to control the page headers and footers. + bundle. It provides an end-user interface to scrlayer to + define and manage page styles. This end user interface is + sufficiently compatible to scrpage2 that users should easily + be able to switch from the old scrpage2 package to the new + one. Nevertheless, it provides several new features to control + headers and footers. - Like most of the KOMA-Script packages you may use this - package not only with KOMA-Script classes but with several - other classes, e.g., the LaTeX standard classes, too. + Like most of the KOMA-Script packages, you can use this + package not only with KOMA-Script classes but also with + several other classes, e.g., the standard LaTeX classes. Requires: scrlayer.sty License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== scrlayer - defining layers and controlling page headers and footers ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info Abstract: scrlayer is a LaTeX package of the KOMA-Script bundle. - Users may already know a kind of layers from packages like - eso-pic or textpos. scrlayer is another package, that - provides background and foreground layers, but in - difference to those other packages, these layers are part - of the page style definition. With this you may simply - switch between usage of layers by switching the page style. + Users may already be familiar with a type of layer from + packages like eso-pic or textpos. scrlayer is another package + that provides background and foreground layers, but unlike + those other packages, these layers are part of the page-style + definition. With this package, you can easily switch between + the layers used by switching the page style. - In short words: The page style interface of scrlayer - provides commands to define layer-stack-based page styles - and to manage those layer stacks. + In short, the page-style interface of scrlayer provides + commands to define page styles based on a stack of layers and + to manage those layer stacks. - Nevertheless using the layers directly is recommended for - advanced users only. End user interfaces for beginners or + Nevertheless, using the layers directly is recommended for + advanced users only. End-user interfaces for beginners or average users are provided by additional packages, that load scrlayer on their own, e.g., scrlayer-scrpage. Requires: scrkbase.sty License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== scrletter - letter extention to KOMA-Script classes ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info Abstract: scrletter provides the features of the letter class scrlttr2 - with the KOMA-Script classes scrartcl, scrreprt, and scrbook - or with the standard classes article, report, and book. + when using the KOMA-Script classes scrartcl, scrreprt, and + scrbook, or the standard classes article, report, and book. Requires: scrkbase - internal KOMA-Script package typearea - KOMA-Script package scrlayer-scrpage - KOMA-Script package Recommended: marvosym - package by Martin Vogel providing symbols License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== scrlfile - control of package dependencies ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info -Abstract: scrlfile is a LaTeX package of the KOMA-Script bundle. It - provides execution of commands before or after loading, - files, classes or packages and even automatic replacement - of loading files, classes, or packages by other files, - classes, or packages. It can also prevent a package from - beeing loaded. It also provides execution of commands - before or after closing the main aux-file while - \end{document}. Is has been used by the KOMA-Script - classes for more than a decade. +Abstract: scrlfile is a LaTeX package of the KOMA-Script bundle. It + provides the ability to execute commands before or after + loading files, classes, or packages. It can even + automatically load one file, class, or package in place of + another or prevent a package from being loaded. It also + provides the ability to execute commands before or after + closing the main aux file during \end{document}. It has + been used by the KOMA-Script classes for more than a + decade. Requires: License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== scrlttr2 - versatile letter class with separation of text area and note paper ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info Abstract: scrlttr2 is a letter class for LaTeX2e that allows - definition of several note papers and text area settings, - that are independent from the note paper. So you may not - only use KOMA-Script package typearea to define the text - area and the margins of the text area, but even packages - like geometry. + definition of several letterheads and text area settings + that are independent from the letterhead. So you can use + not only the KOMA-Script package typearea but even packages + like geometry to define the text area and the margins. - The positions of the elements of the note paper may be - changed by so called pseudo lengths. This makes it not only - possible to adjust scrlttr2 to local conventions, norms and - paper sizes but also to a wanted corporate identity. + The positions of the elements of the letterhead can be + changed by so called pseudo-lengths. This makes it possible + to adjust scrlttr2 not only to local conventions and paper + sizes but also to a corporate brand identity. - Several predefined parameter sets, called letter class - option or lco-files, are for two German letters, Swiss - letters, US letters, Japanese letters, and French letters - are part of the KOMA-Script bundle. More may be found on - CTAN or the KOMA-Script homepage as separate packages. + Several predefined sets of parameters, called + letter-class-option or lco files are part of the + KOMA-Script bundle: two German letters, Swiss letters, US + letters, Japanese letters, and French letters. More can be + found on CTAN or the KOMA-Script homepage as separate + packages. - Additional lco-files for different note papers may be found - on the KOMA-Script homepage, e.g. one demonstration file - for a note paper similar to the one of the Washington State + Additional lco-files for different letterheads can be found + on the KOMA-Script homepage, e.g., one demonstration file + for a letterhead similar to that of Washington State University. Requires: scrkbase - internal KOMA-Script package typearea - KOMA-Script package Recommended: marvosym - package by Martin Vogel providing symbols License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== scrpage2 - control of page headers and footers ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info Abstract: scrpage2 is a LaTeX package of the KOMA-Script bundle. It - provides facilities for changing the contents of page - headers and footers. You may either configure a predefined - pair or page styles similar to headings and plain or - myheadings and plain, use a simple user interface to define - completely new page styles or a more complex expert - interface to have more effective degrees of freedom in - defining new page styles. + provides facilities for changing the contents of headers and + footers. You can configure a predefined pair of page styles + similar to headings and plain or myheadings and plain, use a + simple user interface to define completely new page styles, or + take advantage of a more complex expert interface to have more + effective degrees of freedom in defining new page styles. scrpage2 also provides simple options and commands to decide, e.g., whether or not the running heads should be done automatically, which headings levels should generate automatic running heads, whether or not there should be - horizontal lines above or below the page headers and - footers, to change the colour or font of the page headers - and footers (and the lines) and more. + horizontal lines above or below the headers and footers, what + colours or fonts should be used for the headers, footers, and + separation lines, and more. Requires: Successor: scrlayer-scrpage License: LPPL 1.3c or later -State: Author maintained -Version: 2017/09/07 v3.24 +State: Author maintained, obsolete +Version: 2018/03/30 v3.25 ============================================================================== scrreprt - versatile class may be used as a drop-in replacement of report ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info -Abstract: scrreprt is the KOMA-Script drop-in replacement of LaTeX - standard class report. It provides all options, - environments, counters, lengths and commands of the LaTeX - standard class report, but also several additional options, - environments, commands etc. to make it much more versatile. - The default layout of scrreprt differs from report with - emphasis on typography. Nevertheless by changing the - defaults a layout very similar to the layout of the - standard class may be accomplished. +Abstract: scrreprt is the KOMA-Script drop-in replacement for the + standard LaTeX report class. It provides all options, + environments, counters, lengths, and commands of the standard + LaTeX report class, as well as several additional options, + environments, commands, etc., to make it much more versatile. + The default layout of scrreprt differs from that of report, + with an emphasis on good typography. Nevertheless, by changing + the defaults, you can achieve a layout very similar to that of + the standard class. Requires: scrkbase - internal KOMA-Script package tocbasic - KOMA-Script package typearea - KOMA-Script package License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== scrtime - show the time of the LaTeX run ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info Abstract: scrtime is a LaTeX package of the KOMA-Script bundle. It - provides only some tiny facilities to show the time of the + provides only some small features to show the time of the LaTeX run. Requires: scrkbase - internal package with some basics of KOMA-Script License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== scrwfile - Spare write handles for helper files to avoid `No room' messages ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info -Abstract: scrwfile is a LaTeX package of the KOMA-Script bundle. TeX - provides only about 16 write handles available by - \newwrite. With LaTeX not only the aux-file but each - helper file like the toc-file, the lof-file, the lot-file, - and files like raw indexes and raw glossaries need one of - those handles. scrwfile provides facilities to avoid all - the handles of the helper files, that use the aux-file for - intermediate writing. This means, that toc-file, lof-file, - lot-file and files of packages like listings don't need a - write handle anymore. So the user will have more write - handles for files like indexes or glossaries and may avoid +Abstract: scrwfile is a LaTeX package of the KOMA-Script bundle. TeX + makes only about 16 write handles available for \newwrite. + With LaTeX, each auxiliary file, not only the main aux file + but files such as the toc file, the lof file, the lot file, + and the raw indexes and glossaries need one of these + handles. scrwfile provides facilities to avoid using + handles for auxiliary files that use the main aux file for + intermediate writing. This means that the toc file, the lof + file, the lot file, and files of packages like listings no + longer need a write handle, so the user will have more write + handles for files like indexes or glossaries and can avoid `No room for new \write' error messages. - scrwfile also provides facilities to clone helper files, - e.g., this may be used to have two tables of contents with - different tocdepth settings. + scrwfile also provides facilities to clone auxiliary files, + e.g., to have two tables of contents with different tocdepth + settings. Requires: scrbase - some basic features for class and package authors tocbasic - basic features for helper files and lists of @@ -453,37 +452,38 @@ Maintainer: Markus Kohm E-Mail: komascript at gmx info Abstract: tocbasic is a LaTeX package of the KOMA-Script bundle. The main purpose of package tocbasic is to provide features for - authors of classes and packages to create own tables or + authors of classes and packages to create their own tables or lists of contents like the list of figures and the list of - tables and thereby allow other classes or packages some - types of controll about these. For examples package - tocbasic delegates language control of all these tables and - lists of contents to package babel. So automatic change of - language will be provides inside all these tables and lists - of contents. Using tocbasic will exculpate authors of - classes and packages from implementation of such features. + tables, and thereby allow other classes or packages some + measure of control over these. For example, the tocbasic + package delegates control of the language for all these tables + and lists of contents to the babel package. Thus changes of + language will be automatically reflected inside all these + tables and lists of contents. Using tocbasic will free + authors of classes and packages from the burden of + implementing of such features. KOMA-Script itself uses tocbasic not only for the table of - contents but also for the already mentioned lists of - figures and tables. + contents but also for the lists of figures and tables + mentioned previously. Requires: scrbase - KOMA-Script package for some basic features. License: LPPL 1.3c or later State: Author maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== tocstyle - Control layout of table of contents, list of figures etc. ------------------------------------------------------------------------------ Maintainer: Markus Kohm E-Mail: komascript at gmx info Abstract: tocstyle is a LaTeX package of the KOMA-Script bundle. - While the main classes of the KOMA-Script bundle were made, - there where several ideas for formating the table of - contents and lists of floats, but almost none of them where - implemented. One reason was, that the KOMA-Script author - didn’t like to change the LaTeX kernel at a class, because - this may result in serveral problems with other packages. - The package tocstyle will fill the gap. If it conflicts - with another package, you simply may decide not to use it. + When the main classes of the KOMA-Script bundle were created, + their author had several ideas for formatting the table of + contents and lists of floats, but almost none of them were + implemented. One reason was that the KOMA-Script author + didn't like to change the LaTeX kernel in a class, because + this could result in several problems with other packages. + The package tocstyle will fill the gap. If it conflicts + with another package, you can simply decide not to use it. The current release is only a proof of concept. Requires: @@ -497,20 +497,18 @@ Maintainer: Markus Kohm E-Mail: komascript at gmx info Abstract: Many LaTeX classes, including the standard classes, present the user with the largely fixed configuration of margins - and type area. With the standard classes, the - configuration determined is very much dependent on the - chosen font size. There are separate packages, such as - geometry, which give the user complete control, but also - full responsibility of the settings of typearea and + and type area. With the standard classes, the choice is + limited to selecting a font size. There are separate packages, + such as geometry, which give the user complete control over, + but also full responsibility for, setting the type area and margins. KOMA-Script takes a somewhat different approach with its - typearea package. Here the user is given several - construction setting and automatization possibilities based - on established typography standards in order to help guide - him or her in making a good choice. + typearea package. Users are offered ways to adjust the design + and algorithms based on established typographic standards, + making it easier for them to make good choices. Requires: scrkbase - internal basic features for KOMA-Script packages License: LPPL 1.3c or later State: Autor maintained -Version: 2017/09/07 v3.24 +Version: 2018/03/30 v3.25 ============================================================================== diff --git a/Master/texmf-dist/doc/latex/koma-script/manifest.txt b/Master/texmf-dist/doc/latex/koma-script/manifest.txt index a5ade2ce28a..a0b9a993ee1 100644 --- a/Master/texmf-dist/doc/latex/koma-script/manifest.txt +++ b/Master/texmf-dist/doc/latex/koma-script/manifest.txt @@ -35,7 +35,7 @@ % Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. % ====================================================================== % -% CONTENTS OF THE KOMA-SCRIPT RELEASE 2017/09/07 v3.24 +% CONTENTS OF THE KOMA-SCRIPT RELEASE 2018/03/30 v3.25 % ------------------------------------------------------ % % diff --git a/Master/texmf-dist/doc/latex/koma-script/scrguide.html b/Master/texmf-dist/doc/latex/koma-script/scrguide.html index 91c68657257..68ad75018df 100644 --- a/Master/texmf-dist/doc/latex/koma-script/scrguide.html +++ b/Master/texmf-dist/doc/latex/koma-script/scrguide.html @@ -10,967 +10,975 @@
  • Optionen
  • Anweisungen
  • Umgebungen
  • Längen
  • Pseudolängen
  • Variablen
  • Seitenstile
  • Zähler
  • Stile für das float-Paket
  • Optionen

    Anweisungen

    Umgebungen

    Längen

    Pseudolängen

    Variablen

    Seitenstile

    Zähler

    Stile für das float-Paket

    Options

  • Commands
  • Environments
  • Lengths
  • Pseudolengths
  • Variables
  • Page Styles
  • Counter
  • Styles for the float Package
  • Options

    Commands

    Environments

    Lengths

    Pseudolengths

    Variables

    Page Styles

    Counter

    Styles for the float Package

    = 3.25 + +r2950 2018-03-05 08:54:19 +0100 kohm: + + * scrkernel-compatibility.dtx: New compatibility value + +r2949 2018-03-01 10:42:54 +0100 kohm: + + * TODO, doc/, doc/english/, doc/english/scrbase.tex: docu of + \FamilyCSKey + +r2948 2018-03-01 10:28:00 +0100 kohm: + + * TODO, doc/, doc/english/, doc/english/tocbasic.tex: docu of options + setup and unset of \DeclareNewTOC + +r2947 2018-03-01 10:14:52 +0100 kohm: + + * TODO, doc/, doc/english/, + doc/english/scrbookreportarticle-experts.tex: documentation of + \IfIsAliaskomafont + +r2946 2018-03-01 10:05:28 +0100 kohm: + + * TODO, doc/, doc/english/, doc/english/scrjura.tex: no more undefined + references; scrjura.tex synced with German version + +r2945 2018-03-01 09:03:49 +0100 kohm: + + * TODO: ?\195?\156berholte Punkte entfernt, Frage bez?\195?\188glich + "simple switch" erg?\195?\164nzt + +r2944 2018-02-28 13:23:23 +0100 kohm: + + * TODO, doc/, doc/english/, doc/english/common-marginpar.tex, + doc/english/common-parmarkup.tex, doc/english/common-fontsize.tex, + doc/english/scrbookreportarticle.tex, doc/english/expertpart.tex, + doc/english/common-interleafpage.tex, + doc/english/scrlayer-scrpage.tex, + doc/english/common-headfootheight.tex, doc/english/common-dictum.tex, + doc/english/common-options.tex, doc/english/common-footnotes.tex, + doc/english/scrextend.tex, doc/english/common-lists.tex, + doc/english/common-draftmode.tex, doc/english/common-textmarkup.tex, + doc/english/scrlayer.tex, doc/english/typearea.tex, + doc/english/common-pagestylemanipulation.tex, + doc/english/common-oddorevenpage.tex, doc/english/authorpart.tex, + doc/english/common-titles.tex, doc/english/common-compatibility.tex, + doc/english/common-typearea.tex, doc/english/introduction.tex, + doc/english/preface.tex: New translation by Karl Hagen + +r2943 2018-02-28 13:15:51 +0100 kohm: + + * TODO: Fehler l?\195?\164ngst beseitigt + +r2942 2018-02-19 08:23:07 +0100 kohm: + + * scrkernel-title.dtx: bugfix + +r2941 2018-02-16 04:42:17 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbase.tex, + doc/ngerman/scrlfile.tex, doc/ngerman/scrwfile.tex: Korrekturen [Falk] + +r2940 2018-02-13 09:46:59 +0100 kohm: + + * doc/, doc/scrguide.cls: Farbgebung + +r2939 2018-02-13 09:46:41 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex, + doc/ngerman/scrlayer-scrpage.tex, + doc/ngerman/scrbookreportarticle-experts.tex: Fehlerkorrekturen + [Ernst] + +r2938 2018-02-12 10:12:53 +0100 kohm: + + * scrkernel-sections.dtx: fix usage of font for new defined heading + commands of style part + +r2937 2018-02-12 08:08:32 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex: Korrekturen [Ernst] + +r2936 2018-02-07 13:47:54 +0100 kohm: + + * doc/, doc/guide.tex, doc/scrpage2.tex: scrpage2.pdf generation + improved + +r2935 2018-02-07 12:57:30 +0100 kohm: + + * doc/, doc/scrguide.cls: improvements for non-free + +r2934 2018-02-06 10:26:38 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-textmarkup.tex, + doc/ngerman/scrjura.tex: Korrekturen [Heiner+Alexander] + +r2933 2018-02-06 09:33:25 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex, + doc/ngerman/scrbookreportarticle-experts.tex: Korrekturen [Elke] + +r2932 2018-02-06 09:20:05 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-lists.tex: Eine Randmarke + eingef?\195?\188gt [Elke] + +r2931 2018-02-05 10:50:56 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex, + doc/ngerman/scrbase.tex, doc/ngerman/scrbookreportarticle.tex, + doc/ngerman/scrlayer-notecolumn.tex, doc/ngerman/tocbasic.tex, + doc/ngerman/scrhack.tex, doc/ngerman/scrjura.tex, + doc/ngerman/common-pagestylemanipulation.tex, + doc/ngerman/scrlfile.tex, doc/ngerman/introduction.tex, + doc/ngerman/scraddr.tex: wie-Komma-Korrekturen + +r2930 2018-02-05 09:57:42 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrdatetime.tex: + Doppelpunktverwendung im Satz + +r2929 2018-02-05 07:37:22 +0100 kohm: + + * scrlayer-scrpage.dtx, scrkernel-fonts.dtx: warning for element + pagehead replaced by an info + +r2928 2018-02-02 18:10:27 +0100 kohm: + + * scrlayer-notecolumn.dtx: usage of \closein and \closeout fixed + +r2927 2018-02-02 12:16:47 +0100 kohm: + + * doc/, doc/scrguide.cls, doc/ngerman/, + doc/ngerman/scrbookreportarticle-experts.tex: Korrekturen + [Elke+Markus] + +r2926 2018-02-02 11:18:15 +0100 kohm: + + * TODO: new issue + +r2925 2018-02-02 09:33:36 +0100 kohm: + + * TODO: \IfIsAliaskomafont dokumentiert + +r2924 2018-02-02 08:58:15 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: Korrektur + [Heiner] + +r2923 2018-02-02 07:58:03 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/tocbasic.tex: Korrektur [Elke] + +r2922 2018-02-01 12:55:46 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex, + doc/ngerman/scrbase.tex, doc/ngerman/tocbasic.tex, + doc/ngerman/scrlttr2-experts.tex, doc/ngerman/common-textmarkup.tex, + doc/ngerman/scrlayer.tex, doc/ngerman/scrjura.tex, + doc/ngerman/common-typearea.tex: Korrekturen [Ernst + Rolf] + +r2921 2018-01-31 16:27:33 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle-experts.tex: + Korrekturen + +r2920 2018-01-31 14:24:50 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex, + doc/ngerman/tocbasic.tex, doc/ngerman/scrlttr2-experts.tex, + doc/ngerman/scrlayer.tex, doc/ngerman/introduction.tex: Korrekturen + [Heiner] + +r2919 2018-01-31 13:56:21 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbase.tex, + doc/ngerman/common-parmarkup.tex, doc/ngerman/scrlttr2-experts.tex, + doc/ngerman/scrlayer.tex: Korrekturen [Heiner] + +r2918 2018-01-31 13:01:01 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex, + doc/ngerman/scrlttr2-experts.tex, doc/ngerman/typearea.tex, + doc/ngerman/scrbookreportarticle-experts.tex: Korrekturen [Heiner und + Elke] + +r2917 2018-01-31 11:33:28 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: Korrektur + [Elke] + +r2916 2018-01-31 09:49:41 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/typearea-experts.tex: Korrekturen + [Heiner] + +r2915 2018-01-31 09:48:21 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer-notecolumn.tex: Korrekturen + [Heiner] + +r2914 2018-01-31 09:21:42 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer-scrpage-experts.tex, + doc/ngerman/common-pagestylemanipulation.tex: Korrekturen [Heiner] + +r2913 2018-01-31 08:51:30 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/guide-ngerman.tex, + doc/ngerman/scrlayer.tex, + doc/ngerman/common-pagestylemanipulation.tex: Korrekturen [Heiner] + +r2912 2018-01-31 08:18:25 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrhack.tex: Korrekturen [Heiner] + +r2911 2018-01-30 13:37:05 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex, + doc/ngerman/scrbase.tex, doc/ngerman/scrlayer-scrpage.tex, + doc/ngerman/tocbasic.tex, doc/ngerman/common-draftmode.tex, + doc/ngerman/common-textmarkup.tex, doc/ngerman/scrjura.tex, + doc/ngerman/scrlfile.tex, doc/ngerman/common-titles.tex, + doc/ngerman/scrwfile.tex, doc/ngerman/scraddr.tex: Korrekturen + [Heiner] + +r2910 2018-01-30 11:07:48 +0100 kohm: + + * doc/, doc/guide.bib, doc/ngerman/, doc/ngerman/scrlttr2.tex: + adrconv-Problematik aufgegriffen + +r2909 2018-01-30 09:32:50 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex, + doc/ngerman/common-oddorevenpage.tex, + doc/ngerman/common-compatibility.tex: Korrekturen [Heiner] + +r2908 2018-01-30 08:21:10 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2examples.dtx: Korrektur + [Heiner] + +r2907 2018-01-29 14:12:59 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex, + doc/ngerman/scrbase.tex, doc/ngerman/common-marginpar.tex, + doc/ngerman/common-parmarkup.tex, doc/ngerman/guide-ngerman.tex, + doc/ngerman/scrbookreportarticle.tex, + doc/ngerman/scrlayer-scrpage.tex, doc/ngerman/adrconvnote.tex, + doc/ngerman/common-dictum.tex, doc/ngerman/common-footnotes.tex, + doc/ngerman/tocbasic.tex, doc/ngerman/scrlttr2-experts.tex, + doc/ngerman/scrlayer.tex, doc/ngerman/scrjura.tex, + doc/ngerman/typearea.tex, + doc/ngerman/scrbookreportarticle-experts.tex, + doc/ngerman/common-oddorevenpage.tex, doc/ngerman/scrlfile.tex, + doc/ngerman/common-titles.tex, doc/ngerman/introduction.tex: + Korrekturen [Heiner] + +r2906 2018-01-26 15:57:01 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrjuraexample.tex: eine + ?\195?\132nderung zu viel + +r2905 2018-01-26 11:15:05 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrjuraexample.tex: Korrekturen + [Heiner] + +r2904 2018-01-26 11:14:36 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrjura.tex: Korrekturen [Heiner] + +r2903 2018-01-26 09:46:22 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex, + doc/ngerman/common-textmarkup.tex: Korrekturen [Elke] + +r2902 2018-01-26 09:27:32 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-titles.tex: + zus?\195?\164tzliche Randmarken [Elke] + +r2901 2018-01-26 09:21:20 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-lists.tex: scrlttr2-Randnotiz + auf Kapitel zu scrlttr2 und scrletter beschr?\195?\164nkt + +r2900 2018-01-26 08:58:58 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/guide-ngerman.tex: neueste --> + neuste + +r2899 2018-01-26 08:56:36 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrjura.tex: Korrekturen [Heiner] + +r2898 2018-01-26 08:18:26 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-footnotes.tex: Ligatur in + nicht verwendetem Text gebrochen + +r2897 2018-01-25 11:57:02 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/typearea.tex: Korrekturen + +r2896 2018-01-25 10:23:54 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/expertpart.tex, + doc/ngerman/typearea.tex, doc/ngerman/authorpart.tex, + doc/ngerman/common-compatibility.tex, doc/ngerman/introduction.tex: + Korrekturen + +r2895 2018-01-24 12:02:37 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/typearea.tex: Verwendung von + \OptionVName korrigiert + +r2894 2018-01-24 11:59:22 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer.tex: \OptionVName-Nutzung + korrigiert + +r2893 2018-01-24 11:44:29 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex, + doc/ngerman/common-parmarkup.tex, + doc/ngerman/scrbookreportarticle.tex, + doc/ngerman/scrlayer-notecolumn.tex, + doc/ngerman/common-footnotes.tex, doc/ngerman/scrextend.tex, + doc/ngerman/tocbasic.tex, doc/ngerman/scrlttr2-experts.tex, + doc/ngerman/scrhack.tex, doc/ngerman/scrjura.tex, + doc/ngerman/typearea.tex, + doc/ngerman/scrbookreportarticle-experts.tex, + doc/ngerman/common-titles.tex: Index-Eintr?\195?\164ge nicht mit + ~\PValue, sondern mit ~\textKValue + +r2892 2018-01-24 11:26:46 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer-notecolumn.tex, + doc/ngerman/typearea.tex: Paket-Indexeintrag + +r2891 2018-01-24 11:22:18 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer-notecolumn.tex: Letzte + ?\195?\132nderungen korrigiert + +r2890 2018-01-24 11:21:05 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer-notecolumn.tex: + Hauptindexeintrag f?\195?\188r das Paket + +r2889 2018-01-24 11:20:28 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer-notecolumn.tex: + Indexeintrag f?\195?\188r das Paket + +r2888 2018-01-24 11:11:53 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer-scrpage-experts.tex: Index + Eintrag f?\195?\188r scrlayer korrekt einsortiert + +r2887 2018-01-24 11:06:00 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer-scrpage.tex: Tabelle + korrigiert um keine falschen Variablen-Eintr?\195?\164ge in den + Index + zu verursachen + +r2886 2018-01-24 10:56:26 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: Index + Eintrag korrigiert + +r2885 2018-01-24 10:46:29 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex: Seitenstile nicht fett + +r2884 2018-01-24 10:18:14 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex: Zus?\195?\164tzliche + Index-Eintr?\195?\164ge f?\195?\188r lco-Dateien + +r2883 2018-01-24 09:07:53 +0100 kohm: + + * doc/, doc/scrguide.cls: new keyword + +r2882 2018-01-24 08:56:56 +0100 kohm: + + * doc/, doc/guide.bib: gaphics date update + +r2881 2018-01-23 20:13:20 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: Verweise + auf entfernten Anhang entfernt + +r2880 2018-01-23 11:31:32 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2-experts.tex: Dokumentation + ?\195?\188berarbeitet + +r2879 2018-01-23 11:31:02 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer.tex: Linkfehler korrigiert + +r2878 2018-01-23 09:34:47 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex: Laden von LCOs bei + scrletter pr?\195?\164zisiert + +r2877 2018-01-22 13:07:56 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2-experts.tex: einige + K?\195?\188rzungen und sprachliche Vereinfachungen + +r2876 2018-01-19 11:35:39 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle-experts.tex: + Kapitel ?\195?\188berarbeitet + +r2875 2018-01-18 14:22:09 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle-experts.tex: + diverse Verbesserungen und Erweiterung der Verlinkung + +r2874 2018-01-18 12:23:37 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/guide-ngerman.tex: zwei weitere + Trennausnahmen + +r2873 2018-01-18 12:06:43 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/guide-ngerman.tex: neue + Trennausnahme + +r2872 2018-01-17 13:01:54 +0100 kohm: + + * scrlayer-notecolumn.dtx: Lua replacement of \pdfmdfivesum added for + usage of lualatex + +r2871 2018-01-17 10:27:46 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/typearea-experts.tex: leichte + Verbesserungen + +r2870 2018-01-17 09:33:25 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer-notecolumn.tex: + Vollverlinkung + +r2869 2018-01-16 14:19:39 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer-scrpage-experts.tex, + doc/ngerman/scrlayer-scrpage.tex: diverse Hinweise zu scrpage2 + verschoben + +r2868 2018-01-16 12:16:00 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-pagestylemanipulation.tex: + kleiner Tippfehler + +r2867 2018-01-16 11:43:11 +0100 kohm: + + * TODO: missing English docu issue + +r2866 2018-01-16 11:41:41 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-headfootheight.tex: Option + autoenlargethispage + +r2865 2018-01-16 11:41:21 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer-scrpage.tex, + doc/ngerman/common-textmarkup.tex, + doc/ngerman/common-pagestylemanipulation.tex: weitere Verbesserungen + an der Anleitung + +r2864 2018-01-16 08:55:20 +0100 kohm: + + * scrkernel-listsof.dtx: forgotten debug messages + +r2863 2018-01-15 12:29:20 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer.tex: Umbruchoptimierung + +r2862 2018-01-15 11:50:39 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-pagestylemanipulation.tex: + Einige K?\195?\188rzungen und Pr?\195?\164zisierungen + +r2861 2018-01-15 10:50:58 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-headfootheight.tex: + Wiederholungstext gek?\195?\188rzt + +r2860 2018-01-14 12:21:47 +0100 kohm: + + * TODO: need docu for autoenlargeheadfoot + +r2859 2018-01-14 12:19:38 +0100 kohm: + + * scrlayer-scrpage.dtx: new option autoenlargeheadfoot + +r2858 2018-01-11 11:21:51 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer.tex: Verbesserungen bei den + Erkl?\195?\164rungen + +r2857 2018-01-11 08:15:39 +0100 kohm: + + * doc/, doc/english/, doc/english/scrlayer.tex: section about state of + development removed + +r2856 2018-01-10 09:26:15 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrhack.tex: Erkl?\195?\164rung zum + nomencl Hack ?\195?\188berarbeitet + +r2855 2018-01-10 08:32:08 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/tocbasic.tex: Quellcodeumbruch + +r2854 2018-01-10 07:45:36 +0100 kohm: + + * doc/, doc/scrguide.cls: link colors changed + +r2853 2018-01-09 12:35:34 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/tocbasic.tex: + Kapitel?\195?\188berarbeitung + +r2852 2018-01-09 09:42:28 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/tocbasic.tex: einige Verbesserungen + an der Doku + +r2851 2018-01-09 08:41:11 +0100 kohm: + + * doc/, doc/scrguide.cls: additional keywords + +r2850 2018-01-09 08:39:59 +0100 kohm: + + * doc/, doc/scrguide.cls: additional keywords + +r2849 2018-01-08 13:31:04 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/tocbasic.tex: diverse Verbesserungen + in der Doku + +r2848 2017-12-19 11:12:33 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrjura.tex: Doku von + \withoutparnumber verbessert + +r2847 2017-12-19 10:38:00 +0100 kohm: + + * scrjura.dtx, doc/, doc/ngerman/, doc/ngerman/scrjura.tex: new + \withoutparnumber + +r2846 2017-12-15 09:47:24 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrwfile.tex: Vollverlinkung + +r2845 2017-12-15 09:47:01 +0100 kohm: + + * doc/, doc/scrguide.cls: \XeLaTeX + +r2844 2017-12-14 12:29:04 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlfile.tex: einige Verbesserungen + +r2843 2017-12-14 11:08:46 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbase.tex: Diverse Verbesserungen, + Umsortierungen, Anpassungen + +r2842 2017-12-14 09:02:53 +0100 kohm: + + * doc/, doc/guide.bib: one more Oberdiek package and revision of + others + +r2841 2017-12-13 12:12:48 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbase.tex: einige Passagen + verschlankt, andere erweitert + +r2840 2017-12-13 12:12:28 +0100 kohm: + + * TODO: kleine ?\195?\132nderung + +r2839 2017-12-13 12:11:29 +0100 kohm: + + * doc/, doc/scrguide.cls: new keyword + +r2838 2017-12-13 10:25:24 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/typearea.tex: an Stelle + ?\226?\134?\146 anstelle + +r2837 2017-12-13 10:21:57 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/tocbasic.tex: an Stelle + ?\226?\134?\146 anstelle + +r2836 2017-12-13 10:21:03 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex: an Stelle + ?\226?\134?\146 anstelle + +r2835 2017-12-13 10:17:12 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2-experts.tex: an Stelle + ?\226?\134?\146 anstelle + +r2834 2017-12-13 10:16:22 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlfile.tex: an Stelle + ?\226?\134?\146 anstelle + +r2833 2017-12-13 10:15:23 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer.tex: an Stelle + ?\226?\134?\146 anstelle + +r2832 2017-12-13 10:13:35 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrjura.tex: an Stelle + ?\226?\134?\146 anstelle + +r2831 2017-12-13 10:12:48 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: an Stelle + ?\226?\134?\146 anstelle + +r2830 2017-12-13 10:11:34 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-lists.tex: an Stelle + ?\226?\134?\146 anstelle + +r2829 2017-12-13 10:11:17 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle-experts.tex: an + Stelle ?\226?\134?\146 anstelle + +r2828 2017-12-13 10:09:14 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-footnotes.tex: an Stelle + ?\226?\134?\146 anstelle + +r2827 2017-12-13 10:05:13 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-fontsize.tex: an Stelle + ?\226?\134?\146 anstelle + +r2826 2017-12-11 09:20:20 +0100 kohm: + + * doc/, doc/scrguide.cls: new keyword + +r2825 2017-12-11 09:18:02 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrjura.tex: Einige Umstellungen in + der Formatierung + +r2824 2017-12-11 08:40:49 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex: Umbruch im Quellcode + +r2823 2017-12-08 21:50:56 +0100 kohm: + + * scrkernel-fonts.dtx: additional warning if an element becomes and + alias and vica versa + +r2822 2017-12-08 12:01:06 +0100 kohm: + + * TODO, doc/, doc/ngerman/, doc/ngerman/scrjura.tex: + Teil?\195?\188berarbeitung der scrjura-Anleitung + +r2821 2017-12-08 11:55:09 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-textmarkup.tex: Deutliche + ?\195?\156berarbeitung f?\195?\188r scrjura + +r2820 2017-12-08 10:27:49 +0100 kohm: + + * scrjura.dtx: several fixes and new option "ClauseFont" for + \DeclareNewJuraEnvironment + +r2819 2017-12-08 10:24:32 +0100 kohm: + + * scrkernel-fonts.dtx: \IfIsAliaskomafont fixed + +r2818 2017-12-08 09:31:53 +0100 kohm: + + * scrkernel-basics.dtx: new \FamilyCSKey + +r2817 2017-12-08 09:18:04 +0100 kohm: + + * scrkernel-fonts.dtx: new \IfIsAliaskomafont + +r2816 2017-12-08 08:37:47 +0100 kohm: + + * scrjura.dtx: font alias Clause inside new environments fixed + +r2815 2017-12-08 08:10:55 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-options.tex: einige + Verbesserungen f?\195?\188r scrextend auch f?\195?\188r scrjura + ?\195?\188bernommen + +r2814 2017-12-07 12:45:04 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrextend.tex: Kapitel scrextend + ?\195?\188berabreitet + +r2813 2017-12-07 12:43:10 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-lists.tex: kleine + Verbesserungen + +r2812 2017-12-07 12:36:47 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-dictum.tex: + Umbruchoptimierung + +r2811 2017-12-07 12:24:25 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-dictum.tex: kleinere + Verbesserungen + +r2810 2017-12-07 12:14:29 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-footnotes.tex: Beispiele in + Kapitel 3 + +r2809 2017-12-07 11:43:47 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-interleafpage.tex: + F?\195?\188r die Beispiele wird auf Abschnitt 3.13 verwiesen + +r2808 2017-12-07 11:10:17 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-titles.tex: kleinere + Verbesserungen + +r2807 2017-12-07 10:29:52 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-textmarkup.tex: + K?\195?\188rzung f?\195?\188r den Umbruch bei scrextend + +r2806 2017-12-07 10:03:09 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-fontsize.tex: kleine + Verbesserungen f?\195?\188r scrextend + +r2805 2017-12-07 09:52:54 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-draftmode.tex: + zus?\195?\164tzlichen Hinweis bei scrextend eingef?\195?\188gt + +r2804 2017-12-07 09:34:03 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-compatibility.tex: kleinere + Verbesserungen zur Unterscheidung von Paket und Klasse, + + keine veralteten Optionen bei scrextend + +r2803 2017-12-07 09:09:24 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-options.tex: + geringf?\195?\188gige Verk?\195?\188rzungen f?\195?\188r scrextend + +r2802 2017-12-06 11:45:10 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scraddr.tex: Kosmetische + Verbesserungen + +r2801 2017-12-06 11:17:40 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrdatetime.tex: kleinere + Aktualisierungen + +r2800 2017-12-06 10:42:36 +0100 kohm: + + * doc/, doc/scrguide.cls: dimexpr and numexpr added to the keywords + +r2799 2017-12-06 10:27:11 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer-scrpage.tex: minimale + Randnotizverschiebung + +r2798 2017-12-06 10:06:36 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-pagestylemanipulation.tex: + Verlinkung f?\195?\188r scrlayer-scrpage + +r2797 2017-12-05 13:18:41 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer-scrpage.tex: several + improvements + +r2796 2017-12-05 13:18:04 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-pagestylemanipulation.tex: + several improvements + +r2795 2017-12-05 12:37:56 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-pagestylemanipulation.tex: + das "definierten" war Unfug, denn man kann tats?\195?\164chlich + teilweise auch + noch nicht definierte Seitenstile beeinflussen + +r2794 2017-12-05 09:05:38 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-textmarkup.tex: minimale + Anpassungen + +r2793 2017-12-05 08:37:04 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-headfootheight.tex: + zus?\195?\164tzliche Links + +r2792 2017-12-05 08:26:09 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-options.tex: Umbruch + verbessert + +r2791 2017-12-04 12:36:25 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: und noch + eine Vereinheitlichung + +r2790 2017-12-04 12:33:56 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: noch ein + paar Vereinheitlichungen bez?\195?\188glich der Verzeichnisoptionen + +r2789 2017-12-04 09:59:43 +0100 kohm: + + * scrkernel-basics.dtx: last change fixed + +r2788 2017-12-04 09:50:18 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: + listof=standardlevel + +r2787 2017-12-04 09:48:18 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-marginpar.tex: + Umbruchkorrekturtext aktiviert + +r2786 2017-12-04 09:31:33 +0100 kohm: + + * TODO, doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: + listof|bibliography|index=standardlevel + +r2785 2017-12-04 09:25:29 +0100 kohm: + + * scrkernel-listsof.dtx: comma in book/report dependency moved to + avoid empty element in + scrartcl case + +r2784 2017-12-04 09:24:13 +0100 kohm: + + * scrkernel-basics.dtx: ignore completely empty elements in numerical + key lists + +r2783 2017-12-04 09:10:46 +0100 kohm: + + * scrkernel-listsof.dtx: new listof=standardlevel + +r2782 2017-12-04 08:47:52 +0100 kohm: + + * scrkernel-index.dtx: same numbered-options as listof and + bibliography + +r2781 2017-12-04 08:31:14 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: + listof=leftaligntextentries korrigiert + +r2780 2017-12-03 22:49:27 +0100 kohm: + + * doc/, doc/linkalias.tex: new alias + desc:maincls-experts.cmd.the/Zaehler/ + +r2779 2017-12-03 22:44:49 +0100 kohm: + + * doc/, doc/linkalias.tex: aliases for + desc:maincls-experts.cmd.thepage and + desc:maincls-experts.cmd.pagemark + +r2778 2017-12-03 22:27:12 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: + multiply-defined labels + +r2777 2017-12-03 22:22:51 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle-experts.tex: + Leerzeichen + +r2776 2017-12-03 22:22:02 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2-experts.tex: Leerzeichen + +r2775 2017-12-03 22:21:33 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex: Group Level Fehler + +r2774 2017-12-03 22:21:07 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbase.tex, + doc/ngerman/tocbasic.tex, doc/ngerman/scrjura.tex: Leerzeichen + +r2773 2017-12-03 22:20:09 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-textmarkup.tex: + Quellcodeumbruch + +r2772 2017-12-03 22:17:46 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-interleafpage.tex: + Querverweise korrigiert + +r2771 2017-12-03 22:17:09 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-fontsize.tex: variablen Text + f?\195?\188r scrextend korrigiert + +r2770 2017-12-03 21:17:05 +0100 kohm: + + * doc/, doc/bin/, doc/bin/genhtmlidx.pl: adapted regular expressions + for new perl + +r2769 2017-12-03 11:56:06 +0100 kohm: + + * scrkernel-bibliography.dtx: bibliography=notoc and + bibliography=totoc in scrartcl fixed + +r2768 2017-12-01 12:47:27 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex: Diverse + Modernisierungen und Anpassungen f?\195?\188r scrletter + +r2767 2017-12-01 11:55:23 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2-experts.tex: Es wird Zeit + die Spuren von scrlettr zu beseitigen ?\226?\128?\166 + +r2766 2017-12-01 11:04:31 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-lists.tex: Anpassungen + f?\195?\188r scrletter + +r2765 2017-12-01 10:24:10 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-footnotes.tex: Anpassungen + f?\195?\188r scrletter + +r2764 2017-12-01 09:41:54 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-interleafpage.tex: + Anpassungen an scrletter + +r2763 2017-11-30 15:53:09 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex, + doc/ngerman/scrbookreportarticle.tex, + doc/ngerman/scrlttr2-experts.tex: diverse Verbesserungen zur besseren + Integration von scrletter + +r2762 2017-11-30 12:57:51 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-parmarkup.tex: Anpassungen + f?\195?\188r scrletter + +r2761 2017-11-29 14:35:28 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex, + doc/ngerman/scrlttr2-experts.tex: diverse Verbesserungen f?\195?\188r + scrletter + +r2760 2017-11-29 12:43:49 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-textmarkup.tex: Anpassungen + f?\195?\188r scrletter + +r2759 2017-11-29 12:23:23 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-fontsize.tex: Anpassungen + f?\195?\188r scrletter + +r2758 2017-11-29 10:43:48 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-typearea.tex: Anpassung + f?\195?\188r scrletter + +r2757 2017-11-29 10:41:01 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-draftmode.tex: Anpassungen + f?\195?\188r scrletter + +r2756 2017-11-29 10:37:42 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-compatibility.tex: missing + empty argument added + +r2755 2017-11-29 10:28:57 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-compatibility.tex: scrletter + behandelt + +r2754 2017-11-29 10:08:52 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-options.tex: fehlendes + Leerzeichen erg?\195?\164nzt + +r2753 2017-11-29 09:58:32 +0100 kohm: + + * scrkernel-pseudolengths.dtx: several \glueexpr added to improve + pseudo lengths + +r2752 2017-11-28 13:04:55 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: + zus?\195?\164tzlicher Text f?\195?\188r die Buchfassung + +r2751 2017-11-28 12:18:12 +0100 kohm: + + * doc/, doc/guide.bib: imakeidx added + +r2750 2017-11-28 11:58:26 +0100 kohm: + + * doc/, doc/guide.bib: supertabular added + +r2749 2017-11-28 11:58:07 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-titles.tex: kosmetische + ?\195?\132nderungen + +r2748 2017-11-28 11:57:32 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: diverse + Korrekturen und Verbesserungen + +r2747 2017-11-28 11:48:19 +0100 kohm: + + * doc/, doc/scrguide.cls: tiny source formatting change + +r2746 2017-11-28 11:03:16 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-parmarkup.tex: \important[i] + beseitigt + +r2745 2017-11-28 10:44:00 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-titles.tex: \important + without i + +r2744 2017-11-28 10:40:32 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-titles.tex: \important + verbessert + +r2743 2017-11-27 16:29:36 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle-experts.tex: + Tippfehler und Stilkorrektur + +r2742 2017-11-27 16:28:15 +0100 kohm: + + * TODO: undefined reference issue + +r2741 2017-11-27 12:02:02 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex, + doc/ngerman/common-dictum.tex, doc/ngerman/common-lists.tex: Diverse + Verbesserungen + +r2740 2017-11-27 10:05:05 +0100 kohm: + + * doc/, doc/scrguide.cls: serveral keywords fixed + +r2739 2017-11-27 09:49:28 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: diverse + Verbesserungen + +r2738 2017-11-27 09:30:16 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: diverse + Verbesserungen + +r2737 2017-11-24 12:30:24 +0100 kohm: + + * doc/, doc/guide.bib, doc/ngerman/, + doc/ngerman/scrbookreportarticle.tex: einige Verbesserungen und + kleinere Erweiterungen + +r2736 2017-11-24 09:46:04 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-footnotes.tex: + Erkl?\195?\164rungen teilweise verschoben + +r2735 2017-11-24 09:45:11 +0100 kohm: + + * doc/, doc/scrguide.cls: additional keywords + +r2734 2017-11-24 09:06:12 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-interleafpage.tex: Umbruch + f?\195?\188r die Buchversion verbessert, Erkl?\195?\164rungen + gestrafft + +r2733 2017-11-23 13:34:18 +0100 kohm: + + * doc/, doc/scrguide.cls, doc/ngerman/, + doc/ngerman/scrbookreportarticle.tex: zus?\195?\164tzliche + Informationen eingef?\195?\188gt + +r2732 2017-11-23 10:47:57 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-parmarkup.tex: + zus?\195?\164tzliche Marginalien + +r2731 2017-11-23 10:04:09 +0100 kohm: + + * scrkernel-tocstyle.dtx: fixed default font setting for page numbers + in ToC of level chapter or + section (if chapter does not exist) + +r2730 2017-11-22 10:41:56 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: + Dokumentation an einige Neuerungen angepasst und Umbruch + f?\195?\188r die + Buchausgabe verbessert + +r2729 2017-11-22 10:40:43 +0100 kohm: + + * doc/, doc/scrguide.cls: additional keywords + +r2728 2017-11-21 13:13:57 +0100 kohm: + + * TODO: new missing translation + +r2727 2017-11-21 13:13:38 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: minimale, + stilistische Verbesserung + +r2726 2017-11-21 13:12:36 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-titles.tex: \frontispiece und + diverse Verbesserungen + +r2725 2017-11-21 12:50:05 +0100 kohm: + + * scrkernel-title.dtx: new \frontispiece + +r2724 2017-11-21 12:07:02 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-titles.tex: + zus?\195?\164tzliche Marginalien + +r2723 2017-11-21 11:43:12 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-textmarkup.tex: + Umbruchoptimierung + +r2722 2017-11-21 11:24:32 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-fontsize.tex: Unklarheiten + beseitigt + +r2721 2017-11-21 11:04:37 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-typearea.tex: Umbruch + verbessert, Seitenzahl hinzugef?\195?\188gt + +r2720 2017-11-21 11:01:09 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/typearea-experts.tex: + Ligaturaufl?\195?\182sung + +r2719 2017-11-21 11:00:29 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer.tex: + Ligaturaufl?\195?\182sung + +r2718 2017-11-21 10:59:56 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer-notecolumn.tex: + Ligaturaufl?\195?\182sung + +r2717 2017-11-21 10:57:08 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-pagestylemanipulation.tex: + Ligaturaufl?\195?\182sung + +r2716 2017-11-21 10:55:31 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer-notecolumn.tex: + Ligaturaufl?\195?\182sung + +r2715 2017-11-21 10:55:12 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/tocbasic.tex: + Ligaturaufl?\195?\182sung + +r2714 2017-11-21 10:52:53 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer-notecolumn.tex: + Ligaturauf"|l?\195?\182sung + +r2713 2017-11-21 10:41:42 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-draftmode.tex: documentation + of new option overfullrule + +r2712 2017-11-21 10:27:02 +0100 kohm: + + * scrkernel-miscellaneous.dtx: new option overfullrule + +r2711 2017-11-21 10:06:01 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-options.tex: Wiederholung + leicht gek?\195?\188rzt + +r2710 2017-11-21 10:05:38 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-compatibility.tex: Umbruch + verbessert + +r2709 2017-11-21 09:03:52 +0100 kohm: + + * tocbasic.dtx: tocbibind warning added + +r2708 2017-11-21 08:03:54 +0100 kohm: + + * scrkernel-miscellaneous.dtx: tocbibind warning + +r2707 2017-11-20 12:43:38 +0100 kohm: + + * TODO, doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: + missing option descriptions added + +r2706 2017-11-20 11:38:54 +0100 kohm: + + * TODO, tocbasic.dtx, doc/, doc/ngerman/, doc/ngerman/tocbasic.tex: + new options "setup" and "unset" for \DeclareNewTOC + +r2705 2017-11-16 15:42:14 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/typearea.tex: Tippfehler [gefunden + von Elke] + +r2704 2017-11-16 09:19:11 +0100 kohm: + + * TODO: less cryptic entry + +r2703 2017-11-16 09:17:02 +0100 kohm: + + * TODO: the classes do use \DeclareNewTOC for lof and lot + +r2702 2017-11-16 09:15:55 +0100 kohm: + + * scrkernel-basics.dtx: the name and the value of the original options + are easily available inside @else@ option + +r2701 2017-11-15 15:02:01 +0100 kohm: + + * scrkernel-floats.dtx, TODO, doc/, doc/scrguide.cls, doc/ngerman/, + doc/ngerman/scrbookreportarticle.tex: new \setcaptionalignment + +r2700 2017-11-15 08:19:59 +0100 kohm: + + * scrkernel-notepaper.dtx, scrkernel-floats.dtx, + scrkernel-letterclassoptions.dtx, TODO, scrkernel-miscellaneous.dtx: + \unskip\strut replaced by new \scr@endstrut + +r2699 2017-11-14 15:39:18 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/typearea.tex: Diverse kleinere und + gr?\195?\182?\195?\159ere Verbesserungen und Anpassungen an aktuelle + KOMA-Script-Versionen + +r2698 2017-11-14 15:04:34 +0100 kohm: + + * doc/, doc/scrguide.cls: \XeTeX added + +r2697 2017-11-14 12:59:35 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/common-options.tex, doc/english/, + doc/english/common-options.tex: note about the scope of \KOMAoption + and \KOMAoptions added + +r2696 2017-11-14 10:14:12 +0100 kohm: + + * doc/, doc/english/, doc/english/introduction.tex: revert last + changes + +r2695 2017-11-14 10:06:55 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/introduction.tex: Anpassung an die + lange vergangene Zeit + +r2694 2017-11-14 09:47:32 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/introduction.tex, doc/english/, + doc/english/introduction.tex: Same sections in German and English + guide + +r2693 2017-11-13 20:37:03 +0100 kohm: + + * TODO: new issue + +r2692 2017-11-13 14:58:12 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex, + doc/ngerman/common-lists.tex: Links improved + +r2691 2017-11-13 14:09:40 +0100 kohm: + + * doc/, doc/scrguide.cls: righttopmark etc. added + +r2690 2017-11-13 13:04:34 +0100 kohm: + + * doc/, doc/scrguide.cls: fix: \FloatStyle in \PageStyle replaced by + \PageStyle + +r2689 2017-11-13 12:58:55 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex, + doc/ngerman/common-footnotes.tex, doc/ngerman/common-textmarkup.tex: + references fixed + +r2688 2017-11-13 10:15:20 +0100 kohm: + + * doc/, doc/guide.bib, doc/ngerman/, + doc/ngerman/scrlttr2-experts.tex, doc/english/, + doc/english/scrlttr2-experts.tex: scrlettr linked to + koma-script-obsolete + +r2687 2017-11-13 09:36:26 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrlayer.tex: \textnote inside \item + moved outside + +r2686 2017-11-13 09:35:20 +0100 kohm: + + * doc/, doc/ngerman/, doc/ngerman/tocbasic.tex: \textnote inside + desclist deactivated + +r2685 2017-10-13 16:17:16 +0200 kohm: + + * scrkernel-bibliography.dtx: new definition of \bibliography@heding + used by \bib@heading + +r2684 2017-10-13 15:35:13 +0200 kohm: + + * scrkernel-index.dtx, scrlayer.dtx, scrkernel-bibliography.dtx, + scrmain.ins: \@mkright, \@mkleft, \@mkdouble added to and used by the + KOMA-Script classes + +r2683 2017-10-10 16:10:02 +0200 kohm: + + * scrkernel-floats.dtx, scrkernel-listsof.dtx, tocbasic.dtx: major + change: table/table* reimplementation using \DeclareNewTOC + +r2682 2017-10-10 14:57:37 +0200 kohm: + + * scrkernel-floats.dtx, scrkernel-listsof.dtx, tocbasic.dtx: major + change: figure/figure* reimplementation using \DeclareNewTOC + +r2681 2017-09-28 07:45:58 +0200 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle-experts.tex, + doc/english/, doc/english/scrbookreportarticle-experts.tex: + \DeclareSectionCommand attibute innerskip of chapter is + 0.5\baselineskip + +r2680 2017-09-28 07:45:12 +0200 kohm: + + * scrkernel-paragraphs.dtx, tocbasic.dtx: typo fix + +r2679 2017-09-28 07:44:43 +0200 kohm: + + * TODO: new nice to have + +r2678 2017-09-23 08:51:25 +0200 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrwfile.tex, doc/english/, + doc/english/scrwfile.tex: reference fixed + +r2677 2017-09-13 14:12:17 +0200 kohm: + + * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex, + doc/english/, doc/english/scrbookreportarticle.tex: Typofix [TK] + +r2676 2017-09-07 17:43:34 +0200 kohm: + + * TODO, doc/, doc/ngerman/, + doc/ngerman/scrbookreportarticle-experts.tex, doc/english/, + doc/english/scrbookreportarticle-experts.tex: + \partlineswithprefixformat added + +r2675 2017-09-07 16:42:04 +0200 kohm: + + * scrkernel-sections.dtx: new \partlineswithprefixformat + +r2674 2017-09-07 11:35:17 +0200 kohm: + + * scrkernel-version.dtx, scrkernel-compatibility.dtx: prepared for + 3.25 BETA + r2673 2017-09-07 10:22:59 +0200 kohm: * releaselist.txt: prepared for release v3.24 @@ -24,7 +1568,7 @@ r2669 2017-08-10 13:11:11 +0200 kohm: r2667 2017-08-10 13:04:15 +0200 kohm: - * doc/, doc/scrpage2.tex: \Xmp… added + * doc/, doc/scrpage2.tex: \Xmp?\226?\128?\166 added r2666 2017-08-10 12:24:54 +0200 kohm: @@ -172,7 +1716,7 @@ r2640 2017-05-08 11:36:55 +0200 kohm: r2639 2017-05-08 08:54:21 +0200 kohm: - * scrlayer.dtx, TODO: \layer… macros using \dimexpr + * scrlayer.dtx, TODO: \layer?\226?\128?\166 macros using \dimexpr r2638 2017-05-06 19:17:09 +0200 kohm: @@ -195,7 +1739,7 @@ r2634 2017-05-06 17:48:55 +0200 kohm: * scrkernel-fonts.dtx, doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle-experts.tex, doc/english/, doc/english/scrbookreportarticle-experts.tex: more robust - reimplementation of \use…ofkomafont + reimplementation of \use?\226?\128?\166ofkomafont r2633 2017-05-05 19:05:27 +0200 kohm: @@ -464,7 +2008,7 @@ r2578 2017-02-04 13:18:09 +0100 kohm: r2577 2017-02-01 07:33:09 +0100 kohm: * doc/, doc/ngerman/, doc/ngerman/common-options.tex: Fehlender - Halbsatz ergänzt [HV] + Halbsatz erg?\195?\164nzt [HV] r2576 2017-01-30 20:46:35 +0100 kohm: @@ -581,7 +2125,7 @@ r2566 2016-12-28 18:22:56 +0100 kohm: doc/ngerman/scrjura.tex, doc/ngerman/scrbookreportarticle-experts.tex, doc/ngerman/common-pagestylemanipulation.tex, - doc/ngerman/common-titles.tex: Links für Font-Elemente + doc/ngerman/common-titles.tex: Links f?\195?\188r Font-Elemente r2565 2016-12-21 18:25:47 +0100 kohm: @@ -816,7 +2360,8 @@ r2541 2016-11-21 12:05:13 +0100 kohm: doc/ngerman/scrbookreportarticle-experts.tex, doc/ngerman/common-oddorevenpage.tex, doc/ngerman/scrlfile.tex, doc/ngerman/scrwfile.tex, doc/ngerman/scraddr.tex: - \autopageref{desc:…} replaced by \DescPageRef{…} + \autopageref{desc:?\226?\128?\166} replaced by + \DescPageRef{?\226?\128?\166} r2540 2016-11-21 11:55:10 +0100 kohm: @@ -1326,12 +2871,13 @@ r2480 2016-06-14 09:45:01 +0200 kohm: * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle-experts.tex, doc/english/, doc/english/scrbookreportarticle-experts.tex: additional - info about toc… options + info about toc?\226?\128?\166 options r2479 2016-06-14 09:11:22 +0200 kohm: * doc/, doc/ngerman/, doc/ngerman/tocbasic.tex, doc/english/, - doc/english/tocbasic.tex: additional info about tocentry… options + doc/english/tocbasic.tex: additional info about + tocentry?\226?\128?\166 options r2478 2016-06-13 08:53:07 +0200 kohm: @@ -1342,7 +2888,7 @@ r2477 2016-06-12 11:52:43 +0200 kohm: * TODO, scrkernel-sections.dtx, tocbasic.dtx, doc/, doc/ngerman/, doc/ngerman/tocbasic.tex, doc/english/, doc/english/tocbasic.tex: - prefix tocentry instead (or additional to) prefix toc + prefix tocentry instead (or additional to)?\194?\160prefix toc r2476 2016-06-12 08:32:29 +0200 kohm: @@ -1354,7 +2900,8 @@ r2475 2016-06-09 09:51:01 +0200 kohm: r2474 2016-06-06 16:41:04 +0200 kohm: - * scrkernel-tocstyle.dtx: Summary: handle also long \ragged…entry + * scrkernel-tocstyle.dtx: Summary: handle also long + \ragged?\226?\128?\166entry r2473 2016-06-06 16:38:21 +0200 kohm: @@ -1412,8 +2959,8 @@ r2463 2016-05-19 09:27:47 +0200 kohm: r2462 2016-05-19 09:18:47 +0200 kohm: * scrkernel-notepaper.dtx, scrkernel-miscellaneous.dtx: - Summary: scrlttr2 provides option egregdoesnotlikesansseriftitles - too + Summary:?\194?\160scrlttr2 provides option + egregdoesnotlikesansseriftitles too r2461 2016-05-19 09:17:15 +0200 kohm: @@ -1441,7 +2988,7 @@ r2457 2016-05-09 11:38:14 +0200 kohm: r2456 2016-05-09 11:37:44 +0200 kohm: * doc/, doc/ngerman/, doc/ngerman/scrjura.tex: Summary: - Überflüssiges \ProvidesFile entfernt + ?\195?\156berfl?\195?\188ssiges \ProvidesFile entfernt r2455 2016-05-09 11:36:06 +0200 kohm: @@ -1500,8 +3047,8 @@ r2444 2016-05-05 09:16:53 +0200 kohm: r2443 2016-05-04 10:34:46 +0200 kohm: - * doc/, doc/ngerman/, doc/ngerman/scrjura.tex: Hinweis auf zusätzlich - unterstützte Sprachen + * doc/, doc/ngerman/, doc/ngerman/scrjura.tex: Hinweis auf + zus?\195?\164tzlich unterst?\195?\188tzte Sprachen r2442 2016-05-04 10:19:38 +0200 kohm: @@ -1521,7 +3068,7 @@ r2440 2016-04-29 17:59:32 +0200 kohm: r2439 2016-04-29 07:56:21 +0200 kohm: * doc/, doc/ngerman/, doc/ngerman/common-fontsize.tex: Summary: - fehlendes »Klasse« ergänzt + fehlendes ?\194?\187Klasse?\194?\171 erg?\195?\164nzt r2438 2016-04-27 12:58:21 +0200 kohm: @@ -1760,7 +3307,8 @@ r2393 2016-03-24 10:47:53 +0100 kohm: r2392 2016-03-23 12:56:36 +0100 kohm: * doc/, doc/ngerman/, doc/ngerman/tocbasic.tex: Summary: - \LastTOCLevelWas… and \TOCEntryStyle…InitCode + \LastTOCLevelWas?\226?\128?\166 and + \TOCEntryStyle?\226?\128?\166InitCode r2391 2016-03-23 08:35:30 +0100 kohm: @@ -1882,7 +3430,7 @@ r2368 2016-03-10 11:20:56 +0100 kohm: r2367 2016-03-09 18:14:56 +0100 kohm: * doc/, doc/ngerman/, doc/ngerman/guide-ngerman.tex: Summary: neue - Trennausnahme für Eintragsebene + Trennausnahme f?\195?\188r Eintragsebene r2366 2016-03-09 18:09:14 +0100 kohm: @@ -2298,7 +3846,7 @@ r2266 2015-11-18 10:41:05 +0100 kohm: r2265 2015-11-18 10:40:24 +0100 kohm: * TODO, scrkernel-basics.dtx: \FamilyExecuteOptions has a special - handling für member option @else@ + handling f?\195?\188r member option @else@ r2264 2015-11-17 18:26:57 +0100 kohm: @@ -2404,7 +3952,7 @@ r2244 2015-10-21 10:02:33 +0200 kohm: r2243 2015-10-21 09:45:18 +0200 kohm: - * TODO: removed: \if… issue + * TODO: removed: \if?\226?\128?\166 issue r2242 2015-10-21 09:44:26 +0200 kohm: @@ -2449,7 +3997,7 @@ r2233 2015-10-19 11:53:52 +0200 kohm: r2232 2015-10-19 10:29:26 +0200 kohm: - * TODO: new general issue with \ifis… + * TODO: new general issue with \ifis?\226?\128?\166 r2231 2015-10-19 10:13:54 +0200 kohm: @@ -2498,8 +4046,8 @@ r2222 2015-10-08 08:18:34 +0200 kohm: r2221 2015-10-07 12:17:20 +0200 kohm: - * scrkernel-sections.dtx: new: \toclevel@… will be set by - \DeclareSectionCommand etc. if it could be usefull + * scrkernel-sections.dtx: new: \toclevel@?\226?\128?\166 will be set + by \DeclareSectionCommand etc. if it could be usefull r2220 2015-10-07 09:30:29 +0200 kohm: @@ -2586,9 +4134,10 @@ r2203 2015-09-15 11:32:08 +0200 kohm: r2202 2015-09-14 10:57:28 +0200 kohm: - * TODO, doc/, doc/ngerman/, doc/ngerman/scrlayer.tex: neu: Doku für - mode=picture einschl. der dafür reservierten neuen Anweisungen new: - Doku für \layervalign und \layerhalign + * TODO, doc/, doc/ngerman/, doc/ngerman/scrlayer.tex: neu: Doku + f?\195?\188r mode=picture einschl. der daf?\195?\188r reservierten + neuen Anweisungen new: Doku f?\195?\188r \layervalign und + \layerhalign r2201 2015-09-14 10:54:18 +0200 kohm: @@ -2658,7 +4207,8 @@ r2189 2015-08-29 12:11:08 +0200 kohm: r2188 2015-08-28 16:54:24 +0200 kohm: * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle-experts.tex: - change: Stichwortverzeichniseinträge für Gliederungsstile + change: Stichwortverzeichniseintr?\195?\164ge f?\195?\188r + Gliederungsstile r2187 2015-08-27 21:14:32 +0200 kohm: @@ -2765,8 +4315,8 @@ r2170 2015-07-27 11:52:22 +0200 kohm: r2169 2015-07-26 12:14:32 +0200 kohm: * TODO, doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex: new: - Dokumentation von Zähler letter und Anweisungen \thisletter und - \letterlastpage + Dokumentation von Z?\195?\164hler letter und Anweisungen \thisletter + und \letterlastpage r2168 2015-07-26 11:32:03 +0200 kohm: @@ -2859,7 +4409,8 @@ r2151 2015-07-03 11:25:42 +0200 kohm: * scrkernel-language.dtx: fix: emergency code for brain dead language default settings (like hyphen.cfg of babel) now executes all - commands using \@nameuse and also executes \@nameuse{extra…} + commands using \@nameuse and also executes + \@nameuse{extra?\226?\128?\166} r2150 2015-07-02 10:10:21 +0200 kohm: @@ -3013,7 +4564,8 @@ r2122 2015-06-03 10:05:35 +0200 kohm: r2121 2015-06-02 10:12:38 +0200 kohm: - * tocbasic.dtx: fix: expansion of \…name and \…listname + * tocbasic.dtx: fix: expansion of \?\226?\128?\166name and + \?\226?\128?\166listname r2120 2015-05-24 12:06:25 +0200 kohm: @@ -3030,7 +4582,7 @@ r2118 2015-05-22 17:34:34 +0200 kohm: * scrhack.dtx: change: deactivate hyperref hack if \hy@insteadofrefstepcounter has been - defined, i.e., by a KOMA-Script class ≥ 3.18. + defined, i.e., by a KOMA-Script class ?\226?\137?\165 3.18. r2117 2015-05-22 16:22:03 +0200 kohm: @@ -3356,12 +4908,12 @@ r2059 2015-03-31 10:01:37 +0200 kohm: r2058 2015-03-31 09:04:03 +0200 kohm: - * scrkernel-sections.dtx: fix: \protect usage of \…format in - \@seccntformat + * scrkernel-sections.dtx: fix: \protect usage of + \?\226?\128?\166format in \@seccntformat r2057 2015-03-31 08:29:00 +0200 kohm: - * TODO: added: \…format issue + * TODO: added: \?\226?\128?\166format issue r2056 2015-03-30 10:24:20 +0200 kohm: @@ -3381,14 +4933,16 @@ r2053 2015-03-27 10:25:57 +0100 kohm: * TODO, doc/, doc/english/, doc/english/scrbookreportarticle-experts.tex: change: missing - translations at \DeclareSectionCommand and \chapterhead…vskip + translations at \DeclareSectionCommand and + \chapterhead?\226?\128?\166vskip r2052 2015-03-27 09:07:21 +0100 kohm: * TODO, doc/, doc/ngerman/, - doc/ngerman/scrbookreportarticle-experts.tex: change: Änderungen bei - der Doku von \DeclareSectionCommand und Auswirkungen auf - \chapterhead…vskip vervollständigt + doc/ngerman/scrbookreportarticle-experts.tex: change: + ?\195?\132nderungen bei der Doku von \DeclareSectionCommand und + Auswirkungen auf \chapterhead?\226?\128?\166vskip + vervollst?\195?\164ndigt r2051 2015-03-27 09:06:19 +0100 kohm: @@ -3402,8 +4956,8 @@ r2050 2015-03-26 11:54:11 +0100 kohm: r2049 2015-03-26 11:52:40 +0100 kohm: * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle-experts.tex: - change: Stilbeschreibung und Tabellen für stilabhängige - Einstellungen + change: Stilbeschreibung und Tabellen f?\195?\188r + stilabh?\195?\164ngige Einstellungen r2048 2015-03-26 10:51:38 +0100 kohm: @@ -3451,7 +5005,7 @@ r2040 2015-03-24 17:58:57 +0100 kohm: r2039 2015-03-24 17:14:55 +0100 kohm: - * scrkernel-sections.dtx: fix: \setlenght → \setlength + * scrkernel-sections.dtx: fix: \setlenght ?\226?\134?\146 \setlength r2038 2015-03-24 11:13:55 +0100 kohm: @@ -3463,7 +5017,8 @@ r2037 2015-03-24 11:09:29 +0100 kohm: r2036 2015-03-24 11:08:54 +0100 kohm: - * scrkernel-typearea.dtx: fix: \KOMA@kav@addkey → \KOMA@kav@add + * scrkernel-typearea.dtx: fix: \KOMA@kav@addkey ?\226?\134?\146 + \KOMA@kav@add r2035 2015-03-24 11:02:05 +0100 kohm: @@ -3533,7 +5088,7 @@ r2023 2015-03-23 08:17:44 +0100 kohm: r2022 2015-03-23 08:00:03 +0100 kohm: * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle-experts.tex: - changes: vor … zuvor war doppelt gemoppelt + changes: vor ?\226?\128?\166 zuvor war doppelt gemoppelt r2021 2015-03-22 11:09:00 +0100 kohm: @@ -3688,7 +5243,8 @@ r1999 2015-03-12 11:58:30 +0100 kohm: r1998 2015-03-11 23:09:38 +0100 kohm: - * scrkernel-compatibility.dtx: fix: \scr@v@is@… added to scrextend + * scrkernel-compatibility.dtx: fix: \scr@v@is@?\226?\128?\166 added to + scrextend r1997 2015-03-11 20:19:06 +0100 kohm: @@ -3751,7 +5307,7 @@ r1984 2015-03-10 09:38:06 +0100 kohm: r1983 2015-03-10 09:32:04 +0100 kohm: * scrkernel-compatibility.dtx: new: option value storage new: internal - \scr@v@is@… to check for compatibility + \scr@v@is@?\226?\128?\166 to check for compatibility r1982 2015-03-10 08:53:25 +0100 kohm: @@ -3852,8 +5408,8 @@ r1964 2015-02-27 09:33:54 +0100 kohm: r1963 2015-02-27 09:04:57 +0100 kohm: - * scrkernel-basics.dtx: change: \KOMA@kav@x… uses \protected@edef - instead of \edef + * scrkernel-basics.dtx: change: \KOMA@kav@x?\226?\128?\166 uses + \protected@edef instead of \edef r1962 2015-02-26 09:34:33 +0100 kohm: @@ -3900,9 +5456,9 @@ r1955 2015-02-23 17:55:49 +0100 kohm: * scrkernel-compatibility.dtx, TODO, scrkernel-sections.dtx, doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex, doc/ngerman/common-pagestylemanipulation.tex, doc/english/, - doc/english/scrbookreportarticle.tex: change: use \sectionformat … - \subparagraphformat instead of \othersectionlevelsformat if version - >= 3.17 + doc/english/scrbookreportarticle.tex: change: use \sectionformat + ?\226?\128?\166 \subparagraphformat instead of + \othersectionlevelsformat if version >= 3.17 r1954 2015-02-23 17:53:40 +0100 kohm: @@ -4094,13 +5650,13 @@ r1918 2015-01-28 11:03:48 +0100 kohm: r1917 2015-01-28 08:32:30 +0100 kohm: * doc/, doc/ngerman/, doc/ngerman/common-pagestylemanipulation.tex: - fix: Fehler in den neuen Erklärungen beseitigt [Elke] + fix: Fehler in den neuen Erkl?\195?\164rungen beseitigt [Elke] r1916 2015-01-27 10:06:12 +0100 kohm: * TODO, doc/, doc/ngerman/, doc/ngerman/scrlayer.tex, - doc/ngerman/common-pagestylemanipulation.tex: deutsche Erklärung - einiger Neuheiten ab Version 3.16 + doc/ngerman/common-pagestylemanipulation.tex: deutsche + Erkl?\195?\164rung einiger Neuheiten ab Version 3.16 r1915 2015-01-27 08:45:41 +0100 kohm: @@ -4114,7 +5670,7 @@ r1914 2015-01-27 08:45:11 +0100 kohm: r1913 2015-01-26 21:12:39 +0100 kohm: - * TODO: fehlende Erklärungen in der Anleitung + * TODO: fehlende Erkl?\195?\164rungen in der Anleitung r1912 2015-01-26 21:11:06 +0100 kohm: @@ -4219,8 +5775,8 @@ r1892 2014-12-23 18:57:43 +0100 kohm: r1891 2014-12-23 18:19:04 +0100 kohm: - * scrkernel-sections.dtx: fix: not \…toclevel and not - \scr@…@tocdepth but \…toclevel + * scrkernel-sections.dtx: fix: not \?\226?\128?\166toclevel and not + \scr@?\226?\128?\166@tocdepth but \?\226?\128?\166toclevel r1890 2014-12-22 08:58:28 +0100 kohm: @@ -4286,7 +5842,7 @@ r1879 2014-12-16 08:34:56 +0100 kohm: r1878 2014-12-15 08:01:19 +0100 kohm: * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle-experts.tex: - Neuer Anlauf für bereits verkorksten Satz. + Neuer Anlauf f?\195?\188r bereits verkorksten Satz. r1877 2014-12-12 09:55:47 +0100 kohm: @@ -4371,12 +5927,12 @@ r1863 2014-12-07 14:09:02 +0100 kohm: * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle-experts.tex: Die Spezialbedeutungen negativer Werte von `beforeskip' und `afterskip' bei `\DeclareSectionCommand' auf den Stil section - bezogen. Die Verwendung für chapter und part ohne Stil-Angabe - absichtlich noch nicht 100% klar dokumentiert. + bezogen. Die Verwendung f?\195?\188r chapter und part ohne + Stil-Angabe absichtlich noch nicht 100% klar dokumentiert. r1862 2014-12-05 08:12:21 +0100 kohm: - * TODO: tocstyle doesn't need \…toclevel + * TODO: tocstyle doesn't need \?\226?\128?\166toclevel r1861 2014-12-05 08:08:20 +0100 kohm: @@ -4528,8 +6084,8 @@ r1833 2014-11-21 15:57:23 +0100 kohm: r1832 2014-11-21 15:56:40 +0100 kohm: - * scrlayer.dtx: change: co-using \…numdepth of the KOMA-Script - classes instead of own \…level + * scrlayer.dtx: change: co-using \?\226?\128?\166numdepth of the + KOMA-Script classes instead of own \?\226?\128?\166level r1831 2014-11-21 12:47:37 +0100 kohm: @@ -4678,7 +6234,7 @@ r1802 2014-10-09 10:17:20 +0200 kohm: r1801 2014-10-09 08:08:31 +0200 kohm: * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex: - Verbesserungsvorschläge von Elke + Verbesserungsvorschl?\195?\164ge von Elke r1800 2014-10-07 08:53:12 +0200 kohm: @@ -4765,7 +6321,8 @@ r1784 2014-08-31 11:40:21 +0200 kohm: r1783 2014-08-18 12:54:31 +0200 kohm: - * scrwfile.dtx: use ``…'' instead of »…« + * scrwfile.dtx: use ``?\226?\128?\166'' instead of + ?\194?\187?\226?\128?\166?\194?\171 r1782 2014-08-18 12:48:22 +0200 kohm: @@ -4773,8 +6330,9 @@ r1782 2014-08-18 12:48:22 +0200 kohm: r1781 2014-08-18 12:23:36 +0200 kohm: - * scrlayer-scrpage.dtx: fix: layer names …head.odd, …head.even, - …foot.odd, and …foot.even should + * scrlayer-scrpage.dtx: fix: layer names ?\226?\128?\166head.odd, + ?\226?\128?\166head.even, ?\226?\128?\166foot.odd, and + ?\226?\128?\166foot.even should correspond with even and odd pages (see manual) [Elke] @@ -4999,8 +6557,8 @@ r1740 2014-03-14 16:43:30 +0100 kohm: r1739 2014-03-14 15:47:05 +0100 kohm: * manifest.txt, scrlayer-notecolumn.dtx, doc/, doc/Makefile.guide, - doc/english/, doc/english/scrlayer-notecolumn-example.tex, - doc/english/Makefile, doc/english/scrlayer-notecolumn.tex: translated + doc/english/, doc/english/Makefile, + doc/english/scrlayer-notecolumn.tex: translated scrlayer-notecolumn.tex instead of generated r1738 2014-03-14 08:22:55 +0100 kohm: @@ -5009,8 +6567,8 @@ r1738 2014-03-14 08:22:55 +0100 kohm: r1737 2014-03-13 17:33:07 +0100 kohm: - * doc/, doc/ngerman/, doc/ngerman/scrlayer-notecolumn.tex: Einträge - in einer Tabelle sortiert + * doc/, doc/ngerman/, doc/ngerman/scrlayer-notecolumn.tex: + Eintr?\195?\164ge in einer Tabelle sortiert r1736 2014-03-13 08:41:11 +0100 kohm: @@ -5020,7 +6578,7 @@ r1735 2014-03-12 13:21:08 +0100 kohm: * TODO, doc/, doc/ngerman/, doc/ngerman/scrbase.tex, doc/english/, doc/english/scrbase.tex: translation of - \FamilyCounterKey…\FamilyLengthKey and elimination of + \FamilyCounterKey?\226?\128?\166\FamilyLengthKey and elimination of \Family@Options r1734 2014-03-12 12:19:07 +0100 kohm: @@ -5032,13 +6590,13 @@ r1733 2014-03-12 12:11:20 +0100 kohm: * TODO, doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex, doc/english/, doc/english/scrbookreportarticle.tex: translation of - user documentation of \partnumdepth … \subparagraphnumdepth, - \ifnumbered, \ifunnumbered + user documentation of \partnumdepth ?\226?\128?\166 + \subparagraphnumdepth, \ifnumbered, \ifunnumbered r1732 2014-03-12 12:05:05 +0100 kohm: * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: ein - \OnlyAt in der Erklärung zu tocdepth ergänzt + \OnlyAt in der Erkl?\195?\164rung zu tocdepth erg?\195?\164nzt r1731 2014-03-08 09:00:38 +0100 kohm: @@ -5133,8 +6691,8 @@ r1715 2014-03-01 13:05:30 +0100 kohm: r1714 2014-02-28 16:31:14 +0100 kohm: * doc/, doc/ngerman/, doc/ngerman/scrbase.tex, - doc/ngerman/scrbookreportarticle-experts.tex: Index-Eintrag für - \ifstr verbessert + doc/ngerman/scrbookreportarticle-experts.tex: Index-Eintrag + f?\195?\188r \ifstr verbessert r1713 2014-02-27 17:36:50 +0100 kohm: @@ -5198,7 +6756,7 @@ r1698 2014-02-26 08:25:13 +0100 kohm: r1697 2014-02-21 18:21:16 +0100 kohm: * doc/, doc/ngerman/, doc/ngerman/typearea.tex: fetten Indexeintrag - für den Bundsteg durch einen normalen ersetzt + f?\195?\188r den Bundsteg durch einen normalen ersetzt r1696 2014-02-17 10:22:47 +0100 kohm: @@ -5213,12 +6771,12 @@ r1695 2014-02-17 10:10:45 +0100 kohm: r1694 2014-02-17 08:20:04 +0100 kohm: * doc/, doc/plength.dtx: firstfoot and firsthead are variable now - [patch by Michael Käufl] + [patch by Michael K?\195?\164ufl] r1693 2014-02-17 08:18:44 +0100 kohm: * doc/, doc/ngerman/, doc/ngerman/typearea.tex: Leerzeichenfehler - [Michael Käufl] + [Michael K?\195?\164ufl] r1692 2014-02-14 08:09:57 +0100 kohm: @@ -5232,18 +6790,18 @@ r1691 2014-02-14 08:08:07 +0100 kohm: r1690 2014-02-13 08:30:22 +0100 kohm: - * doc/, doc/ngerman/, doc/ngerman/typearea.tex: Index-Eintrag für - Kopf- und Fuß-Höhe + * doc/, doc/ngerman/, doc/ngerman/typearea.tex: Index-Eintrag + f?\195?\188r Kopf- und Fu?\195?\159-H?\195?\182he r1689 2014-02-13 08:29:19 +0100 kohm: * doc/, doc/ngerman/, doc/ngerman/scrlayer-scrpage.tex: Index-Eintrag - für Fuß-Breite + f?\195?\188r Fu?\195?\159-Breite r1688 2014-02-13 08:28:20 +0100 kohm: * doc/, doc/ngerman/, doc/ngerman/common-headfootheight.tex: - Index-Eintrag für Kopf- und Fuß-Höhe + Index-Eintrag f?\195?\188r Kopf- und Fu?\195?\159-H?\195?\182he r1687 2014-02-12 15:28:07 +0100 kohm: @@ -5258,17 +6816,17 @@ r1686 2014-02-12 15:04:23 +0100 kohm: r1685 2014-02-12 15:02:53 +0100 kohm: * doc/, doc/ngerman/, doc/ngerman/scrlttr2-experts.tex: Indexeintrag - für version=2.9t und version=2.9u entfernt + f?\195?\188r version=2.9t und version=2.9u entfernt r1684 2014-02-10 10:14:06 +0100 kohm: * doc/, doc/ngerman/, doc/ngerman/scrlttr2-experts.tex: Tschechisch in - der Liste der Sprachen aufgeführt + der Liste der Sprachen aufgef?\195?\188hrt r1683 2014-02-10 10:10:37 +0100 kohm: - * doc/, doc/ngerman/, doc/ngerman/scrlttr2-experts.tex: Doku für - Tschechisch + * doc/, doc/ngerman/, doc/ngerman/scrlttr2-experts.tex: Doku + f?\195?\188r Tschechisch r1682 2014-02-10 10:01:35 +0100 kohm: @@ -5312,12 +6870,12 @@ r1675 2014-02-03 08:37:48 +0100 mjk: r1674 2014-01-31 13:18:11 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/scrlayer-scrpage-experts.tex: - Korrekturen und Wünsche von Elke + Korrekturen und W?\195?\188nsche von Elke r1673 2014-01-31 13:17:07 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/guide-ngerman.tex: Trennausnahme - für Hintergrundebene(n) + f?\195?\188r Hintergrundebene(n) r1672 2014-01-30 15:13:25 +0100 mjk: @@ -5331,7 +6889,7 @@ r1671 2014-01-30 14:38:17 +0100 mjk: r1670 2014-01-30 13:25:27 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/scrbase.tex: noch zwei kleine - Änderungen auf Elkes Hinweise + ?\195?\132nderungen auf Elkes Hinweise r1669 2014-01-30 13:17:20 +0100 mjk: @@ -5347,7 +6905,8 @@ r1667 2014-01-30 13:11:54 +0100 mjk: r1666 2014-01-30 13:11:16 +0100 mjk: - * doc/, doc/ngerman/, doc/ngerman/scrwfile.tex: Noch ein Tippfähler + * doc/, doc/ngerman/, doc/ngerman/scrwfile.tex: Noch ein + Tippf?\195?\164hler r1665 2014-01-30 12:45:14 +0100 mjk: @@ -5361,7 +6920,7 @@ r1664 2014-01-30 12:38:00 +0100 mjk: r1663 2014-01-30 12:04:28 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/scrwfile.tex: diverse Korrekturen - von Elke und eine Ergänzung von mir + von Elke und eine Erg?\195?\164nzung von mir r1662 2014-01-30 11:44:20 +0100 mjk: @@ -5398,7 +6957,8 @@ r1656 2014-01-28 09:11:31 +0100 mjk: r1655 2014-01-28 08:46:12 +0100 mjk: * scrjura.dtx: \contract@sentence verwendet nun \textsuperscript und - ermöglicht die Trennung des erstes Wortes nach einer Satzmarkierung + erm?\195?\182glicht die Trennung des erstes Wortes nach einer + Satzmarkierung r1654 2014-01-24 19:11:48 +0100 mjk: @@ -5504,7 +7064,7 @@ r1634 2014-01-21 10:30:39 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex, doc/ngerman/scrlayer-scrpage.tex, doc/ngerman/common-textmarkup.tex: - Korrekturen und Vorschläge von Elke + Korrekturen und Vorschl?\195?\164ge von Elke r1633 2014-01-21 09:03:32 +0100 mjk: @@ -5515,8 +7075,9 @@ r1633 2014-01-21 09:03:32 +0100 mjk: r1632 2014-01-20 17:18:42 +0100 mjk: - * scrkernel-basics.dtx: use \setkeys{…}{{\CurrentOption}} instead if - \setkeys{…}{\CurrentOption} + * scrkernel-basics.dtx: use + \setkeys{?\226?\128?\166}{{\CurrentOption}} instead if + \setkeys{?\226?\128?\166}{\CurrentOption} r1631 2014-01-20 10:27:14 +0100 mjk: @@ -5528,8 +7089,9 @@ r1630 2014-01-20 09:45:29 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex, doc/ngerman/scrlayer-scrpage.tex, doc/ngerman/scrlttr2-experts.tex, - doc/ngerman/common-textmarkup.tex: Einige Verbesserungsvorschläge von - Elke und ein paar Umbruchänderungen + doc/ngerman/common-textmarkup.tex: Einige + Verbesserungsvorschl?\195?\164ge von Elke und ein paar + Umbruch?\195?\164nderungen r1629 2014-01-17 11:58:39 +0100 mjk: @@ -5549,13 +7111,14 @@ r1627 2014-01-16 13:50:27 +0100 mjk: r1626 2014-01-16 12:43:39 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: - Beispielseite mit einer verfügbaren Abbildung aus Paket mwe. + Beispielseite mit einer verf?\195?\188gbaren Abbildung aus Paket + mwe. r1625 2014-01-16 10:00:54 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex, doc/ngerman/scrbookreportarticle.tex, doc/ngerman/scrlayer.tex: - kleinere Anpassungen (Indexeinträge) + kleinere Anpassungen (Indexeintr?\195?\164ge) r1624 2014-01-15 10:31:27 +0100 mjk: @@ -5668,12 +7231,12 @@ r1606 2014-01-09 11:50:16 +0100 mjk: * doc/, doc/scrguide.cls, doc/ngerman/, doc/ngerman/scrlayer-scrpage-experts.tex, doc/ngerman/common-pagestylemanipulation.tex: diverse Korrekturen und - Optimierungen für die nächste Auflage + Optimierungen f?\195?\188r die n?\195?\164chste Auflage r1605 2014-01-09 09:55:07 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/typearea.tex: gleich noch das Datum - geändert + ge?\195?\164ndert r1604 2014-01-09 09:54:44 +0100 mjk: @@ -5718,8 +7281,8 @@ r1597 2014-01-03 13:57:42 +0100 mjk: r1596 2014-01-02 20:00:08 +0100 mjk: * doc/, doc/scrguide.cls, doc/ngerman/, doc/ngerman/scrlayer.tex: - diverse Anpassungen für kritische Umbrüche in der nächsten - Buchauflage + diverse Anpassungen f?\195?\188r kritische Umbr?\195?\188che in der + n?\195?\164chsten Buchauflage r1595 2014-01-02 11:36:25 +0100 mjk: @@ -5732,8 +7295,8 @@ r1594 2014-01-01 15:56:30 +0100 mjk: * TODO, doc/, doc/scrguide.cls, doc/ngerman/, doc/ngerman/scrbase.tex, doc/ngerman/common-marginpar.tex, doc/ngerman/tocbasic.tex, doc/ngerman/scrlfile.tex: einige - Erklärungen ergänzt und den Umbruch für die nächste Buchauflage - optimiert + Erkl?\195?\164rungen erg?\195?\164nzt und den Umbruch f?\195?\188r + die n?\195?\164chste Buchauflage optimiert r1593 2013-12-31 12:58:50 +0100 mjk: @@ -5775,9 +7338,8 @@ r1586 2013-12-28 18:17:15 +0100 mjk: r1585 2013-12-28 17:57:29 +0100 mjk: - * doc/, doc/ngerman/, doc/ngerman/scrlttr2examples.dtx, doc/english/, - doc/english/scrlttr2examples.dtx: current ghostscript does not find - Charter but Bitstream-Charter + * doc/, doc/ngerman/, doc/ngerman/scrlttr2examples.dtx, doc/english/: + current ghostscript does not find Charter but Bitstream-Charter r1584 2013-12-28 16:29:11 +0100 mjk: @@ -5786,8 +7348,8 @@ r1584 2013-12-28 16:29:11 +0100 mjk: r1583 2013-12-28 16:27:34 +0100 mjk: - * doc/, doc/ngerman/, doc/ngerman/scrlfile.tex: Umbruch für die - nächste Buchauflage + * doc/, doc/ngerman/, doc/ngerman/scrlfile.tex: Umbruch f?\195?\188r + die n?\195?\164chste Buchauflage r1582 2013-12-24 11:13:55 +0100 mjk: @@ -5833,13 +7395,13 @@ r1573 2013-12-20 10:59:10 +0100 mjk: r1572 2013-12-20 10:45:17 +0100 mjk: - * doc/, doc/ngerman/, doc/ngerman/common-textmarkup.tex: markup für - \color + * doc/, doc/ngerman/, doc/ngerman/common-textmarkup.tex: markup + f?\195?\188r \color r1571 2013-12-20 09:51:13 +0100 mjk: - * doc/, doc/ngerman/, doc/ngerman/scraddr.tex: Warnung bezüglich - \KOMAoptions und \KOMAoption + * doc/, doc/ngerman/, doc/ngerman/scraddr.tex: Warnung + bez?\195?\188glich \KOMAoptions und \KOMAoption r1570 2013-12-20 09:48:29 +0100 mjk: @@ -5897,7 +7459,7 @@ r1558 2013-12-17 14:46:13 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/scrlayer-scrpage-experts.tex, doc/ngerman/scrlayer-scrpage.tex, doc/ngerman/common-pagestylemanipulation.tex: einige Verbesserungen - für die nächste Buchauflage + f?\195?\188r die n?\195?\164chste Buchauflage r1557 2013-12-17 12:05:35 +0100 mjk: @@ -5916,14 +7478,15 @@ r1555 2013-12-17 09:01:58 +0100 mjk: r1554 2013-12-17 08:45:48 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/common-headfootheight.tex: einige - Formulierungen verbessert und Teile der Einleitung als ergänzende - Informationen formatiert + Formulierungen verbessert und Teile der Einleitung als + erg?\195?\164nzende Informationen formatiert r1553 2013-12-16 18:08:48 +0100 mjk: * TODO, doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: - \partnumdepth, \chapternumdepth … \subparagraphnumdepth, - \ifnumbered, \ifunnumbered auf Deutsch dokumentiert + \partnumdepth, \chapternumdepth ?\226?\128?\166 + \subparagraphnumdepth, \ifnumbered, \ifunnumbered auf Deutsch + dokumentiert r1552 2013-12-16 17:51:32 +0100 mjk: @@ -5933,18 +7496,18 @@ r1552 2013-12-16 17:51:32 +0100 mjk: r1551 2013-12-16 15:02:13 +0100 mjk: * scrkernel-pagestyles.dtx, TODO, scrkernel-sections.dtx: new: - \partnumdepth, \chapternumdepth … \subparagraphnumdepth, - \ifnumbered, \ifunnumbered + \partnumdepth, \chapternumdepth ?\226?\128?\166 + \subparagraphnumdepth, \ifnumbered, \ifunnumbered r1550 2013-12-16 09:10:28 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/typearea.tex: einen scrpage2-Verweis - ergänzt + erg?\195?\164nzt r1549 2013-12-14 18:44:34 +0100 mjk: * TODO: \@pageat bei Verwendung von scrlayer-scrpage mit scrlttr2 - berücksichtigen + ber?\195?\188cksichtigen r1548 2013-12-14 18:36:23 +0100 mjk: @@ -5962,8 +7525,8 @@ r1546 2013-12-13 17:39:21 +0100 mjk: r1545 2013-12-13 16:32:18 +0100 mjk: - * doc/, doc/english/, doc/english/scrbase.tex: "There is not a …" - --> "There is no …" + * doc/, doc/english/, doc/english/scrbase.tex: "There is not a + ?\226?\128?\166" --> "There is no ?\226?\128?\166" r1544 2013-12-13 12:13:03 +0100 mjk: @@ -6015,8 +7578,8 @@ r1538 2013-12-12 12:01:33 +0100 mjk: * TODO, doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex, doc/ngerman/common-options.tex, doc/ngerman/common-textmarkup.tex, - doc/ngerman/common-compatibility.tex: noch ein paar Änderungen für - das nächste Buch + doc/ngerman/common-compatibility.tex: noch ein paar + ?\195?\132nderungen f?\195?\188r das n?\195?\164chste Buch r1537 2013-12-11 20:21:09 +0100 mjk: @@ -6025,21 +7588,21 @@ r1537 2013-12-11 20:21:09 +0100 mjk: doc/ngerman/common-interleafpage.tex, doc/ngerman/common-options.tex, doc/ngerman/common-lists.tex, doc/ngerman/common-textmarkup.tex, doc/ngerman/typearea.tex, doc/ngerman/common-titles.tex, - doc/ngerman/common-compatibility.tex: diverse Änderungen für die - nächste Auflage + doc/ngerman/common-compatibility.tex: diverse ?\195?\132nderungen + f?\195?\188r die n?\195?\164chste Auflage r1536 2013-12-11 10:18:01 +0100 mjk: * doc/, doc/scrguide.cls, doc/ngerman/, doc/ngerman/common-options.tex, doc/ngerman/typearea.tex, - doc/ngerman/introduction.tex: einige Anpassungen für die nächste - Buchauflage + doc/ngerman/introduction.tex: einige Anpassungen f?\195?\188r die + n?\195?\164chste Buchauflage r1535 2013-12-11 08:22:22 +0100 mjk: - * doc/, doc/ngerman/, doc/ngerman/guide-ngerman.tex: Künftig wird die - Anleitung nur noch einen Autor haben (sobald das Kapitel über - scrpage2 ausgelagert ist) + * doc/, doc/ngerman/, doc/ngerman/guide-ngerman.tex: K?\195?\188nftig + wird die Anleitung nur noch einen Autor haben (sobald das Kapitel + ?\195?\188ber scrpage2 ausgelagert ist) r1534 2013-12-10 19:50:34 +0100 mjk: @@ -6061,7 +7624,7 @@ r1533 2013-12-10 19:06:14 +0100 mjk: r1532 2013-12-10 11:28:56 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/common-options.tex: einige Dinge - sind für scrlayer etc. unerheblich + sind f?\195?\188r scrlayer etc. unerheblich r1531 2013-12-10 10:57:42 +0100 mjk: @@ -6240,7 +7803,7 @@ r1500 2013-11-06 10:22:28 +0100 mjk: r1499 2013-11-05 18:22:29 +0100 mjk: * scrkernel-letterclassoptions.dtx: change: test for correct paper - size with tolerance of ± 0.1 mm + size with tolerance of ?\194?\177 0.1 mm r1498 2013-11-05 17:00:39 +0100 mjk: @@ -6309,7 +7872,7 @@ r1487 2013-11-04 11:44:15 +0100 mjk: r1486 2013-11-04 11:38:49 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/typearea.tex: footlines korrigiert - (Bezüge zur Kopfzeile) + (Bez?\195?\188ge zur Kopfzeile) r1485 2013-11-04 11:37:58 +0100 mjk: @@ -6460,12 +8023,12 @@ r1457 2013-10-23 11:34:02 +0200 mjk: r1456 2013-10-23 11:16:09 +0200 mjk: * doc/, doc/ngerman/, doc/ngerman/common-pagestylemanipulation.tex: - fehlendes Beispiel für \GenericMarkFormat + fehlendes Beispiel f?\195?\188r \GenericMarkFormat r1455 2013-10-23 09:58:56 +0200 mjk: * doc/, doc/ngerman/, doc/ngerman/common-pagestylemanipulation.tex: - einige zustätzliche Index-Einträge + einige zust?\195?\164tzliche Index-Eintr?\195?\164ge r1454 2013-10-23 09:21:29 +0200 mjk: @@ -6573,8 +8136,8 @@ r1433 2013-10-16 16:24:20 +0200 mjk: r1432 2013-10-16 13:10:21 +0200 mjk: - * doc/, doc/ngerman/, doc/ngerman/typearea.tex: Erklärung, die - bereits in Abschnitt 2.4 zu finden ist, wieder entfernt + * doc/, doc/ngerman/, doc/ngerman/typearea.tex: Erkl?\195?\164rung, + die bereits in Abschnitt 2.4 zu finden ist, wieder entfernt r1431 2013-10-16 13:05:21 +0200 mjk: @@ -6584,8 +8147,8 @@ r1431 2013-10-16 13:05:21 +0200 mjk: r1430 2013-10-16 13:01:50 +0200 mjk: * doc/, doc/ngerman/, doc/ngerman/scrlayer-scrpage.tex, - doc/ngerman/scrlayer.tex, doc/ngerman/typearea.tex: Berücksichtigung - von scrlayer-scrpage bei typearea + doc/ngerman/scrlayer.tex, doc/ngerman/typearea.tex: + Ber?\195?\188cksichtigung von scrlayer-scrpage bei typearea r1429 2013-10-16 12:10:43 +0200 mjk: @@ -6620,7 +8183,7 @@ r1424 2013-10-16 08:56:53 +0200 mjk: doc/ngerman/common-headfootheight.tex, doc/ngerman/common-pagestylemanipulation.tex, doc/english/, doc/english/common-headfootheight.tex, - doc/english/common-pagestylemanipulation.tex: Anleitung für + doc/english/common-pagestylemanipulation.tex: Anleitung f?\195?\188r scrlayer-scrpage r1423 2013-10-15 10:17:36 +0200 mjk: @@ -6687,7 +8250,7 @@ r1412 2013-10-08 12:50:05 +0200 mjk: r1411 2013-10-08 12:45:17 +0200 mjk: * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: fehlendes - Leerzeichen ergänzt (zweiter Absatz open=Methode) + Leerzeichen erg?\195?\164nzt (zweiter Absatz open=Methode) r1410 2013-10-08 12:30:47 +0200 mjk: @@ -6769,7 +8332,7 @@ r1395 2013-10-02 18:37:13 +0200 mjk: r1394 2013-10-02 11:12:48 +0200 mjk: * TODO, doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex, - doc/ngerman/tocbasic.tex: \addxcontentsline…, + doc/ngerman/tocbasic.tex: \addxcontentsline?\226?\128?\166, \tocbasic@addxcontentsline, \nonumberline, Eigenschaft "numberline" und die Klassenoptionen in diesem Zusammenhang dokumentiert @@ -6917,9 +8480,9 @@ r1370 2013-08-28 13:46:00 +0200 mjk: r1369 2013-08-28 13:45:40 +0200 mjk: - * doc/, doc/ngerman/, doc/ngerman/tocbasic.tex: Gegenüberstellung von - remarkbox und figure und ein Beispiel für die Verwendung von - remarkbox + * doc/, doc/ngerman/, doc/ngerman/tocbasic.tex: + Gegen?\195?\188berstellung von remarkbox und figure und ein Beispiel + f?\195?\188r die Verwendung von remarkbox r1368 2013-08-28 13:44:19 +0200 mjk: @@ -7004,7 +8567,7 @@ r1353 2013-07-22 18:38:26 +0200 mjk: doc/ngerman/scrbookreportarticle.tex, doc/ngerman/scrlttr2-experts.tex, doc/english/, doc/english/scrlttr2.tex, doc/english/scrlttr2-experts.tex: Kleinere - Ergänzungen und Korrekturen + Erg?\195?\164nzungen und Korrekturen r1352 2013-07-09 15:01:26 +0200 mjk: @@ -7014,7 +8577,7 @@ r1352 2013-07-09 15:01:26 +0200 mjk: r1351 2013-07-09 08:22:42 +0200 mjk: * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: - Angezeigter Code stimmt mit Abbildung überein [Epllus] + Angezeigter Code stimmt mit Abbildung ?\195?\188berein [Epllus] r1350 2013-07-08 12:48:52 +0200 mjk: @@ -7032,8 +8595,8 @@ r1348 2013-06-12 08:23:25 +0200 mjk: r1347 2013-06-12 08:21:59 +0200 mjk: - * scrkernel-fonts.dtx: \use…ofkomafont internally doesn't set the - color + * scrkernel-fonts.dtx: \use?\226?\128?\166ofkomafont internally + doesn't set the color r1346 2013-06-09 10:33:26 +0200 mjk: @@ -7067,7 +8630,8 @@ r1342 2013-05-31 15:53:50 +0200 mjk: r1341 2013-05-31 12:02:05 +0200 mjk: * doc/, doc/english/, doc/english/typearea-experts.tex: fix: \indent - before \rule{…}{…} to show the typing area correctly + before \rule{?\226?\128?\166}{?\226?\128?\166} to show the typing + area correctly r1340 2013-05-31 11:59:06 +0200 mjk: @@ -7199,8 +8763,9 @@ r1315 2013-03-30 16:15:12 +0100 mjk: r1314 2013-03-28 09:47:28 +0100 mjk: - * TODO: Die KOMA-Script-Klassen müssen bezüglich \footheight nichts - beachten, da sie die Linie ohnehin immer über dem Fuß einfügen. + * TODO: Die KOMA-Script-Klassen m?\195?\188ssen bez?\195?\188glich + \footheight nichts beachten, da sie die Linie ohnehin immer + ?\195?\188ber dem Fu?\195?\159 einf?\195?\188gen. r1313 2013-03-26 12:15:09 +0100 mjk: @@ -7492,8 +9057,8 @@ r1253 2012-10-13 17:09:33 +0200 mjk: r1252 2012-10-08 09:27:49 +0200 mjk: * scrjura.dtx: Fix: \Paragraph und \SubParagraph funktionierten nur im - vertikalen Modus erzeugten aber fälschlich keinen Absatz am Anfang - [Timon Geppert] + vertikalen Modus erzeugten aber f?\195?\164lschlich keinen Absatz am + Anfang [Timon Geppert] r1251 2012-09-22 09:04:00 +0200 mjk: @@ -7541,21 +9106,23 @@ r1243 2012-07-22 12:12:56 +0200 mjk: r1242 2012-07-22 12:11:28 +0200 mjk: * doc/, doc/ngerman/, doc/ngerman/typearea.tex: Zweimal \PParameter - für BCOR in \POParameter korrigiert. + f?\195?\188r BCOR in \POParameter korrigiert. r1241 2012-07-17 09:13:20 +0200 mjk: * doc/, doc/ngerman/, doc/ngerman/introduction.tex: Hinweis, dass - (auch ungünstige) Voreinstellungen keine Fehler darstellen. + (auch ung?\195?\188nstige) Voreinstellungen keine Fehler darstellen. r1240 2012-07-17 08:54:45 +0200 mjk: * doc/, doc/ngerman/, doc/ngerman/typearea.tex: Von Axel Berger - gewünschter expliziter Hinweis auf das Offensichtliche ergänzt. + gew?\195?\188nschter expliziter Hinweis auf das Offensichtliche + erg?\195?\164nzt. r1239 2012-07-07 13:32:45 +0200 mjk: - * doc/, doc/ngerman/: Fixed: ein »sind« zuviel [Stephan Opfer] + * doc/, doc/ngerman/: Fixed: ein ?\194?\187sind?\194?\171 zuviel + [Stephan Opfer] r1238 2012-07-05 10:29:01 +0200 mjk: @@ -7688,8 +9255,9 @@ r1213 2012-04-17 10:13:15 +0200 mjk: r1212 2012-04-16 09:45:21 +0200 mjk: - * doc/, doc/ngerman/, doc/ngerman/scrwfile.tex: »Verzeichnissn« --> - »Verzeichnissen« [gemeldet von Jonas Stein] + * doc/, doc/ngerman/, doc/ngerman/scrwfile.tex: + ?\194?\187Verzeichnissn?\194?\171 --> + ?\194?\187Verzeichnissen?\194?\171 [gemeldet von Jonas Stein] r1211 2012-04-08 11:14:11 +0200 mjk: @@ -7725,8 +9293,8 @@ r1204 2012-03-15 16:46:57 +0100 mjk: r1203 2012-03-15 16:45:32 +0100 mjk: - * LIESMICH.SVN: Informationen für Entwickler mit Mac OS X oder - Windows hinzugefügt + * LIESMICH.SVN: Informationen f?\195?\188r Entwickler mit Mac OS X + oder Windows hinzugef?\195?\188gt r1201 2012-03-15 16:13:55 +0100 mjk: @@ -7745,8 +9313,8 @@ r1198 2012-03-14 16:56:28 +0100 mjk: r1197 2012-03-14 15:24:14 +0100 mjk: - * doc/, doc/ngerman/, doc/ngerman/tocbasic.tex: Fehler, der während - der Übersetzung entdeckt wurde, behoben. + * doc/, doc/ngerman/, doc/ngerman/tocbasic.tex: Fehler, der + w?\195?\164hrend der ?\195?\156bersetzung entdeckt wurde, behoben. r1196 2012-03-14 09:34:56 +0100 mjk: @@ -7798,8 +9366,8 @@ r1187 2012-03-09 13:12:03 +0100 mjk: r1186 2012-03-09 13:11:11 +0100 mjk: - * doc/, doc/ngerman/, doc/ngerman/tocbasic.tex: fehlende Erklärung zu - noprotrusion + * doc/, doc/ngerman/, doc/ngerman/tocbasic.tex: fehlende + Erkl?\195?\164rung zu noprotrusion r1185 2012-03-09 08:46:33 +0100 mjk: @@ -7812,16 +9380,15 @@ r1184 2012-03-09 08:46:20 +0100 mjk: r1183 2012-03-09 08:33:38 +0100 mjk: * manifest.txt, doc/, doc/ngerman/, doc/ngerman/scrwfile.tex, - doc/english/, doc/english/expertpart.tex, - doc/english/scrlttr2examples.dtx, doc/english/scrhack.tex, + doc/english/, doc/english/expertpart.tex, doc/english/scrhack.tex, doc/english/authorpart.tex: these files should have been part of the repository for several weeks r1182 2012-03-08 12:40:30 +0100 mjk: * scrkernel-version.dtx, scrkernel-compatibility.dtx, - scrkernel-index.dtx: brackets at \idx@heading fixed [Jürgen - Spitzmüller] + scrkernel-index.dtx: brackets at \idx@heading fixed [J?\195?\188rgen + Spitzm?\195?\188ller] r1181 2012-03-06 18:08:46 +0100 mjk: @@ -7908,7 +9475,7 @@ r1168 2012-02-26 16:11:03 +0100 mjk: doc/english/common-interleafpage.tex, doc/english/scrdatetime.tex, doc/english/adrconvnote.tex, doc/english/scrlfile.tex, doc/english/scraddr.tex: ein paar kleinere Verbesserungen, die - während der Übersetzung aufgefallen sind + w?\195?\164hrend der ?\195?\156bersetzung aufgefallen sind r1167 2012-02-26 16:10:51 +0100 mjk: @@ -7916,7 +9483,7 @@ r1167 2012-02-26 16:10:51 +0100 mjk: doc/ngerman/common-interleafpage.tex, doc/ngerman/scrdatetime.tex, doc/ngerman/adrconvnote.tex, doc/ngerman/scrlfile.tex, doc/ngerman/scraddr.tex: ein paar kleinere Verbesserungen, die - während der Übersetzung aufgefallen sind + w?\195?\164hrend der ?\195?\156bersetzung aufgefallen sind r1166 2012-02-26 16:09:33 +0100 mjk: @@ -8091,7 +9658,7 @@ r1138 2012-02-05 11:11:34 +0100 mjk: r1137 2012-02-03 16:25:43 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/scrbookreportarticle.tex: einige - Querverweise ergänzt + Querverweise erg?\195?\164nzt r1136 2012-02-03 16:25:19 +0100 mjk: @@ -8332,7 +9899,7 @@ r1102 2011-09-12 11:05:56 +0200 mjk: r1101 2011-09-11 18:14:15 +0200 mjk: - * scrwfile.dtx: several docu fixes by Patrick Häcker + * scrwfile.dtx: several docu fixes by Patrick H?\195?\164cker r1100 2011-09-09 11:53:12 +0200 mjk: @@ -8461,8 +10028,8 @@ r1077 2011-04-05 08:58:11 +0200 mjk: r1076 2011-04-05 08:52:55 +0200 mjk: * TODO, doc/, doc/guide.bib, doc/ngerman/, - doc/ngerman/scrbookreportarticle.tex: neue Werte für Option captions - dokumentiert + doc/ngerman/scrbookreportarticle.tex: neue Werte f?\195?\188r Option + captions dokumentiert r1075 2011-04-02 07:54:03 +0200 mjk: @@ -8554,7 +10121,7 @@ r1056 2011-03-07 10:50:55 +0100 mjk: * TODO, doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex: alte Font-Elemente refname und refvalue dokumentiert; neue Werte - dateleft, dateright, nodate für Option refline dokumentiert + dateleft, dateright, nodate f?\195?\188r Option refline dokumentiert r1055 2011-03-07 09:38:43 +0100 mjk: @@ -8613,8 +10180,8 @@ r1042 2011-02-09 18:51:45 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex: Neue Variablen firsthead, firstfoot, nexthead, nextfoot und die Empfehlung die - überholten Anweisungen \firshead, \firstfoot, \nexthead, \nextfoot - nicht mehr zu verwenden. + ?\195?\188berholten Anweisungen \firshead, \firstfoot, \nexthead, + \nextfoot nicht mehr zu verwenden. r1041 2011-02-09 18:37:55 +0100 mjk: @@ -8731,7 +10298,8 @@ r1028 2011-01-20 08:56:03 +0100 mjk: r1027 2011-01-18 12:50:07 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/scrdatetime.tex: Dank Benjamin Hell - werden nun auch Schwedisch und Dänish von scrdate unterstützt. + werden nun auch Schwedisch und D?\195?\164nish von scrdate + unterst?\195?\188tzt. r1026 2011-01-18 12:43:01 +0100 mjk: @@ -8989,7 +10557,7 @@ r970 2010-06-09 10:32:03 +0200 mjk: r969 2010-06-07 16:47:10 +0200 mjk: - * scrjura.dtx: \changes hinzugefügt bzw. korrigiert + * scrjura.dtx: \changes hinzugef?\195?\188gt bzw. korrigiert r968 2010-06-07 16:26:51 +0200 mjk: @@ -9124,7 +10692,7 @@ r942 2010-03-18 11:54:00 +0100 mjk: r941 2010-03-14 10:08:21 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/scrlfile.tex: fehlende \ChangedAt - und fehlende Doku zu \AfterReadingMainAux ergänzt + und fehlende Doku zu \AfterReadingMainAux erg?\195?\164nzt r940 2010-03-12 11:48:23 +0100 mjk: @@ -9138,8 +10706,8 @@ r939 2010-03-11 11:20:56 +0100 mjk: \ISODayNumber, \DayName, \ISODayName, \DayNameByNumber, \ISOToday, - \IsoToday, \todaysnumber sind dokumentiert (scrdate). Die Änderung - bezüglich Option 12h ist dokumentiert (scrtime). + \IsoToday, \todaysnumber sind dokumentiert (scrdate). Die ?\195?\132nderung + bez?\195?\188glich Option 12h ist dokumentiert (scrtime). r938 2010-03-11 09:46:00 +0100 mjk: @@ -9294,7 +10862,7 @@ r916 2009-11-28 11:57:23 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex, doc/ngerman/scrbookreportarticle.tex: Ligaturverhinderung im Index - wegen neuer hyperref-Version geändert + wegen neuer hyperref-Version ge?\195?\164ndert r915 2009-11-28 11:53:56 +0100 mjk: @@ -9367,7 +10935,7 @@ r904 2009-11-09 10:25:24 +0100 mjk: r903 2009-09-05 15:45:26 +0200 mjk: - * TODO: microtype-TODO für tocbasic aufgenommen + * TODO: microtype-TODO f?\195?\188r tocbasic aufgenommen r902 2009-08-05 11:43:27 +0200 mjk: @@ -9559,12 +11127,14 @@ r860 2009-04-21 09:06:07 +0200 mjk: r859 2009-04-21 08:56:43 +0200 mjk: - * scrkernel-sections.dtx: One »~« replaced by »\nobreakspace« to - improve compatibility with Spanish (babel). + * scrkernel-sections.dtx: One ?\194?\187~?\194?\171 replaced by + ?\194?\187\nobreakspace?\194?\171 to improve compatibility with + Spanish (babel). r858 2009-04-21 08:55:07 +0200 mjk: - * scrkernel-sections.dtx: one »~« replaced by »\nobreakspace« + * scrkernel-sections.dtx: one ?\194?\187~?\194?\171 replaced by + ?\194?\187\nobreakspace?\194?\171 r857 2009-04-12 19:55:30 +0200 mjk: @@ -9620,7 +11190,7 @@ r845 2009-03-25 10:46:36 +0100 mjk: r844 2009-03-24 10:22:26 +0100 mjk: - * scrjura.dtx: Alexanders Doku-Änderungen + * scrjura.dtx: Alexanders Doku-?\195?\132nderungen r843 2009-03-19 11:01:11 +0100 mjk: @@ -9694,8 +11264,9 @@ r836 2009-03-16 15:07:38 +0100 mjk: r835 2009-03-16 10:09:44 +0100 mjk: - * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex: Peter heißt jetzt - einheitlich Musterfrau während Petra Mustermann heißt. + * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex: Peter hei?\195?\159t + jetzt einheitlich Musterfrau w?\195?\164hrend Petra Mustermann + hei?\195?\159t. r834 2009-03-16 10:07:02 +0100 mjk: @@ -9714,8 +11285,8 @@ r832 2009-03-12 08:55:06 +0100 mjk: r831 2009-03-04 19:19:04 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/scrlttr2.tex, - doc/ngerman/scrlttr2-experts.tex: Erlärung der neuen Möglichkeiten - von scrlttr2 3.03 bis 2009/03/04 + doc/ngerman/scrlttr2-experts.tex: Erl?\195?\164rung der neuen + M?\195?\182glichkeiten von scrlttr2 3.03 bis 2009/03/04 r830 2009-03-04 19:17:55 +0100 mjk: @@ -9739,8 +11310,9 @@ r827 2009-03-04 11:25:28 +0100 mjk: r826 2009-03-02 17:24:10 +0100 mjk: * doc/, doc/linkalias.tex, doc/ngerman/: Option "version" wird - neuerdings bereits im Kapitel über typearea eingeführt, also - müssen die Links in den freien Versionen darauf zeigen. + neuerdings bereits im Kapitel ?\195?\188ber typearea + eingef?\195?\188hrt, also m?\195?\188ssen die Links in den freien + Versionen darauf zeigen. r825 2009-02-27 09:45:52 +0100 mjk: @@ -9838,8 +11410,8 @@ r805 2009-01-23 15:39:38 +0100 mjk: r804 2009-01-20 18:46:00 +0100 mjk: - * doc/, doc/ngerman/: {} hinter \nopagebreak eingefügt (Danke an - Torsten Krüger) + * doc/, doc/ngerman/: {} hinter \nopagebreak eingef?\195?\188gt (Danke + an Torsten Kr?\195?\188ger) r803 2009-01-20 12:12:55 +0100 mjk: @@ -9964,7 +11536,7 @@ r786 2008-12-08 11:48:52 +0100 mjk: r785 2008-12-08 11:47:02 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/guide-ngerman.tex: Verbesserungen - beim Änderungsverzeichnis berücksichtigt + beim ?\195?\132nderungsverzeichnis ber?\195?\188cksichtigt r784 2008-12-08 11:46:07 +0100 mjk: @@ -9976,12 +11548,12 @@ r783 2008-12-08 11:34:24 +0100 mjk: r782 2008-12-08 11:18:24 +0100 mjk: - * doc/, doc/ngerman/: \ChangedAt-Einträge korrigiert + * doc/, doc/ngerman/: \ChangedAt-Eintr?\195?\164ge korrigiert r781 2008-12-07 13:54:17 +0100 mjk: - * doc/, doc/ngerman/, doc/ngerman/typearea.tex: vertikale Abstände - nach listings verbessert + * doc/, doc/ngerman/, doc/ngerman/typearea.tex: vertikale + Abst?\195?\164nde nach listings verbessert r780 2008-12-07 13:53:42 +0100 mjk: @@ -9995,7 +11567,7 @@ r779 2008-12-07 13:51:55 +0100 mjk: r778 2008-11-28 08:09:13 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/typearea.tex: erste Korrekturen und - Vorschläge von Torsten + Vorschl?\195?\164ge von Torsten r777 2008-11-25 14:50:13 +0100 mjk: @@ -10020,8 +11592,8 @@ r770 2008-11-22 08:06:54 +0100 mjk: r769 2008-11-21 09:24:20 +0100 mjk: - * doc/, doc/ngerman/: geänderte Voreinstellung für »version« - dokumentiert + * doc/, doc/ngerman/: ge?\195?\164nderte Voreinstellung f?\195?\188r + ?\194?\187version?\194?\171 dokumentiert r768 2008-11-21 09:03:06 +0100 mjk: @@ -10075,7 +11647,7 @@ r761 2008-11-13 12:49:56 +0100 mjk: r760 2008-11-13 09:48:02 +0100 mjk: * doc/, doc/ngerman/, doc/ngerman/scrlttr2-experts.tex: - \ChangedAt-Einträge korrigiert + \ChangedAt-Eintr?\195?\164ge korrigiert r759 2008-11-12 16:21:03 +0100 mjk: @@ -10099,7 +11671,7 @@ r756 2008-11-03 17:37:07 +0100 mjk: r755 2008-11-03 15:48:41 +0100 mjk: - * scrkernel-notepaper.dtx: nix geändert + * scrkernel-notepaper.dtx: nix ge?\195?\164ndert r754 2008-11-03 15:06:03 +0100 mjk: @@ -10326,7 +11898,7 @@ r707 2008-05-02 16:43:26 +0200 mjk: r706 2008-04-30 09:52:59 +0200 mjk: - * doc/: diverse Neuerungen inbesondere bezüglich der Optionen + * doc/: diverse Neuerungen inbesondere bez?\195?\188glich der Optionen dokumentiert r705 2008-04-30 09:52:22 +0200 mjk: @@ -10908,7 +12480,7 @@ r584 2007-12-15 15:57:37 +0100 mjk: r583 2007-12-15 15:51:52 +0100 mjk: * doc/: Tabelle der vordefinierten lco-Dateien um die Japanischen - lco-Dateien ergänzt + lco-Dateien erg?\195?\164nzt r582 2007-12-15 15:42:28 +0100 mjk: @@ -10943,12 +12515,13 @@ r576 2007-12-07 10:46:47 +0100 mjk: r575 2007-12-07 10:04:44 +0100 mjk: - * TODO, doc/: Änderung bezüglich der Nummerierung in "\frontmatter" - dokumentiert + * TODO, doc/: ?\195?\132nderung bez?\195?\188glich der Nummerierung in + "\frontmatter" dokumentiert r574 2007-12-07 09:27:54 +0100 mjk: - * TODO, doc/: "location"-Werte für Option "fromalign" dokumentiert + * TODO, doc/: "location"-Werte f?\195?\188r Option "fromalign" + dokumentiert r573 2007-12-07 09:24:24 +0100 mjk: @@ -10956,20 +12529,20 @@ r573 2007-12-07 09:24:24 +0100 mjk: r572 2007-12-07 09:23:01 +0100 mjk: - * doc/: \ChangedAt-Einträge korrigiert + * doc/: \ChangedAt-Eintr?\195?\164ge korrigiert r571 2007-12-07 08:27:39 +0100 mjk: * TODO, doc/: Optionen "firsthead" und "firstfoot" dokumentiert - (einschl. Auswirkungen auf Pseudolänge "firstfootvpos") + (einschl. Auswirkungen auf Pseudol?\195?\164nge "firstfootvpos") r570 2007-12-04 12:05:53 +0100 mjk: - * TODO: tocstyle wird erwähnt + * TODO: tocstyle wird erw?\195?\164hnt r569 2007-12-04 12:04:15 +0100 mjk: - * TODO, doc/: Pseudo-Längen "lochpos", "locvpos", "locheight" + * TODO, doc/: Pseudo-L?\195?\164ngen "lochpos", "locvpos", "locheight" dokumentiert r568 2007-12-04 11:46:01 +0100 mjk: @@ -10982,8 +12555,8 @@ r567 2007-12-04 11:44:02 +0100 mjk: r566 2007-12-04 11:36:59 +0100 mjk: - * TODO, doc/: neue Werte für Option "subject"; Tabelle der - Pseudo-Längen sortiert + * TODO, doc/: neue Werte f?\195?\188r Option "subject"; Tabelle der + Pseudo-L?\195?\164ngen sortiert r565 2007-11-30 13:06:11 +0100 mjk: @@ -10994,7 +12567,7 @@ r564 2007-11-29 12:35:39 +0100 mjk: * TODO: partentry, partentrypagenumber, chapterentry, chapterentrypagenumber, sectionentry, sectionentrypagenumber - dokumentiert aber noch nicht übersetzt. + dokumentiert aber noch nicht ?\195?\188bersetzt. r563 2007-11-29 12:33:47 +0100 mjk: @@ -11031,11 +12604,11 @@ r557 2007-11-28 12:35:00 +0100 mjk: r556 2007-11-28 10:06:03 +0100 mjk: - * doc/: Erklärung zu Option "foldmarks" verbessert + * doc/: Erkl?\195?\164rung zu Option "foldmarks" verbessert r555 2007-11-27 12:36:05 +0100 mjk: - * TODO, doc/: Pseudo-Länge "fromrulewidth" dokumentiert + * TODO, doc/: Pseudo-L?\195?\164nge "fromrulewidth" dokumentiert r554 2007-11-27 12:27:16 +0100 mjk: @@ -11047,12 +12620,12 @@ r553 2007-11-27 10:00:28 +0100 mjk: r552 2007-11-27 09:50:51 +0100 mjk: - * TODO, doc/: Die neuen Möglichkeiten für die Konfigurierung der - Faltmarken dokumentiert + * TODO, doc/: Die neuen M?\195?\182glichkeiten f?\195?\188r die + Konfigurierung der Faltmarken dokumentiert r551 2007-11-26 13:10:17 +0100 mjk: - * TODO, doc/: Erklärung zur Option "foldmarks" erweitert + * TODO, doc/: Erkl?\195?\164rung zur Option "foldmarks" erweitert r550 2007-11-26 12:23:35 +0100 mjk: @@ -11151,7 +12724,7 @@ r533 2007-11-12 15:15:16 +0100 mjk: r532 2007-11-10 11:25:07 +0100 mjk: - * TODO: neue Pseudo-Längen + * TODO: neue Pseudo-L?\195?\164ngen r531 2007-11-10 11:22:39 +0100 mjk: @@ -11168,7 +12741,7 @@ r530 2007-11-10 08:53:30 +0100 mjk: r529 2007-11-08 11:29:28 +0100 mjk: - * TODO: einige Änderungen bei den Faltmarken + * TODO: einige ?\195?\132nderungen bei den Faltmarken r528 2007-11-08 11:27:59 +0100 mjk: @@ -11394,8 +12967,8 @@ r480 2007-09-12 17:03:04 +0200 mjk: r479 2007-09-12 12:47:27 +0200 mjk: - * doc/: Tabellenüberschrift für Tabelle 6.18 (Datumsbefehle und - Ausgabebeispiel) ergänzt [GH] + * doc/: Tabellen?\195?\188berschrift f?\195?\188r Tabelle 6.18 + (Datumsbefehle und Ausgabebeispiel) erg?\195?\164nzt [GH] r478 2007-09-12 12:44:45 +0200 mjk: @@ -11407,7 +12980,7 @@ r477 2007-09-06 11:05:54 +0200 mjk: r476 2007-09-06 11:01:22 +0200 mjk: - * doc/: Fehlende schließende Klammer ergänzt + * doc/: Fehlende schlie?\195?\159ende Klammer erg?\195?\164nzt r475 2007-09-06 10:55:26 +0200 mjk: @@ -11420,8 +12993,8 @@ r474 2007-09-04 11:48:13 +0200 mjk: r473 2007-09-04 11:46:50 +0200 mjk: - * doc/: Gesucht sind linksbündige Fußnotenmarkierungen, nicht - linksb+ndige Fußnoten + * doc/: Gesucht sind linksb?\195?\188ndige + Fu?\195?\159notenmarkierungen, nicht linksb+ndige Fu?\195?\159noten r472 2007-09-04 11:31:06 +0200 mjk: @@ -11782,8 +13355,9 @@ r390 2007-06-14 09:56:35 +0200 mjk: r389 2007-06-06 09:32:40 +0200 mjk: - * doc/: "Es wird auch kein zusätzlicher vertikaler Abstand vor und - nach der Umgebung eingefügt." added at declaration of addmargin + * doc/: "Es wird auch kein zus?\195?\164tzlicher vertikaler Abstand + vor und nach der Umgebung eingef?\195?\188gt." added at declaration + of addmargin r388 2007-06-06 09:28:51 +0200 mjk: @@ -12160,7 +13734,7 @@ r311 2006-11-28 11:50:17 +0100 mjk: ab 2.96a) erfolgt im Inhaltsverzeichnis kein Seitenumbruch mehr zwischen part- und chapter-, bzw. part- und section-, bzw. chapter- und section-, bzw. section- und subsection-Eintrag. Das genau - Verhalten ist von der Klasse abhängig. + Verhalten ist von der Klasse abh?\195?\164ngig. r310 2006-11-28 09:26:08 +0100 mjk: @@ -13157,7 +14731,7 @@ r68 2006-03-08 08:52:54 +0100 mjk: r64 2006-02-13 18:53:08 +0100 mjk: * lppl-de.txt: erste Version der mit Frank Mittelbach abgesprochenden - inoffiziellen Übersetzung der LPPL 1.3b + inoffiziellen ?\195?\156bersetzung der LPPL 1.3b r60 2006-01-25 12:56:38 +0100 mjk: @@ -13217,7 +14791,8 @@ r40 2005-11-26 17:28:08 +0100 mjk: r39 2005-11-26 17:15:37 +0100 mjk: - * doc/: Fließumgebung --> Gleitumgebung, Fließobjekt --> Gleitobjekt + * doc/: Flie?\195?\159umgebung --> Gleitumgebung, Flie?\195?\159objekt + --> Gleitobjekt r38 2005-11-26 15:45:37 +0100 mjk: @@ -13243,7 +14818,7 @@ r34 2005-11-26 10:58:13 +0100 mjk: r33 2005-11-25 11:48:07 +0100 mjk: - * doc/: Widmung prägnanter gefasst + * doc/: Widmung pr?\195?\164gnanter gefasst r32 2005-11-05 10:04:02 +0100 mjk: @@ -13251,8 +14826,8 @@ r32 2005-11-05 10:04:02 +0100 mjk: r31 2005-11-05 10:03:34 +0100 mjk: - * doc/: Erklärung zu smallheadings, normalheadings, bigheadings - erweitert [Stephan Hennig] + * doc/: Erkl?\195?\164rung zu smallheadings, normalheadings, + bigheadings erweitert [Stephan Hennig] r30 2005-11-05 10:01:05 +0100 mjk: diff --git a/Master/texmf-dist/source/latex/koma-script/doc/bin/genhtmlidx.pl b/Master/texmf-dist/source/latex/koma-script/doc/bin/genhtmlidx.pl index c0f7be336ae..da8837f8958 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/bin/genhtmlidx.pl +++ b/Master/texmf-dist/source/latex/koma-script/doc/bin/genhtmlidx.pl @@ -81,14 +81,14 @@ while ( $auxfile=shift ) { open AUX,"<$auxfile" or die "Cannot read $auxfile!\n"; while () { my $line=$_; - if ( /^\\newlabel{(desc:[^}]+)}{(.*)}$/ ) { + if ( /^\\newlabel\{(desc:[^\}]+)\}\{(.*)\}$/ ) { my $label=$1; my $refargs=$2; - if ( $refargs =~ /^{([^{}]*({((?:(?>[^{}]*)|(?1))*)})*)}{([^}]+)}(.*)$/ ) { + if ( $refargs =~ /^\{([^\{\}]*(\{((?:(?>[^\{\}]*)|(?1))*)\})*)\}\{([^\}]+)\}(.*)$/ ) { my $ref=$1; my $page=$4; my $rest=$5; - if ( $rest =~ /^{([^{}]*({((?:(?>[^{}]*)|(?1))*)})*)}{([^}]*)}{(.*)}$/ ) { + if ( $rest =~ /^\{([^\{\}]*(\{((?:(?>[^\{\}]*)|(?1))*)\})*)\}\{([^\}]*)\}\{(.*)\}$/ ) { my $title=$1; my $anchor=$4; my $ignore=$5; diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/adrconvnote.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/adrconvnote.tex index e9b26afb6b7..75b9b8f392c 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/adrconvnote.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/adrconvnote.tex @@ -1,6 +1,6 @@ % ====================================================================== % adrconvnote.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % adrconvnote.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,12 +46,13 @@ % ====================================================================== \KOMAProvidesFile{adrconvnote.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (chapter: adrconv)] -\translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm} +\translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm\and + Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-01-29 \chapter{Creating Address Files from an Address Database}% \labelbase{addrconv}% @@ -59,12 +60,11 @@ \Index{address>database}% \IndexPackage{addrconv} -In former versions of {\KOMAScript} the package \Package{addrconv} was -a permanent part of the {\KOMAScript} system. The chief involvement -with {\KOMAScript} was that with the help of \Package{addrconv} it was -possible from an address database in {\BibTeX} format to create -address files compatible with the {\KOMAScript} letter class or with -the package \Package{scraddr}. +In previous versions of \KOMAScript{}, the \Package{addrconv} package was an +integral part of the \KOMAScript{} system. The main connection to +\KOMAScript{} was that with the help of this package, it was possible to +create address files compatible with the \KOMAScript{} letter class or with +the \Package{scraddr} package from an address database in \BibTeX{} format. \begin{lstlisting}[morekeywords={@address}] @address{HMUS, @@ -80,19 +80,17 @@ the package \Package{scraddr}. } \end{lstlisting} -From entries such as that given above, address files can be generated. -For this \Package{addrconv} employs {\BibTeX} and various {\BibTeX} -styles. Additionally, there are some {\LaTeX} files which can help to -create various telephone and address lists for printing. +From entries such as the one above, you can use \BibTeX{} and various +{\BibTeX} styles to create address files. There are also some special \LaTeX{} +files that make it possible to create various telephone and address lists from +the address files. -However, the package \Package{addrconv} was actually an independent -package, since besides what is required for {\KOMAScript} it includes -several more interesting features. Therefore, the package -\Package{addrconv} has for some time already been removed from the -{\KOMAScript} system. The package \Package{adrconv}, with a single -\emph{d}, entirely replaces \Package{addrconv}. If it is not included -in your {\TeX} distribution then it can be downloaded from -\cite{package:adrconv} and you can install it separately. +However, the \Package{addrconv} package was actually an independent package, +including features beyond what is required for \KOMAScript{}. That is why +\Package{addrconv} has not been included in \KOMAScript{} for some time. The +\Package{adrconv} package, with a single \emph{d}, entirely replaces +\Package{addrconv}. If it is not included in your \TeX{} distribution, you can +download it from \cite{package:adrconv} and install it separately. %%% Local Variables: %%% mode: latex diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/authorpart.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/authorpart.tex index 78be0e66a7c..37b4d7bc8a5 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/authorpart.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/authorpart.tex @@ -1,6 +1,6 @@ % ====================================================================== % authorpart.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % authorpart.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,32 +46,30 @@ % ====================================================================== \ProvidesFile{authorpart.tex}[2012/04/02 Part KOMA-Script for Authors] -\translator{Markus Kohm\and Krickette Murabayashi} +\translator{Markus Kohm\and Krickette Murabayashi\and Karl Hagen} \setpartpreamble{% \vspace*{2\baselineskip}% \setlength{\parindent}{1em}% - \noindent In this part you may find information for authors of articles, - reports, books, and letters. It is assumed that the average user is less - interested in the implementation of \KOMAScript{} or in the problems of - implementing \KOMAScript. Also, the average user isn't interested in - obsolete options and instructions. He wants to know how he can achieve - things using current options and instructions. Some users may be interested - in typographic background information. + \noindent This part provides information for writers of articles, reports, + books, and letters. The average user is probably less interested in how + things are implemented in \KOMAScript{} and what pitfalls exist. Also, + normal users aren't interested in obsolete options and instructions. They + want to know how to achieve things using current options and instructions, + and perhaps in some background information about typography. - In this part, the few passages that contain additional information and - justification, and therefore are of less interest for the impatient reader, - have been set in sans serif font and can be skipped if necessary. For those - who are interested in more information about implementation, side effects - with other packages, and obsolete options and instructions, please refer to - \autoref{part:forExperts} on \autopageref{part:forExperts}. Furthermore, - that part of the \KOMAScript{} guide describes all the features that were - created specially for writers of packages and classes.% + The few passages in this part which contain extra information and + explanations that may be of less interest for the impatient reader are set + in a sans-serif typeface and can be skipped if desired. For those who are + interested in more information about the implementation, side-effects with + other packages, or obsolete options and instructions, please refer to + \autoref{part:forExperts} beginning on \autopageref{part:forExperts}. That + part of the \KOMAScript{} guide also describes all the features that were + created specially for authors of packages and classes.% } -\part{\KOMAScript{} for Authors} -\label{part:forAuthors} +\part{\KOMAScript{} for Authors\label{part:forAuthors}} \endinput diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-compatibility.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-compatibility.tex index f397b67f842..bed043d8d37 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-compatibility.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-compatibility.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-compatibility.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % common-compatibility.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,11 +46,11 @@ % ====================================================================== \KOMAProvidesFile{common-compatibility.tex} - [$Date: 2017-03-22 09:50:43 +0100 (Wed, 22 Mar 2017) $ + [$Date: 2018-02-28 13:23:23 +0100 (Wed, 28 Feb 2018) $ KOMA-Script guide (common paragraphs)] -\translator{Markus Kohm\and Krickette Murabayashi} +\translator{Markus Kohm\and Krickette Murabayashi\and Karl Hagen} -% Date of the translated German file: 2017-03-22 +% Date of the translated German file: 2018-01-30 \section{Compatibility with Earlier Versions of \KOMAScript} \seclabel{compatibilityOptions} @@ -58,122 +58,138 @@ \BeginIndex{}{Compatibility} \IfThisCommonFirstRun{}{% - It applies, mutatis mutandis, what is written in - \autoref{sec:\ThisCommonFirstLabelBase.compatibilityOptions}. - \IfThisCommonLabelBase{scrlttr2}{However, this feature exists at - \Class{scrlttr2} since version~2.9t. }% - So if you have alread read and understood - \autoref{sec:\ThisCommonFirstLabelBase.compatibilityOptions} you can - switch to \autopageref{sec:\ThisCommonLabelBase.compatibilityOptions.next}, + The information in + \autoref{sec:\ThisCommonFirstLabelBase.compatibilityOptions} applies equally + to this chapter. + \IfThisCommonLabelBase{scrlttr2}{However, this feature has existed in + \Class{scrlttr2} since version~2.9t, whereas \Package{scrletter} does not + offer it. }{}% + So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.compatibilityOptions} you can skip + ahead to \autopageref{sec:\ThisCommonLabelBase.compatibilityOptions.next}, \autopageref{sec:\ThisCommonLabelBase.compatibilityOptions.next}.% } -\IfThisCommonLabelBase{typearea}{% - Those who achieve their documents in source code set utmost value to the - fact that future \LaTeX{} runs will yield exactly the same - result. Nevertheless, in some cases improvement and bug corrections of - packages will result in changes of the behaviour and make-up. But sometimes - this is not wanted.% +\IfThisCommonLabelBaseOneOf{typearea,maincls,scrlttr2,scrextend}{% + Those who produce their documents from source code typically attach the + utmost importance to the fact that future \LaTeX{} runs will yield exactly + the same result. In some cases, however, improvements and bug fixes to the + \IfThisCommonLabelBaseOneOf{maincls,scrlttr2}{class}{package} will + result in changes of behaviour, especially to the layout. This, however, + may be undesirable.% }{% - \IfThisCommonLabelBase{maincls}{% - Those who achieve their documents in source code set utmost value to the - fact that future \LaTeX{} runs will yield exactly the same - result. However, sometimes improvement and bug corrections of classes will - result in changes of the behaviour and make-up. But sometimes this is not - wanted. }{% - \IfThisCommonLabelBase{scrextend}{% - Those who achieve their documents in source code set utmost value to the - fact that future \LaTeX{} runs will yield exactly the same result. In - some cases improvement and bug corrections of packages will result in - changes of the behaviour and make-up. But sometimes this is not wanted.% - }{% - \IfThisCommonLabelBase{scrlttr2}{% - In some cases improvement and bug corrections of classes will result - in changes of the behaviour and make-up. But sometimes this is not - wanted.% - }{\InternalCommonFileBaseError}% - }% - }% -} + % \IfThisCommonLabelBase{scrextend}{% + % In some cases, improvements and bug fixes to the package will result + % in changes of behaviour, especially to the layout. This, however, + % may be undesirable. Those who produce their documents from source code + % typically attach the utmost importance to the fact that future + % \LaTeX{} runs will yield exactly the same result.% + % }{% + \ThisCommonLabelBaseFailure + % \IfThisCommonLabelBase{scrlttr2}{% + % In some cases, improvements and bug fixes to the package will result + % in changes of behaviour, especially to the layout. This, however, + % may be undesirable. + % }{}% + % }% +}% + \begin{Declaration} \OptionVName{version}{value}% \OptionValue{version}{first}% \OptionValue{version}{last} \end{Declaration} -\IfThisCommonLabelBase{scrextend}{At }{Since }% -\ChangedAt{v2.96a}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% -\ChangedAt{v2.9t}{\Class{scrlttr2}}% -\ChangedAt{v3.01b}{\Package{typearea}}% -\IfThisCommonLabelBase{typearea}{% - version~3.01b of \Package{typearea} }{% - \IfThisCommonLabelBase{maincls}{% - version~2.96a of \KOMAScript{} }{% - \IfThisCommonLabelBase{scrlttr2}{% - version~2.9t of \Class{scrlttr2} }{% - \IfThisCommonLabelBase{scrextend}{% - \Package{scrextend} }{\InternalCommonFileUsageError}% +%\ChangedAt{v2.96a}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% +%\ChangedAt{v2.9t}{\Class{scrlttr2}}% +%\ChangedAt{v3.01b}{\Package{typearea}}% +\IfThisCommonLabelBase{scrextend}{With \Package{scrextend}, you can}{Since + \IfThisCommonLabelBase{typearea}{% + Version~3.01b, \Package{typearea}\ChangedAt{v3.01b}{\Package{typearea}}}{% + \IfThisCommonLabelBase{maincls}{% + Version~2.96a, \KOMAScript{}\ChangedAt{v2.96a}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}}}{% + \IfThisCommonLabelBase{scrlttr2}{% + Version~2.9t, \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}}% + \ChangedAt{v2.9t}{\Class{scrlttr2}}}{% + \InteralCommonFileUsageError}% }% }% -}% -it's your choice if your source code should result in the same make-up at -future \LaTeX{} runs or if you like to participate in all improvements of new -releases\IfThisCommonLabelBaseOneOf{maincls,scrlttr2}{ of the class}{}. You -may select the compatible version of \KOMAScript{} with option -\Option{version}. Compatibility to the lowest supported \KOMAScript{} release -may be achieved by +\ has been able to } +choose whether the source file should, as much as possible, +continue to produce exactly the same result within a \LaTeX{} run or should +be formatted according to the modifications of the latest version% +\IfThisCommonLabelBaseOneOf{maincls,scrlttr2}{ of the class}{}. You +can specify the version with which you want your file to be compatible by +using the \Option{version} option. Compatibility with the oldest supported +\KOMAScript{} version can be achieved with \OptionValue{version}{first}\important{\OptionValue{version}{first}} or \OptionValue{version}{2.9} or \OptionValue{version}{2.9t}. Setting \PName{value} to an unknown release number will result in a warning message and selects \OptionValue{version}{first} for safety. -With \OptionValue{version}{last} the most recent version will be selected at -every \LaTeX{} run. Be warned, though, that using \OptionValue{version}{last} -poses possibilities of compatibility issues for future \LaTeX{} runs. Option -\Option{version} without any \PName{value} means the -same. \ChangedAt{v3.01a}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}\and \Class{scrlttr2}\and \Package{scrextend}}This is the -default behaviour as long as you do not use any deprecated options. +With \OptionValue{version}{last}\important{\OptionValue{version}{last}}% +\textnote{default}, you can select the latest version. In this case, you give +up backwards compatibility. If the option is used without a value, +\PValue{last} is assumed. This\ChangedAt{v3.01a}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}\and \Class{scrlttr2}\and + \Package{scrextend}} also corresponds to the default setting, as long as you +do not use any deprecated options. -If\textnote{Attention!} you use a deprecated option of \KOMAScript~2, -\KOMAScript~3 will switch to \OptionValue{version}{first} automatically. This -will also result in a warning message that explains how to prevent this -switching. Alternatively you may select another adjustment using option -\Option{version} with the wanted compatibility after the deprecated option. +\IfThisCommonLabelBase{scrextend}{% scrextend doesn't recognize obsolete options +}{% + If\textnote{Attention!} you use a deprecated option of \KOMAScript~2, + \KOMAScript~3 will switch to \OptionValue{version}{first} automatically. + This will also result in a warning message that explains how to prevent + this switch. Alternatively, you can choose a different setting for + \Option{version} with the desired compatibility after the deprecated + option.% +} -Compatibility is primarily make-up compatibility. New features not related to -the mark-up will be available even if you switch compatibility to a version -before first implementation of the feature. Option \Option{version} does not -influence make-up changes that are motivated by bug fixes. If you need bug -compatibility you should physically save the used \KOMAScript{} version -together with your document. +Compatibility is primarily a question of line and page breaks (wrapping). If +you choose compatibility with an older version, new options that do not affect +wrapping are still available. The \Option{version} option does not affect any +wrapping changes that are the result of fixing unambiguous errors. +If\textnote{Hint!} you need unconditional wrapping compatibility even in the +case of bugs, you should physically save the old \KOMAScript{} version you +need together with your document. \IfThisCommonLabelBase{scrlttr2}{% \begin{Example} - The letter examples of this chapter should use and show all the features - of the recent \KOMAScript{} release. To achieve this, we set the - corresponding compatibility:% + The example letters in this chapter should use all the features of the + latest version of \KOMAScript{}. For this, the we set the compatibility + correspondingly when loading the class:% \lstinputcode[xleftmargin=1em,lastline=1]{letter-0.tex}% In this case the symbolic value \PValue{last} has been used to select the latest version.% - \end{Example}% -}{} + \iftrue% Umbruchkorrektur + Here, the latest version was simply chosen with the symbolic value + \PValue{last}.% + \else% + In order not to have to specify a new version number for each new version, + the symbolic value \PValue{last} was chosen here.% + \fi + \end{Example}}{} -Please note\textnote{Attention!} that you cannot change option -\Option{version} anymore after loading the % +Note\textnote{Attention!} that you cannot change the \Option{version} option +after loading the % \IfThisCommonLabelBaseOneOf{maincls,scrlttr2}{class}{% - package \IfThisCommonLabelBase{typearea}{\Package{typearea}}{% - \IfThisCommonLabelBase{scrextend}{\Package{scrextend}}{% + \IfThisCommonLabelBase{typearea}{\Package{typearea}}{% + \IfThisCommonLabelBase{scrextend}{\Package{scrextend}}{% \InternalCommonFileUsageError }% }% -}. Therefore, the usage of option \Option{version} within the argument of +\ package}. Setting this option with \DescRef{\ThisCommonLabelBase.cmd.KOMAoptions} or -\DescRef{\ThisCommonLabelBase.cmd.KOMAoption} is not recommended and will -cause an error.% +\DescRef{\ThisCommonLabelBase.cmd.KOMAoption} will +therefore cause an error.% \EndIndexGroup % \EndIndexGroup +\phantomsection +\label{sec:\ThisCommonLabelBase.compatibilityOptions.end} +\endinput + %%% Local Variables: %%% mode: latex %%% coding: us-ascii diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-dictum.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-dictum.tex index c89b4e093a6..5dff550ac7d 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-dictum.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-dictum.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-dictum.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % common-dictum.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,42 +46,51 @@ % ====================================================================== \KOMAProvidesFile{common-dictum.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (common paragraphs)] -\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi} +\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi\and + Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-01-29 \section{Dicta} \seclabel{dictum}% \BeginIndexGroup -\BeginIndex{}{smart slogan}% +\BeginIndex{}{saying}% \BeginIndex{}{dictum}% -\BeginIndex{}{excerpt}% +\BeginIndex{}{epigraph}% \IfThisCommonFirstRun{}{% - What is written in \autoref{sec:\ThisCommonFirstLabelBase.dictum} applies, - mutatis mutandis. % + The information in \autoref{sec:\ThisCommonFirstLabelBase.dictum} applies + equally to this chapter. % \IfThisCommonLabelBase{scrextend}{% However, \Package{scrextend} does not support the commands \DescRef{maincls.cmd.setchapterpreamble} and - \DescRef{maincls.cmd.setpartpreamble}. You should read the manual of the - used class, if you want to know, if that class does support similar - commands. % + \DescRef{maincls.cmd.setpartpreamble}. + \iftrue% Umbruchvariante + Whether the class you are using offers an equivalent instruction + can be found in the documentation for the respective class .% + \fi% }{}% - So if you have alread read and understood - \autoref{sec:\ThisCommonFirstLabelBase.dictum} you can jump to - \autoref{sec:\ThisCommonLabelBase.dictum.next} on + So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.dictum}, you can skip ahead to + \autoref{sec:\ThisCommonLabelBase.dictum.next}, \autopageref{sec:\ThisCommonLabelBase.dictum.next}.% -} - -Sometimes you may find a dictum, a kind of smart slogan or excerpt, often -ragged left above or below the heading of a chapter or section. The text and -the source of the slogan often use special styles. +}{}% +\IfThisCommonLabelBase{scrextend}{% Umbruchkorrekturvarianten + A common element in a document is an epigraph or quotation that is set above + or below a chapter or section heading, typically right-justified. The + epigraph and its source are usually specially formatted.% +}{% + A common element in a document is an epigraph or quotation that is set above + or below a chapter or section heading, along with a reference to the source + and its own formatting.% +} % +\KOMAScript{} refers to such an epigraph as a \emph{dictum}. \begin{Declaration} - \Macro{dictum}\OParameter{author}\Parameter{dictum}% + \Macro{dictum}\OParameter{author}\Parameter{text}% \Macro{dictumwidth}% \Macro{dictumauthorformat}\Parameter{author}% \Macro{dictumrule}% @@ -89,30 +98,34 @@ the source of the slogan often use special styles. \Macro{raggeddictumtext}% \Macro{raggeddictumauthor} \end{Declaration}% -The command \Macro{dictum} inserts such a dictum. % +You can set such a saying with the help of the \Macro{dictum} command. % \IfThisCommonLabelBase{maincls}{% - This\textnote{Hint!} macro can be used as obligatory argument of either the - command \DescRef{maincls.cmd.setchapterpreamble} or - \DescRef{maincls.cmd.setpartpreamble}. However, this is not obligatory.\par% + This\textnote{Hint!} macro can be included in the mandatory argument of + either the \DescRef{maincls.cmd.setchapterpreamble} or the + \DescRef{maincls.cmd.setpartpreamble} command. However, this is not + obligatory.\par% }{}% -The dictum together with an optional \PName{author} is inserted in a +The dictum, along with an optional \PName{author}, is inserted in a \Macro{parbox}\IndexCmd{parbox} (see \cite{latex:usrguide}) of width -\Macro{dictumwidth}. Yet \Macro{dictumwidth} is not a length which can be set -with \Macro{setlength}. It is a macro that can be redefined using -\Macro{renewcommand}. Default setting is \PValue{0.3333\Length{textwidth}}, -which is a third of the textwidth. The box itself is positioned with the -command \Macro{raggeddictum}. Default here is -\Macro{raggedleft}\IndexCmd{raggedleft}, that is, right justified. The -command \Macro{raggeddictum} can be redefined using \Macro{renewcommand}. +\Macro{dictumwidth}. However, \Macro{dictumwidth} is not a length which can be +set with \Macro{setlength}. It is a macro that can be redefined using +\Macro{renewcommand}. The default is \PValue{0.3333\Length{textwidth}}, which +is one third of the text width. The box itself is aligned with the command +\Macro{raggeddictum}. The default is \Macro{raggedleft}\IndexCmd{raggedleft}, +that is, right justified. \Macro{raggeddictum} can be redefined +with \IfThisCommonLabelBase{scrextend}{% Umbruchoptimierung +}{the help of }\Macro{renewcommand}. +You can align the \PName{dictum} within the box using +\Macro{raggeddictumtext}\important{\Macro{raggeddictumtext}}. +The default is \Macro{raggedright}\IndexCmd{raggedright}, that is, left +justified. You can also redefine this macro with \Macro{renewcommand}.% \BeginIndexGroup \BeginIndex{FontElement}{dictum}\LabelFontElement{dictum}% -Within the box the \PName{dictum} is set using \Macro{raggeddictumtext}. -Default setting is \Macro{raggedright}\IndexCmd{raggedright}, that is, left -justified. Similarly to \Macro{raggeddictum} this can be redefined with -\Macro{renewcommand}. The output uses the default font setting for the -element \FontElement{dictum}, which can be changed with the commands -\DescRef{\ThisCommonLabelBase.cmd.setkomafont} and +\LabelFontElement{dictumtext}% +The output uses the default font setting for the element +\FontElement{dictum}\important{\FontElement{dictum}}, which can be changed +with the commands \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and \DescRef{\ThisCommonLabelBase.cmd.addtokomafont} (see \autoref{sec:\ThisCommonLabelBase.textmarkup}, \DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}). Default settings are @@ -141,9 +154,10 @@ listed in \autoref{tab:maincls.dictumfont}% }{% , \autopageref{tab:\ThisCommonFirstLabelBase.dictumfont}.% } +\EndIndexGroup -If there is an \PName{author} name, it is separated from the \PName{dictum} by -a rule to the full width of the \Macro{parbox}. This% +If an \PName{author} is defined, it is separated from the \PName{dictum} by +a horizontal rule spanning the full width of the \Macro{parbox}. This% \IfThisCommonLabelBase{maincls}{% \ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% @@ -152,81 +166,85 @@ a rule to the full width of the \Macro{parbox}. This% \ChangedAt{v3.10}{\Package{scrextend}}% }{\InternalCommonFileUsageError}% } % -rule is defined as vertical object to command \Macro{dictumrule}: +rule is defined in \Macro{dictumrule}\important{\Macro{dictumrule}} as a +vertical object with \begin{lstcode} \newcommand*{\dictumrule}{\vskip-1ex\hrulefill\par} \end{lstcode} -The alignment is defined with \Macro{raggeddictumauthor}. Default is +The \Macro{raggeddictumauthor}\important{\Macro{raggeddictumauthor}} command +defines the alignment for the rule and the \PName{author}. The default is \Macro{raggedleft}. This command can also be redefined using -\Macro{renewcommand}. The format of the output is defined with -\Macro{dictumauthorformat}. This macro expects the \PName{author} as -argument. As default \Macro{dictumauthorformat} is defined as: +\Macro{renewcommand}. The format is defined with +\Macro{dictumauthorformat}\important{\Macro{dictumauthorformat}}. This macro +expects the \PName{author} text as its argument. By default +\Macro{dictumauthorformat} is defined as \begin{lstcode} \newcommand*{\dictumauthorformat}[1]{(#1)} \end{lstcode} +Thus the \PName{author} is set enclosed in rounded parentheses. +\BeginIndexGroup \BeginIndex{FontElement}{dictumauthor}\LabelFontElement{dictumauthor}% -Thus the \PName{author} is set enclosed in rounded parentheses. For the -element \FontElement{dictumauthor}, a different font than for the element -\DescRef{\LabelBase.fontelement.dictum} can be defined. Default settings are +For the \FontElement{dictumauthor}\important{\FontElement{dictumauthor}} +element, you can define a different font than that used for the +\DescRef{\LabelBase.fontelement.dictum} element. The default settings are listed in \autoref{tab:maincls.dictumfont}. Changes can be made using the -commands \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and -\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} (see +\DescRef{\ThisCommonLabelBase.cmd.setkomafont} and +\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} commands (see \autoref{sec:\ThisCommonLabelBase.textmarkup}, \DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}).% \EndIndexGroup \IfThisCommonLabelBase{maincls}{% - If \Macro{dictum} is used within the macro + If you use \Macro{dictum} within the \DescRef{maincls.cmd.setchapterpreamble} or - \DescRef{maincls.cmd.setpartpreamble} you have to take care of the - following: the horizontal positioning is always done with - \Macro{raggeddictum}. Therefore, the optional argument for horizontal - positioning which is implemented for these two commands has no - effect. \Length{textwidth} is not the width of the whole text corpus but the - actually used text width. If \Macro{dictumwidth} is set to + \DescRef{maincls.cmd.setpartpreamble} macro, you must ensure that + the horizontal positioning is always done with + \Macro{raggeddictum}. Therefore, the optional argument for horizontal + positioning which is implemented for these two commands has no effect. + \Length{textwidth} is not the width of the whole text body but the + current text width. If \Macro{dictumwidth} is set to \PValue{.5\Length{textwidth}} and \DescRef{maincls.cmd.setchapterpreamble} has an optional width of \PValue{.5\Length{textwidth}} too, you will get a - box with a width one quarter of the text width. Therefore, if you use - \Macro{dictum} it is recommended to refrain from setting the optional width - for \DescRef{maincls.cmd.setchapterpreamble} or + box with a width one quarter of the text width. Therefore, if you use + \Macro{dictum} you should refrain from setting the optional width for + \DescRef{maincls.cmd.setchapterpreamble} or \DescRef{maincls.cmd.setpartpreamble}. If\textnote{Hint!} you have more than one dictum, one under another, you - should separate them by an additional vertical space, easily accomplished - using the command \Macro{bigskip}\IndexCmd{bigskip}.% + should separate them by an additional vertical space, which is easily + accomplished using the \Macro{bigskip}\IndexCmd{bigskip} command.% \iftrue% }{\csname iffalse\endcsname} - \begin{Example} - You are writing a chapter on an aspect of weather forecasting. You - have come across an aphorism which you would like to place at the - beginning of the chapter beneath the heading. You could write: + \begin{Example} + You are writing a chapter about modern marriage, and you want to place a + dictum in the preamble to the chapter heading. You write: \begin{lstcode} \setchapterpreamble[u]{% - \dictum[Anonymous]{Forecasting is the art of saying - what is going to happen and then to explain - why it didn't.}} - \chapter{Weather forecasting} + \dictum[Schiller]{So pause ye who would link your fates~\dots}} + \chapter{Modern Marriage} \end{lstcode} - The output would look as follows: - \begin{ShowOutput} - {\usekomafont{disposition}\usekomafont{chapter}% - 17\enskip Weather forecasting\par} \vspace{\baselineskip} - \dictum[Anonymous]{Forecasting is the art of saying what is going to - happen and then to explain why it didn't.} - \end{ShowOutput} - - If you would rather the dictum span only a quarter of the text width - rather than one third you can redefine \Macro{dictumwidth}: + The output would look as follows: + \begin{ShowOutput} + {\usekomafont{disposition}\usekomafont{chapter}% + 17\enskip Modern Marriage\par} \vspace{\baselineskip} + \dictum[Schiller]{So pause ye who would link + your fates~\dots} + \end{ShowOutput} + + If you want the dictum to span only a quarter of the text width + rather than a third, you can redefine \Macro{dictumwidth} this way: \begin{lstcode} \renewcommand*{\dictumwidth}{.25\textwidth} \end{lstcode} - \end{Example} +\end{Example} - For a somewhat more sophisticated formatting of left- or right-aligned - paragraphs including hyphenation you can use the - package~\Package{ragged2e}~\cite{package:ragged2e}.% +\IfThisCommonLabelBase{maincls}{}{% Umbruchkorrekturtext + At this point, note the \Package{ragged2e}\important{\Package{ragged2e}}% + \IndexPackage{ragged2e} package, with which you can produce unjustified text + that uses hyphenation (see \cite{package:ragged2e}).% +}% \fi % \EndIndexGroup @@ -235,6 +253,8 @@ commands \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and %%% Local Variables: %%% mode: latex +%%% mode: flyspell %%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" %%% TeX-master: "../guide" -%%% End: +%%% End: diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-draftmode.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-draftmode.tex index de1f947fcdb..383c9236c56 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-draftmode.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-draftmode.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-draftmode.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % common-draftmode.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,11 +46,12 @@ % ====================================================================== \KOMAProvidesFile{common-draftmode.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-02-28 13:23:23 +0100 (Wed, 28 Feb 2018) $ KOMA-Script guide (common paragraphs)] -\translator{Markus Kohm\and Gernot Hassenpflug\and Krickette Murabayashi} +\translator{Markus Kohm\and Gernot Hassenpflug\and Krickette Murabayashi\and + Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-01-30 \section{Draft Mode} \seclabel{draft}% @@ -58,45 +59,69 @@ \BeginIndex{}{draft mode}% \IfThisCommonFirstRun{}{% - What is written in \autoref{sec:\ThisCommonFirstLabelBase.draft} - applies, mutatis mutandis. So if you have alread read and understood - \autoref{sec:\ThisCommonFirstLabelBase.draft} you can jump to - \autoref{sec:\ThisCommonLabelBase.draft.next} on + The information in \autoref{sec:\ThisCommonFirstLabelBase.draft} applies + equally to \IfThisCommonLabelBase{scrlttr2}{\Class{scrlttr2}% + \OnlyAt{\Class{scrlttr2}}}{this chapter}. So if you have already read + and understood \autoref{sec:\ThisCommonFirstLabelBase.draft}, you can skip + ahead to \autoref{sec:\ThisCommonLabelBase.draft.next} on \autopageref{sec:\ThisCommonLabelBase.draft.next}.% + \IfThisCommonLabelBase{scrlttr2}{ The \Package{scrletter} package does not + provide a draft mode itself but relies upon the class you use.}{}% } -Many classes and packages provide a draft mode aside from the final -typesetting mode. The difference of draft and final mode may be as manifold as -the classes and package that support these modes. For instance, the -\Package{graphics}\IndexPackage{graphics} and the -\Package{graphicx}\IndexPackage{graphicx} packages do not actually output the -graphics in their own draft mode. Instead they output a framed box of the -appropriate size containing only the graphic's file name (see -\cite{package:graphics}).% +Many classes and packages provide a draft mode in addition to the normal +typesetting mode. The differences between these two are as diverse as +the classes and packages that offer this distinction.% +\IfThisCommonLabelBase{scrextend}{% Umbruchkorrekturtext + \ The draft mode of some packages also results in changes to the output + that affect the document's layout. This is not the case with + \Package{scrextend}.% +}{} \begin{Declaration} \OptionVName{draft}{simple switch} + \OptionVName{overfullrule}{simple switch} \end{Declaration}% -This option\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}\and \Class{scrlttr2}} is normally used to distinguish -between the draft and final versions of a document. \PName{simple switch} -value may be any standard value from \autoref{tab:truefalseswitch}, -\autopageref{tab:truefalseswitch}. In particular, switching on the option -\important{\OptionValue{draft}{true}} activates small black boxes that are set -at the end of overly long lines. The boxes help the untrained eye to find -paragraphs that have to be treated manually. With the default -\OptionValue{draft}{false} option no such boxes are shown. Such overly long -lines often vanish using package +The \Option{draft}\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrartcl}\and + \Class{scrreprt}}% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.00}{\Class{scrlttr2}}\OnlyAt{\Class{scrlttr2}}% + }{}% +} option distinguishes between documents being drafted and finished +documents\Index{final version}. The \PName{simple switch} can be one of the +standard values for simple switches from \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch}. If you activate this +option\important{\OptionValue{draft}{true}}, small black boxes will be output +at the end of overly long lines. These boxes make it easier for the untrained +eye to locate the paragraphs that require manual post-processing. By contrast, +the default, \OptionValue{draft}{false}, shows no such boxes. Incidentally, +such lines often disappear when you use the \Package{microtype}\IndexPackage{microtype}\important{\Package{microtype}} -\cite{package:microtype}. +package \cite{package:microtype}. + +Since\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.25}{\Class{scrbook}\and \Class{scrartcl}\and + \Class{scrreprt}}% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.25}{\Class{scrlttr2}}% + }{% + \IfThisCommonLabelBase{scrextend}{% + \ChangedAt{v3.25}{\Package{scrextend}}% + }{}% + }% +} the \Option{draft} option can lead to all sorts of unwanted effects with +various packages, \KOMAScript{} allows you to control this marking of overly +long lines separately with the +\Option{overfullrule}\important{\OptionValue{overfullrule}{true}} option. If +this option is enabled, the marker is again displayed.% +% \EndIndexGroup % \EndIndexGroup -\phantomsection -\label{sec:\ThisCommonLabelBase.draft.end}% -\endinput - %%% Local Variables: %%% mode: latex %%% coding: us-ascii diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-fontsize.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-fontsize.tex index 25a090c3f64..843f9482f2d 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-fontsize.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-fontsize.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-fontsize.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % common-fontsize.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,107 +46,132 @@ % ====================================================================== \KOMAProvidesFile{common-fontsize.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (common paragraphs: fontsize)] -\translator{Markus Kohm\and Krickette Murabayashi} +\translator{Markus Kohm\and Krickette Murabayashi\and Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2017-12-13 -\section{Selection of the Document Font Size} +\section{Choosing the Document Font Size} \seclabel{fontOptions}% \BeginIndexGroup \BeginIndex{}{font>size}% -\IfThisCommonFirstRun{}{% - What is described in \autoref{sec:\ThisCommonFirstLabelBase.fontOptions} - applies, mutatis mutandis. So if you have alread read and understood - \autoref{sec:\ThisCommonFirstLabelBase.fontOptions} you can jump to the - \IfThisCommonLabelBase{scrlttr2}{example at the }{% - \IfThisCommonLabelBase{last paragraph at the }{}% - }% - end of this section on - \autopageref{sec:\ThisCommonLabelBase.fontOptions.end}.% +\IfThisCommonFirstRun{% + The main font and its size are central elements in the design of a document. + As stated in \autoref{cha:typearea}, the division of the page into the text + area and the margins fundamentally depends on them. The main font is the one + that is used for most of the text in a document. All variations, whether in + shape, thickness, slant, or size, are related to the main font.% +}{% + The information in \autoref{sec:\ThisCommonFirstLabelBase.fontOptions} + applies equally to + \IfThisCommonLabelBase{scrlttr2}{\Class{scrlttr2}\OnlyAt{scrlttr2}}% + {this chapter}. \IfThisCommonLabelBase{scrlttr2}{By contrast, the + \Package{scrletter} package by itself does not offer font-size selection + but depends completely on the class you use.}{} So if you have already + read and understood \autoref{sec:\ThisCommonFirstLabelBase.fontOptions}, you + can \IfThisCommonLabelBase{scrlttr2}{continue to + \autopageref{sec:\ThisCommonLabelBase.fontOptions.end} at the end of this + section. If you use \Package{scrletter}, you can }{}% + skip directly to \autoref{sec:\ThisCommonLabelBase.fontOptions.next}, + \autopageref{sec:\ThisCommonLabelBase.fontOptions.next}.% } -The main document font size is one of the basic decisions for the document -layout. The maximum width of the text area, and therefore splitting the page -into text area and margins, depends on the font size as stated in -\autoref{cha:typearea}. The main document font will be used for most -of the text. All font variations either in mode, weight, declination, or size -should relate to the main document font. - - \begin{Declaration} \OptionVName{fontsize}{size} \end{Declaration} -In contrast to the standard classes and most other classes that provide only -a very limited number of font sizes, the \KOMAScript{} classes offer the -feature of selection of any desired \PName{size} for the main document -font. In this context, any well known \TeX{} unit of measure may be used and -using a number without unit of measure means \PValue{pt}.\iffree{}{ More - information about font size selection for experts and interested users may - be found in \autoref{sec:maincls-experts.addInfos}, +While\IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{% + \textnote{\KOMAScript{} vs. standard classes}} the standard classes support +only a very limited number of font sizes, +\IfThisCommonLabelBase{scrlttr2}{\Class{scrlttr2}}{\KOMAScript} provides the +ability to specify any \PName{size} for the main font. You can also use any +known \TeX unit as a unit for the \PName{size}. If the \PName{size} is +specified without a unit, it is assumed to be \PValue{pt}.\iffree{}{ The exact + procedure for setting the font size is documented for experts and interested + users in \autoref{sec:maincls-experts.addInfos}, \DescPageRef{maincls-experts.option.fontsize}.} -If you use this option inside the document, the main document font size and -all dependent sizes will change from this point. This may be useful, e.\,g., -if \IfThisCommonLabelBase{scrlttr2}{one more letter }{the appendix }% -should be set using smaller fonts on the whole. It should be noted that -changing the main font size does not result in an automatic recalculation of -type area and margins (see +If you set the option within the document, the main font size and the +dependent font sizes of the commands \Macro{tiny}, \Macro{scriptsize}, +\Macro{footnotesize}, \Macro{small}, \Macro{normalsize}, \Macro{large}, +\Macro{Large}, \Macro{LARGE}, \Macro{huge} and \Macro{Huge} are changed. This +can be useful, for example, if you want % +\IfThisCommonLabelBase{scrlttr2}{another letter }{the appendix }% +to be set in a smaller font size. + +Note\textnote{Attention!} that using this option after +\IfThisCommonLabelBase{scrextend}{potentially loading + \hyperref[cha:typearea]{\Package{typearea}}\IndexPackage{typearea}% + \important{\hyperref[cha:typearea]{\Package{typearea}}}}{loading the class} +does not automatically recalculate the type area and margins (see \DescRef{typearea.cmd.recalctypearea}\IndexCmd{recalctypearea}, -\autoref{sec:typearea.options}, -\DescPageRef{typearea.cmd.recalctypearea}). On the other hand, each -recalculation of type area and margins will be done on the basis of the -current main font size. The effects of changing the main font size to other -additionally loaded packages or the used document class depend on those -packages and the class. This may even result in error messages or typesetting -errors, which cannot be considered a fault of \KOMAScript, and even the -\KOMAScript{} classes do not change all lengths if the main font size changes -after loading the class. +\autoref{sec:typearea.typearea}, +\DescPageRef{typearea.cmd.recalctypearea}). However, if this recalculation is +performed, it will be based on the current main font size. The effects of +changing the main font size upon other loaded packages or the class used +depends on these packages and on the class. \IfThisCommonLabelBase{maincls}{% + This means that you can encounter errors which are not the fault of + \KOMAScript, and even the \KOMAScript{} classes themselves do not + recalculate all lengths if the main font size changes after loading the + class.% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + You can encounter errors which are not the fault of \KOMAScript{}, and + further, the \Class{scrlttr2} class itself does not recalculate all + lengths if the main font size changes after loading the class.% + }{% + This means that you can encounter errors which are not the fault of + \KOMAScript{}.% + }% +}% -This\textnote{Attention!} option is not intended to be a substitution for -\Macro{fontsize} (see \cite{latex:fntguide}). Also, you should not use it -instead of one of the main font depending font size commands \Macro{tiny} up -to \Macro{Huge}!% -\phantomsection\label{sec:\ThisCommonLabelBase.fontOptions.end}% +This\textnote{Attention!} option should by no means be misinterpreted as a +substitute for \Macro{fontsize} (see \cite{latex:fntguide}). Also, you should +not use it in place of one of the font size commands that are relative to the +main font, from \Macro{tiny} to \Macro{Huge}. \IfThisCommonLabelBase{scrlttr2}{% - \ Default at \Class{scrlttr2} is \OptionValue{fontsize}{12pt}. + For \Class{scrlttr2} the default is \OptionValue{fontsize}{12pt}. \begin{Example} - Assumed, the example is a letter to \emph{``The friends of insane font - sizes''} and therefor it should be printed with 14\Unit{pt} instead of - 12\Unit{pt}. Only a simple change of the first line is needed:% + \phantomsection\label{sec:\ThisCommonLabelBase.fontOptions.end}% + Suppose the organization in the sample letter is the \emph{``Friends of + Noxious Font Sizes''}, for which reason it should be set in 14\Unit{pt} + instead of 12\Unit{pt}. You can achieve this by making a small change to + the first line:% \lstinputcode[xleftmargin=1em]{letter-6}% - Alternatively the option may be set at the optional argument of the - \DescRef{\LabelBase.env.letter} environment:% + Alternatively, the option could be set as an optional argument to + \DescRef{\LabelBase.env.letter}: \lstinputcode[xleftmargin=1em]{letter-5}% - In the case of this late change of the font size no recalculation of the - type area will happen. Because of this, the two results of - \autoref{fig:scrlttr2.letter-5-6} differ. + Since the text area is not recalculated in this late change of the font + size, the two results differ in \autoref{fig:scrlttr2.letter-5-6}. \begin{figure} \centering \frame{\includegraphics[width=.4\textwidth]{letter-5}}\quad \frame{\includegraphics[width=.4\textwidth]{letter-6}} - \caption[{Example: letter with addressee, opening, text, closing, - postscript, distribution list, enclosure, and insane large font - size}]{% - result of a small letter with addressee, opening, text, closing, - postscript, distribution list, enclosure, and insane large font size - (date and folding marks are defaults of DIN-letters): at left one the - font size has been defined by the optional argument of - \DescRef{\LabelBase.env.letter}, at the right one the optional - argument of \DescRef{\LabelBase.cmd.documentclass} has been used} + \caption[{Example: letter with address, salutation, text, closing phrase, + postscript, enclosures, distribution list, and noxiously large font + size}] + {result of a short letter with recipient, opening, text, closing, + postscript, enclosures, distribution list, and a noxiously large font + (the date is set by default): in the left-hand version, the font size + has been defined by the optional argument of + \DescRef{\LabelBase.env.letter}; in the right-hand one, the optional + argument of \DescRef{\LabelBase.cmd.documentclass} has been used} \label{fig:scrlttr2.letter-5-6} \end{figure} \end{Example} }{% \IfThisCommonLabelBase{maincls}{% - The default at \Class{scrbook}, \Class{scrreprt}, and \Class{scrartcl} is + \par + \phantomsection\label{sec:\ThisCommonLabelBase.fontOptions.end}% + The default for \Class{scrbook}, \Class{scrreprt}, and \Class{scrartcl} is \OptionValue{fontsize}{11pt}.\textnote{\KOMAScript{} vs. standard classes} - In contrast, the default of the standard classes would be - \Option{10pt}. You may attend to this if you switch from a standard class - to a \KOMAScript{} class.% + In contrast, the default size in the standard classes is \Option{10pt}. + You may need to account for this difference if you switch from a standard + class to a \KOMAScript{} class\iffree{}{ or when using the + \DescRef{maincls-experts.option.emulatestandardclasses}% + \IndexOption{emulatestandardclasses} option}.% }{}% }% % @@ -154,10 +179,10 @@ to \Macro{Huge}!% % \EndIndexGroup -\endinput - %%% Local Variables: %%% mode: latex +%%% mode: flyspell %%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" %%% TeX-master: "../guide" -%%% End: +%%% End: diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-footnotes.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-footnotes.tex index a99f9abb53d..c08b203b298 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-footnotes.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-footnotes.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-footnotes.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % common-footnotes.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,11 +46,11 @@ % ====================================================================== \KOMAProvidesFile{common-footnotes.tex} - [$Date: 2017-04-13 09:48:05 +0200 (Thu, 13 Apr 2017) $ + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (common paragraphs: Footnotes)] -\translator{Markus Kohm\and Krickette Murabayashi} +\translator{Markus Kohm\and Krickette Murabayashi\and Karl Hagen} -% Date of the translated German file: 2017-04-13 +% Date of the translated German file: 2018-01-29 \section{Footnotes} \seclabel{footnotes}% @@ -58,40 +58,69 @@ \BeginIndex{}{footnotes}% \IfThisCommonFirstRun{}{% - All of what is described in - \autoref{sec:\ThisCommonFirstLabelBase.footnotes} is generally - applicable. So if you have alread read and understood - \autoref{sec:\ThisCommonFirstLabelBase.footnotes} you can switch to - \autoref{sec:\ThisCommonLabelBase.footnotes.next}, + The information in \autoref{sec:\ThisCommonFirstLabelBase.footnotes} applies + equally to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.footnotes}, you can skip ahead to + \autopageref{sec:\ThisCommonLabelBase.footnotes.next}, \autopageref{sec:\ThisCommonLabelBase.footnotes.next}.% + \IfThisCommonLabelBase{scrlttr2}{ % + If you do not use a \KOMAScript{} class, \Package{scrletter}% + \OnlyAt{\Package{scrletter}} relies on the + \hyperref[cha:scrextend]{\Package{scrextend}}\IndexPackage{scrextend}% + \important{\hyperref[cha:scrextend]{\Package{scrextend}}} package. + Therefore, see also \autoref{sec:scrextend.footnotes}, + \autopageref{sec:scrextend.footnotes} when using \Package{scrletter}.% + \iffalse% Umbruchkorrekturtext + \ Note in particular that in this case some typical \KOMAScript{} + extensions are not active by default\textnote{default}. Instead, the + footnotes make use of the class used, or the \LaTeX{} kernel.% + \fi% + }{}% } \IfThisCommonLabelBase{maincls}{% - \KOMAScript{}, unlike the standard classes, provides features for - configuration of the footnote block format.% + Unlike\textnote{\KOMAScript{} vs. standard classes} the standard classes, + \KOMAScript{} offers the ability to configure the format of the footnote + block.% }{% \IfThisCommonLabelBase{scrlttr2}{% - The commands for setting footnotes may be found at each introduction into - \LaTeX, e.\,g., at \cite{lshort}. \KOMAScript{} provides additional - features to change the footnote block format.% + You can find the basic commands to set footnotes in any introduction to + \LaTeX, for example \cite{lshort}. \KOMAScript{}% + \textnote{\KOMAScript{} vs. standard classes} provides additional features + to change the format of the footnote block. % + \iffalse % Umbruchoptimierung + + Whether footnotes should be allowed for letters depends very much on the + type of letter and its layout. For example, you should not allow + footnotes to overlap visually with the letterhead footer or be confused + with the courtesy-copy list. Doing so is the responsibility of the + user.% + + Since footnotes are rarely used in letters, examples in this section have + been omitted. If you need examples, you can find them in + \autoref{sec:\ThisCommonFirstLabelBase.footnotes}, + \autopageref{sec:\ThisCommonFirstLabelBase.footnotes}.% + \fi% }{% \IfThisCommonLabelBase{scrextend}{% - Package \Package{scrextend} supports all the footnote features of the - \KOMAScript{} classes. Nevertheless, by default the footnotes are under - full control of the used class. This changes as soon as command - \DescRef{\ThisCommonLabelBase.cmd.deffootnote} (see - \DescPageRef{\ThisCommonLabelBase.cmd.deffootnote}) has been used. - - Package \Package{scrextend} does not provide settings for the separation - line above the footnotes.% + The footnote capabilities of the \KOMAScript{} classes are also + provided by \Package{scrextend}. By default, the formatting of + footnotes is left to the class used. This changes as soon as you + issue the \DescRef{\ThisCommonLabelBase.cmd.deffootnote} command, + which is explained in detail on + \DescPageRef{\ThisCommonLabelBase.cmd.deffootnote}. + + The options for adjusting the dividing line above footnotes, however, + are not provided by \Package{scrextend}.% }{\InternalCommonFileUsageError}% }% -} +}% \begin{Declaration} \OptionVName{footnotes}{setting} + \Macro{multfootsep} \end{Declaration} -\IfThisCommonLabelBase{scrextend}{At several classes footnotes }{% +\IfThisCommonLabelBase{scrextend}{Many classes mark footnotes }{% Footnotes % \IfThisCommonLabelBase{maincls}{% \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and @@ -101,49 +130,55 @@ \ChangedAt{v3.00}{\Class{scrlttr2}}% }{}% }% + are marked % }% -will be marked with a tiny superscript number in text by default. If more than -one footnote falls at the same place, one may think that it is only one -footnote with a very large number instead of multiple footnotes (i.\,e., -footnote 12 instead of footnotes 1 and 2). Using -\important{\OptionValue{footnotes}{multiple}} -\OptionValue{footnotes}{multiple}\IndexOption{footnotes=~multiple} will -separate multiple footnotes immediately next to each other by a separator -string. The predefined separator at -\DescRef{\ThisCommonLabelBase.cmd.multfootsep}\IndexCmd{multfootsep}\important{\DescRef{\ThisCommonLabelBase.cmd.multfootsep}} -is a single comma without space. The whole mechanism is compatible with -package -\Package{footmisc}\IndexPackage{footmisc}\important{\Package{footmisc}}, -Version~5.3d (see \cite{package:footmisc}). It is related not only to -footnotes placed using -\DescRef{\ThisCommonLabelBase.cmd.footnote}\IndexCmd{footnote}, but -\DescRef{\ThisCommonLabelBase.cmd.footnotemark}\IndexCmd{footnotemark} too. +by default in the text with a small superscript number. If several footnotes +appear in succession at the same point, it gives the impression that there is +one footnote with a large number rather than multiple footnotes (e.\,g. +footnote 12 instead of footnotes 1 and 2). +With\important{\OptionValue{footnotes}{multiple}} +\OptionValue{footnotes}{multiple}\IndexOption{footnotes=~multiple}, footnotes +that follow each other directly are separated with a delimiter instead. The +default delimiter in \Macro{multfootsep}\important{\Macro{multfootsep}} is +defined as a comma without a space: +\begin{lstcode} + \newcommand*{\multfootsep}{,} +\end{lstcode} +This can be redefined. -Command \DescRef{\ThisCommonLabelBase.cmd.KOMAoptions} or -\DescRef{\ThisCommonLabelBase.cmd.KOMAoption} may be used to switch back to -the default \OptionValue{footnotes}{nomultiple} at any time. If any problems -using another package that influences footnotes occur, it is recommended not -to use the option anywhere and not to change the \PName{setting} anywhere +The whole mechanism is compatible with the +\Package{footmisc}\IndexPackage{footmisc}\important{\Package{footmisc}} +package, version~5.3d to 5.5b (see \cite{package:footmisc}). It affects +footnote markers placed using +\DescRef{\ThisCommonLabelBase.cmd.footnote}\IndexCmd{footnote}, as well as +those placed directly with +\DescRef{\ThisCommonLabelBase.cmd.footnotemark}\IndexCmd{footnotemark}. + +You can switch back to the default +\OptionValue{footnotes}{nomultiple} at any time using the +\DescRef{\ThisCommonLabelBase.cmd.KOMAoptions} or +\DescRef{\ThisCommonLabelBase.cmd.KOMAoption} command. However, if you +encounter any problems using another package that alters the footnotes, you +should not use this option, nor should you change the \PName{setting} anywhere inside the document. -A summary of the available \PName{setting} values of \Option{footnotes} may -be found at \autoref{tab:\ThisCommonFirstLabelBase.footnotes}% +A summary of the available \PName{setting} values of \Option{footnotes} can +be found in \autoref{tab:\ThisCommonFirstLabelBase.footnotes}% \IfThisCommonFirstRun{% . \begin{table} - \caption[{Available values for option \Option{footnotes}}] - {Available values for option \Option{footnotes} setting up footnotes} + \caption[{Available values for the \Option{footnotes} option}] + {Available values for the \Option{footnotes} option to configure footnotes} \label{tab:\ThisCommonLabelBase.footnotes} \begin{desctabular} \pventry{multiple}{% - At sequences of immediately following footnote marks, consecutive - marks will be separated by + Consecutive footnote marks will be separated by \DescRef{\ThisCommonLabelBase.cmd.multfootsep}\IndexCmd{multfootsep}.% - \IndexOption{footnotes~=\PValue{multiple}}}% + \IndexOption{footnotes~=\textKValue{multiple}}}% \pventry{nomultiple}{% - Immediately following footnotes will be handled like single footnotes - and not separated from each other.% - \IndexOption{footnotes~=\PValue{nomultiple}}}% + Consecutive footnote marks will be handled like single footnotes + and not separated from each other.% + \IndexOption{footnotes~=\textKValue{nomultiple}}}% \end{desctabular} \end{table}% }{, @@ -158,15 +193,14 @@ be found at \autoref{tab:\ThisCommonFirstLabelBase.footnotes}% \Macro{footnotemark}\OParameter{number}% \Macro{footnotetext}\OParameter{number}\Parameter{text}% \Macro{multiplefootnoteseparator}% - \Macro{multfootsep} \end{Declaration}% -Similar to the standard classes, footnotes in {\KOMAScript} are produced with -the \Macro{footnote} command, or alternatively the paired usage of the -commands \Macro{footnotemark} and \Macro{footnotetext}. As in the standard -classes, it is possible that a page break occurs within a footnote. Normally -this happens if the footnote mark is placed so near the bottom of a page as to -leave {\LaTeX} no choice but to break the footnote onto the next page. -\KOMAScript% +Footnotes in \KOMAScript{} are produced, as they are in the standard classes, +with the \Macro{footnote} command, or alternatively the pair of commands +\Macro{footnotemark} and \Macro{footnotetext}. As in the standard classes, +it is possible for a page break to occur within a footnote. Normally this +happens if the footnote mark is placed so near the bottom of a page as to +leave \LaTeX{} no choice but to move the footnote to the next page. +Unlike\textnote{\KOMAScript{} vs. standard classes} \IfThisCommonLabelBase{maincls}{% \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% @@ -175,95 +209,89 @@ leave {\LaTeX} no choice but to break the footnote onto the next page. \ChangedAt{v3.00}{\Class{scrlttr2}}% }{}% } % -, unlike the standard classes, can recognize and separate consecutive -footnotes -automatically. See\important{\DescRef{\ThisCommonLabelBase.option.footnote}} -the previously documented option -\DescRef{\ThisCommonLabelBase.option.footnotes} for this. +the standard classes, \KOMAScript{} can recognize and separate consecutive +footnotes automatically. +See\important{\DescRef{\ThisCommonLabelBase.option.footnotes}} the previously +documented option \DescRef{\ThisCommonLabelBase.option.footnotes}. -If you want to set the separator manually, you may use -\Macro{multiplefootnoteseparator}. Note that this command should not be -redefined, because it has been defined not only to be the separator string but -also the type style, i.\,e., font size and superscript. The separator string -without type style may be found at \Macro{multfootsep}. The predefined default -is -\begin{lstcode} - \newcommand*{\multfootsep}{,} -\end{lstcode} -and may be changed by redefining the command. +If instead you want to place this delimiter manually, you can do so by calling +\Macro{multiplefootnoteseparator}. However, users should not redefine this +command, as it contains not only the delimiter but also the delimiter's +formatting, for example the font size selection and the superscript. The +delimiter itself is stored in the previously described +\DescRef{\ThisCommonLabelBase.cmd.multfootsep}% +\important{\DescRef{\ThisCommonLabelBase.cmd.multfootsep}}% +\IndexCmd{multfootsep} command. -\IfThisCommonLabelBase{scrlttr2}{% - Examples and additional information may be found at +\IfThisCommonFirstRun{\iftrue}{% + You can find examples and additional hints in \autoref{sec:\ThisCommonFirstLabelBase.footnotes} from - \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.footnote} onward.% - \iffalse% -}{\csname iftrue\endcsname}% + \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.footnote}.% + \csname iffalse\endcsname }% \begin{Example} \phantomsection\xmpllabel{cmd.footnote}% - Assume you want to place two footnotes following a single word. First you - may try + Suppose you want to put two footnotes after a single word. First you try \begin{lstcode} Word\footnote{1st footnote}\footnote{2nd footnote} \end{lstcode} - for this. Assume that the footnotes will be numbered with 1 and 2. Now the - reader may think it's a single footnote 12, because the 2 - immediately follows the 1. You may change this using + Let's assume that the footnotes are numbered 1 and 2. Since the two + footnote numbers follow each other directly, it creates the impression + that the word has only one footnote numbered 12. You can change this + behaviour by using \begin{lstcode} \KOMAoptions{footnotes=multiple} \end{lstcode} - which would switch on the automatic recognition of footnote sequences. As - an alternative you may use + to enable the automatic recognition of footnote sequences. Alternatively, + you can use \begin{lstcode} - Word\footnote{1st footnote}% + word\footnote{Footnote 1}% \multiplefootnoteseparator - \footnote{2nd footnote} + \footnote{Footnote 2} \end{lstcode} - This should give you the wanted result even if the automatic solution - would fail or could not be used. - - Further, assume you want the footnotes separated not only by a single - comma, but by a comma and a white space. In this case you may redefine + This should give you the desired result even if automatic detection + fails or cannot be used for some reason. + + Now suppose you also want the footnote numbers to be separated not just by + a comma, but by a comma and a space. In this case, write \begin{lstcode} \renewcommand*{\multfootsep}{,\nobreakspace} \end{lstcode} - at the document preamble. \Macro{nobreakspace}\IndexCmd{nobreakspace} - instead of a usual space character has been used in this case to avoid - paragraph or at least page breaks within footnote sequences. + in the preamble of your document. + \Macro{nobreakspace}\IndexCmd{nobreakspace} was used here instead of a + normal space to avoid paragraph or page breaks within the sequence of + footnotes. \end{Example}% \fi% +% \EndIndexGroup \begin{Declaration} \Macro{footref}\Parameter{reference} \end{Declaration} -Sometimes% -\IfThisCommonLabelBase{maincls}{% +Sometimes\IfThisCommonLabelBase{maincls}{% \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% }{% \IfThisCommonLabelBase{scrlttr2}{% \ChangedAt{v3.00}{\Class{scrlttr2}}% - }{}% -} % -there are single footnotes to multiple text passages. The least sensible way -to typeset this would be to repeatedly use -\DescRef{\ThisCommonLabelBase.cmd.footnotemark} with the same manually set -number. The disadvantages of this method would be that you have to know the -number and manually fix all the -\DescRef{\ThisCommonLabelBase.cmd.footnotemark} commands, and if the number -changes because of adding or removing a footnote before, each -\DescRef{\ThisCommonLabelBase.cmd.footnotemark} would have to be -changed. Because of this, \KOMAScript{} provides the use of the -\Macro{label}\IndexCmd{label}\important{\Macro{label}} mechanism in such -cases. After simply setting a \Macro{label} inside the footnote, -\Macro{footref} may be used to mark all the other text passages with the same -footnote mark. -\IfThisCommonLabelBase{scrlttr2}{\iffalse}{\csname iftrue\endcsname}% + }{}} you have a footnote in a document to which there are several references +in the text. An inconvenient way to typeset this would be to use +\DescRef{\ThisCommonLabelBase.cmd.footnotemark} to set the number directly. +The disadvantage of this method is that you need to know the number and +manually set every \DescRef{\ThisCommonLabelBase.cmd.footnotemark} command. +And if the number changes because you add or remove an earlier footnote, you +will have to change each \DescRef{\ThisCommonLabelBase.cmd.footnotemark}. +\KOMAScript{} thefore offers the \Macro{label}\IndexCmd{label}% +\important{\Macro{label}} mechanism to handle such cases. After placing a +\Macro{label} inside the footnote, you can use \Macro{footref} to set all the +other marks for this footnote in the text. +\IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname}% \begin{Example} \phantomsection\xmpllabel{cmd.footref}% - Maybe you have to mark each trade name with a footnote which states that - it is a registered trade name. You may write, e.\,g., + You are writing a text in which you must create a footnote each time a + brand name occurs, indicating that it is a registered trademark. You can + write, for example, \begin{lstcode} Company SplishSplash\footnote{This is a registered trade name. All rights are reserved.\label{refnote}} @@ -277,16 +305,20 @@ footnote mark. commands. The footnote text will be produced by \DescRef{\ThisCommonLabelBase.cmd.footnote}. \end{Example} -\fi -Because of setting the additional footnote marks using the \Macro{label} -mechanism, changes of the footnote numbers will need at least two \LaTeX{} -runs to ensure correct numbers for all \Macro{footref} marks.% -\IfThisCommonLabelBase{scrlttr2}{ % - An example for the usage \Macro{footref} can be found in - \autoref{sec:\ThisCommonFirstLabelBase.footnotes} on - \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.footref}.% -}{}% -% + \fi When setting footnote marks with the \Macro{label} mechanism, any + changes to the footnote numbers will require at least two \LaTeX{} runs to + ensure correct numbers for all \Macro{footref} marks.% + \IfThisCommonLabelBaseOneOf{scrlttr2,scrextend}{\par% + You can find an example of how to use \Macro{footref} in + \autoref{sec:\ThisCommonFirstLabelBase.footnotes} on + \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.footref}.% + }{} \IfThisCommonLabelBase{scrlttr2}{}{% + \par + Note\textnote{Attention!} that statements like \Macro{ref}\IndexCmd{ref} + or \Macro{pageref}\IndexCmd{pageref} are fragile and therefore you should + put \Macro{protect}\IndexCmd{protect} in front of them if they appear in + moving arguments such as headings.% + }% \EndIndexGroup @@ -296,37 +328,48 @@ runs to ensure correct numbers for all \Macro{footref} marks.% \Macro{deffootnotemark}\Parameter{definition}% \Macro{thefootnotemark} \end{Declaration}% -Footnotes are formatted slightly differently in {\KOMAScript} to in the -standard classes. As in the standard classes the footnote mark in the text is -depicted using a small superscripted number. The same formatting is used in -the footnote itself. The mark in the footnote is type-set right-aligned in a -box with width \PName{mark width}. The first line of the footnote follows -directly. +\IfThisCommonLabelBase{maincls}{The \KOMAScript{} classes set}{\KOMAScript{} + sets}\textnote{\KOMAScript{} vs. standard classes} footnotes slightly +differently than the standard classes do. As in the standard classes, the +footnote mark in the text is rendered with small, superscript numbers. The +same formatting is used in the footnote itself. The mark in the footnote is +typeset right-justified in a box with a width of \PName{mark width}. The first +line of the footnote follows directly. -All following lines will be indented by the length of \PName{indent}. If the +All subsequent lines will be indented by the length of \PName{indent}. If the optional parameter \PName{mark width} is not specified, it defaults to -\PName{indent}. If the footnote consists of more than one paragraph, then the -first line of a paragraph is indented, in addition to \PName{indent}, by the -value of \PName{parindent}. +\PName{indent}. If the footnote consists of more than one paragraph, the first +line of each paragraph is indented by the value of \PName{parindent}. -\hyperref[fig:maincls.deffootnote]{Figure~\ref*{fig:maincls.deffootnote}} % -\IfThisCommonFirstRun{at \autopageref{fig:maincls.deffootnote} }% -illustrates the layout parameters. The default configuration of the -{\KOMAScript} classes is: +\autoref{fig:\ThisCommonFirstLabelBase.deffootnote} % +\IfThisCommonFirstRun{}{on + \autopageref{fig:\ThisCommonFirstLabelBase.deffootnote} }{}% +shows the different parameters% +\IfThisCommonLabelBase{maincls}{ again}{}% +. The default configuration of the \KOMAScript{} classes is as follows: +\IfThisCommonLabelBase{scrextend}{\iftrue}{\csname iffalse\endcsname}% +\begin{lstcode} + \deffootnote[1em]{1.5em}{1em}{% + \textsuperscript{\thefootnotemark}} +\end{lstcode} +\else \begin{lstcode} - \deffootnote[1em]{1.5em}{1em} - {\textsuperscript{\thefootnotemark}} + \deffootnote[1em]{1.5em}{1em}{% + \textsuperscript{\thefootnotemark}% + } \end{lstcode} +\fi% \DescRef{\ThisCommonLabelBase.cmd.textsuperscript} controls both the -superscript and the smaller font size. Command \Macro{thefootnotemark} is the -current footnote mark without any formatting.% +superscript and the smaller font size. The command \Macro{thefootnotemark} +contains the current footnote mark without any formatting.% \IfThisCommonLabelBase{scrextend}{ % - Package \Package{scrextend} in contrast to this does not change the default - footnote settings of the used class. Loading the package does not change any - type style of footnote marks or footnote text in general. You have to copy - the above shown source to use the default settings of the \KOMAScript{} - classes with \Package{scrextend}. This may be done immediately after loading - package \Package{scrextend}.% + The \Package{scrextend} package, by contrast, does not change the default + footnote settings of the class you are using. Simply loading the package, + therefore, should not lead to any changes in the formatting of footnote + marks or footnote text. To use the default settings of the \KOMAScript{} + classes with \Package{scrextend}, you must change the settings above + yourself. For example, you can insert the line of code above immediately + after loading the \Package{scrextend} package.% }{}% \IfThisCommonLabelBase{maincls}{% @@ -385,81 +428,76 @@ current footnote mark without any formatting.% \BeginIndexGroup \BeginIndex{FontElement}{footnote}\LabelFontElement{footnote}% \BeginIndex{FontElement}{footnotelabel}\LabelFontElement{footnotelabel}% -The% -\IfThisCommonLabelBase{maincls}{% +The footnote\IfThisCommonLabelBase{maincls}{% \ChangedAt{v2.8q}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}% -}{}} font element \FontElement{footnote}\important{\FontElement{footnote}} -determines the font of the footnote including the footnote mark. Using the -element \FontElement{footnotelabel}\important{\FontElement{footnotelabel}} the -font of the footnote mark can be changed separately with the commands +}}{}, including the footnote mark, uses the font specified in the +\FontElement{footnote}\important{\FontElement{footnote}} element. You can +change the font of the footnote mark separately using the \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and -\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} (see +\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} commands (see \autoref{sec:\ThisCommonLabelBase.textmarkup}, -\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}). Please refer also to -\autoref{tab:\ThisCommonLabelBase.fontelements}, +\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}) +for the \FontElement{footnotelabel}\important{\FontElement{footnotelabel}} +element. See also \autoref{tab:\ThisCommonLabelBase.fontelements}, \autopageref{tab:\ThisCommonLabelBase.fontelements}. -Default setting is no change in the font.% +The default setting is no change to the font.% \IfThisCommonLabelBase{scrextend}{ % - With \Package{scrextend} the elements may change the fonts only if the - footnotes are handled by the package, i.\,g., after using + However, with \Package{scrextend} these elements will only change the fonts + if footnotes are handled by the package, that is, after using \Macro{deffootnote}.% -}{} Please don't misuse the element for other purpose, i.e., to use ragged -right footnotes (see also \DescRef{\LabelBase.cmd.raggedfootnote}, +}{} Please don't misuse this element for other purposes, for example to set +the footnotes ragged right (see also \DescRef{\LabelBase.cmd.raggedfootnote}, \DescPageRef{\LabelBase.cmd.raggedfootnote}). \BeginIndex{FontElement}{footnotereference}% \LabelFontElement{footnotereference}% The footnote mark in the text is defined separately from the mark in front of the actual footnote. This is done with -\Macro{deffootnotemark}. Default setting is: +\Macro{deffootnotemark}. The default setting is: \begin{lstcode} \deffootnotemark{% \textsuperscript{\thefootnotemark}} \end{lstcode} -In the above% -\IfThisCommonLabelBase{maincls}{% +With\IfThisCommonLabelBase{maincls}{% \ChangedAt{v2.8q}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% -}{} the font for the element -\FontElement{footnotereference}\important{\FontElement{footnotereference}} is -applied (see \autoref{tab:\ThisCommonLabelBase.fontelements}, -\autopageref{tab:\ThisCommonLabelBase.fontelements}). Thus the footnote marks -in the text and in the footnote itself are identical. The font can be changed +}{} this default, the font for the +\FontElement{footnotereference}\important{\FontElement{footnotereference}} +element is used (see \autoref{tab:\ThisCommonLabelBase.fontelements}, +\autopageref{tab:\ThisCommonLabelBase.fontelements}). Thus, the footnote marks +in the text and in the footnote itself are identical. You can change the font with the commands \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and \DescRef{\ThisCommonLabelBase.cmd.addtokomafont} (see \autoref{sec:\ThisCommonLabelBase.textmarkup}, \DescPageRef{\ThisCommonLabelBase.cmd.setkomafont})% -\IfThisCommonLabelBase{scrextend}{ after usage of \Macro{deffootnotemark}}{}. +\IfThisCommonLabelBase{scrextend}{ after \Macro{deffootnotemark} is used}{}. -\IfThisCommonLabelBase{scrlttr2}{% - Examples may be found at \autoref{sec:\ThisCommonFirstLabelBase.footnotes}, - from \DescPageRef{\ThisCommonFirstLabelBase.cmd.deffootnote} onwards.% - \iffalse% -}{\csname iftrue\endcsname}% +\IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname}% \begin{Example} - \phantomsection\xmpllabel{cmd.deffootnote}% - A\textnote{Hint!} feature often asked for is footnote marks which are - neither in superscript nor in a smaller font size. They should not touch - the footnote text but be separated by a small space. This can be - accomplished as follows: + \phantomsection + \xmpllabel{cmd.deffootnote}% + One\textnote{Hint!} feature that is often requested is footnote marks + which are neither in superscript nor in a smaller font. They should not + touch the footnote text but be separated by a small space. You can + accomplish this as follows: \begin{lstcode} \deffootnote{1em}{1em}{\thefootnotemark\ } \end{lstcode} - The footnote mark and the following space are therefore set - right-aligned into a box of width 1\Unit{em}. The following lines of - the footnote text are also indented by 1\Unit{em} from the left - margin. - - Another\textnote{Hint!} often requested footnote layout is left-aligned - footnote marks. These can be obtained with: + This will set the footnote mark and subsequent space right-aligned in a + box of width 1\Unit{em}. The lines of the footnote text that follow are + also indented by 1\Unit{em} from the left margin. + + Another\textnote{Hint!} layout that is often requested is footnote marks + that are left-aligned. You can obtain them with the following + definition: \begin{lstcode} \deffootnote{1.5em}{1em}{% \makebox[1.5em][l]{\thefootnotemark}} \end{lstcode} - If you want however only to change the font for all footnotes, for example - to sans serif, you can solve this problem simply by using the commands + If, however you want to change the font for all footnotes, for example + to sans serif, this can easily be done with the commands \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and \DescRef{\ThisCommonLabelBase.cmd.addtokomafont} (see \autoref{sec:\ThisCommonLabelBase.textmarkup}, @@ -469,21 +507,23 @@ with the commands \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and \end{lstcode} \end{Example}% \IfThisCommonLabelBase{scrextend}{}{% - As demonstrated with the examples above, the simple user interface of - {\KOMAScript} provides a great variety of different footnote - formattings.% + As the examples show, {\KOMAScript} allows a wide variety of different + footnote formats with this simple user interface.% }% \fi% +\IfThisCommonFirstRun{}{% + For examples, see \autoref{sec:\ThisCommonFirstLabelBase.footnotes}, + \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.deffootnote}.% +}{}% % \EndIndexGroup \EndIndexGroup - +\IfThisCommonLabelBase{scrextend}{\iffalse}{\csname iftrue\endcsname} \begin{Declaration} \Macro{setfootnoterule}\OParameter{thickness}\Parameter{length}% \end{Declaration}% -Generally% -\IfThisCommonLabelBase{maincls}{% +Generally,\IfThisCommonLabelBase{maincls}{% \ChangedAt{v3.06}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% }{% @@ -494,22 +534,20 @@ Generally% \ChangedAt{v3.06}{\Package{scrextend}}% }{}% }% -} % -a horizontal rule will be placed between the text area and the footnote -area. But normally this rule is not as long as the width of the typing -area. With Command \Macro{setfootnoterule} you may change the thickness and -the width of that rule. Thereby the parameters \PName{thickness} and -\PName{length} will be evaluated not at definition time but when setting the -rule itself. If optional argument \PName{thickness} ha been omitted the -thickness of the rule will not be changed. Empty arguments \PName{thickness} -or \PName{length} are also allowed and do not change the corresponding -parameter. Using implausible values may result in warning messages not only -setting the arguments but also when \KOMAScript{} uses the parameters. +} a horizontal rule is set between the text area and the footnote area, but +normally this rule does not extend the full width of the type area. With +\Macro{setfootnoterule}, you can set the exact thickness and length of the +rule. In this case, the parameters \PName{thickness} and \PName{length} are +only evaluated when setting the rule itself. If the optional argument +\PName{thickness} has been omitted, the thickness of the rule will not be +changed. Empty arguments for \PName{thickness} or \PName{length} are also +allowed and do not change the corresponding parameters. Using absurd values +will result in warning messages both when setting and when using the +parameters. \BeginIndexGroup \BeginIndex{FontElement}{footnoterule}\LabelFontElement{footnoterule}% -With element \FontElement{footnoterule}\important{\FontElement{footnoterule}} -the color% +You can% \IfThisCommonLabelBase{maincls}{% \ChangedAt{v3.07}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% @@ -522,21 +560,23 @@ the color% }{}% }% } % -of the rule may be changed using the commands -\DescRef{\ThisCommonLabelBase.cmd.setkomafont} and -\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} for element -\FontElement{footnoterule} (see \autoref{sec:\ThisCommonLabelBase.textmarkup}, -\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}). Default is no change of -font or color. For color changes a color package like -\Package{xcolor}\IndexPackage{xcolor}\important{\Package{xcolor}} would be -needed.% +change the colour of the rule with the +\FontElement{footnoterule}\important{\FontElement{footnoterule}} element using +the \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and +\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} commands (see +\autoref{sec:\ThisCommonLabelBase.textmarkup}, +\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}). The default is no change +of font or colour. In order to change the colour, you must also load a colour +package like +\Package{xcolor}\IndexPackage{xcolor}\important{\Package{xcolor}}.% \EndIndexGroup \EndIndexGroup +\fi \begin{Declaration} \Macro{raggedfootnote} \end{Declaration} -The default% +By default% \IfThisCommonLabelBase{maincls}{% \ChangedAt{v3.23}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% @@ -549,24 +589,31 @@ The default% }{}% }% } % -for the alignment of footnotes in \KOMAScript{} is justified, same as the -default in the standard classes. But \KOMAScript{} provides -\Macro{raggedfootnote} to change this default. Valid definitions of -\Macro{raggedfootnote} would be \Macro{raggedright}\IndexCmd{raggedright}, +\KOMAScript{} justifies footnotes just as in the standard classes. +But\textnote{\KOMAScript{} vs. standard classes} you can also change the +justification separately from the rest of the document by redefining +\Macro{raggedfootnote}. Valid definitions are +\Macro{raggedright}\IndexCmd{raggedright}, \Macro{raggedleft}\IndexCmd{raggedleft}, -\Macro{centering}\IndexCmd{centering}, \Macro{relax}\IndexCmd{relax} or the -empty definition, which is the default. You can also use the alignment -commands of package \Package{ragged2e}\IndexPackage{ragged2e} (see -\cite{package:ragged2e}). - -\begin{Example} - Assuming you are using footnotes only to show informations with very large - links that cannot be printed justified accommdatingly. You can use +\Macro{centering}\IndexCmd{centering}, \Macro{relax}\IndexCmd{relax} or an +empty definition, which is the default. The alignment commands of the +\Package{ragged2e}\IndexPackage{ragged2e} package are also valid (see +\cite{package:ragged2e}). \IfThisCommonLabelBase{scrextend}{% + You can find a suitable example in + \autoref{sec:\ThisCommonFirstLabelBase.footnotes}, + \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.raggedfootnote}.% + \iffalse }{\csname iftrue\endcsname}% + \begin{Example} + \phantomsection\xmpllabel{cmd.raggedfootnote}% + Suppose you are using footnotes only to provide references to very long + links, where line breaks would produce poor results if justified. You can + use \begin{lstcode} \let\raggedfootnote\raggedright \end{lstcode} - in your document preamble to switch to ragged-right footnotes. -\end{Example}% + in your document's preamble to switch to ragged-right footnotes. + \end{Example}% +\fi \EndIndexGroup % \EndIndexGroup diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-headfootheight.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-headfootheight.tex index 54d1873bec5..8f9fcbb9462 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-headfootheight.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-headfootheight.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-headfootheight.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2013-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % common-headfootheight.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2013-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,82 +46,109 @@ % ============================================================================ \KOMAProvidesFile{common-headfootheight.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-02-28 13:23:23 +0100 (Wed, 28 Feb 2018) $ KOMA-Script guide (common paragraph: Head and Foot Height)] -\translator{Markus Kohm\and Jana Schubert\and Jens H\"uhne} +\translator{Markus Kohm\and Jana Schubert\and Jens H\"uhne\and Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-01-16 -\section{Head and Foot Height} +\section{Header and Footer Height} \seclabel{height} \BeginIndexGroup -\BeginIndex{Package}{scrlayer}% -\BeginIndex{}{page>head>height}% -\BeginIndex{}{page>foot>height}% - +\BeginIndex{}{header>height}% +\BeginIndex{}{footer>height}% \IfThisCommonLabelBase{scrlayer-scrpage}{% - \begin{Explain} - The \LaTeX{} standard classes do not use the page footer a lot and if they - do use it, they put the contents into a \Macro{mbox} which results in the + \begin{Explain}% + The \LaTeX{} standard classes do not use the footer much, and if they do + use it, they put the contents into a \Macro{mbox} which results in the footer being a single text line. This is probably the reason that \LaTeX{} - itself does not have a well-defined foot height. Actually there is - \Length{footskip}\IndexLength{footskip} giving the distance between the - last base line of the text area and the base line of the footer. However, - if the footer consists of more than one text line, there is no definite - statement whether this length should be the distance to the first or the - last base line of the footer. + itself does not have a well-defined footer height. Although the distance + between the last baseline of the text area and the baseline of the footer + is defined with \Length{footskip}\IndexLength[indexmain]{footskip}, if the + footer consists of more than one text line, there is no definite statement + whether this length should be the distance to the first or the last + baseline of the footer. - Despite the fact that the page header of the standard classes will also be - put into a horizontal box and therefore is a single text line too, - \LaTeX{} indeed has a length to setup the height of the page header. The - reason for this may be that the height will be needed to determine the - start of the text area. + Although the page header of the standard classes will also be put into a + horizontal box, and therefore is also a single text line, \LaTeX{} in fact + provides a length to set the height of the header. The reason for this may + be that this height is needed to determine the start of the text area. \end{Explain}% }{% - Page head and footer are the main elements not only of a page style. Layer - can also be restricted to these using corresponding options (see - \autoref{tab:scrlayer.layerkeys}, + The header and footer of a page are central elements not just of a page + style. They can also serve to restrict layers using the appropriate options + (see \autoref{tab:scrlayer.layerkeys}, \autopageref{tab:scrlayer.layerkeys}). Therefore the heights of these - elements are very important and have to be well defined.% + elements must be defined.% } \IfThisCommonFirstRun{}{% - All of what is described in - \autoref{sec:\ThisCommonFirstLabelBase.height} is generally - applicable. So if you have alread read and understood - \autoref{sec:\ThisCommonFirstLabelBase.height} you can switch to + The information in \autoref{sec:\ThisCommonFirstLabelBase.height} applies + equally to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.height}, you can skip ahead to \autoref{sec:\ThisCommonLabelBase.height.next}, \autopageref{sec:\ThisCommonLabelBase.height.next}.% } \begin{Declaration} - \Length{footheight}% + \Length{footheight} \Length{headheight} + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \OptionVName{autoenlargeheadfoot}{simple switch}% + }{}% \end{Declaration} -The package \Package{scrlayer} introduces \Length{footheight} as a new length -similar to \Length{headheight} of the \LaTeX{} kernel. Additionally -\Package{scrlayer-scrpage} interprets \Length{footskip} to be the distance -from the last possible base line of the text area to the first normal base -line of the footer. Package \Package{typearea}\IndexPackage{typearea} -interprets \Package{footheight} in the same way. So \Package{typearea}'s foot -height options may also be used to setup the values for packages -\Package{scrlayer} and \Package{scrlayer-scrpage}. See option -\DescRef{typearea.option.footheight} and \DescRef{typearea.option.footlines} -in \autoref{sec:typearea.typearea}, -\DescPageRef{typearea.option.footheight}) and option -\DescRef{typearea.option.footinclude} at +The \Package{scrlayer} package introduces a new length, \Length{footheight}, +analogous to \Length{headheight}% +\IfThisCommonLabelBase{scrlayer-scrpage}{}{of the \LaTeX{} kernel}. +Additionally, +\Package{scrlayer\IfThisCommonLabelBase{scrlayer-scrpage}{-scrpage}{}} +interprets \Length{footskip} to be the distance from the last baseline of the +text area to the first normal baseline of the footer. The +\hyperref[cha:typearea]{\Package{typearea}}\IndexPackage{typearea}% +\important{\hyperref[cha:typearea]{\Package{typearea}}} package interprets +\Length{footheight} in the same way, so \Package{typearea}'s options for the +footer height can also be used to set the values for the \Package{scrlayer} +package. See the \DescRef{typearea.option.footheight} and +\DescRef{typearea.option.footlines} options in +\autoref{sec:typearea.typearea}, \DescPageRef{typearea.option.footheight}) +and option \DescRef{typearea.option.footinclude} on \DescPageRef{typearea.option.footinclude} of the same section. -If you do not use package \Package{typearea}, you should setup the head and -foot height using the lengths directly where necessary. At least for the head -package \Package{geometry} provides similar settings. If you setup a head or -foot height that is too small for the effective content, -\Package{scrlayer-scrpage} will try to adjust the corresponding lengths -properly. Furthermore, it will warn you and give you additional information -about the changes and proper settings you may use yourself. The automatic -changes will become valid immediately after the need for them has been -detected. They will never be removed automatically, however, even if content -with a lower height requirement should be detected at a later point in time.% +If you do not use the \hyperref[cha:typearea]{\Package{typearea}}% +\important{\hyperref[cha:typearea]{\Package{typearea}}} package, you should +adjust the header and footer heights using appropriate values for the lengths +where necessary. For the header, at least, the \Package{geometry} package, for +example, provides similar settings. +\IfThisCommonLabelBase{scrlayer-scrpage}{\par% + If you choose a header or footer height that is too small for the actual + content, \Package{scrlayer-scrpage} tries by default to adjust the lengths + appropriately. At the same time, it will issue a warning containing + suggestions for suitable settings. These automatic changes take effect + immediately after the need for them has been detected and are not + automatically reversed, for example, when the content of the header or + footer becomes smaller afterwards. + However,\ChangedAt{v3.25}{\Package{scrlayer-scrpage}}, this behaviour can be + changed by using the \Option{autoenlargeheadfoot} option. This option + recognizes the values for simple switches in \autoref{tab:truefalseswitch}, + \autopageref{tab:truefalseswitch}. The option is activated by default. If it + is deactivated, the header and footer are no longer enlarged + automatically. Only a warning with hints for suitable settings is issued.% +}{% + \IfThisCommonLabelBase{scrlayer}{\par% + If you choose a header or footer height that is too small for the actual + content, \Package{scrlayer} usually accepts this without issuing an error + message or a warning. The header then expands according to its height, + usually upwards, with the footer moved down accordingly. Information about + this change is not obtained automatically. However, packages like + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + \important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}}% + \IndexPackage{scrlayer-scrpage} that build upon \Package{scrlayer} may + contain their own tests which can lead to their own actions (see + \DescRef{scrlayer-scrpage.length.headheight} and + \DescRef{scrlayer-scrpage.length.footheight} on + \DescPageRef{scrlayer-scrpage.length.headheight}).% + }{}% +}% \EndIndexGroup % \EndIndexGroup diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-interleafpage.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-interleafpage.tex index 28169a0c58d..36f9fb4ae4d 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-interleafpage.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-interleafpage.tex @@ -46,11 +46,12 @@ % ====================================================================== \KOMAProvidesFile{common-interleafpage.tex}% - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (common paragraphs: Interleaf Pages)] -\translator{Markus Kohm\and Gernot Hassenpflug\and Krickette Murabayashi} +\translator{Markus Kohm\and Gernot Hassenpflug\and Krickette Murabayashi\and + Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2017-12-07 \section{Interleaf Pages} \seclabel{emptypage}% @@ -59,98 +60,117 @@ \BeginIndex{}{page>style}% \IfThisCommonFirstRun{}{% - What is described in \autoref{sec:\ThisCommonFirstLabelBase.emptypage} - applies, mutatis mutandis. So if you have alread read and understood - \autoref{sec:\ThisCommonFirstLabelBase.emptypage} you can switch to + The information in \autoref{sec:\ThisCommonFirstLabelBase.emptypage} applies + equally to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.emptypage}, you can skip ahead to \autoref{sec:\ThisCommonLabelBase.emptypage.next}, \autopageref{sec:\ThisCommonLabelBase.emptypage.next}.% } -Interleaf pages are pages that are intended to stay blank. Originally these -pages were really completely white. \LaTeX{}, on the other hand, by default -sets those pages with the current valid page style. So those pages may have a -head and a pagination. \KOMAScript{} provides several extensions to this. +Interleaf pages are pages that are inserted between parts of a document. +Traditionally, these pages are completely blank. \LaTeX{}, however, +sets them by default with the current page style. \KOMAScript{} provides +several extensions to this functionality. -Interleaf pages may be found in books mostly. Because chapters in books -commonly start on odd pages, sometimes a left page without contents has to be -added before. This is also the reason that interleaf pages only exist in -double-sided printing. The unused back sides of the one-sided printings are -not interleaf pages, really, although they may seem to be such pages. +Interleaf pages are mostly found in books. Because book chapters commonly +start on the right (recto) page of a two-page spread, an empty left (verso) +page must be inserted if the previous chapter ends on a recto page. For this +reason, interleaf pages really only exist for two-sided printing. +% +\iffalse % Umbruchkorrektur + The blank versos in one-sided printing are not true interleaf pages, + although they may appear as such in counting the printed sheets. +\fi% \IfThisCommonLabelBase{scrlttr2}{% - At letters interleaf pages are unusual. This may be benefited by the case, - that real two-sided letters are seldom, because binding of letters is not - done often. Nevertheless \Class{scrlttr2} supports interleaf pages in the - case of two-sided letters. Because the following described commands are - seldom used in letters no examples are shown. If you need examples, please - note them at \autoref{sec:maincls.emptypage} from - \autopageref{sec:maincls.emptypage} upward.% + Interleaf pages are unusual in letters. This is not least because two-sided + letters are rare, as letters are usually not bound. Nevertheless, + \KOMAScript{} also supports interleaf pages for two-sided letters. However, + since the commands described here are seldom used in letters, you will not + find any examples here. If necessary, please refer to the examples in + \autoref{sec:maincls.emptypage}, starting on + \autopageref{sec:maincls.emptypage}.% }{}% \begin{Declaration} \OptionVName{cleardoublepage}{page style} \OptionValue{cleardoublepage}{current} \end{Declaration}% -With this option, % -\IfThisCommonLabelBase{maincls}{% +With this option,\IfThisCommonLabelBase{maincls}{% \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% }{% \IfThisCommonLabelBase{scrlttr2}{% \ChangedAt{v3.00}{\Class{scrlttr2}}% }{}% -} % -you may define the page style of the interleaf pages created by the +} you can define the page style of the interleaf pages created by the commands \DescRef{\LabelBase.cmd.cleardoublepage}, \DescRef{\LabelBase.cmd.cleardoubleoddpage}, or -\DescRef{\LabelBase.cmd.cleardoubleevenpage} to break until the wanted -page. Every already defined \PName{page style} (see +\DescRef{\LabelBase.cmd.cleardoubleevenpage} to advance to the desired page. +You can use any previously defined \PName{page style} (see \autoref{sec:\ThisCommonLabelBase.pagestyle} from \autopageref{sec:\ThisCommonLabelBase.pagestyle} and -\autoref{cha:scrlayer-scrpage} from \autopageref{cha:scrlayer-scrpage}) may be -used. Besides this, \OptionValue{cleardoublepage}{current} is valid. This case -is the default until \KOMAScript~2.98c and results in interleaf page without -changing the page style. Since \KOMAScript~3.00% -\IfThisCommonLabelBase{maincls}{% +\autoref{cha:scrlayer-scrpage} from \autopageref{cha:scrlayer-scrpage}). +In addition, \OptionValue{cleardoublepage}{current} is also possible. +This case corresponds to the default prior to \KOMAScript~2.98c and creates an +interleaf page without changing the page style. Starting with +\KOMAScript~3.00\IfThisCommonLabelBase{maincls}{% \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% }{% \IfThisCommonLabelBase{scrlttr2}{% \ChangedAt{v3.00}{\Class{scrlttr2}}% }{}% -} % -the default follows the recommendation of most typographers and has been -changed to blank interleaf pages with page style \PageStyle{empty} unless you -switch compatibility to an earlier version (see option -\DescRef{\ThisCommonLabelBase.option.version}, +}, the default\textnote{default} follows the recommendation of most +typographers and creates interleaf pages with the +\IfThisCommonLabelBase{scrextend}{% + \DescRef{maincls.pagestyle.empty}}{% + \DescRef{\ThisCommonLabelBase.pagestyle.empty}}\IndexPagestyle{empty} +page style unless you switch compatibility to earlier \KOMAScript{} versions +(see option \DescRef{\ThisCommonLabelBase.option.version}% +\important{\OptionValueRef{\LabelBase}{version}{2.98c}}, \autoref{sec:\ThisCommonLabelBase.compatibilityOptions}, \DescPageRef{\ThisCommonLabelBase.option.version}). \IfThisCommonLabelBase{maincls}{\iftrue}{\csname iffalse\endcsname} \begin{Example} \phantomsection\xmpllabel{option.cleardoublepage}% - Assume you want interleaf pages almost empty but with pagination. This - means you want to use page style \PageStyle{plain}. You may use following - to achieve this: + Suppose you want interleaf pages that are empty except for the pagination% + \iffree{, so they are created with \IfThisCommonLabelBase{scrextend}{% + \DescRef{maincls.pagestyle.plain}}{% + \DescRef{\LabelBase.pagestyle.plain}}}{}. You can achieve this, + for example, with: \begin{lstcode} \KOMAoptions{cleardoublepage=plain} \end{lstcode} - More information about page style \PageStyle{plain} may be found at - \autoref{sec:maincls.pagestyle}, - \DescPageRef{maincls.pagestyle.plain}. + You can find more information about the + \IfThisCommonLabelBase{scrextend}{% + \DescRef{maincls.pagestyle.plain}}{\DescRef{\LabelBase.pagestyle.plain}} + page style in \IfThisCommonLabelBase{scrextend}{% + \autoref{sec:maincls.pagestyle}}{% + \autoref{sec:\LabelBase.pagestyle}}, + \IfThisCommonLabelBase{scrextend}{% + \DescPageRef{maincls.pagestyle.plain}}{% + \DescPageRef{\LabelBase.pagestyle.plain}}. \end{Example} \else - \IfThisCommonLabelBase{scrextend}{\iftrue}{\csname iffalse\endcsname} + \IfThisCommonLabelBase{scrextend}{% + You can find an example for setting the page style of interleaf pages in + \autoref{sec:\ThisCommonFirstLabelBase.emptypage}, + \PageRefxmpl{\ThisCommonFirstLabelBase.option.cleardoublepage}.% + \iffalse% Umbruchvariante ohne Beispiel + }{\csname iffalse\endcsname} \begin{Example} \phantomsection\xmpllabel{option.cleardoublepage}% - Assume you want interleaf pages almost empty but with pagination. This - means you want to use page style \PageStyle{plain}. You may use - following to achieve this: + Suppose you want interleaf pages that are empty except for the pagination, + so they are created with the \IfThisCommonLabelBase{scrextend}{% + \DescRef{maincls.pagestyle.plain}}{\DescRef{\LabelBase.pagestyle.plain}} + page style. You can achieve this with \begin{lstcode} \KOMAoptions{cleardoublepage=plain} \end{lstcode} - More information about page style \PageStyle{plain} may be found at - \autoref{sec:maincls.pagestyle}, - \DescPageRef{maincls.pagestyle.plain}. + You can find more information about the + \DescRef{maincls.pagestyle.plain} page style in + \autoref{sec:maincls.pagestyle}, \DescPageRef{maincls.pagestyle.plain}. \end{Example}% \fi% \fi% @@ -175,81 +195,103 @@ switch compatibility to an earlier version (see option \Macro{cleardoubleevenplainpage}% \Macro{cleardoubleevenstandardpage} \end{Declaration}% -The {\LaTeX} kernel contains the \Macro{clearpage} command, which takes -care that all not yet output floats are output, and then starts a new -page. There exists the instruction \Macro{cleardoublepage} which -works like \Macro{clearpage} but which, in the double-sided layouts -(see layout option \Option{twoside} in -\autoref{sec:typearea.options}, -\DescPageRef{typearea.option.twoside}) starts a new right-hand -page. An empty left page in the current page style is output if -necessary. +The\textnote{standard classes} {\LaTeX} kernel provides the \Macro{clearpage} +command, which ensures that all pending floats are output and then starts a +new page. There is also the \Macro{cleardoublepage} command, which works like +\Macro{clearpage} but which starts a new right-hand page in two-sided printing +(see the \Option{twoside} layout option in \autoref{sec:typearea.options}, +\DescPageRef{typearea.option.twoside}). An empty left-hand page in the current +page style is output if necessary. -With% -\IfThisCommonLabelBase{maincls}{% +With\IfThisCommonLabelBase{maincls}{% \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% }{% \IfThisCommonLabelBase{scrlttr2}{% \ChangedAt{v3.00}{\Class{scrlttr2}}% }{}% -} % -\Macro{cleardoubleoddstandardpage}, {\KOMAScript} works as described above. -The \Macro{cleardoubleoddplainpage} command changes the page style of the -empty left page to \PageStyle{plain}\IndexPagestyle{plain} in order to -suppress the \IfThisCommonLabelBase{scrlttr2}{page}{running} head. -Analogously, the page style \PageStyle{empty}\IndexPagestyle{empty} is applied -to the empty page with \Macro{cleardoubleoddemptypage}, suppressing the page -number as well as the \IfThisCommonLabelBase{scrlttr2}{page}{running} -head. The page is thus entirely empty. If another \PName{page style} is wanted -for the interleaf page is may be set with the argument of -\Macro{cleardoubleoddusingpagestyle}. Every already defined \PName{page style} -(see \autoref{cha:scrlayer-scrpage}) may be used. +} \Macro{cleardoubleoddstandardpage}, {\KOMAScript}\textnote{\KOMAScript} +works as exactly in the way just described for the standard classess. The +\Macro{cleardoubleoddplainpage}% +\important{\IfThisCommonLabelBase{scrextend}{% + \DescRef{maincls.pagestyle.plain}}{\DescRef{\LabelBase.pagestyle.plain}}} +command, on the other hand, additionally changes the page style of the empty +left page to \IfThisCommonLabelBase{scrextend}{% + \DescRef{maincls.pagestyle.plain}}{\DescRef{\LabelBase.pagestyle.plain}}% +\IndexPagestyle{plain} in order to suppress the +\IfThisCommonLabelBase{scrlttr2}{page header}{running title}. Likewise, the +\Macro{cleardoubleoddemptypage}\important{% + \IfThisCommonLabelBase{scrextend}{\DescRef{maincls.pagestyle.empty}}{% + \DescRef{\LabelBase.pagestyle.empty}}} command uses the +\IfThisCommonLabelBase{scrextend}{\DescRef{maincls.pagestyle.empty}}{% + \DescRef{\LabelBase.pagestyle.empty}}\IndexPagestyle{empty} page style to +suppress both \IfThisCommonLabelBase{scrlttr2}{page header and page footer}% +{running title and page number} on the empty left-hand side. The page is thus +completely empty. If you want to specify your own \PName{page style} for the +interleaf page, this should be given as an argument of +\Macro{cleardoubleoddusingpagestyle}. You can use any previously defined +\PName{page style} (see \autoref{cha:scrlayer-scrpage}). \IfThisCommonLabelBase{scrlttr2}{}{% - Sometimes chapters should not start on the right-hand page but the left-hand - page. This is in contradition to the classic typography; nevertheless, it - may be suitable, e.\,g., if the double-page spread of the chapter start is - of special contents. \KOMAScript{} therefor provides the commands - \Macro{cleardoubleevenstandardpage}, \Macro{cleardoubleevenplainpage}, - \Macro{cleardoubleevenemptypage}, and \Macro{cleardoubleevenpageusingstyle}, - which are equivalent to the odd-page commands.% + Sometimes\textnote{odd-side interleaf pages} you want chapters to start not + on the right-hand but on the left-hand page. Although this layout contradicts + classic typography, it can be appropriate if the double-page spread at the + beginning of the chapter very specific contents. For this reason, + \KOMAScript{} provides the \Macro{cleardoubleevenstandardpage} command, + which is equivalent to the \Macro{cleardoubleoddstandardpage} command + except that the next page is a left page. The same applies to the + \Macro{cleardoubleevenplainpage}, \Macro{cleardoubleevenemptypage}, and + \Macro{cleardoubleevenpageusingstyle} commands% + \IfThisCommonLabelBase{maincls}{% Umbruchoptimierungsalternative + , the last of which expects an argument}{}.% } -However, the approach used by the \KOMAScript{} commands -\Macro{cleardoublestandardpage}, \Macro{cleardoubleemptypage}, -\Macro{cleardoubleplainpage}, and \Macro{cleardoublepageusingstyle} is -dependent on the option -\Option{cleardoublepage}\important{\Option{cleardoublepage}} described above -and is similar to one of the corresponding commands above. The same is valid for -the standard command \Macro{cleardoublepage}, that may be either -\Macro{cleardoubleoddpage} or \Macro{cleardoubleevenpage}. - -\IfThisCommonLabelBase{scrlttr2}{% - In \Class{scrlttr2} the other commands are there only for completeness. More - information about them may be found at - \autoref{sec:maincls.emptypage}, - \DescPageRef{maincls.cmd.cleardoublepage} if needed.% -}{}% -\IfThisCommonLabelBase{scrlttr2}{\iffalse}{\csname iftrue\endcsname} -\begin{Example} +The \Macro{cleardoublestandardpage}, \Macro{cleardoubleemptypage}, and +\Macro{cleardoubleplainpage} commands, and the single-argument +\Macro{cleardoublepageusingstyle} command, as well as the standard +\Macro{cleardoublepage} command, % +\IfThisCommonLabelBase{maincls}{% + depend on the \DescRef{maincls.option.open}\IndexOption{open}% + \important{\DescRef{maincls.option.open}} option explained in + \autoref{sec:maincls.structure}, \DescPageRef{maincls.option.open} and, + depending on that setting, correspond to one of the commands explained in + the preceding paragraphs. }{% + correspond to the commands previously explained for the + \IfThisCommonLabelBase{scrlttr2}{\Class{scrlttr2} class}{% + \IfThisCommonLabelBase{scrextend}{\Package{scrextend} package}{% + \InternalCommonFileUsageError}% + }% + \IfThisCommonLabelBase{scrlttr2}{. % + The remaining commands are defined in \Class{scrlttr2} for completeness + only. You can find more information on them in + \autoref{sec:maincls.emptypage}, \DescPageRef{maincls.cmd.cleardoublepage} + if necessary% + }{% + \ to transition to the next odd page% + }.% +}% +\IfThisCommonLabelBaseOneOf{scrlttr2,scrextend}{\iffalse}{\csname + iftrue\endcsname} + \begin{Example} \phantomsection\xmpllabel{cmd.cleardoublepage}% - Assume you want to set next in your document a double-page spread - with a picture at the left-hand page and a chapter start at the - right-hand page. The picture should have the same size as the text - area without any head line or pagination. If the last chapter - ends with a left-hand page, an interleaf page has to be added, which - should be completely empty. - - First you will use + Suppose you want to insert a double-page spread into your document with a + picture on the left-hand page and a new chapter starting on the right-hand + page. If the previous chapter ends with a left-hand page, an interleaf + page has to be added, which should be completely empty. The picture should + be the same size as the text area without any header or footer. +\iffalse% Umbruchkorrekturtext + First of all, \begin{lstcode} \KOMAoptions{cleardoublepage=empty} \end{lstcode} - to make interleaf pages empty. You may use this setting at the document - preamble already. As an alternative you may set it as the optional - argument of \DescRef{\ThisCommonLabelBase.cmd.documentclass}. + ensures that interleaf pages use the + \IfThisCommonLabelBase{scrextend}{\DescRef{maincls.pagestyle.empty}}{% + \DescRef{\LabelBase.pagestyle.empty}} page style. You can put this + setting in the document preamble, or you can set it as an optional + argument of \DescRef{\ThisCommonLabelBase.cmd.documentclass}. +\fi - At the relevant place in your document, you'll write: + At the relevant place in your document, write: \begin{lstcode} \cleardoubleevenemptypage \thispagestyle{empty} @@ -257,24 +299,30 @@ the standard command \Macro{cleardoublepage}, that may be either height=\textheight,% keepaspectratio]% {picture} - \chapter{Chapter Headline} + \chapter{Chapter Heading} \end{lstcode} - The first of these lines switches to the next left page. If needed it also - adds a completely blank right-hand page. The second line makes sure that - the following left-hand page will be set using page style - \PageStyle{empty} too. From third down to sixth line, an external picture - of wanted size will be loaded without deformation. Package - \Package{graphicx}\IndexPackage{graphicx} will be needed for this - command. The last line starts a new chapter on the next page which will be - a right-hand one. + The first of these lines switches to the next left-hand page. If needed it + also adds a completely blank right-hand page. The second line makes sure + that the following left-hand page will also be set using the + \IfThisCommonLabelBase{scrextend}{\DescRef{maincls.pagestyle.empty}}{% + \DescRef{\LabelBase.pagestyle.empty}} page style. The third through + sixth lines load an image file named \File{picture} and scale it to the + desired size without distorting it. This command requires the + \Package{graphicx}\IndexPackage{graphicx} package (see + \cite{package:graphics}). The last line starts + a new chapter on the next page, which will be a right-hand one. \end{Example}% \fi% -The commands \Macro{cleardoubleoddpage} respective \Macro{cleardoubleevenpage} -leads to the next odd respectively even page. The page style of an interleaf -page will be set depending on option -\DescRef{\LabelBase.option.cleardoublepage}.% -% +In two-sided printing, \Macro{cleardoubleoddpage} always moves to the next +left-hand page and \Macro{cleardoubleevenpage} to the next right-hand +page. The style of the interleaf page to be inserted if necessary is defined +with the \DescRef{\LabelBase.option.cleardoublepage} option.% +\IfThisCommonLabelBase{scrextend}{\par% + For an example that uses \Macro{cleardoubleevenemptypage}, see + \autoref{sec:maincls.emptypage}, + \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.cleardoublepage}.% +}{}% \EndIndexGroup % \EndIndexGroup diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-lists.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-lists.tex index 961ae6c4ed2..79a0a697fda 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-lists.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-lists.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-lists.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % common-lists.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,11 +46,12 @@ % ====================================================================== \KOMAProvidesFile{common-lists.tex} - [$Date: 2017-01-30 20:46:35 +0100 (Mon, 30 Jan 2017) $ + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (common paragraphs)] -\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi} +\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi\and + Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-02-06 \section{Lists} \seclabel{lists}% @@ -58,91 +59,106 @@ \BeginIndex{}{lists}% \IfThisCommonFirstRun{}{% - All of what is described in \autoref{sec:\ThisCommonFirstLabelBase.lists} is - generally applicable. So if you have alread read and understood - \autoref{sec:\ThisCommonFirstLabelBase.lists} you can switch to + The information in \autoref{sec:\ThisCommonFirstLabelBase.lists} applies + equally to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.lists}, you can skip ahead to \autoref{sec:\ThisCommonLabelBase.lists.next}, \autopageref{sec:\ThisCommonLabelBase.lists.next}.% - \IfThisCommonLabelBase{scrextend}{ % - However, \Package{scrextend} does support only the environments + \IfThisCommonLabelBaseOneOf{scrextend,scrlttr2}{ % + \IfThisCommonLabelBase{scrlttr2}{% + The \Package{scrletter}\OnlyAt{\Package{scrletter}} package does not + define any list environments itself but leaves them to the class + used. If this is not a \KOMAScript{} class, it will load + \hyperref[cha:scrextend]{\Package{scrextend}}\IndexPackage{scrextend}% + \important{\hyperref[cha:scrextend]{\Package{scrextend}}}.% + }{} % + However, the \Package{scrextend} package only defines the \DescRef{\ThisCommonLabelBase.env.labeling}, - \DescRef{\ThisCommonLabelBase.env.addmargin} and - \DescRef{\ThisCommonLabelBase.env.addmargin*}. All the other list - environments may be supported and controlled by the used class.% + \DescRef{\ThisCommonLabelBase.env.addmargin}, and + \DescRef{\ThisCommonLabelBase.env.addmargin*} environments. All other list + environments are left to the responsibility of the class used.% }{}% } -Both {\LaTeX} and the standard classes offer different environments for -lists. Though slightly changed or extended all these list are of course -offered in {\KOMAScript} as well. In general, all lists\,---\,even of different -kind\,---\,can be nested up to four levels. From a typographical view, -anything more would make no sense, as more than three levels can no longer be -easily perceived. The recommended\textnote{Hint!} procedure in such a case is -to split the large list into several smaller ones. +\IfThisCommonLabelBase{scrextend}{}{% + Both {\LaTeX} and the standard classes\textnote{\KOMAScript{} vs. standard + classes} offer different environments for lists. Naturally, {\KOMAScript} + also offers all these environments, though slightly modified or extended in + some cases. In general, all lists\,---\,even those of different + kinds\,---\,can be nested up to four levels deep. From a typographical view, + anything more would make no sense, as lists of more than three levels cannot + easily be apprehended. In such cases, I recommend\textnote{Hint!} that you + split a large list into several smaller ones.% +} \IfThisCommonFirstRun{}{% - Because lists are standard elements of \LaTeX{} this section abandons on - examples. Nevertheless, you may find examples either in - \autoref{sec:\ThisCommonFirstLabelBase.lists} from - \autopageref{sec:\ThisCommonFirstLabelBase.lists} or in almost every - introduction to \LaTeX.% + Because lists are standard elements of \LaTeX{}, examples have been omitted + in this section. Nevertheless, you can find examples either in + \autoref{sec:\ThisCommonFirstLabelBase.lists}, + \autopageref{sec:\ThisCommonFirstLabelBase.lists} or in any \LaTeX{} + tutorial.% } \IfThisCommonLabelBase{scrextend}{\iffalse}{\csname iftrue\endcsname} \begin{Declaration} - \begin{Environment}{itemize}\labelsuffix[itemize] + \begin{Environment}{itemize} \begin{Body} \Macro{item} \dots \BodyDots \end{Body} \end{Environment} - \Macro{labelitemi}% - \Macro{labelitemii}% - \Macro{labelitemiii}% + \Macro{labelitemi} + \Macro{labelitemii} + \Macro{labelitemiii} \Macro{labelitemiv} \end{Declaration}% - The simplest form of a list is an \Environment{itemize} list. + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{}% + The simplest form of a list is the itemized list\textnote{itemized list}, + \Environment{itemize}. % \iffalse % Umbruckoptimierungstext - The users of a certain disliked word processing package often refer to - this form of a list as \emph{bulletpoints}. Presumably, these users - are unable to envisage that, depending on the level, a different - symbol from a large dot could be used to introduce each - point. % + The users of a certain disliked word processing package often refer to this + form of a list as \emph{bullet points}. Presumably, they cannot imagine + that, depending on the level, a symbol other than a large dot could be used + to introduce each point. % \fi% - Depending on the level, {\KOMAScript} uses the following marks: - ``{\labelitemi}'', ``{\labelitemii}'', ``{\labelitemiii}'' and + Depending on the level, \KOMAScript{} classes use the following marks: + ``{\labelitemi}'', ``{\labelitemii}'', ``{\labelitemiii}'', and ``{\labelitemiv}''. The definition of these symbols is specified in the macros \Macro{labelitemi}, \Macro{labelitemii}, - \Macro{labelitemiii} and \Macro{labelitemiv}, all of which can be - redefined using \Macro{renewcommand}. Every item is introduced with + \Macro{labelitemiii}, and \Macro{labelitemiv}, all of which you can + redefine using \Macro{renewcommand}. Every item is introduced with \Macro{item}.% \IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} \begin{Example} \phantomsection\xmpllabel{env.itemize}% - You have a simple list which is nested in several levels. You write + You have a simple list which is nested in several levels. You write, for example: \begin{lstcode} - \minisec{Vehicles} + \minisec{Vehicles in the game} \begin{itemize} \item aeroplanes \begin{itemize} \item biplane - \item jets \item transport planes \begin{itemize} - \item single-engined + \item single-engine \begin{itemize} - \item jet-driven - \item propeller-driven + \item jet propelled + \item propeller driven \end{itemize} - \item multi-engined + \item twin-engine + \begin{itemize} + \item jet propelled + \item propeller driven + \end{itemize} \end{itemize} \item helicopters \end{itemize} + \item motorcycles \item automobiles \begin{itemize} \item racing cars - \item private cars + \item passenger cars \item lorries \end{itemize} \item bicycles @@ -150,34 +166,35 @@ to split the large list into several smaller ones. \end{lstcode} As output you get: \begin{ShowOutput}[\baselineskip] - \minisec{Vehicles} + \minisec{Vehicles in the game} \begin{itemize} \item aeroplanes \begin{itemize} \item biplanes - \item jets \item transport planes \begin{itemize} - \item single-engined + \item single-engine \begin{itemize} - \item jet-driven + \item jet-propelled \item propeller-driven \end{itemize} - \item multi-engined + \item twin-engine + \begin{itemize} + \item jet propelled + \item propeller driven + \end{itemize} \end{itemize} \item helicopters \end{itemize} -% Falls fuer die Umbruchoptimierung erforderlich, kann die Liste -% beispielsweise so erweitert werden: -% \item motorcycles -% \begin{itemize} -% \item historically accurate -% \item futuristic, not real -% \end{itemize} + \item motorcycles + % \begin{itemize} + % \item historically accurate + % \item futuristic, not real + % \end{itemize} \item automobiles \begin{itemize} \item racing cars - \item private cars + \item passenger cars \item lorries \end{itemize} \item bicycles @@ -205,60 +222,59 @@ to split the large list into several smaller ones. \Macro{labelenumiii}% \Macro{labelenumiv} \end{Declaration}% - Another form of a list often used is a numbered list which is already - implemented by the {\LaTeX} kernel. Depending on the level, the - numbering\Index{numbering} uses the following characters: Arabic numbers, - small letters, small roman numerals, and capital letters. The kind of - numbering is defined with the macros \Macro{theenumi} down to - \Macro{theenumiv}. The output format is determined by the macros - \Macro{labelenumi} to \Macro{labelenumiv}. While the small letter of the - second level is followed by a round parenthesis, the values of all other - levels are followed by a dot. Every item is introduced with \Macro{item}.% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{}The numbered + list\textnote{numbered list} is also very common and already provided by the + {\LaTeX} kernel. The numbering\Index{numbering} differs according to the + level, with Arabic numbers, small letters, small Roman numerals, and capital + letters, respectively. The style of numbering is defined with the macros + \Macro{theenumi} down to \Macro{theenumiv}. The output format is determined + by the macros \Macro{labelenumi} to \Macro{labelenumiv}. While the small + letter of the second level is followed by a right parenthesis, the values of + all other levels are followed by a dot. Every item is introduced with + \Macro{item}.% \IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} \begin{Example} \phantomsection\xmpllabel{env.enumerate}% - Replacing every occurrence of an - \DescRef{\ThisCommonLabelBase.env.itemize} environment with an - \Environment{enumerate} environment in the example above we - get the following result: + Let's shorten the previous example, using an + \DescRef{\ThisCommonLabelBase.env.itemize} environment instead of the + \Environment{enumerate} environment: \begin{ShowOutput}[\baselineskip] - \minisec{Vehicles} + \minisec{Vehicles in the game} \begin{enumerate} \item aeroplanes \begin{enumerate} \item biplanes - \item jets \item transport planes \begin{enumerate} - \item single-engined + \item single-engine \begin{enumerate} - \item jet-driven\label{xmp:maincls.jets} + \item jet-propelled\label{xmp:maincls.jets} \item propeller-driven \end{enumerate} - \item multi-engined + \item twin-engine \end{enumerate} - \item helicopters + % \item helicopters \end{enumerate} - % Wie oben: - % \item motorcycles - % \begin{enumerate} - % \item historically accurate - % \item futuristic, not real - % \end{enumerate} - \item automobiles + \item motorcycles \begin{enumerate} - \item racing cars - \item private cars - \item lorries + \item historically accurate + \item futuristic, not real \end{enumerate} - \item bicycles + %\item automobiles + % \begin{enumerate} + % \item racing cars + % \item private cars + % \item lorries + % \end{enumerate} + %\item bicycles \end{enumerate} \end{ShowOutput} - Using \Macro{label} within a list you can set labels which are - referenced with \Macro{ref}. In the example above, a label was set - after the jet-driven, single-engined transport planes with - \Macro{label}\PParameter{xmp:jets}. The \Macro{ref} value is then - \ref{xmp:maincls.jets}. + Within the list, you can set labels in the normal way with + \Macro{label} and then reference then with \Macro{ref}. + In the example above, a label was set after the jet-propelled, + single-engine transport planes with + ``\Macro{label}\PParameter{xmp:jets}''. The \Macro{ref} value is then + ``\ref{xmp:maincls.jets}''. \end{Example} \fi% % @@ -273,44 +289,44 @@ to split the large list into several smaller ones. \end{Body} \end{Environment} \end{Declaration}% - A further list form is the description list. Its main use is the description - of several items. The item itself is an optional parameter in - \Macro{item}. % + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{}Another list + form is the description list\textnote{description list}. It primarily serves + to describe individual items or keywords. The item itself is specified as an + optional parameter in \Macro{item}. % \BeginIndex{FontElement}{descriptionlabel}% \LabelFontElement{descriptionlabel}% The font\Index{font>style}\ChangedAt{v2.8p}{% \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - which is responsible for emphasizing the item can be changed with the - commands \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and - \DescRef{\ThisCommonLabelBase.cmd.addtokomafont} (see + \ used to format the keyword can be changed with the + \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and + \DescRef{\ThisCommonLabelBase.cmd.addtokomafont} commands (see \autoref{sec:\ThisCommonLabelBase.textmarkup}, - \DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}) for the element - \FontElement{descriptionlabel} (see - \autoref{tab:\ThisCommonLabelBase.fontelements}, - \autopageref{tab:\ThisCommonLabelBase.fontelements}). Default setting is + \DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}) for the + \FontElement{descriptionlabel}\important{\FontElement{descriptionlabel}} + element (see \autoref{tab:\ThisCommonLabelBase.fontelements}, + \autopageref{tab:\ThisCommonLabelBase.fontelements}). The default is \Macro{sffamily}\linebreak[1]\Macro{bfseries}.% \IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} \begin{Example} \phantomsection\xmpllabel{env.description}% - Instead of items in sans serif and bold, you want them printed in the - standard font in bold. Using + You want the keywords to be printed bold and in the normal font instead + of bold and sans serif. Using \begin{lstcode} \setkomafont{descriptionlabel}{\normalfont\bfseries} \end{lstcode} you redefine the font accordingly. An example for a description list is the output of the page styles - listed in \autoref{sec:maincls.pagestyle}. The heavily - abbreviated source could be: + listed in \autoref{sec:maincls.pagestyle}. The (abbreviated) source is: \begin{lstcode} \begin{description} - \item[empty] is the page style without any header or footer. + \item[empty] is the page style without any header or footer. \item[plain] is the page style without headings. \item[headings] is the page style with running headings. \item[myheadings] is the page style for manual headings. \end{description} \end{lstcode} - This abbreviated version gives: + This gives: \begin{ShowOutput} \begin{description} \item[empty] is the page style without any header or footer. @@ -326,8 +342,8 @@ to split the large list into several smaller ones. \fi \begin{Declaration} - \begin{Environment}{labeling} - \OParameter{delimiter}\Parameter{widest pattern} + \begin{Environment}{labeling}\OParameter{delimiter} + \Parameter{widest pattern} \labelsuffix[labeling] \begin{Body} \Macro{item}\OParameter{keyword}\dots @@ -335,17 +351,21 @@ to split the large list into several smaller ones. \end{Body} \end{Environment} \end{Declaration}% -An additional form of a description list is only available in the -{\KOMAScript} classes% -\IfThisCommonLabelBase{scrextend}{ and the package \Package{scrextend}}{}: the -\Environment{labeling} environment. Unlike the % +Another form of description list\textnote{alternative description list} is +only available in the {\KOMAScript} classes% +\IfThisCommonLabelBase{scrextend}{ and \Package{scrextend} }{% + \IfThisCommonLabelBase{scrlttr2}{ and + \hyperref[cha:scrextend]{\Package{scrextend}}}{}% +}% +: the \Environment{labeling} environment. Unlike \IfThisCommonLabelBase{scrextend}{% \DescRef{\ThisCommonFirstLabelBase.env.description}% }{% - \DescRef{\ThisCommonLabelBase.env.description}% -} environment, you can provide a -pattern whose length determines the indentation of all items. Furthermore, you -can put an optional \PName{delimiter} between the item and its description. + the \DescRef{\ThisCommonLabelBase.env.description} described above% +}, you can specify a pattern for \Environment{labeling} whose length +determines the indentation of all items. Furthermore, you can put an optional +\PName{delimiter} between the item and its description. % +\BeginIndexGroup \BeginIndex{FontElement}{labelinglabel}\LabelFontElement{labelinglabel}% \BeginIndex{FontElement}{labelingseparator}% \LabelFontElement{labelingseparator}% @@ -361,10 +381,9 @@ The font\Index{font>style}% \ChangedAt{v3.02}{\Package{scrextend}}% }{\InternalCommonFileUsageError}% }% -}% -which is responsible for emphasizing the item and the separator can be changed -with the commands \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and -\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} (see +} used to format the item and the separator can be changed with the +\DescRef{\ThisCommonLabelBase.cmd.setkomafont} and +\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} commands (see \autoref{sec:\ThisCommonLabelBase.textmarkup}, \DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}) for the element \FontElement{labelinglabel} and \FontElement{labelingseparator} (see @@ -374,18 +393,18 @@ with the commands \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and \begin{Example} \phantomsection\xmpllabel{env.labeling}% \IfThisCommonLabelBase{scrextend}{% - A small example of a list like this may be written:% + A small example of a list like this can be written as follows:% }{% Slightly changing the example from the \DescRef{\ThisCommonLabelBase.env.description} environment, we could - write:% + write the following:% }% \begin{lstcode} \setkomafont{labelinglabel}{\ttfamily} \setkomafont{labelingseparator}{\normalfont} \begin{labeling}[~--]{myheadings} \item[empty] - Page style without header and footer + Page style without header or footer \item[plain] Page style for chapter beginnings without headings \item[headings] @@ -394,13 +413,13 @@ with the commands \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and Page style for manual headings \end{labeling} \end{lstcode} - As the result we get: + The result is this: \begin{ShowOutput} \setkomafont{labelinglabel}{\ttfamily} \setkomafont{labelingseparator}{\normalfont} \begin{labeling}[~--]{myheadings} \item[empty] - Page style without header and footer + Page style without header or footer \item[plain] Page style for chapter beginnings without headings \item[headings] @@ -409,15 +428,16 @@ with the commands \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and Page style for manual headings \end{labeling} \end{ShowOutput} - As can be seen in this example, a font changing command may be set - in the usual way. But if you do not want the font of the separator to - be changed in the same way as the font of the label, you have to set - the font of the separator as well. + As this example shows, you can set a font-changing command in the usual + way. But if you do not want the font of the separator to be changed in the + same way as the font of the label, you have to set the font of the + separator as well. \end{Example} \fi% -Originally, this environment was implemented for things like ``Precondition, -Assertion, Proof'', or ``Given, Required, Solution'' that are often used in -lecture hand-outs. By now this environment has found many different +\EndIndexGroup +Originally, this environment was implemented for things like ``Premise, +Evidence, Proof'', or ``Given, Find, Solution'' that are often used in +lecture handouts. These days, however, the environment has very different applications. For example, the environment for examples in this guide was defined with the \Environment{labeling} environment.% % @@ -428,25 +448,26 @@ defined with the \Environment{labeling} environment.% \begin{Declaration} \begin{Environment}{verse}\end{Environment} \end{Declaration}% - Usually the \Environment{verse} environment is not perceived as a list - environment because you do not work with \Macro{item} commands. Instead, - fixed line breaks are used within the \Environment{flushleft} - environment. Yet internally in both the standard classes as well as - {\KOMAScript} it is indeed a list environment. + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{} The + \Environment{verse} environment\textnote{verse} is not normally perceived + as a list environment because you do not work with \Macro{item} commands. + Instead, fixed line breaks are used within the \Environment{flushleft} + environment. Internally, however, both the standard classes as well as + {\KOMAScript} implement it as a list environment. In general, the \Environment{verse} environment is used for - poems\Index{poems}. Lines are indented both left and right. Individual - lines of verse are ended by a fixed line break \verb|\\|. Verses are set as + poetry\Index{poetry}. Lines are indented both left and right. Individual + lines of verse are ended by a fixed line break: \verb|\\|. Verses are set as paragraphs, separated by an empty line. Often also \Macro{medskip}\IndexCmd{medskip} or \Macro{bigskip}\IndexCmd{bigskip} is - used instead. To avoid a page break at the end of a line of verse you could, + used instead. To avoid a page break at the end of a line of verse you can, as usual, insert \verb|\\*| instead of \verb|\\|. \IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} \begin{Example} \phantomsection\xmpllabel{env.verse}% -\iffalse - As an example, the first lines of ``Little Red Riding Hood and the - Wolf'' by Roald Dahl: + \iffalse + As an example, the first lines of ``Little Red Riding Hood and the + Wolf'' by Roald Dahl: \begin{lstcode} \begin{verse} As soon as Wolf began to feel\\* @@ -457,24 +478,24 @@ defined with the \Environment{labeling} environment.% And Wolfie said, `May I come in?' \end{verse} \end{lstcode} - The result is as follows: - \begin{ShowOutput} - \begin{verse} - As soon as Wolf began to feel\\* - That he would like a decent meal,\\* - He went and knocked on Grandma's door.\\* - When Grandma opened it, she saw\\* - The sharp white teeth, the horrid grin,\\* - And Wolfie said, `May I come in?' - \end{verse} - \end{ShowOutput} -\else - As an example, the sonnet of Emma Lazarus from the pedestal of Liberty - Enlightening the World\footnote{The lines from Roald Dahl's poem - ``Little Red Riding Hood and the Wolf'', that has been used in former - releases, has been replaced, because in these times several - politicians all over the world really seem to need ``The New - Colossus'' as urgent reminder.}: + The result is as follows: + \begin{ShowOutput} + \begin{verse} + As soon as Wolf began to feel\\* + That he would like a decent meal,\\* + He went and knocked on Grandma's door.\\* + When Grandma opened it, she saw\\* + The sharp white teeth, the horrid grin,\\* + And Wolfie said, `May I come in?' + \end{verse} + \end{ShowOutput} + \else + As an example, Emma Lazarus's sonnet from the pedestal of Liberty + Enlightening the World\footnote{The lines from Roald Dahl's poem + ``Little Red Riding Hood and the Wolf'', which was used in former + releases, has been replaced, because in these times certain + politicians around the world really seem to need ``The New + Colossus'' as urgent reminder.}: \begin{lstcode} \begin{verse} Not like the brazen giant of Greek fame\\* @@ -493,81 +514,138 @@ defined with the \Environment{labeling} environment.% I lift my lamp beside the golden door.'' \end{verse} \end{lstcode} - The result is as follows: - \begin{ShowOutput} - \begin{verse} - Not like the brazen giant of Greek fame\\* - With conquering limbs astride from land to land\\* - Here at our sea-washed, sunset gates shall stand\\* - A mighty woman with a torch, whose flame\\* - Is the imprisoned lightning, and her name\\* - Mother of Exiles. From her beacon-hand\\* - Glows world-wide welcome; her mild eyes command\\* - The air-bridged harbor that twin cities frame.\\* - ``Keep, ancient lands, your storied pomp!'' cries she\\* - With silent lips. ``Give me your tired, your poor,\\* - Your huddled masses yearning to breathe free,\\* - The wretched refuse of your teeming shore.\\* - Send these, the homeless, tempest-tossed to me:\\* - I lift my lamp beside the golden door.'' - \end{verse} - \end{ShowOutput} -\fi - However, if you have very long lines of verse, for instance: + The result is as follows: + \begin{ShowOutput} + \begin{verse} + Not like the brazen giant of Greek fame\\* + With conquering limbs astride from land to land\\* + Here at our sea-washed, sunset gates shall stand\\* + A mighty woman with a torch, whose flame\\* + Is the imprisoned lightning, and her name\\* + Mother of Exiles. From her beacon-hand\\* + Glows world-wide welcome; her mild eyes command\\* + The air-bridged harbor that twin cities frame.\\* + ``Keep, ancient lands, your storied pomp!'' cries she\\* + With silent lips. ``Give me your tired, your poor,\\* + Your huddled masses yearning to breathe free,\\* + The wretched refuse of your teeming shore.\\* + Send these, the homeless, tempest-tossed to me:\\* + I lift my lamp beside the golden door.'' + \end{verse} + \end{ShowOutput} + \fi + However, if you have very long lines of verse where a line + break occurs within a line of verse: \begin{lstcode} \begin{verse} Both the philosopher and the house-owner - have always something to repair.\\ + always have something to repair.\\* \bigskip Don't trust a man, my son, who tells you that he has never lied. \end{verse} \end{lstcode} - where a line break occurs within a line of verse: \begin{ShowOutput} \begin{verse} - Both the philosopher and the house-owner - have always something to repair.\\ - \bigskip - Don't trust a man, my son, who tells you - that he has never lied. + Both the philosopher and the house-owner always have something to + repair.\\ + \bigskip Don't trust a man, my son, who tells you that he has never + lied. \end{verse} \end{ShowOutput} - there \verb|\\*| can not prevent a page break occurring within a verse - at such a line break. To prevent such a page break, a + in this case \verb|\\*| can not prevent a page break occurring within a + verse at such a line break. To prevent such a page break, a \Macro{nopagebreak}\IndexCmd{nopagebreak} would have to be inserted somewhere in the first line: \begin{lstcode} \begin{verse} - Both the philosopher and the house-owner\nopagebreak - have always something to repair.\\ + Both the philosopher and the house-owner\nopagebreak{} + always have something to repair.\\ \bigskip - Don't trust a man, my son, who tells you\nopagebreak + Don't trust a man, my son, who tells you\nopagebreak{} that he has never lied. \end{verse} \end{lstcode} - - In the above example, \Macro{bigskip} was used to separate the lines of - verse. + \iftrue% Umbruchkorrekturtext + Here are two sayings that should always be considered when confronted + with seemingly strange questions about {\LaTeX} or its accompanying + explanations: +\begin{lstcode} + \begin{verse} + A little learning is a dangerous thing.\\* + Drink deep, or taste not the Pierian Spring;\\ + \bigskip + Our judgments, like our watches, none\\* + go just alike, yet each believes his own. + \end{verse} +\end{lstcode} + \begin{ShowOutput} + \iffree{}{\vskip-.8\baselineskip}% Umbruchkorrektur + \begin{verse} + A little learning is a dangerous thing.\\* + Drink deep, or taste not the Pierian Spring;\\ + \bigskip + Our judgments, like our watches, none\\* + go just alike, yet each believes his own. + \end{verse} + \end{ShowOutput} + \fi + Incidentally, \Macro{bigskip} was used in these examples to separate two + sayings. \end{Example} - \fi % \ifCommonmaincls + \fi % \EndIndexGroup - \begin{Declaration} - \begin{Environment}{quote}\end{Environment} - \begin{Environment}{quotation}\end{Environment} - \end{Declaration}% - These two environments are also list environments and can be found both in - the standard and the {\KOMAScript} classes. Both environments use justified - text which is indented both on the left and right side. Usually they are - used to separate long citations\Index{citations} from the main text. The - difference between these two lies in the manner in which paragraphs are - typeset. While \Environment{quote} paragraphs are highlighted by vertical - space, in \Environment{quotation} paragraphs the first line is - indented. This is also true for the first line of a \Environment{quotation} - environment. To prevent indentation you have to insert a \Macro{noindent} - command\IndexCmd{noindent} before the text. + \iftrue% Umbruchkorrekturvarianten + \begin{Declaration} + \begin{Environment}{quote}\end{Environment} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{}This is + internally also a list environment\textnote{block quote with paragraph + spacing} and can be found both in the standard classes and in + {\KOMAScript}. The content of the environment is set fully justified. + The environment is often used to format longer quotes\Index{quotes}. + Paragraphs within the environment are distinguished with vertical space.% + \EndIndexGroup + + \begin{Declaration} + \begin{Environment}{quotation}\end{Environment} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{}This + environment\textnote{block quote with paragraph indent} is comparable to + \DescRef{\ThisCommonLabelBase.env.quote}. While + \DescRef{\ThisCommonLabelBase.env.quote} paragraphs are indicated by + vertical spacing, \Environment{quotation} indents the first line of each + paragraph horizontally. This also applies to the first paragraph of a + \Environment{quotation} environment. If you want to prevent the + indentation there, you must precede it with the + \Macro{noindent}\IndexCmd{noindent} command.% + \else + \begin{Declaration} + \begin{Environment}{quote}\end{Environment} + \begin{Environment}{quotation}\end{Environment} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{} These two + environments\textnote{block quotes} are also set internally as list + environments and can be found in both the standard and the {\KOMAScript} + classes. Both environments use justified text which is indented on both + the left and the right side. Often they are used to separate longer + quotations\Index{quotations} from the main text. The difference between + the two lies in in the manner in which paragraphs are typeset. While + \Environment{quote} paragraphs are distinguished by vertical space, in + \Environment{quotation} paragraphs, the first line is indented. This also + applies to the first line of a \Environment{quotation} + environment% Umbruchkorrektur + \IfThisCommonLabelBase{maincls}{% + , unless it is preceded by \Macro{noindent}\IndexCmd{noindent}.% + }{% + \IfThisCommonLabelBase{scrlttr2}{% + . If you want to prevent the indentation there, you must precede it + with the \Macro{noindent} command\IndexCmd{noindent}.% + }{\InternalCommonFileUsageError}% + }% + \fi % Umbruchkorrekturvarianten \IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} \begin{Example} \phantomsection\xmpllabel{env.quote}% @@ -596,13 +674,13 @@ defined with the \Environment{labeling} environment.% \begin{quotation} The old year was turning brown; the West Wind was calling; - + Tom caught the beechen leaf in the forest falling. ``I've caught the happy day blown me by the breezes! Why wait till morrow-year? I'll take it when me pleases. This I'll mend my boat and journey as it chances west down the withy-stream, following my fancies!'' - + Little Bird sat on twig. ``Whillo, Tom! I heed you. I've a guess, I've a guess where your fancies lead you. Shall I go, shall I go, bring him word to meet you?'' @@ -622,7 +700,7 @@ defined with the \Environment{labeling} environment.% Why wait till morrow-year? I'll take it when me pleases. This I'll mend my boat and journey as it chances west down the withy-stream, following my fancies!'' - + Little Bird sat on twig. ``Whillo, Tom! I heed you. I've a guess, I've a guess where your fancies lead you. Shall I go, shall I go, bring him word to meet you?'' @@ -643,38 +721,38 @@ defined with the \Environment{labeling} environment.% \OParameter{inner indentation}\Parameter{indentation} \end{Environment} \end{Declaration} -Similar to % -\IfThisCommonLabelBase{scrextend}{% +Like \IfThisCommonLabelBase{scrextend}{% \DescRef{\ThisCommonFirstLabelBase.env.quote} and - \DescRef{\ThisCommonFirstLabelBase.env.quotation} which are available at the - standard classes and also the \KOMAScript{} classes% -}{% + \DescRef{\ThisCommonFirstLabelBase.env.quotation}, which are available in + the standard and the \KOMAScript{} classes}{% \DescRef{\ThisCommonLabelBase.env.quote} and \DescRef{\ThisCommonLabelBase.env.quotation}% -} % -the \Environment{addmargin} environment changes the margin\Index{margin}. In -contrast to the first two environments, with \Environment{addmargin} the user -can set the width of the indentation. Besides this, this environment does not -change the indentation of the first line nor the vertical spacing between -paragraphs. +}, the \Environment{addmargin} environment changes the margin\Index{margin}. +However, unlike the first two environments, \Environment{addmargin} lets the +user change the width of the indentation. Apart from this change, this +environment does not change the indentation of the first line nor the vertical +spacing between paragraphs. -If only the obligatory argument \PName{indentation} is given, both the -left and right margin are expanded by this value. If the optional -argument \PName{left indentation} is given as well, then at the left -margin the value \PName{left indentation} is used instead of -\PName{indentation}. +If only the obligatory argument \PName{indentation} is given, both the left +and right margin are expanded by this value. If the optional argument +\PName{left indentation} is given as well, then the value \PName{left + indentation} is used for the left margin instead of \PName{indentation}. -The starred \Environment{addmargin*} only differs from the normal -version in a two-sided layout. Furthermore, the difference only occurs -if the optional argument \PName{inner indentation} is used. In this -case this value \PName{inner indentation} is added to the normal inner -indentation. For right-hand pages this is the left margin, for -left-hand pages the right margin. Then the value of -\PName{indentation} determines the width of the opposite margin. +The starred variant \Environment{addmargin*}% +\important{\Environment{addmargin*}} differs from the normal version only in +the two-sided mode. Furthermore, the difference only occurs if the optional +argument \PName{inner indentation} is used. In this case, the value of +\PName{inner indentation} is added to the normal inner indentation. For +right-hand pages this is the left margin; for left-hand pages, the right +margin. Then the value of \PName{indentation} determines the width of the +opposite margin. -Both versions of this environment take also negative values for all -parameters. This has the effect of expanding the environment into the -margin. +Both versions of this environment allow negative values for all parameters. +\IfThisCommonLabelBase{scrextend}{% + The environment then protrudes into the margin accordingly.% +}{% + This can be done so that the environment protrudes into the margin.% +}% \IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} \begin{Example} \phantomsection\xmpllabel{env.addmargin}% @@ -689,7 +767,7 @@ margin. \end{addmargin*}% } \end{lstcode} - If you now put your source code in such an environment it will show + If you now put your source code in such an environment, it will show up as: \begin{ShowOutput} \newenvironment{SourceCodeFrame}{% @@ -701,7 +779,7 @@ margin. \end{minipage}% \end{addmargin*}% } - You define yourself the following environment: + You define the following environment: \begin{SourceCodeFrame} \begin{lstcode} \newenvironment{\SourceCodeFrame}{% @@ -715,38 +793,38 @@ margin. } \end{lstcode} \end{SourceCodeFrame} - This may be feasible or not. In any case it shows the usage of this + This may be feasible or not. In any case, it shows the usage of this environment. \end{ShowOutput} The optional argument of the \Environment{addmargin*} environment makes sure that the inner margin is extended by 1\Unit{em}. In turn the outer margin is decreased by 1\Unit{em}. The result is a shift - by 1\Unit{em} to the outside. Instead of \PValue{1em} you can of + by 1\Unit{em} to the outside. Instead of \PValue{1em}, you can of course use a length, for example, \PValue{2\Macro{parindent}}. \end{Example} \fi% -Whether a page is going to be on the left or right side of the book can not be -determined for certain in the first {\LaTeX} run. For details please refer to +Whether a page is going to be on the left or right side of the book cannot be +determined reliably on the first {\LaTeX} run. For details please refer to the explanation of the commands \DescRef{\ThisCommonLabelBase.cmd.ifthispageodd} (\autoref{sec:\ThisCommonLabelBase.oddOrEven}, \DescPageRef{\ThisCommonLabelBase.cmd.ifthispageodd}) and \iffree{\Macro{ifthispagewasodd}}{% - \DescRef{\ThisCommonLabelBase.cmd.ifthispagewasodd}} -(\autoref{sec:maincls-experts.addInfos}, -\DescPageRef{maincls-experts.cmd.ifthispageodd}). - + \DescRef{maincls-experts.cmd.ifthispagewasodd}} +(\autoref{sec:maincls-experts.addInfos}\iffree{}{, +\DescPageRef{maincls-experts.cmd.ifthispageodd}}). +\IfThisCommonLabelBase{scrlttr2}{}{% \begin{Explain} - There may be several questions about coexistence of lists and - paragraphs. Because of this additional information may be found at the - description of option \Option{parskip} in + The interplay of environments such as lists and paragraphs gives rise to + frequent questions. Therefore, you can find further explanation in the + description of the \Option{parskip} option in + \autoref{sec:maincls-experts.addInfos}\iffree{}{, + \DescPageRef{maincls-experts.option.parskip}. Also in the expert section, in \autoref{sec:maincls-experts.addInfos}, - \DescPageRef{maincls-experts.option.parskip}. Also at the expert part, - in \autoref{sec:maincls-experts.addInfos}, - \DescPageRef{maincls-experts.env.addmargin*}, you may find additional - information about page breaks inside of \Environment{addmargin*}.% -\end{Explain}% + \DescPageRef{maincls-experts.env.addmargin*}, you can find additional + information about page breaks inside \Environment{addmargin*}}.% +\end{Explain}}% % \EndIndexGroup % diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-marginpar.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-marginpar.tex index ff57abce762..4ef54b7e68e 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-marginpar.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-marginpar.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-marginpar.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % common-marginpar.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,33 +46,33 @@ % ====================================================================== \KOMAProvidesFile{common-marginpar.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (common paragraphs)] -\translator{Gernot Hassenpflug\and Markus Kohm} +\translator{Gernot Hassenpflug\and Markus Kohm\and Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-01-29 -\section{Margin Notes} +\section{Marginal Notes} \seclabel{marginNotes}% \BeginIndexGroup -\BeginIndex{}{margin>notes}% +\BeginIndex{}{marginal notes}% \IfThisCommonFirstRun{}{% - All of what is described in - \autoref{sec:\ThisCommonFirstLabelBase.marginNotes} is generally - applicable. So if you have alread read and understood - \autoref{sec:\ThisCommonFirstLabelBase.marginNotes} you can switch to + The information in \autoref{sec:\ThisCommonFirstLabelBase.marginNotes} + applies equally to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.marginNotes}, you can skip ahead to \autoref{sec:\ThisCommonLabelBase.marginNotes.next}, \autopageref{sec:\ThisCommonLabelBase.marginNotes.next}.% } -Aside from the text area, that normally fills the typing area, usually a -marginalia column may be found. Margin notes will be printed at this area. +In addition to the text area, which normally fills the type area, documents +often contain a column for marginalia. You can set marginal notes in this +area. \IfThisCommonLabelBase{scrlttr2}{% - Nevertheless, margin notes are unusual at letters and should be used - seldomly.% + In letters, however, marginal notes are unusual and should be used + sparingly.% }{% - At lot of them may be found in this \iffree{manual}{book}.% + This \iffree{guide}{book} makes frequent use of them.% }% @@ -80,31 +80,30 @@ marginalia column may be found. Margin notes will be printed at this area. \Macro{marginpar}\OParameter{margin note left}\Parameter{margin note}% \Macro{marginline}\Parameter{margin note} \end{Declaration}% -Usually margin notes\Index[indexmain]{margin>notes} in {\LaTeX} are -inserted with the command \Macro{marginpar}. They are placed in the -outer margin. In documents with one-sided layout the right border is -used. Though \Macro{marginpar} can take an optional different margin -note argument in case the output is in the left margin, margin notes -are always set in justified layout. However, experience has shown -that many users prefer left- or right-aligned margin notes instead. -To facilitate this, {\KOMAScript} offers the command -\Macro{marginline}. +Marginal notes\Index[indexmain]{marginal notes} in {\LaTeX} are usually +inserted with the \Macro{marginpar} command. They are placed in the outer +margin. One-sided documents use the right border. Although you can specify a +different marginal note for \Macro{marginpar} in case it winds up in the left +margin, marginal notes are always fully justified. However, experience has +shown that many users prefer left- or right-justified marginal notes +instead. For this purpose, {\KOMAScript} offers the \Macro{marginline} +command. \IfThisCommonFirstRun{% \iftrue% }{% - An example for this may be found in + For a detailed example, see \autoref{sec:\ThisCommonFirstLabelBase.marginNotes} at \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.marginline}.% \csname iffalse\endcsname% }% \begin{Example} \phantomsection\xmpllabel{cmd.marginline}% - In this \iffree{document}{book}, sometimes, the class name - \Class{scrartcl} can be found in the margin. This can be produced with:% - \iffalse% Umbruchkorrekturtext - \footnote{In fact, instead of \Macro{texttt}, a semantic highlighting - was used. To avoid confusion this was replaced in the example.}% + In some parts of this \iffree{guide}{book}, the class name + \Class{scrartcl} can be found in the margin. You can produced this with:% + \iftrue% Umbruchkorrekturtext + \footnote{Actually, instead of \Macro{texttt}, a semantic markup + was used. To avoid confusion, this has been replaced in the example.}% \fi \begin{lstcode} \marginline{\texttt{scrartcl}} @@ -116,15 +115,23 @@ To facilitate this, {\KOMAScript} offers the command \marginpar[\raggedleft\texttt{scrartcl}] {\raggedright\texttt{scrartcl}} \end{lstcode} - Thus \Macro{marginline} is really only an abbreviated writing of the + Thus \Macro{marginline} is really just a shorthand notation for the code above.% \end{Example}% \fi -Experts\textnote{Attention!} and advanced users may find information about -problems using \Macro{marginpar} at \autoref{sec:maincls-experts.addInfos}, -\DescPageRef{maincls-experts.cmd.marginpar}. These are valid for -\Macro{marginline} also.% +Advanced users\textnote{Attention!} will find notes about difficulties that +can arise using \Macro{marginpar} in \autoref{sec:maincls-experts.addInfos}% +\iffree{}{, on \DescPageRef{maincls-experts.cmd.marginpar}}. These remarks +also apply to \Macro{marginline}. In addition, +\autoref{cha:scrlayer-notecolumn} introduces a package that you can use to +create note columns with their own page breaks.% +\iftrue% Umbruchkorrektur + \ However, the + \hyperref[cha:scrlayer-notecolumn]{\Package{scrlayer-notecolumn}}% + \IndexPackage{scrlayer-notecolumn} package is more a proof of concept than a + finished package.% +\fi% % \EndIndexGroup % diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-oddorevenpage.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-oddorevenpage.tex index 1ec1edd6b97..04ff2b91ac0 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-oddorevenpage.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-oddorevenpage.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-oddorevenpage.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % common-oddorevenpage.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,51 +46,46 @@ % ====================================================================== \KOMAProvidesFile{common-oddorevenpage.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (common paragraph: Detection of Odd and Even Pages)] -\translator{Markus Kohm\and Krickette Murabayashi} +\translator{Markus Kohm\and Krickette Murabayashi\and Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-01-30 -\section{Detection of Odd and Even Pages} +\section{Detecting Odd and Even Pages} \seclabel{oddOrEven}% \BeginIndexGroup% \BeginIndex{}{page>odd}% \BeginIndex{}{page>even}% \IfThisCommonFirstRun{}{% - What is described in - \autoref{sec:maincls.oddOrEven} applies, mutatis mutandis. - So if you have alread read and understood - \autoref{sec:\ThisCommonFirstLabelBase.oddOrEven} you can - switch to \autopageref{sec:\ThisCommonLabelBase.oddOrEven.next}, + The information in \autoref{sec:maincls.oddOrEven} applies equally to this + chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.oddOrEven}, you can skip ahead to + \autopageref{sec:\ThisCommonLabelBase.oddOrEven.next}, \autopageref{sec:\ThisCommonLabelBase.oddOrEven.next}.% } -In double-sided documents we distinguish left and right pages. Left pages -always have an even page number, right pages always have an odd page -number. % For this they are mostly called even and odd pages so they - % are -Thus, they are most often referred to as even and odd pages -in this -\iffree{guide}{book}. % +In two-sided documents we distinguish left and right pages. Left pages always +have an even page number, and right pages always have an odd page number. % \IfThisCommonLabelBase{maincls}{% - This also means that the detection - of a left or right page is same as detection of even and odd page - numbers. + Identifying right and left pages is equivalent to identifying even- or + odd-numbered pages, and so we normally refer to them as even and odd pages + in this \iffree{guide}{book}. -% Umbruchkorrekturtext + % Umbruchkorrekturtext \iftrue% - There's no distinction in left and right pages in single-sided - documents. Nevertheless there are pages with even or odd page numbers.% + In one-sided documents, the distinction between left and right pages does + not exist. Nevertheless, there are still pages with even and odd page + numbers.% \fi% }{% \IfThisCommonLabelBase{scrlttr2}{% - Letters will be set single-side mostly. Nevertheless, printing letters - with single-side layout using both paper sides or exceptionally generating - real double-side letters it may be useful to know whether producing - currently an even or odd page.% + As a rule, letters will be set one-sided. However, if you need to print + letters using both sides of the paper or, in exceptional cases, are + generating real two-sided letters, it may be useful to know whether you + are currently on an even or odd page.% }{}% } @@ -98,34 +93,33 @@ in this \begin{Declaration} \Macro{ifthispageodd}\Parameter{true part}\Parameter{false part} \end{Declaration}% -If one wants to find out with {\KOMAScript} whether a text falls on an -even or odd page, one can use the \Macro {ifthispageodd} command. The -\PName{true part} argument is executed only if the command falls on an odd -page. Otherwise the \PName{false part} argument is executed. +If you want to determine whether text appears on an even or odd page, +\KOMAScript{} provides the \Macro {ifthispageodd} command. The \PName{true + part} argument is executed only if you are currently on an odd page. +Otherwise the \PName{false part} argument is executed. \begin{Example} - Assume that you simply want to show whether a text will be placed onto an + Suppose you simply want to show whether a text will be placed onto an even or odd page. You may achieve that using \begin{lstcode} This page has an \ifthispageodd{odd}{even} page number. \end{lstcode} - which will result in the output + This results in the output \begin{quote} This page has an \ifthispageodd{odd}{even} page number. \end{quote} \end{Example} -Because the \Macro{ifthispageodd} command uses a mechanism that is -very similar to a label and a reference to it, at least two {\LaTeX} -runs are required after every text modification. Only then the -decision is correct. In the first run a heuristic is used to make the -first choice. +Because the \Macro{ifthispageodd} command uses a mechanism that is very +similar to a label and a reference to it, at least two {\LaTeX} runs are +required after each change to the text. Only then will the decision be +correct. In the first run, a heuristic is used to make the initial choice. -At \autoref{sec:maincls-experts.addInfos}, -\DescPageRef{maincls-experts.cmd.ifthispageodd} experts may find more -information about the problems detecting left and right pages or even and odd -page number.% +\iffree{}{In \autoref{sec:maincls-experts.addInfos}, +\DescPageRef{maincls-experts.cmd.ifthispageodd}, advanced users can find more +information about the problems of detecting left and right pages, or even and +odd page numbers.}% % \EndIndexGroup % diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-options.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-options.tex index 5d97ff8d26a..241a6f2200f 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-options.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-options.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-options.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % common-options.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,57 +46,55 @@ % ====================================================================== \KOMAProvidesFile{common-options.tex} - [$Date: 2016-11-14 21:06:12 +0100 (Mo, 14. Nov 2016) $ + [$Date: 2017-12-07 23:10:55 -0800 (Thu, 07 Dec 2017) $ KOMA-Script guide (common paragraphs)] -\translator{Gernot Hassenpflug\and Krickette Murabayashi} +\translator{Gernot Hassenpflug\and Krickette Murabayashi\and Karl Hagen} -% Date of the translated German file: 2017-06-23 +% Date of the translated German file: 2017-12-07 -\section{Early or late Selection of Options} +\section{Early or Late Selection of Options} \seclabel{options} \BeginIndexGroup \BeginIndex{}{options}% -\IfThisCommonFirstRun{}{% - All of what is described in - \autoref{sec:\ThisCommonFirstLabelBase.options} is generally - applicable. So if you have alread read and understood - \autoref{sec:\ThisCommonFirstLabelBase.options} you can switch to +\IfThisCommonFirstRun{% + This section introduces a special feature of \KOMAScript{} which, in + addition to \IfThisCommonLabelBase{typearea}{\Package{typearea}}{% + \IfThisCommonLabelBase{maincls}{\Class{scrbook}, \Class{scrreprt}, and + \Class{scrartcl}}{% + \IfThisCommonLabelBase{scrlttr2}{the \Class{scrlttr2} class}{% + \IfThisCommonLabelBase{scrextend}{the classes and + \Package{scrextend}}{% + \IfThisCommonLabelBase{scrhack}{\Package{scrhack}}{% + \IfThisCommonLabelBase{scrjura}{\Package{scrjura}}{% + \IfThisCommonLabelBase{scrlayer}{\Package{scrlayer}}{% + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}}{% + \IfThisCommonLabelBase{scrlayer-notecolumn}{% + \Package{scrlayer-notecolumn}}{% + \InternalCommonFileUsageError}}}}}}}}}% + , is also relevant to other \KOMAScript{} packages and classes. % + \IfThisCommonLabelBase{scrlttr2}{So that each chapter may stand on its own, + this section appears in nearly identical form in several chapters, but if + you are studying all of \KOMAScript{}, you of course only need to read it + one time.% + }{This section appears in nearly identical form in several chapters, so you + can find all the information about a single package or class in the + relevant chapter. Users who are interested not just in a particular + package or class but in getting an overview of \KOMAScript{} as a whole + only need to read this section in one of the chapters and can + \IfThisCommonLabelBase{maincls}{skip the rest of the chapter.}{% + then skip it as they study the guide.}% + }% +}{% + The information in \autoref{sec:\ThisCommonFirstLabelBase.options} applies + equally to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.options}, you can skip ahead to \autoref{sec:\ThisCommonLabelBase.options.next}, \autopageref{sec:\ThisCommonLabelBase.options.next}.% } -In this section a peculiarity of {\KOMAScript} is presented, which, apart -from % -\IfThisCommonLabelBase{typearea}{the \Package{typearea} package, is also - relevant to other {\KOMAScript} packages and classes}{% - \IfThisCommonLabelBase{maincls}{the classes \Class{scrbook}, - \Class{scrreprt}, and \Class{scrartcl} is also relevant to other - {\KOMAScript} classes and packages}{% - \IfThisCommonLabelBase{scrlttr2}{the class \Class{scrlttr2} is also - relevant to other {\KOMAScript} classes and packages}{% - \IfThisCommonLabelBase{scrextend}{the classes and the - \Package{scrextend} package is also relevant to several other - {\KOMAScript} packages}{% - \IfThisCommonLabelBase{scrhack}{the \Package{scrhack} package, is also - relevant to other \KOMAScript{} packages and classes}{% - \IfThisCommonLabelBase{scrjura}{the \Package{scrjura} package, is - also relevant to other \KOMAScript{} packages and classes}{% - \IfThisCommonLabelBase{scrlayer}{the \Package{scrlayer} package, - is also relevant to other \KOMAScript{} packages and classes}{% - \IfThisCommonLabelBase{scrlayer-scrpage}{the - \Package{scrlayer-scrpage} package, is also relevant to other - \KOMAScript{} packages and classes}{% - \IfThisCommonLabelBase{scrlayer-notecolumn}{the - \Package{scrlayer-notecolumn} package, is also relevant to - other \KOMAScript{} packages and classes}{% - \InternalCommonFileUsageError}}}}}}}}}% -. Such that the user can find all information corresponding to a single -package or a single class in the relevant chapter, this section is found -almost identically in several chapters. Users who are not only interested in a -particular package or class, but wish to gain an overview of {\KOMAScript} as -a whole, may read the section in one chapter and may thereafter skip it -wherever coming across it in the document. + \begin{Declaration} \Macro{documentclass}\OParameter{option list}% @@ -104,49 +102,59 @@ wherever coming across it in the document. \Macro{usepackage}\OParameter{option list}% \Parameter{package list} \end{Declaration} -In \LaTeX{}, provision is made for the user to pass class options as a -comma-separated list of keywords as optional arguments to -\Macro{documentclass}. -Apart from being passed to the class, -these options are also passed on to all packages which can understand -the options. Provision is also made for the user to pass optional -arguments as a comma-separated list of keywords as optional arguments -to \Macro{usepackage}. {\KOMAScript} -expands\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}\and \Package{scrextend}\and \Package{typearea}} the -option mechanism for the {\KOMAScript} classes and various packages to -use further possibilities. Thus, most {\KOMAScript} options can also -take a value. An option may have not only the form \PName{Option}, but -may also have the form \PName{option}\texttt{=}\PName{value}. Apart -from this difference \Macro{documentclass} and \Macro{usepackage} -function the same in {\KOMAScript} as described in -\cite{latex:usrguide} or any introduction to \LaTeX, for example +\LaTeX{} allows users to pass class options\textnote{class options} as a +comma-separated list of keywords in the optional argument to +\Macro{documentclass}. In addition to being passed to the class, these options +are also passed on to all packages\textnote{global options} that can +understand them. Users can also pass a similar comma-separated list of +keywords in the optional argument of \Macro{usepackage}\textnote{packet + options}. \KOMAScript{} extends\ChangedAt{v3.00}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}\and \Package{scrextend}\and + \Package{typearea}} the option mechanism for +\IfThisCommonLabelBaseOneOf{scrextend,scrjura}{}{the \KOMAScript{} classes and +} some packages with further options. Thus most \KOMAScript{} options can also +take a value, so an option does not necessarily take the form \PName{option}, +but can also take the form \PName{option}\texttt{=}\PName{value}% +\important{\PName{option}\texttt{=}\PName{value}}. Except for this difference, +\Macro{documentclass} and \Macro{usepackage} in \KOMAScript{} function as +described in \cite{latex:usrguide} or any introduction to \LaTeX, for example \cite{lshort}.% +% +\iffree{}{\IfThisCommonLabelBase{scrlayer-scrpage}{\par + Incidentally, the \Package{scrpage2}\IndexPackage{scrpage2}% + \important{\Package{scrpage2}} package, which is considered obsolete, does + not have this extension. It therefore understands only simple options without + an assigned value.\par}{}}% \IfThisCommonLabelBaseNotOneOf{% scrjura,scrhack,scrlayer,scrlayer-scrpage,scrlayer-notecolumn,scrextend% }{% + When using a \KOMAScript{} class\textnote{Attention!}, you should not + specify options when loading the \Package{typearea} or \Package{scrbase} + packages. The reason for this restriction is that the class already loads + these packages without options, and \LaTeX{} refuses to load a package + multiple times with different option settings.% + \IfThisCommonLabelBaseOneOf{maincls,scrlttr2}{ In general, it is not + necessary to load either one of these packages explicitly when using any + \KOMAScript{} class.}{}% + \par +} - When using a {\KOMAScript} class, no options should be passed on -% Die Alternativen an dieser Stelle dienen der Verbesserung des Umbruchs - \IfThisCommonLabelBase{typearea}{unnecessary, explicit }{}% - loading of the \Package{typearea} or \Package{scrbase} packages. The reason - for this is that the class already loads these packages without options and - \LaTeX{} refuses multiple loadings of a package with different option - settings.% - \IfThisCommonLabelBaseOneOf{maincls,scrlttr2}{\ Actually, it is no longer - necessary when using any {\KOMAScript} class to explicity load either one - of these packages.}{}% -}{} - -You should note\textnote{Attention!}, that in opposite to the interface -described below the options interface of \Macro{documentclass} and -\Macro{usepackage} is not robust. So commands, lengths, counters and such -constructs may break inside the optional argument of these commands. Because -of this, the usage of a \LaTeX{} length inside the value of an option would -cause an error before \KOMAScript{} can get the control over the option -execution. So, if you want to use a \LaTeX{} length, counter or command as part -of the value of an option, you have to use +% Umbruchoptimierung!!! +\IfThisCommonLabelBase{typearea}{Setting the options with + \Macro{documentclass} or \Macro{usepackage} has one\textnote{Attention!} + major disadvantage: +}{% + Note that the \Macro{documentclass} and \Macro{usepackage} have one drawback + when using the option interface described bellow\textnote{Attention!}: +}% +unlike the interface described below, the options in \Macro{documentclass} and +\Macro{usepackage} are not robust. So commands, lengths, counters, and such +constructs may break inside the optional argument of these commands. For +example, using a \LaTeX{} length in the value of an option results in an error +before the value is passed to \KOMAScript{} and it can take control of the +option execution. So if you want to use a \LaTeX{} length, counter, or command +as part of the value of an option, you have to use \DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption}. These commands will be described next.% % @@ -157,58 +165,66 @@ of the value of an option, you have to use \Macro{KOMAoptions}\Parameter{option list} \Macro{KOMAoption}\Parameter{option}\Parameter{value list} \end{Declaration} -\KOMAScript{}\ChangedAt{v3.00}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}\and \Package{scrextend}\and - \Package{typearea}} offers most class and package options the -opportunity to change the value of options even after loading of the -class or package. One may then change the values of a list of options -at will with the \Macro{KOMAoptions} command. Each option in the -\PName{option list} has the form -\PName{option}\texttt{=}\PName{value}. - -Some options also have a default value. If one does not give a value, -i.\,e., gives the option simply in the form \PName{option}, then the -default value will be used. - -Some options can assume several values simultaneously. For such options there -exists the possibility, with the help of \Macro{KOMAoption}, to pass a single -\PName{option} a list of values. The individual values are given as a -comma-separated \PName{value list}. +\KOMAScript{}\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}\and \Package{scrextend}\and \Package{typearea}} also +provides the ability to change the values of most +\IfThisCommonLabelBaseOneOf{scrextend,scrjura}{}{class and }package options +even after loading the \IfThisCommonLabelBaseOneOf{scrextend,scrjura}{}{% + class or} package. You can use the \Macro{KOMAoptions} command to change the +values of a list of options, as in +\DescRef{\ThisCommonLabelBase.cmd.documentclass} or +\DescRef{\ThisCommonLabelBase.cmd.usepackage}. Each option in the +\PName{option list} has the form \PName{option}\texttt{=}\PName{value}% +\important{\PName{option}\texttt{=}\PName{value},\dots}. + +Some options also have a default value. If you do not specify a value, that is +if you give the option simply as \PName{option}, then this default value will +be used. + +Some options can have several values simultaneously. For such options, it is +possible, with the help of \Macro{KOMAoption}, to pass a list of values to a +single \PName{option}. The individual values are given as a comma-separated +\PName{value list}\important{\PName{value},\dots}. \begin{Explain} - % If in the \PName{option list} one sets an option to a disallowed - % value, or the \PName{value list} contains an invalid value, then an - % error is produced. If \LaTeX{} is run in an interactive mode, then - % it stops at this point. Entering ``\texttt{h}'' displays a help - % screen, in which also the valid values for the corresponding option - % are given. - - % If a \PName{value} includes an equal sign or a comma, then the - % \PName{value} must be enclosed in curly brackets. - - To implement this possibility {\KOMAScript} uses the commands - \DescRef{scrbase.cmd.FamilyOptions} and \DescRef{scrbase.cmd.FamilyOption} - with the family ``\PValue{KOMA}''. -\iffalse % Umbruchkorrektur - More information on these commands % - \IfThisCommonLabelBase{maincls}{for experts }{% - \IfThisCommonLabelBase{scrlttr2}{for experts }{}}% - is found in \autoref{sec:scrbase.keyvalue}, - \DescPageRef{scrbase.cmd.FamilyOptions}. -\else - For more information in these commands see \autoref{part:forExperts}, - \autoref{sec:scrbase.keyvalue}, - \DescPageRef{scrbase.cmd.FamilyOptions}. -\fi + \KOMAScript{} uses the commands \DescRef{scrbase.cmd.FamilyOptions} and + \DescRef{scrbase.cmd.FamilyOption} with the family ``\PValue{KOMA}'' to + implement this ability. + \IfThisCommonLabelBaseOneOf{typearea}{% Umbruchkorrektur + Advanced users will find more on these instructions in + \autoref{sec:scrbase.keyvalue}, \DescPageRef{scrbase.cmd.FamilyOptions}. + }{% + See \autoref{part:forExperts}, \autoref{sec:scrbase.keyvalue}, + \DescPageRef{scrbase.cmd.FamilyOptions}. }% \end{Explain} + +Options set with \Macro{KOMAoptions} or \Macro{KOMAoption} will reach +\IfThisCommonLabelBase{scrextend}{}{both the \KOMAScript{} class and }any +previously loaded \KOMAScript{} packages that recognise these options. If an +option or a value is unknown, \hyperref[cha:scrbase]{\Package{scrbase}}% +\IndexPackage{scrbase}\important{\hyperref[cha:scrbase]{\Package{scrbase}}} +will report it as an error.% +% +\iffalse% Umbruchkorrekturtext +\iffree{}{\IfThisCommonLabelBase{scrlayer-scrpage}{\par + Incidentally, the \Package{scrpage2}\IndexPackage{scrpage2}% + \important{\Package{scrpage2}}, which is considered obsolete, does not have + this extension. Options can therefore only be set when the package is loaded + with the option explained previously.}{}}% +\fi% % \EndIndexGroup % \EndIndexGroup +\phantomsection +\label{sec:\ThisCommonLabelBase.options.end} +\endinput %%% Local Variables: %%% mode: latex -%%% coding: iso-latin-1 +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" %%% TeX-master: "../guide" -%%% End: +%%% End: diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-pagestylemanipulation.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-pagestylemanipulation.tex index 8c85bf399fc..422721ad15d 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-pagestylemanipulation.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-pagestylemanipulation.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-pagestylemanipulation.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2013-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % common-pagestylemanipulation.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2013-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,166 +46,188 @@ % ============================================================================ \KOMAProvidesFile{common-pagestylemanipulation.tex} - [$Date: 2013-10-22 11:17:09 +0200 (Di, 22 Okt 2013) $ + [$Date: 2018-02-05 01:50:56 -0800 (Mon, 05 Feb 2018) $ KOMA-Script guide (common paragraph: - Manipulation of defined page styles)] -\translator{Markus Kohm\and Jana Schubert} + Setting up defined page styles)] +\translator{Markus Kohm\and Jana Schubert\and Karl Hagen} -% Date version of the translated file: 2015-06-18 +% Date version of the translated file: 2018-02-05 -\section{Manipulation of Defined Page Styles} +\section{Manipulating Page Styles} \seclabel{pagestyle.content} \BeginIndexGroup \BeginIndex{}{page>style} \IfThisCommonLabelBase{scrlayer}{% - Even though \Package{scrlayer} itself does not define a concrete page style - with content\,---\,the already mentioned page styles - \PageStyle{@everystyle@} and \PageStyle{empty} are initially defined without - any level and so empty and without content\,---\,, it provides some options - and commands for the manipulation of the contents.% + Although \Package{scrlayer} itself does not define concrete page styles with + content\,---\,the previously mentioned page styles + \DescRef{\LabelBase.pagestyle.@everystyle@} and \PageStyle{empty} are + initially defined without any layers, i.\,e., without content\,---\,, the + package provides some options and commands to manipulate their contents.% }{% \IfThisCommonLabelBase{scrlayer-scrpage}{% - \hyperref[sec:scrlayer-scrpage.predefined.pagestyles]% - {Section~\ref*{sec:scrlayer-scrpage.predefined.pagestyles}} states the - predefined defaults for the page style \PageStyle{scrheadings} and - \PageStyle{plain.scrheadings} and how they can be adapted. But - information about the generation of, i.\,e., the running heads, the - manipulation of the widths of page head and footer, and how you can get - horizontal lines printed above or below the page head or footer are still - missing. Even though all these are features of package \Package{scrlayer}, - they will be described consecutively, because these basic features of - \Package{scrlayer} are also a fundamental part of the features of - \Package{scrlayer-scrpage}.% + \autoref{sec:scrlayer-scrpage.predefined.pagestyles} explains how the page + styles \DescRef{\LabelBase.pagestyle.scrheadings} and + \DescRef{\LabelBase.pagestyle.plain.scrheadings} are defined and how these + defaults can be changed. But topics such as creating running headers, + changing the widths of the header and footer, and putting horizontal lines + above or below the header or footer have yet to be described. Although + these capabilities are actually part of the + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + \important{\hyperref[cha:scrlayer]{\Package{scrlayer}}} package, they will + be explained below because these basic features of + \hyperref[cha:scrlayer]{\Package{scrlayer}} make up an important part of + \IfThisCommonLabelBase{scrlayer-scrpage}{\Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + }.% }{% \IfThisCommonLabelBase{scrlayer-scrpage-experts}{% - This section is an add-on to + This section is a supplement to \autoref{sec:scrlayer.pagestyle.content}. It describes features that may - be to complicated for beginners.% + be too complicated for beginners.% }{\InternalCommonFileUsageError}% }% } - \IfThisCommonLabelBase{scrlayer-scrpage-experts}{\iffalse}{% \csname iftrue\endcsname}% \begin{Declaration} - \Macro{automark}\OParameter{section level of the right mark}% - \Parameter{section level of the left mark}% - \Macro{automark*}\OParameter{section level of the right mark}% - \Parameter{section level of the left mark}% - \Macro{manualmark}% - \Option{automark}% - \OptionVName{autooneside}{simple switch}% - \Option{manualmark} + \Macro{automark}\OParameter{section level of the right mark} + \Parameter{section level of the left mark} + \Macro{automark*}\OParameter{section level of the right mark} + \Parameter{section level of the left mark} + \Macro{manualmark} \end{Declaration} \IfThisCommonLabelBase{scrlayer-scrpage}{% \begin{Explain} - With the \LaTeX{} standard classes or the \KOMAScript{} classes the - decision whether using automatic running heads\Index{running - heads>automatic}, or static or manual running heads\Index{running - heads>static}\Index{running heads>manual} would be done using either - page style \PageStyle{headings} or \PageStyle{myheadings}. Automatic - running heads are replications of a significant, characterizing text - snippet of the page mostly inside the page head, sometimes in the page - footer. - - The article classes\OnlyAt{\Class{article}\and \Class{scrartcl}} - \Class{article} or \Class{scrartcl} with page style - \PageStyle{headings}\IndexPagestyle{headings} use the section heading, - which is either the mandatory or the optional argument of - \DescRef{maincls.cmd.section}, for the automatic running head of single side - documents. Double side documents use this section heading as the - \emph{left mark} and at once use the subsection heading as the - \emph{right mark}. The left mark will be printed on left pages, which - founds the name \emph{left mark}. The right mark will be printed on - right\,---\,in single side mode this means every\,---\,page. The classes - by default also remove the right mark whenever they put the section - heading into the left mark. - - The report and book classes \OnlyAt{\Class{report}\and - \Class{scrreprt}\and \Class{book}\and \Class{scrbook}} start one level - higher. So they use the chapter heading to be the right mark in single - side layout. In double side layout they use the chapter heading to be - the left mark and the section heading to be the right mark. - - If you are using \PageStyle{myheadings} instead of - \PageStyle{headings}\IndexPagestyle{myheadings}, the marks in the page - header still exists and would be printed same like using - \PageStyle{headings}. But section commands will not automatically set - the marks any longer. So\important{% - \DescRef{\ThisCommonLabelBase.cmd.markright}\\ - \DescRef{\ThisCommonLabelBase.cmd.markboth}}% - you can fill them only using the commands + In both the standard \LaTeX{} classes and the \KOMAScript{} classes, the + decision of whether to use automatic or static running + heads\Index{running heads>automatic}\Index{running heads>static} is made + by using the appropriate page style. Running heads repeat some + descriptive text, such as a title, that is appropriate to the page or + column, usually in the header, more rarely in the footer. As already + explained in + \autoref{sec:maincls.pagestyle}, you get automatic running heads with + \DescRef{maincls.pagestyle.headings}\IndexPagestyle{headings}% + \important{\DescRef{maincls.pagestyle.headings}} + + In the article classes\OnlyAt{\Class{article}\and \Class{scrartcl}} + \Class{article} or \hyperref[cha:maincls]{\Class{scrartcl}}, the + \PageStyle{headings}\IndexPagestyle{headings} page style uses the + section heading, which is either the mandatory or the optional argument + of \DescRef{maincls.cmd.section}, for the running head% + \textnote{automatic running head} of one-sided documents. Two-sided + documents use this section heading as the \emph{left mark} and the + subsection heading as the \emph{right mark}. The left mark is printed, + as the name indicates, on left-hand (verso) pages. The right mark is + printed on right-hand (recto)\,---\,in one-sided printing this means on + all\,---\,pages. The classes by default also delete the right mark + whenever they put the section heading into the left mark. + + The report and book classes \OnlyAt{\Class{report}\and + \Class{scrreprt}\and \Class{book}\and \Class{scrbook}} start one level + higher. Thus they use the chapter heading as the right mark in one-sided + printing. In two-sided printing, the chapter heading is the left mark + and the section heading is the right mark. + + If you use \DescRef{maincls.pagestyle.myheadings}% + \IndexPagestyle{myheadings}% + \important{\DescRef{maincls.pagestyle.myheadings}}\textnote{manual + running head}, the marks in the page header still exist, and the page + numbers are placed in the same way, but section commands no longer set + the marks automatically. You can set them manually\important{% + \DescRef{\ThisCommonLabelBase.cmd.markright}\\ + \DescRef{\ThisCommonLabelBase.cmd.markboth}} using the commands \DescRef{\ThisCommonLabelBase.cmd.markright} and - \DescRef{\ThisCommonLabelBase.cmd.markboth}, which will be described - later in this section. + \DescRef{\ThisCommonLabelBase.cmd.markboth}, which are described later + in this section. \end{Explain}\par }{% \IfThisCommonLabelBase{scrlayer}{% - In common classes the decision for a page style\,---\,generally - \PageStyle{headings} and \PageStyle{myheading}\,---\,is also a decision - to use either automatic or manual running heads. % + For most classes, the choice of a page style\,---\,generally + \PageStyle{headings} or \PageStyle{myheading}\,---\,determines whether + the running heads are created automatically or manually. % }{\InternalCommonFileUsageError}% }% - This difference between those two page styles has been abolished by - \Package{scrpage2} and also by \Package{scrlayer}. Instead of distinguishing - between automatic and manual running head by the selection of a page style, - two new commands, \Macro{automark} and \Macro{manualmark}, are provided. - - The command \Macro{manualmark} switches to manual marks and deactivates the - automatic filling of the marks. In contrast to this \Macro{automark} and - \Macro{automark*} can be used to define, which section levels should be used - for the automatic mark filling. The optional argument is the \PName{section - level of the right mark}, the mandatory argument the \PName{section level - of the left mark}. The arguments always should be the name of a section - level like \PValue{part}, \PValue{chapter}, \PValue{section}, - \PValue{subsection}, \PValue{subsubsection}, \PValue{paragraph}, or - \PValue{subparagraph}. - - Generally the higher level should be used for the left mark and the lower - level for the right mark. This is only a convention and not a need, but it - makes sense. - - Please note\textnote{Attention} that not every class provides running heads - for every section level. For example the standard classes never setup the - running head of \DescRef{maincls.cmd.part}. The \KOMAScript{} classes - provide running heads for every section level. - - The difference in \Macro{automark} and \Macro{automark*} is, that - \Macro{automark} deletes all prior usages of \Macro{automark} or - \Macro{automark*}, while \Macro{automark*} changes only the behaviour of the - section levels of its arguments. So you can even build more complex cases. + This distinction has been eliminated by % + \iffalse \Package{scrpage2} and now also by \fi% + \hyperref[cha:scrlayer]{\Package{scrlayer}}\IndexPackage{scrlayer}. Instead + of distinguishing between automatic\textnote{automatic and manual running + heads} and manual running heads by which page style is selected, there are + two new commands: \Macro{automark} and \Macro{manualmark}. + + The \Macro{manualmark}\important{\Macro{manualmark}} command switches to + manual marks and deactivates the automatic filling of the marks. In contrast, + \Macro{automark}\important{\Macro{automark}} and \Macro{automark*} define + which section levels should be used to set the mark automatically. The + optional argument is the \PName{section level of the right mark}, the + mandatory argument the \PName{section level of the left mark}. The + arguments should always be the name of a section level like + \PValue{part}, \PValue{chapter}, \PValue{section}, \PValue{subsection}, + \PValue{subsubsection}, \PValue{paragraph}, or \PValue{subparagraph}. + + Normally, the higher level should be used for the left mark and the lower + level for the right mark. This is only a convention and not a requirement, + but it makes sense. + + Please note\textnote{Attention!} that not every class provides running heads + for every section level. For example, the standard classes\textnote{% + \KOMAScript{} vs. standard classes} never use \DescRef{maincls.cmd.part} + in the heading. The \KOMAScript{} classes, on the other hand, support all + levels. + + The difference between \Macro{automark} and \Macro{automark*}% + \important{\Macro{automark*}} is that \Macro{automark} overrides all + previous commands to automatically set the mark, while \Macro{automark*} + changes only the behaviour of the section levels specified in its + arguments.% + \IfThisCommonLabelBase{scrlayer-scrpage}{}{ With this feature you can handle + relatively complex cases.}% Umbruchoptimierung \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{\csname iffalse\endcsname}% + \iffalse% Umbruchkorrekturtext + \iffree{}{\par + The obsolete package + \Package{scrpage2}\IndexPackage{scrpage2}\important{\Package{scrpage2}} + understands both \Macro{manualmark} and \Macro{automark}, but not + \Macro{automark*}. Therefore the following examples are not completely + transferable when using \Package{scrpage2}.% + }% + \fi + % \begin{Example} \phantomsection\xmpllabel{mark}% - Assume you want the chapter heading to be the running head of even pages - and the section heading to be the running head of odd pages like this is - usual for books. But on odd pages you also want the chapter headings as - a running head as long as the first section appears. To do so, you first - have to load \Package{scrlayer-scrpage} and select page style - \PageStyle{scrheadings}. So you're document starts with: + Suppose you want chapter headings to be used as the running head of even + pages and the section heading to be the running head of odd pages, as + usual. But on odd pages you also want the chapter headings to be used as + the running head until the first section appears. To do so, you first + have to load \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} + and select the \DescRef{\LabelBase.pagestyle.scrheadings} page style, + so the document starts with: \begin{lstcode} \documentclass{scrbook} \usepackage{scrlayer-scrpage} \pagestyle{scrheadings} \end{lstcode} - Next you will setup the chapter heading to be not only the left but also - the right mark: + Next, ensure that the chapter headings set both the left and the right + marks: \begin{lstcode} \automark[chapter]{chapter} \end{lstcode} - Then the section heading should also become a right mark: + Then the section heading should also set right marks: \begin{lstcode} \automark*[section]{} \end{lstcode} - Here the star version is used, because the prior \Macro{automark} - command should be still valid. Additionally the mandatory argument for - the \PName{section level of the left mark} is empty, because this mark - should be unchanged. + Here the starred version is used, since the previous \Macro{automark} + command should remain in effect. Additionally, the mandatory argument + for the \PName{section level of the left mark} is empty because this + mark should remain unchanged. - Now you just need some document contents to see a result: + All that's missing now is a bit of document content to show the result: \begin{lstcode} \usepackage{lipsum} \begin{document} @@ -215,50 +237,70 @@ \lipsum[21-40] \end{document} \end{lstcode} - We once again use package \Package{lipsum}\IndexPackage{lipsum} to - generate some dummy text with command - \Macro{lipsum}\IndexCmd{lipsum}. The package is really useful. - - If you'd test the example, you'd see, that the chapter start page does - not have a running head as usual. This is, because it automatically uses - the \PageStyle{plain} page style - \PageStyle{plain.scrheadings}. Pages~2--4 have the chapter headings in - the running head. After the section heading on page~4 the running head - of page~5 changes into this section heading. From this page to the end - the running head alternates between chapter and section heading from - page to page. + We use the extremely useful \Package{lipsum}\IndexPackage{lipsum} + package to generate some dummy text with command + \Macro{lipsum}\IndexCmd{lipsum}. + + If you test the example, you will see that the first page of the chapter + appears, as usual, without a running head, since this page automatically + uses the \PageStyle{plain} page style + \DescRef{\LabelBase.pagestyle.plain.scrheadings} (see the + \DescRef{maincls.cmd.chapterpagestyle} on + \DescPageRef{maincls.cmd.chapterpagestyle}). Pages~2--4 have the + chapter headings in the running head. After the section heading on + page~4, the running head of page~5 changes to this section heading. From + this page to the end, the running head alternates from page to page + between the chapter and section headings.% \end{Example} \fi - Instead of the commands you may also use the options \Option{manualmark} and - \Option{automark} to switch between manual and automatic running - heads. Thereby \Option{automark} always uses the default + \begin{Declaration} + \Option{automark} + \OptionVName{autooneside}{simple switch} + \Option{manualmark} + \end{Declaration} + Instead of the commands described previously, you can also use the + \Option{manualmark}\important{\Option{manualmark}\\\Option{automark}} and + \Option{automark} options to switch between automatic and manual running + heads. \Option{automark} always uses the default\textnote{default} + \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{\csname + iffalse\endcsname}% + \lstinline|\automark[section]{chapter}| for classes with + \DescRef{maincls.cmd.chapter} and + \lstinline|\automark[subsection]{section}| for other classes. + \else \begin{lstcode} \automark[section]{chapter} \end{lstcode} - for classes with \DescRef{maincls.cmd.chapter} and + for classes with \DescRef{maincls.cmd.chapter} and \begin{lstcode} \automark[subsection]{section} \end{lstcode} - for classes without \DescRef{maincls.cmd.chapter}. - - But normally in single side mode you do not want that the lower level - influences the right mark, you want the higher level, that will fill only - the left mark in double side layout, to be the running head of all - pages. The default option \Option{autooneside} corresponds to this - behaviour. The option understands the values for simple switches, that can - be found in \autoref{tab:truefalseswitch} on - \autopageref{tab:truefalseswitch}. If you'd deactivate the option, in single - side layout the optional and the obligatory arguments of \Macro{automark} - and \Macro{automark*} will influence the running head again.% + for other classes. + \fi + + \IfThisCommonLabelBase{scrlayer-scrpage}{% + In one-sided printing, you normally want only the higher section levels + to provide the running title.% + }{% + In one-sided printing, you normally do not want the lower section level + to influence the right mark. Instead, you want the higher section + level, which would appear in only the left mark in two-sided printing, to + be the running head of all pages.% + } The default option \Option{autooneside}\important{\Option{autooneside}} + corresponds to this behaviour. The option accepts the values for + simple switches listed in \autoref{tab:truefalseswitch}, + \autopageref{tab:truefalseswitch}. If you deactivate this option, the + optional and mandatory arguments of \Macro{automark} and \Macro{automark*} + will again control the running head in one-sided printing.% \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{\csname iffalse\endcsname}% \begin{Example} \phantomsection\xmpllabel{mark.oneside}% - Assume you have a single sided report but want similar running heads as - in the book example before. The chapter headings should be used as a - running head as long as the first section appears. From the first - section on, the section heading should be used. So we modify the + Suppose you have a one-sided report but want running heads similar to + those in the previous book example. Specifically, the chapter headings + should be used as the running head until the first section appears. + From the then on, the section heading should be used. So we modify the previous example a little bit: \begin{lstcode} \documentclass{scrreprt} @@ -273,77 +315,116 @@ \lipsum[21-40] \end{document} \end{lstcode} - You can see, that we do not need a \Macro{automark*} command in this - case. Please try the example also with \Option{autooneside} set to - \PValue{true} or remove the option and its value. You should find a - difference at the running head in the pages' head from page~4 on. + As you can see an \DescRef{\LabelBase.cmd.automark*} command is not + required in this case. You should try the example with + \Option{autooneside} set to \PValue{true}, or remove the option, for + comparison. You will notice a difference in the running head from + page~4 on. \end{Example} \fi - Please note\textnote{Attention!}, only loading the package does not have any - effect on the fact whether automatic or manual running heads are used or - what kind of section headings do fill up the marks. Only using an explicit - option \Option{automark} or \Option{manualmark} or one of the commands - \Macro{automark} or \Macro{manualmark} can reach a well defined state.% + Note\textnote{Attention!} that merely loading the package does not have any + effect on whether automatic or manual running heads are used, or what kind + of sectioning headings fill the marks. Only by explicitly using the option + \Option{automark} or \Option{manualmark}, or the command + \DescRef{\LabelBase.cmd.automark} or \DescRef{\LabelBase.cmd.manualmark}, + will the conditions here be initialized.% + \IfThisCommonLabelBase{scrlayer-scrpage}{\par% + You can find additional background information and examples of how to use + these commands in the documentation for the \Package{scrlayer} package + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + } in \autoref{sec:scrlayer-scrpage.pagestyle.content}, starting on + \DescPageRef{scrlayer-scrpage.cmd.manualmark}.% + }{}% + \EndIndexGroup \EndIndexGroup \begin{Declaration} \OptionVName{draft}{simple switch} \end{Declaration} - This \KOMAScript{} option understands the values for simple switches, that - are shown in \autoref{tab:truefalseswitch} on - \autopageref{tab:truefalseswitch}. If the option is active, all elements of - the page styles will also show dimension lines. This might be useful while - draft editing.% - \IfThisCommonLabelBase{scrlayer-scrpage}{% - If the option has been set as a global option (see the optional argument - of \DescRef{\LabelBase.cmd.documentclass}), but you do not want the - dimension lines, you can deactivate them for the package only using + This \KOMAScript{} option accepts the values for simple switches + listed in \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. + If this option is active, all elements of the page styles will also show + rulers\index{ruler}% + \IfThisCommonLabelBase{scrlayer}{ for}{% + . This can sometimes be useful during} + the drafting process.% + \IfThisCommonLabelBase{scrlayer-scrpage}{ % + If this option has been set globally (see the optional argument + of \DescRef{\LabelBase.cmd.documentclass}) but you do not want the + rulers, you can deactivate them for this package alone by using \OptionValue{draft}{false} as an optional argument of \DescRef{\LabelBase.cmd.usepackage} while loading the package.% }{}% \EndIndexGroup \begin{Declaration} - \Macro{MakeMarkcase}\Parameter{string} + \Macro{MakeMarkcase}\Parameter{text} \end{Declaration} - The automatic running head and only this uses \Macro{MakeMarkcase} for its - output. If the command has not been defined, e.\,g., by the class, while - loading \Package{scrlayer}, it would be defined with the default of - outputting the argument \PName{string} without changes. But the default can - be change either redefining \Macro{MakeMarkcase} or using option - \DescRef{\LabelBase.option.markcase}, that will be described next. - Depending on the setting the argument could, e.\,g., be converted into upper - or lower cases. - % + Automatic running heads, but not manual ones, use \Macro{MakeMarkcase} for + their output. If the command has not been defined, e.\,g., by the class + while loading \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }, it is defined by default to output the argument \PName{text} without + changes. But the default can be changed either by redefining + \Macro{MakeMarkcase} or by using the \DescRef{\LabelBase.option.markcase}% + \IndexOption{markcase}\important{\DescRef{\LabelBase.option.markcase}} + option, which will be described next. Depending on the setting, the + argument can, e.\,g., be converted into upper or lower case.% \EndIndexGroup \begin{Declaration} - \OptionVName{markcase}{Wert} + \OptionVName{markcase}{value} \end{Declaration} - As already mentioned with \Package{scrlayer} you may switch between manual - and automatic running heads. Using automatic running heads the corresponding - marks will be filled by the section heading commands. Some culture areas do - convert the running heads into upper case letters in opposite to the German - typographic habit. The \LaTeX{} standard classes do so by default. Package - \Package{scrlayer} optionally provides this too. Therefor you'd use option - \OptionValue{markcase}{upper} which results in a redefinition of - \DescRef{scrlayer.cmd.MakeMarkcase}\IndexCmd[indexmain]{MakeMarkcase}, a - command, that is used by \Package{scrlayer} for automatic running heads. - - Unfortunately \LaTeX's command for upper case letter typesetting, - \Macro{MakeUppercase}\IndexCmd{MakeUppercase} results in an very inadequate - typesetting, because it neither uses letter spacing nor does it space - balancing. One reason for this behaviour might be, that a glyph analyzing - would be needed, to incorporate the letter shapes and their combination - while space balancing. Because of this \KOMAScript{} author suggests to - abstain from upper case letter typesetting for running heads. This could be - achieved using \OptionValue{markcase}{used}. Nevertheless, some classes - would add \Macro{MarkUppercase} or even \TeX{} command \Macro{uppercase} - into the running heads. For such cases option - \OptionValue{markcase}{noupper} can be used. This will also deactivate + As explained earlier, with \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } you can choose between manual and automatic running heads. Using automatic + running heads, the corresponding marks are set using the section heading + commands. In some cultures, in contrast to the typography of German-speaking + countries, it is common practice to set the running heads in upper-case + letters. The \LaTeX{} standard classes do so by default. The + \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } package also offers this as an option. To do so, use the + \OptionValue{markcase}{upper}\important{\OptionValue{markcase}{upper}}% + \IndexOption[indexmain]{markcase~=upper} option, which redefines + \DescRef{scrlayer.cmd.MakeMarkcase}\IndexCmd[indexmain]{MakeMarkcase}. + + \IfThisCommonLabelBase{scrlayer}{% + Because of the poor typographical quality of the primitive capitalisation + routine (see the explanation of \DescRef{scrlayer-scrpage.option.markcase} + in \autoref{sec:scrlayer-scrpage.pagestyle.content}, + \autopageref{expl:scrlayer-scrpage.MakeUppercase}) the author of + \KOMAScript recommends that you avoid upper-case typesetting for running + heads.% + }{% + Unfortunately,\phantomsection\label{expl:\ThisCommonLabelBase.MakeUppercase} + the \LaTeX{} command for converting text to upper case\Index{upper case}, + \Macro{MakeUppercase}\IndexCmd{MakeUppercase}, does not produce good + results because it neither spaces characters nor balances lines + appropriately. This is certainly in part due to the fact that a + typographically correct upper-case conversion requires analysing the + glyphs to account for the different letter shapes \iffree{and their + combinations}{} while balancing the block. I therefore recommend that + you avoid upper-case typesetting for running heads.% + } This is usually possible with \OptionValue{markcase}{used}\important{% + \OptionValue{markcase}{used}}\IndexOption[indexmain]{markcase~=used}. + However, some classes insert \Macro{MarkUppercase}, or even the \TeX{} + command \Macro{uppercase}, into the running heads. For such cases, you can + use the option \OptionValue{markcase}{noupper}% + \important{\OptionValue{markcase}{noupper}}% + \IndexOption[indexmain]{markcase~=noupper}. This will also deactivate \Macro{MakeUppercase} and \Macro{uppercase} inside the running heads. You can find all valid values for \Option{markcase} in @@ -353,19 +434,19 @@ \IfThisCommonLabelBase{scrlayer-scrpage}{% \begin{table} \centering - \caption[Possible values for option \Option{markcase}]{Possible values + \caption[Available values for option \Option{markcase}]{Available values for option \Option{markcase} to select upper/lower case letter typesetting in automatic running heads}% \label{tab:\ThisCommonLabelBase.markcase}% \begin{desctabular} \pventry{lower}{\IndexOption[indexmain]{markcase~=lower}% redefines \DescRef{\LabelBase.cmd.MakeMarkcase} to convert the - automatic running heads into lower case letters using + automatic running heads into lower-case letters using \Macro{MakeLowercase} (lower case typesetting).% }% \pventry{upper}{\IndexOption[indexmain]{markcase~=upper}% redefines \DescRef{\LabelBase.cmd.MakeMarkcase} to convert the - automatic running heads into upper case letters using + automatic running heads into upper-case letters using \Macro{MakeUppercase} (upper case typesetting).% }% \pventry{used}{\IndexOption[indexmain]{markcase~=used}% @@ -376,104 +457,137 @@ \PValue{ignoreupper}, \PValue{noupper}}{\IndexOption[indexmain]{markcase~=noupper}% redefines not only \DescRef{\LabelBase.cmd.MakeMarkcase} but also - locally to the running heads \Macro{MakeUppercase} and - \Macro{uppercase} to leave the automatic running heads unchanged.% + \Macro{MakeUppercase} and \Macro{uppercase} locally to the running + heads to leave the automatic running heads unchanged.% }% \end{desctabular} \end{table} }{}% \EndIndexGroup + \begin{Declaration} - \Macro{leftmark}% - \Macro{rightmark}% - \Macro{headmark}% + \Macro{leftmark} + \Macro{rightmark} + \Macro{headmark} \Macro{pagemark} \end{Declaration} - If you want to differ from the predefined page styles, usually you need to - decide, where to place the marks' contents. With \Macro{leftmark} you can - state the contents of the left mark. - - Similar you can use \Macro{rightmark} to state the contents of the right - mark. For more information about some intricacies of this see the further - description of \DescRef{maincls-experts.cmd.rightmark} in + If you want to depart from the predefined page styles, you typically need to + decide where to place the marks' contents. With + \Macro{leftmark}\important{\Macro{leftmark}} you can define what will + appear in the left mark when the page is output. + + Similarly, you can use \Macro{rightmark}\important{\Macro{rightmark}} to + define the contents of the right mark.\iffree{}{ For information about some + subtleties when using these commands, see further + \DescRef{maincls-experts.cmd.rightmark} in \autoref{sec:maincls-experts.addInfos}, - \DescPageRef{maincls-experts.cmd.rightmark}. + \DescPageRef{maincls-experts.cmd.rightmark}.} - Somehow easier would be usage of \Macro{headmark}. This extension of - \Package{scrlayer} aliases either \Macro{leftmark} or \Macro{rightmark} - depending on whether the current page is even or odd. + You can make life easier with \Macro{headmark}\important{\Macro{headmark}}. + This extension of \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } is a shorthand that resolves to either \Macro{leftmark} or + \Macro{rightmark} depending on whether the current page is even or odd. - Strictly thought command \Macro{pagemark} is not involved by \TeX's mark - mechanism. It is only used to output a formatted page number. + The \Macro{pagemark}\important{\Macro{pagemark}} command has nothing to do + with \TeX's mark mechanism. It is serves to output a formatted page number. \BeginIndex{FontElement}{pagenumber}\LabelFontElement{pagenumber}% The font of element \FontElement{pagenumber}\important{\FontElement{pagenumber}} will be used - for the output. This can be changed using command \Macro{setkomafont} or - \DescRef{maincls.cmd.addtokomafont} (see also + for the output. This can be changed using the \Macro{setkomafont} or + \DescRef{maincls.cmd.addtokomafont} commands (see also \autoref{sec:maincls.textmarkup}, \DescPageRef{maincls.cmd.setkomafont}).% \EndIndex{FontElement}{pagenumber}% \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{% \par % - If you are interested in an example about usage of commands - \Macro{headmark} and \Macro{pagemark}, have a look into + If you are interested in an example showing the usage of the + \Macro{headmark} and \Macro{pagemark} commands, see \autoref{sec:scrlayer-scrpage.pagestyle.content}, - \PageRefxmpl{scrlayer-scrpage.cmd.headmark}. The package - \Package{scrlayer-scrpage} internally uses a lot of such features of - \Package{scrlayer}.% + \PageRefxmpl{scrlayer-scrpage.cmd.headmark}. Internally, the + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + } package uses many such features of + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }{% + \Package{scrlayer}% + }.% \csname iffalse\endcsname}% \begin{Example} \phantomsection\xmpllabel{cmd.headmark}% - Assume you want to use a left aligned running head and right aligned - page number in the head of the pages of a document in single side - layout. The following minimal but working examples would do so: + Suppose you want the running head to be aligned to the left margin and + the page number to the right margin in one-sided printing. The following + minimal working example does just this: \begin{lstcode} \documentclass{scrreprt} \usepackage{blindtext} \usepackage[automark]{scrlayer-scrpage} \pagestyle{scrheadings} \ihead{\headmark} - \ohead[\pagemark]{\pagemark} + \ohead*{\pagemark} \chead{} \cfoot[]{} \begin{document} \blinddocument \end{document} \end{lstcode} - Here package \Package{blindtext}\IndexPackage{blindtext} with its - command \Macro{blinddocument}\IndexCmd{blinddocument} has been used to - easily generate content for an example document. - - Commands \DescRef{scrlayer-scrpage.cmd.ihead}\IndexCmd{ihead} and - \DescRef{scrlayer-scrpage.cmd.ohead}\IndexCmd{ohead} have been used to - place the wanted marks. Although the page mark will be place not only to - pages in page style \PageStyle{scrheadings} but using the optional - argument also to pages in page style \PageStyle{plain.scrheadings}. - - Because of both page styles already have marks in the middle of the page - head and page foot, those elements will be cleared using + The \Package{blindtext}\IndexPackage{blindtext} package and its + \Macro{blinddocument}\IndexCmd{blinddocument} command have been used + here to quickly generate sample document content for the example. + + The \DescRef{scrlayer-scrpage.cmd.ihead}\IndexCmd{ihead} and + \DescRef{scrlayer-scrpage.cmd.ohead*}\IndexCmd{ohead*} commands + configure the desired marks. The starred variant + \DescRef{scrlayer-scrpage.cmd.ohead*} % + \iffalse% Umbruchvarianten + configures the page number mark not only on the pages set with the + \DescRef{\LabelBase.pagestyle.scrheadings}% + \IndexPagestyle{scrheadings} page style but also those set + with the \PageStyle{plain} % + \else% + also configures the page number with the % + \fi% + \DescRef{\LabelBase.pagestyle.plain.scrheadings}% + \IndexPagestyle{plain.scrheadings} page style used on the first page of + a chapter.% + + Because these page styles have predefined marks in the centre of the + header and footer, those elements are cleared by using \DescRef{scrlayer-scrpage.cmd.chead} and - \DescRef{scrlayer-scrpage.cmd.cfoot}\IndexCmd{cfoot} with empty - arguments. Alternatively you'd use + \DescRef{scrlayer-scrpage.cmd.cfoot} with empty arguments. Alternatively + you could use \DescRef{scrlayer-scrpage-experts.cmd.clearpairofpagestyles} \IndexCmd{clearpairofpagestyles} \emph{before} - \DescRef{scrlayer-scrpage.cmd.ihead}. You will find a description of - this command in \autoref{sec:scrlayer-scrpage-experts.pagestyle.pairs}. + \DescRef{scrlayer-scrpage.cmd.ihead}. You will find this command + described in \autoref{sec:scrlayer-scrpage-experts.pagestyle.pairs}. \end{Example} - Please note\textnote{Attention!}, that the empty optional argument of + Please note\textnote{Attention!} that the empty optional argument of \DescRef{scrlayer-scrpage.cmd.cfoot} in the example above is not the same - like omitting the optional argument. Please try it out and have a look at - the difference in the footer of the first page.% + as omitting the optional argument. You should try it yourself and have a + look at the difference in the footer of the first page.% \fi - If all the mark features described above are not sufficient, experienced - users can find more of them on \IfThisCommonLabelBase{scrlayer-scrpage}{% + \IfThisCommonLabelBase{scrlayer-scrpage}{% Umbruchvarianten + Advanced users can find more mark-setting commands% + }{% + If the options for the marks described above are not sufficient, + additional commands for advanced users are documented% + } % + starting on \IfThisCommonLabelBase{scrlayer-scrpage}{% \DescPageRef{scrlayer-scrpage-experts.cmd.righttopmark}}{% - \DescPageRef{scrlayer.cmd.righttopmark}}. For example, you can find there - \DescRef{scrlayer-scrpage-experts.cmd.leftfirstmark} and - \DescRef{scrlayer-scrpage-experts.cmd.rightbotmark}, which seem to be useful - for lexicon like documents.% + \DescPageRef{\ThisCommonLabelBase.cmd.righttopmark}}.% + \iffalse% Umbruchkorrektur + \ For example, there you can find + \DescRef{scrlayer-scrpage-experts.cmd.leftfirstmark} and + \DescRef{scrlayer-scrpage-experts.cmd.rightbotmark}, which are quite useful + for documents like lexicons.% + \fi% \EndIndexGroup @@ -486,11 +600,14 @@ \Macro{paragraphmarkformat}% \Macro{subparagraphmarkformat} \end{Declaration} - Usually the \KOMAScript{} classes and package \Package{scrlayer} use these - commands internally to bring the section numbers into wanted form and - additionally they support the \DescRef{maincls.cmd.autodot} mechanism of the - \KOMAScript{} classes. If wanted these commands may be redefined to get - another form of section numbers.% + \KOMAScript{} classes and the \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } package typically use these commands internally to format the section + numbers. They also support the \DescRef{maincls.cmd.autodot} mechanism of + the \KOMAScript{} classes. If desired, these commands can be redefined to + achieve a different formatting of section numbers.% \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{% \ See the example in \autoref{sec:scrlayer-scrpage.pagestyle.content}, \PageRefxmpl{scrlayer-scrpage.cmd.sectionmarkformat} for more @@ -499,15 +616,19 @@ }% \begin{Example} \phantomsection\xmpllabel{cmd.sectionmarkformat}% - Assume you do not want section numbers but section heading text only in - the running head. So: -\begin{lstcode} + \iftrue + For example, if you want to have running heads without a section + number, this is how you do it: + \else + Suppose you want section headings without the section number to appear + in the running head. This can be accomplished easily with the + following: + \fi +\begin{lstcode}[belowskip=-\dp\strutbox] \renewcommand*{\sectionmarkformat}{} \end{lstcode} - would be a simple solution for this. \end{Example} - \fi - % + \fi% \EndIndexGroup @@ -520,28 +641,33 @@ \Macro{paragraphmark}\Parameter{Text}% \Macro{subparagraphmark}\Parameter{Text} \end{Declaration} - Most classes use these commands to setup marks corresponding to the section - commands. Thereby the only argument is the text without the number of the - section heading, that should be used for the running head. For the number - simply the number of the current section level will be used, if the current - level uses numbers. - - Unfortunately\textnote{Attention!}, not all classes use such a command for - every section level. The standard classes for example do not call - \Macro{partmark}. The \KOMAScript{} classes support such commands for all - section levels and therefore also use \Macro{partmark}. - - If users redefine these commands, they should\textnote{Attention!} take care - to also use the counter \DescRef{maincls.counter.secnumdepth} for the test - whether or not the section level should output a number, even in the case - the user does not change counter \DescRef{maincls.counter.secnumdepth} - himself, because packages and classes may do so locally and rely on correct - handling of \DescRef{maincls.counter.secnumdepth}. - - However, package \Package{scrlayer} redefines these commands whenever you - use \DescRef{scrlayer.cmd.automark} or \DescRef{scrlayer.cmd.manualmark} or - the corresponding options, to activate or deactivate the wanted running - heads.% + Most classes use these commands internally to set the marks according to the + sectioning commands. The argument should contain the text without the number + of the sectioning unit. The number is automatically determined using the + current section level if you use numbered headings. + + However\textnote{Attention!}, not all classes use such a command for + every section level. The standard classes\textnote{\KOMAScript{} vs. + standard classes}, for example, do not call \Macro{partmark} + \IfThisCommonLabelBase{scrlayer-scrpage}{% + upon a \Macro{part} command}{% + , whereas the \KOMAScript{} classes naturally support \Macro{partmark} as + well}. + + If you redefine these commands, be sure\textnote{Attention!} to check + whether the numbers will be output via the + \DescRef{maincls.counter.secnumdepth} before setting the number even if you + do not change the \DescRef{maincls.counter.secnumdepth} counter yourself, + because packages and classes may do so locally and rely on correct handling + of \DescRef{maincls.counter.secnumdepth}. + + The \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } package also redefines these commands whenever you use + \DescRef{scrlayer.cmd.automark} or \DescRef{scrlayer.cmd.manualmark} or the + corresponding options, to activate or deactivate the desired running heads.% \EndIndexGroup @@ -550,36 +676,50 @@ \Macro{markright}\Parameter{right mark}% \Macro{markboth}\Parameter{left mark}\Parameter{right mark} \end{Declaration} - Independent of whether currently manual or automatic running heads are - active, you may change the contents of the \PName{left mark} or the - \PName{right mark} at any time using these commands. You should note, that - the resulting contents of \Macro{leftmark}\IndexCmd{leftmark} is the - \PName{left mark} of the last \Macro{markleft} or \Macro{markboth} command - of the current page. In opposite to this the resulting contents of - \Macro{rightmark}\IndexCmd{rightmark} is the \PName{right mark} of the first - \Macro{rightmark} or \Macro{markboth} command of the current page. - - If you are using manual running heads, the marks will stay valid until one - of the corresponding commands will be used again. If you are using automatic - running heads the marks can loose their validity with the next section - heading depending on the configuration of the automatism. - - You may also use these commands together with the star versions of the - section commands.% + Regardless of whether you are working with manual or automatic running + heads, you can always change the contents of the \PName{left mark} or the + \PName{right mark} using these commands. Note that the left-hand mark + resulting from \Macro{leftmark}\IndexCmd{leftmark}% + \important{\Macro{leftmark}} will be the last mark placed on the + corresponding page, while the right-hand mark resulting from + \Macro{rightmark}\IndexCmd{rightmark}\important{\Macro{rightmark}} is the + first mark placed on the corresponding page. For more details, see + \iffree{}{the additional explanation of + \DescRef{maincls-experts.cmd.rightmark} in + \autoref{sec:maincls-experts.addInfos}, + \DescPageRef{maincls-experts.cmd.rightmark} or} to + \DescRef{scrlayer.cmd.rightfirstmark}\IfThisCommonLabelBase{scrlayer}{}{ in + \autoref{sec:scrlayer.pagestyle.content}}, + \DescPageRef{scrlayer.cmd.rightfirstmark}. + + If you are using manual running heads\Index{running head>manual}, the marks + remain valid until they are explicitly replaced by reusing the corresponding + commands. However, if you are using automatic running heads, the marks can + become invalid with the next section heading, depending on the automatic + configuration. + + You can also use these commands in conjunction with the starred versions of + the sectioning commands.% \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{% - \ You can find a detailed example about usage of \Macro{markboth} with - \Package{scrlayer-scrpage} in + \ You can find detailed examples illustrating usage of \Macro{markboth} + with the \IfThisCommonLabelBase{scrlayer-scrpage}{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }{% + \Package{scrlayer}% + }-derived package \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + } in \autoref{sec:scrlayer-scrpage.pagestyle.content}, - \PageRefxmpl{scrlayer-scrpage.cmd.markboth}. Package - \Package{scrlayer-scrpage} is a kind of extension of \Package{scrlayer}.% + \PageRefxmpl{scrlayer-scrpage.cmd.markboth}.% \csname iffalse\endcsname% }% \begin{Example} \phantomsection\xmpllabel{cmd.markboth}% - Assume you are using a preface with several pages just before the table - of contents, that should not have an entry at the table of contents - itself. Because of using a separation line at the page head, you want - also a running head for this preface: + Suppose you write a preface of several pages placed just before the + table of contents but not appearing in it. However, since you use + dividing lines in your header, you want a running head for this preface: \begin{lstcode} \documentclass[headsepline]{book} \usepackage{scrlayer-scrpage} @@ -593,9 +733,10 @@ \blinddocument \end{document} \end{lstcode} - First of all this seems to produce the wanted result. But have a closer - look: In difference to the other running heads ``\texttt{Preface}'' is - not in upper case letters. But you can fix this easily: + At first glance, this seems to produce the desired result. Taking a + second look, however, you can see that the running title + ``\texttt{Preface}'' does not appear in upper-case letters, unlike the + other running heads. But that's easy to change: \begin{lstcode} \documentclass[headsepline]{book} \usepackage{scrlayer-scrpage} @@ -612,14 +753,14 @@ Using command \DescRef{\LabelBase.cmd.MakeMarkcase} results in getting the same letter case as for automatic running heads. - Now, let's move command \DescRef{maincls.cmd.tableofcontents} in front - of the preface. Let's remove the \Macro{markboth} command too. You'll - realise, that the preface now has the running head - ``\texttt{CONTENTS}''. This is because of a quirk of + Now, let's move the \DescRef{maincls.cmd.tableofcontents} in front + of the preface and remove the \Macro{markboth} command. You'll + discover that the preface now has the running head + ``\texttt{CONTENTS}''. This is due to a quirk of \DescRef{maincls.cmd.chapter*} (see also \autoref{sec:maincls.structure} - on \DescPageRef{maincls.cmd.chapter*}). If in such cases the running - head should be removed, \Macro{markboth} with two empty arguments would - be useful: + on \DescPageRef{maincls.cmd.chapter*}). If you do not want a running + head here, you can easily accomplish this by passing two empty arguments + to \Macro{markboth}: \begin{lstcode} \documentclass[headsepline]{book} \usepackage{scrlayer-scrpage} @@ -634,8 +775,7 @@ \end{document} \end{lstcode} \end{Example} - \fi - % + \fi% \EndIndexGroup \fi @@ -644,39 +784,49 @@ \begin{Declaration} \Macro{GenericMarkFormat}\Parameter{name of the section level} \end{Declaration} - At the running head this command will be used by default for the formatting - of all section numbers below the subsection and with classes without - \DescRef{maincls.cmd.chapter} also for the section level and the subsection - level, if the mark commands for those numbers have not been defined before - loading \Package{scrlayer}. Thereby the package uses - \Macro{@seccntmarkformat} if such a command has been defined, like the - \KOMAScript{} classes do. Otherwise \Macro{@seccntformat} will be used, - which is provided by the \LaTeX{} kernel. The expected, mandatory argument - of the command is the \PName{name of a section level}, i.\,e., - \PValue{chapter} or \PValue{section} \emph{without} the backslash prefix. - - You can change the default formatting of the numbers, that use this command, - by redefining only this single command. Classes can change the default + By default, this command is used to format all section numbers in running + heads below the subsection level, and for classes without + \DescRef{maincls.cmd.chapter}, also for the section and subsection levels, + unless the respective mark commands for those levels are defined before + loading \Package{scrlayer}. The command causes the package to use + \Macro{@seccntmarkformat}\IndexCmd{@seccntmarkformat}% + \important{\Macro{@seccntmarkformat}} if this internal command is defined, + as it is in the \KOMAScript{} classes. Otherwise \Macro{@seccntformat}% + \IndexCmd{@seccntformat}\important{\Macro{@seccntformat}} will be used, + which is provided by the \LaTeX{} kernel. The mandatory argument of the + command contains the name of a sectioning command, such as \PValue{chapter} + or \PValue{section} \emph{without} the backslash prefix. + + By redefining this command, you can change the default number format for all + sectioning commands that use it. Classes can also change the default formatting also by defining this command.% \IfThisCommonLabelBase{scrlayer-scrpage-experts}{\iftrue}{% \par % - A detailed example about cooperation of command \Macro{GenericMarkFormat} - and the commands \DescRef{\ThisCommonLabelBase.cmd.sectionmarkformat} and - \DescRef{\ThisCommonLabelBase.cmd.subsectionmarkformat} that are described - at \DescPageRef{\ThisCommonLabelBase.cmd.chaptermark} is shown in - \autoref{sec:scrlayer-scrpage-experts.pagestyle.content}, + A detailed example illustrating the interplay of the + \Macro{GenericMarkFormat} command with the + \DescPageRef{\ThisCommonLabelBase.cmd.chaptermark} command and + \DescRef{\ThisCommonLabelBase.cmd.sectionmarkformat} or + \DescRef{\ThisCommonLabelBase.cmd.subsectionmarkformat} when using + the \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }-derived package \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + } is shown in \autoref{sec:scrlayer-scrpage-experts.pagestyle.content}, \PageRefxmpl{scrlayer-scrpage-experts.cmd.GenericMarkFormat}.% \csname iffalse\endcsname}% \begin{Example} - \phantomsection + \phantomsection \xmpllabel{cmd.GenericMarkFormat}% - Assume you want the section numbers of all levels at the running head of - an article to be printed in white colour inside a black coloured - box. Using standard \LaTeX{} \Class{article} class, package - \Package{scrlayer} defines the number mark commands - \Macro{sectionmarkformat} and \Macro{subsectionmarkformat} using - \Macro{GenericMarkFormat}. So you need to redefine only this single - command: + Suppose you want the section numbers of all levels in the running head + of an article to be printed in white within a black box. Since the + commands \Macro{sectionmarkformat} and \Macro{subsectionmarkformat} of + the \Package{scrlayer} package are defined with + \Macro{GenericMarkFormat} for articles using the standard \LaTeX{} + \Class{article} class, you need to redefine only this one command: \begin{lstcode} \documentclass{article} \usepackage{blindtext} @@ -691,40 +841,39 @@ \blinddocument \end{document} \end{lstcode} - The colour has been done using package - \Package{xcolor}\IndexPackage{xcolor}. See the package manual for more - information about this. + The colour has been changed using the + \Package{xcolor}\IndexPackage{xcolor} package. More details can be found + in that package's manual (see \cite{package:xcolor}). - Additionally a not visible strut has been used. Every complete \LaTeX{} + This example also uses an invisible strut. Any detailed \LaTeX{} introduction should explain the related command \Macro{strut}. - A helper macro \Macro{numberbox} has been defined for the formatting of - the number within a box. In the redefinition of - \Macro{GenericMarkFormat} this has been prefixed by \Macro{protect} to - protect it from expansion. This is necessary because otherwise the upper - case letter conversion of \Macro{MakeUppercase} that will be used for - the running head, would result in an ask for colours ``\texttt{BLACK}'' - and ``\texttt{WHITE}'' instead of ``\texttt{black}'' and - ``\texttt{white}'' and those colours are undefined. Alternatively you - may define \Macro{numberbox} using \Macro{DeclareRobustCommand*} instead - of \Macro{newcommand*} and then omit \Macro{protect} (see - \cite{latex:clsguide}). - - If you'd do the same with a \KOMAScript{} class or with one of the - \LaTeX{} standard classes \Class{book} or \Class{report}, you'd - additionally have to redefine \DescRef{scrlayer.cmd.sectionmarkformat}% - \IndexCmd{sectionmarkformat}% + A helper macro, \Macro{numberbox}, has been defined to format the number + within a box. This command is prefixed in the redefinition of + \Macro{GenericMarkFormat} by \Macro{protect} in order to protect it from + expansion. This is necessary because otherwise the upper-case letter + conversion of \Macro{MakeUppercase} for the running head, would result + in using the colours ``\texttt{BLACK}'' and ``\texttt{WHITE}'' instead + of ``\texttt{black}'' and ``\texttt{white}'', and those colours are + undefined. Alternatively, you could define \Macro{numberbox} using + \Macro{DeclareRobustCommand*} instead of \Macro{newcommand*} and omit + \Macro{protect} (see \cite{latex:clsguide}). + + If you wanted to achieve the same effect with a \KOMAScript{} class or + with the standard \LaTeX{} classes \Class{book} or \Class{report}, you + would also have to redefine, respectively, + \DescRef{scrlayer.cmd.sectionmarkformat}\IndexCmd{sectionmarkformat}% \important{\DescRef{scrlayer.cmd.sectionmarkformat}} and \DescRef{scrlayer.cmd.subsectionmarkformat}% \IndexCmd{subsectionmarkformat}% - \important{\DescRef{scrlayer.cmd.subsectionmarkformat}} respectively + \important{\DescRef{scrlayer.cmd.subsectionmarkformat}}, or \DescRef{scrlayer.cmd.chaptermarkformat}% \IndexCmd{chaptermarkformat}% \important{\DescRef{scrlayer.cmd.chaptermarkformat}} and \DescRef{scrlayer.cmd.sectionmarkformat}% \IndexCmd{sectionmarkformat}% - \important{\DescRef{scrlayer.cmd.sectionmarkformat}} and too, because - then these would not have been defined using \Macro{GenericMarkFormat}: + \important{\DescRef{scrlayer.cmd.sectionmarkformat}}, because + these are not by default defined using \Macro{GenericMarkFormat}: \begin{lstcode} \documentclass{scrbook} \usepackage{blindtext} @@ -742,8 +891,7 @@ \end{document} \end{lstcode} \end{Example} - \fi - % + \fi% \EndIndexGroup @@ -755,66 +903,79 @@ \Macro{leftbotmark}% \Macro{leftfirstmark} \end{Declaration} - For page styles \LaTeX\ChangedAt{v3.16}{\Package{scrlayer}} uses a bipartite - \TeX{} mark. Running heads can use the left part of that mark by - \DescRef{scrlayer.cmd.leftmark}% + \LaTeX\ChangedAt{v3.16}{\Package{scrlayer}} typically uses a two-part + \TeX{} mark for page styles. Running heads can access the left part of that + mark with \DescRef{scrlayer.cmd.leftmark}% \important{\DescRef{scrlayer.cmd.leftmark}}\IndexCmd{leftmark} and the right - part by \DescRef{scrlayer.cmd.rightmark}% - \important{\DescRef{scrlayer.cmd.rightmark}}\IndexCmd{rightmark}. Indeed, it - seems that it was suggested to use \DescRef{scrlayer.cmd.leftmark} for the - running head of left, even pages and \DescRef{scrlayer.cmd.rightmark} for - the running head of right, odd pages of double-sided documents. Within - single-sided layouts the standard classes even do not set the left part of - the mark. - - \TeX{} itself knows three alternatives to make usage of a mark. The - \Macro{botmark} is the last valid mark of the page that has been build - last. If there has not been set any mark on the page, it is the last mark of - the already shipped out pages. \LaTeX{} command - \DescRef{scrlayer.cmd.leftmark} uses exactly this mark. So it shows the left - part of the last mark of the page. This is the same like - \Macro{leftbotmark}. In opposite to this \Macro{rightbotmark} shows the - right part of that mark. - - \Macro{firstmark} is the first mark of the page that has been build - last. This means the first mark, that has been set on the page. If there has - not been set any mark on the page, this is the last mark of the already - shipped out pages. \LaTeX{} command \DescRef{scrlayer.cmd.rightmark} uses - exaclty this mark. So it shows the right part of the first mark of the - page. This is the same like \Macro{rightfirstmark}. In opposite to this - \Macro{leftfirstmark} shows the left part of that mark. - - \Macro{topmark} is the content of \Macro{botmark} before building the - current page. \LaTeX{} itself does not use it. Nevertheless, - \Package{scrlayer} provides \Macro{lefttopmark} to show the left part of it - and \Macro{righttopmark} to show the right part of it. - - Note\textnote{Attention!} that the left part and the right part of the mark - can be made all together only. Even if you use + part with \DescRef{scrlayer.cmd.rightmark}% + \important{\DescRef{scrlayer.cmd.rightmark}}\IndexCmd{rightmark}. In fact, + it was probably intended to use \DescRef{scrlayer.cmd.leftmark} for the + running head of left (even) pages and \DescRef{scrlayer.cmd.rightmark} for + the running head of right (odd) pages of two-sided documents. In + one-sided printing, however, the standard classes do not even set the left + part of the mark. + + \TeX{} itself knows three ways to access a mark. The \Macro{botmark}% + \IndexCmd{botmark}\important{\Macro{botmark}} is the last valid mark of the + most recent page that has been built. If no mark has been set on the page, + it corresponds to the last mark set on the pages that have already been + shipped out. The \LaTeX{} command \DescRef{scrlayer.cmd.leftmark} uses + precisely this mark, so it returns the left part of the last mark of the + page. This corresponds exactly to \Macro{leftbotmark}% + \important{\Macro{leftbotmark}}. By comparison, \Macro{rightbotmark}% + \important{\Macro{rightbotmark}} prints the right part of this mark. + + \Macro{firstmark}\IndexCmd{firstmark}\important{\Macro{firstmark}} is the + first mark of the last page that has been built. This is the first mark that + has been set on the page. If no mark has been set on the page, it + corresponds to the last mark of the pages that have already been shipped + out. The \LaTeX{} command \DescRef{scrlayer.cmd.rightmark} uses precisely + this mark, so it returns the right part of the first mark of the page. This + corresponds exactly to \Macro{rightfirstmark}% + \important{\Macro{rightfirstmark}}. By comparison, \Macro{leftfirstmark}% + \important{\Macro{leftfirstmark}} prints the left part of this mark. + + \Macro{topmark}\IndexCmd{topmark}\important{\Macro{topmark}} is the content + that \Macro{botmark} had before building the current page. \LaTeX{} itself + does not use it. Nevertheless, \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } provides \Macro{lefttopmark}\important{\Macro{lefttopmark}} to access the + left part of this mark and \Macro{righttopmark}% + \important{\Macro{righttopmark}} to access the right part. + + Note\textnote{Attention!} that the left and right portions of the mark + can only be set together. Even if you use \DescRef{scrlayer.cmd.markright}\IndexCmd{markright} to change only the - right part, the left part will be made again (unchanged). Accordingly in - double-side mode using page style - \PageStyle{headings\important{\PageStyle{headings}}\IndexPagestyle{headings}} - the higher section levels always make both parts. For example + right part, the left part will set again (unchanged). Accordingly, in + two-sided printing, using the \PageStyle{headings}% + \important{\PageStyle{headings}}\IndexPagestyle{headings} page style, + the higher section levels always make both parts. For example, \DescRef{scrlayer.cmd.chaptermark} uses \DescRef{scrlayer.cmd.markboth} with - an empty right argument in this case. This is the reason why + an empty right argument in this case. This is the reason \DescRef{scrlayer.cmd.rightmark} or \Macro{rightfirstmark} always shows an - empty value on pages with chapter beginnings, even if there was a + empty value on pages which start a chapter, even if there was a \DescRef{scrlayer.cmd.sectionmark} or \DescRef{maincls.cmd.section} on the same page to make the right part of the mark. Please note\textnote{Attention!} that using any of these commands to show - the left or right part of the mark as part of the page content could have - unexpected results. They are recommended to be used in the head or foot of a - page style only. So with \Package{scrlayer} they should be part of the - contents of a layer. But it does not matter whether or not a layer is - restricted to the background or the foreground. Both kind of layers are - shipped out after building the current page. - - If you need more information about the mark mechanism of \TeX, please have a - look at \cite[chapter~23]{knuth:texbook}. You will find, that marks are an - issue for real experts. So if the explanation above was at least more - confusing than illuminative: Please don't worry.% + the left or right part of the mark as part of the page content may lead to + unexpected results. They are really meant for use in the header or footer + of a page style only. Therefore, they should always be part of the contents + of a layer when using \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }. But it does not matter whether the layer is restricted to the background + or the foreground, since all layers are shipped out after building the + current page. + + If you need more information about the mark mechanism + \iffree{of \TeX{}}{\unskip}, please have a look at + \cite[chapter~23]{knuth:texbook}. The topic is flagged there as an issue for + real experts. \IfThisCommonLabelBase{scrlayer}{% Umbruchkorrektur + So if the explanation above confused you, please don't worry about it.}{}% \EndIndexGroup @@ -824,40 +985,45 @@ \Macro{@mkdouble}\Parameter{mark}% \Macro{@mkboth}\Parameter{left mark}\Parameter{right mark} \end{Declaration} - Sometimes inside classes and packages the marks for running heads should be - filled up only if automatic running heads are active (see option - \DescRef{scrlayer.option.automark} and command - \DescRef{scrlayer.cmd.automark} on - \DescPageRef{scrlayer-scrpage.cmd.automark}). In the \LaTeX{} standard - classes only \Macro{@mkboth} has been used for this. This command is either - \Macro{@gobbletwo}, that simply destroys both mandatory arguments, or - \DescRef{scrlayer.cmd.markboth}, a command that fills up the left and - \PValue{left mark} and the \PValue{right mark}. Packages like - \Package{babel} also change \Macro{\@mkboth}, i.\,e., to add language - switching to the running head. - - But if a class or package author only wants to change either the \PName{left - mark} or the \PName{right mark} without the other one, a proper command is - missing. Package \Package{scrlayer} itself needs such commands for the - implementation of all cases of automatic running heads. So if command - \Macro{@mkleft} to fill up only the left mark or \Macro{@mkright} to fill up - only the right mark or \Macro{@mkdouble} to fill up both marks with the same - content is undefined while loading \Package{scrlayer}, the package will - define them. Thereby the actual definition of \Macro{@mkboth} will be used - as an indicator whether or not automatic running heads should be used. The - new commands will full up the marks only in the case of automatic running - heads. - - Class and package authors can use these commands too, if they want to fill - up only one of the marks or both marks with the same content but only if - automatic running heads are activated. This condition is also the difference - to the commands \Macro{markleft}, \Macro{markright}, and \Macro{markboth}.% - \EndIndexGroup -\fi - + Within classes and packages, you may only want to use running heads if + automatic running heads are active (see the + \DescRef{scrlayer.option.automark} option and the + \DescRef{scrlayer.cmd.automark} command on + \DescPageRef{scrlayer-scrpage.cmd.automark}). In the standard \LaTeX{} + classes, this only works with \Macro{@mkboth}. This command corresponds to + either \Macro{@gobbletwo}, which simply consumes both mandatory arguments, + or \DescRef{scrlayer.cmd.markboth}, which sets both the \PValue{left mark} + and the \PValue{right mark}. Packages like \Package{babel} also change + \Macro{\@mkboth}, e.\,g., to enable language switching in the running head. + + However, if you want to change only the \PName{left mark} or the + \PName{right mark} without changing the other one, there is no corresponding + command. The \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } package itself needs such commands to implement automatic running heads. + So if \Macro{@mkleft}, for setting the left mark only, or \Macro{@mkright}, + for setting the right mark only, or \Macro{@mkdouble}, for setting both + marks with the same content, is undefined when loading + \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }, this package will define them. This definition uses the state of + \Macro{@mkboth} as an indication of whether to use automatic running heads. + The commands will set the marks only in the case of automatic running heads. + + Class and package authors can also fall back on these commands as appropriate + if they want to set the left or right the marks only if automatic running + heads are activated.% + \EndIndexGroup% +\fi% +% \IfThisCommonLabelBase{scrlayer}{% - For more information about manipulation of the contents of page styles see - also \autoref{sec:scrlayer-scrpage.pagestyle.content} from + \par + For more information about manipulating the contents of page styles, see + also \autoref{sec:scrlayer-scrpage.pagestyle.content} starting at \autopageref{sec:scrlayer-scrpage.pagestyle.content}.% }{}% \EndIndexGroup diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-parmarkup.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-parmarkup.tex index dad2091a6f1..647d09dde34 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-parmarkup.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-parmarkup.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-parmarkup.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % common-parmarkup.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,94 +46,107 @@ % ====================================================================== \KOMAProvidesFile{common-parmarkup.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (common paragraph: Paragraph Markup)] -\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi} +\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi\and + Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-01-31 -\section{Paragraph Markup} +\section{Marking Paragraphs} \seclabel{parmarkup}% \BeginIndexGroup -\BeginIndex{}{paragraph>markup}% +\BeginIndex{}{paragraph>marking}% \IfThisCommonLabelBase{maincls}{% The\textnote{paragraph indent vs. paragraph spacing} standard classes normally set paragraphs\Index[indexmain]{paragraph} indented and without any - vertical inter-paragraph space. This is the best solution when using a - regular page layout, like the ones produced with the \Package{typearea} + vertical, inter-paragraph space. This is the best solution when using a + regular page layout like the ones produced with the \Package{typearea} package. If neither indentation nor vertical space is used, only the length - of the last line would give the reader a reference point. In extreme cases, - it is very difficult to detect whether a line is full or not. Furthermore, - it is found that a marker at the paragraph's end tends to be easily - forgotten by the start of the next line. A marker at the paragraph's - beginning is more easily remembered. Inter-paragraph spacing has the + of the last line would give the reader a guide to the paragraph break. In + extreme cases, it is very difficult to tell whether a line is full or not. + Furthermore, typographers find that a signal given at the paragraph's end is + easily forgotten by the start of the next line. A signal at the paragraph's + beginning is more easily remembered. Inter-paragraph spacing has the drawback of disappearing in some contexts. For instance, after a displayed formula it would be impossible to detect if the previous paragraph continues - or if a new one begins. Also, when starting to read at the top of a new page - it might be necessary to look at the previous page in order determine if a - new paragraph has been started or not. All these problems disappear when - using indentation. A combination of indentation and vertical inter-paragraph - spacing is extremely redundant and therefore should be avoided. The - indentation\Index[indexmain]{indentation} is perfectly sufficient by - itself. The only drawback of indentation is the reduction of the line - length. The use of inter-paragraph spacing\Index{paragraph>spacing} is - therefore justified when using short lines, for instance in a newspaper.% + or a new one begins. Also, at the top of a new page, it might be necessary + to look at the previous page to determine if a new paragraph has been + started or not. All these problems disappear when using indentation. A + combination of indentation and vertical inter-paragraph spacing is redundant + and therefore should be avoided. Indentation\Index[indexmain]{indentation} + alone is sufficient. The only drawback of indentation is that it shortens + the line length. The use of inter-paragraph spacing\Index{paragraph>spacing} + is therefore justified when using short lines, such as in a newspaper.% }{% \IfThisCommonLabelBase{scrlttr2}{% - In the preliminaries of \autoref{sec:maincls.parmarkup}, - \autopageref{sec:maincls.parmarkup} it was argued why paragraph indent is - preferred over paragraph spacing. But the elements the argumentation - depends on, i.\,e., figures, tables, lists, equations, and even new pages, - are rare. Often letters are not so long that an oversighted paragraph will - have serious consequences to the readability of the document. Because of - this, the arguments are less serious for standard letters. This may be one - reason that in letters you often encounter paragraphs marked not with - indentation of the first line, but with a vertical skip between them. But - there may be still some advantages of the paragraph indent. One may be - that such a letter is highlighted in the mass of letters. Another may be - that the \emph{corporate identity} need not be broken for letters only.% + The preliminaries of \autoref{sec:maincls.parmarkup}, + \autopageref{sec:maincls.parmarkup} explain why paragraph indentation is + preferred to paragraph spacing. But the elements to which this explanation + refers, for example figures, tables, lists, equations, and even new pages, + are rare in normal letters. Letters are usually not so long that an + unrecognised paragraph will have serious consequences to the readability + of the document. The arguments for indentation, therefore, are less + consequential for standard letters. This may be one reason that you often + find paragraphs in letters marked with vertical spacing. But two + advantages of paragraph indentation remain. One is that such a letter + stands out from the crowd. Another is that it maintains the \emph{brand + identity}, that is the uniform appearance, of all documents from a single + source.% }{\InternalCommonFileUsageError}% } % \IfThisCommonFirstRun{}{% - Apart from these suggestions, everything that has been written at + Apart from these suggestions, the information described in \autoref{sec:\ThisCommonFirstLabelBase.parmarkup} for the other - \KOMAScript{} classes is valid for letters too. So if you have alread read + \KOMAScript{} classes is valid for letters too. So if you have already read and understood \autoref{sec:\ThisCommonFirstLabelBase.parmarkup} you can - jump to \autoref{sec:\ThisCommonLabelBase.parmarkup.next} on + skip ahead to \autoref{sec:\ThisCommonLabelBase.parmarkup.next} on \autopageref{sec:\ThisCommonLabelBase.parmarkup.next}.% + \IfThisCommonLabelBase{scrlttr2}{ % + This also applies if you work not with the + \Class{scrlttr2}\OnlyAt{scrlttr2} class but with the \Package{scrletter} + package. The package does not provide its own settings for paragraph + formatting but relies entirely on the class being used.% + }{}% } \begin{Declaration} - \OptionVName{parskip}{manner} + \OptionVName{parskip}{method} \end{Declaration} \IfThisCommonLabelBase{maincls}{% - Once in a while there are requests for a document layout with vertical - inter-paragraph spacing instead of indentation. The \KOMAScript{} classes - provide with option \Option{parskip}\ChangedAt{v3.00}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} several capabilities to use - inter-paragraph spacing instead of paragraph indent.% + Once in a while you may require a document layout with vertical + inter-paragraph spacing instead of indentation. The \KOMAScript{} classes + provide several ways to accomplish this with the + \Option{parskip}\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} option.% }{% \IfThisCommonLabelBase{scrlttr2}{% - Especially in letters you often encounter paragraphs marked not with - indentation of the first line, but with a vertical skip between - them. \KOMAScript{} class \Class{scrlttr2} provides several capabilities for - this.% + In letters, you often encounter paragraphs marked not by indentation of + the first line but by a vertical space between them. The \KOMAScript{} + class \Class{scrlttr2}\OnlyAt{scrlttr2} provides ways to accomplish this + with the \Option{parskip} option.% }{\InternalCommonFileUsageError}% } % -The \PName{manner} consists of two elements. The first element is either -\PValue{full} or \PValue{half}, meaning the space amount of one line or only -half of a line. The second element is ``\PValue{*}'', ``\PValue{+}'', or -``\PValue{-}'', and may be omitted. Without the second element the last line -of a paragraph will end with white space of at least 1\Unit{em}. With the plus -character as second element the white space amount will be a third, and with -the asterisk a fourth, of the width of a normal line. The minus variant does -not take care about the white space at the end of the last line of a -paragraph. +The \PName{method} consists of two elements. The first element is either +\PValue{full}\important{\OptionValue{parskip}{full}\\ + \OptionValue{parskip}{half}} or \PValue{half}, where \PValue{full} stands +for a paragraph spacing of one line and \PValue{half} stands for a paragraph +spacing of half a line. The second element consists of one of the characters +``\PValue{*}'', ``\PValue{+}'', or ``\PValue{-}'' and can be omitted. Without +the second element\important{\OptionVName{parskip}{distance}}, the final line +of a paragraph will end with a white space of at least 1\Unit{em}. With the +plus character as the second element% +\important{\OptionValue{parskip}{\PName{distance}+}}, the white space will be +at least one third\,---\,and with the +asterisk\important{\OptionValue{parskip}{\PName{distance}*}} one +fourth\,---\,the width of a normal line. With the minus variant% +\important{\OptionValue{parskip}{\PName{Abstand}-}}, no provision is made for +white space in the last line of a paragraph. -The setting may be changed at any place inside the document. In this case the -command \Macro{selectfont}\IndexCmd{selectfont}% +You can change the setting at any time. If you change it inside the document, +the \Macro{selectfont}\IndexCmd{selectfont}% \IfThisCommonLabelBase{maincls}{% \ChangedAt{v3.08}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% @@ -144,19 +157,20 @@ command \Macro{selectfont}\IndexCmd{selectfont}% \InternalComonFileUsageError% }% } % -will be called implicitly. The change will be valid and may be seen from the -next paragraph. +command will be called implicitly. Changes to paragraph spacing within a +paragraph will not be visible until the end of the paragraph. -Besides the resulting eight possible combinations for \PName{manner}, the values -for simple switches shown at \autoref{tab:truefalseswitch}, -\autopageref{tab:truefalseswitch} may be used. Switching on the option would -be the same as using \PValue{full} without annex and therefore will result in -inter-paragraph spacing of one line with at least 1\Unit{em} white space at -the end of the last line of each paragraph. Switching off the options would -reactivate the default of 1\Unit{em} indent at the first line of the -paragraph instead of paragraph spacing. All the possible values of option -\Option{parskip} are shown in -\autoref{tab:\ThisCommonFirstLabelBase.parskip}% +In addition to the resulting eight combinations for \PName{method}, you can +use the values for simple switches shown in \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch}. Activating the option% +\important{\Option{parskip}\\\OptionValue{parskip}{true}} corresponds to using +\PValue{full} with no second element and therefore results in inter-paragraph +spacing of one line with at least 1\Unit{em} white space at the end of the +last line of each paragraph. Deactivating% +\important{\OptionValue{parskip}{false}} the option re-activates the default +indentation of 1\Unit{em} at the first line of the paragraph instead of +paragraph spacing. A summary of all possible values for \PName{method} are +shown in \autoref{tab:\ThisCommonFirstLabelBase.parskip}% \IfThisCommonFirstRun{.% \begin{desclist} % Umbruchkorrektur @@ -165,54 +179,55 @@ paragraph instead of paragraph spacing. All the possible values of option % \begin{table} \desccaption % \caption - [{Possible values of option \Option{parskip}}]{% - Possible values of option \Option{parskip} to select - the paragraph mark\label{tab:\ThisCommonFirstLabelBase.parskip}% + [{Available values of option \Option{parskip}}]{% + Available values of option \Option{parskip} to select + how paragraph are + distinguished\label{tab:\ThisCommonFirstLabelBase.parskip}% }% {% - Possible values of option \Option{parskip} (\emph{continuation})% + Available values of option \Option{parskip} (\emph{continuation})% }% % \begin{desctabular} \entry{\PValue{false}, \PValue{off}, \PValue{no}% - \IndexOption{parskip~=\PValue{false}}}{% + \IndexOption{parskip~=\textKValue{false}}}{% paragraph indentation instead of vertical space; the last line of a - paragraph may be arbitrarily filled}% + paragraph can be arbitrarily filled}% \entry{\PValue{full}, \PValue{true}, \PValue{on}, \PValue{yes}% - \IndexOption{parskip~=\PValue{full}}% + \IndexOption{parskip~=\textKValue{full}}% }{% one line vertical space between paragraphs; there must be at least 1\Unit{em} free space in the last line of a paragraph}% \pventry{full-}{% one line vertical space between paragraphs; the last line of a paragraph - may be arbitrarily filled\IndexOption{parskip~=\PValue{full-}}}% + can be arbitrarily filled\IndexOption{parskip~=\textKValue{full-}}}% \pventry{full+}{% one line vertical space between paragraphs; there must be at least a third - of a line free space at the end of a - paragraph\IndexOption{parskip~=\PValue{full+}}}% + of a line of free space at the end of a + paragraph\IndexOption{parskip~=\textKValue{full+}}}% \pventry{full*}{% one line vertical space between paragraphs; there must be at least a - quarter of a line free space at the end of a - paragraph\IndexOption{parskip~=\PValue{full*}}}% + quarter of a line of free space at the end of a + paragraph\IndexOption{parskip~=\textKValue{full*}}}% \pventry{half}{% half a line vertical space between paragraphs; there must be at least 1\Unit{em} free space in the last line of a - paragraph\IndexOption{parskip~=\PValue{half}}}% + paragraph\IndexOption{parskip~=\textKValue{half}}}% \pventry{half-}{% one line vertical space between - paragraphs\IndexOption{parskip~=\PValue{half-}}}% + paragraphs\IndexOption{parskip~=\textKValue{half-}}}% \pventry{half+}{% half a line vertical space between paragraphs; there must be at least a - third of a line free space at the end of a - paragraph\IndexOption{parskip~=\PValue{half+}}}% + third of a line of free space at the end of a + paragraph\IndexOption{parskip~=\textKValue{half+}}}% \pventry{half*}{% half a line vertical space between paragraphs; there must be at least a - quarter of a line free space at the end of a - paragraph\IndexOption{parskip~=\PValue{half+}}}% + quarter of a line of free space at the end of a + paragraph\IndexOption{parskip~=\textKValue{half*}}}% \pventry{never}{% there% \IfThisCommonLabelBase{maincls}{% - \ChangedAt{v3.08}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}}% + \ChangedAt{v3.08}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% }{% \IfThisCommonLabelBase{scrlttr2}{% \ChangedAt{v3.08}{\Class{scrlttr2}}% @@ -221,7 +236,7 @@ paragraph instead of paragraph spacing. All the possible values of option will be no inter-paragraph spacing even if additional vertical spacing is needed for the vertical adjustment with \Macro{flushbottom}\IndexCmd{flushbottom}% - \IndexOption{parskip~=\PValue{never}}}% + \IndexOption{parskip~=\textKValue{never}}}% % \end{desctabular} % \end{table}% \end{desclist}% @@ -229,17 +244,17 @@ paragraph instead of paragraph spacing. All the possible values of option All\textnote{Attention!} eight \PValue{full} and \PValue{half} option values also change the spacing before, after, and inside list environments. This -avoids the problem of these environments or the paragraphs inside them having -a larger separation than the separation between the paragraphs of normal text.% +prevents these environments or the paragraphs inside them from having +a larger separation than that between the paragraphs of normal text.% \IfThisCommonLabelBase{maincls}{ % Additionally, these options ensure that the table of contents and the lists of figures and tables are set without any additional spacing.% }{ % - Several element of the first letter page will be set without inter-paragraph - spacing always.% + Several elements of the letterhead are always set without inter-paragraph + spacing.% }% -The default behaviour of {\KOMAScript} follows +The default\textnote{default} behaviour of \KOMAScript{} is \OptionValue{parskip}{false}. In this case, there is no spacing between paragraphs, only an indentation of the first line by 1\Unit{em}.% % diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-textmarkup.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-textmarkup.tex index 9746ed6ee99..58dd710110a 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-textmarkup.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-textmarkup.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-textmarkup.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % common-textmarkup.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,11 +46,12 @@ % ====================================================================== \KOMAProvidesFile{common-textmarkup.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-21 10:37:34 +0100 (Wed, 21 Mar 2018) $ KOMA-Script guide (common paragraphs)] -\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi} +\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi\and + Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-02-06 \section{Text Markup} \seclabel{textmarkup}% @@ -59,46 +60,57 @@ \BeginIndex{}{font}% \IfThisCommonFirstRun{}{% - What is described in \autoref{sec:\ThisCommonFirstLabelBase.textmarkup} - applies, mutatis mutandis. So if you have alread read and understood - \autoref{sec:\ThisCommonFirstLabelBase.textmarkup.next} you can switch - to \autopageref{sec:\ThisCommonLabelBase.textmarkup.next}.% - \IfThisCommonLabelBaseOneOf{scrextend,scrjura,scrlayer-notecolumn}{}{ % - But you should have a look at + The information in in \autoref{sec:\ThisCommonFirstLabelBase.textmarkup} + largely applies to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.textmarkup.next}, you can + \IfThisCommonLabelBaseOneOf{scrextend,scrjura,scrlayer-notecolumn}{}{% + limit yourself to examining \autoref{tab:\ThisCommonLabelBase.fontelements}, - \autopageref{tab:\ThisCommonLabelBase.fontelements}.% - }% + \autopageref{tab:\ThisCommonLabelBase.fontelements} and then }% + skip ahead to \autoref{sec:\ThisCommonLabelBase.textmarkup.next}, + \autopageref{sec:\ThisCommonLabelBase.textmarkup.next}.% + \IfThisCommonLabelBase{scrextend}{\ In this case, however, + note\textnote{limitation} that \Package{scrextend} supports only the + elements for the document title, the dictum, the footnotes, and the + \DescRef{maincls.env.labeling} environment. from + \autoref{tab:maincls.fontelements}, + \autopageref{tab:maincls.fontelements}. Although the + \DescRef{maincls.fontelement.disposition} element exists, + \Package{scrextend} uses it only for the document title.% + }{}% } -{\LaTeX} offers different possibilities for logical and direct -markup\Index{logical markup}\Index{markup} of text. -Selection of the -font family commands, as well as choosing the font size and width is -supported. More information about the standard font facilities may be found at -\cite{lshort}, \cite{latex:usrguide}, and \cite{latex:fntguide}. - +% Umbruchkorrektur +\IfThisCommonLabelBase{scrlayer-scrpage}{}{% + {\LaTeX} offers different possibilities for logical and direct + markup\Index{logical markup}\Index{markup} of text. % + \IfThisCommonLabelBaseOneOf{scrlttr2}{}{% + In addition to the choice of the font, this includes commands for choosing + the font size and orientation. % + } For more information about the standard font facilities, see + \cite{lshort}, \cite{latex:usrguide}, and \cite{latex:fntguide}.} \IfThisCommonLabelBaseOneOf{scrlayer-scrpage,scrjura,scrlayer-notecolumn}{% \iffalse}{% \csname iftrue\endcsname}% \begin{Declaration} - \Macro{textsuperscript}\Parameter{Text}% - \Macro{textsubscript}\Parameter{Text} + \Macro{textsuperscript}\Parameter{text}% + \Macro{textsubscript}\Parameter{text} \end{Declaration} - The \LaTeX-Kern already defines the command - \Macro{textsuperscript}\IndexCmd{textsuperscript} to - superscript\Index{text>superscript}\Index{superscript} text. Unfortunately, - until release 2015/01/01 {\LaTeX} itself does not offer a command to produce - text in subscript\Index{text>subscript}\Index{subscript} instead of - superscript\Index{text>superscript}\Index{superscript}. {\KOMAScript} - defines \Macro{textsubscript} for this purpose. % + The \LaTeX{} kernel defines the command + \Macro{textsuperscript}\IndexCmd{textsuperscript} to put text in + superscript\Index{text>superscript}\Index{superscript}. Unfortunately, + \LaTeX{}\textnote{\Latex~2015/01/01} itself did not offer a command to + produce text in subscript\Index{text>subscript}\Index{subscript} until + release 2015/01/01. \KOMAScript{} defines \Macro{textsubscript} for this + purpose. % \ifthiscommonfirst \begin{Example} \phantomsection \xmpllabel{cmd.textsubscript}% You are writing a text on human metabolism. From time to time you have to give some simple chemical formulas in which the numbers are - in subscript. For enabling logical markup you first define in the + in subscript. To allow for logical markup, you first define in the document preamble or in a separate package: \begin{lstcode} \newcommand*{\molec}[2]{#1\textsubscript{#2}} @@ -106,16 +118,16 @@ supported. More information about the standard font facilities may be found at \newcommand*{\molec}[2]{#1\textsubscript{#2}} Using this you then write: \begin{lstcode} - The cell produces its energy partly from reaction of \molec C6\molec + The cell produces its energy partly from the reaction of \molec C6\molec H{12}\molec O6 and \molec O2 to produce \molec H2\Molec O{} and - \molec C{}\molec O2. However, arsenic (\molec{As}{}) has a quite + \molec C{}\molec O2. However, arsenic (\molec{As}{}) has quite a detrimental effect on the metabolism. \end{lstcode} The output looks as follows: \begin{ShowOutput} - The cell produces its energy from reaction of \molec C6\molec + The cell produces its energy partly from the reaction of \molec C6\molec H{12}\molec O6 and \molec O2 to produce \molec H2\molec O{} and - \molec C{}\molec O2. However, arsenic (\molec{As}{}) has a quite + \molec C{}\molec O2. However, arsenic (\molec{As}{}) has quite a detrimental effect on the metabolism. \end{ShowOutput} @@ -129,30 +141,31 @@ supported. More information about the standard font facilities may be found at \renewcommand*{\molec}[2]{\textsf{#1\textsubscript{#2}}} Now the output in the whole document changes to: \begin{ShowOutput} - The cell produces its energy partly from reaction of \molec + The cell produces its energy partly from the reaction of \molec C6\molec H{12}\molec O6 and \molec O2 to produce \molec H2\molec O{} and \molec C{}\molec O2. However, arsenic (\molec{As}{}) has - a quite detrimental effect on the metabolism. + quite a detrimental effect on the metabolism. \end{ShowOutput} \end{Example} \iftrue \begin{Explain} - In the example above, the notation ``\verb|\molec C6|'' is used. + The example above uses the notation ``\verb|\molec C6|''. This makes use of the fact that arguments consisting of only one character do not have to be enclosed in parentheses. That is why ``\verb|\molec C6|'' is similar to ``\verb|\molec{C}{6}|''. You - might already know this from indices or powers in mathematical - environments, such as ``\verb|$x^2$|'' instead of ``\verb|$x^{2}$|'' + may already be familiar with this notation from indices or powers in + mathematical environments, such as ``\verb|$x^2$|'' instead of + ``\verb|$x^{2}$|'' for ``$x^2$''. \end{Explain} \else % maybe some time I've made an English book - Experts can find information about the reason why the example above does - work unless putting all arguments of \Macro{molec} into braces in + Advanced users can find information about the reason the example above + does work unless you put all arguments of \Macro{molec} into braces in \autoref{sec:experts.knowhow}, \DescPageRef{experts.macroargs}.% - \fi - \else - You may find an example of usage at + \fi% + \else% + You can find an example that uses it in \autoref{sec:\ThisCommonFirstLabelBase.textmarkup}, \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.textsubscript}. \fi% @@ -165,58 +178,83 @@ supported. More information about the standard font facilities may be found at \Macro{addtokomafont}\Parameter{element}\Parameter{commands}% \Macro{usekomafont}\Parameter{element} \end{Declaration}% -With\ChangedAt{v2.8p}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} the help of the two commands \Macro{setkomafont} and -\Macro{addtokomafont}, it is possible to define the \PName{commands} that -change the characteristics of a given \PName{element}. Theoretically, all -possible statements including literal text could be used as \PName{commands}. -You should\textnote{Attention!}, however, absolutely limit yourself to those -statements that really switch only one font attribute. This will usually be -the commands \Macro{normalfont}, \Macro{rmfamily}, \Macro{sffamily}, -\Macro{ttfamily}, \Macro{mdseries}, \Macro{bfseries}, \Macro{upshape}, -\Macro{itshape}, \Macro{slshape}, and \Macro{scshape}, as well as the font -size commands \Macro{Huge}, \Macro{huge}, \Macro{LARGE}, \Macro{Large}, -\Macro{large}, \Macro{normalsize}, \Macro{small}, \Macro{footnotesize}, -\Macro{scriptsize}, and \Macro{tiny}. The description of these commands can be -found in \cite{lshort}, \cite{latex:usrguide}, or \cite{latex:fntguide}. Color -switching commands like \Macro{normalcolor} (see \cite{package:graphics} and -\cite{package:xcolor}) are also acceptable. The behavior when using other -commands, especially those that make redefinitions or generate output, is not -defined. Strange behavior is possible and does not represent a bug. +With% +\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v2.8p}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{} the help of the \Macro{setkomafont} and \Macro{addtokomafont} +commands, you can attach particular font styling \PName{commands} that change +the appearance of a given \PName{element}. Theoretically, all statements, +including literal text, can be used as \PName{commands}. You +should\textnote{Attention!}, however, limit yourself to those statements that +really change font attributes only. These are usually commands like +\Macro{rmfamily}, \Macro{sffamily}, \Macro{ttfamily}, \Macro{upshape}, +\Macro{itshape}, \Macro{slshape}, \Macro{scshape}, \Macro{mdseries}, +\Macro{bfseries}, \Macro{normalfont}, as well as the font size commands +\Macro{Huge}, \Macro{huge}, \Macro{LARGE}, \Macro{Large}, \Macro{large}, +\Macro{normalsize}, \Macro{small}, \Macro{footnotesize}, \Macro{scriptsize}, +and \Macro{tiny}. You can find these commands explained in \cite{lshort}, +\cite{latex:usrguide}, or \cite{latex:fntguide}. Colour switching commands +like \Macro{normalcolor} (see \cite{package:graphics} and +\cite{package:xcolor}) are also acceptable.% +\iffalse % Umbruchkorrekturtext + \ The behaviour when using other commands, especially those that lead to + redefinitions or generate output, is undefined. Strange behaviour is possible + and does not represent a bug. +\else + \ The use of other commands, in particular those that redefine things or + or lead to output, is not supported. Strange behaviour is possible in these + cases and does not represent a bug. +\fi -The command \Macro{setkomafont} provides a font switching command with a -completely new definition. In contrast to this, the \Macro{addtokomafont} -command merely extends an existing definition. It is recommended to not use -both commands inside the document body, but only in the document preamble. -Usage examples can be found in the paragraphs on the corresponding element.% -\IfThisCommonLabelBaseOneOf{scrjura,scrlayer-notecolumn}{}{% - \ Names\IfThisCommonLabelBase{scrlayer-scrpage}{, defaults,}{} and meanings - of the individual items are listed in % - \IfThisCommonLabelBase{scrextend}{% +The command \Macro{setkomafont} provides an element with a completely new +definition of its font styling. In contrast, the \Macro{addtokomafont} command +merely extends an existing definition. You should not use either command +inside the document body but only in the preamble. For examples of their use, +refer to the sections for the respective element.% +\IfThisCommonLabelBase{scrlayer-notecolumn}{}{% + \ The name and meaning of each element + \IfThisCommonLabelBaseOneOf{scrlayer-scrpage,scrjura}{, as well as their + defaults,}{} are listed in \IfThisCommonLabelBase{scrextend}{% \autoref{tab:maincls.fontelements}, \autopageref{tab:maincls.fontelements} }{% \autoref{tab:\ThisCommonLabelBase.fontelements} % }.% \IfThisCommonLabelBase{scrextend}{ % - However only the listed elements for the document title, dicta, footnotes, - and the \DescRef{maincls.env.labeling} environment are supported. Though - element \DescRef{maincls.fontelement.disposition} exists, it will also be - used for the document title only. This has been done for compatibility - with the \KOMAScript{} classes.% - }{}% - \IfThisCommonLabelBase{scrlayer-scrpage}{}{ % - The default values are shown in the corresponding paragraphs.% + However, in \Package{scrextend} only\textnote{limitation} the listed + elements for the document title, dictum, footnotes, and the + \DescRef{maincls.env.labeling} environment are supported. Although the + \DescRef{maincls.fontelement.disposition} element exists, + \Package{scrextend} uses it only for the document title.% + }{% + \IfThisCommonLabelBase{scrlayer-scrpage}{ % + The specified defaults apply only if the corresponding element has not + already been defined before loading \Package{scrlayer-scrpage}. For + example, the \KOMAScript classes define + \DescRef{maincls.fontelement.pageheadfoot}, and then + \Package{scrlayer-scrpage} uses the setting it finds.% + }{% + \IfThisCommonLabelBase{scrjura}{}{ % + The default values can be found in the corresponding sections.% + }% + }% }% }% -With command \Macro{usekomafont} the current font style may be changed into -the font style of the selected \PName{element}.% +\IfThisCommonLabelBaseOneOf{scrlttr2,scrextend}{% Umbruchvarianten + The \Macro{usekomafont} command can be used to switch the current font style + to the specified \PName{Element}.% +}{% + With the \Macro{usekomafont} command, the current font style can be changed + to the one defined for the specified \PName{element}.% +} + \IfThisCommonLabelBase{maincls}{\iftrue}{\csname iffalse\endcsname} \begin{Example} \phantomsection\xmpllabel{cmd.setkomafont}% - Assume that you want to use for the element - \DescRef{\ThisCommonLabelBase.fontelement.captionlabel} the same font - specification that is used with + Suppose you want to use the same font specification for the element + \DescRef{\ThisCommonLabelBase.fontelement.captionlabel} + that is used with \DescRef{\ThisCommonLabelBase.fontelement.descriptionlabel}. This can be easily done with: \begin{lstcode} @@ -224,86 +262,92 @@ the font style of the selected \PName{element}.% \usekomafont{descriptionlabel}% } \end{lstcode} - You can find other examples in the paragraphs on each element. + You can find other examples in the explanation of each element. \end{Example} \begin{desclist} \desccaption{% - Elements whose type style can be changed with the {\KOMAScript} command - \Macro{setkomafont} or + Elements whose font style can be changed in \Class{scrbook}, + \Class{scrreprt} or \Class{scrartcl} with \Macro{setkomafont} and \Macro{addtokomafont}% \label{tab:maincls.fontelements}% \label{tab:scrextend.fontelements}% }{% - Elements whose type style can be changed (\emph{continuation})% + Elements whose font style can be changed (\emph{continued})% }% \feentry{author}{% \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}\and \Package{scrextend}}% - author of the document on the main title, i.\,e., the argument of + author of the document in the title, i.\,e., the argument of \DescRef{\ThisCommonLabelBase.cmd.author} when - \DescRef{\ThisCommonLabelBase.cmd.maketitle} will be used (see + \DescRef{\ThisCommonLabelBase.cmd.maketitle} is used (see \autoref{sec:maincls.titlepage}, \DescPageRef{maincls.cmd.author})}% - \feentry{caption}{text of a table or figure caption (see - \autoref{sec:maincls.floats}, \DescPageRef{maincls.cmd.caption})}% - \feentry{captionlabel}{label of a table or figure caption; used according - to the element \DescRef{\ThisCommonLabelBase.fontelement.caption} (see + \feentry{caption}{text of a figure or table caption (see \autoref{sec:maincls.floats}, \DescPageRef{maincls.cmd.caption})}% - \feentry{chapter}{title of the sectional unit + \feentry{captionlabel}{label of a figure or table caption; applied in + addition to the \DescRef{\ThisCommonLabelBase.fontelement.caption} + element (see \autoref{sec:maincls.floats}, + \DescPageRef{maincls.cmd.caption})}% + \feentry{chapter}{title of the sectioning command \DescRef{\ThisCommonLabelBase.cmd.chapter} (see \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.chapter})}% \feentry{chapterentry}{% - table of contents entry of the sectional unit + table of contents entry for the sectioning command \DescRef{\ThisCommonLabelBase.cmd.chapter} (see \autoref{sec:maincls.toc}, \DescPageRef{maincls.cmd.tableofcontents})}% + \feentry{chapterentrydots}{% + \ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}}% + optional points connecting table-of-content entries for the + \DescRef{\ThisCommonLabelBase.cmd.chapter} level, differing from the + \DescRef{\ThisCommonLabelBase.fontelement.chapterentrypagenumber} + element (see \autoref{sec:maincls.toc}, + \DescPageRef{maincls.cmd.tableofcontents})}% \feentry{chapterentrypagenumber}{% - page number of the table of contents entry of the sectional unit - \DescRef{\ThisCommonLabelBase.cmd.chapter}, variation on the element + page number of the table of contents entry for the sectioning command + \DescRef{\ThisCommonLabelBase.cmd.chapter}, differing from the element \DescRef{\ThisCommonLabelBase.fontelement.chapterentry} (see \autoref{sec:maincls.toc}, \DescPageRef{maincls.cmd.tableofcontents})}% \feentry{chapterprefix}{% - chapter number line at setting - \OptionValueRef{maincls}{chapterprefix}{true} or + label, e.\,g., ``Chapter'', appearing before the chapter number in both + \OptionValueRef{maincls}{chapterprefix}{true} and \OptionValueRef{maincls}{appendixprefix}{true} (see \autoref{sec:maincls.structure}, \DescPageRef{maincls.option.chapterprefix})}% \feentry{date}{% \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}\and \Package{scrextend}}% - date of the document on the main title, i.\,e., the argument of + date of the document in the main title, i.\,e., the argument of \DescRef{\ThisCommonLabelBase.cmd.date} when - \DescRef{\ThisCommonLabelBase.cmd.maketitle} will be used (see + \DescRef{\ThisCommonLabelBase.cmd.maketitle} is used (see \autoref{sec:maincls.titlepage}, \DescPageRef{maincls.cmd.date})}% \feentry{dedication}{% \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}\and \Package{scrextend}}% dedication page after the main title, i.\,e., the argument of \DescRef{\ThisCommonLabelBase.cmd.dedication} when - \DescRef{\ThisCommonLabelBase.cmd.maketitle} will be used (see + \DescRef{\ThisCommonLabelBase.cmd.maketitle} is used (see \autoref{sec:maincls.titlepage}, \DescPageRef{maincls.cmd.dedication})}% \feentry{descriptionlabel}{labels, i.\,e., the optional argument of \DescRef{\ThisCommonLabelBase.cmd.item.description} in the \DescRef{\ThisCommonLabelBase.env.description} environment (see \autoref{sec:maincls.lists}, \DescPageRef{maincls.env.description})}% - \feentry{dictum}{dictum, wise saying, or smart slogan (see - \autoref{sec:maincls.dictum}, \DescPageRef{maincls.cmd.dictum})}% - \feentry{dictumauthor}{author of a dictum, wise saying, or smart slogan; - used according to the element - \DescRef{\ThisCommonLabelBase.fontelement.dictum} (see + \feentry{dictum}{dictum or epigraph (see \autoref{sec:maincls.dictum}, + \DescPageRef{maincls.cmd.dictum})}% + \feentry{dictumauthor}{author of a dictum or epigraph; applied in addition + to the element \DescRef{\ThisCommonLabelBase.fontelement.dictum} (see \autoref{sec:maincls.dictum}, \DescPageRef{maincls.cmd.dictum})}% - \feentry{dictumtext}{another name for + \feentry{dictumtext}{alternative name for \DescRef{\ThisCommonLabelBase.fontelement.dictum}}% - \feentry{disposition}{all sectional unit titles, i.\,e., the arguments of - \DescRef{\ThisCommonLabelBase.cmd.part} down to + \feentry{disposition}{all sectioning command titles, i.\,e., the arguments + of \DescRef{\ThisCommonLabelBase.cmd.part} down to \DescRef{\ThisCommonLabelBase.cmd.subparagraph} and \DescRef{\ThisCommonLabelBase.cmd.minisec}, including the title of the - abstract; used before the element of the corresponding unit (see - \autoref{sec:maincls.structure} ab - \autopageref{sec:maincls.structure})}% + abstract; applied before the element of the respective unit (see + \autoref{sec:maincls.structure}, \autopageref{sec:maincls.structure})}% \feentry{footnote}{footnote text and marker (see \autoref{sec:maincls.footnotes}, \DescPageRef{maincls.cmd.footnote})}% - \feentry{footnotelabel}{mark of a footnote; used according to the element - \DescRef{\ThisCommonLabelBase.fontelement.footnote} (see + \feentry{footnotelabel}{marker for a footnote; applied in addition to the + element \DescRef{\ThisCommonLabelBase.fontelement.footnote} (see \autoref{sec:maincls.footnotes}, \DescPageRef{maincls.cmd.footnote})}% \feentry{footnotereference}{footnote reference in the text (see \autoref{sec:maincls.footnotes}, \DescPageRef{maincls.cmd.footnote})}% @@ -317,8 +361,8 @@ the font style of the selected \PName{element}.% \DescRef{\ThisCommonLabelBase.env.labeling} environment (see \autoref{sec:maincls.lists}, \DescPageRef{maincls.env.labeling})}% \feentry{labelingseparator}{separator, i.\,e., the optional argument of - the \DescRef{\ThisCommonLabelBase.env.labeling} environment; used - according to the element + the \DescRef{\ThisCommonLabelBase.env.labeling} environment; applied in + addition to the element \DescRef{\ThisCommonLabelBase.fontelement.labelinglabel} (see \autoref{sec:maincls.lists}, \DescPageRef{maincls.env.labeling})}% \feentry{minisec}{title of \DescRef{\ThisCommonLabelBase.cmd.minisec} (see @@ -326,68 +370,68 @@ the font style of the selected \PName{element}.% \feentry{pagefoot}{only used if package \Package{scrlayer-scrpage} has been loaded (see \autoref{cha:scrlayer-scrpage}, \DescPageRef{scrlayer-scrpage.fontelement.pagefoot})}% - \feentry{pagehead}{another name for + \feentry{pagehead}{alternative name for \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot}}% - \feentry{pageheadfoot}{the head of a page, but also the foot of a page - (see \autoref{sec:maincls.pagestyle} ab + \feentry{pageheadfoot}{the header and footer of a page (see + \autoref{sec:maincls.pagestyle} from \autopageref{sec:maincls.pagestyle})}% \feentry{pagenumber}{page number in the header or footer (see \autoref{sec:maincls.pagestyle})}% - \feentry{pagination}{another name for + \feentry{pagination}{alternative name for \DescRef{\ThisCommonLabelBase.fontelement.pagenumber}}% - \feentry{paragraph}{title of the sectional unit + \feentry{paragraph}{title of the sectioning command \DescRef{\ThisCommonLabelBase.cmd.paragraph} (see \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.paragraph})}% \feentry{part}{title of the \DescRef{\ThisCommonLabelBase.cmd.part} - sectional unit, without the line containing the part number (see + sectioning command, without the line containing the part number (see \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.part})}% \feentry{partentry}{% - table of contents entry of the sectional unit + table of contents entry for the sectioning command \DescRef{\ThisCommonLabelBase.cmd.part} (see \autoref{sec:maincls.toc}, \DescPageRef{maincls.cmd.tableofcontents})}% \feentry{partentrypagenumber}{% - Page number of the table of contents entry of the sectional unit - \DescRef{\ThisCommonLabelBase.cmd.part} variation on the element - \DescRef{\ThisCommonLabelBase.fontelement.partentry} (see + page number of the table of contents entry for the sectioning command + \DescRef{\ThisCommonLabelBase.cmd.part}; applied in addition to the + element \DescRef{\ThisCommonLabelBase.fontelement.partentry} (see \autoref{sec:maincls.toc}, \DescPageRef{maincls.cmd.tableofcontents})}% \feentry{partnumber}{line containing the part number in a title of the - sectional unit \DescRef{\ThisCommonLabelBase.cmd.part} (see + sectioning command \DescRef{\ThisCommonLabelBase.cmd.part} (see \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.part})}% \feentry{publishers}{% \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}\and \Package{scrextend}}% - publishers of the document on the main title, i.\,e., the argument of + publishers of the document in the main title, i.\,e., the argument of \DescRef{\ThisCommonLabelBase.cmd.publishers} when - \DescRef{\ThisCommonLabelBase.cmd.maketitle} will be used (see + \DescRef{\ThisCommonLabelBase.cmd.maketitle} is used (see \autoref{sec:maincls.titlepage}, \DescPageRef{maincls.cmd.publishers})}% - \feentry{section}{title of the sectional unit + \feentry{section}{title of the sectioning command \DescRef{\ThisCommonLabelBase.cmd.section} (see \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.section})}% \feentry{sectionentry}{% - table of contents entry of sectional unit + table of contents entry for sectioning command \DescRef{\ThisCommonLabelBase.cmd.section} (only available in \Class{scrartcl}, see \autoref{sec:maincls.toc}, \DescPageRef{maincls.cmd.tableofcontents})}% \feentry{sectionentrypagenumber}{% - page number of the table of contents entry of the sectional unit - \DescRef{\ThisCommonLabelBase.cmd.section}, variation on element - \DescRef{\ThisCommonLabelBase.fontelement.sectionentry} (only available - in \Class{scrartcl, see \autoref{sec:maincls.toc}, + page number of the table of contents entry for the sectioning command + \DescRef{\ThisCommonLabelBase.cmd.section}; applied in addition to + element \DescRef{\ThisCommonLabelBase.fontelement.sectionentry} (only + available in \Class{scrartcl, see \autoref{sec:maincls.toc}, \DescPageRef{maincls.cmd.tableofcontents}})}% - \feentry{sectioning}{another name for + \feentry{sectioning}{alternative name for \DescRef{\ThisCommonLabelBase.fontelement.disposition}}% \feentry{subject}{% - categorization of the document, i.\,e., the argument of + topic of the document, i.\,e., the argument of \DescRef{\ThisCommonLabelBase.cmd.subject} on the main title page (see \autoref{sec:maincls.titlepage}, \DescPageRef{maincls.cmd.subject})}% - \feentry{subparagraph}{title of the sectional unit + \feentry{subparagraph}{title of the sectioning command \DescRef{\ThisCommonLabelBase.cmd.subparagraph} (see \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.subparagraph})}% - \feentry{subsection}{title of the sectional unit + \feentry{subsection}{title of the sectioning command \DescRef{\ThisCommonLabelBase.cmd.subsection} (see \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.subsection})}% - \feentry{subsubsection}{title of the sectional unit + \feentry{subsubsection}{title of the sectioning command \DescRef{\ThisCommonLabelBase.cmd.subsubsection} (see \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.subsubsection})}% @@ -402,112 +446,122 @@ the font style of the selected \PName{element}.% \feentry{titlehead}{% \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}\and \Package{scrextend}}% - head above the main title of the document, i.\,e., the argument of + heading above the main title of the document, i.\,e., the argument of \DescRef{\ThisCommonLabelBase.cmd.titlehead} when - \DescRef{\ThisCommonLabelBase.cmd.maketitle} will be used (see + \DescRef{\ThisCommonLabelBase.cmd.maketitle} is used (see \autoref{sec:maincls.titlepage}, \DescPageRef{maincls.cmd.titlehead})}% \end{desclist} \else \IfThisCommonLabelBase{scrextend}{\iftrue}{\csname iffalse\endcsname} \begin{Example} - Assumed, you want to print the document title in a serif font and with - red colour. You may do this using: + Suppose you want to print the document title in a red serif font. + You can do this using: \begin{lstcode} \setkomafont{title}{\color{red}} \end{lstcode} - Package \Package{color} or \Package{xcolor} will be needed for command - \Macro{color}\PParameter{red}. The additional usage of - \Macro{normalfont} is not needed in this case, because it is already - part of the definition of the title itself. This\textnote{Attention!} - example also needs option - \OptionValueRef{scrextend}{extendedfeature}{title} (see + You will need the \Package{color} or the \Package{xcolor} package for + the \Macro{color}\PParameter{red} command. Using \Macro{normalfont} is + unnecessary in this case because it is already part of the definition of + the title itself. This\textnote{Attention!} example also needs the + \OptionValueRef{scrextend}{extendedfeature}{title} option (see \autoref{sec:scrextend.optionalFeatures}, \DescPageRef{scrextend.option.extendedfeature}). \end{Example} \else \IfThisCommonLabelBase{scrlttr2}{% - A general example for the usage of \Macro{setkomafont} and - \Macro{usekomafont} may be found in \autoref{sec:maincls.textmarkup} at + You can find a general example that uses both \Macro{setkomafont} and + \Macro{usekomafont} in \autoref{sec:maincls.textmarkup} on \PageRefxmpl{maincls.cmd.setkomafont}. \begin{desclist} \desccaption{% - Alphabetical list of elements whose font can be changed in - \Class{scrlttr2} using the commands \Macro{setkomafont} and - \Macro{addtokomafont}\label{tab:scrlttr2.fontelements}% + Elements whose font style can be changed in the \Class{scrlttr2} + class or the \Package{scrletter} package with the + \Macro{setkomafont} and \Macro{addtokomafont} + commands\label{tab:scrlttr2.fontelements}% }{% - Elements whose font can be changed (\emph{continuation})% + Elements whose font style can be changed (\emph{continued})% }% - \feentry{addressee}{name und address in address field % + \feentry{addressee}{recipient's name and address in the address field (\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.addrfield})}% \feentry{backaddress}{% - return address for a window envelope % + return address for a window envelope (\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.backaddress})}% \feentry{descriptionlabel}{% - label, i.\,e., the optional argument of + label, i.\,e. the optional argument of \DescRef{\ThisCommonLabelBase.cmd.item.description}, in a - \DescRef{\ThisCommonLabelBase.env.description} environment % + \DescRef{\ThisCommonLabelBase.env.description} environment (\autoref{sec:scrlttr2.lists}, \DescPageRef{scrlttr2.env.description})}% \feentry{foldmark}{% - foldmark on the letter page; intended for color settings % + fold mark on the letterhead page; allows change of line colour (\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.foldmarks})}% \feentry{footnote}{% - footnote text and marker % - (see \autoref{sec:scrlttr2.footnotes}, + footnote text and marker (\autoref{sec:scrlttr2.footnotes}, \DescPageRef{scrlttr2.cmd.footnote})}% \feentry{footnotelabel}{% - mark of a footnote; used according to the element - \DescRef{\ThisCommonLabelBase.fontelement.footnote} % - (see \autoref{sec:scrlttr2.footnotes}, + footnote marker; applied in addition to the + \DescRef{\ThisCommonLabelBase.fontelement.footnote} element + (\autoref{sec:scrlttr2.footnotes}, \DescPageRef{scrlttr2.cmd.footnote})}% \feentry{footnotereference}{% - footnote reference in the text % - (see \autoref{sec:scrlttr2.footnotes}, + footnote reference in the text (\autoref{sec:scrlttr2.footnotes}, \DescPageRef{scrlttr2.cmd.footnote})}% \feentry{footnoterule}{% horizontal rule\ChangedAt{v3.07}{\Class{scrlttr2}} above the - footnotes at the end of the text area % - (see \autoref{sec:maincls.footnotes}, + footnotes at the end of the text area + (\autoref{sec:maincls.footnotes}, \DescPageRef{maincls.cmd.setfootnoterule})}% + \feentry{fromaddress}{% + sender's address in the letterhead + (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.variable.fromaddress})}% + \feentry{fromname}{% + sender's name in the letterhead, not including + \PValue{fromaddress} (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.variable.fromname})}% + \feentry{fromrule}{% + horizontal rule in the letterhead; intended for + colour changes (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.option.fromrule})}% \feentry{labelinglabel}{% - labels, i.\,e., the optional argument of + labels, i.\,e. the optional argument of \DescRef{\ThisCommonLabelBase.cmd.item.labeling} in the \DescRef{\ThisCommonLabelBase.env.labeling} environment % (see \autoref{sec:scrlttr2.lists}, \DescPageRef{scrlttr2.env.labeling})}% \feentry{labelingseparator}{% - separator, i.\,e., the optional argument of the - \DescRef{\ThisCommonLabelBase.env.labeling} environment; used - according to the element - \DescRef{\ThisCommonLabelBase.fontelement.labelinglabel} % + separator, i.\,e. the optional argument of the + \DescRef{\ThisCommonLabelBase.env.labeling} environment; applied + in addition to the + \DescRef{\ThisCommonLabelBase.fontelement.labelinglabel} element (see \autoref{sec:scrlttr2.lists}, \DescPageRef{scrlttr2.env.labeling})}% \feentry{pagefoot}{% - used after element - \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot} for the page - foot, that has been defined with variable - \DescRef{scrlttr2.variable.nextfoot}\IndexVariable{nextfoot}, or for - the page foot of package \Package{scrlayer-scrpage} % - (\autoref{cha:scrlayer-scrpage}, + used after the + \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot} element for + the footer defined with the + \DescRef{scrlttr2.variable.nextfoot}\IndexVariable{nextfoot} + variable, or for the footer of the \Package{scrlayer-scrpage} + package (\autoref{cha:scrlayer-scrpage}, \DescPageRef{scrlayer-scrpage.fontelement.pagefoot})}% \feentry{pagehead}{% - another name for + alternative name for \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot}}% \feentry{pageheadfoot}{% - the head of a page, but also the foot of a page at all page style, - that has been defined using \KOMAScript{} % - (see \autoref{sec:scrlttr2.pagestyle}, - \DescPageRef{scrlttr2.fontelement.pageheadfoot})}% + the header and footer of a page for all page styles + that have been defined using \KOMAScript{} + (\autoref{sec:maincls.pagestyle}, + \DescPageRef{\ThisCommonLabelBase.fontelement.pageheadfoot})}% \feentry{pagenumber}{% page number in the header or footer % - (see \autoref{sec:scrlttr2.pagestyle}, - \DescPageRef{scrlttr2.fontelement.pagenumber})}% + (\autoref{sec:maincls.pagestyle}, + \DescPageRef{\ThisCommonLabelBase.fontelement.pagenumber})}% \feentry{pagination}{% - another name for + alternative name for \DescRef{\ThisCommonLabelBase.fontelement.pagenumber}}% \feentry{placeanddate}{% \ChangedAt{v3.12}{\Class{scrlttr2}}% @@ -523,7 +577,7 @@ the font style of the selected \PName{element}.% (\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.variable.yourref})}% \feentry{specialmail}{% - mode of dispatch in the address field % + delivery type in the address field % (\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.variable.specialmail})}% \feentry{lettersubject}{% @@ -537,109 +591,154 @@ the font style of the selected \PName{element}.% (\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.variable.title})}% \feentry{toaddress}{% - variation of the element - \DescRef{\ThisCommonLabelBase.fontelement.addressee} for setting the - addressee address (less the name) in the address field % - (\autoref{sec:scrlttr2.firstpage}, + variation of the + \DescRef{\ThisCommonLabelBase.fontelement.addressee} element to + format the recipient's address, not including the name, in the + address field (\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.variable.toaddress})}% \feentry{toname}{% - variation of the element - \DescRef{\ThisCommonLabelBase.fontelement.addressee} for the name - (only) of the addressee in the address field % + variation of the + \DescRef{\ThisCommonLabelBase.fontelement.addressee} element to + format the recipient's name in the address field (\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.variable.toname})}% \end{desclist} }{% \IfThisCommonLabelBase{scrlayer-scrpage}{% \begin{desclist} - \desccaption[{Elements of \Package{scrlayer-scrpage} whose type - style can be changed with \KOMAScript{} command - \Macro{setkomafont} or \Macro{addtokomafont}}]% - {Elements of \Package{scrlayer-scrpage} whose type style can be - changed with \KOMAScript{} command \Macro{setkomafont} or - \Macro{addtokomafont} and the default of those, if they have not - been defined before loading \Package{scrlayer-scrpage}% + \desccaption[{Elements of \Package{scrlayer-scrpage} whose font + styles can be changed with the \Macro{setkomafont} and + \Macro{addtokomafont} commands}]% + {Elements of \Package{scrlayer-scrpage} whose font styles can be + changed with the \Macro{setkomafont} and \Macro{addtokomafont} + commands, and their defaults, if they have not been defined + before loading \Package{scrlayer-scrpage}% \label{tab:scrlayer-scrpage.fontelements}% }% - {Elements whose type style can be changed (\emph{continuation})}% + {Elements whose font style can be changed (\emph{continued})}% \feentry{footbotline}{% - Horizontal line below the footer of a page style defined using - \Package{scrlayer-scrpage}. The font will be used after + horizontal line below the footer of a page style defined using + \Package{scrlayer-scrpage}. The font will be applied after \Macro{normalfont}\IndexCmd{normalfont} and the fonts of elements \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot}% \IndexFontElement{pageheadfoot} and \DescRef{\ThisCommonLabelBase.fontelement.pagefoot}% \IndexFontElement{pagefoot}. It is recommended to use this element for colour changes only.\par - Default: \emph{empty}% + \mbox{Default: \emph{empty}}% }% \feentry{footsepline}{% - Horizontal line above the footer of a page style defined using - \Package{scrlayer-scrpage}. The font will be used after + horizontal line above the footer of a page style defined using + \Package{scrlayer-scrpage}. The font will be applied after \Macro{normalfont}\IndexCmd{normalfont} and the fonts of elements \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot}% \IndexFontElement{pageheadfoot} and \DescRef{\ThisCommonLabelBase.fontelement.pagefoot}% \IndexFontElement{pagefoot}. It is recommended to use this element for colour changes only.\par - Default: \emph{empty}% + \mbox{Default: \emph{empty}}% }% \feentry{headsepline}{% - Horizontal line below the header of a page style defined using - \Package{scrlayer-scrpage}. The font will be used after + horizontal line below the header of a page style defined using + \Package{scrlayer-scrpage}. The font will be applied after \Macro{normalfont}\IndexCmd{normalfont} and the fonts of elements \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot}% \IndexFontElement{pageheadfoot} and - \DescRef{\ThisCommonLabelBase.fontelement.pagehead}% + \DescRef{scrlayer-scrpage.fontelement.pagehead}% \IndexFontElement{pagehead}. It is recommended to use this element for colour changes only.\par Default: \emph{empty}% }% \feentry{headtopline}{% - Horizontal line above the header of a page style defined using - \Package{scrlayer-scrpage}. The font will be used after + horizontal line above the header of a page style defined using + \Package{scrlayer-scrpage}. The font will be applied after \Macro{normalfont}\IndexCmd{normalfont} and the fonts of elements \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot}% \IndexFontElement{pageheadfoot} and - \DescRef{\ThisCommonLabelBase.fontelement.pagehead}% + \DescRef{scrlayer-scrpage.fontelement.pagehead}% \IndexFontElement{pagehead}. It is recommended to use this element for colour changes only.\par - Default: \emph{empty}% + \mbox{Default: \emph{empty}}% }% \feentry{pagefoot}{% - Contents of the page footer of a page style defined using - \Package{scrlayer-scrpage}. The font will be used after + contents of the page footer of a page style defined using + \Package{scrlayer-scrpage}. The font will be applied after \Macro{normalfont}\IndexCmd{normalfont} and the font of element \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot}% \IndexFontElement{pageheadfoot}.\par - Default: \emph{empty}% + \mbox{Default: \emph{empty}}% }% \feentry{pagehead}{% - Contents of the page header of a page style defined using - \Package{scrlayer-scrpage}. The font will be used after + contents of the page header of a page style defined using + \Package{scrlayer-scrpage}. The font will be applied after \Macro{normalfont}\IndexCmd{normalfont} and the font of element \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot}% \IndexFontElement{pageheadfoot}.\par - Default: \emph{empty}% + \mbox{Default: \emph{empty}}% }% \feentry{pageheadfoot}{% - Contents of the page header or footer of a page style defined - using \Package{scrlayer-scrpage}. The font will be used after + contents of the page header or footer of a page style defined + using \Package{scrlayer-scrpage}. The font will be applied after \Macro{normalfont}\IndexCmd{normalfont}.\par - Default: \Macro{normalcolor}\Macro{slshape}% + \mbox{Default: \Macro{normalcolor}\Macro{slshape}}% }% \feentry{pagenumber}{% - Pagination set with + pagination set with \DescRef{\ThisCommonLabelBase.cmd.pagemark}. If you redefine - \DescRef{\ThisCommonLabelBase.cmd.pagemark}, you have to take care + \DescRef{\ThisCommonLabelBase.cmd.pagemark}, you have to be sure that your redefinition also uses \Macro{usekomafont}\PParameter{pagenumber}!\par - Default: \Macro{normalfont}% + \mbox{Default: \Macro{normalfont}}% }% \end{desclist} }{% - \IfThisCommonLabelBaseOneOf{scrjura,scrlayer-notecolumn}{}{% - \InternalCommonFileUsageError% + \IfThisCommonLabelBase{scrjura}{% + \begin{table} + \caption{Elements whose \Package{scrjura} font styles can be + changed with \Macro{setkomafont} and \Macro{addtokomafont}, + including their default settings}% + \label{tab:scrjura.fontelements}% + \begin{desctabular} + \feentry{Clause}{% + alias for \FontElement{\PName{environment name}.Clause} + within a contract environment, for example + \FontElement{contract.Clause} within + \DescRef{\ThisCommonLabelBase.env.contract}; if no + corresponding element is defined, + \FontElement{contract.Clause} is used% + }% + \feentry{contract.Clause}{% + heading of a paragraph within + \DescRef{\ThisCommonLabelBase.env.contract} (see + \autoref{sec:\ThisCommonLabelBase.contract}, + \DescPageRef{\ThisCommonLabelBase.fontelement.contract.Clause}); + \par + \mbox{Default: \Macro{sffamily}\Macro{bfseries}\Macro{large}}% + }% + \entry{\DescRef{\ThisCommonLabelBase.fontelement./Name/.Clause}}{% + \IndexFontElement[indexmain]{\PName{name}.Clause}% + heading of a paragraph within a \PName{name} environment + defined with + \DescRef{\ThisCommonLabelBase.cmd.DeclareNewJuraEnvironment} + as long as the setting was made with \Option{ClauseFont} or + the item was subsequently defined (see + \autoref{sec:\ThisCommonLabelBase.newenv}, + \DescPageRef{\ThisCommonLabelBase.fontelement./Name/.Clause}); + \par + \mbox{Default: \emph{none}}% + }% + \feentry{parnumber}{% + paragraph numbers within a contract environment (see + \autoref{sec:\ThisCommonLabelBase.par}, + \DescPageRef{\ThisCommonLabelBase.fontelement.parnumber});\par + \mbox{Default: \emph{empty}}% + }% + \end{desctabular} + \end{table} + }{% + \IfThisCommonLabelBase{scrlayer-notecolumn}{}{% + \InternalCommonFileUsageError% + }% }% }% }% @@ -657,23 +756,34 @@ the font style of the selected \PName{element}.% \Macro{useshapeofkomafont}\Parameter{element} \end{Declaration} Sometimes\ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}\and \Package{scrextend}} and despite the recommendation -users use the font setting feature of elements not only for font settings but -for other settings too. In this case it may be useful to switch only to the -font setting of an element but not to those other settings. You may use -\Macro{usefontofkomafont} in such cases. This will activate the font size and -baseline skip, the font encoding, the font family, the font series, and the -font shape of an element, but no further settings as long as those further -settings are local. - -You may also switch to one of those attributes only using one of the other -commands. Note, that \Macro{usesizeofkomafont} will activate both, the font -size and the baseline skip. + \Class{scrartcl}\and \Package{scrextend}}, although this is not recommended, +the font setting of an element is used for settings that are not actually +related to the font. If you want to apply only the font setting of an element +but not those other settings, you can use \Macro{usefontofkomafont} instead of +\DescRef{\ThisCommonLabelBase.cmd.usekomafont}. This will activate the font +size and baseline skip, the font encoding, the font family, the font series, +and the font shape of an element, but no further settings as long as those +further settings are local. -You should not misunderstand these commands as a legitimation of using all -kind of commands at the font setting of an element. Hence this would result -in errors sooner or later (see \autoref{sec:maincls-experts.experts}, -\DescPageRef{maincls-experts.cmd.addtokomafontrelaxlist}).% +You can also switch to a single one of those attributes using one of the other +commands. Note that \Macro{usesizeofkomafont} uses both the font +size and the baseline skip.% +% +\IfThisCommonLabelBase{scrextend}{% Umbruchvariante! +}{% + \IfThisCommonLabelBase{scrjura}{% + \par% + However, the misuse of the font settings is strongly discouraged (see + \autoref{sec:maincls-experts.experts}, + \DescPageRef{maincls-experts.cmd.addtokomafontrelaxlist})!% + }{% + \par% + However, you should not take these commands as legitimizing the insertion + of arbitrary commands in an element's font setting. To do so can lead + quickly to errors (see \autoref{sec:maincls-experts.experts}, + \DescPageRef{maincls-experts.cmd.addtokomafontrelaxlist}).% + }% +}% \EndIndexGroup % \EndIndexGroup @@ -685,5 +795,3 @@ in errors sooner or later (see \autoref{sec:maincls-experts.experts}, %%% ispell-local-dictionary: "en_GB" %%% TeX-master: "../guide" %%% End: - -% LocalWords: mutatis mutandis diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-titles.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-titles.tex index 5f178c218c5..e0617438062 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-titles.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-titles.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-titles.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % common-titles.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,88 +46,94 @@ % ====================================================================== \KOMAProvidesFile{common-titles.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (common paragraphs)] -\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi} +\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi\and + Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-01-30 \section{Document Titles} \seclabel{titlepage}% \BeginIndexGroup \BeginIndex{}{title}% -\BeginIndex{}{document>title}% \IfThisCommonFirstRun{}{% - What is written in \autoref{sec:\ThisCommonFirstLabelBase.titlepage} - applies, mutatis mutandis. So if you have alread read and understood - \autoref{sec:\ThisCommonFirstLabelBase.titlepage} you can jump to - \autoref{sec:\ThisCommonLabelBase.titlepage.next} on + This information in \autoref{sec:\ThisCommonFirstLabelBase.titlepage} + largely applies to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.titlepage}, you can skip to + \autoref{sec:\ThisCommonLabelBase.titlepage.next}, \autopageref{sec:\ThisCommonLabelBase.titlepage.next}.% }% \IfThisCommonLabelBase{scrextend}{\iftrue}{\csname iffalse\endcsname}% - \ But there's a difference: The\textnote{Attention!} document title - capabilities of \Package{scrextend} are part of the optional, advanced + \ However,\textnote{Attention!} the capabilities of \Package{scrextend} + for handling the document title are part of the optional, advanced features. Therfore they are only available, if - \OptionValueRef{\ThisCommonLabelBase}{extendedfeature}{title} has been + \OptionValueRef{\ThisCommonLabelBase}{extendedfeature}{title} is selected while loading the package (see \autoref{sec:\ThisCommonLabelBase.optionalFeatures}, \DescRef{\ThisCommonLabelBase.option.extendedfeature}). - Beyond that \Package{scrextend} cannot be used with a \KOMAScript{} - class together. Because of this + Furthermore, \Package{scrextend} cannot be used with a \KOMAScript{} + class. Because of this, you should replace \begin{lstcode} \documentclass{scrbook} \end{lstcode} - must be replaced by + with \begin{lstcode} \documentclass{book} \usepackage[extendedfeature=title]{scrextend} \end{lstcode} - at all examples from \autoref{sec:maincls.titlepage}, if \Package{scrextend} - should be used. + for all examples from \autoref{sec:maincls.titlepage}, if you want to + try them with \Package{scrextend}. \fi -In general we distinguish two kinds of document titles. First known are title -pages. In this case the document title will be placed together with additional -document information, like the author, on a page of its own. Besides the main -title page, several further title pages may exist, like the half-title or -bastard title, publisher data, dedication, or similar. The second known kind -of document title is the in-page title. In this case, the document title is -placed at the top of a page and specially emphasized, and may be accompanied -by some additional information too, but it will be followed by more material -in the same page, for instance by an abstract, or the table of contents, or -even a section. +In general, we distinguish two kinds of document titles. First, there are +title pages. These include title of the document, together with additional +information such as the author, on a separate page. In addition to the main +title page, there may be several other title pages, such as the half-title or +bastard title, publisher data, dedication, and so on. Second, there is the +in-page title. This kind of title appears at the top of a new page, usually +the first, and is specially emphasized. It too may be accompanied by +additional information, but it will be followed by more material on the same +page, for example by an abstract, the table of contents, or even a section. \begin{Declaration} \OptionVName{titlepage}{simple switch}% \OptionValue{titlepage}{firstiscover} + \Macro{coverpagetopmargin} + \Macro{coverpageleftmargin} + \Macro{coverpagerightmargin} + \Macro{coverpagebottommargin} \end{Declaration}% -Using \DescRef{\ThisCommonLabelBase.cmd.maketitle} (see -\DescPageRef{\ThisCommonLabelBase.cmd.maketitle}), this option% -\IfThisCommonLabelBase{maincls}{% - \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}}% -}{} switches between document title pages\Index{title>pages} and in-page -title\Index{title>in-page}. For \PName{simple switch}, any value from -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} may be used. - -The option -\OptionValue{titlepage}{true}\important{\OptionValue{titlepage}{true}} -\IfThisCommonLabelBase{scrextend}{}{or \Option{titlepage} }makes {\LaTeX} use -separate pages for the titles. Command -\DescRef{\ThisCommonLabelBase.cmd.maketitle} sets these pages inside a -\DescRef{\ThisCommonLabelBase.env.titlepage} environment and the pages -normally have neither header nor footer. In comparison with standard {\LaTeX}, -{\KOMAScript} expands the handling of the titles significantly. - -The option +This option\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{} determines whether to use document title pages\Index{title>pages} or +in-page titles\Index{title>in-page} when using +\DescRef{\ThisCommonLabelBase.cmd.maketitle} (see +\DescPageRef{\ThisCommonLabelBase.cmd.maketitle}). Any value from +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} can be used +for \PName{simple switch}. + +With the \OptionValue{titlepage}{true}% +\important{\OptionValue{titlepage}{true}} +\IfThisCommonLabelBase{scrextend}{}{or \Option{titlepage}} option, +invoking \DescRef{\ThisCommonLabelBase.cmd.maketitle} creates titles on +separate pages. These pages are set inside a +\DescRef{\ThisCommonLabelBase.env.titlepage} environment, and they +normally have neither header nor footer. Compared to standard {\LaTeX}, +{\KOMAScript} significantly expands the handling of the titles. These +additional elements can be found on the following pages. + +In contrast, with the \OptionValue{titlepage}{false}\important{\OptionValue{titlepage}{false}} -specifies that an \emph{in-page} title is used. This means that the title is -specially emphasized, but it may be followed by more material on the same -page, for instance by an abstract or a section.% +option, invoking \DescRef{\ThisCommonLabelBase.cmd.maketitle} creates an +\emph{in-page} title. This means that the title is specially emphasized, but +it may be followed by more material on the same page, for instance an abstract +or a section.% The third choice,% \IfThisCommonLabelBase{maincls}{% @@ -138,34 +144,27 @@ The third choice,% \ChangedAt{v3.12}{\Package{scrextend}}% }{\InternalCommonFileUseError}% } \OptionValue{titlepage}{firstiscover}% -\important{\OptionValue{titlepage}{firstiscover}} does not only select title -pages. It additionally prints the first title page of -\DescRef{\ThisCommonLabelBase.cmd.maketitle}\IndexCmd{maketitle}, this is -either the extra title or the main title, as a cover\Index{cover} page. Every -other setting of option \Option{titlepage} would cancel this setting. The -margins\important{% - \Macro{coverpagetopmargin}\\ - \Macro{coverpagebottommargin}\\ - \Macro{coverpageleftmargin}\\ - \Macro{coverpagerightmargin}} of the cover page are given by -\Macro{coverpagetopmargin}\IndexCmd[indexmain]{coverpagetopmargin}, -\Macro{coverpagebottommargin}\IndexCmd[indexmain]{coverpagebottommargin}, -\Macro{coverpageleftmargin}\IndexCmd[indexmain]{coverpageleftmargin} und -\Macro{coverpagerightmargin}\IndexCmd[indexmain]{coverpagerightmargin}. The -defaults of these depend on the lengths -\Length{topmargin}\IndexLength{topmargin} and -\Length{evensidemargin}\IndexLength{evensidemargin} and can be changed using -\Macro{renewcommand}. +\important{\OptionValue{titlepage}{firstiscover}} not only activates title +pages but also prints the first title page of +\DescRef{\ThisCommonLabelBase.cmd.maketitle}\IndexCmd{maketitle}, i.\,e. +either the half-title or the main title, as a cover\Index{cover} page. Any +other setting of the \Option{titlepage} option will cancel this setting. The +margins\important{\Macro{coverpage\dots margin}} of the cover page are given +by \Macro{coverpagetopmargin}, \Macro{coverpageleftmargin}, +\Macro{coverpagerightmargin}, and \Macro{coverpagebottommargin}. The defaults +of these depend on the lengths of \Length{topmargin}\IndexLength{topmargin} +and \Length{evensidemargin}\IndexLength{evensidemargin} and can be changed +with \Macro{renewcommand}. \IfThisCommonLabelBase{maincls}{% - The default of classes \Class{scrbook} and \Class{scrreprt} is usage of - title pages. Class \Class{scrartcl}, on the other hand, uses in-page titles - as default.% + The default of the \Class{scrbook} and \Class{scrreprt} classes is to use + title pages. The \Class{scrartcl} class, on the other hand, uses in-page + titles by default.% }{% \IfThisCommonLabelBase{scrextend}{% - The default depends on the used class and \Package{scrextend} handles it - compatible to the standard class. If a class does not set up a comparable - default, in-page title will be used.% + The default depends on the class used and \Package{scrextend} recognizes + it in a way that compatible with the standard class. If a class does not + set up a comparable default, it will be an in-page title.% }{\InternalCommonFileUsageError}% }% % @@ -175,16 +174,16 @@ defaults of these depend on the lengths \begin{Declaration} \begin{Environment}{titlepage}\end{Environment}% \end{Declaration}% -With the standard classes and with {\KOMAScript}, all title pages are defined -in a special environment, the \Environment{titlepage} environment. This -environment always starts a new page\,---\,in the two-sided layout a new right -page\,---\,and in single column mode. For this page, the style is changed by -\DescRef{maincls.cmd.thispagestyle}\PParameter{empty}, so that -neither page number nor running heading are output. At the end of the -environment the page is automatically shipped out. Should you not be able to -use the automatic layout of the title pages provided by -\DescRef{\ThisCommonLabelBase.cmd.maketitle}, that will be described next; it -is advisable to design a new one with the help of this environment. +The standard classes and {\KOMAScript} set all title pages in a special +environment: the \Environment{titlepage} environment. This environment always +starts a new page\,---\,in two-sided printing a new right-hand page\,---\,and +in single-column mode. For this page, the style is changed to +\DescRef{maincls.cmd.thispagestyle}% +\PParameter{\DescRef{maincls.pagestyle.empty}}, so that neither page number +nor running head is output. At the end of the environment, the page is +automatically shipped out. Should you not be able to use the automatic layout +of the title pages provided by \DescRef{\ThisCommonLabelBase.cmd.maketitle}, +described next, you should design a new one with the help of this environment. \IfThisCommonFirstRun{\iftrue}{% A simple example for a title page with \Environment{titlepage} is shown in @@ -194,7 +193,7 @@ is advisable to design a new one with the help of this environment. }% \begin{Example} \phantomsection\xmpllabel{env.titlepage} - Assume you want a title page on which only the word ``Me'' stands at + Suppose you want a title page on which only the word ``Me'' stands at the top on the left, as large as possible and in bold\,---\,no author, no date, nothing else. The following document creates just that: @@ -215,71 +214,79 @@ is advisable to design a new one with the help of this environment. \begin{Declaration} \Macro{maketitle}\OParameter{page number} \end{Declaration}% -While the the standard classes produce at least one title page that may have -the three items title, author, and date, with {\KOMAScript} the -\Macro{maketitle} command can produce up to six pages. In contrast to the -standard classes, the \Macro{maketitle} macro in {\KOMAScript} accepts an -optional numeric argument. If it is used, this number is made the page number -of the first title page. However, this page number is not output, but affects -only the numbering. You should choose an odd number, because otherwise the -whole count gets mixed up. In my opinion there are only two meaningful -applications for the optional argument. On the one hand, one could give to the -half-title\Index[indexmain]{half-title} the logical page number \(-\)1 in -order to give the full title page the number 1. On the other hand, it could be -used to start at a higher page number, for instance, 3, 5, or 7, to +While\textnote{\KOMAScript{} vs. standard classes} the standard classes +produce at most one title page that can have three items (title, author, and +date), with \KOMAScript{} \Macro{maketitle} can produce up to six pages. In +contrast to the standard classes, \Macro{maketitle} in {\KOMAScript} accepts +an optional numeric argument. If it is used, this number is the page number of +the first title page. This page number is not output, but it affects the +subsequent numbering. You should definitely choose an odd number, because +otherwise the whole count gets mixed up. In my opinion, there are only two +useful applications for the optional argument. On the one hand, you could give +the the logical page number -1 to the half-title\Index[indexmain]{half-title} +in order to give the full title page the number 1. On the other hand, you +could use it to start at a higher page number, for example, 3, 5, or 7, to accommodate other title pages added by the publishing house. The optional -argument is ignored for \emph{in-page} titles. However, the page style of such -a title page can be changed by redefining the -\DescRef{\ThisCommonLabelBase.cmd.titlepagestyle} macro. For that see -\autoref{sec:maincls.pagestyle}, \DescPageRef{maincls.cmd.titlepagestyle}. - -The following commands do not lead immediately to the ship-out of the -titles. The typesetting and ship-out of the title pages are always done by -\Macro{maketitle}. By the way, you should note that \Macro{maketitle} should -not be used inside a \DescRef{\ThisCommonLabelBase.env.titlepage} -environment. Like\textnote{Attention!} shown in the examples, one should use -either \Macro{maketitle} or \DescRef{\ThisCommonLabelBase.env.titlepage} only, -but not both. - -The commands explained below only define the contents of the title -pages. Because of this, they have to be used before \Macro{maketitle}. It is, -however, not necessary and, when using, e.\,g., the \Package{babel} -package\IndexPackage{babel}, not recommended to use these in the preamble -before \Macro{begin}\PParameter{document} (see \cite{package:babel}). Examples -can be found at the end of this section. +argument is ignored for \emph{in-page} titles. You can change the page style +of such a title page by redefining the +\DescRef{\ThisCommonLabelBase.cmd.titlepagestyle} macro (see +\autoref{sec:maincls.pagestyle}, \DescPageRef{maincls.cmd.titlepagestyle}). + +The following commands do not lead immediately to the ship-out of the titles. +The typesetting and ship-out of the title pages are always done by +\Macro{maketitle}. Note also that \Macro{maketitle} should not be used inside +a \DescRef{\ThisCommonLabelBase.env.titlepage} environment. +As\textnote{Attention!} shown in the examples, you should use either +\Macro{maketitle} or \DescRef{\ThisCommonLabelBase.env.titlepage}, but not +both. + +The following commands only define the contents of the title. Therefore they +must be used before \Macro{maketitle}. It is, however, not necessary and, when +using the \Package{babel} package\IndexPackage{babel} not recommended, to +include these in the preamble before \Macro{begin}\PParameter{document} (see +\cite{package:babel}). You can find examples +\IfThisCommonFirstRun{in the descriptions of the other commands in this + section}{in \autoref{sec:\ThisCommonFirstLabelBase.titlepage}, starting on + \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.extratitle}}. \begin{Declaration} \Macro{extratitle}\Parameter{half-title} + \Macro{frontispiece}\Parameter{frontispiece} \end{Declaration}% \begin{Explain}% - In earlier times the inner book was often not protected from dirt by a cover. - This task was then taken over by the first page of the book which - carried mostly a shortened title called the \emph{half-title}. - Nowadays the extra page is often applied before the real full title - and contains information about the publisher, series number and similar - information. + In earlier times the inner book was often not protected from dirt by a + cover. This function was then assumed by the first page of the book, which + usually had just a short title, known as the \emph{half-title}. Nowadays the + extra page often appears before the real main title and contains information + about the publisher, series number, and similar information. \end{Explain} -With {\KOMAScript} it is possible to include a page before the real title -page. The \PName{half-title} can be arbitrary text\,---\,even several -paragraphs. The contents of the \PName {half-title} are output by -{\KOMAScript} without additional formatting. Their organisation is completely -left to the user. The back of the half-title remains empty. The half-title -has its own title page even when \emph{in-page} titles are used. The output of -the half-title defined with \Macro{extratitle} takes place as part of the -titles produced by \DescRef{\ThisCommonLabelBase.cmd.maketitle}. +With {\KOMAScript}, it is possible to include a page before the real title +page. The \PName{half-title} can be arbitrary text\,---\,even several +paragraphs. The contents of the \PName{half-title} are output by {\KOMAScript} +without additional formatting. Their organisation is completely left to the +user. The verso of the half-title\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.25}{\Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrextend}{% + \ChangedAt{v3.25}{\Package{scrextend}}% + }{\ThisCommonLabelBaseFailure}% +} is the frontispiece. The half-title is set on its own page even when in-page +titles are used. The output of the half-title defined with \Macro{extratitle} +takes place as part of the title produced by +\DescRef{\ThisCommonLabelBase.cmd.maketitle}. \IfThisCommonFirstRun{\iftrue}{% - A simple example for a title page with extra title and main title is shown + An example of a simple title page with half-title and main title is shown in \autoref{sec:\ThisCommonFirstLabelBase.titlepage} on \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.extratitle}% \csname iffalse\endcsname% }% \begin{Example} \phantomsection\xmpllabel{cmd.extratitle} - Let's go back to the previous example and assume - that the spartan ``Me'' is the half-title. The full title should - still follow the half-title. One can proceed as follows: + Let's return to the previous example and suppose + that the Spartan ``Me'' is the half-title. The full title should + still follow the half-title. You can proceed as follows: \begin{lstcode} \documentclass{scrbook} \begin{document} @@ -288,7 +295,7 @@ titles produced by \DescRef{\ThisCommonLabelBase.cmd.maketitle}. \maketitle \end{document} \end{lstcode} - You can center the half-title horizontally and put it a little lower down + You can centre the half-title horizontally and put it a little lower down the page: \begin{lstcode} \documentclass{scrbook} @@ -318,84 +325,101 @@ titles produced by \DescRef{\ThisCommonLabelBase.cmd.maketitle}. \Macro{and}% \Macro{thanks}\Parameter{footnote} \end{Declaration}% -The contents of the full title page are defined by seven elements. The output -of the full title page occurs as part of the title pages of -\DescRef{\ThisCommonLabelBase.cmd.maketitle}, whereas the now listed elements -only define the corresponding elements. - -\BeginIndexGroup -\BeginIndex{FontElement}{titlehead}\LabelFontElement{titlehead}% -The\important{\Macro{titlehead}} \PName{title - head}\Index[indexmain]{title>head} is defined with the command -\Macro{titlehead}. It is typeset with the font of the homonymous element in -regular justification and full width at the top of the page. It can be freely -designed by the user.% +There are seven elements available for the content of the main title page. The +main title page is output as part of the title pages created by +\DescRef{\ThisCommonLabelBase.cmd.maketitle}, while the definitions given here +only apply to the respective elements. + +\BeginIndexGroup\BeginIndex{FontElement}{titlehead}% +\LabelFontElement{titlehead}% +The\important{\Macro{titlehead}} \PName{title head}% +\Index[indexmain]{title>head} is defined with the command +\Macro{titlehead}. It occupies the entire text width, at the top of the page, +in normal justification, and it can be freely designed by the user. It uses +the font element\important{\FontElement{titlehead}} with same name (see +\autoref{tab:\ThisCommonFirstLabelBase.mainTitle}, +\autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}).% \EndIndexGroup -\BeginIndexGroup -\BeginIndex{FontElement}{subject}\LabelFontElement{subject}% +\BeginIndexGroup\BeginIndex{FontElement}{subject}\LabelFontElement{subject}% The\important{\Macro{subject}} \PName{subject}\Index[indexmain]{subject} is -output with the font of the homonymous element immediately above the -\PName{title}.% +output with the font element\important{\FontElement{subject}} of the same name +immediately above the \PName{title}.% \EndIndexGroup -\BeginIndexGroup -\BeginIndex{FontElement}{title}\LabelFontElement{title}% -The\important{\Macro{title}} \PName{title} is output with a very large font -size. Beside\IfThisCommonLabelBase{maincls}{% +\BeginIndexGroup\BeginIndex{FontElement}{title}\LabelFontElement{title}% +The\important{\Macro{title}} \PName{title} is set in a very large font size. +Along\IfThisCommonLabelBase{maincls}{% \ChangedAt{v2.8p}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}}}{} all other element the font size\textnote{Attention!} -is, however, not affected by the font switching element \FontElement{title} -(see \autoref{tab:\ThisCommonFirstLabelBase.mainTitle}, + \Class{scrartcl}}}{} with the font size, the font element +\FontElement{title}\IndexFontElement[indexmain]{title}% +\important{\FontElement{title}} is applied (see +\autoref{tab:\ThisCommonFirstLabelBase.mainTitle}, \autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}).% \EndIndexGroup -\BeginIndexGroup -\BeginIndex{FontElement}{subtitle}\LabelFontElement{subtitle}% +\BeginIndexGroup\BeginIndex{FontElement}{subtitle}\LabelFontElement{subtitle}% The\important{\Macro{subtitle}} \PName{subtitle}\IfThisCommonLabelBase{maincls}{% \ChangedAt{v2.97c}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}}}{} is output with the font of the homonymous element -just below the title.% + \Class{scrartcl}}}{} is set just below the title using the font +element\important{\FontElement{subtitle}} of the same name (see +\autoref{tab:\ThisCommonFirstLabelBase.mainTitle}, +\autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}).% \EndIndexGroup -\BeginIndexGroup -\BeginIndex{FontElement}{author}\LabelFontElement{author}% +\BeginIndexGroup\BeginIndex{FontElement}{author}\LabelFontElement{author}% Below\important{\Macro{author}} the \PName{subtitle} appears the -\PName{author}\Index[indexmain]{author}. Several authors can be specified in -the argument of \Macro{author}. They should be separated by \Macro{and}. The -font of element \FontElement{author} is used for the output of the authors.% +\PName{author}\Index[indexmain]{author}. Several authors can be specified in +the argument of \Macro{author}. They should be separated by +\Macro{and}\important{\Macro{and}}. The output uses the font +element\important{\FontElement{author}} of the same name. (see +\autoref{tab:\ThisCommonFirstLabelBase.mainTitle}, +\autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}).% \EndIndexGroup -\BeginIndexGroup -\BeginIndex{FontElement}{date}\LabelFontElement{date}% +\BeginIndexGroup\BeginIndex{FontElement}{date}\LabelFontElement{date}% Below\important{\Macro{date}} the author or authors appears the -date\Index{date} in the font of the homonymous element. The default value is -the present date, as produced by \Macro{today}\IndexCmd{today}. The +date\Index{date} in the font of the element of the same name. The default +value is the current date, as produced by \Macro{today}\IndexCmd{today}. The \Macro{date} command accepts arbitrary information\,---\,even an empty -argument.% +argument. The output uses the font element\important{\FontElement{date}} of +the same name (see \autoref{tab:\ThisCommonFirstLabelBase.mainTitle}, +\autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}).% \EndIndexGroup -\BeginIndexGroup -\BeginIndex{FontElement}{publishers}\LabelFontElement{publishers}% +\BeginIndexGroup\BeginIndex{FontElement}{publishers}% +\LabelFontElement{publishers}% Finally\important{\Macro{publishers}} comes the \PName{publisher}\Index[indexmain]{publisher}. Of course this command can also -be used for any other information of little importance. If necessary, the +be used for any other information of minor importance. If necessary, the \Macro{parbox} command can be used to typeset this information over the full -page width like a regular paragraph instead of centering it. Then it is to be -considered equivalent to the title head. However, note that this field is put -above any existing footnotes. The font of element \FontElement{publishers} is -used for the output.% +page width like a regular paragraph instead of centring it. It should then be +considered equivalent to the title head. Note, however, that this field is +placed above any existing footnotes. The output uses the font +element\important{\FontElement{publishers}} of the same name (see +\autoref{tab:\ThisCommonFirstLabelBase.mainTitle}, +\autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}).% \EndIndexGroup Footnotes\important{\Macro{thanks}}\Index{footnotes} on the title page are produced not with \Macro{footnote}, but with \Macro{thanks}. They serve typically for notes associated with the authors. Symbols are used as footnote -markers instead of numbers. Note\textnote{Attention!}, that \Macro{thanks} has -to be used inside the argument of another command, e.\,g., at the argument -\PName{author} of the command \Macro{author}. - -While% +markers instead of numbers. Note\textnote{Attention!} that \Macro{thanks} has +to be used inside the argument of another command, such as in the +\PName{author} argument of the command \Macro{author}. +\IfThisCommonLabelBase{scrextend}{% + However, in order for the \DescRef{\ThisCommonLabelBase.fontelement.footnote} + element to be aware of the \Package{scrextend} package, not only does the + title extension need to be enabled, it must also be set to use footnotes + with this package (see the introduction to + \autoref{sec:\ThisCommonLabelBase.footnotes}, + \autopageref{sec:\ThisCommonLabelBase.footnotes}). Otherwise, the font + specified by the class or other packages used for the footnotes will be + used.% +}{}% + +For% \IfThisCommonLabelBase{maincls}{% \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% @@ -403,104 +427,118 @@ While% \IfThisCommonLabelBase{scrextend}{% \ChangedAt{v3.12}{\Package{scrextend}}% }{\InternalCommonFileUsageError}% -} printing the title elements the equal named font switching elements will be -used for all them. The defaults, that may be found in -\autoref{tab:\ThisCommonFirstLabelBase.titlefonts}, % -\IfThisCommonFirstRun{}{% - \autopageref{tab:\ThisCommonFirstLabelBase.titlefonts}, % -}% -may be changed using the commands -\DescRef{\ThisCommonLabelBase.cmd.setkomafont} and -\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} (see +} the output of the title elements, the font\textnote{font} can be set using +the \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and +\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} command (see \autoref{sec:\ThisCommonLabelBase.textmarkup}, -\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}).% +\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}). The defaults are listed +in \autoref{tab:\ThisCommonFirstLabelBase.titlefonts}% +\IfThisCommonFirstRun{}{% + , \autopageref{tab:\ThisCommonFirstLabelBase.titlefonts}% +}.% \IfThisCommonFirstRun{% \begin{table} % \centering +% \caption \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% -% \caption +% \addtokomafont{caption}{\raggedright}% \begin{captionbeside} [{Font defaults for the elements of the title}] {\label{tab:\ThisCommonLabelBase.titlefonts}% - Font defaults for the elements of the title} + \hspace{0pt plus 1ex}Font defaults for the elements of the title} [l] \begin{tabular}[t]{ll} \toprule Element name & Default \\ \midrule - \DescRef{\ThisCommonLabelBase.fontelement.author} & \Macro{Large} \\ - \DescRef{\ThisCommonLabelBase.fontelement.date} & \Macro{Large} \\ - \DescRef{\ThisCommonLabelBase.fontelement.dedication} & \Macro{Large} \\ - \DescRef{\ThisCommonLabelBase.fontelement.publishers} & \Macro{Large} \\ - \DescRef{\ThisCommonLabelBase.fontelement.subject} & - \Macro{normalfont}\Macro{normalcolor}\Macro{bfseries}\Macro{Large} \\ - \DescRef{\ThisCommonLabelBase.fontelement.subtitle} & - \Macro{usekomafont}\PParameter{title}\Macro{large} \\ - \DescRef{\ThisCommonLabelBase.fontelement.title} & \Macro{usekomafont}\PParameter{disposition} \\ - \DescRef{\ThisCommonLabelBase.fontelement.titlehead} & \\ + \FontElement{author} & \Macro{Large} \\ + \FontElement{date} & \Macro{Large} \\ + \FontElement{dedication} & \Macro{Large} \\ + \FontElement{publishers} & \Macro{Large} \\ + \FontElement{subject} & + \Macro{normalfont}\Macro{normalcolor}% + \Macro{bfseries}\Macro{Large} \\ + \FontElement{subtitle} & + \DescRef{\ThisCommonLabelBase.cmd.usekomafont}% + \PParameter{title}\Macro{large} \\ + \FontElement{title} & + \DescRef{\ThisCommonLabelBase.cmd.usekomafont}% + \PParameter{disposition} \\ + \FontElement{titlehead} & \\ \bottomrule \end{tabular} \end{captionbeside} \end{table}% -}{} - -With the exception of \PName{titlehead} and possible footnotes, all -the items are centered horizontally. The information is summarised in -\autoref{tab:\ThisCommonFirstLabelBase.mainTitle}% -\IfThisCommonFirstRun{}{% - , \autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}}. +}{}% + +With the exception of \PName{title head} and any footnotes, all output is +centred horizontally. % +\iffree{% + \IfThisCommonLabelBase{scrextend}{The formatting of each element is}{These + details are} briefly summarized in + \autoref{tab:\ThisCommonFirstLabelBase.mainTitle}\IfThisCommonFirstRun{}{% + , \autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}}.% +}{% + \IfThisCommonLabelBase{scrextend}{% + The alignment of individual elements can also be found in + \autoref{tab:\ThisCommonFirstLabelBase.mainTitle}\IfThisCommonFirstRun{}{% + , \autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}}.% + }{% + For a summary, see \autoref{tab:\ThisCommonFirstLabelBase.mainTitle}.% + }% +}% \IfThisCommonFirstRun{% \begin{table} -% \centering + % \centering \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% % \caption \begin{captionbeside}[Main title]{% - Font and horizontal positioning of the - elements in the main title page in the order of their vertical - position from top to bottom when typeset with - \DescRef{\ThisCommonLabelBase.cmd.maketitle}} + \hspace{0pt plus 1ex}% + Font and horizontal positioning of the elements in the main title page + in the order of their vertical position from top to bottom when + typeset with \DescRef{\ThisCommonLabelBase.cmd.maketitle}} [l] \setlength{\tabcolsep}{.85\tabcolsep}% Umbruchoptimierung \begin{tabular}[t]{llll} \toprule - Element & Command & Font & Orientation \\ + Element & Command & Font & Alignment \\ \midrule Title head & \Macro{titlehead} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{titlehead} & justified \\ - Subject & \Macro{subject} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{subject} & centered \\ - Title & \Macro{title} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{title}\Macro{huge} & centered \\ - Subtitle & \Macro{subtitle} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{subtitle} & centered \\ - Authors & \Macro{author} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{author} & centered \\ - Date & \Macro{date} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{date} & centered \\ - Publishers & \Macro{publishers} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{publishers} & centered \\ + Subject & \Macro{subject} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{subject} & centred \\ + Title & \Macro{title} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{title}\Macro{huge} & centred \\ + Subtitle & \Macro{subtitle} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{subtitle} & centred \\ + Authors & \Macro{author} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{author} & centred \\ + Date & \Macro{date} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{date} & centred \\ + Publishers & \Macro{publishers} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{publishers} & centred \\ \bottomrule \end{tabular} \end{captionbeside} \label{tab:maincls.mainTitle} \end{table} -}{} % -Please note\textnote{Attention!}, that for the main title \Macro{huge} will be -used after the font switching element +}{} + +Note\textnote{Attention!} that for the main title, \Macro{huge} will be used +after the font switching element \DescRef{\ThisCommonLabelBase.fontelement.title}\IndexFontElement{title}. So you cannot change the size of the main title using \DescRef{\ThisCommonLabelBase.cmd.setkomafont} or \DescRef{\ThisCommonLabelBase.cmd.addtokomafont}.% \IfThisCommonFirstRun{\iftrue}{% - An example for a title page with all elements provided by \KOMAScript{} for - the main title page is shown in - \autoref{sec:\ThisCommonFirstLabelBase.titlepage} on + An example for a title page using all the elements offered by \KOMAScript{} + is shown in \autoref{sec:\ThisCommonFirstLabelBase.titlepage} on \PageRefxmpl{\ThisCommonFirstLabelBase.maintitle}.% \csname iffalse\endcsname% }% \begin{Example} \phantomsection\xmpllabel{maintitle}% - Assume you are writing a dissertation. The title page should have the + Suppose you are writing a dissertation. The title page should have the university's name and address at the top, flush left, and the semester, - flush right. As usual, a title is to be used, including author and - delivery date. The adviser must also be indicated, together with the fact - that the document is a dissertation. This can be obtained as follows: + flush right. As usual, a title including author and submission date + should be given. The adviser must also be indicated, together with the + fact that the document is a dissertation. You can do this as follows: \begin{lstcode} \documentclass{scrbook} \usepackage[english]{babel} @@ -523,30 +561,31 @@ you cannot change the size of the main title using \fi \begin{Explain} - A frequent misunderstanding concerns the role of the full title page. It is - often erroneously assumed that the cover\Index{cover} or dust cover is - meant. Therefore, it is frequently expected that the title page does not - follow the normal page layout, but has equally large left and right margins. - - However, if one takes a book and opens it, one notices very quickly at least - one title page under the cover within the so-called inner book. Precisely + A common misconception concerns the function of the full title page. It is + often erroneously assumed to be the cover\Index{cover} or dust jacket. + Therefore, it is frequently expected that the title page will not follow the + normal layout for two-sided typesetting but will have equally large left and + right margins. + + But if you pick up a book and open it, you will quickly find at least one + title page inside the cover, within the so-called book block. Precisely these title pages are produced by \DescRef{\ThisCommonLabelBase.cmd.maketitle}. - As is the case with the half-title, the full title page belongs to the inner - book, and therefore should have the same page layout as the rest of the - document. A cover is actually something that should be created in a - separate document. The cover often has a very individual format. It can also - be designed with the help of a graphics or DTP program. A separate document - should also be used because the cover will be printed on a different medium, - possibly cardboard, and possibly with another printer. - - Nevertheless, since \KOMAScript~3.12 the first title page of - \DescRef{\ThisCommonLabelBase.cmd.maketitle} can be printed as a cover page - with different margins. For more information about this see the description - of option + As is the case with the half-title, the full title page belongs to the book + block, and therefore should have the same page layout as the rest of the + document. A cover is actually something that you should create in a + separate document. After all, it often has a very distinct format. It can + also be designed with the help of a graphics or DTP program. A separate + document should also be used because the cover will be printed on a + different medium, such as cardboard, and possibly with another printer. + + Nevertheless, since \KOMAScript~3.12 the first title page issued by + \DescRef{\ThisCommonLabelBase.cmd.maketitle} can be formatted as a cover + page with different margins. Changes to the margins on this page do not + affect the other margins. For more information about this option, see \OptionValueRef{\ThisCommonLabelBase}{titlepage}{firstiscover}% - \IndexOption{titlepage~=\PValue{firstiscover}} on + \IndexOption{titlepage~=\textKValue{firstiscover}} on \DescPageRef{\ThisCommonLabelBase.option.titlepage}. \end{Explain} % @@ -557,15 +596,15 @@ you cannot change the size of the main title using \Macro{uppertitleback}\Parameter{titlebackhead}% \Macro{lowertitleback}\Parameter{titlebackfoot} \end{Declaration}% -With the standard classes, the back of the title page of a double-side print -is left empty. However, with {\KOMAScript} the back of the full title page -can be used for other information. Exactly two elements which the user can -freely format are recognized: \PName -{titlebackhead}\Index{title>back}\Index{title>rear side}\Index{title>flipside} -and \PName {titlebackfoot}. The head can reach up to the foot and vice -versa. \iffree{If one takes this manual as an example, the exclusion of - liability was set with the help of the \Macro{uppertitleback} command.}{The - publishers information of this book. e.\,g., could have been set either with +In\textnote{\KOMAScript{} vs. standard classes} two-sided printing, the +standard classes leave the back (verso) of the title page empty. However, with +{\KOMAScript} the back of the full title page can be used for other +information. There are exactly two elements which the user can freely format: +\PName{titlebackhead}\Index{title>back}\Index{title>verso} and +\PName{titlebackfoot}. The header can extend to the footer and vice versa. +\iffree{Using this guide as an example, the legal disclaimer was set with the + help of the \Macro{uppertitleback} command.}{The publishers information of + this book, for example, could have been set either with \Macro{uppertitleback} or \Macro{lowertitleback}.}% % \EndIndexGroup @@ -574,18 +613,27 @@ versa. \iffree{If one takes this manual as an example, the exclusion of \begin{Declaration} \Macro{dedication}\Parameter{dedication} \end{Declaration}% -\BeginIndexGroup -\BeginIndex{FontElement}{dedication}\LabelFontElement{dedication}% -{\KOMAScript} provides a page for dedications. The -dedication\Index{dedication} is centered and uses a slightly larger type size -given by the font of the homonymous element. The font can be changed using -command \DescRef{\ThisCommonLabelBase.cmd.setkomafont} or -\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} (see +{\KOMAScript} offers its own dedication page. This +dedication\Index{dedication} is centred and set by default with a slightly +larger font\textnote{font}. +\BeginIndexGroup\BeginIndex{FontElement}{dedication}% +\LabelFontElement{dedication} +The% +\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrextend}{% + \ChangedAt{v3.12}{\Package{scrextend}}% + }{\InternalCommonFileUseError}% +}\important{\FontElement{dedication}} exact font setting for the +\FontElement{dedication} element, which is taken from +\autoref{tab:\ThisCommonFirstLabelBase.titlefonts}, +\autopageref{tab:\ThisCommonFirstLabelBase.titlefonts}, can be changed with +the \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and +\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} commands (see \autoref{sec:\ThisCommonLabelBase.textmarkup}, -\autopageref{sec:\ThisCommonLabelBase.textmarkup}). The back is empty like -the back page of the half-title. The dedication page is produced by -\DescRef{\ThisCommonLabelBase.cmd.maketitle} and must therefore be defined -before this command is issued.% +\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}).% \EndIndexGroup \IfThisCommonFirstRun{\iftrue}{% @@ -596,8 +644,8 @@ before this command is issued.% }% \begin{Example} \phantomsection\xmpllabel{fulltitle}% - This time assume that you have written a poetry book and you want to - dedicate it to your wife. A solution would look like this: + Suppose you have written a book of poetry and want to + dedicate it to your spouse. A solution would look like this: \begin{lstcode} \documentclass{scrbook} \usepackage[english]{babel} @@ -608,14 +656,14 @@ before this command is issued.% \date{1412} \lowertitleback{This poem book was set with% the help of {\KOMAScript} and {\LaTeX}} - \uppertitleback{Selfmockery Publishers} - \dedication{To my treasure hazel-hen\\ + \uppertitleback{Self-mockery Publishers} + \dedication{To my treasured hazel-hen\\ in eternal love\\ from your dormouse.} \maketitle \end{document} \end{lstcode} - Please use your own favorite pet names. + Please use your own favourite pet names to personalize it. \end{Example}% \fi% \EndIndexGroup diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-typearea.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-typearea.tex index 0ca2f88ad3f..30b89d03311 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-typearea.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-typearea.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-typearea.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % common-typearea.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,40 +46,43 @@ % ====================================================================== \KOMAProvidesFile{common-typearea.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (common paragraphs: typearea)] -\translator{Markus Kohm\and Krickette Murabayashi} +\translator{Markus Kohm\and Krickette Murabayashi\and Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-02-01 \section{Page Layout} \seclabel{typearea} \BeginIndexGroup \BeginIndex{}{page>layout} -Each page of a document is separated into several different layout elements, -e.\,g., margins, head, foot, text area, margin note column, and the distances -between all these elements. \KOMAScript{} additionally distinguishes the page -as a whole also known as the paper and the viewable area of the page. Without -doubt, the separation of the page into the several parts is one of the basic -features of a class. Nevertheless at \KOMAScript{} the classes delegate that -business to the package \Package{typearea}. This package may be used with other -classes too. In difference to those other classes the \KOMAScript{} classes -load \Package{typearea} on their own. Because of this, there's no need to load -the package explicitly with \Macro{usepackage} while using a \KOMAScript{} -class. Nor would this make sense or be useful. See also -\autoref{sec:\csname label@base\endcsname.options}. +Each page of a document consists of different layout elements, such as the +margins, the header, the footer, the text area, the marginal note column, and +the distances between these elements. \KOMAScript{} additionally distinguishes +the entire page, also known as the paper, and the visible page. Without doubt, +the separation of the page into these different parts is one of the basic +features of a class\IfThisCommonLabelBase{scrlttr2}{\OnlyAt{scrlttr2}}{}. +\KOMAScript{} delegates this work to the package \Package{typearea}. This +package can also be used with other classes. The \KOMAScript{} classes, +however, load \Package{typearea} on their own. Therefore, it's neither +necessary nor sensible to load the package explicitly with \Macro{usepackage} +while using a \KOMAScript{} class. See also +\autoref{sec:\ThisCommonLabelBase.options}, +\autopageref{sec:\ThisCommonLabelBase.options}. -Some settings of \KOMAScript{} classes do influence the page layout. Those -effects will be documented at the corresponding settings. +Some settings of \KOMAScript{} classes affect the page layout and vice versa. +Those effects are documented at the corresponding settings. -For more information about page size, separation of pages into margins and -type area, and about selection of one or two column typesetting see the -documentation of package \Package{typearea}. You may find it at -\autoref{cha:typearea} from \autopageref{cha:typearea} onwards. +For more information about the choice of paper format, the division of the +page into margins and type area, and the choice between one- and two-column +typesetting, see the documentation for the \Package{typearea} package. You can +find it in \autoref{cha:typearea}, starting on \autopageref{cha:typearea}. %%% Local Variables: %%% mode: latex +%%% mode: flyspell %%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" %%% TeX-master: "../guide" %%% End: diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/expertpart.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/expertpart.tex index a2d84d41846..60dd17e9b3a 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/expertpart.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/expertpart.tex @@ -1,6 +1,6 @@ % ====================================================================== % expertpart.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % expertpart.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,20 +46,20 @@ % ====================================================================== \KOMAProvidesFile{expertpart.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-02-28 13:23:23 +0100 (Wed, 28 Feb 2018) $ Part KOMA-Script for Experts] -\translator{Markus Kohm} +\translator{Markus Kohm\and Karl Hagen} \setpartpreamble{% \vspace*{2\baselineskip}% \setlength{\parindent}{1em}% - \noindent In this part information for the authors of LaTeX packages and - classes can be found. This applies not only instructions that are useful for - implementation of new packages and classes, but also interfaces to allow - further intervention in \KOMAScript. Moreover, in this part, information on - obsolete options and instructions are provided as well as background - information on the implementation of KOMAScript. + \noindent In this part, you can find information for the authors of LaTeX + packages and classes. This applies not only to commands that are useful for + implementing new packages and classes, but also to interfaces that allow + further alteration of \KOMAScript{}. Moreover, this part provides + information on obsolete options and instructions, as well as background + information on the implementation of \KOMAScript{}. This part is intended to supplement the information for authors of articles, reports, books and letters in \autoref{part:forAuthors}. More information diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/guide-english.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/guide-english.tex index 7f9529ea7a3..edebaee2b9d 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/guide-english.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/guide-english.tex @@ -1,6 +1,6 @@ % ====================================================================== % guide-english.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % guide-english.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,7 +46,7 @@ % ====================================================================== % \KOMAProvidesFile{guide-english.tex} - [$Date: 2017-08-08 18:17:31 +0200 (Tue, 08 Aug 2017) $ + [$Date: 2018-03-21 10:37:34 +0100 (Wed, 21 Mar 2018) $ KOMA-Script guide language dependencies] % % \section{Extra Packages} @@ -73,7 +73,7 @@ \vfill \noindent Note: This document is a translation of the German \KOMAScript{} manual. Several authors have been involved to this translation. Some of them - are native English speakers, others like me are not. Improvements of the + are native English speakers. Others, like me, are not. Improvements of the translation by native speakers or experts are welcome at all times!% }% \newcommand*{\GuideAuthorHeadline}{Authors of the {\KOMAScript} Bundle}% @@ -81,7 +81,7 @@ } \newcommand*{\GuideWarrantyHeadline}{Legal Notes:}% \newcommand*{\GuideWarranty}{There is no warranty for any part of the documented software. The authors have taken care in the preparation of this - book, but make no expressed or implied warranty of any kind and assume no + guide, but make no expressed or implied warranty of any kind and assume no responsibility for errors or omissions. No liability is assumed for incidental or consequential damages in connection with or arising out of the use of the information or programs contained here.\par\medskip% @@ -93,11 +93,11 @@ paragraph and page breaks\par\medskip% This guide is part of {\KOMAScript}, which is free under the terms and conditions of {\LaTeX} Project Public License Version 1.3c. A version of - this license, which is valid to {\KOMAScript}, is part of {\KOMAScript} (see + this license, which is valid for {\KOMAScript}, is part of {\KOMAScript} (see \File{lppl.txt}). Distribution of this manual\,---\,even if it is printed\,---\,is allowed provided that all parts of {\KOMAScript} are - distributed. Distribution without the other parts of {\KOMAScript} needs an - explicit, additional authorization by the authors.}% + distributed with it. Distribution without the other parts of {\KOMAScript} + requires an explicit, additional authorization by the authors.}% \newcommand*{\GuideDedication}{To all my friends all over the world!}% % \end{macrocode} % \end{macro} @@ -331,8 +331,8 @@ % Note, that the non free manual contains more information. % \begin{macrocode} \newcommand*{\GuideLoadNonFree}{% - Sorry, currently additional information to this may be found at the same - point of the German \KOMAScript{} book \cite{book:komascript} only. + Currently, additional information on this topic can be found at the same + point in the German \KOMAScript{} book \cite{book:komascript} only. } % \end{macrocode} % \end{macro} @@ -354,14 +354,14 @@ % The titles and short titles of each single index. \newcommand*{\GuidegenIndex}{General Index}% \newcommand*{\GuidecmdIndex}{Index of Commands, Environments, and Variables}% -\newcommand*{\GuidecmdIndexShort}{Index of Commands etc.}% +\newcommand*{\GuidecmdIndexShort}{Index of Commands, etc.}% \newcommand*{\GuidelenIndex}{Index of Lengths and Counters}% -\newcommand*{\GuidelenIndexShort}{Index of Lengths etc.}% -\newcommand*{\GuideelmIndex}{Index of Elements with Capability of - Font Adjustment}% +\newcommand*{\GuidelenIndexShort}{Index of Lengths, etc.}% +\newcommand*{\GuideelmIndex}{Index of Elements Capable of + Adjusting Fonts}% \newcommand*{\GuideelmIndexShort}{Index of Elements}% \newcommand*{\GuidefilIndex}{Index of Files, Classes, and Packages}% -\newcommand*{\GuidefilIndexShort}{Index of Files etc.}% +\newcommand*{\GuidefilIndexShort}{Index of Files, etc.}% \newcommand*{\GuideoptIndex}{Index of Class and Package Options}% \newcommand*{\GuideoptIndexShort}{Index of Options}% % \end{macro} @@ -379,9 +379,9 @@ % \begin{macro}{\GuideIndexPreamble} % The preamble text of the whole index. \newcommand*{\GuideIndexPreamble}{% - There are two kinds of page numbers at this index. The bold printed numbers - show the pages of declaration or explanation of the topic. The normal - printed numbers show the pages of using a topic.% + There are two kinds of page numbers in this index. The numbers in bold + show the pages where the topic is defined or explained. The numbers in + ordinary type show the pages of where the topic is mentioned.% } % \end{macro} % @@ -403,21 +403,20 @@ % \begin{macro}{\GuideBibPreamble} % \begin{macrocode} \newcommand*{\GuideBibPreamble}{% - In the following you can find many references. All of them are referenced - from the main text. In many cases the reference points to documents or - directories which can be accessed via Internet. In these cases the - reference includes a URL instead of a publisher. If the reference points to + In the following, you will find many references. All of them are referenced + in the main text. In many cases the reference points to documents or + directories which can be accessed via the Internet. In these cases, the + reference includes a URL instead of a publisher. If the reference points to a {\LaTeX} package then the URL is written in the form ``\url{CTAN://}\emph{destination}''. The prefix ``\url{CTAN://}'' means the - \TeX{} archive on a CTAN server or mirror. For example, you can substitute - the prefix with \url{http://mirror.ctan.org/}. For {\LaTeX} - packages it is also important to mention that we have tried to give a - version number appropriate to the text that cites the reference. But for - some packages is is very difficult to find a consistent version number and - release date. Additionally the given version is not always the current - version. If you want install new packages take care that the package is the - most up-to-date version and check first whether the package is already - available on your system or not.% + \TeX{} archive on a CTAN server or mirror. For example, you can replace the + prefix with \url{http://mirror.ctan.org/}. For {\LaTeX} packages, it is also + important to mention that we have tried to give a version number appropriate + to the text that cites the reference. But for some packages is is very + difficult to find a consistent version number and release date. + Additionally, the given version is not always the current version. If you + want install new packages, be sure that the package is the most up-to-date + version and check first if the package is already available on your system.% } % \end{macrocode} % \end{macro} @@ -429,12 +428,11 @@ % The preamble of the change log index. % \begin{macrocode} \newcommand*{\GuideChangeLogPreamble}{% - At this list of changes you will find all significant changes of the user + In this list of changes, you will find all significant changes to the user interface of the {\KOMAScript} bundle at the last few versions. The list was - sorted about the names of the classes and packages and their version. The - numbers behind the versions are the pages, where the changes are - described. At the margins of these pages you will find corresponding version - marks.% + sorted by the names of the classes and packages and their version. The + numbers after the version are the pages where the changes are described. In + the margins of these pages, you will find corresponding version marks.% } % \end{macrocode} % \end{macro} diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/guide.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/guide.tex index e22f7c8e590..7386ccba9c7 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/guide.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/guide.tex @@ -1,6 +1,6 @@ % ====================================================================== % guide.tex -% Copyright (c) Markus Kohm, 2002-2015 +% Copyright (c) Markus Kohm, 2002-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % guide.tex -% Copyright (c) Markus Kohm, 2002-2015 +% Copyright (c) Markus Kohm, 2002-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -48,7 +48,7 @@ \documentclass[\languagename]{scrguide} \KOMAProvidesFile{guide.tex} - [$Date: 2015-04-21 10:08:26 +0200 (Tue, 21 Apr 2015) $ + [$Date: 2018-02-07 13:47:54 +0100 (Wed, 07 Feb 2018) $ KOMA-Script (guide main file)] \begin{document} @@ -72,8 +72,8 @@ \dedication{\GuideDedication} \pdfbookmark[-1]{\KOMAScript}{title} -\bookmark[level=0,gotor=scrguide.pdf]{Deutsch} -\bookmark[level=0,gotor=scrguien.pdf]{English} +\iffree{\bookmark[level=0,gotor=scrguide.pdf]{Deutsch} +\bookmark[level=0,gotor=scrguien.pdf]{English}}{} \bookmarksetup{startatroot} \maketitle diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/introduction.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/introduction.tex index c3383f83345..2d556d09737 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/introduction.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/introduction.tex @@ -1,6 +1,6 @@ % ====================================================================== % introduction.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % introduction.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,107 +46,102 @@ % ====================================================================== \KOMAProvidesFile{introduction.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide introduction] \translator{Kevin Pfeiffer\and Gernot Hassenpflug\and - Krickette Murabayashi\and Markus Kohm} + Krickette Murabayashi\and Markus Kohm\and Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-02-05 \chapter{Introduction} \labelbase{introduction} -This chapter includes important information about the structure of the manual -and the history of KOMA-Script, which begins years before the first -version. You will also find information for those who have not installed -KOMA-Script or encounter errors. +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 evidenced by the fact that it -consists of -not only a single class or a single package, but a bundle of many classes and -packages. Although the classes are designed as a counterpart to the standard -classes, that does not necessarily mean that they only have the commands, -environments, and setting of the standard classes or imitate their -appearance. The capabilities of \KOMAScript{} surpass the capabilities of the -standard classes considerably. Some of them are to be regarded as a supplement -to the basic skills of the \LaTeX{} kernel. - -The foregoing means that the documentation of \KOMAScript{} has to be -extensive. In addition, \KOMAScript{} usually is not taught. That means there -is no teacher who knows his students and can therefore choose the teaching and -learning materials and adapt them accordingly. It would be easy to write the -documentation for any specific audience. The difficulty is, however, that the -guide must service all potential audiences. We, the authors, have tried to -create a guide that is suited for the computer scientist as well as the -secretary or the fishmonger. We have tried, although this is actually % dealing -% with -an impossible task. The result consists of several compromises and we -hope that you will keep this in mind when using it. Your suggestions for -improvement are, of course, always welcome. - -Despite the volume of the manual, % in case of problems -it is recommended to -consult the documentation. Attention is drawn to the multi-part index at the -end of this document. In addition to this guide, documentation includes all the -text documents that are part of the bundle. See \File{manifest.tex} for a list -of all of them. - +{\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 consists of several parts. There's a part for average users, -another part for advanced users and experts, and an appendix with additional -examples and information for those who always want to know more. - -\hyperref[part:forAuthors]{Part~\ref{part:forAuthors}} is recommended for all -\KOMAScript{} users. This means that you may find here even some information -for newcomers to \LaTeX. In particular, this part is enhanced by many examples -to the average user that are intended to illustrate the explanations. Do not -be afraid to try these examples yourself and in modifying them to find out how -\KOMAScript{} works. Nevertheless 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 considerably long, it is nevertheless -quite useful not only to those having problems using \LaTeX{} or \KOMAScript. - -\hyperref[part:forExperts]{Part~\ref{part:forExperts}} is recommended for -advanced \KOMAScript{} users. These are all of you who already know -\LaTeX{}, maybe worked with \KOMAScript{} for a while, and want to -learn more about \KOMAScript{} internals, interaction of \KOMAScript{} -with other packages, and how to use \KOMAScript{} as an answer to -special demands. For this purpose we will have a closer look at some -aspects from \autoref{part:forAuthors} again. In addition some -instructions that have been implemented for advanced users and -experts, especially, will be documented. This is complemented by the -documentation of packages that are normally hidden to the user insofar -as they do their work under the surface of the classes and user -packages. These packages are specifically designed to be used by other -authors of classes and packages. - -The appendix, which may be found only in the German book version, contains -information which is beyond what is covered in \autoref{part:forAuthors} and -\autoref{part:forExperts}. Advanced users may find background information on -issues of typography to give them a basis for their own decisions. In -addition, the appendix provides examples for aspiring authors of -packages. These examples are less intended to be simply transferred. Rather, -they convey knowledge of planning and implementation of projects as well as -some basic \LaTeX{} instructions for authors of packages. - -If you are only interested in using a single {\KOMAScript} class or package -you can probably successfully avoid reading the entire guide. Each class and -package typically has its own chapter; however, the three main classes -(\Class{scrbook}, \Class{scrrprt}, and \Class{scrartcl}) are introduced -together in \autoref{cha:maincls}. Where an example or note only -applies to one or two of the three classes, e.\,g., -\Class{scrartcl}\OnlyAt{\Class{scrartcl}}, it is called out in the -margin, as -shown here with \Class{scrartcl}. +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 @@ -157,21 +152,24 @@ shown here with \Class{scrartcl}. and useful to you. \end{Explain} +At this point you should know enough to understand the this guide. +It might, however, still be worth reading the rest of this chapter. \section{History of {\KOMAScript}}\seclabel{history} -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. +%\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 @@ -180,27 +178,26 @@ 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. -Beginning 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.'' +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} @@ -209,9 +206,9 @@ needing documentation; hence this ``small guide.'' 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 +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 @@ -220,76 +217,132 @@ 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. -Thanks go as well to 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 in the {\TeX} newsgroups and mailing -lists who answer questions and have helped me to provide support for -{\KOMAScript}. +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} was 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. +{\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.}% + 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.} + 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 by their package management software. It is -recommended to make installations and updates of \KOMAScript{} using these -tools. Nevertheless the manual installation without using the package managers -has been described in the file \File{INSTALL.txt}, that is part of every legal -\KOMAScript{} bundle. You should also read the documentation that comes with -the {\TeX} distribution you are using. +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, one of the {\KOMAScript} packages, or another part -of {\KOMAScript}, please do the following: first have a look on CTAN to see if -a newer version of {\KOMAScript} is available; if a newer version is -available, % in this case -install the -applicable section and try again. - -If you are using the most recent version of {\KOMAScript} and still have a -bug, please provide a short {\LaTeX} document that demonstrates the -problem. You should only use the packages and definitions needed to -demonstrate the problem; do not use any unusual packages. - -By preparing such an example it often becomes clear whether the problem is -truly a {\KOMAScript} bug or something else. To find out the version numbers -of all packages in use, simply put \Macro{listfiles} in the preamble of your -example and read the end of the \File{log}-file. +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. -Please report {\KOMAScript} (only) bugs 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 -also include such an example as part of your question. +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 an experienced {\KOMAScript} user you may want to look at some -more advanced examples and information. These you will find on the -{\KOMAScript} documentation web site \cite{homepage}. The main language of the -site is German, but nevertheless English is welcome. +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: diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/japanlco.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/japanlco.tex index 8d16d34e560..6503afae061 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/japanlco.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/japanlco.tex @@ -1,6 +1,6 @@ % ====================================================================== % japanlco.tex -% Copyright (c) Gernot Hassenpflug and Markus Kohm, 2001-2017 +% Copyright (c) Gernot Hassenpflug and Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % japanlco.tex -% Copyright (c) Gernot Hassenpflug und Markus Kohm, 2001-2017 +% Copyright (c) Gernot Hassenpflug und Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -50,22 +50,22 @@ % \KOMAProvidesFile{japanlco.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-21 10:37:34 +0100 (Wed, 21 Mar 2018) $ KOMA-Script guide (appendix: japanlco)] \appendix \chapter[{Japanese Letter Support for \Class{scrlttr2}}] -{Japanese Letter Support for \Class{scrlttr2}\footnote{This chapter has been - written originally by Gernot Hassenpflug.}} +{Japanese Letter Support for \Class{scrlttr2}\footnote{This chapter was + originally written by Gernot Hassenpflug.}} \labelbase{japanlco} \Index{letter>Japanese} -Since version~2.97e \Class{scrlttr2} provides support not only for European -ISO~envelope sizes and window envelopes, but also for Japanese envelopes, in -the form of \File{lco} files which set the layout of the paper. This chapter -documents the support, and provides a few examples of using the provided -\File{lco} files for printing letters intended for Japanese envelopes. +Since version~2.97e, \Class{scrlttr2} has provided support not only for +European ISO~envelope sizes and window envelopes but also for Japanese +envelopes, in the form of \File{lco} files which set the layout of the paper. +This chapter documents this support and provides a few examples of using the +provided \File{lco} files to print letters intended for Japanese envelopes. \section{Japanese standard paper and envelope sizes} \seclabel{PaperEnvelope} @@ -74,7 +74,7 @@ The Japan Industrial Standard (JIS) defines paper sizes and envelope sizes for national use, which both overlap with the ISO and US sizes and include some metricated traditional Japanese sizes. Envelope window size and position have not been defined internationally as yet; hence, there exists a plethora of -envelopes with differing window sizes and positions. The below subsections +envelopes with differing window sizes and positions. The following subsections give some background on Japanese paper sizes and envelopes. \subsection{Japanese paper sizes} @@ -82,7 +82,7 @@ give some background on Japanese paper sizes and envelopes. The JIS defines two main series of paper sizes: \begin{enumerate} -\item the JIS A-series, which is identical to the ISO A-series, but +\item the JIS A-series, which is identical to the ISO A-series but with slightly different tolerances; and \item the JIS B-series, which is not identical to the ISO/DIN B-series. Instead, the JIS B-series paper has an area 1.5 times that @@ -94,7 +94,7 @@ The JIS defines two main series of paper sizes: Both JIS A-series and B-series paper is widely available in Japan and most photocopiers and printers are loaded with at least A4 and B4 paper. The -ISO/JIS~A-series, and the different ISO and JIS~B-series sizes are listed in +ISO/JIS~A-series and the different ISO and JIS~B-series sizes are listed in \autoref{tab:japanlco.jpapersizes1}. %% ISO/JIS standard comparison @@ -125,7 +125,7 @@ A12 & 13 & 18 & & \multicolumn2l{} & B12 & 16 & 22 \\ \end{tabular} \label{tab:japanlco.jpapersizes1} \footnotetext[1]{Although Japan's official postcard size - appears to be A6, it is actually 100$\times$148\Unit{mm}, 5 millimeters + appears to be A6, it is actually 100$\times$148\Unit{mm}, 5 millimetres narrower than A6.} \end{minipage} \end{table} @@ -134,9 +134,9 @@ There are also a number of traditional paper sizes, which are now used mostly only by printers. The most common of these old series are the Shiroku-ban and the Kiku paper sizes. The difference of these types compared to the JIS~B-series are shown in \autoref{tab:japanlco.jpapersizes2}. -Finally, there are some common stationary sizes, listed in +Finally, there are some common stationery sizes, listed in \autoref{tab:japanlco.jpapersizes3}. You may come across these when buying -stationary. +stationery. %% JIS B-series variants \begin{table} @@ -160,8 +160,8 @@ Size & \multicolumn{2}{l}{W$\times$H in mm} & \multicolumn{2}{l}{W$\times$H in %% Japanese contemporary sizes \begin{table} \centering -\caption[{Main Japanese contemporary stationary}] -{Main Japanese contemporary stationary}%; trim sizes are given with width +\caption[{Main Japanese contemporary stationery}] +{Main Japanese contemporary stationery}%; trim sizes are given with width % preceding height, both in millimeters} \begin{tabular}{lr@{$\times$}ll}\toprule Name & \multicolumn{2}{l}{W$\times$H in mm} & Usage and Comments \\ \midrule @@ -179,28 +179,26 @@ Ippitsu sen & 82 & 185 & ``note paper'' \\ \label{tab:japanlco.jpapersizes3} \end{table} -The ISO~C-series is not a paper size as such, but is a standard -developed for envelopes, intended for the corresponding A-series -paper, and is discussed in the next subsection. +The ISO~C-series is not a paper size as such but a standard developed for +envelopes and intended for the corresponding A-series paper. It is discussed +in the next subsection. %\clearpage \subsection{Japanese envelope sizes} \seclabel{envelope} -ISO (International Organization for Standardization) envelope sizes -are the official international metric envelope sizes; however, Japan -uses also JIS and metricated traditional envelope sizes. Sizes -identified as nonstandard do not conform to Universal Postal Union -requirements for correspondence envelopes. +ISO (International Organization for Standardization) envelope sizes are the +official international metric envelope sizes; however, Japan uses also JIS and +metricated traditional envelope sizes. Sizes identified as non-standard do not +conform to Universal Postal Union requirements for correspondence envelopes. \subsubsection{ISO envelope sizes} -The ISO C-series envelope sizes, and possibly B-series envelope sizes, -are available in Japan. C-series envelopes can hold the corresponding -A-series paper, while B-series envelopes can hold either the -corresponding A-series paper or the corresponding C-series -envelope. The ISO envelope sizes commonly for Japan are listed in -\autoref{tab:japanlco.jenvsizes1}, with the corresponding paper they -are intended for, and the folding required. +The ISO C-series envelope sizes, and possibly B-series envelope sizes, are +available in Japan. C-series envelopes can hold the corresponding A-series +paper, while B-series envelopes can hold either the corresponding A-series +paper or the corresponding C-series envelope. The ISO envelope sizes commonly +for Japan are listed in \autoref{tab:japanlco.jenvsizes1}, with the +corresponding paper they are intended for, and the folding required. %%%%%% JIS Japanese Envelopes @@ -230,19 +228,19 @@ Name & \multicolumn2l{W$\times$H in mm} & Usage and Comments \\ %\endlastfoot \midrule C0 & 917 & 1297 & for flat A0 sheet; \\* - & \multicolumn2l{} & nonstandard \\ + & \multicolumn2l{} & non-standard \\ C1 & 648 & 917 & for flat A1 sheet; \\* - & \multicolumn2l{} & nonstandard \\ + & \multicolumn2l{} & non-standard \\ C2 & 458 & 648 & for flat A2 sheet, A1 sheet folded in half; \\* - & \multicolumn2l{} & nonstandard \\ + & \multicolumn2l{} & non-standard \\ C3 & 324 & 458 & for flat A3 sheet, A2 sheet folded in half; \\* - & \multicolumn2l{} & nonstandard \\ + & \multicolumn2l{} & non-standard \\ B4 & 250 & 353 & C4 envelope \\ C4 & 229 & 324 & for flat A4 sheet, A3 sheet folded in half; \\* - & \multicolumn2l{} & very common; nonstandard \\ + & \multicolumn2l{} & very common; non-standard \\ B5 & 176 & 250 & C5 envelope \\ C5 & 162 & 229 & for flat A5 sheet, A4 sheet folded in half; \\* - & \multicolumn2l{} & very common; nonstandard \\ + & \multicolumn2l{} & very common; non-standard \\ B6 & 125 & 176 & C6 envelope; A4 folded in quarters; \\* & \multicolumn2l{} & very common \\ C6 & 114 & 162 & for A5 sheet folded in half, \\* @@ -251,9 +249,9 @@ C6 & 114 & 162 & for A5 sheet folded in half, \\* C6/C5 & 114 & 229 & A4 sheet folded in thirds; \\* & \multicolumn2l{} & very common \\ C7/6 & 81 & 162 & for A5 sheet folded in thirds; uncommon; \\* - & \multicolumn2l{} & nonstandard \\ + & \multicolumn2l{} & non-standard \\ C7 & 81 & 114 & for A5 sheet folded in quarters; uncommon; \\* - & \multicolumn2l{} & nonstandard \\ + & \multicolumn2l{} & non-standard \\ C8 & 57 & 81 & \\ C9 & 40 & 57 & \\ C10 & 28 & 40 & \\ @@ -274,7 +272,7 @@ DL\footnotemark[1] & 110 & 220 & for A4 sheet folded in thirds, \\* \subsubsection{JIS and traditional envelope sizes} The JIS classifies envelopes into three categories based on the -general shape of the envelope, and where the flap is located: +general shape of the envelope and where the flap is located: \begin{description} \item[You:] these envelopes are of the `commercial' type, rectangular, @@ -292,9 +290,8 @@ general shape of the envelope, and where the flap is located: rates. `Kaku-kei' means square-style. \end{description} -The main JIS and traditional envelope sizes and the corresponding -paper and its required folding are listed in -\autoref{tab:japanlco.jenvsizes2}. +The main JIS and traditional envelope sizes, the corresponding paper, and +its required folding are listed in \autoref{tab:japanlco.jenvsizes2}. %% JIS and other envelope sizes %\begin{table} @@ -322,9 +319,9 @@ JIS & Name & \multicolumn2l{W$\times$ in mm} & Usage and Comments \\ \endlastfoot \midrule & Chou 1 & 142 & 332 & for A4 folded in half lengthwise;\\* - & & \multicolumn2l{} & nonstandard \\ + & & \multicolumn2l{} & non-standard \\ Yes & Chou 2 & 119 & 277 & for B5 folded in half lengthwise;\\* - & & \multicolumn2l{} & nonstandard \\ + & & \multicolumn2l{} & non-standard \\ Yes & Chou 3 & 120 & 235 & for A4 folded in thirds;\\* & & \multicolumn2l{} & very common \\ & Chou 31 & 105 & 235 & for A4 folded in thirds \\ @@ -333,27 +330,27 @@ Yes & Chou 3 & 120 & 235 & for A4 folded in thirds;\\* Yes & Chou 4 & 90 & 205 & for JIS B5 folded in fourths\footnotemark[3];\\* & & \multicolumn2l{} & very common \\ & Kaku A3 & 320 & 440 & for A3 flat, A2 folded in half\\* - & & \multicolumn2l{} &; nonstandard \\ + & & \multicolumn2l{} &; non-standard \\ & Kaku 0 & 287 & 382 & for B4 flat, B3 folded in half;\\* - & & \multicolumn2l{} & nonstandard \\ + & & \multicolumn2l{} & non-standard \\ & Kaku 1 & 270 & 382 & for B4 flat, B3 folded in half;\\* - & & \multicolumn2l{} & nonstandard \\ + & & \multicolumn2l{} & non-standard \\ Yes & Kaku 2 & 240 & 332 & for A4 flat, A3 folded in half;\\* - & & \multicolumn2l{} & nonstandard \\ + & & \multicolumn2l{} & non-standard \\ & Kaku & 229 & 324 & for A4 flat, A3 folded in half;\\* & Kokusai A4 & \multicolumn2l{} & same size as ISO C4;\\* - & & \multicolumn2l{} & nonstandard \\ + & & \multicolumn2l{} & non-standard \\ Yes & Kaku 3 & 216 & 277 & for B5 flat, B4 folded in half;\\* - & & \multicolumn2l{} & nonstandard \\ + & & \multicolumn2l{} & non-standard \\ Yes & Kaku 4 & 197 & 267 & for B5 flat, B4 folded in half;\\* - & & \multicolumn2l{} & nonstandard \\ + & & \multicolumn2l{} & non-standard \\ Yes & Kaku 5 & 190 & 240 & for A5 flat, A4 folded in half\\* - & & \multicolumn2l{} &; nonstandard \\ + & & \multicolumn2l{} &; non-standard \\ Yes & Kaku 6 & 162 & 229 & for A5 flat, A4 folded in half;\\* & & \multicolumn2l{} & same size as ISO C5;\\* - & & \multicolumn2l{} & nonstandard \\ + & & \multicolumn2l{} & non-standard \\ Yes & Kaku 7 & 142 & 205 & for B6 flat, B5 folded in half;\\* - & & \multicolumn2l{} & nonstandard \\ + & & \multicolumn2l{} & non-standard \\ Yes & Kaku 8 & 119 & 197 & pay envelope (for salaries, wages)\\* & & \multicolumn2l{} &; common for direct mail \\ Yes & You 0\footnotemark[1] & 235 & 120 & for A4 folded in thirds;\\* @@ -361,7 +358,7 @@ Yes & You 0\footnotemark[1] & 235 & 120 & for A4 folded in thirds;\\* & & \multicolumn2l{} & `Open Side' style flap \\ & You 0\footnotemark[1] & 197 & 136 & for kyabine\footnotemark[1] (cabinet) size photos \\* & & \multicolumn2l{} & (165\Unit{mm}$\times$120\Unit{mm});\\* - & & \multicolumn2l{} & nonstandard \\ + & & \multicolumn2l{} & non-standard \\ & You 1\footnotemark[2] & 176 & 120 & for B5 folded in quarters \\ & You 1\footnotemark[2] & 173 & 118 & for B5 folded in quarters \\ Yes & You 2 & 162 & 114 & for A5 folded in half,\\* @@ -398,8 +395,8 @@ sizes and locations are listed in \autoref{tab:japanlco.jwinsizes1}. \begin{table} \begin{minipage}{\textwidth}\renewcommand*{\footnoterule}{} \centering -\caption[{Supported Japanese envelope types and the window sizes and - locations}] {Supported Japanese envelope types and the window sizes and +\caption[{Supported Japanese envelope types, window sizes, and + locations}] {Supported Japanese envelope types, window sizes, and locations.} \begin{tabular}{lllll} \toprule @@ -437,8 +434,8 @@ You 4 & A & 90$\times$45 & l 23, t 13 & \Option{NipponEL} \\ \bottomrule \end{tabular}% \footnotetext[1]{Names (acting as subtype information) are taken from - the manufacturer catalog.}% -\footnotetext[2]{Given as width by height in millimeters.}% + the manufacturer catalogue.}% +\footnotetext[2]{Given as width by height in millimetres.}% \footnotetext[3]{Given as offset from left (l) or right (r), followed by offset from bottom (b) or top (t).}% \footnotetext[4]{The \File{lco} file, which provides support (see @@ -451,18 +448,17 @@ You 4 & A & 90$\times$45 & l 23, t 13 & \Option{NipponEL} \\ \end{table} \section{Provided \File{lco} files} -In \Class{scrlttr2} support is provided for Japanese envelope and +In \Class{scrlttr2}, support is provided for Japanese envelope and window sizes through a number of \File{lco} files which customize the -foldmarks required for different envelope sizes and subvariants with +fold marks required for different envelope sizes and subvariants with different window positions and sizes. -The provided \File{lco} files together with the envelope types for -which they provide support are listed at -\autoref{tab:japanlco.lcolist}. See \autoref{tab:japanlco.jenvsizes1} -for the full list of Japanese envelopes and the paper they take, and -\autoref{tab:japanlco.jwinsizes1} for the common window sizes and -locations. The rightmost column indicates which \File{lco} file -provides the support. +The \File{lco} files provided together with the envelope types that they +support are listed at \autoref{tab:japanlco.lcolist}. See +\autoref{tab:japanlco.jenvsizes1} for the full list of Japanese envelopes and +the paper they take, and \autoref{tab:japanlco.jwinsizes1} for the common +window sizes and locations. The rightmost column indicates which \File{lco} +file provides the support. The tolerances for location is about 2\Unit{mm}, so it is possible to accommodate all the envelope and window variants of @@ -495,8 +491,8 @@ location\footnotemark[1] \\ \end{minipage} \end{table} -\section{Examples of Japanese letter usage} -Assume you want to write a letter on A4 size paper and will post it in +\section{Examples of Japanese Letter Usage} +Suppose you want to write a letter on A4 size paper and will post it in a Japanese envelope. If the envelope has no window, then it is enough to determine whether the envelope dimensions match a European one\,---\,the standard \File{DIN.lco} style may suffice for many such @@ -504,18 +500,18 @@ cases. If you wish to use a windowed envelope, please note that owing to the large variety, not all existing subvariants are currently -supported. If you should note that you particular windowed envelope -has its window dimensions and positions significantly (more than -approximately 2\Unit{mm}) different from any of the supported subvariants, +supported. If you notice that the window dimensions and positions +of your particular windowed envelope differ significantly (more than +approximately 2\Unit{mm}) from those of any of the supported subvariants, please contact the author of {\KOMAScript} to obtain support as soon as -possible, and in the meanwhile create a customized \File{lco} file for your +possible, and in the meantime, create a customized \File{lco} file for your own use, using one of the existing ones as a template and reading the {\KOMAScript} documentation attentively. If your window envelope subvariant is supported, this is how you would go about using it: simply select the required \File{lco} file and -activate the horizontal and vertical foldmarks as required. Another, -independent, mark is the punching mark which divides a sheet in two +activate the horizontal and vertical fold marks as required. Another, +independent, mark is the hole-punch mark, which divides a sheet in two horizontally for easy punching and filing. \subsection{Example 1:} diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/linkalias.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/linkalias.tex index 16dcdc1d4e8..3d4328a4891 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/linkalias.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/linkalias.tex @@ -39,7 +39,7 @@ % \KOMAProvidesFile{linkalias.tex} - [$Date: 2016-11-20 17:40:30 +0100 (Sun, 20 Nov 2016) $ + [$Date: 2017-12-03 22:49:27 +0100 (Sun, 03 Dec 2017) $ link aliases for the free version] \makeatletter @@ -67,3 +67,6 @@ \lalias{desc:maincls-experts.cmd.AfterBibliographyPreamble}{sec:maincls-experts.addInfos} \lalias{desc:maincls-experts.option.fontsize}{sec:maincls-experts.addInfos} \lalias{desc:maincls-experts.cmd.raggedsection}{sec:maincls-experts.coexistence} +\lalias{desc:maincls-experts.cmd.thepage}{sec:maincls-experts.addInfos} +\lalias{desc:maincls-experts.cmd.pagemark}{sec:maincls-experts.addInfos} +\lalias{desc:maincls-experts.cmd.the/Zaehler/}{sec:maincls-experts.addInfos} diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/preface.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/preface.tex index 3047b682368..873f3039879 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/preface.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/preface.tex @@ -1,6 +1,6 @@ % ====================================================================== % preface.tex -% Copyright (c) Markus Kohm, 2008-2017 +% Copyright (c) Markus Kohm, 2008-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % preface.tex -% Copyright (c) Markus Kohm, 2008-2017 +% Copyright (c) Markus Kohm, 2008-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -36,28 +36,82 @@ % ====================================================================== \KOMAProvidesFile{preface.tex} - [$Date: 2017-01-16 07:48:29 +0100 (Mon, 16 Jan 2017) $ - Preface to the KOMA-Script book] -%\translator{Markus Kohm} + [$Date: 2018-03-28 11:44:09 +0200 (Wed, 28 Mar 2018) $ + Preface to version 3.25] +\translator{Markus Kohm\and Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-03-12 -\addchap{Preface to the English \KOMAScript{} Guide} +\addchap{Preface to \KOMAScript~3.25} -The translation of the German \KOMAScript{} guide is still a work in progress -and a never ending story. I always try to have an English user guide with all -descriptions of the German one. But as long as I have to do the primary -translation, these translations not only can but should be improved. +The \KOMAScript~3.25 manual,\---\,especially the German version\,---\,once +again benefits from the fact that a new edition of the print version +\cite{book:komascript} and the eBook version \cite{ebook:komascript} will be +published at almost the same time as this version. This has led to many +improvements which also affect the free manual, in both the German and the +English version. -The translation of \autoref{cha:tocbasic} has still an example in German. A -proficient English speaker with basic TeX knowledge could improve the -translation. A large part of \autoref{cha:scrjura} has been translated by -Alexander Willand. The remaining part may need improvement. +One of these improvements is the linking to the explanations of commands, +environments, options, etc., within the manual. To avoid the temptation to +jump to the beginning of the explanation within the explanation itself, and +so to avoid reading recursively, as it were, these links only take effect +if they actually lead away from the current location. -So this English guide is complete but nevertheless not as good as the German -one. Currently there are only a few editors for the English guide, who improve -my translation for free. Many thanks to them for their very good job! -Nevertheless, additional editors or translators would be welcome! +Another important improvement to the English guide has been accomplished by +Karl Hagen, who has newly translated the entire manual. Many, many thanks to +him! Additional editors or translators, however, would still be welcome! + +\iffree{Readers of this free, screen version, however, still have to live with + some restrictions. So some information\,---\,mainly intended for advanced + users or capable of turning an ordinary user into an advanced one\,---\,is + reserved for the printed book, which currently exists only in German. As a + result, some links in this manual lead to a page that simply mentions this + fact. In addition, the free version is scarcely suitable for making a + hard-copy. The focus, instead, is on using it on screen, in parallel with + the document you are working on. It still has no optimized wrapping but is + almost a first draft, in which both the paragraph and page breaks are in + some cases quite poor. Corresponding optimizations are reserved for the + German book editions.}{} + +It is not just about the manual that I now receive little criticism. For the +classes and packages as well, there are hardly any requests for new features. +For me, this means that my knowledge about user desires stagnates. So for a +few years, I mostly implemented things that I thought could be useful. +However, the feedback that I have received about these new possibilities was +largely limited to complaints that old \emph{hacks} based on undocumented +\KOMAScript{} features sometimes no longer work. Little was said about the +happiness that such dirty workarounds were no longer necessary. Therefore, I +have decided to limit extensions and improvements to \KOMAScript{} more and +more to those things that are explicitly requested by users. Could it be that +\KOMAScript{}, after only 25 years, has reached the level that it fulfils all +desires? + +Unfortunately, the declining number of error reports is not purely gratifying. +Over this period, I have often observed that those who discover a problem no +longer report it directly to me but work around it with the help of some +Internet forums. Often, there are more or less ingenious workarounds in these +forums. Although this is generally helpful, it unfortunately, as a rule, +causes the problem to remain unreported and therefore never really eliminated. +It goes without saying that such workarounds can sometimes become a problem +themselves, as mentioned in the previous paragraph. + +Thankfully, there are third parties who occasionally point out such issues. +This applies to individual contributions in a very few forums. Direct contact +with the person for whom the problem occurred is in this case usually not +possible, although it would sometimes be desirable. + +Therefore, let me please ask again explicitly that you report all suspected +bugs directly, either in German or in English. Linguistic perfection is less +important. The message should be reasonably understandable and the problem +comprehensible. A code example that is as short as possible is generally +independent of the language used. With direct contact, I can ask further +questions, if necessary. Please do not rely on anyone else to report the +problem at some point. Assume that it will only be fixed if you report it +yourself. More about error messages can be found in the first chapter of the +manual. + +\bigskip\noindent +Markus Kohm, Neckarhausen in the March rain, 2018. \endinput diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scraddr.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scraddr.tex index a4a7c5454e2..ac5ef90a5e7 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scraddr.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scraddr.tex @@ -1,6 +1,6 @@ % ====================================================================== % scraddr.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scraddr.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,36 +46,40 @@ % ====================================================================== \KOMAProvidesFile{scraddr.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-27 11:46:14 +0200 (Tue, 27 Mar 2018) $ KOMA-Script guide (chapter: scraddr)] -\translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm} +\translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm\and Karl + Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-02-05 -\chapter{Access to Address Files with \Package{scraddr}}% +\chapter{Accessing Address Files with \Package{scraddr}}% \labelbase{scraddr}% \BeginIndexGroup \BeginIndex{Package}{scraddr} +The \Package{scraddr} package is a small extension to \KOMAScript{}'s letter +class and letter package. Its goal is to make access to the data in address +files easier and more flexible. + \section{Overview}\seclabel{overview} -The package \Package{scraddr} is a small extension to the {\KOMAScript} letter -class. Its aim is to make access to the data of address files more flexible -and easier. Basically, the package implements a new loading mechanism for -address files which contain address entries in the form of \DescRef{\LabelBase.cmd.adrentry} -and newer \DescRef{\LabelBase.cmd.addrentry} commands, as described in \autoref{cha:scrlttr2} -from \DescPageRef{scrlttr2.cmd.adrentry}. +Basically, the package provides a new loading mechanism for address files +consisting of \DescRef{\LabelBase.cmd.adrentry} and the newer +\DescRef{\LabelBase.cmd.addrentry} format entries, as described in +\autoref{cha:scrlttr2} starting on \DescPageRef{scrlttr2.cmd.adrentry}. \begin{Declaration} \Macro{InputAddressFile}\Parameter{file name} \end{Declaration}% -The command \Macro{InputAddressFile} is the main command of the -\Package{scraddr}, and reads the content of the address -file\Index{address>file} given as its parameter. If the file does not -exist the command returns an error message. +The \Macro{InputAddressFile} command is the main command of \Package{scraddr}. +It reads the content of the address file\Index{address>file} given as its +parameter. If the file is not found, an error message is issued. -For every entry in the address file the command generates a set of -macros for accessing the data. For large address files this will take -a lot of {\TeX} memory. +For each entry in this address file, the command generates a set of +macros to access the data. For large address files, this will require +a lot of \TeX{} memory. +% +\EndIndexGroup \begin{Declaration}% \Macro{adrentry}\Parameter{Lastname}\Parameter{Firstname}% @@ -89,15 +93,12 @@ a lot of {\TeX} memory. \Macro{adrchar}\Parameter{initial}% \Macro{addrchar}\Parameter{initial}% \end{Declaration}% -The structure of the address entries in the address file was discussed -in detail in \autoref{sec:scrlttr2.addressFile} from -\DescPageRef{scrlttr2.cmd.adrentry} onwards. The division of -the address file with the help of \Macro{adrchar} or \Macro{addrchar}, -also discussed therein, has no meaning for \Package{scraddr} and is -simply ignored. - -The commands for accessing the data are given by the name of the data -field they are intended for. +The structure of the address entries in the address file was discussed in +detail in \autoref{sec:scrlttr2.addressFile}, starting on +\DescPageRef{scrlttr2.cmd.adrentry}. The subdivision of the address file with +the help of \Macro{adrchar} or \Macro{addrchar}, also discussed there, has no +meaning for \Package{scraddr} and is simply ignored by the package.% +\EndIndexGroup \begin{Declaration} \Macro{Name}\Parameter{key}% @@ -111,35 +112,32 @@ field they are intended for. \Macro{FreeIII}\Parameter{key}% \Macro{FreeIV}\Parameter{key} \end{Declaration}% -These commands give access to data of your address file. The last -parameter, i.\,e., parameter 8 for the \DescRef{\LabelBase.cmd.adrentry} entry and -parameter 9 for the \DescRef{\LabelBase.cmd.addrentry} entry, is the identifier of an -entry, thus the \PName{key} has to be unique and non-blank. The -\PName{key} should only be composed of multiple uppercase letters out of the -namespace of \TeX{} macro names. +These commands give access to data of your address file. The last parameter, +that is, parameter 8 for the \DescRef{\LabelBase.cmd.adrentry} entry and +parameter 9 for the \DescRef{\LabelBase.cmd.addrentry} entry, is the +identifier of an entry, thus the \PName{key} has to be unique and non-empty. +To guarantee safe functioning, you should use only ASCII letters in the +\PName{key}. -If the file contains more than one entry with the same \PName{key} -value, the last occurrence will be used.% -% -\EndIndexGroup -% -\EndIndexGroup +Furthermore, if the file contains more than one entry with the same +\PName{key} name, the last occurrence will be used.% % \EndIndexGroup \section{Usage}\seclabel{usage} - -First of all, we need an address file with valid address entries. In -this example the file has the name \File{lotr.adr} and contains the -following entries. +\BeginIndexGroup +\BeginIndex[indexother]{Cmd}{addrentry}% +\BeginIndex[indexother]{Cmd}{adrentry}% +To use the package, we need a valid address file. For example, the file +\File{lotr.adr} contains the following entries: \begin{lstcode} \addrentry{Baggins}{Frodo}% {The Hill\\ Bag End/Hobbiton in the Shire}{}% {Bilbo Baggins}{pipe-weed}% {the Ring-bearer}{Bilbo's heir}{FRODO} \adrentry{Gamgee}{Samwise}% - {Bagshot Row 3\\Hobbiton in the Shire}{}% + {3 Bagshot Row\\Hobbiton in the Shire}{}% {Rosie Cotton}{taters}% {the Ring-bearer's faithful servant}{SAM} \adrentry{Bombadil}{Tom}% @@ -148,64 +146,85 @@ following entries. {The Master of Wood, Water and Hill}{TOM} \end{lstcode} -The 4th parameter, the telephone number, has been -left blank. If you know the story behind these addresses you will -agree that a telephone number makes no sense here, and besides, it -should simply be possible to leave them out. +The fourth parameter, the telephone number, has been left blank, since there +are no phones in Middle Earth. And as you can see, blank fields are possible. +On the other hand, you cannot simply omit an argument altogether. -The command -\Macro{InputAddressFile} is used to load the address file shown above: +\BeginIndexGroup +\BeginIndex[indexother]{Cmd}{InputAddressFile} +With the \Macro{InputAddressFile} command described above, we read the address +file into our letter document: \begin{lstcode} \InputAddressFile{lotr} \end{lstcode} +\EndIndexGroup - -With the help of the commands introduced in this chapter we can now -write a letter to old \textsc{Tom Bombadil}. In this letter we ask -him if he can remember two fellow-travelers from Elder Days. +\BeginIndexGroup +\BeginIndex[indexother]{Cmd}{Name}% +\BeginIndex[indexother]{Cmd}{Address}% +\BeginIndex[indexother]{Cmd}{FirstName}% +\BeginIndex[indexother]{Cmd}{LastName}% +\BeginIndex[indexother]{Cmd}{FreeI}% +\BeginIndex[indexother]{Cmd}{FreeII}% +\BeginIndex[indexother]{Cmd}{FreeIII}% +\BeginIndex[indexother]{Cmd}{FreeIV}% +\BeginIndex[indexother]{Cmd}{Comment}% +With the help of the commands introduced in this chapter we can now write a +letter to old \textsc{Tom Bombadil}, in which we ask him if he can remember +two companions from olden times. \begin{lstcode} \begin{letter}{\Name{TOM}\\\Address{TOM}} \opening{Dear \FirstName{TOM} \LastName{TOM},} - or \FreeIII{TOM}, how your delightful \FreeI{TOM} calls you. Can - you remember Mr.\,\LastName{FRODO}, strictly speaking - \Name{FRODO}, since there was Mr.\,\FreeI{FRODO} too. He was - \Comment{FRODO} in the Third Age and \FreeIV{FRODO} \Name{SAM}, - \Comment{SAM}, has attended him. + Or \FreeIII{TOM}, as your beloved \FreeI{TOM} calls you. Do + you still remember Mr \LastName{FRODO}, or more precisely + \Name{FRODO}, since there was also Mr \FreeI{FRODO}. He was + \Comment{FRODO} in the Third Age and \FreeIV{FRODO}. \Name{SAM}, + \Comment{SAM}, accompanied him. - Their passions were very worldly. \FirstName{FRODO} enjoyed - smoking \FreeII{FRODO}, his attendant appreciated a good meal with - \FreeII{SAM}. + Their passions were very worldly. \FirstName{FRODO} enjoyed + smoking \FreeII{FRODO}. His companion appreciated a good meal + with \FreeII{SAM}. Do you remember? Certainly Mithrandir has told you much - about their deeds and adventures . + about their deeds and adventures. \closing{``O spring-time and summer-time and spring again after!\\ O wind on the waterfall, and the leaves' laughter!''} \end{letter} \end{lstcode} -In the address of letters often both firstname and lastname are required, als -shown above in \DescRef{scrlttr2.cmd.opening}. Thus, the command -\Macro{Name}\PParameter{key} is an abridgement for -\Macro{FirstName}\PParameter{key} \Macro{LastName}\PParameter{key}. - -The 5th and 6th parameters of the \DescRef{\LabelBase.cmd.adrentry} or \DescRef{\LabelBase.cmd.adrentry} -commands are for free use. They are accessible with the commands -\Macro{FreeI} and \Macro{FreeII}. In this example, the 5th parameter contains -the name of a person who is the most important in the life of the entry's -person, the 6th contains the person's passion. The 7th parameter is a comment -or in general also a free parameter. The commands \Macro{Comment} or -\Macro{FreeIII} give access to this data. Use of \Macro{FreeIV} is only valid -for \DescRef{\LabelBase.cmd.addrentry} entries; for \DescRef{\LabelBase.cmd.adrentry} entries -it results in an error. More on this is covered in the next section. +You can also produce the combination of \Macro{FirstName}\Parameter{key} and +\Macro{LastName}\Parameter{key} used in the \DescRef{scrlttr2.cmd.opening} of +this letter with \Macro{Name}\PParameter{key}. + +You can use the fifth and sixth parameters of the +\DescRef{\LabelBase.cmd.adrentry} or \DescRef{\LabelBase.cmd.adrentry} for any +purpose you wish. You can access them with the \Macro{FreeI} and +\Macro{FreeII} commands. In this example, the fifth parameter contains the +name of the most important person in the life of the person in the entry. The +sixth contains the person's favourite thing. The seventh parameter is a +comment or in general also a free parameter. You can access it with the +\Macro{Comment} or \Macro{FreeIII} commands. \Macro{FreeIV} is only valid for +\DescRef{\LabelBase.cmd.addrentry} entries. For +\DescRef{\LabelBase.cmd.adrentry} entries, it results in an error. You can +find more details in the next section. +% +\EndIndexGroup +\EndIndexGroup \section{Package Warning Options} -As mentioned above, the command \Macro{FreeIV} leads to an error if it is used -for \DescRef{\LabelBase.cmd.adrentry} entries. How \Package{scraddr} reacts in -such a situation is decide by package options. +As mentioned above, you cannot use the \Macro{FreeIV} command with +\DescRef{\LabelBase.cmd.adrentry} entries. However, you can configure how +\Package{scraddr} reacts in such a situation by package options. +Note\textnote{Attention!} that this package does not support the extended +options interface with \DescRef{maincls.cmd.KOMAoptions} and +\DescRef{maincls.cmd.KOMAoption}. You should therefore specify the options +either as global options in \DescRef{maincls.cmd.documentclass} or as local +options in \DescRef{maincls.cmd.usepackage} + \begin{Declaration} \Option{adrFreeIVempty}% @@ -213,25 +232,22 @@ such a situation is decide by package options. \Option{adrFreeIVwarn}% \Option{adrFreeIVstop}% \end{Declaration}% -These four options allow the user to choose between \emph{ignore} and -\emph{rupture} during the {\LaTeX} run if \Macro{FreeIV} has been used -with an \DescRef{\LabelBase.cmd.adrentry} entry. +These four options let you choose from four different reactions, ranging +from \emph{ignore} to \emph{abort}, if \Macro{FreeIV} is used +within an \DescRef{\LabelBase.cmd.adrentry} entry. \begin{labeling}[~--]{\Option{adrFreeIVempty}} \item[\Option{adrFreeIVempty}] the command \Macro{FreeIV} will be ignored \item[\Option{adrFreeIVshow}] - ``(entry FreeIV undefined at \PName{key})'' will be - written as warning in the text + the warning ``(entry FreeIV undefined at \PName{key})'' will be + written in the text \item[\Option{adrFreeIVwarn}] - writes a warning in the logfile + a warning is written in the logfile \item[\Option{adrFreeIVstop}] - the {\LaTeX} run will be interrupted with an error message + the \LaTeX{} run will abort with an error message \end{labeling} -To choose the desired reaction, one of these options can be given in -the optional argument of the \Macro{usepackage} command. The default -setting is \Option{adrFreeIVshow}.% -% +The default setting is \Option{adrFreeIVshow}.% \EndIndexGroup % \EndIndexGroup diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex index a6f4778ea9c..714e020a933 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrbase.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrbase.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,146 +46,106 @@ % ====================================================================== \KOMAProvidesFile{scrbase.tex} - [$Date: 2017-04-22 16:16:15 +0200 (Sat, 22 Apr 2017) $ + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ KOMA-Script package scrbase] -\translator{Markus Kohm\and Melvin Hendrix} +\translator{Markus Kohm\and Melvin Hendrix\and Karl Hagen} -% Date of the translated German file: 2017-04-13 +% Date of the translated German file: 2018-02-15 -\chapter{Basic Functions of Package \Package{scrbase}} +\chapter{Basic Functions in the \Package{scrbase} Package} \labelbase{scrbase} \BeginIndexGroup \BeginIndex{Package}{scrbase}% -The package \Package{scrbase} provides basic features designed and implemented -for use by authors of packages and classes. However, \Package{scrbase} cannot -only by used for wrapper classes related to \KOMAScript{} class. Authors of -classes that have nothing to do with \KOMAScript{} can benefit from -\Package{scrbase} functionality. +The \Package{scrbase} package provides basic features intended for use by +authors of packages and classes. Its use is not limited merely to wrapper +classes which in turn load a \KOMAScript{} class. Authors of classes that +otherwise have nothing to do with \KOMAScript{} can also benefit from the +functionality of \Package{scrbase}. \section{Loading the Package} \seclabel{loadit} -Whereas users load packages using \Macro{usepackage}, authors of packages or +Whereas users load packages with \Macro{usepackage}, authors of packages or classes should use \Macro{RequirePackage}\IndexCmd{RequirePackage}. Authors of -wrapper packages may also use \Macro{RequirePackageWithOptions}. Command -\Macro{RequirePackage} has the same optional argument for package options like -\Macro{usepackage}. In contrast, \Macro{RequirePackageWithOptions} does not -have an optional argument but passes all options given when loading the -wrapper package to the required package. See \cite{latex:clsguide} for more -information about these commands. - -The package \Package{scrbase} needs the functionality of package -\Package{keyval}\IndexPackage{keyval} internally. This may be provided by -package \Package{xkeyval} alternatively. Package \Package{scrbase} loads -\Package{keyval} as needed. - -The package \Package{keyval} provides definition of keys and assignment of -values to these keys. The options provided by \Package{scrbase} also use -\Package{keyval} syntax: \PName{key}\texttt{=}\PName{value}. +wrapper packages can also use \Macro{RequirePackageWithOptions}. The +\Macro{RequirePackage} command has the same optional argument for package +options as \Macro{usepackage}. In contrast, \Macro{RequirePackageWithOptions} +does not have an optional argument but passes to this package all the options +that were previously given when loading the wrapper package or class. See +\cite{latex:clsguide} for more information about these commands. -\begin{Declaration} - \OptionVName{internalonly}{value} -\end{Declaration} -Package \Package{scrbase} provides some commands for conditional -execution. The primary names for these are builds like -\Macro{scr@\PName{name}}, which are internal commands. \KOMAScript{} only uses -these internal commands internally. Authors of packages and classes may use -these internal commands, too, but should not redefine them. Because some of -these commands are useful for users, too, they are provided as -\Macro{\PName{name}} normally. But eventually, other packages may provide -commands with the same name but different syntax or different -functionality. As this would result in an conflict, \Package{scrbase} can -suppress the definition of the user commands \Macro{\PName{name}}. Using -option \Option{internalonly} without \PName{value} will define only the -internal commands and suppress definition of all the user commands for -conditional execution. Alternatively, the user may give all the commands that -should not be defined as \PName{value}, but replaces ``\Macro{}'' by -``\texttt{/}''. - -Authors of packages and classes normally should not use this option. Users may -use it with or without \PName{value} either as a global option with -\Macro{documentclass} or using \Macro{PassOptionsToPackage}. -\begin{Example} - The user does not want \Package{scrbase} to define commands \Macro{ifVTeX} - and \DescRef{\LabelBase.cmd.ifundefinedorrelax}. Because of this, to load the class, the user - writes: -\begin{lstcode} - \documentclass% - [internalonly=/ifVTeX/ifundefinedorrelax]% - {foo} -\end{lstcode} - Class name \Class{foo} is, therefore, an placeholder - for any class in this example. The meanings of commands \Macro{ifVTeX} and - \DescRef{\LabelBase.cmd.ifundefinedorrelax} and many more commands for conditional execution - is located in \autoref{sec:scrbase.if}. -\end{Example} -% -\EndIndexGroup +The \Package{scrbase} package needs the functionality of the +\Package{keyval}\IndexPackage{keyval} package internally. This can also be +provided by the \Package{xkeyval} package. If needed, \Package{scrbase} itself +loads \Package{keyval}. + +The \Package{keyval} package lets you define keys and assign values to them. +The options provided by \Package{scrbase} also use \Package{keyval} syntax: +\PName{key}\texttt{=}\PName{value}. \section{Keys as Attributes of Families and their Members} \seclabel{keyvalue} As already mentioned in \autoref{sec:scrbase.loadit}, \Package{scrbase} uses -package \Package{keyval} for keys and values of keys. Nevertheless -\Package{scrbase} extends the functionality of \Package{keyval}. Whereas only -one family owns all keys of \Package{keyval}, \Package{scrbase} recognises -also family members. Therefore, a key may be owned by a family or by one or -more family members. Additionally, a value may be assigned to the key of a -family member, to the key of a family, or to the keys of all family members. +the \Package{keyval} package to set keys and their values. However, +\Package{scrbase} extends this functionality. Whereas with \Package{keyval} a +key belongs to only one family, \Package{scrbase} also recognizes family +members. A key can therefore belong to both a family and one or more family +members. Additionally, you can assign a value to the key of a family member, +to the key of a family, or to the keys of all family members. \begin{Declaration} \Macro{DefineFamily}\Parameter{family}% - \Macro{DefineFamilyMember}\OParameter{family member}\Parameter{family}% + \Macro{DefineFamilyMember}\OParameter{member}\Parameter{family}% \end{Declaration} -\Package{scrbase} needs to know the members of a family for different -reasons. First, you have to define a new family using -\Macro{DefineFamily}, which produces an empty member list. If the family -has already been defined nothing would happen. Nothing also means that an -already existing member list would not be overwritten. - -Next, a new member can be added to the family using -\Macro{DefineFamilyMember}. If the family does not exist, this would result in -an error message. If the member already exists, nothing happens. If the -optional \PName{family member} is omitted, the default value -``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is used. During -class or package loading \Macro{@currname} and \Macro{@currext} together -represent the file name of the class or package. +\Package{scrbase} needs to know the members of a family for various reasons. +Therefore, you must first define a new family using \Macro{DefineFamily}, +which produces an empty member list. If the family has already been defined, +nothing happens. Therefore an existing member list will not be overwritten. + +Next, you can add a new member to the family using \Macro{DefineFamilyMember}. +If the family does not exist, this will result in an error message. If the +member already exists, nothing happens. If the optional \PName{member} is +omitted, the default value +``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is used. While +the class or package is being loaded, \Macro{@currname} and \Macro{@currext} +together represent the file name of the class or package. Theoretically, it is possible, to define a member without a name using an -empty optional \PName{family member} argument. But this is the same as the -family itself. It is recommended that only letters and digits be used for -\PName{family} and the first character of \PName{family member} should not be -a letter or digit. Otherwise, it could happen that members of one family are -the same as members of another family. - -\Package{scrbase} assigns family ``\PValue{KOMA}'' to itself and adds member -``\PValue{.scrbase.sty}'' to it. Family ``\PValue{KOMA}'' is reserved to -\KOMAScript{}. For your own packages, use the name of the bundle as -\PName{family} and the name of the package as \PName{family member} of that -\PName{family}. +empty optional \PName{member} argument. But this is the same as the family +itself. You should use only letters and digits for the \PName{family} name, +and the first character of \PName{member} should be something else, preferably +a point. Otherwise, it could happen that the members of one family will clash +with the members of other families. + +\Package{scrbase} assigns the family ``\PValue{KOMA}'' to itself and adds the +member ``\PValue{.scrbase.sty}''. The values ``\PValue{KOMA}'' and +``\PValue{KOMAarg}'' are reserved for \KOMAScript{}. If you are creating a +bundle of packages, you should use the name of the bundle as \PName{family} +and the name of each package as \PName{member} of that \PName{family}. % \begin{Example} - Assume you are writing a bundle called ``master butcher''. Within that - bundle you have packages \File{salami.sty}, \File{liversausage.sty}, and - \File{kielbasa.sty}. Therefore, you decide to use family name - ``\PValue{butcher}'' and,to each of the package file, you add the lines + Suppose you are writing a bundle called ``master butcher''. Within that + bundle, you have the packages \File{salami.sty}, \File{mettwurst.sty}, + and \File{kielbasa.sty}. Therefore, you decide to use family name + ``\PValue{butcher}'' and you add the lines \begin{lstcode} \DefineFamily{butcher} \DefineFamilyMember{butcher} \end{lstcode} - When loading the three packages, this will - add the members ``\PValue{.salami.sty}'', ``\PValue{.liversausage.sty}'', + to each of the package files. When loading the three packages, this will + add the members ``\PValue{.salami.sty}'', ``\PValue{.mettwurst.sty}'', and ``\PValue{.kielbasa.sty}'' to the family ``\PValue{butcher}''. After - loading all three packages, all three member will be defined. + loading all three packages, all three members will be defined. \end{Example} % \EndIndexGroup \begin{Declaration} - \Macro{DefineFamilyKey}\OParameter{family member}\Parameter{family}% + \Macro{DefineFamilyKey}\OParameter{member}\Parameter{family}% \Parameter{key}% \OParameter{default}\Parameter{action}% \Macro{FamilyKeyState}% @@ -194,71 +154,77 @@ the same as members of another family. \Macro{FamilyKeyStateUnknownValue}% \Macro{FamilyKeyStateNeedValue} \end{Declaration} -The command \Macro{DefineFamilyKey} defines a \PName{key}. If a \PName{family - member} is given, the \PName{key} becomes an attribute of that member in the -given \PName{family}. If a \PName{family member} is not given, the member -``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is assumed. If, -later, a value is assigned to the \PName{key}, the \PName{action} will be -executed and the value made an argument of \PName{action}. So inside -\PName{action} ``\lstinline{#1}'' would be that value. If the value is -omitted, the \PName{default} is used instead. If there is no \PName{default}, -the \PName{key} can be used only with a value being defined. - -\begin{Explain} +The \Macro{DefineFamilyKey} command defines a \PName{key}. If you specify a +\PName{member}, the \PName{key} becomes an attribute of that member in the +given \PName{family}. If you do not specify a \PName{member}, the member +``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is assumed. If you +later assign a value to the \PName{key}, the \PName{action} will be +executed and the value made an argument of \PName{action}. Within +\PName{action}, ``\lstinline{#1}'' stands for that value. If you omit the value, +the \PName{default} is used instead. If you do not specify a \PName{default}, +the \PName{key} then always requires you to pass an explicit value. + +%\begin{Explain} \phantomsection\label{explain:scrbase.macro.DefineFamilyKey}% - At least + Ultimately, \begin{lstcode}[escapeinside=`'] \DefineFamilyKey[`\PName{member}']{`\PName{family}'}{`\PName{key}'} [`\PName{default}']{`\PName{action}'} \end{lstcode} - will result in a call of + results in a call to \begin{lstcode}[moretexcs={define@key},escapeinside=`'] \define@key{`\PName{family\,member}'}{`\PName{key}'} [`\PName{default}']{`\PName{extended action}'} \end{lstcode} - with \Macro{define@key} provided by package - \Package{keyval}\IndexPackage{keyval} (see \cite{package:keyval}). However, - the call of \Macro{define@key} and the \PName{action} is, in fact, - extended by additional arrangements. -\end{Explain} - -Success\ChangedAt{v3.12}{\Package{scrbase}} or failure of the execution of the -\PName{action} should be reported back to \Package{scrbase} by -\Macro{FamilyKeyState}. The package itself will take care of additional -procedures if needed. You should not report errors by yourself! The default -state before execution of \PName{action} is -\Macro{FamilyKeyStateUnknown}. This signals that it is not known whether or -not the execution is successful. If this state does not change until end of -execution of the \PName{action}, \Package{scrbase} will write a message into -the \File{log} file and assumes state \Macro{FamilyKeyStateProcessed} during -the further procedure. - -State \Macro{FamilyKeyStateProcessed} signals that the option and the value -assignment to the option are completely and successfully finished. You may -switch to this state by using \Macro{FamilyKeyStateProcessed} itself. - -State \Macro{FamilyKeyStateUnknownValue} indicates that the option was -handled, but the value, that should be assigned to the key, was unknown or not -allowed. You should use \Macro{FamilyKeyStateUnknownValue} to switch to -this state. - -State \Macro{FamilyKeyStateNeedValue} signals that the option could not be -set because it needs a value, but no value was assigned to the -key. This state is used automatically, whenever an option has been -defined without \PName{default} value and is used without value -assignment. You should not set the state using \Macro{FamilyKeyStateNeedValue} -yourself. - -Last but not least you may switch to additional failure states, simply -re-defining \Macro{FamilyKeyState} with a very short text message. -Generally, the four predefined states should be sufficient. + where \Macro{define@key} is provided by the + \Package{keyval}\IndexPackage{keyval} package (see \cite{package:keyval}). + However, there are some additional precautions taken with the call to + \Macro{define@key}, and the \PName{action} will be extended to include these + precautions. +%\end{Explain} + +Success\ChangedAt{v3.12}{\Package{scrbase}} or failure in executing the +\PName{action} should be reported back to \Package{scrbase} through +\Macro{FamilyKeyState} so that the package itself can take further action as +needed. This could be, for example, an error message or merely warning of an +unknown option. You should not report errors directly! + +The default state of \PName{action} before execution is +\Macro{FamilyKeyStateUnknown}. This indicates that it is not known whether or +not the key could be processed successfully. If this state remains unchanged +after the \PName{action} has been executed, \Package{scrbase} writes a +message to the \File{log} file and assumes the that state is +\Macro{FamilyKeyStateProcessed}. + +The \Macro{FamilyKeyStateProcessed} state indicates that the key and the value +assigned to it have been successfully processed and everything is OK. You can +switch to this state by calling \Macro{FamilyKeyStateProcessed} itself. + +The \Macro{FamilyKeyStateUnknownValue} state indicates that the key has been +processed but that the value passed to it was either unknown or not allowed. +For example, \hyperref[cha:typearea]{\Package{typearea}} reports this +condition if you try to set the \DescRef{typearea.option.twoside} option to +\PValue{unknown}. You can set this state by simply calling +\Macro{FamilyKeyStateUnknownValue}. + +The \Macro{FamilyKeyStateNeedValue} state indicates that the key could not be +processed because it expects a value, but it was called without such a value. +This state is set automatically if you use a key that does not have a +\PName{default} value without assigning a value. Theoretically, you could +set this state explicitly with \Macro{FamilyKeyStateNeedValue}, but you should +not need to set it yourself. + +In addition, you can define additional error conditions by redefining +\Macro{FamilyKeyState} with a short text message. Generally, however, the four +predefined states should be sufficient. \begin{Example} - Assume each of the three packages from the previous example should get a - key named \PValue{coldcuts}. When used, a switch is set at each of - the packages. For package \Package{salami} this may be: + Suppose each of the three packages from the previous example should have a + key named \PValue{coldcuts}. When used, a switch should be set in each of + the packages. For the \Package{salami} package, for example, this could look + like this: \begin{lstcode} - \newif\if@Salami@Aufschnitt + \newif\if@salami@coldcuts \DefineFamilyKey{butcher}% {coldcuts}[true]{% \expandafter\let\expandafter\if@salami@coldcuts @@ -266,67 +232,75 @@ Generally, the four predefined states should be sufficient. \FamilyKeyStateProcessed } \end{lstcode} - Available values for the key are \PValue{true} or \PValue{false} in this - case. Instead of testing on inappropriate values, success will be signalled - for any case in this example. If the key is used later, it is executed with - one of the allowed values or without assignment. In the second case, the - default \PName{true} will be used. - - The definitions in the other packages are similar. Only ``\texttt{salami}'' - has to be replaced by the corresponding names. + When called, the value will therefore be either \PValue{true} or + \PValue{false}. This example does not test for illegal values. Instead, + it is always reported that the key was processed completely and correctly. + If the key is used later, one of the permitted values, or no value, must be + used. In the second case, the default \PName{true} value will be used. + + The definitions for the other packages are similar. Only ``\texttt{salami}'' + has to be replaced by the respective names. \end{Example} % \EndIndexGroup \begin{Declaration} - \Macro{RelaxFamilyKey}\OParameter{family member}\Parameter{family}% + \Macro{RelaxFamilyKey}\OParameter{member}\Parameter{family}% \Parameter{key} \end{Declaration} -If\ChangedAt{v3.15}{\Package{scrbase}} the \PName{key} of the \PName{family - member} of \PName{family} has been defined before, that definition will be -cancelled. Afterwards the \PName{key} will not be defined for the \PName{family - member} of \PName{family} any longer. Usage of \Macro{RelaxFamilyKey} for a -not yet defined \PName{key} of the \PName{family member} of the \PName{family} -is also allowed.% +If\ChangedAt{v3.15}{\Package{scrbase}} a \PName{key} has been previously +defined as a \PName{member} of a \PName{family}, that definition will be +cancelled. Afterwards the \PName{key} will no longer be defined for this +\PName{member} of the \PName{family}. You can use \Macro{RelaxFamilyKey} for a +\PName{key} that is not defined for this \PName{member} of the \PName{family}. + +If you do not specify a \PName{member}, then the member +``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is assumed, just as +with \DescRef{\LabelBase.cmd.DefineFamilyKey}. However, \Macro{RelaxFamilyKey} +is only rarely used while loading a package rather than at runtime. Therefore +the \PName{member} should usually be specified explicitly as well.% \EndIndexGroup \begin{Declaration} - \Macro{FamilyProcessOptions}\OParameter{family member}\Parameter{family} + \Macro{FamilyProcessOptions}\OParameter{member}\Parameter{family} \end{Declaration} -Generally the extension of keys of families to keys of families and family -members, as mentioned earlier, uses keys or key-value settings as class or -package options. The command \Macro{FamilyProcessOptions} is an extension of -\Macro{ProcessOption*} from \LaTeX{} kernel (see \cite{latex:clsguide}, which -processes not only options that has been declared using \Macro{DeclareOption}, -it processes all keys of the given family member. If the optional argument -\PName{family member} is omitted, family member +In essence, extending keys from families to both families and family members +means that either keys or key-value pairs can be used as normal class or +package options. The \Macro{FamilyProcessOptions} command is an extension of +\Macro{ProcessOption*} from the \LaTeX{} kernel (see \cite{latex:clsguide}, +which processes not only options declared with \Macro{DeclareOption}, but also +all keys of the given member. If you omit the optional argument +\PName{member}, the member ``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is used. -Somehow special are keys that are not attached to a family member, but to a -family. These are keys with an empty family member. Such keys are set before -the keys of the family members. +One feature worth noting is that keys which are attached not to a family +member but to a family have an empty family member. Such keys are set before +the keys of the members. \begin{Example} - If a package in the previous example would be extended by the line + If, in the packages from the previous example, you add the line \begin{lstcode} \FamilyProcessOptions{butcher} \end{lstcode} - then the user may select the option \Option{coldcuts} when loading the - package. If the option is used globally, this means at the optional - argument of \Macro{documentclass}, then the option would be passed - automatically to all three packages, if all three packages are loaded - later. + after you define the key, you can specify the \Option{coldcuts} option when + loading the package. If you specify the option globally in + \Macro{documentclass}, the option will be passed automatically to all three + packages if they are loaded later. \end{Example} -Please note\textnote{Attention!} that packages always process global options -before local options. When processing unknown options initiate an entry in the -\File{log}-file and the option is otherwise ignored. By contrast, unknown -options assigned to the package locally leads to an error message. +Note\textnote{Attention!} that packages always process global options +before local options. While unknown global options result in an entry in the +\File{log} file and the option being otherwise ignored, unknown local +options result in an error message. -\Macro{FamilyProcessOptions} may be interpreted either as an extension of -\Macro{ProcessOption*} or as an extension of the \PName{key=value} mechanism +You can think of \Macro{FamilyProcessOptions} as an extension of either +\Macro{ProcessOption*} or the \PName{key=value} mechanism of \Package{keyval}. Ultimately, with the help of \Macro{FamilyProcessOptions}, \PName{key=value} pairs become options.% + +As with\textnote{Attention!} \Macro{ProcessOptions}, +\Macro{FamilyProcessOptions} must not be used while executing options code. +In particular, you cannot load packages while processing options.% % \EndIndexGroup @@ -335,60 +309,60 @@ of \Package{keyval}. Ultimately, with the help of \Macro{BeforeFamilyProcessOptions}\OParameter{member}\Parameter{family}% \Parameter{code}% \end{Declaration} -Especially\ChangedAt{v3.18}{\Package{scrbase}} authors of wrapper classes or -wrapper packages sometimes need a hook to execute \PName{code} just before -\DescRef{\LabelBase.cmd.FamilyProcessOptions}. The package \Package{scrbase} -provides such a hook and you can add \PName{code} to it using -\Macro{BeforeFamilyProcessOptions}. The parameters \PName{member} and -\PName{family} are same to \DescRef{\LabelBase.cmd.FamilyProcessOptions}. In -difference to \DescRef{\LabelBase.cmd.FamilyProcessOptions} you can add -\PName{code} also to the hook of not yet defined \PName{family} or -\PName{member}. - -Note, the hook of a family member will be cleaned after execution. But if you -use an empty \PName{member} the \PName{code} will be executed before the -\DescRef{\LabelBase.cmd.FamilyProcessOptions} of every member of the \PName{family} and will -never be deleted. +Authors\ChangedAt{v3.18}{\Package{scrbase}} of wrapper classes in particular +sometimes need a hook to execute \PName{code} before +\DescRef{\LabelBase.cmd.FamilyProcessOptions}. The \Package{scrbase} package +provides such a hook, and you can add \PName{code} to it with +\Macro{BeforeFamilyProcessOptions}. The \PName{member} and \PName{family} +parameters are same as those of \DescRef{\LabelBase.cmd.FamilyProcessOptions}. +However, you can also add \PName{code} to the hook for families or members +that have not yet been defined. + +Note that the hook of a family member is automatically deleted after it is +executed. But if you use an empty \PName{member}, this hook\Index{hook} will +be executed for every member of the \PName{family} and will not be deleted. \begin{Example} - Now, you are writing a package that loads \Package{liversausage}. But you do - not provide option \Option{coldcut} with this package. So you use - \Macro{BeforeFamilyProcessOptions} to deactivate - that option before loading the package: + You are writing a \Package{smokedsausage} package that loads + \Package{mettwurst}. But you do not want to be able to set the + \Option{coldcut} option with this package. So you use + \Macro{BeforeFamilyProcessOptions} to deactivate that option before you load + the package: \begin{lstcode} \RequirePackage{scrbase} - \BeforeFamilyProcessOptions[.liversausage.sty]{butcher}{% - \RelaxFamilyKey[.liversausage.sty]{butcher}{coldcut}% + \BeforeFamilyProcessOptions[.mettwurst.sty]{butcher}{% + \RelaxFamilyKey[.mettwurst.sty]{butcher}{coldcut}% } - \RequirePackageWithOptions{liversausage} + \RequirePackageWithOptions{mettwurst} \end{lstcode} - If after this a user tries to load your package with option - \Option{coldcut}, package \Package{liversausage} will throw an undefined - option error. If \Option{coldcut} is used as a global option, package - \Package{liversausage} will ignore it. But default settings inside - \Package{liversausage}, e.\,g., using \DescRef{\LabelBase.cmd.FamilyExecuteOptions} before - \DescRef{\LabelBase.cmd.FamilyProcessOptions} are not effected. + If a user tries to load your package with the \Option{coldcut} option, the + \Package{mettwurst} package will throw an undefined option error. If + \Option{coldcut} is used as a global option, the \Package{mettwurst} + package will ignore it. But default settings inside \Package{mettwurst}, + for example using \DescRef{\LabelBase.cmd.FamilyExecuteOptions} before + \DescRef{\LabelBase.cmd.FamilyProcessOptions} are not affected. Of course, + you can also insert your own default for \Package{smokedsausage} via + \Macro{BeforeFamilyProcessOptions} in \Package{mettwurst}. \end{Example} \EndIndexGroup \begin{Declaration} - \Macro{FamilyExecuteOptions}\OParameter{family member}\Parameter{family}% + \Macro{FamilyExecuteOptions}\OParameter{member}\Parameter{family}% \Parameter{options list} \end{Declaration} This command is an extension of \Macro{ExecuteOptions} from the \LaTeX{} kernel (see \cite{latex:clsguide}). The command processes not only options -that are defined using \Macro{DeclareOption}, but also processes all keys of -the given \PName{family member}. If the optional argument \Macro{family - member} is omitted, then +defined with \Macro{DeclareOption} but also all keys of the given +\PName{family}. If you omit the optional argument \Macro{member}, ``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is used. -Somehow special are keys of empty family members, which are not attached to a -family member, but to a family. Such keys are set before the keys of family -members. +One feature worth noting is that keys which are attached not to a family +member but to a family have an empty family member. Such keys are set before +the keys of the members. \begin{Example} - Assume option \Option{coldcuts} should be set by default in the - previous example. In this case only line + Suppose the \Option{coldcuts} option should be set by default in the + previous examples. In this case only line \begin{lstcode} \FamilyExecuteOptions{butcher}{coldcuts} \end{lstcode} @@ -396,14 +370,15 @@ members. \end{Example} If\ChangedAt{v3.20}{\Package{scrbase}} you call \Macro{FamilyExecuteOptions} -with an unknown option inside the \PName{options list}, you will get an -error. But you will not get an error, if the \PName{family member} has an -option \Option{@else@}. In this case option \Option{@else@} will be used -instead of the unknown option. \KOMAScript{} itself uses this feature, e.\,g., -inside the definition of section like commands to prior the style attribute -above all other attributes. - -Usage of the command inside the execution of an option is provided.% +with an unknown option inside the \PName{options list}, you will get an error. +An exception to this rule occurs when the \PName{member} has an option called +\Option{@else@}. In this case, the \Option{@else@} option will be used instead +of the unknown option. \KOMAScript{} itself uses this feature, for example +inside the definition of sectioning commands, to evaluate the style option +before all other attributes. + +You can also use this command inside the code executed when processing the +option.% % \EndIndexGroup @@ -411,27 +386,27 @@ Usage of the command inside the execution of an option is provided.% \begin{Declaration} \Macro{FamilyOptions}\Parameter{family}\Parameter{options list}% \end{Declaration} -Hence \PName{options list} is like: +Unlike normal options defined with \Macro{DeclareOption}, the \PName{key}s can +also be set after loading a class or package. To do this, you call +\Macro{FamilyOptions}. The \PName{options list} has the form \begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} \PName{key}\texttt{=}\PName{value}\texttt{,}% \PName{key}\texttt{=}\PName{value}\dots \end{tabular}\vskip\dp\strutbox\end{flushleft} -after which the value assignment may be omitted for \PName{key}s that have a +after which the value assignment can be omitted for \PName{key}s that have a defined default. -In contrast to average options that are defined using \Macro{DeclareOption}, -the \PName{key}s also may be set after loading a class or package. For this, -the user calls \Macro{FamilyOptions}. Thereafter, the \PName{key}s of all -members of the specified family are set. If a \PName{key} also exists as a -family attribute, then the family key is set first. After this, the member -keys follow in the order in which the members have been defined. If a given -\PName{key} does not exist, either for the family or for any member of the -family, then \Macro{FamilyOptions} will result in an error. Package -\Package{scrbase} reports an error also if there are members with key -\PName{key}, but all those members signal failure via \DescRef{\LabelBase.cmd.FamilyKeyState}. +The statement sets the keys of all members of the specified family. If a +\PName{key} also exists as an attribute of the family itself, then the family +key is set first, followed by the member keys in the order in which they were +defined. If a given \PName{key} does not exist, either for the family or for +any member of the family, then \Macro{FamilyOptions} will throw an error. An +error also occurs if a \PName{key} exists for some members but each of those +members returns an error through \DescRef{\LabelBase.cmd.FamilyKeyState}. \begin{Example} - You extend your butcher project by a package \Package{sausagesalad}. If this - package has been loaded, all sausage package should generate cold cuts: + You extend your butcher project with a \Package{sausagesalad} package. If + this package has been loaded, all sausage packages should generate cold + cuts: \begin{lstcode} \ProvidesPackage{sausagesalad}% [2008/05/06 nonsense package] @@ -440,16 +415,16 @@ family, then \Macro{FamilyOptions} will result in an error. Package \FamilyProcessOptions{butcher}\relax \FamilyOptions{butcher}{coldcuts} \end{lstcode} - If currently none of the sausage packages are loaded, the undefined option - \Option{coldcuts} leads to an error message. This is avoided by adding - before the last line of the code above: + If no sausage package has yet been loaded, the undefined option + \Option{coldcuts} leads to an error message. You can avoid this by defining + a corresponding key for the package before the last line of the code above: \begin{lstcode} \DefineFamilyKey{butcher}% {coldcuts}[true]{}% \end{lstcode} - However, sausage packages loaded after - \Package{sausagesalad} still do not produce cold cuts. This may be corrected - by editing the last line of the code again to: + However, sausage packages loaded after \Package{sausagesalad} still do not + produce cold cuts. You can correct this by replacing the previous command + with: \begin{lstcode} \AtBeginDocument{% \DefineFamiyKey[.sausagesalad.sty]% @@ -462,39 +437,45 @@ family, then \Macro{FamilyOptions} will result in an error. Package {coldcuts=#1}}% }% \end{lstcode} - This code does following: First the option will be defined while - \Macro{begin}\PParameter{document} to do nothing for package - \Package{sausagesalad}. Because \Macro{@currname} and \Macro{@currext} are - not longer valid at this time, the optional argument on - \DescRef{\LabelBase.cmd.DefineFamilyKey} has to be used. But until this re-definition of the - option, a second definition is made, that calls the option again while - \Macro{begin}\PParameter{document} for the whole family and so also for - other sausage salad packages. + Thus, the option is defined during \Macro{begin}\PParameter{document} so + that it no longer functions for the \Package{sausagesalad} package. Because + \Macro{@currname} and \Macro{@currext} no longer contain the file name of + the package, you must use the optional argument of + \DescRef{\LabelBase.cmd.DefineFamilyKey}. + + But until this redefinition is performed, it uses a definition that executes + the option again for the family and all its members during + \Macro{begin}\PParameter{document}, thus setting it for other sausage + packages. The delay in executing \Macro{FamilyOptions} is crucial here. For + one thing, it includes only the packages loaded afterwards. For another, it + ensures that its own \Option{coldcuts} option has already been redefined. + This avoids endless recursion. \end{Example} % \EndIndexGroup +\vskip-\ht\strutbox% Umbruchkorrektur wegen Beispiel am Ende \begin{Declaration} \Macro{FamilyOption}\Parameter{family}% - \Parameter{option}\Parameter{values list}% + \Parameter{option}\Parameter{value list}% \end{Declaration} -Besides options that have concurrently excluding values, there may be options -that produce several values at the same time. Using \DescRef{\LabelBase.cmd.FamilyOptions} for -that type of option would result in using the same option several times with -different value assignments. Instead of this, \Macro{FamilyOption} may be used -to assign a whole \PName{values list} to the same \PName{option}. The -\PName{values list} is a comma separated list of values, also known as -\emph{csv}: -\begin{flushleft}\begin{tabular}{l} +In addition to options that have mutually exclusive values, there may be +options that can take multiple values at the same time. To use +\DescRef{\LabelBase.cmd.FamilyOptions} for that type of option, it would be +necessary to invoke the same option several times with different value +assignments. Instead, you can easily assign a whole list of values to a single +\PName{option} using \Macro{FamilyOption}. The \PName{value list} is a comma +separated list of values, also known as \emph{csv}: +%\begin{flushleft}\begin{tabular}{l} \PName{value}\texttt{,}\PName{value}\dots -\end{tabular}\end{flushleft} -By the way, please note that usage of a comma inside a value may be done only -if the value is put inside braces. The general functionality of this command -is the same as that of the previous command \DescRef{\LabelBase.cmd.FamilyOptions}. +%\end{tabular}\end{flushleft} +Note in this context that you can use a comma in a value by putting the value +inside braces. This command's other functionality is the same previously +described for \DescRef{\LabelBase.cmd.FamilyOptions}. \begin{Example} - Package \Package{sausagesalad} should have one mire option, to add - additional ingredients. Each of the ingredients sets a switch as was done + The \Package{sausagesalad} package should have one more option to add + additional ingredients. Each of the ingredients sets a switch, as was done previously for the cold cuts. \begin{lstcode} \newif\if@saladwith@onions @@ -505,15 +486,14 @@ is the same as that of the previous command \DescRef{\LabelBase.cmd.FamilyOption } \end{lstcode} Here the three ingredients ``onions'', ``gherkins'', and ``chillies'' have - been defined. An error message for ``not defined'' ingredients does not - exist. + been defined. There is no error message for unknown ingredients. - For a salad with onions and gherkins the user may use + For a salad with onions and gherkins, you can use \begin{lstcode} \FamilyOptions{butcher}{% ingredient=onions,ingredient=gherkins} \end{lstcode} - or shorter + or simply \begin{lstcode} \FamilyOption{butcher} {ingredient}{onions,gherkins} @@ -530,63 +510,65 @@ is the same as that of the previous command \DescRef{\LabelBase.cmd.FamilyOption Sometimes\ChangedAt{v3.12}{\Package{scrbase}} it is useful to delay the execution of an \PName{action} that is part of a value assignment to a key until all assignments inside one -\DescRef{\LabelBase.cmd.FamilyProcessOptions}, -\DescRef{\LabelBase.cmd.FamilyExecuteOptions}, -\DescRef{\LabelBase.cmd.FamilyOptions}, or -\DescRef{\LabelBase.cmd.FamilyOption} is finished. This may be done using -\Macro{AtEndOfFamilyOptions} or its star -variation\ChangedAt{v3.23}{\Package{scrbase}} inside an option -definition. Reporting failure states of \PName{action} is not possible in this -case. Furthermore, the command should not be used outside an option -definition. - -The variations differ in cases when execution of an option results in further -option calls. In this case all actions of \Macro{AtEndOfFamilyOptions} will be -executed when the inner-most option call returns. The actions of -\Macro{AtEndOfFamilyOptions*} will be executed when the top-most option call -returns. Nevertheless, the order of the actions of both commands is -undefined!% +\DescRef{\LabelBase.cmd.FamilyProcessOptions}\IndexCmd{FamilyProcessOptions}, +\DescRef{\LabelBase.cmd.FamilyExecuteOptions}\IndexCmd{FamilyExecuteOptions}, +\DescRef{\LabelBase.cmd.FamilyOptions}\IndexCmd{FamilyOptions}, or +\DescRef{\LabelBase.cmd.FamilyOption}\IndexCmd{FamilyOptions} is finished. +You can do this using \Macro{AtEndOfFamilyOptions} or its starred +variant\ChangedAt{v3.23}{\Package{scrbase}} inside an option definition. +However, reporting failure states of \PName{action} is not possible with this +command, nor should it be used outside an option definition. + +The two variants differ in case there are nested option definitions, when +executing an option requires further option calls. In this case all actions +specified by \Macro{AtEndOfFamilyOptions} will be executed when the innermost +option call returns. In contrast, the actions of \Macro{AtEndOfFamilyOptions*} +are not executed until the outermost option call returns. +However,\textnote{Attention!} the order of the actions of both commands is +emphatically undefined! It is not guaranteed that the action requested first +will be executed first, nor the converse.% \EndIndexGroup \begin{Declaration} - \Macro{FamilyBoolKey}\OParameter{family member}\Parameter{family}% + \Macro{FamilyBoolKey}\OParameter{member}\Parameter{family}% \Parameter{key}\Parameter{switch name}% \Macro{FamilySetBool}\Parameter{family}% \Parameter{key}\Parameter{switch name}\Parameter{value} \end{Declaration} -In the previous examples, boolean switches often have been used. In the example -with option \Option{coldcuts}, it is necessary that the user assigns either -value \PValue{true} or value \PValue{false}. There is no error message for -wrong value assignment. Because of this, boolean switches are a necessary -feature. Package \Package{scrbase} provides \Macro{FamilyBoolKey} for definition of -such options. Therefore, the arguments \PName{family member}, \PName{family}, and -\PName{key} are the same as that used by \DescRef{\LabelBase.cmd.DefineFamilyKey} (see -\DescPageRef{scrbase.cmd.DefineFamilyKey}). Argument \PName{switch name} -is the name of the switch without the prefix \Macro{if}. If a switch with this -name does not exist already, \Macro{FamilyBoolKey} will define it and -initialize it to \PName{false}. Internally \Macro{FamilyBooKey} uses -\Macro{FamilySetBool} as \PName{action} of \DescRef{\LabelBase.cmd.DefineFamilyKey}. The -\PName{default} for those options is always \PValue{true}. - -On the other hand, \Macro{FamilySetBool} understands \PName{value} \PValue{on} -and \PValue{yes} beside \PName{true} for switching on and \PName{off} and -\PName{no} beside \PName{false} for switching off. Unknown values will result -in a call of \DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} with the arguments -\PName{family}, \PName{key}, and \PName{value}, which results in setting of -\DescRef{\LabelBase.cmd.FamilyKeyState}. Depending on the command used and -other family members, this may result in an error message about unknown value -assignment (see also \DescPageRef{scrbase.cmd.FamilyUnknownKeyValue} and +Boolean switches have been used several times in the previous examples. In the +example with \Option{coldcuts} option, the user had to assign either +\PValue{true} or \PValue{false} as a value. There was no error message if the +user provided the wrong value. Because boolean switches are a common use case, +you can easily define them with \Package{scrbase} using \Macro{FamilyBoolKey}. +The \PName{member}, \PName{family}, and \PName{key} arguments are the same as +those used by \DescRef{\LabelBase.cmd.DefineFamilyKey} (see +\DescPageRef{scrbase.cmd.DefineFamilyKey}). The \PName{switch name} is the +name of the switch without the prefix \Macro{if}. If a switch with this name +does not exist already, \Macro{FamilyBoolKey} will define it and initialize it +to \PName{false}. Internally, \Macro{FamilyBooKey} uses \Macro{FamilySetBool} +as the \PName{action} of \DescRef{\LabelBase.cmd.DefineFamilyKey}. The +\PName{default} for such an option is always \PValue{true}. + +\Macro{FamilySetBool}, on the other hand, accepts \PValue{on} and +\PValue{yes}, in addition to \PName{true}, to turn the switch on, and +\PName{off} and \PName{no}, in addition to \PName{false}, to turn it off. +Unknown values will result in a call to +\DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} with the arguments +\PName{family}, \PName{key}, and \PName{value}, which sets +\DescRef{\LabelBase.cmd.FamilyKeyState} accordingly. As a result, an error +message about an unknown value assignment is printed if necessary (see also +\DescPageRef{scrbase.cmd.FamilyUnknownKeyValue} and \DescPageRef{scrbase.cmd.FamilyKeyState}). \begin{Example} - The key \Option{coldcuts} should be declared somehow more - robust. Additionally, all sausage packages should use the same key. So - either all or none of them will produce cold cuts. + The key \Option{coldcuts} should be defined more robustly in the sausage + packages. Additionally, all sausage packages should use the same key, so + that either all sausage packages will produce cold cuts or none will. \begin{lstcode} \FamilyBoolKey{butcher}{coldcuts}% {@coldcuts} \end{lstcode} - A test, whether or not to produce cold cuts, may be: + A test of whether to produce cold cuts would look like this: \begin{lstcode} \if@coldcuts ... @@ -594,7 +576,7 @@ assignment (see also \DescPageRef{scrbase.cmd.FamilyUnknownKeyValue} and ... \fi \end{lstcode} - This would be the same in each of the three sausage packages, thereby + This would be the same in all three sausage packages, thereby defining the attribute ``coldcuts'' as a family option: \begin{lstcode}[moretexcs={define@key}] \@ifundefined{if@coldcuts}{% @@ -611,55 +593,71 @@ assignment (see also \DescPageRef{scrbase.cmd.FamilyUnknownKeyValue} and \FamilyBoolKey[]{butcher}{coldcuts}% {@coldcuts} \end{lstcode} - using the additional information at - \autopageref{explain:scrbase.macro.DefineFamilyKey}, this is not only valid - for \DescRef{\LabelBase.cmd.DefineFamilyKey} but for \Macro{FamilyBoolKey} too. + taking advantage of the treatment of empty family members as opposed to + omitting the optional argument explained on + \autopageref{explain:scrbase.macro.DefineFamilyKey}, which applies not only + to \DescRef{\LabelBase.cmd.DefineFamilyKey} but also for + \Macro{FamilyBoolKey}. + + Since \DescRef{\LabelBase.cmd.FamilyKeyState} is already set by + \Macro{FamilySetBool}, you can check its status with the help of + \DescRef{\LabelBase.cmd.DefineFamilyKey}. For example, in the first case you + could add an equivalence test to \Macro{FamilySetBool} to perform additional + actions depending on whether \Macro{FamilySetBool} succeeded or not: + \begin{lstcode} + \ifx\FamilyKeyState\FamilyKeyStateProcessed + ... + \else + ... + \fi + \end{lstcode} + Note\textnote{Attention!} that it is essential to perform the test with + \Macro{ifx} at this point. Fully expanding tests like \Macro{ifstr} should + be avoided here. Depending on the current status and the comparison status, + they can lead to different error messages as well as incorrect results. \end{Example} % \EndIndexGroup \begin{Declaration} - \Macro{FamilyNumericalKey}\OParameter{family member}\Parameter{family}% + \Macro{FamilyNumericalKey}\OParameter{member}\Parameter{family}% \Parameter{key}% \OParameter{default}\Parameter{command}% - \Parameter{values list}% + \Parameter{value list}% \Macro{FamilySetNumerical}\Parameter{family}\Parameter{key}% - \Parameter{command}\Parameter{values list}% + \Parameter{command}\Parameter{value list}% \Parameter{value} \end{Declaration} -In contrast to switches that may be either true or false, a key exists -that accept several values. For example an alignment may not only be left or -not left, but left, centered, or right. Internally such -differentiation often is made using \Macro{ifcase}. This \TeX{} command -expects a numerical value. Because of this the command to define a macro by -a \PName{key} has been named \Macro{FamilyNumericalKey} in -\Package{scrbase}. The \PName{values list} thereby has the form: -\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} - \Parameter{value}\Parameter{definition}\texttt{,}% - \Parameter{value}\Parameter{definition}\texttt{,}% - \dots -\end{tabular}\vskip\dp\strutbox\end{flushleft} -Therefore, the \PName{values list} does not solely define the supported values to the -\PName{key}. For each of the \PName{value}s, the -\PName{definition} of macro \Macro{\PName{command}} also is given. Usually, -\PName{definition} is just a numerical value. Nevertheless, other content is -possible and allowed. Currently, the only limitation is that -\PName{definition} has to be fully expandable and will be expanded during the -assignment. +While switches can accept only two values, there are also keys that recognize +several values. For example an alignment can be not just left or not-left, but +left, centred, or right. Internally, such differentiation is often made using +\Macro{ifcase}. This \TeX{} command expects a numerical value. Therefore in +\Package{scrbase} the command to define a macro by a \PName{key} has been +named \Macro{FamilyNumericalKey}. The \PName{value list} has the form: +%\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + \Parameter{value}\Parameter{definition}\texttt{,}\linebreak[1]% + \Parameter{value}\Parameter{definition}\texttt{,}~\dots +%\end{tabular}\vskip\dp\strutbox\end{flushleft} +The \PName{value list} defines not just the values permitted for the +\PName{key}. For each \PName{value}, the \PName{definition} of the macro +\Macro{\PName{command}} also is given. Usually, the \PName{definition} is just +a numerical value. Although other content is possible, there is currently a +restriction that the \PName{definition} must be fully expandable, and it will +be expanded during the assignment. \begin{Example} - The sausage may be cut different. For example the cold cuts may stay uncut or - will be cut roughly or may be cut thinly. This information should be stored - in command \Macro{cuthow}. + The sausage for the sausage salad can be cut differently. For example, the + cold cuts could simply remain uncut or be cut into thick or thin slices. + This information should be stored in the command \Macro{cuthow}. \begin{lstcode} \FamilyNumericalKey{butcher}% {saladcut}{cuthow}{% {none}{none},{no}{none},{not}{none}% - {rough}{rough},% + {thick}{thick},% {thin}{thin}% } \end{lstcode} - Not cutting anything may be selected either by + Not cutting anything can be selected by \begin{lstcode} \FamilyOptions{butcher}{saladcut=none} \end{lstcode} @@ -671,182 +669,192 @@ assignment. \begin{lstcode} \FamilyOptions{butcher}{saladcut=not} \end{lstcode} - In all three cases \Macro{cuthow} would be defined with content - \PValue{none}. It may be very useful to provide several values for the same - result as shown in this example. + In all three cases \Macro{cuthow} would be defined with the content + \PValue{none}. It can be useful to provide several values for the same + result, as shown in this example. - Now, it's most likely, that the kind of cutting will not be printed, but - should be evaluated later. In this case a textual definition would not be - useful. If the key is defined like this: + Now it's very likely that the manner of cutting will not be printed but + should be evaluated later. In this case, a textual definition would be + rather impractical. If the key is defined like this: \begin{lstcode} \FamilyNumericalKey{butcher}% {saladcut}{cuthow}{% {none}{0},{no}{0},{not}{0}% - {rough}{1},% + {thick}{1},% {thin}{2}% } \end{lstcode} - then a condition like the following may be used: + then you can use a condition like the following: \begin{lstcode} \ifcase\cuthow - % no cut + % uncut \or - % rough cut + % thickly cut \else - % thin cut + % thinly cut \fi \end{lstcode} \end{Example} -Internally, \Macro{FamilyNumericalKey} uses \Macro{FamilySetNumerical} as -\PName{action} of \DescRef{\LabelBase.cmd.DefineFamilyKey}. If a unknown value -is assigned to such a key, \Macro{FamilySetNumerical} will call -\DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} with the arguments -\PName{family}, \PName{key} and \PName{value}. This will normally result in an -error message about assigning an unknown value. +Internally, \Macro{FamilyNumericalKey} uses \Macro{FamilySetNumerical} as the +\PName{action} of \DescRef{\LabelBase.cmd.DefineFamilyKey}. If an unknown +value is assigned to such a key, \Macro{FamilySetNumerical} will call +\DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} with the \PName{family}, +\PName{key} and \PName{value} arguments. This leads to an error signalled with +the \DescRef{\LabelBase.cmd.FamilyKeyStateUnknownValue} status in +\DescRef{\LabelBase.cmd.FamilyKeyState}. Similarly, when calling +\Macro{FamilySetNumerical} the success is signalled via +\DescRef{\LabelBase.cmd.FamilyKeyStateProcessed} in +\DescRef{\LabelBase.cmd.FamilyKeyState}.% % \EndIndexGroup \begin{Declaration} - \Macro{FamilyCounterKey}\OParameter{family member}\Parameter{family}% + \Macro{FamilyCounterKey}\OParameter{member}\Parameter{family}% \Parameter{key}% \OParameter{default}\Parameter{\LaTeX{} counter}% \Macro{FamilySetCounter}\Parameter{family}% \Parameter{key}\Parameter{\LaTeX{} counter}\Parameter{value} \end{Declaration} -Beside\ChangedAt{v3.12}{\Package{scrbase}} -\DescRef{\LabelBase.cmd.FamilyNumericalKey} that defines a macro to a numeric -value depending on a symbolic value, there are circumstances when a -\PName{key} directly represents a \PName{\LaTeX{} counter}, that should be -assigned directly to a numeric value. In those cases, \Macro{FamilyCounterKey} -can be used that internally will call \Macro{FamilySetCounter}. A primary test -of the \PName{value} argument is done that only detects whether or not usage -of \PName{value} as a number is plausible. The assignment is done, only if -this plausibility test is successful. Nevertheless the assignment can still -fail and result in a \TeX{} error. But if the plausibility test fails already, -this is signalled by \DescRef{\LabelBase.cmd.FamilyKeyStateUnknownValue}. +While\ChangedAt{v3.12}{\Package{scrbase}} +\DescRef{\LabelBase.cmd.FamilyNumericalKey} defines a macro in which a numeric +value corresponds to a symbolic value, there are, of course, circumstances +when a \PName{key} directly represents a \PName{\LaTeX{} counter} to which a +numeric value should be assigned immediately. For this case, you can use +\Macro{FamilyCounterKey}, which calls \Macro{FamilySetCounter} internally. +There are some basic tests of the \PName{value} argument to determine if the +\PName{value} argument appears to be suitable for assignment to a counter. The +assignment will only be made if these tests succeed. However, not all errors +can be detected here, so an incorrect assignment can also lead to an error +message from \TeX{} itself. Errors that are detected, however, are signalled +by \DescRef{\LabelBase.cmd.FamilyKeyStateUnknownValue}. If\ChangedAt{v3.15}{\Package{scrbase}} the value is omitted, the \PName{default} is used instead. If there is no \PName{default}, the -\PName{key} can be used only with a value being defined.% +\PName{key} can be used only with an explicit value.% \EndIndexGroup \begin{Declaration} - \Macro{FamilyCounterMacroKey}\OParameter{family member}\Parameter{family}% + \Macro{FamilyCounterMacroKey}\OParameter{member}\Parameter{family}% \Parameter{key}% \OParameter{default}\Parameter{macro}% \Macro{FamilySetCounterMacro}\Parameter{family}% \Parameter{key}\Parameter{macro}\Parameter{value}% \end{Declaration} These\ChangedAt{v3.12}{\Package{scrbase}} two commands differ from the -previously described \DescRef{\LabelBase.cmd.FamilyCounterKey} and \DescRef{\LabelBase.cmd.FamilySetCounter} -only by the fact, that they do not assign a \PName{value} to a \PName{\LaTeX - counter}, but define a \Macro{macro} with the -\PName{value}.% +previously described \DescRef{\LabelBase.cmd.FamilyCounterKey} and +\DescRef{\LabelBase.cmd.FamilySetCounter} only by the fact that they do not +assign a \PName{value} to a \LaTeX{} counter, but define a \Macro{macro} with +the \PName{value}. This \PName{value} is locally assigned to a counter and +then its expanded value is used. Therefore, its value at the time the option +is called applies.% \EndIndexGroup \begin{Declaration} - \Macro{FamilyLengthKey}\OParameter{family member}\Parameter{family}% + \Macro{FamilyLengthKey}\OParameter{member}\Parameter{family}% \Parameter{key}% \OParameter{default}\Parameter{length}% \Macro{FamilySetLength}\Parameter{family}% \Parameter{key}\Parameter{length}\Parameter{value}% - \Macro{FamilyLengthMacroKey}\OParameter{family member}\Parameter{family}% + \Macro{FamilyLengthMacroKey}\OParameter{member}\Parameter{family}% \Parameter{key}% \OParameter{default}\Parameter{Makro}% \Macro{FamilySetLengthMacro}\Parameter{family}% \Parameter{key}\Parameter{Makro}\Parameter{value}% \end{Declaration} -With\ChangedAt{v3.12}{\Package{scrbase}} \Macro{FamilyLengthKey} you can +With\ChangedAt{v3.12}{\Package{scrbase}} \Macro{FamilyLengthKey}, you can define a \PName{key} that represents a \PName{length}. It does not matter -whether the \PName{length} is a \LaTeX{} length, a \TeX{} skip or a \TeX{} +whether the \PName{length} is a \LaTeX{} length, a \TeX{} skip, or a \TeX{} dimension. Internally the \PName{length} will be set to the \PName{value} -using \Macro{FamilySetLength}. Thereby a primary test is used to decide, -whether or not it is plausible to assign \PName{length} to \PName{value}. The -assignment is done only if this plausibility test is successful. Nevertheless, -not all assignment errors can be recognised, so an inaccurate \PName{value} -can still result in \TeX{} error. Recognised errors however will be signalled -by \DescRef{\LabelBase.cmd.FamilyKeyStateUnknownValue}. +using \Macro{FamilySetLength}. There are some basic tests to decide whether +this \PName{value} is valid to assign to \PName{length}. The assignment will +only take place if these tests succeed. However, not all errors can be +detected, so an inaccurate \PName{value} can still result in a \TeX{} error. +Errors that are detected, however, are signalled by +\DescRef{\LabelBase.cmd.FamilyKeyStateUnknownValue}. -If\ChangedAt{v3.15}{\Package{scrbase}} the value is omitted, -the \PName{default} is used instead. If there is no \PName{default}, the -\PName{key} can be used only with a value being defined. +If\ChangedAt{v3.15}{\Package{scrbase}} the value is omitted, the +\PName{default} is used instead. If there is no \PName{default}, the +\PName{key} can be used only with an explicit value. -In difference to this, \Macro{FamilyLengthMacroKey} and -\Macro{FamilySetLengthMacro} do not assign \PName{value} to a \PName{length}, -but define a \Macro{macro} with this -\PName{value}.% +\Macro{FamilyLengthMacroKey} and \Macro{FamilySetLengthMacro} store the +\PName{value} not in a \PName{length} but in a \Macro{macro}.% \EndIndexGroup \begin{Declaration} - \Macro{FamilyStringKey}\OParameter{family member}\Parameter{family}% + \Macro{FamilyStringKey}\OParameter{member}\Parameter{family}% \Parameter{key}% \OParameter{default}\Parameter{command} + \Macro{FamilyCSKey}\OParameter{member}\Parameter{family}% + \Parameter{key}% + \OParameter{default}\Parameter{command name} \end{Declaration} This defines\ChangedAt{v3.08}{\Package{scrbase}} a \PName{key} that accepts -every value. The value will be stored into the given \Macro{command}. If there +any value. The value will be stored in the specified \Macro{command}. If there is no optional argument for the \PName{default}, \Macro{FamilyStringKey} is the same as: -\begin{quote} -\DescRef{\LabelBase.cmd.DefineFamilyKey}\OParameter{family member}\Parameter{family}% -\Parameter{key}\\ -\hphantom{\DescRef{\LabelBase.cmd.DefineFamilyKey}}% -\PParameter{\Macro{def}\PName{command}\string{\#1\string}% -\DescRef{\LabelBase.cmd.FamilyKeyStateProcessed}}. -\end{quote} -If an optional argument \PName{default} is used, \Macro{FamilyStringKey} -is the same as: -\begin{quote} -\DescRef{\LabelBase.cmd.DefineFamilyKey}\OParameter{family member}\Parameter{family}% -\Parameter{key}\\ -\hphantom{\DescRef{\LabelBase.cmd.DefineFamilyKey}}% -\OParameter{default}% -\PParameter{\Macro{def}\PName{command}\string{\#1\string}}. -\end{quote} -If \PName{command} is not been defined, an empty macro will be defined. +\begin{lstcode}[escapeinside=`'] + \DefineFamilyKey[`\PName{member}']{`\PName{family}'}{`\PName{key}'} + {\def`\PName{command}'{#1}} +\end{lstcode} +If you use the optional argument \PName{default}, \Macro{FamilyStringKey} +corresponds to: +\begin{lstcode}[escapeinside=`'] + \DefineFamilyKey[`\PName{member}']{`\PName{family}'}{`\PName{key}'} + [`\PName{default}'] + {\def`\PName{command}'{#1}\FamilyKeyStateProcessed} +\end{lstcode} + \begin{Example} - By default an amount of 250\Unit{g} sausage salad should be produced. The - amount should be configurable by an option. The wanted amount will be stored - in the macro \Macro{saladweight}. The option should be named - \PValue{saladweight}, too: + By default 250\Unit{g} of sausage salad should be produced. However, the + amount should be configurable by an option. To do so, the quantity to be + created is stored in the macro \Macro{saladweight}. The option to change + the weight should also be called \PValue{saladweight}: \begin{lstcode} \newcommand*{\saladweight}{250g} \FamilyStringKey{butcher}% {saladweight}[250g]{\saladweight} \end{lstcode} - To switch back to the default weight after changing it, the user may simply - use the option without weight: + To switch back to the default weight after changing it, you can simply + call the option without the weight: \begin{lstcode} \FamilyOptions{butcher}{saladweight} \end{lstcode} - This may be done, because the default weight has been set as default at the - definition of the option above. + This is possible because the default quantity was also set as the default + value in the definition. \end{Example} -In this case there are not unknown values because all values are simply used -for a macro definition. Nevertheless, you should note that paragraph breaks -at the value assignment to the key are not allowed. +In this case, there are no unknown values because all values are simply used +for a macro definition. Note, however, that paragraph breaks are not allowed +when assigning a value to the key. + +In contrast\ChangedAt{v3.25}{\Package{scrbase}} to \Macro{FamilyStringKey}, +the \Macro{FamilyCSKey} command expects for the final argument not a macro but +only the name of a command, for example \PParameter{saladweight} instead of +\PParameter{\Macro{saladweight}}.% % \EndIndexGroup \begin{Declaration} \Macro{FamilyUnknownKeyValue}\Parameter{family}\Parameter{key}% - \Parameter{value}\Parameter{values list}% + \Parameter{value}\Parameter{value list}% \end{Declaration} -The command \Macro{FamilyUnknownKeyValue} throws and error message about -unknown values assigned to a known key. The \PName{values list} is a comma -separated list of allowed values in the form: -\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} - `\PName{value}'\texttt{,} `\PName{value}' \dots -\end{tabular}\vskip\dp\strutbox\end{flushleft} -Currently\ChangedAt{v3.12}{\Package{scrbase}}, \PName{values list} is -not used by \Package{scrbase}. +The command \Macro{FamilyUnknownKeyValue} throws an error message due to an +unknown or illegal values by means of \DescRef{\LabelBase.cmd.FamilyKeyState}. +The \PName{value list} is a comma separated list of permissible values in the +form +%\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + `\PName{value}'\texttt{,} `\PName{value}' \dots +%\end{tabular}\vskip\dp\strutbox\end{flushleft} +However\ChangedAt{v3.12}{\Package{scrbase}}, the \PName{value list} is +currently not evaluated by \Package{scrbase}. \begin{Example} - Now, for the cold cuts, the choices should be cut or no-cut and in case of cut - rough or thin. Rough should be the default for cutting. + The user should now also be able to select whether the cold cuts should be + cut thick or thin. Thick should be the default setting, which should be used + even if the user does not specify how to cut the coldcuts. \begin{lstcode} \@ifundefined{if@thincut}{% \expandafter @@ -857,36 +865,44 @@ not used by \Package{scrbase}. \DefineFamilyKey{butcher}% {coldcuts}[true]{% \FamilySetBool{butcher}{coldcuts}% - {@coldcuts}% - {#1}% + {@coldcuts}% + {#1}% \ifx\FamilyKeyState\FamilyKeyStateProcessed \@thincutfalse - \else + \else \ifstr{#1}{thin}{% - \@coldcutstrue - \@thincuttrue + \@coltcutstrue + \@finecuttrue \FamilyKeyStateProcessed - }{}% + }{% + \FamilyUnknownKeyValue{butcher}% + {coldcuts}% + {#1}{% + `true', `on', `yes', + `false`, `off`, `no', + `thin'% + }% + }% \fi }% \end{lstcode} - Let's have a look at the definition of \Option{butcher}: - First of all, we try to set the boolean switch of cold cuts using - \DescRef{\LabelBase.cmd.FamilySetBool}. After this command, we test whether - or not \DescRef{\LabelBase.cmd.FamilyKeyState} signals the success of the - command with state \DescRef{\LabelBase.cmd.FamilyKeyStateProcessed}. If so, - only the thin cut has to be deactivated. - - In the other case, the value will be tested to be equal to \PValue{thin}. In - that case, cold cuts and thin cut are activated and the state will be - switched to \DescRef{\LabelBase.cmd.FamilyKeyStateProcessed}. If the last - test failed also, the failure state of - \DescRef{\LabelBase.cmd.FamilySetBool} is still valid at the end of the - execution. - - Command \Macro{ifstr} is used for the thin test. It is - described on \DescPageRef{scrbase.cmd.ifstr} in - \autoref{sec:scrbase.if}. + First we try to set the boolean coldcuts switch using + \DescRef{\LabelBase.cmd.FamilySetBool}. If this succeeds, i.\,e. if + \DescRef{\LabelBase.cmd.FamilyKeyState} corresponds to + \DescRef{\LabelBase.cmd.FamilyKeyStateProcessed}, thincut will be + deactivated. Otherwise, we check if the value is equal to \PValue{thin} + rather than one of the valid values for a boolean switch. In this case, both + coldcuts and thincut are activated and the state will be switched to + \DescRef{\LabelBase.cmd.FamilyKeyStateProcessed}. If the previous test + fails, the error state signalled by \DescRef{\LabelBase.cmd.FamilySetBool} + is reset to \DescRef{\LabelBase.cmd.FamilyKeyStateUnknownValue}. The list of + the permissible values will be added to it. However, since this list is no + longer used, it would have been easy to skip the call to + \Macro{FamilyUnknownKeyValue} in the example and thus assume the error + status of \DescRef{\LabelBase.cmd.FamilySetBool}. + + The \Macro{ifstr} command used in the test is explained on + \DescPageRef{scrbase.cmd.ifstr} in \autoref{sec:scrbase.if}. \end{Example} % \EndIndexGroup @@ -895,26 +911,27 @@ not used by \Package{scrbase}. \begin{Declaration} \Macro{FamilyElseValues} \end{Declaration} -With former releases\ChangedAt{v3.12}{\Package{scrbase}} of \Package{scrbase}, -additional allowed values reported by -\DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} can be set re-defining -\Macro{FamilyElseValues} in the form: -\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} - \texttt{,} `\PName{value}'\texttt{,} `\PName{value}' \dots -\end{tabular}\vskip\dp\strutbox\end{flushleft} -Since release~3.12 \DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} does not -report errors itself, but signals them using -\DescRef{\LabelBase.cmd.FamilyKeyState}. Therefore, \Macro{FamilyElseValues} -became deprecated. Nevertheless, its former usage is recognised by -\Package{scrbase} and results in a code change demand message.% +In\ChangedAt{v3.12}{\Package{scrbase}} previous\textnote{Obsolete!} versions +of \Package{scrbase}, you could use the \Macro{FamilyElseValues} command to +define additional values for processing by +\DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} in the form +%\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + \texttt{,} `\PName{value}'\texttt{,} `\PName{value}' \dots, + %\end{tabular}\vskip\dp\strutbox\end{flushleft} +which were then output in an error message. Since version~3.12, +\DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} no longer issues error messages +itself but signals them using \DescRef{\LabelBase.cmd.FamilyKeyState}. +Therefore, \Macro{FamilyElseValues} is now deprecated. Nevertheless, +\Package{scrbase} detects its use and issues a message requesting that you +update the code accordingly.% \EndIndexGroup \section{Conditional Execution} \seclabel{if} -The package \Package{scrbase} provides several commands for conditional -execution. other than the \TeX{} syntax of conditionals, e.\,g., +The \Package{scrbase} package provides several commands for conditional +execution. It does not rely on the \TeX{} syntax of conditionals such as \begin{lstcode} \iftrue ... @@ -922,334 +939,401 @@ execution. other than the \TeX{} syntax of conditionals, e.\,g., ... \fi \end{lstcode} -yet the \LaTeX{} syntax also known from \LaTeX{} commands like -\Macro{IfFileExists}, \Macro{@ifundefined}, \Macro{@ifpackageloaded}, and many -others, is used. Nevertheless, some package authors prefer to use the \TeX{} -syntax even for users at the \LaTeX{} interface level that could inevitably -lead to naming conflicts with the \Package{scrbase} conditionals. In fact, the -conditionals of \Package{scrbase} are very basic. Because of this -\Package{scrbase} firstly defines these conditionals as internal commands with -prefix \Macro{scr@}. Additional user commands without this prefix are -subsequently defined. But the definition of the user commands may be -suppressed with option \DescRef{\LabelBase.option.internalonly} (see -\autoref{sec:scrbase.loadit}, \DescPageRef{scrbase.option.internalonly}). - -Authors of packages and classes should use the internal commands as -\KOMAScript{} itself does. Nevertheless, for completeness the user commands -are described separately. +but uses the \LaTeX{} syntax with arguments similar to those used by \LaTeX{} +commands like \Macro{IfFileExists}, \Macro{@ifundefined}, +\Macro{@ifpackageloaded}, and many others. Some package authors, however, +prefer to use the syntax of \TeX{} conditionals even for users working at the +\LaTeX{} interface level. Since the \Package{scrbase} conditionals are fairly +low-level instructions, it is possible that such packages could provide +commands with the same names but a different syntax, leading to problems even +if the underlying semantics were actually the same. Therefore, +\Package{scrbase} plays it safe. + +\begin{Declaration} + \OptionVName{internalonly}{value} +\end{Declaration} +The \Package{scrbase} package provides some commands for conditional +execution. It primarily uses names like +\Macro{scr@\PName{name}}\textnote{package authors}, which are internal +commands. \KOMAScript{} also uses these commands internally. Authors of +packages and classes can also use these commands but should not redefine them. +Because some of these commands may also be useful for users, they are provided +as \Macro{\PName{name}}\textnote{users} normally. Since other packages may +provide conflicting commands with the same name but different syntax or +functionality, \Package{scrbase} can suppress the definition of +\Macro{\PName{name}}. Using the \Option{internalonly} option without a +\PName{value} will define only the internal commands and suppress definition +of all the user commands for conditional execution. Alternatively, the user +can list all the commands that should not be defined as the \PName{value}, +replacing ``\Macro{}'' with ``\texttt{/}''. + +Authors of packages and classes normally should not use this option. Users can +specify it with or without the \PName{value} either as a global option with +\DescRef{maincls.cmd.documentclass} or using +\Macro{PassOptionsToPackage}\IndexCmd{PassOptionsToPackage}. +\begin{Example} + The user does not want \Package{scrbase} to define the + \DescRef{\LabelBase.cmd.ifVTeX} and + \DescRef{\LabelBase.cmd.ifundefinedorrelax} commands. So to load the class, + the user writes: +\begin{lstcode} + \documentclass% + [internalonly=/ifVTeX/ifundefinedorrelax]% + {foo} +\end{lstcode} + The class name \Class{foo} is used here as a placeholder for any class. The + commands \DescRef{\LabelBase.cmd.ifVTeX} and + \DescRef{\LabelBase.cmd.ifundefinedorrelax} are explained later in this + section. +\end{Example} + +Authors of packages and classes should use the same internal names as +\KOMAScript{} itself. For completeness, the user commands are also given in +the following explanations.% +\EndIndexGroup \begin{Declaration} \Macro{scr@ifundefinedorrelax}% - \Parameter{name}\Parameter{then instructions}\Parameter{else instructions}% + \Parameter{name}\Parameter{then code}\Parameter{else code}% \Macro{ifundefinedorrelax}% - \Parameter{name}\Parameter{then instructions}\Parameter{else instructions} + \Parameter{name}\Parameter{then code}\Parameter{else code} \end{Declaration} -This command has almost the same functionality as \Macro{@ifundefined} from -the \LaTeX{} kernel (see \cite{latex:source2e}). So the \PName{then - instructions} will be executed if \PName{name} is the name of a command -that is currently either not defined or \Macro{relax}. Otherwise, the -\PName{else instructions} will be executed. In contrast to -\Macro{@ifundefined}, \Macro{\PName{name}} is not defined to be \Macro{relax} -in the event it was not defined before. Moreover, using \eTeX{} this case will -not consume any hash memory.% -% +This command works like \Macro{@ifundefined} from the \LaTeX{} kernel (see +\cite{latex:source2e}). So the \PName{then code} will be executed if +\PName{name} is the name of a command that is currently either not defined or +\Macro{relax}. Otherwise, the \PName{else code} will be executed. Unlike +\Macro{@ifundefined}, no hash memory is allocated nor is \Macro{\PName{Name}} +set to \Macro{relax} if \Macro{\PName{name}} was previously undefined.% +\EndIndexGroup + +\begin{Declaration} + \Macro{ifnotundefined}\Parameter{name}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If the command with the given name has already been defined, the \PName{then +code} will be executed. Otherwise, the \PName{else code} will be executed. +Since \eTeX{} already has a primitive \Macro{ifdefined}, this somewhat +unwieldy name, unfortunately, had to be chosen. There is no corresponding +internal command.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{scr@ifluatex} + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If\ChangedAt{v3.21}{\Package{scrbase}} you use lua\TeX{}, the \PName{then +code} will be executed. Otherwise, the \PName{else code} will be executed. +\iftrue% Umbruchkorrekturtext +This test is rarely useful. % +\fi% +As a rule, it is better to test directly for the command you want. +There\textnote{Attention!} is no user equivalent for this instruction. Use the +\Package{ifluatex}\important{\Package{ifluatex}} package instead (see +\cite{package:ifluatex}).% \EndIndexGroup +\iffalse% It makes no sense to document this instruction yet +\begin{Declaration} + \Macro{scr@ifpdforluatex} + \Parameter{then code}\Parameter{else code} +\end{Declaration} +Until lua\TeX~0.85, it was mostly irrelevant whether you used pdf\TeX{} or +lua\TeX{}. This command, which executes the \PName{then code} in both cases, +derives from that fact. If neither pdf\TeX{} nor lua\TeX{} is used, the +\PName{else code} will be executed. Since version~0.85, lua\TeX{} has given up +compatibility with many of its commands. Therefore this distinction is no +longer useful in practice and is no longer used by \KOMAScript{} itself. There +is no user equivalent of this statement.% +\EndIndexGroup +\fi + \begin{Declaration} \Macro{scr@ifpdftex}% - \Parameter{then instructions}\Parameter{else instructions}% + \Parameter{then code}\Parameter{else code}% \Macro{ifpdftex}% - \Parameter{then instructions}\Parameter{else instructions} + \Parameter{then code}\Parameter{else code} \end{Declaration} -If pdf\TeX{} has been used, the \PName{then instructions} will be executed, -otherwise the \PName{else instructions}. Whether or not a PDF-file is -generated does not matter, and the pdf\TeX{} test is rarely useful. In -general, test for the desired command instead (see previous -\Macro{scr@ifundefinedorrelax} and -\DescRef{\LabelBase.cmd.ifundefinedorrelax}). -% +If you use pdf\TeX{}, the \PName{then code} will be executed. Otherwise, the +\PName{else code} will be executed. It does not matter whether a PDF-file is +actually generated or not. This test is rarely useful. As a rule, you should +test directly for the command you want instead.% \EndIndexGroup \begin{Declaration} \Macro{scr@ifVTeX}% - \Parameter{then instructions}\Parameter{else instructions}% + \Parameter{then code}\Parameter{else code}% \Macro{ifVTeX}% - \Parameter{then instructions}\Parameter{else instructions} + \Parameter{then code}\Parameter{else code} \end{Declaration} -If V\TeX{} has been used, the \PName{then instructions} will be executed, -otherwise the \PName{else instructions}. This test is seldom useful. Test for -the desired command instead (see previous \Macro{scr@ifundefinedorrelax} and -\DescRef{\LabelBase.cmd.ifundefinedorrelax}). +If you use V\TeX{}, the \PName{then code} will be executed. Otherwise, the +\PName{else code} will be executed. This test is seldom useful. As a rule, +you should test directly for the command you want instead.% % \EndIndexGroup \begin{Declaration} \Macro{scr@ifpdfoutput}% - \Parameter{then instructions}\Parameter{else instructions}% + \Parameter{then code}\Parameter{else code}% \Macro{ifpdfoutput}% - \Parameter{then instructions}\Parameter{else instructions} + \Parameter{then code}\Parameter{else code} \end{Declaration} -When generating a PDF-file the \PName{then instructions} will be executed, -otherwise the \PName{else instructions}. Whether pdf\TeX{} or V\TeX{} or -another \TeX{} engine is used to generate the PDF-file does not matter. -% +If a PDF file is generated, the \PName{then code} will be executed. Otherwise, +the \PName{else code} will be executed. It does not matter whether PDF file is +created using lua\TeX{}, pdf\TeX{}, or V\TeX{}, or \XeTeX{}.% \EndIndexGroup \begin{Declaration} \Macro{scr@ifpsoutput}% - \Parameter{then instructions}\Parameter{else instructions}% + \Parameter{then code}\Parameter{else code}% \Macro{ifpsoutput}% - \Parameter{then instructions}\Parameter{else instructions} + \Parameter{then code}\Parameter{else code} \end{Declaration} -When generating a PostScript-file the \PName{then instructions} will be -executed, otherwise the \PName{else instructions}. V\TeX{} provides direct -PostScript generation that will be recognised here. If V\TeX{} is not used, -but a switch \Macro{if@dvips} has been defined, the decision depends on that -switch. \KOMAScript{} provides \Macro{if@dvips} in \Package{typearea}. +If a PostScript file is generated, the \PName{then code} will be executed. +Otherwise, the \PName{else code} will be executed. V\TeX{} can generate +PostScript directly, which is recognized here. However, if V\TeX{} is not used +but the switch \Macro{if@dvips} has been defined, the decision depends on that +switch. \KOMAScript{} provides \Macro{if@dvips} in +\hyperref[cha:typearea]{\Package{typearea}}\IndexPackage{typearea}% +\IndexCmd{if@dvips}. % \EndIndexGroup \begin{Declaration} \Macro{scr@ifdvioutput}% - \Parameter{then instructions}\Parameter{else instructions}% + \Parameter{then code}\Parameter{else code}% \Macro{ifdvioutput}% - \Parameter{then instructions}\Parameter{else instructions} + \Parameter{then code}\Parameter{else code} \end{Declaration} -When generating a DVI-file the \PName{then instructions} will be executed, -otherwise the \PName{else instructions}. If neither a direct PDF-file -generation nor a direct PostScript-file generation has been detected, DVI-file -generation is assumed. -% +If a DVI-file is generated, the \PName{then code} will be executed. Otherwise, +the \PName{else code} will be executed. A DVI file is always assumed to be +generated if no direct output of a PDF file or a PostScript file can be +detected.% \EndIndexGroup \begin{Declaration} - \Macro{ifnotundefined}\Parameter{name}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{if@atdocument}\ \PName{then code}\ % + \textMacro{else}\ \PName{else code}\ \textMacro{fi} \end{Declaration} -\eTeX{} will be used to test, whether or not a command with the given -\PName{name} has already been defined. The \PName{then instructions} will be -executed if the command is defined, otherwise the \PName{else - instructions}. There is no corresponding internal command. +This conditional command intentionally exists only as an internal command. In +the document preamble, \Macro{if@atdocument} corresponds to \Macro{iffalse}. +After \Macro{begin}\PParameter{document}, it corresponds to \Macro{iftrue}. +Authors of classes and packages may find this command useful if a command +should behave differently depending on whether it is used in the preamble or +inside document body. Note\textnote{Attention!} that this command is a +condition using \TeX{} syntax and not \LaTeX{} syntax! % \EndIndexGroup \begin{Declaration} - \Macro{ifstr}\Parameter{string}\Parameter{string}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifstr}\Parameter{string 1}\Parameter{string 2}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -Both \PName{string} arguments are expanded and afterwards compared. If the -expansions are the same, the \PName{then instructions} will be executed, -otherwise the \PName{else instructions}. There is no corresponding internal +Both \PName{string} arguments are expanded and then compared. If the +expansions are the same, the \PName{then code} will be executed. Otherwise the +\PName{else code} will be executed. There is no corresponding internal command. % \EndIndexGroup \begin{Declaration} - \Macro{ifstrstart}\Parameter{string}\Parameter{string}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifstrstart}\Parameter{string 1}\Parameter{string 2}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -Both\ChangedAt{v3.12}{\Package{scrbase}} \PName{string} arguments are -expanded and afterwards compared. If aside from white spaces the first string -starts with the second one, the \PName{then instructions} will be executed, -otherwise the \PName{else instructions}. The command is not completely -expandable and there is no corresponding internal command.% +Both\ChangedAt{v3.12}{\Package{scrbase}} \PName{string} arguments are expanded +and then compared. If \PName{string 1}, apart from white space, begins with +\PName{string 2}, the \PName{then code} will be executed. Otherwise, the +\PName{else code} will be executed. There is no corresponding internal +command.% \EndIndexGroup \begin{Declaration} - \Macro{ifisdimen}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifisdimen}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} the expansion of\PName{code} results in -a \Macro{dimen}, which is also known as \TeX{} length register, the -\PName{then instructions} will be executed, otherwise the \PName{else - instructions}. The command is not completely expandable and there is no -corresponding internal command.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to a +\Macro{dimen}, i.\,e. a \TeX{} length register, the \PName{then code} will be +executed. Otherwise the \PName{else code} will be executed. The command is not +completely expandable, and there is no corresponding internal command.% \EndIndexGroup \begin{Declaration} - \Macro{ifisdimension}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifisdimension}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} \PName{code} expands to something with -the syntax of the value of a length, the \PName{then instructions} will be -executed, otherwise the \PName{else instructions}. Please -note\textnote{Attention!} that currently an invalid unit will result in an -error message. The command is not completely expandable and there is no -corresponding internal command.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to something +syntactically equivalent to a length, the \PName{then code} will be executed. +Otherwise the \PName{else code} will be executed. Note\textnote{Attention!} +that unknown units will cause an error message. The command is not completely +expandable, and there is no corresponding internal command.% \EndIndexGroup \begin{Declaration} - \Macro{ifisdimexpr}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifdimen}\Parameter{string}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} the expansion of\PName{code} results in -a \Macro{dimexpr}, which is also known as \TeX{} length expression, the -\PName{then instructions} will be executed, otherwise the \PName{else - instructions}. Note\textnote{Attention!} that illegal expressions will -result in error messages. The command is not completely expandable and there -is no corresponding internal command.% +The \PName{then code} will be executed if the first-order expansion of +\PName{string} consists of digits and a valid length unit. Otherwise, the +\PName{else code} will be used. There is no corresponding internal command.% \EndIndexGroup \begin{Declaration} - \Macro{ifisskip}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifisdimexpr}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} the expansion of\PName{code} results in -a \Macro{skip}, which is also known as \TeX{} distance register, the -\PName{then instructions} will be executed, otherwise the \PName{else - instructions}. The command is not completely expandable and there is no -corresponding internal command.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to an \eTeX{} +\Macro{dimexpr}\IndexCmd{dimexpr}, the \PName{then code} will be executed. +Otherwise, the \PName{else code} will be executed. Note\textnote{Attention!} +that illegal expressions will result in error messages. The command is not +completely expandable, and there is no corresponding internal command.% \EndIndexGroup \begin{Declaration} - \Macro{ifisglue}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifisskip}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} \PName{code} expands to something with -the syntax of the value of a skip, the \PName{then instructions} will be -executed, otherwise the \PName{else instructions}. Please -note\textnote{Attention!} that currently an invalid unit will result in an -error message. The command is not completely expandable and there is no -corresponding internal command.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to a +\Macro{skip}, i.\,e. a \TeX{} distance, the \PName{then code} will be +executed. Otherwise, the \PName{else code} will be executed. The command is not +completely expandable, and there is no corresponding internal command.% \EndIndexGroup \begin{Declaration} - \Macro{ifisglueexpr}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifisglue}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} the expansion of\PName{code} results in -a \Macro{glueexpr}, which is also known as \TeX{} distance expression, the -\PName{then instructions} will be executed, otherwise the \PName{else - instructions}. Note,\textnote{Attention!} that illegal expressions will -result in error messages. The command is not completely expandable and there -is no corresponding internal command.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to something +syntactically equivalent of the value of a skip, the \PName{then code} will be +executed. Otherwise, the \PName{else code} will be executed. +Note\textnote{Attention!} that invalid units will result in an error message. +The command is not completely expandable, and there is no corresponding +internal command.% \EndIndexGroup \begin{Declaration} - \Macro{ifiscount}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifisglueexpr}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} the expansion of\PName{code} results in -a \Macro{count}, which is also known as \TeX{} counter register, the -\PName{then instructions} will be executed, otherwise the \PName{else - instructions}. The command is not completely expandable and there is no -corresponding internal command. For test with \LaTeX{} counters, see -\DescRef{\LabelBase.cmd.ifiscounter}.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to a +\Macro{glueexpr}, i.\,e. an \eTeX{} distance expression, the \PName{then +code} will be executed. Otherwise, the \PName{else code} will be executed. +Note,\textnote{Attention!} that illegal expressions will result in error +messages. The command is not completely expandable, and there is no +corresponding internal command.% \EndIndexGroup \begin{Declaration} - \Macro{ifisinteger}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifiscounter}\Parameter{counter}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} \PName{code} expands to something with -the syntax of the value of a counter, which would be a negative or positive -integer, the \PName{then instructions} will be executed, otherwise the -\PName{else instructions}. The command is not completely expandable and there -is no corresponding internal command.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{counter} is defined as a +\LaTeX{} counter, the \PName{then code} will be executed. Otherwise, the +\PName{else code} will be executed. The command is not completely expandable, +and there is no corresponding internal command.% \EndIndexGroup \begin{Declaration} - \Macro{ifisnumexpr}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifiscount}\Parameter{count}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} the expansion of\PName{code} results in -a \Macro{numexpr}, which is also known as \TeX{} number expression, the -\PName{then instructions} will be executed, otherwise the \PName{else - instructions}. Note\textnote{Attention!} that illegal expressions will -result in error messages. The command is not completely expandable and there -is no corresponding internal command.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{count} expands to a +\Macro{count}, i.\,e. a \TeX{} counter, the \PName{then code} will be +executed. Otherwise, the \PName{else code} will be executed. The command is +not completely expandable, and there is no corresponding internal command. For +tests of \LaTeX{} counters, see \DescRef{\LabelBase.cmd.ifiscounter}.% \EndIndexGroup \begin{Declaration} - \Macro{ifiscounter}\Parameter{counter}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifisinteger}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} \PName{counter} is an already defined -\LaTeX{} counter, the \PName{then instructions} will be executed, otherwise -the \PName{else instructions}. The command is not completely expandable and -there is no corresponding internal command.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to something +syntactically equivalent to of the value of a counter, i.\,e. a negative or +positive integer, the \PName{then code} will be executed. Otherwise, the +\PName{else code} will be executed. The command is not completely expandable, +and there is no corresponding internal command.% \EndIndexGroup \begin{Declaration} \Macro{ifnumber}\Parameter{string}% - \Parameter{then instructions}\Parameter{else instructions} -\end{Declaration} -Note that this does not compare numbers. The \PName{then instructions} will -be executed if the one step expansion of \PName{string} consists of digits -only. Otherwise the \PName{else instructions} will be used. There is no -corresponding internal command. -% -\EndIndexGroup - - -\begin{Declaration} - \Macro{ifdimen}\Parameter{string}% - \Parameter{then instructions}\Parameter{else instructions} + \Parameter{then code}\Parameter{else code} \end{Declaration} -Note that this does not compare dimensions. The \PName{then instructions} will -be executed, if the one step expansion of \PName{string} consists of digits -and a valid unit of length. Otherwise, the \PName{else instructions} will be -used. There is no corresponding internal command. +The \PName{then code} will be executed if the first-order expansion of +\PName{string} consists only of digits. Otherwise, the \PName{else code} will +be used. There is no corresponding internal command. % \EndIndexGroup \begin{Declaration} - \Macro{if@atdocument}\ \PName{the instructions}\ % - \textMacro{else}\ \PName{else instructions}\ \textMacro{fi} + \Macro{ifisnumexpr}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -This command exists intentionally as internal command only. In the document -preamble \Macro{if@atdocument} is same as \Macro{iffalse}. After -\Macro{begin}\PParameter{document} it's the same as \Macro{iftrue}. Authors of -classes and packages may use this if a command should work somehow different -depending on whether it has been used in the preamble or inside the documents -body. Please note\textnote{Attention!} that this is a condition in \TeX{} -syntax not in \LaTeX{} syntax! -% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to a +\Macro{numexpr}, i.\,e. an \eTeX{} number expression, the \PName{then code} +will be executed. Otherwise, the \PName{else code} will be executed. +Note\textnote{Attention!} that illegal expressions will result in error +messages. The command is not completely expandable, and there is no +corresponding internal command.% \EndIndexGroup -\section{Definition of Language-Dependent Terms} +\section{Defining Language-Dependent Terms} \seclabel{languageSupport} \BeginIndexGroup \BeginIndex{}{language>definition} \index{language>dependent terms|see{language definition}} \index{terms>language-dependent|see{language definition}} -Normally, one has to change or define language-dependent terms like -\Macro{captionsenglish} in such a way that, in addition to the available terms, -the new or redefined terms are defined. This is made more difficult by the +Beginners often find it difficult to change language-dependent terms +\Macro{listfigurename}\IndexCmd{listfigurename}, by default usually ``List of +Figures.'' For example, if these are simply redefined with +\Macro{renewcommand} in the document preamble, they will not survive a later +change of language. If you use \Package{babel}\IndexCmd{babel}, the +redefinition in the preamble is overwritten with +\Macro{begin}\PParameter{document}. + +To define or change language-dependent terms, you normally have to redefine +commands like \Macro{captionsenglish} so that the new or redefined terms are +defined in addition to the previous terms. This is made more difficult by the fact that some packages like \Package{german}\IndexPackage{german} or -\Package{ngerman}\IndexPackage{ngerman} redefine those settings when the -packages are loaded. These definitions unfortunately occur in such a manner as -to destroy all previous private settings. That is also the reason why it makes -sense to delay changes with \Macro{AtBeginDocument} until -\Macro{begin}\PParameter{document}; that is, after package loading is -completed. The user can also use \Macro{AtBeginDocument} or redefine the -language-dependent terms after \Macro{begin}\PParameter{document}; that is, -not put them in the preamble at all. The package \Package{scrbase} -provides some additional commands for defining language-dependent terms. - +\Package{ngerman}\IndexPackage{ngerman} redefine those settings when they are +loaded. These definitions, unfortunately, occur in a way that undoes all the +previous changes. For this reason, it makes sense to delay changes until +\Macro{begin}\PParameter{document} by using \Macro{AtBeginDocument}, that is, +after all packages have been loaded. A user can also use +\Macro{AtBeginDocument} or redefine the language-dependent terms not in the +preamble but after \Macro{begin}\PParameter{document}. + +Adding further to the difficulty, some packages define additional +language-dependent terms in \Macro{captions\PName{language}}, while others use +\Macro{extras\PName{language}}. So the user must understand the commands very +well in order to use the correct one in the right way. + +The \Package{scrbase} package therefore provides additional commands to define +or modify language-dependent terms, relieving the user of many of these +problems. These commands also let you simultaneously define or change the +language-dependent terms of several dialects or forms of a language. \begin{Declaration} \Macro{defcaptionname}% @@ -1269,46 +1353,45 @@ provides some additional commands for defining language-dependent terms. \Macro{renewcaptionname*}% \Parameter{language list}\Parameter{term}\Parameter{definition} \end{Declaration} -Using one of these commands, the user can assign a \PName{definition} for a -particular language to a \PName{term}. Several languages can be concatenated -with comma to a \PName{language list}. The \PName{term} is always a -macro. The commands differ depending on whether a given language or a -\PName{term} within a given language are already defined or not at the -time the command is called. - -If a language is not defined, then \Macro{providecaptionname} does -nothing other than write a message in the log file. This happens only once -for each language. If a language is defined, but \PName{term} is not yet -defined for it, then it will be defined using \PName{definition}. The +With these four commands and their starred variants, you can assign a +\PName{definition} for a particular language to a \PName{term}. Several +languages can be concatenated with comma in the \PName{language list}. + +The \PName{term} is always a macro. The commands differ depending on whether a +given language or a \PName{term} within a given language is already defined at +the time the command is called. + +If a language is not defined, \Macro{providecaptionname} does nothing other +than write a message to the log file. This happens only once for each +language. If a language is defined but does not yet contain a corresponding +\PName{term}, it will be defined using \PName{definition}. However, the \PName{term} will not be redefined if the language already has such a definition; instead, an appropriate message is written to the log file. -The command \Macro{newcaptionname} has a slightly different behaviour. If a -language is not yet defined, then a new language command will be -created and a message written to the log file. For language -\PValue{USenglish}, for example, this would be the language command -\Macro{captionsUSenglish}. If \PName{term} is not yet defined in a -language, then it will be defined using \PName{definition}. If -\PName{term} already exists in a language, then this results in an error -message. - -The command \Macro{renewcaptionname} again behaves differently. It requires an -existing definition of \PName{term} in the languages. If neither -a language nor \PName{term} exist or \PName{term} is unknown in a -defined language, then an error message is given. Otherwise, the -\PName{term} for the language will be redefined according to -\PName{definition}. - -The\ChangedAt{v3.12}{\Package{scrbase}} command \Macro{defcaptionname} always -defines the \PName{term}. So previous definitions of \PName{term} for the -given \PName{language} will be overwritten. You may use this command even for -undefined languages. - -\KOMAScript{} employs \Macro{providecaptionname} in order to define the -commands in \autoref{sec:scrlttr2-experts.languages}. +On the other hand, if a language has not yet been defined, +\Macro{newcaptionname} defines a new language command will be created. For the +language \PValue{USenglish}, for example, this would be the language command +\Macro{captionsUSenglish}. This definition will also be noted in the log file. +If \PName{term} is not yet defined in this language, it will be defined using +\PName{definition}. If the \PName{term} already exists in a language, an error +message is issued. + +The \Macro{renewcaptionname} command behaves still differently. If a language +is undefined, an error message is issued. If the \PName{term} is not defined +in this language, an error message is also issued. If the \PName{term} is +defined in the language, it will be redefined to \PName{definition}. + +The\ChangedAt{v3.12}{\Package{scrbase}} \Macro{defcaptionname} command always +defines the \PName{term}, thus overwriting any previous definition. As with +\Macro{providecaptionname}, the language specified need not be previously +defined. + +\KOMAScript{} itself uses \Macro{providecaptionname} to define the commands in +\autoref{sec:scrlttr2-experts.languages}. +\DescPageRef{scrlttr2-experts.cmd.yourrefname}. \begin{Example} - If you prefer ``fig.'' instead of ``figure'' in \PValue{USenglish}, you may + If you prefer ``fig.'' instead of ``figure'' in \PValue{USenglish}, you can achieve this using: \begin{lstcode} \renewcaptionname{USenglish}{\figurename}{fig.} @@ -1322,35 +1405,35 @@ commands in \autoref{sec:scrlttr2-experts.languages}. \begin{lstcode} \renewcaptionname{USenglish,UKenglish}{\figurename}{fig.} \end{lstcode} - You can extend the \PName{language list} in the same manner by + You can extend the \PName{language list} in the same manner with \PValue{american}, \PValue{australian}, \PValue{british}, \PValue{canadian}, and \PValue{newzealand}. \end{Example} - -Since \KOMAScript~3.12\ChangedAt{v3.12}{\Package{scrbase}} you do not need to -delay the definition or redefinition until \Macro{begin}\PParameter{document} -using \Macro{AtBeginDocument} any longer because \Package{scrbase} does the -delay automatically for (re)definitions in the document's -preamble. Additionally, \Package{scrbase} tests if a redefinition should be -made in \Macro{extras\PName{language}} instead of -\Macro{captions\PName{language}} and does so automatically. The new star -variants of the commands always use \Macro{extras\PName{language}}. So -redefinition of language dependent terms for packages like \Package{hyperref} -that use \Macro{extras\PName{language}} should work as expected by the user. - -Language dependent terms usually defined by classes and language -packages are listed and described in \autoref{tab:scrbase.commonNames}. + +Since \KOMAScript~3.12\ChangedAt{v3.12}{\Package{scrbase}}, you no longer need +to delay the definition or redefinition until +\Macro{begin}\PParameter{document} using \Macro{AtBeginDocument} because +\Package{scrbase} does this itself if the commands are called in the +document's preamble. Additionally, \Package{scrbase} now checks if a term +should be redefined in \Macro{extras\PName{language}} instead of +\Macro{captions\PName{language}}. The new starred variants of the commands +always use \Macro{extras\PName{language}}. So redefining language-dependent +terms for packages like \Package{hyperref} that use +\Macro{extras\PName{language}} should work as expected. + +Language-dependent terms that are commonly defined by classes and language +packages are described in \autoref{tab:scrbase.commonNames}. \begin{desclist} \renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% \desccaption[{% - Overview of usual language dependent terms% + Overview of common language-dependent terms% }]{% - Overview of language dependent terms of usual language packages% + Overview of language-dependent terms of typical language packages% \label{tab:scrbase.commonNames}% }{% - Overview of usual language dependent terms - (\emph{continuation})% + Overview of common language dependent terms + (\emph{continued})% }% \entry{\Macro{abstractname}}{% heading of the abstract% @@ -1381,7 +1464,7 @@ packages are listed and described in \autoref{tab:scrbase.commonNames}. \IndexCmd{contentsname}% }% \entry{\Macro{enclname}}{% - prefix heading for the enclosure of a letter% + prefix heading for the enclosures of a letter% \IndexCmd{enclname}% }% \entry{\Macro{figurename}}{% @@ -1443,58 +1526,60 @@ packages are listed and described in \autoref{tab:scrbase.commonNames}. \EndIndexGroup -\section{Identification of \KOMAScript} +\section{Identifying \KOMAScript} \seclabel{identify} -Package \Package{scrbase} may be used independent of \KOMAScript{} with -other packages and classes. Nevertheless, it is a \KOMAScript{} package. For -this, \Package{scrbase} also provides commands to identify \KOMAScript{} and -to identify itself as a \KOMAScript{} package. +Although\,---\,or especially because\,---\,\Package{scrbase} is generally +designed as a package for authors of classes and packages, it is of course +used by the \KOMAScript{} classes and most \KOMAScript{} packages. It +therefore contains two commands that are present in all \KOMAScript{} classes +and all basic \KOMAScript{} packages. \begin{Declaration} \Macro{KOMAScript} \end{Declaration} -This command only sets the word ``\KOMAScript'' with sans-serif font and -a little bit tracking for the capitals. By the way: All \KOMAScript{} classes -and packages define this command, if it has not been defined already. The -definition is robust using \Macro{DeclareRobustCommand}. -% +This command simply sets the word ``\KOMAScript'' in sans-serif font and with +a slight tracking for the capitals. By the way, all \KOMAScript{} classes and +packages define this command as required. The definition is robust using +\Macro{DeclareRobustCommand}. Since packages that do not belong to +\KOMAScript{} can also define this command, its existence should not be +interpreted as an indication that a \KOMAScript{} package is in use.% \EndIndexGroup \begin{Declaration} \Macro{KOMAScriptVersion} \end{Declaration} -\KOMAScript{} defines the main version of \KOMAScript{} in this command. It -has the form ``\PName{date} \PName{version} \texttt{KOMA-Script}''. This main -version is same for all \KOMAScript{} classes and the \KOMAScript{} packages -that are essential for the classes. Because of this, it may be inquired after -loading \Package{scrbase}, too. For example, this document has been made using +\KOMAScript{} defines the major version of \KOMAScript{} in this command. It +has the form ``\PName{date} \PName{version} \texttt{KOMA-Script}''. This major +version is same for all \KOMAScript{} classes and all \KOMAScript{} packages +used by the classes. For this reason, it can be queried after you +load \Package{scrbase}, too. For example, this guide was made using \KOMAScript{} version ``\KOMAScriptVersion''. % \EndIndexGroup -\section{Extension of the \LaTeX{} Kernel} +\section{Extensions to the \LaTeX{} Kernel} \seclabel{latexkernel} -Sometimes the \LaTeX{} kernel itself provides commands, but lacks other, -similar commands that would often be useful, too. Some of those commands for -authors of packages and classes are provided by \Package{scrbase}. +Sometimes the \LaTeX{} kernel itself provides commands but lacks other very +similar commands that would often be useful. A few such commands are provided +by \Package{scrbase} for authors of packages and classes. \begin{Declaration} \Macro{ClassInfoNoLine}\Parameter{class name}\Parameter{information}% \Macro{PackageInfoNoLine}\Parameter{package name}\Parameter{information}% \end{Declaration}% -For authors of classes and package the \LaTeX{} kernel already provides -commands like \Macro{ClassInfo} and \Macro{PackageInfo} to write information. -together with the current line number, into the log-file. Besides -\Macro{PackageWarning} and \Macro{ClassWarning} to throw warning messages with -line numbers, it also provides \Macro{PackageWarningNoLine} and -\Macro{ClassWarningNoLine} for warning messages without line -numbers. Nevertheless, the commands \Macro{ClassInfoNoLine} and -\Macro{PackageInfoNoLine} for writing information without line numbers into the -log-file are missing. Package \Package{scrbase} provides them. +The \LaTeX{} kernel already provides authors of classes and packages commands +like \Macro{ClassInfo} and \Macro{PackageInfo} to write information, along +with the current line number, to the log file. In addition to +\Macro{PackageWarning} and \Macro{ClassWarning}, which throw warning messages +with line numbers, it also provides \Macro{PackageWarningNoLine} and +\Macro{ClassWarningNoLine} for warning messages without line numbers. However +the obvious commands \Macro{ClassInfoNoLine} and \Macro{PackageInfoNoLine}, +for writing information without line numbers into the log file, are missing. +The \Package{scrbase} package provides them. % \EndIndexGroup @@ -1502,47 +1587,47 @@ log-file are missing. Package \Package{scrbase} provides them. \begin{Declaration} \Macro{l@addto@macro}\Parameter{command}\Parameter{extension}% \end{Declaration}% -The \LaTeX{} kernel already provides an internal command \Macro{g@addto@macro} -to extend the definition of macro \Macro{command} by \PName{extension} -globally. This may be used only for macros that have no -arguments. Nevertheless, sometimes a command like this, that works locally to -a group instead of globally, could be useful. Package \Package{scrbase} -provides such a command with \Macro{l@addto@macro}. An alternative may be -usage of package \Package{etoolbox}\IndexPackage{etoolbox}, which provides -several of such commands for different purposes (see \cite{package:etoolbox}). -% +The \LaTeX{} kernel provides an internal command \Macro{g@addto@macro} to +extend the definition of macro \Macro{command} globally with +\PName{extension}. This works in this form only for macros that have no +arguments. However, sometimes you may need a command like this that works +locally within the current group. The \Package{scrbase} package provides such +a command with \Macro{l@addto@macro}. An alternative is to use the +\Package{etoolbox}\IndexPackage{etoolbox} or +\Package{xpatch}\IndexPackage{xpatch} package, which offers a whole range of +such commands for different purposes (see \cite{package:etoolbox} or +\cite{package:xpatch}).% \EndIndexGroup -\section{Extension of the Mathematical Features of \eTeX} +\section{Extensions to the Mathematical Features of \eTeX} \seclabel{etex} -\eTeX{}, that is meanwhile used by \LaTeX{} and needed by \KOMAScript{}, -provided with \Macro{numexpr}\IndexCmd{numexpr}, an extended feature for -calculation of simple arithmetic with \TeX{} counters and -integers. The four basic arithmetic operations and brackets are -supported. Correct rounding is done while division. Sometimes additional -operators would be useful. +\eTeX{}, which is used by \LaTeX{} and loaded by \KOMAScript{}, has extended +capabilities for calculating simple arithmetic with \TeX{} counters and +integers using \Macro{numexpr}\IndexCmd{numexpr}. The four basic arithmetic +operations and parentheses are supported. Division is rounded +correctly. Sometimes additional operators would be useful. \begin{Declaration} \Macro{XdivY}\Parameter{dividend}\Parameter{divisor}% \Macro{XmodY}\Parameter{dividend}\Parameter{divisor}% \end{Declaration}% -Having a division with remainder command\ChangedAt{v3.05a}{\Package{scrbase}} -\Macro{XdivY} gives the value of the integer quotient, with command -\Macro{XmodY} giving the value of the remainder. This kind of division is -defined: +The command\ChangedAt{v3.05a}{\Package{scrbase}} +\Macro{XdivY} returns the value of the integer quotient, with command +\Macro{XmodY} giving the value of the remainder. This type of of division is +defined by the equation \[ \textit{dividend} = \textit{divisor} \cdot \textit{integer quotient} + \textit{remainder} \] -with \textit{dividend} and \textit{remainder} are integer, \textit{remainder} -is greater or equal to \textit{divisor}, and \textit{divisor} is a natural -number greater than 0. +where \textit{dividend}, \textit{divisor}, and \textit{remainder} are +integers, \textit{remainder} is greater or equal to 0 and less than +\textit{divisor}, and \textit{divisor} is a natural number greater than 0. -The value may be used for assignment to a counter or directly in the -expression of \Macro{numexpr}. For output the value as an Arabic number has -to be prefixed by \Macro{the}.% +You can assign the value to a counter or use it directly within an expression +using \Macro{numexpr}. To output the value as an Arabic number, you must +prefix it with \Macro{the}.% % \EndIndexGroup % diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle-experts.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle-experts.tex index 5eba7be2753..c01bbdada5d 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle-experts.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle-experts.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrbookreportarticle-experts.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrbookreportarticle-experts.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -48,13 +48,13 @@ % ============================================================================ \KOMAProvidesFile{scrbookreportarticle-experts.tex} - [$Date: 2017-05-12 13:41:47 +0200 (Fri, 12 May 2017) $ + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (chapter: scrbook, scrreprt, scrartcl for experts)] -\translator{Gernot Hassenpflug\and Markus Kohm} +\translator{Gernot Hassenpflug\and Markus Kohm\and Karl Hagen} -% Date of the translated German file: 2017-05-08 +% Date of the translated German file: 2018-02-13 \chapter[{Additional Information about the Main Classes and \Package{scrextend}}]{Additional Information about the Main Classes @@ -67,29 +67,29 @@ \BeginIndex{Class}{scrbook}% \BeginIndex{Class}{scrreprt}% \BeginIndex{Package}{scrextend}% - -This chapter gives additional information about the \KOMAScript{} classes -\Class{scrbook}, \Class{scrreprt}, and \Class{scrartcl}. Some of the features -are also available for package \Package{scrextend}. \iffree{Some parts of the - chapter are subject to the \KOMAScript{} book \cite{book:komascript} - only. This should not be a problem, because the}{The} average user, who only -want to use the package, will not need the information, that is addressed to -users with non-standard requirements or who want to write their own classes -using a \KOMAScript{} class. Another part of the information describes features -of the classes that exist only because of compatibility to former -releases of \KOMAScript{} or the standard classes. The features, that exist -only because of compatibility to former \KOMAScript{} releases, are printed -with a sans serif font. You should not use them any longer. +This chapter provides additional information about the \KOMAScript{} classes +\Class{scrbook}, \Class{scrreprt}, and \Class{scrartcl} and some commands that +are also available in \Package{scrextend}. \iffree{Some parts of the chapter + are found only in the German \KOMAScript{} book \cite{book:komascript}. This + should not be a problem because the}{The} average user, who only wants to +use the classes, will seldom need this information. Some of this information +is addressed to users with non-standard requirements or who want to write +their own classes based on a \KOMAScript{} class. Other parts describe +features that exist only for the sake of compatibility with the standard +classes or earlier versions of \KOMAScript{}. Portions that describe features +that exist only for reasons of compatibility with earlier versions of +\KOMAScript{} are printed in sans serif font. You should not use them any +longer. \LoadNonFree{scrbookreportarticle-experts}{0} -\section{Additional Information to User Commands} +\section{Extensions to User Commands} \seclabel{addInfos} \LoadNonFree{scrbookreportarticle-experts}{1} -\section{Cooperation and Coexistence of \KOMAScript{} and Other Packages} +\section{\KOMAScript's Interaction with Other Packages} \seclabel{coexistence} \LoadNonFree{scrbookreportarticle-experts}{2} @@ -98,9 +98,9 @@ with a sans serif font. You should not use them any longer. \section{Expert Commands} \seclabel{experts} -This sections described commands, that are more or less out of average user's -interest. Nevertheless these commands provide additional features for -experts. Because the information is addressed to experts it's condensed. +This sections describes commands that are of little or no interest to the +average user. These commands offer additional features for experts. Because +the information is addressed to experts, it is condensed. % \subsection{Identification} % \seclabel{identification} @@ -109,17 +109,16 @@ experts. Because the information is addressed to experts it's condensed. \Macro{KOMAClassName}% \Macro{ClassName} \end{Declaration} -\Macro{KOMAClassName} stores the name of the currently used \KOMAScript{} -class. If someone wants to know, whether or not or a \KOMAScript{} class is -used or which \KOMAScript{} is used this may be tested with this command. In -difference to this, \Macro{ClassName} tells which would be the standard class, -that has been replaced by a \KOMAScript{} class. - -Please note\textnote{Attention!}, that the existence of -\DescRef{scrbase.cmd.KOMAScript}\IndexCmd{KOMAScript} is not a indication for -the usage of a \KOMAScript{} class. First of all: Every \KOMAScript{} package -and not only \KOMAScript{} classes define \Macro{KOMAScript}. Furthermore -other packages may also define the \KOMAScript{} word mark with this name.% +\Macro{KOMAClassName} stores the name of the \KOMAScript{} class currently in +use. So if you want to know if a \KOMAScript{} class is used, you can easily +test for this command. In contrast, \Macro{ClassName} indicates which standard +class has been replaced by this \KOMAScript{} class. + +Note\textnote{Attention!} in this context, however, that the existence of +\DescRef{scrbase.cmd.KOMAScript}\IndexCmd{KOMAScript} cannot guarantee that a +\KOMAScript{} class is in use. For one thing, all \KOMAScript{} packages +define this command. For another, other packages may find it useful to define +the \KOMAScript{} label using this name.% % \EndIndexGroup @@ -133,27 +132,26 @@ other packages may also define the \KOMAScript{} word mark with this name.% The\ChangedAt{v3.08}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} \KOMAScript{} classes do not use \Macro{addcontentsline}\IndexCmd{addcontentsline}% -\important{\Macro{addcontentsline}} directly. Instead they -call \Macro{addtocentrydefault} with similar arguments. The command may be used -for both, entries with and without number. Thereby \PName{level} is the -textual sectioning level, i.\,e., \PValue{part}, +\important{\Macro{addcontentsline}} directly to make entries in the table of +contents. Instead, they call \Macro{addtocentrydefault} with similar +arguments. The command can be used for both numbered and unnumbered entries. +The \PName{level} is the sectioning level, that is \PValue{part}, \PValue{chapter}, \PValue{section}, \PValue{subsection}, \PValue{subsubsection}, \PValue{paragraph}, or \PValue{subparagraph}. The -already formatted sectioning number is given by the second argument, -\PName{number}. This argument may be empty. The text of the entry is given by -argument \PName{heading}. It is recommended to protect fragile commands inside -this argument with prefix +formatted sectioning number is given the second argument, \PName{number}. This +argument can be empty. The text of the entry is given by the \PName{heading} +argument. You should protect fragile commands inside this argument with \Macro{protect}\IndexCmd{protect}\important{\Macro{protect}}. -There's one speciality for argument \PName{number}. An empty argument -signalizes, that an entry without number should be generated. \KOMAScript{} -uses +One notable feature of the \PName{number} argument is that an empty argument +indicates that an unnumbered entry should be generated. By default, +\KOMAScript{} uses \begin{quote} \Macro{addcontentsline}\PParameter{toc}\Parameter{level}% \Parameter{heading} \end{quote} -for this. Nevertheless, if the argument is not empty an entry with number -will be made and \PName{number} is the already formatted heading +for this. If the argument is not empty, however, an entry with number +will be created and \PName{number} is the formatted heading number. \KOMAScript{} uses \begin{quote}\raggedright \Macro{addcontentsline}\PParameter{toc}\Parameter{level}% @@ -162,10 +160,10 @@ number. \KOMAScript{} uses \PName{heading}\%\\ } \end{quote} -to make this. +to create this entry. -Package authors an authors of wrapper classes may redefined this command to -manipulate the entries. For example\textnote{Example} one could suggest +Package authors and authors of wrapper classes can redefine this command to +alter the entries. For example\textnote{Example}, you could use \begin{lstcode} \renewcommand{\addtocentrydefault}[3]{% \ifstr{#3}{}{% @@ -177,22 +175,22 @@ manipulate the entries. For example\textnote{Example} one could suggest }% }% \end{lstcode} -to omit entries with empty \PName{heading}. In real live this would not be -needed, because the \KOMAScript{} classes already use another method to -suppress empty entries. See the description of the structuring commands in -\autoref{sec:maincls.structure} from \DescPageRef{maincls.cmd.part} -onward for this.% +to\IndexCmd{ifstr} omit entries with an empty \PName{heading}. In practice, +such a change is not necessary because the \KOMAScript{} classes already use +another method to suppress empty entries. See the description of the +sectioning commands in \autoref{sec:maincls.structure}, starting on +\DescPageRef{maincls.cmd.part} for this.% % \EndIndexGroup \begin{Declaration} - \Macro{addparttocentry}\Parameter{number}\Parameter{heading}% - \Macro{addchaptertocentry}\Parameter{number}\Parameter{heading}% - \Macro{addsectiontocentry}\Parameter{number}\Parameter{heading}% - \Macro{addsubsectiontocentry}\Parameter{number}\Parameter{heading}% - \Macro{addsubsubsectiontocentry}\Parameter{number}\Parameter{heading}% - \Macro{addparagraphtocentry}\Parameter{number}\Parameter{heading}% + \Macro{addparttocentry}\Parameter{number}\Parameter{heading} + \Macro{addchaptertocentry}\Parameter{number}\Parameter{heading} + \Macro{addsectiontocentry}\Parameter{number}\Parameter{heading} + \Macro{addsubsectiontocentry}\Parameter{number}\Parameter{heading} + \Macro{addsubsubsectiontocentry}\Parameter{number}\Parameter{heading} + \Macro{addparagraphtocentry}\Parameter{number}\Parameter{heading} \Macro{addsubparagraphtocentry}\Parameter{number}\Parameter{heading} \end{Declaration}% The\ChangedAt{v3.08}{\Class{scrbook}\and \Class{scrreprt}\and @@ -201,10 +199,9 @@ command \DescRef{\LabelBase.cmd.addtocentrydefault}\IndexCmd{addtocentrydefault}% \important{\DescRef{\LabelBase.cmd.addtocentrydefault}} directly only if no individual command for the \PName{level} has been defined or if that command -is \Macro{relax}\IndexCmd{relax}\important{\Macro{relax}}. Nevertheless, the -default definition of all these individual commands simply call -\DescRef{\LabelBase.cmd.addtocentrydefault} with their own \PName{level} -passing their arguments through.% +is \Macro{relax}\IndexCmd{relax}\important{\Macro{relax}}. By default, all +these commands simply pass their own \PName{level} and arguments directly to +\DescRef{\LabelBase.cmd.addtocentrydefault}.% % \EndIndexGroup @@ -212,29 +209,33 @@ passing their arguments through.% \begin{Declaration} \Macro{raggedchapterentry} \end{Declaration} -Previous\ChangedAt{v3.21}{\Class{scrbook}\and \Class{scrreprt}} versions of -\KOMAScript{} provide a feature for printing chapter entries at the table of -contents left-aligned instead of justified by defining command -\Macro{raggedchapterentry} to be \Macro{raggedright}. Officially this feature -has been removed from \KOMAScript{} version 3.21 on. - -Indeed attribute \PValue{raggedentrytext} of toc-entry style \PValue{tocline} -of package \Package{tocbasic}\IndexPackage{tocbasic} has been implemented to -use such a macro \Macro{ragged\PName{entry level}entry} as an indicator for -left-aligned text. If such a macro is \Macro{raggedright}, the text is printed -left-aligned. With any other definition the text is printed justified. - -With this implementation of \PValue{raggedentrytext} full compatibility to the -previous documentation of \Macro{raggedchapterentry} is reached. As -stated formerly, other definitions of \Macro{raggedchapterentry}\,---\,and now -also of \Macro{raggedsectionentry} and similar macros for other entry -levels\,---\,could result in the potentially unexpected effect of justified -text. - -Nevertheless, it is recommended to use the attribute of style \PValue{tocline} -to select justified or left-aligned text.% +In\ChangedAt{v3.21}{\Class{scrbook}\and \Class{scrreprt}} earlier versions of +\KOMAScript{}, it was possible to define the \Macro{raggedchapterentry} macro +as \Macro{raggedright} to print chapter entries in the table of contents +left-aligned instead of fully justified. Officially, this feature has not +existed in \KOMAScript{} since version~3.21. + +In fact, the \PValue{raggedentrytext} attribute for the \PValue{tocline} +TOC-entry style of the \Package{tocbasic}\IndexPackage{tocbasic} package is +implemented by setting the \Macro{ragged\PName{entry level}entry} macro to +either \Macro{relax} or \Macro{raggedright}. This attribute is evaluated by +checking whether the corresponding macro is defined as \Macro{raggedright}. If +so, the text is printed left-aligned. With any other definition, no ragged +margins are used. + +Since it was previously documented that \Macro{raggedchapterentry} should not +be defined as anything other than \Macro{raggedright}, this behaviour is +compatible with the documented behaviour of earlier versions. As noted in +earlier releases, other definitions of \Macro{raggedchapterentry}\,---\,and +now also of \Macro{raggedsectionentry} and similar macros for other entry +levels\,---\,may lead to unexpected results. + +You should select the desired justification for the all table-of-contents +entries using the \PValue{raggedentrytext} attribute of \PValue{tocline} +rather than attempting to set the attribute for specific entry levels.% \EndIndexGroup + % \subsection{Font Settings} % \seclabel{fonts} @@ -243,53 +244,53 @@ to select justified or left-aligned text.% \Macro{@fontsizefilebase}% \Macro{changefontsizes}\Parameter{font size} \end{Declaration} -The prefix \File{scrsize} for file names of font size files, that has been -mentioned\iffree{ in \autoref{sec:maincls-experts.addInfos}}{} at -\DescPageRef{maincls-experts.option.fontsize} is only the default of the -internal macro \Macro{@fontsizefilebase}\IndexCmd{@fontsizefilebase}. This -default is used only, if the macro has not already be defined when loading a -\KOMAScript{} class or package \Package{scrextend}. Authors of wrapper classes -may define this macro with another file name prefix to use completely -different font size files. Also\textnote{Hint!} authors of wrapper classes -could change or deactivate the \emph{fallback} solution for unknown font sizes -by redefinition of macro -\Macro{changefontsizes}\important{\Macro{changefontsizes}}. This macro has -exactly one argument: the wanted \PName{font size}.% -% +The \File{scrsize} prefix for file names of font-size files described +in \autoref{sec:maincls-experts.addInfos}\iffree{}{ on +\DescPageRef{maincls-experts.option.fontsize}} is just the default for the +internal \Macro{@fontsizefilebase}\IndexCmd{@fontsizefilebase} macro. This +default is used only when the macro is not yet defined when loading a +\KOMAScript{} class or the \Package{scrextend} package. Authors of wrapper +classes can redefine this macro to use completely different font-size files. +Similarly\textnote{Hint!} authors of wrapper classes can change or deactivate +the fallback solution for unknown font sizes by redefining the +\Macro{changefontsizes}\important{\Macro{changefontsizes}} macro. This macro +has exactly one argument: the desired \PName{font size}. +However\textnote{Attention!}, the \Macro{changefontsizes} macro is not +designed as an end-user instruction.% \EndIndexGroup \begin{Declaration} - \Macro{newkomafont}\OParameter{warning message}\Parameter{element}% + \Macro{newkomafont}\OParameter{warning}\Parameter{element}% \Parameter{default}% - \Macro{aliaskomafont}\Parameter{alias name}\Parameter{element} + \Macro{aliaskomafont}\Parameter{alias}\Parameter{element} \end{Declaration} -Experts may use \Macro{newkomafont} to define a \PName{default} for the font -style of an \PName{element}. After this that default may be changed using -commands \DescRef{maincls.cmd.setkomafont} and -\DescRef{maincls.cmd.addtokomafont} (see \autoref{sec:maincls.textmarkup}, -\DescPageRef{maincls.cmd.setkomafont}). Of course this is not enough to use -the defined font style. The expert himself has to prepare his code to use -command \DescRef{maincls.cmd.usekomafont}% -\important{\DescRef{maincls.cmd.usekomafont}}\IndexCmd{usekomafont} (see -\DescPageRef{maincls.cmd.usekomafont}) with that \PName{element} at his code -definitions. - -The optional argument \PName{warning message} defines a warning message, -that \KOMAScript{} will show whenever the default font style of that -\PName{element} will be changed. The sender of the warning in such cases will -be the used \KOMAScript{} class or package \Package{scrextend}. - -Command \Macro{aliaskomafont} defines an \PName{alias name} to an already -defined \PName{element}. \KOMAScript{} will inform the user automatically -about the real name of the element, whenever an \PName{alias name} will be -used. An\textnote{Hint!} \PName{alias name} may be used, e.\,g., if a -developer finds a better name for an element, that has been defined formerly -with another name, if the old name should still be usable because of -compatibility. Also an \PName{alias name}s may increase usability, because -different users may find different names more or less intuitive. \KOMAScript{} -itself defines a lot of \PName{alias name}s for several \PName{element}s. -% +Experts can use \Macro{newkomafont} to define a \PName{default} for the font +style of an \PName{element}. Subsequently, that default can be changed with +the \DescRef{maincls.cmd.setkomafont} and \DescRef{maincls.cmd.addtokomafont} +commands (see \autoref{sec:maincls.textmarkup}, +\DescPageRef{maincls.cmd.setkomafont}). Of course, merely defining the font +style does not actually put it to use. You must make sure you include the +\DescRef{maincls.cmd.usekomafont}% +\important{\DescRef{maincls.cmd.usekomafont}}\IndexCmd{usekomafont} command +(see \DescPageRef{maincls.cmd.usekomafont}) for this \PName{element} in your +code at the appropriate places. Calling \Macro{newkomafont} for an existing +element will result in error messages. + +The optional \PName{warning} argument defines a warning message. The +\KOMAScript{} classes output it with \Macro{ClassWarning}, and the +\Package{scrextend} package with \Macro{PackageWarning}, whenever the default +font style of that \PName{element} is changed. The package \Package{scrkbase} +is listed as the generator of the warning. + +The \Macro{aliaskomafont} command defines an \PName{alias} for a previously +defined \PName{element}. \KOMAScript{} informs the user in the \File{log} file +about the actual name of the element if it uses an \PName{alias}. +You\textnote{Hint!} can use an \PName{alias}, for example, if you think of a +better name for an element and the old name should remain usable for the sake +of compatibility. It can also increase user-friendliness by creating aliases +for all the terms that different users may intuitively choose. \KOMAScript{} +itself makes use of this possibility.% \EndIndexGroup @@ -299,21 +300,21 @@ itself defines a lot of \PName{alias name}s for several \PName{element}s. \Macro{addtokomafontgobblelist}\Parameter{macro} \end{Declaration} As already mentioned in \autoref{part:forAuthors} of this manual, font -settings of elements should consist only in commands to select the size, -family, coding, series, shape, or colour. At least changing the colour is not -always transparent in \LaTeX{} and therefore could result in unwanted effects -if someone uses \DescRef{maincls.cmd.usekomafont} at an inappropriate state. - -Users tend to use different, somehow critical things in the font setting of an -element, e.\,g., \Macro{MakeUppercase} at the very end of the setting. As long -as possible, the internal usage of font settings has been implemented so that -such forbidden settings do not matter. Even using a command that expects an -argument, e.\,g., \Macro{textbf} instead of \Macro{bfseries}, would work -mostly, if it the last one in the font setting of an element\,---\,but without -warranty. - -Inside \KOMAScript, sometimes, it was necessary to restrict the font change to -real font settings. This has been done, e.\,g., using +settings of elements should consist only of commands to select the size, +family, encoding, series, shape, or colour. Colour changes are not +always transparent in \LaTeX{} and therefore can cause in unwanted side-effects +if you use \DescRef{maincls.cmd.usekomafont} at an inappropriate place. + +Users tend to put very different, sometimes critical, things into the font +setting of an element, such as \Macro{MakeUppercase} at the very end of the +setting. As much as possible, the internal use of the font settings has been +implemented so that many of these prohibited elements still do no harm, and it +usually works even if the last command in a font setting expects an argument, +for example using \Macro{textbf} instead of \Macro{bfseries}. But there is no +guarantee for that. + +Internally, \KOMAScript{} must sometimes limit font changes to real font +settings. This is accomplished, for example, by using \DescRef{maincls.cmd.usefontofkomafont}% \IndexCmd{usefontofkomafont}% \IndexCmd{usesizeofkomafont}\IndexCmd{useencodingofkomafont}% @@ -322,102 +323,108 @@ real font settings. This has been done, e.\,g., using (see \autoref{sec:maincls.textmarkup}, \DescPageRef{maincls.cmd.usefontofkomafont}). -Nevertheless, command \DescRef{maincls.cmd.usefontofkomafont} and it's -siblings have some limitations. Therefore you must not use a command that +Nevertheless, the \DescRef{maincls.cmd.usefontofkomafont} command and its +siblings have their limitations. Therefore you must not use a command that always needs a fully expandable argument inside the font setting of an -element. But this is exactly what \Macro{MakeUppercase} -needs. Therefore\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} \KOMAScript{} holds a list of macros, which should become -\Macro{relax} inside \DescRef{maincls.cmd.usefontofkomafont} and it's -siblings. Since \KOMAScript~3.24\ChangedAt{v3.24}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} only \Macro{normalcolor} is added to +element. But this is exactly what \Macro{MakeUppercase} needs. +Therefore\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and +\Class{scrartcl}} \KOMAScript{} maintains an internal list of macros that +should become \Macro{relax} inside \DescRef{maincls.cmd.usefontofkomafont} and +its siblings. Since \KOMAScript~3.24\ChangedAt{v3.24}{\Class{scrbook}\and +\Class{scrreprt}\and \Class{scrartcl}} only \Macro{normalcolor} is added to this list by default. -Amongst others, \Macro{normalcolor}, \Macro{MakeUppercase}, and -\Macro{MakeLowercase} are part of that list. More macros can be added one by -one using \Macro{addtokomafontrelaxlist}. - -Note that \PName{macro} will be set simply to \Macro{relax}. So if -\PName{macro} really has an argument, the argument will be execute -locally. Therefore you must not add commands like \Macro{setlength} to the -list. The user himself is responsible for all errors resulting in the usage of -\Macro{addtokomafontrelaxlist}. Additionally this command should not be -misunderstood as a legitimation for adding all kind of commands to the font -setting of an element! +Note that the given \PName{macro} is actually just set to \Macro{relax}. So +any arguments within the font setting will be executed locally, if applicable. +Therefore you should never add commands like \Macro{setlength} to the list. +You are responsible for all errors resulting caused by using +\Macro{addtokomafontrelaxlist}. Also, do not take this command as license to +add all sorts of commands to the font settings! For\ChangedAt{v3.24}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} some commands you may prefere to execute the first -argument unchanged. These commands can be added to another list using -\Macro{addtokomatfontonearglist}. By default \Macro{MakeUppercase} and +\Class{scrartcl}} commands whose first argument should be executed without an +additional group, there is \Macro{addtokomatfontonearglist}. The specified +macro is set to \Macro{@firstofone}. By default \Macro{MakeUppercase} and \Macro{MakeLowercase} are added to this list. -If\ChangedAt{v3.19}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} -a \PName{macro} and it's first argument should be ignored locally inside -\DescRef{maincls.cmd.usefontofkomafont} and it's siblings, you can use -\Macro{addtokomafontgobblelist} instead of \Macro{addtokomafontrelaxlist}. An -example for this is the command \Macro{color}, that has to be ignored with the -colour name and therefore is a default member of the gobble-list. - -Note, the defaults of the three lists can change. If you need a command inside -one of the lists you should add it yourself.% +If\ChangedAt{v3.19}{\Class{scrbook}\and \Class{scrreprt}\and +\Class{scrartcl}}, on the other hand, a \PName{macro} and its first argument +should be ignored locally inside \DescRef{maincls.cmd.usefontofkomafont} and +its siblings, you can use \Macro{addtokomafontgobblelist} instead of +\Macro{addtokomafontrelaxlist}. An example of this is the command +\Macro{color}, which must be ignored along with the colour name and therefore +is a member of this list by default. + +Note the defaults of these three lists may change in future version. If you +need a certain commands in one of the lists, you should should explicitly add +them yourself.% \EndIndexGroup \begin{Declaration} \Macro{IfExistskomafont}\Parameter{element}\Parameter{then code}% - \Parameter{else code} + \Parameter{else code} + \Macro{IfIsAliaskomafont}\Parameter{element}\Parameter{then code}% + \Parameter{else code} \end{Declaration} Which\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}\and \Class{scrlttr2}} elements are defined depends on the -version of \KOMAScript. So sometimes it may be useful to be able to test, -whether or not an \PName{element} exists. The command executes the \PName{then - code} only if an \PName{element} has been defined using -\DescRef{\LabelBase.cmd.newkomafont} or \DescRef{\LabelBase.cmd.aliaskomafont} -and therefore can be changed using \DescRef{maincls.cmd.setkomafont} or -\DescRef{maincls.cmd.addtokomafont} and can be used by one of the -\Macro{use\dots komafont} commands. Otherwise it executes the \PName{else - code}.% +version of \KOMAScript. So it sometimes makes sense to test in advance whether +a specific \PName{element} even exists. The \Macro{IfExistskomafont} command +executes the \PName{then code} if and only if an \PName{element} has been +defined using \DescRef{\LabelBase.cmd.newkomafont} or +\DescRef{\LabelBase.cmd.aliaskomafont} and therefore can also be changed using +\DescRef{maincls.cmd.setkomafont} or \DescRef{maincls.cmd.addtokomafont} and +can be used by one of the \Macro{use\dots komafont} commands. Otherwise it +executes the \PName{else code}.% + +In contrast, \Macro{IfIsAliaskomafont}\ChangedAt{v3.25}{\Class{scrbook}\and +\Class{scrreprt}\and \Class{scrartcl}\and \Class{scrlttr2}} executes +\PName{then code} only if \PName{element} has been defined with +\DescRef{\LabelBase.cmd.aliaskomafont} as an alias of another element. For +undefined elements as well as for elements defined with +\DescRef{\LabelBase.cmd.newkomafont}, however, it executes the +\PName{else code}.% \EndIndexGroup % \subsubsection{Paragraph Indention or Gap} % \seclabel{parskip} \begin{Declaration} - \Macro{setparsizes}\Parameter{indent}\Parameter{distance}%^^A - \Parameter{last line end space} + \Macro{setparsizes}\Parameter{indent}\Parameter{distance} + \Parameter{last-line end space} \end{Declaration} -With this command \KOMAScript{} provides to set the indent of the first line -of a new paragraph, the distance between paragraphs and the white space that -has to be at the end of the last line of each paragraph. This command should -be used whenever changes should also be recognized by option -\OptionValueRef{maincls}{parskip}{relative}. \KOMAScript{}\textnote{Beispiel} -itself uses this command, e.\,g., with +\KOMAScript{} provides the option to set the indent of the first line of a new +paragraph, the distance between paragraphs, and the white space required at the +end of the last line of each paragraph. You should use this command whenever +the \OptionValueRef{maincls}{parskip}{relative} option should recognize these +changes. \KOMAScript{}\textnote{example} itself uses this command, for +example, in the form \begin{lstcode} \setparsizes{0pt}{0pt}{0pt plus 1fil} \end{lstcode} -to switch of paragraph indent and distance between paragraphs and to allow any -white space at the end of the last line of paragraphs. This make sense, if a -paragraph consists of a box only, that should be printed without vertical -distance but with the whole column width. If, in opposite to that, the box -should only span the whole width but should be printed with the current -settings of paragraph indent and distance between paragraphs, usage of +to eliminate both the paragraph indentation and inter-paragraph spacing, as +well as to allow any amount of white space at the end of the last line of the +paragraph. Such values are useful if a paragraph consists of only a box that +should be printed without vertical spacing and filling the whole column +width. If, on the other hand, the box should only span the whole width but use +the current settings for indentation and distance between paragraphs, then \begin{lstcode} \setlength{\parfillskip}{0pt plus 1fil} \end{lstcode} -would be recommended. - -Since \KOMAScript~3.17\ChangedAt{v3.17}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} changing or -reactivation\IndexCmd{activateareas} of the typing area or the margins (see -\autoref{cha:typearea}) will also reactivate the values of \Macro{setparsizes} -if they have not been changed since the last usage of this command. This is -one more reason not to change these values without using \KOMAScript. With -compatibility to a \KOMAScript{} version prior to 3.17 (see +is preferable. + +Starting with \KOMAScript~3.17\ChangedAt{v3.17}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}}, recalculating or +reactivating\IndexCmd{activateareas} the type area or the margins (see +\autoref{cha:typearea}) also readjusts the values of \Macro{setparsizes} if +they have not been changed in the meantime. This is one more reason not to +change these values without using \KOMAScript. Setting compatibility to a +\KOMAScript{} version prior to 3.17 (see \autoref{sec:maincls.compatibilityOptions}, -\DescPageRef{maincls.option.version}, option -\DescRef{maincls.option.version}% +\DescPageRef{maincls.option.version}, option \DescRef{maincls.option.version}% \IndexOption{version}\important{\OptionValueRef{maincls}{version}{3.17}}) -this reactivation of the \Macro{setparsizes} values is deactivated.% +disables this recalculation.% % \EndIndexGroup @@ -436,70 +443,74 @@ this reactivation of the \Macro{setparsizes} values is deactivated.% \Macro{ProvideSectionCommand}\OParameter{attributes}\Parameter{name} \end{Declaration} With\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} these commands you can either define a new section-like -command \Macro{\PName{name}} or change an already defined sectioning command -\Macro{\PName{name}}. To do so you use the optional argument to setup several + \Class{scrartcl}} these commands you can either define a new sectioning +command, \Macro{\PName{name}}, or modify an existing sectioning command, +\Macro{\PName{name}}. To do so, you use the optional argument to set several \PName{attributes}. The \PName{attributes} are a comma-separated list of -\PName{key}=\PName{value} assignments. Beside the style-independent attributes -shown in \autoref{tab:maincls-experts.declaresection.keys}, there are style -dependent attributes, too. Currently the following styles are provided: -\begin{labeling}{\PValue{chapter}:} +\PName{key}=\PName{value} assignments. In addition to the style-independent +attributes shown in\autoref{tab:maincls-experts.declaresection.keys}, +\autopageref{tab:maincls-experts.declaresection.keys}, there are also +attributes that depend on the style. Currently the following styles are +available: +\begin{description}\setkomafont{descriptionlabel}{} \item[\PValue{chapter}:] \ChangedAt{v3.18}{\Class{scrbook}\and - \Class{scrreprt}}Style of chapter headings. This style is currently used - for \DescRef{maincls.cmd.chapter}\IndexCmd{chapter} and indirectly for - \DescRef{maincls.cmd.addchap}\IndexCmd{addchap}. You can define new - section-like commands using this style. To define new or to reconfigure - existing commands you can also use the additional attributes of + \Class{scrreprt}}The style for chapter headings. This style is used by + default for \DescRef{maincls.cmd.chapter}\IndexCmd{chapter} and indirectly + for \DescRef{maincls.cmd.addchap}\IndexCmd{addchap}. You can define new + sectioning commands using this style, but then they do not automatically + have an \Macro{add\dots} variant. To configure existing or new sectioning + commands, you can also use the attributes of \autoref{tab:maincls-experts.declarechapterstyle.keys}, \autopageref{tab:maincls-experts.declarechapterstyle.keys}. - Note\textnote{Attention!} that command \DescRef{maincls.cmd.addchap} and the - star variants are configured automatically together with - \DescRef{maincls.cmd.chapter} and should not be changed independently. Note + Note\textnote{Attention!} that the \DescRef{maincls.cmd.addchap} command, + like the starred variants, is configured automatically with + \DescRef{maincls.cmd.chapter} and cannot be modified independently. Note that \Class{scrartcl}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} does not provide this style. \item[\PValue{part}:] \ChangedAt{v3.18}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}}Style part headings. This style is - currently used for \DescRef{maincls.cmd.part}\IndexCmd{part} and indirectly - for \DescRef{maincls.cmd.addpart}\IndexCmd{addpart}. You can define new - section-like commands using this style. To define new or to reconfigure - existing commands you can also use the additional attributes of + \Class{scrreprt}\and \Class{scrartcl}}The style for part headings. This + style is used by default for \DescRef{maincls.cmd.part}\IndexCmd{part} and + indirectly for \DescRef{maincls.cmd.addpart}\IndexCmd{addpart}. You can + define new sectioning commands using this style, but then they do not + automatically have an \Macro{add\dots} variant. To configure existing or new + sectioning commands, you can also use the attributes of \autoref{tab:maincls-experts.declarepartstyle.keys}, \autopageref{tab:maincls-experts.declarepartstyle.keys}. - Note\textnote{Attention!} that command \DescRef{maincls.cmd.addpart} and the - star variants are configured automatically together with - \DescRef{maincls.cmd.part} and should not be changed independently. -\item[\PValue{section}:] Style of section headings. This style is currently + Note\textnote{Attention!} that the \DescRef{maincls.cmd.addpart} command, + like the starred variants, is configured automatically with + \DescRef{maincls.cmd.part} and cannot be modified independently. +\item[\PValue{section}:] The style for section headings. This style is currently used for \DescRef{maincls.cmd.section}\IndexCmd{section}, \DescRef{maincls.cmd.subsection}\IndexCmd{subsection}, \DescRef{maincls.cmd.subsubsection}\IndexCmd{subsubsection}, \DescRef{maincls.cmd.paragraph}\IndexCmd{paragraph}, and \DescRef{maincls.cmd.subparagraph}\IndexCmd{subparagraph}. You can define - new section-like commands using this style. To define new or to reconfigure - existing commands you can also use the additional attributes of + new sectioning commands using this style. To configure existing or new + sectioning commands, you can also use the attributes of \autoref{tab:maincls-experts.declaresectionstyle.keys}, - \autopageref{tab:maincls-experts.declaresectionstyle.keys}. Definitions of - new commands need\ChangedAt{v3.24}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} at least the \PName{key}s \PValue{style}, - \PValue{afterskip}, \PValue{beforeskip}, and \PValue{level}. \PValue{font} - and \PValue{indent} are recommended. Need for \PValue{tocindent} and - \PValue{tocnumwidth} depend on the command \PName{name}. This is also true - if a command that was not a section-like command before will be redefined as - a section-like command using - \Macro{RedeclareSectionCommand}. Note\textnote{Attention!} that command - \Macro{addsec} and the star variants are configured automatically together - with \DescRef{maincls.cmd.section} and should not be changed - independently. Defining a new section-like command with this style will also - define an element with the same \PName{name} and the possibility to change - its font using \DescRef{maincls.cmd.setkomafont} or - \DescRef{maincls.cmd.addtokomafont} (see \autoref{sec:maincls.textmarkup}, - \DescPageRef{maincls.cmd.setkomafont}), if such an element does not already - exist. -\end{labeling} - + \autopageref{tab:maincls-experts.declaresectionstyle.keys}. When redefining + a command, you need\ChangedAt{v3.24}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} at least the \PName{key}s + \PValue{style}, \PValue{afterskip}, \PValue{beforeskip}, and \PValue{level}. + \PValue{font} and \PValue{indent} are recommended. \PValue{tocindent} and + \PValue{tocnumwidth} may also be required depending on the command's + \PName{name}. This also applies if a command that was not previously a + sectioning command is redefined as a sectioning command using + \Macro{RedeclareSectionCommand}. Note\textnote{Attention!} that the + \Macro{addsec} command and its starred variants are configured automatically + with \DescRef{maincls.cmd.section} and cannot be changed independently. +\end{description} +Defining a sectioning command also creates an element with the same +\PName{name}, if it does not already exist. For \PValue{chapter} and +\PValue{part}, elements are also created for the prefix line. You can change +its font settings using \DescRef{maincls.cmd.setkomafont} or +\DescRef{maincls.cmd.addtokomafont} (see \autoref{sec:maincls.textmarkup}, +\DescPageRef{maincls.cmd.setkomafont}). + \begin{table} - \caption[{Style-independent attributes at the declaration of section-like - commands}]{Available \PName{key}s and \PName{value}s for the - style-independent \PName{attributes} declaring a section-like command}% + \caption[{Style-independent attributes for declaring sectioning + commands}]{Available \PName{key}s and \PName{value}s for + style-independent \PName{attributes} when declaring sectioning command}% \label{tab:maincls-experts.declaresection.keys}% \begin{tabularx}{\linewidth}{llX} \toprule @@ -508,48 +519,46 @@ dependent attributes, too. Currently the following styles are provided: \PValue{counterwithin} & \PName{counter name} & The value of the counter of the heading should depend on \PName{counter name}. Whenever \Macro{stepcounter} or \Macro{refstepcounter} increases the value of - \PName{counter name}, the value of the counter of this heading should be - set to 0. Also the output of the value of this heading should be prefixed - by \Macro{the\PName{counter name}} - followed by a dot.\\ + \PName{counter name}, the value of the counter of this heading is + reset to 0. In addition, \Macro{the\PName{counter name}} is prefixed + with a dot when this counter is output.\\ \ChangedAt{v3.19}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartl}}% \PValue{counterwithout} & \PName{counter name} & Cancels a prior \PValue{counterwithin} setting. Therefore it makes sense only if you - re-define an existing - section-like command.\\ - \PValue{expandtopt} & \PName{switch}& If the switch is on, all following - values for lengths will be completely expanded, evaluated and stored as - \texttt{pt} values. If the switch is off, all following values for - lengths will be completely expanded, tentatively evaluated but only - expanded stored. Any values from \autoref{tab:truefalseswitch}, - \autopageref{tab:truefalseswitch} may be used. Default is - \PValue{false}.\\ - \PValue{level} & \PName{integer} & A number, denoting depth of section - (see counter \DescRef{maincls.counter.secnumdepth}, + redefine an existing sectioning command.\\ + \PValue{expandtopt} & \PName{switch}& If the switch is on, all subsequent + values for lengths will be completely expanded, evaluated, and stored as + \texttt{pt} values when they are defined. This means lengths no longer + depend on the current font size. If the switch is off, all subsequent + values for lengths will be tentatively expanded and evaluated but stored + for full evaluation at application time. You can use any values from + \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. The + default is \PValue{false}.\\ + \PValue{level} & \PName{integer} & The numerical value of the sectioning level + (see the \DescRef{maincls.counter.secnumdepth} counter, \autoref{sec:maincls.structure}, \DescPageRef{maincls.counter.secnumdepth}); - the value should be unique.\\ + the value should be unique and is mandatory for new levels.\\ \PValue{style} & \PName{name} & Defines the style of the heading.\\ \ChangedAt[2016/03]{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - \PValue{tocstyle} & \PName{name} & Defines the style of the entries into - the table of contents. You can use every already defined toc-entry style + \PValue{tocstyle} & \PName{name} & Defines the style of the entries in + the table of contents. You can use every previously defined TOC-entry style (see \autoref{sec:tocbasic.tocstyle}). An empty \PName{name} prevents a - new definition of the toc-entry + new definition of the TOC-entry command \Macro{l@\dots}.\\ \ChangedAt[2016/03]{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% \PValue{toc\PName{option}} & \PName{value} & Additional options depending - on the TOC-entry style given by \Option{tocstyle}. See + on the TOC-entry style selected with \Option{tocstyle}. See \autoref{sec:tocbasic.tocstyle}, \autopageref{sec:tocbasic.tocstyle} for - additional information about TOC-entry styles. See + additional information about TOC-entry styles. You can find the attributes + that can be used as \PName{option}s for the predefined TOC-entry styles of + the \Package{tocbasic} package in \autoref{tab:tocbasic.tocstyle.attributes}, - \autopageref{tab:tocbasic.tocstyle.attributes} for information about the - attributes of the predefined TOC-entry styles of package - \Package{tocbasic}, that can be used - as \PName{option}.\\ + \autopageref{tab:tocbasic.tocstyle.attributes}.\\ % \PValue{tocindent} & \PName{length} & Total indentation from the left % margin of the entry in the table of % contents corresponding to this @@ -575,250 +584,205 @@ dependent attributes, too. Currently the following styles are provided: \end{table} \begin{table} - \caption[{Attributes of the style \PValue{section} declaring a section-like - command}]{Additional \PName{keys} and \PName{value}s of attributes - declaring a section-like command with style \PValue{section}}% + \caption[{Attributes of the \PValue{section} style when declaring a + sectioning command}]{Additional \PName{key}s and \PName{value}s for + attributes when declaring a sectioning command with the \PValue{section} + style}% \label{tab:maincls-experts.declaresectionstyle.keys}% \begin{tabularx}{\linewidth}{llX} \toprule \PName{key} & \PName{value} & Description \\ \midrule \PValue{afterskip} & \PName{length} & A negative value activates a run-in - heading. The absolute value is the - skip to leave to right of the run-in - heading. A positive value is the - vertical skip below the heading.\\ - \PValue{beforeskip} & \PName{length}& The absolute value of the vertical - skip before the heading. If the - value is negative, then the - paragraph indent of the text - following the heading is - suppressed.\\ - \PValue{font} & \PName{font commands} & - The initial font setting that - should be used beside - \DescRef{maincls.fontelement.disposition} for the - heading. You can use all settings, - that are allowed for - \DescRef{maincls.cmd.setkomafont} and - \DescRef{maincls.cmd.addtokomafont} for the - element of the heading.\\ - \PValue{indent} & \PName{length} & Indentation of heading from the left - margin.\\ + heading. The absolute value is the horizontal space after the heading. A + positive value is the vertical skip below the heading.\\ + \PValue{beforeskip} & \PName{length} & The amount indicates the vertical + skip before the heading. If the value is negative, a positive distance + is still inserted, but in this case the paragraph indent of the text + following the heading is suppressed.\\ + \PValue{font} & \PName{font commands} & The font settings that should be + used for the heading in addition to + \DescRef{maincls.fontelement.disposition}. You can use all settings that + are allowed for \DescRef{maincls.cmd.setkomafont} and + \DescRef{maincls.cmd.addtokomafont} for the element of the heading.\\ + \PValue{indent} & \PName{length} & The indentation of heading from the + left margin.\\ \bottomrule \end{tabularx} \end{table} \begin{table} - \caption[{Attributes of the style \PValue{chapter} declaring a section-like - command}]{Additional \PName{keys} and \PName{value}s of attributes - declaring a section-like command with style \PValue{chapter}}% + \caption[{Attributes of the \PValue{chapter} style when declaring a + sectioning command}]{Additional \PName{keys} and \PName{value}s for + attributes when declaring a sectioning command with the \PValue{chapter} + style}% \label{tab:maincls-experts.declarechapterstyle.keys}% \begin{tabularx}{\linewidth}{llX} \toprule \PName{key} & \PName{value} & Description \\ \midrule - \PValue{afterskip} & \PName{length} & The absolute value is the - vertical skip below the heading.\\ - \PValue{beforeskip} & \PName{length}& The absolute value of the vertical - skip before the heading. If the - value is negative, then the - paragraph indent of the text - following the heading is - suppressed. This will be done also - for positive values if class option - \DescRef{maincls.option.version} is - set to a value less than 3.22.\\ - \PValue{font} & \PName{font commands} & - The initial font setting that - should be used beside - \DescRef{maincls.fontelement.disposition} for the - heading. You can use all settings, - that are allowed for - \DescRef{maincls.cmd.setkomafont} and - \DescRef{maincls.cmd.addtokomafont} for the - element of the heading.\\ + \PValue{afterskip} & \PName{length} & The value is the vertical skip below + the heading.\\ + \PValue{beforeskip} & \PName{length} & The value of the vertical skip + before the heading. If the value is negative, then the positive distance + is nevertheless inserted, and the paragraph indent of the text following + the heading is suppressed. There will also be no indentation even for + positive values if the \DescRef{maincls.option.version} class option is + set to a value less than 3.22.\\ + \PValue{font} & \PName{font commands} & The font setting to use for the + heading in addition to \DescRef{maincls.fontelement.disposition}. You + can use all settings, that are allowed for + \DescRef{maincls.cmd.setkomafont} and + \DescRef{maincls.cmd.addtokomafont} for this element.\\ \PValue{innerskip} & \PName{length} & The vertical skip between the prefix - line and the heading's text, if a - prefix line is used.\\ - \PValue{pagestyle} & \PName{page style name} & - The name of the page style that - should be used automatically on - pages with the heading. There is no - validation whether or not - \PName{page style name} is really - the name of a page style. Therefore, - wrong names will result in error - messages at usage of the - section-like command.\\ - \PValue{prefixfont} & \PName{font commands} & - The initial font setting that - should be used beside - \DescRef{maincls.fontelement.disposition} - and the - element of the heading for the - prefix line of the heading. You can - use all settings that are allowed - for - \DescRef{maincls.cmd.setkomafont} - and - \DescRef{maincls.cmd.addtokomafont} - for the element of the prefix - line.\\ + line and the heading's text, if a prefix line is used.\\ + \PValue{pagestyle} & \PName{page style name} & The name of the page style + to use automatically for pages with the heading. There is no check to + see if the \PName{page style name} is valid. Therefore, incorrect names + will result in error messages when the sectioning command is used.\\ + \PValue{prefixfont} & \PName{font commands} & The font setting to use + for the prefix line of the heading, in addition to the + \DescRef{maincls.fontelement.disposition} and sectioning command + elements. You can use all settings that are allowed for + \DescRef{maincls.cmd.setkomafont} and + \DescRef{maincls.cmd.addtokomafont} for the element of the prefix + line.\\ \bottomrule \end{tabularx} \end{table} \begin{table} - \caption[{Attributes of the style \PValue{part} declaring a section-like - command}]{Additional \PName{keys} and \PName{value}s of attributes - declaring a section-like command with style \PValue{part}}% + \caption[{Attributes of the \PValue{part} style when declaring a sectioning + command}]{Additional \PName{keys} and \PName{value}s for attributes + when declaring a sectioning command with the \PValue{part} style}% \label{tab:maincls-experts.declarepartstyle.keys}% \begin{tabularx}{\linewidth}{llX} \toprule \PName{key} & \PName{value} & Description \\ \midrule - \PValue{afterskip} & \PName{length} & The absolute value is the - vertical skip below the heading.\\ - \PValue{beforeskip} & \PName{length}& The absolute value of the vertical - skip before the heading.\\ - \PValue{font} & \PName{font commands} & - The initial font setting that - should be used beside - \DescRef{maincls.fontelement.disposition} - for the - heading. You can use all settings, - that are allowed for - \DescRef{maincls.cmd.setkomafont} and - \DescRef{maincls.cmd.addtokomafont} - for the element of the heading.\\ + \PValue{afterskip} & \PName{length} & The value is the vertical skip below + the heading.\\ + \PValue{beforeskip} & \PName{length}& The value is the vertical skip above + the heading.\\ + \PValue{font} & \PName{font commands} & The font setting to use for the + heading in addition to \DescRef{maincls.fontelement.disposition}. You + can use all settings that are allowed for + \DescRef{maincls.cmd.setkomafont} and + \DescRef{maincls.cmd.addtokomafont} for the element of the heading.\\ \PValue{innerskip} & \PName{length} & % \OnlyAt{\Class{scrbook}\and % \Class{scrreprt}}% - The vertical skip between the prefix - line and the heading's text of - \Class{scrbook} and - \Class{scrreprt}.\\ + The vertical skip between the prefix line and the heading text in + \Class{scrbook} and \Class{scrreprt}.\\ \PValue{pagestyle} & \PName{page style name} & % \OnlyAt{\Class{scrbook}\and % \Class{scrreprt}}% - The name of the page style that - should be used automatically on - pages with the heading. There is no - validation whether or not - \PName{page style name} is really - the name of a page style. Therefore, - wrong names will result in error - messages at usage of the - section-like command. This feature - is only available with - \Class{scrbook} or - \Class{scrreprt}.\\ - \PValue{prefixfont} & \PName{font commands} & - The initial font setting that - should be used beside - \DescRef{maincls.fontelement.disposition} - and the - element of the heading for the - prefix line of the heading. You can - use all settings that are allowed - for - \DescRef{maincls.cmd.setkomafont} - and - \DescRef{maincls.cmd.addtokomafont} - for the element of the prefix - line.\\ + The name of the page style to use automatically on pages with the + heading. There is no check to see if \PName{page style name} is valid. + Therefore, incorrect names will result in error messages when the + sectioning command is used. This feature only exists in \Class{scrbook} + and\Class{scrreprt}.\\ + \PValue{prefixfont} & \PName{font commands} & The font setting to use for + the prefix line of the heading, in addition to the + \DescRef{maincls.fontelement.disposition} and sectioning command + elements. You can use all settings that are allowed for + \DescRef{maincls.cmd.setkomafont} and + \DescRef{maincls.cmd.addtokomafont} for the element of the prefix + line.\\ \bottomrule \end{tabularx} \end{table} -\Macro{DeclareNewSectionCommand} defines a new section-like command. If the +\Macro{DeclareNewSectionCommand} defines a new sectioning command. If the same \PName{name} is already used by \TeX{} for something else, the command will result in an error message and will not define anything. -\Macro{ProvideSectionSommand} is similar but does not show any error message. +\Macro{ProvideSectionSommand} behaves similarly but does not issue an error +message. -\Macro{RedeclareSectionCommand} can only change an existing command to a -section-like command with given \PName{attributes}. There is no pre-validation -to make sure that \Macro{\PName{name}} was a section-like command -before. However, it has to be an already used command sequence \PName{name}. +\Macro{RedeclareSectionCommand}, on the other hand, can only change an +existing command to a sectioning command with the specified +\PName{attributes}. It does not check whether \Macro{\PName{name}} is already +a sectioning command. It only needs to be a \PName{name} already a \TeX +command. \Macro{DeclareSectionCommand} does not check whether or not \PName{name} is -an already used \TeX{} command sequence. It just defines a section-like -command \Macro{\PName{name}} with the given \PName{attributes}. - -Every section-like command has also a corresponding counter with the same -\PName{name}, that will be allocated using \Macro{newcounter} if -necessary. The same rule applies to the corresponding output of the counter: -\Macro{the\PName{name}}, the output format: \Macro{\PName{name}format}, the -command to generate a running head: \Macro{\PName{name}mark}, the counter -format of the running head: \Macro{\PName{name}markformat}, the font element: -\FontElement{\PName{name}}, and the section depth number: -\Macro{\PName{name}numdepth}. The command for the running head -\Macro{\PName{name}mark} will be defined to not generate any running head. The -output of the counter, \Macro{the\PName{name}}, will show an Arabic number. If -the \PName{key} \PValue{counterwithin} defines a counter the heading number -depends on, the output of the counter will be prefixed by the output of that -counter followed by a dot. - -Beside\ChangedAt[2016/03]{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} the section-like command, a command for corresponding -entries to the table of contents is defined also. This is done using package -\Package{tocbasic}\important{\Package{tocbasic}}\IndexPackage{tocbasic}. -Attribute \PName{tocstyle} defines the style of those entries. If you set an -empty \PName{name}, e.\,g., using \OptionValue{tocstyle}{} or -\OptionValue{tocstyle}{\{\}}, the entry command will not be changed. This is -important, if you use another package to modify the table of contents. If you -do not set attribute \PValue{tocstyle} the already configured style will be -used again. +an existing \TeX{} command name. It just defines a sectioning +command \Macro{\PName{name}} with the specified \PName{attributes}. + +Each sectioning command also has a corresponding counter with the same +\PName{name} that is allocated with \Macro{newcounter} if necessary. The same +naming rule applies to the corresponding output of the counter +(\Macro{the\PName{name}}), the counter's format (\Macro{\PName{name}format}), +the command to generate a running head (\Macro{\PName{name}mark}), the format +of the counter in the running head (\Macro{\PName{name}markformat}), the font +element (\FontElement{\PName{name}}), and the section-depth number +(\Macro{\PName{name}numdepth}). The command for the running head, +\Macro{\PName{name}mark}, is defined by default not to generate a running +head. The default output of the counter \Macro{the\PName{name}} is an Arabic +number. If the counter is defined as depending on another counter with the +\PValue{counterwithin} \PName{key}, the output of this counter will be +prefixed by a dot. + +In\ChangedAt[2016/03]{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} addition to the sectioning command itself, a command for +corresponding entries to the table of contents is also defined. This is done +using the \hyperref[cha:tocbasic]{\Package{tocbasic}}% +\important{\hyperref[cha:tocbasic]{\Package{tocbasic}}}\IndexPackage{tocbasic} +package. The \PName{tocstyle} attribute defines the style of those entries. If +you set an empty \PName{name}, e.\,g. using \OptionValue{tocstyle}{} or +\OptionValue{tocstyle}{\{\}}, the command for the TOC entry will not be +changed. This is important, for example, if you use another package to modify +the table of contents. If you do not set the \PValue{tocstyle} attribute, the +previous style will be used again during the redefinition. The\ChangedAt[2016/03]{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} different toc-entry styles also have different, additional -attributes. You can set them here too, if you prefix them with -\PValue{toc}. For example, you can setup the level of the toc-entries, -\PValue{level}, using \PValue{toclevel}, the indention, \PValue{indent}, using -\PValue{tocindent}, or the number width, \PValue{numwidth}, using -\PValue{tocnumwidth}. For more toc-entry style attributes see -\autoref{sec:tocbasic.tocstyle}, \autopageref{sec:tocbasic.tocstyle}. + \Class{scrartcl}} different TOC-entry styles also have different additional +attributes. You can set them directly if you prefix them with \PValue{toc}. +For example, you can set the level of the TOC entries, \PValue{level}, using +\PValue{toclevel}, the indention, \PValue{indent}, using \PValue{tocindent}, +or the number width, \PValue{numwidth}, using \PValue{tocnumwidth}. For more +TOC-entry style attributes see \autoref{sec:tocbasic.tocstyle}, +\autopageref{sec:tocbasic.tocstyle}. \begin{Example} - Because of incomprehensible reasons, the headings of - \DescRef{maincls.cmd.paragraph} shouldn't be run-in headings any longer but - headings similar to \DescRef{maincls.cmd.subsubsection}. The vertical skip - above the heading should be 10\,pt and the following text should be set - without any vertical distance. To do so, you can simply use: + For some unknown reason, you want to redefine the + \DescRef{maincls.cmd.paragraph} headings so that they are no longer run-in + headings but are similar to \DescRef{maincls.cmd.subsubsection}. The + vertical skip above the heading should be 10\Unit{pt} and no additional + vertical skip below the heading. To do so, you can use: \begin{lstcode} \RedeclareSectionCommand[% beforeskip=-10pt,% afterskip=1sp% ]{paragraph} \end{lstcode} - The negative value of \PValue{beforeskip} does not only result in a - positive vertical skip before the heading, but also deactivates the paragraph - indentation of the following text. Despite the specification of no vertical - skip after the heading a value of 1\,sp has been given to - \PValue{afterskip}. This is because \LaTeX{} here doesn't accept 0\,pt as - positive value. So 1\,sp is the lowest possible positive value. - - Generally, for the vertical adjustment it is better to have some - tolerance in the declaration of gaps\,---\,the so called \emph{glue}: + The negative value of \PValue{beforeskip} creates a positive vertical skip + before the heading and simultaneously disables the paragraph indentation of + the following text. Even though the specification did not want any vertical + skip after the heading, a value of 1\Unit{sp} has been given here. This is + because \LaTeX{} doesn't recognize 0\Unit{pt} as positive value. So + 1\Unit{sp} is the smallest possible positive value. + + Generally, it is better to have some tolerance for adjusting the vertical + spacing, the so-called \emph{glue}: \begin{lstcode} \RedeclareSectionCommand[% beforeskip=-10pt plus -2pt minus -1pt,% afterskip=1sp plus -1sp minus 1sp% ]{paragraph} \end{lstcode} - Doing so you have to know, that the glue also switches the algebraic sign - before becoming a skip, if the value is negative. That is the reason for the - negative glue values in the example. Additionally we used the occasion to - minimize the vertical skip after the heading using glue too. + Note that the glue also switches the algebraic sign before becoming a skip, + if the value is negative. That is the reason for the negative glue values in + the example. Additionally we used the occasion to minimize the vertical skip + after the heading using glue too. \end{Example} -In the example above only \PValue{beforeskip} and \PValue{afterskip} were -needed, because since v3.15 \KOMAScript{} defines -\DescRef{maincls.cmd.paragraph} itself using -\Macro{DeclareSectionCommand}. All other values are just reused with their -initial definition. Furthermore, the original definition of -\DescRef{maincls.cmd.paragraph} in \Class{scrartcl} reads: +In the example above, we only needed to define the keys \PValue{beforeskip} +and \PValue{afterskip} because since v3.15 \KOMAScript{} has defined +\DescRef{maincls.cmd.paragraph} internally using +\Macro{DeclareSectionCommand}, and therefore the other settings can be adopted +unchanged. The original definition of \DescRef{maincls.cmd.paragraph} in +\Class{scrartcl} reads: \begin{lstcode} \DeclareSectionCommand[% level=4, @@ -833,23 +797,24 @@ initial definition. Furthermore, the original definition of \end{lstcode} \Class{scrreprt} and \Class{scrbook} use slightly different values. -Some settings of \DescRef{maincls.cmd.chapter} depend on option -\DescRef{maincls.option.headings} (see \autoref{sec:maincls.structure}, +Some settings of \DescRef{maincls.cmd.chapter} depend on the +\DescRef{maincls.option.headings} option (see \autoref{sec:maincls.structure}, \DescPageRef{maincls.option.headings}). \hyperref[tab:maincls.chapter.skips]{Table~\ref*{tab:maincls.chapter.skips}} shows the default values of these settings. An overview of all settings is shown in \autoref{tab:maincls.section.defaults}. For more information\ChangedAt[2016/03]{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} about the default of the toc-entry styles see +\Class{scrartcl}} about the default of the TOC-entry styles see \autoref{sec:tocbasic.tocstyle}\important{\Package{tocbasic}}, -\autopageref{sec:tocbasic.tocstyle}. Please note, that \PValue{1ex} and +\autopageref{sec:tocbasic.tocstyle}. Note that \PValue{1ex} and \Length{baselineskip} depend on the default font size of the heading or the table of contents entry.% -% + \begin{table} \centering - \caption{Defaults of the chapter headings of \Class{scrbook} - and \Class{scrreprt} subject to option \DescRef{maincls.option.headings}} + \caption{Defaults for the chapter headings of \Class{scrbook} + and \Class{scrreprt} depending on the \DescRef{maincls.option.headings} + option} \label{tab:maincls.chapter.skips} \begin{tabular}{ll} \multicolumn{2}{@{}l}{\bfseries @@ -894,12 +859,12 @@ table of contents entry.% %begin{table} % \centering \begin{longtable}{@{}p{\columnwidth}@{}} - \caption{Default of the headings of \Class{scrbook} and + \caption{Defaults for the headings of \Class{scrbook} and \Class{scrreprt}}% \label{tab:maincls.section.defaults}\\ \endfirsthead - \caption[]{Default of the headings of \Class{scrbook} and - \Class{scrreprt} \emph{(Continuation)}}\\ + \caption[]{Default for the headings of \Class{scrbook} and + \Class{scrreprt} \emph{(continued)}}\\ \addlinespace[-\normalbaselineskip] \endhead \raggedleft\dots\\ @@ -938,7 +903,7 @@ table of contents entry.% \PValue{font} & see element \DescRef{maincls.fontelement.chapter}, \autoref{tab:maincls.structureElementsFont}, \autopageref{tab:maincls.structureElementsFont} \\ - \PValue{innerskip} & \PValue{0pt} \\ + \PValue{innerskip} & \PValue{0.5\Length{baselineskip}} \\ \PValue{level} & 0 \\ \PValue{prefixfont} & see element \DescRef{maincls.fontelement.chapterprefix}, @@ -1050,7 +1015,10 @@ table of contents entry.% \end{tabularx} \end{longtable} %end{table} -% +Incidentally, the internal macro \Macro{scr@parindent} used in the settings +for \DescRef{maincls.cmd.subparagraph} is the paragraph indent set by the +\DescRef{maincls.option.parskip} option or the +\DescRef{maincls-experts.cmd.setparsizes} command. \EndIndexGroup @@ -1064,98 +1032,111 @@ table of contents entry.% \Macro{ProvideSectionCommands}\OParameter{attributes} \Parameter{list of names} \end{Declaration} -With\ChangedAt[2014/11]{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} these commands you can either define or change several -section-like commands at once. The names of the section-like commands are -given by the comma-separated \PName{list of names}. - -There are two more differences to the previously described commands that only -define or change a single section-like command. Firstly, in case of error\,---\,if \Macro{DeclareNewSectionCommands} is used for an already defined \TeX{} -command sequence or if \Macro{RedeclareSectionCommands} is used for an -undefined \TeX{} command sequence\,---\,the definition will be done in spite -of raising an error message. - -Secondly, there is one more attribute \PValue{increaselevel} with an optional -integer argument. This attribute changes the meaning of the attributes -\PValue{level} and \PValue{toclevel} (see -\autoref{tab:maincls-experts.declaresection.keys}) so their values become -start values for the first section-like command of the \PName{list of - names}. From section-like command to section-like command of the \PName{list - of names} the value of \PValue{level} and \PValue{toclevel} -will be increased by the value of \PValue{increaselevel}. If attribute -\PValue{increaselevel} is used without an assignment the increase value is 1. +These\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} commands can define or change a whole series of +sectioning commands at once. The names of the sectioning commands are given by +the comma-separated \PName{list of names}. + +These commands differ in two other ways from the previously described commands +that only define or change a single sectioning command. First, in case of +error\,---\,that is if a command already exists with +\Macro{DeclareNewSectionCommands} or is undefined with +\Macro{RedeclareSectionCommands}\,---\,the definition will be performed +regardless. An appropriate an error message will, of course, be reported +anyway. + +Second, there is another attribute, +\important{\PValue{increaselevel}}\OptionVName{increaselevel}{integer}. This +attribute changes the meaning of the attributes \PValue{level} and +\PValue{toclevel} (see \autoref{tab:maincls-experts.declaresection.keys}) so +that their values become starting values for the first sectioning command of +the \PName{list of names}. For all other sectioning command in the \PName{list +of names}, the values of \PValue{level} and \PValue{toclevel} are successively +increased by the value of \PValue{increaselevel}. If the +\PValue{increaselevel} attribute is used without assigning a value, 1 is +assumed. % \EndIndexGroup \begin{Declaration} - \Macro{chapterheadstartvskip}% - \Macro{chapterheadmidvskip}% - \Macro{chapterheadendvskip}% - \Macro{partheadstartvskip}% - \Macro{partheadmidvskip}% - \Macro{partheadendvskip}% + \Macro{chapterheadstartvskip} + \Macro{chapterheadmidvskip} + \Macro{chapterheadendvskip} + \Macro{partheadstartvskip} + \Macro{partheadmidvskip} + \Macro{partheadendvskip} \Macro{partheademptypage} \end{Declaration} These\important[i]{\DescRef{maincls.cmd.chapter}\\ \DescRef{maincls.cmd.part}\\ \DescRef{maincls.cmd.addchap}\\ - \DescRef{maincls.cmd.addpart}} commands are used inside of the definition of the headings -\DescRef{maincls.cmd.chapter}\IndexCmd{chapter}, \DescRef{maincls.cmd.part}, \DescRef{maincls.cmd.addchap}, -\DescRef{maincls.cmd.addpart} and their star-variations. Thereby -\Macro{chapterheadstartvskip} is designed to be a command, that inserts a -vertical distance before the chapter heading. Analogues -\Macro{chapterheadendvskip} is designed to be a command, that inserts a vertical -distance after the chapter heading. If\ChangedAt{v3.15}{\Class{scrbook}\and + \DescRef{maincls.cmd.addpart}\\ + \DescRef{maincls.cmd.chapter*}\\ + \DescRef{maincls.cmd.part*}\\ + \DescRef{maincls.cmd.addchap*}\\ + \DescRef{maincls.cmd.addpart*}} commands are used inside the headings of the +previously described \PValue{chapter} and \PValue{part} styles and thus for +the definitions of \DescRef{maincls.cmd.chapter}\IndexCmd{chapter}, +\DescRef{maincls.cmd.part}\IndexCmd{part}, +\DescRef{maincls.cmd.addchap}\IndexCmd{addchap}, and +\DescRef{maincls.cmd.addpart}\IndexCmd{addpart}, as well as their starred +variants \DescRef{maincls.cmd.chapter*}\IndexCmd{chapter*}, +\DescRef{maincls.cmd.part*}\IndexCmd{part*}, +\DescRef{maincls.cmd.addchap*}\IndexCmd{addchap*}, and +\DescRef{maincls.cmd.addpart*}\IndexCmd{addpart*}. +The \Macro{chapterheadstartvskip} command is intended to insert a +vertical skip before the chapter heading. Similarly, +\Macro{chapterheadendvskip} is a command intended to insert a vertical +skip after the chapter heading. If\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}} the chapter heading has a prefix number line (see option \DescRef{maincls.option.chapterprefix} in \autoref{sec:maincls.structure}, \DescPageRef{maincls.option.chapterprefix}), \Macro{chapterheadmidvskip} -will be used between the number line and the heading text. +is also used between the number line and the heading text. -Vertical distance above and below part headings will be inserted using the -commands \Macro{partheadstartvskip} and \Macro{partheadendvskip}. A page break -would be interpreted to be part of the vertical distance and therefore is -already part of the default of \Macro{partheadendvskip} in +The \Macro{partheadstartvskip} and \Macro{partheadendvskip} commands insert +vertical skips above and below part headings. A page break is interpreted as +part of the vertical distance. Such a page break is part of the default +definitions of \Macro{partheadendvskip} in \Class{scrbook}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} and -\Class{scrreprt}. Command +\Class{scrreprt}. The \Macro{partheademptypage}\ChangedAt{v3.02}{\Class{scrbook}\and - \Class{scrreprt}} is used to produce the empty page after the part heading -page of \Class{scrbook} and \Class{scrreprt}. +\Class{scrreprt}} command produces an empty page after the part heading page +of \Class{scrbook} and \Class{scrreprt}. -Since \KOMAScript~3.15\ChangedAt{v3.15}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} the defaults of these seven commands -are independent from option \DescRef{maincls.option.headings} (see +Starting with \KOMAScript~3.15\ChangedAt{v3.15}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}}, the defaults of these seven commands +are independent from the \DescRef{maincls.option.headings} option (see \autoref{sec:maincls.structure}, -\DescPageRef{maincls.option.headings}). The original definitions of the -chapter heading reads since -\KOMAScript~3.157\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}}:\IndexLength{@tempskipa} +\DescPageRef{maincls.option.headings}). The default definitions for the +chapter headings starting with +\KOMAScript~3.17\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} correspond to:\IndexLength{@tempskipa} \begin{lstcode} \newcommand*{\chapterheadstartvskip}{\vspace{\@tempskipa}} \newcommand*{\chapterheadmidvskip}{\par\nobreak\vskip\@tempskipa} \newcommand*{\chapterheadendvskip}{\vskip\@tempskipa} \end{lstcode} -Every usage of \OptionValueRef{maincls}{headings}{big}\IndexOption{headings}, +These defaults are reactivated every time you use +\OptionValueRef{maincls}{headings}{big}\IndexOption{headings}, \OptionValueRef{maincls}{headings}{normal}, or -\OptionValueRef{maincls}{headings}{small} reactivates these default -definitions. - -Command \DescRef{maincls.cmd.chapter} automatically sets the internal length -\Length{@tempskipa} to the value of the -\DescRef{\LabelBase.cmd.DeclareSectionCommand}\IndexCmd{DeclareSectionCommand} attribute -\PValue{beforeskip} before calling -\Macro{chapterheadstartvskip}. Correspondingly it sets the length to the value -of attribute \PValue{afterskip} before calling \Macro{chapterheadendvskip} and -\PValue{innerskip} before calling \Macro{chapterheadmidvskip}. If you redefine -\Macro{chapterheadstartvskip}, \Macro{chapterheadmidvskip}, or -\Macro{chapterheadendvskip} you should also correspond the new definition to -\Length{@tempskipa} to respect the values of \DescRef{\LabelBase.cmd.DeclareSectionCommand}. - -The default values of the distances of \DescRef{maincls.cmd.part} do not depend on option -\DescRef{maincls.option.headings}. So the corresponding commands will not be redefined using -the options. The\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} original definitions of these commands of \Class{scrbook} -and \Class{scrreprt} read: +\OptionValueRef{maincls}{headings}{small}. As a side effect, these options may +affect not only chapter titles but all headings in the \PValue{chapter} style + +The \PValue{chapter} style automatically sets the internal length +\Length{@tempskipa} to the value that results from the +\DescRef{\LabelBase.cmd.DeclareSectionCommand}\IndexCmd{DeclareSectionCommand} +attribute \PValue{beforeskip} before calling \Macro{chapterheadstartvskip}. +Similarly, it sets this length to the value of the \PValue{afterskip} +attribute before calling \Macro{chapterheadendvskip}, and to +\PValue{innerskip} before calling \Macro{chapterheadmidvskip}. + +The default values of the distances of \DescRef{maincls.cmd.part} do not +depend on the \DescRef{maincls.option.headings} option. So the corresponding +commands will not be redefined by this option. +Their\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and +\Class{scrartcl}} default definitions in \Class{scrbook} and \Class{scrreprt} +correspond to: \begin{lstcode} \newcommand*{\partheadstartvskip}{% \null\vskip-\baselineskip\vskip\@tempskipa @@ -1180,24 +1161,113 @@ and of \Class{scrartcl}: \vskip\@tempskipa } \end{lstcode} -Again \DescRef{maincls.cmd.part} sets -\Length{@tempskipa}\IndexLength{@tempskipa} to the values of +The \PValue{part} style once again sets the internal length +\Length{@tempskipa}\IndexLength{@tempskipa} according to the settings of \DescRef{\LabelBase.cmd.DeclareSectionCommand}\IndexCmd{DeclareSectionCommand} -before the internal usage of the command. - -It\ChangedAt[2015/03]{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} is not recommended to redefine the command for the -distances above or below the headings only for changing these distances, -because you can reconfigure these distances much easier using -\DescRef{\LabelBase.cmd.RedeclareSectionCommand}. Redefinition of the commands -should be reserved to more complex changes. An\textnote{Example!} example -that redefines \Macro{chapterheadstartvskip} and \Macro{chapterheadendvskip} -to print extra rules above and below the chapter heading may be found at -\cite{homepage} (in German).% +before using the commands. + +If you redefine one of the commands used for the vertical skip in the original +\Length{@tempskipa} but still want to be able to configure the lengths, for +example with \DescRef{\LabelBase.cmd.RedeclareSectionCommand}, you should also +use \Length{@tempskipa} in the new definition. +Since\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} you can more easily configure the distances above, within, +and below the headings using \DescRef{\LabelBase.cmd.RedeclareSectionCommand}, +you generally should not redefine the commands described here. Changing them +should be reserved for more complex changes that cannot be accomplished with +\DescRef{\LabelBase.cmd.RedeclareSectionCommand}. An\textnote{Example!} +example that redefines \Macro{chapterheadstartvskip} and +\Macro{chapterheadendvskip} to print extra rules above and below the chapter +heading can be found at \cite{homepage} (in German).% % \EndIndexGroup +\begin{Declaration} + \Macro{partlineswithprefixformat}% + \Parameter{level}\Parameter{number}\Parameter{text}% +\end{Declaration} +This\ChangedAt{v3.25}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} command is used by headings with the \PValue{part} style to +output the heading number and heading text. The \PName{number} and +\PName{text} arguments are already formatted, including the font +selections. Ultimately, this command controls the arrangement of the two parts +of the heading. For unnumbered headings, \PName{number} is a completely empty +argument, so it does not contain any formatting commands. + +The default definition is rather Spartan: +\begin{lstcode} + \newcommand{\partlineswithprefixformat}[3]{% + #2#3% + } +\end{lstcode} + +\begin{Example} + You want to have part headings in a light blue box with blue frame. The + box should occupy only about three quarters of full width of the text + area. So you try: +\begin{lstcode} + \documentclass{scrbook} + \usepackage{xcolor} + \renewcommand*{\partlineswithprefixformat}[3]{% + \fcolorbox{blue}{blue!25}{% + \parbox{.75\linewidth}{#2#3}% + }% + } + \begin{document} + \part{Framed Part} + \end{document} +\end{lstcode} + But surprisingly the heading is not longer centred\,---\,neither the box + itself nor the text inside the box. + + The reason for the missing centring of the box is that the end of the + paragraph is hidden in the third argument of the command. So it still + finishes the paragraph of the text inside the box but not the paragraph of + the \Macro{parbox} itself. To solve this you add a \Macro{par} at the end of + the definition. + + The reason for the missing centring inside the box is that the alignment of + \DescRef{maincls.cmd.raggedpart} is valid outside the box but not + automatically inside a \Macro{parbox}. To solve this you add + \Macro{raggedpart} inside the box. + + With +\begin{lstcode} + \documentclass{scrbook} + \usepackage{xcolor} + \renewcommand*{\partlineswithprefixformat}[3]{% + \fcolorbox{blue}{blue!25}{% + \parbox{.75\linewidth}{\raggedpart #2#3}% + }% + } + \par + \begin{document} + \part{Framed Part} + \end{document} +\end{lstcode} + you get the expected result. +\end{Example} + +As the example shows, users who redefine this command must watch out for +several side effects. In addition to preserving the text alignment, they also +must prevent page breaks within the headings, for example if they insert extra +paragraphs or space. The example above does not have this problem. Not only +does the box prevent a page breaks anyway, but \KOMAScript{} itself also +changes \Macro{interlinepenalty} as part of \PName{text} so to prevent page +breaks there. It also finishes \PName{text} with an internal paragraph break +using \Macro{@@par}. + +The default definition of \Macro{partlineswithprefixformat} does not use the +first argument, \PName{level}, nor is it needed in the example above. It is of +interest only if you want to define several commands with the \PValue{part} +style and need to distinguish the different levels. The predefined commands +\DescRef{maincls.cmd.part}, \DescRef{maincls.cmd.part*}, +\DescRef{maincls.cmd.addpart}, and \DescRef{maincls.cmd.addpart*} all share +the same \PName{level} \PName{part}.% +\EndIndexGroup + + \begin{Declaration} \Macro{chapterlineswithprefixformat}% \Parameter{level}\Parameter{number}\Parameter{text}% @@ -1205,20 +1275,21 @@ to print extra rules above and below the chapter heading may be found at \Parameter{level}\Parameter{number}\Parameter{text} \end{Declaration} These\ChangedAt{v3.19}{\Class{scrbook}\and \Class{scrreprt}} commands are used -by headings with style \PValue{chapter} to output the heading number and -heading text depending on option +by headings with the \PValue{chapter} style to output the heading number and +heading text, depending on the \DescRef{maincls.option.chapterprefix}\IndexOption{chapterprefix}% -\textnote{\DescRef{maincls.option.chapterprefix}} (see \autoref{sec:maincls.structure}, -\DescPageRef{maincls.option.chapterprefix}). If the option is -\PValue{true} \Macro{chapterlineswithprefixformat} is used, otherwise -\Macro{chapterlinesformat}. +\textnote{\DescRef{maincls.option.chapterprefix}} option (see +\autoref{sec:maincls.structure}, +\DescPageRef{maincls.option.chapterprefix}). If the option is \PValue{true}, +\Macro{chapterlineswithprefixformat} is used. Otherwise +\Macro{chapterlinesformat} determines the ouput. -The arguments \PName{number} and \PName{text} are already formatted, i.\,e., -they contain font selections. At least the order and layout of both has to be -done with these commands. If a heading has no number argument \PName{number} -will be completely empty also without any format or font commands. +The \PName{number} and \PName{text} arguments are already formatted, including +the font selections. Ultimately, these commands thus control the arrangement +of the two parts of the heading. For unnumbered headings, the \PName{number} +argument is completely empty, so it does not contain any formatting commands. -The default definitions are very simple: +The\textnote{default} defaults for these commands are: \begin{lstcode} \newcommand{\chapterlinesformat}[3]{% \@hangfrom{#2}{#3}% @@ -1230,7 +1301,8 @@ The default definitions are very simple: \begin{Example} You want to have chapter headings with yellow background. For the headings - without prefix line you use the follow definition in the document preamble: + without a prefix line, you use the following definition in the document + preamble: \begin{lstcode} \makeatletter \renewcommand{\chapterlinesformat}[3]{% @@ -1242,7 +1314,7 @@ The default definitions are very simple: } \makeatother \end{lstcode} - For chapter headings without prefix line you use: + For chapter headings with prefix line, you use: \begin{lstcode} \renewcommand{\chapterlineswithprefixformat}[3]{% \colorbox{yellow}{% @@ -1252,9 +1324,9 @@ The default definitions are very simple: }% } \end{lstcode} - Unfortunately you will find, that these re-definitions result in justified + Unfortunately, you discover that these redefinitions result in justified text for the headings. The reason is the \Macro{parbox} command. To change - this, you can use \DescRef{maincls.cmd.raggedchapter} (see + this, you can use the \DescRef{maincls.cmd.raggedchapter} command (see \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.raggedchapter}) inside the argument of \Macro{parbox}. Otherwise \Macro{raggedchapter} would be used only before \Macro{chapterlineswithprefixformat} and @@ -1279,32 +1351,32 @@ The default definitions are very simple: }% } \end{lstcode} - Remember to use \Macro{makeatletter} and \Macro{makeatother} only at the - document preamble. Do not use it inside your own wrapper-class or - package. It is only needed because of \Macro{@hangfrom} in the definition of + Remember to use \Macro{makeatletter} and \Macro{makeatother} only in the + document preamble. Do not use it inside your own wrapper class or package. + They are only needed here because of \Macro{@hangfrom} in the definition of \Macro{chapterlinesformat}. \end{Example} -As the example shows, users, who change the definition of one of the commands, -should take care of several side effects. The alignment of the text is only -one thing. They also have to prevent page breaks in the headings, e.\,g., if -they add extra space into the output. The example above does not have page -break problems. Not only the boxes prevent page breaks. \KOMAScript{} itself -also changes \Macro{interlinepenalty} as part of \PName{text} to prevent page -breaks. It also finishes \PName{text} with an internal paragraph break using -\Macro{@par}. - -Command \DescRef{maincls.cmd.raggedchapter} is not part of \PName{text} but -executed before \Macro{chapterlineswithprefixformat} or -\Macro{chapterlinesformat}. This makes it much easier to use, e.\,g., -\Macro{MakeUppercase} at a re-definition. Please note, typographers use -individual letter spacing at majuscule text, but \LaTeX{} command -\Macro{MakeUppercase} does not. - -The first argument, \PName{level}, is not used by the default definition and -also not needed in the example above. It is of interest only, if a user would -define several commands with \PValue{chapter} style and need to distinguish -the different levels. The predefined commands \DescRef{maincls.cmd.chapter}, +As the example shows, users who redefine this command must watch out for +several side effects. In addition to preserving the text alignment, they also +must prevent page breaks within the headings, for example if they insert extra +paragraphs or space. The example above does not have this problem. Not only +does the box prevent a page breaks anyway, but \KOMAScript{} itself also +changes \Macro{interlinepenalty} as part of \PName{text} so to prevent page +breaks there. It also finishes \PName{text} with an internal paragraph break +using \Macro{@@par}. + +Incidentally, the \DescRef{maincls.cmd.raggedchapter} command is not part of +\PName{text}, as otherwise using \Macro{MakeUppercase} inside redefined +versions of these two commands would be much more difficult. Note, however, +that typographic rules require individual adjustments of letter spacing in +capitalised text. However the \LaTeX{} \Macro{MakeUppercase} command does not +do this. + +The default definitions do not use the first argument, \PName{level}, nor is +it needed in the example above. It is of interest only if you want to define +several commands with the \PValue{chapter} style and need to distinguish the +different levels. The predefined commands \DescRef{maincls.cmd.chapter}, \DescRef{maincls.cmd.chapter*}, \DescRef{maincls.cmd.addchap}, and \DescRef{maincls.cmd.addchap*} all share the same \PName{level} \PName{chapter}.% @@ -1318,20 +1390,19 @@ the different levels. The predefined commands \DescRef{maincls.cmd.chapter}, \Parameter{level}\Parameter{indent}\Parameter{number}\Parameter{text}% \end{Declaration} These\ChangedAt{v3.19}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} commands are used by headings with style \PValue{section} -to output the heading number and heading text. If the heading is printed as -catch phrase at the very beginning of the following paragraph text -\Macro{sectioncatchphraseformat} is used, otherwise -\Macro{sectionlinesformat}. +\Class{scrartcl}} commands are used by headings with the \PValue{section} +style depending on whether the reading is run-in or on its own line. +Free-standing headings use \Macro{sectionlinesformat} for their output, while +run-in headings use \Macro{sectioncatchphraseformat}. In both cases \PName{indent} is the value of the horizontal indention of the -heading relative to the text area. If the value is negative the heading should -even move into the left margin. +heading relative to the text area. If the value is negative, the heading can +protrude into the left margin. -The arguments \PName{number} and \PName{text} are already formatted, i.\,e., -they contain font selections. At least the order and layout of both has to be -done with these commands. If a heading has no number argument \PName{number} -will be completely empty also without any format or font commands. +The arguments \PName{number} and \PName{text} are already formatted, including +the font settings. Ultimately, these commands thus control the arrangement of +the two parts of the heading. For unnumbered headings, the \PName{number} +argument is completely empty, so it does not contain any formatting commands. The default definitions are: \begin{lstcode} @@ -1343,14 +1414,14 @@ The default definitions are: } \end{lstcode} -If the user re-defines one of these commands, he has to take care to prevent -page breaks inside the printing of the heading. \KOMAScript{} itself only -changes \Macro{interlinepenalty} to impede page breaks. +If you redefine one of these commands, you are responsible for preventing page +breaks inside heading. \KOMAScript{} itself only changes +\Macro{interlinepenalty} to impede page breaks. \begin{Example} - Like chapter headings in the previous example, headings of \PName{level} - \PValue{section} should be printed with a background colour. The lower - levels should be affected: + As in the previous example with chapter headings, the free-standing headings + of the \PValue{section} \PName{level} should now be printed with a + background colour. Headings of lower levels should not be changed: \begin{lstcode} \makeatletter \renewcommand{\sectionlinesformat}[4]{% @@ -1369,15 +1440,16 @@ changes \Macro{interlinepenalty} to impede page breaks. } \makeatother \end{lstcode} - With this code the indention part of indented headings would not be - coloured, but with negative indention the background of the margin part of - the headings will also become yellow. You can move the \Macro{hspace*} - command into the \Macro{colorbox} to change this. - - Again remember to use \Macro{makeatletter} and \Macro{makeatother} only at the - document preamble. Do not use it inside your own wrapper-class or - package. It is only needed because of \Macro{@hangfrom} in the definition of - \Macro{sectionlinesformat}. + With this code, area of the indention is not coloured if the heading is + indented. If, however, the heading is placed in the left margin with + negative indention, this area of the margin is also highlighted. You can + move the \Macro{hspace*} command into the \Macro{colorbox} to change this + behaviour. + + Again, remember to use \Macro{makeatletter} and \Macro{makeatother} only in + the document preamble. You should omit them inside your own wrapper class or + package. They are only needed because of \Macro{@hangfrom} in the definition + of \Macro{sectionlinesformat}. \end{Example} The first argument, \PName{level}, is not used by the default definition. The @@ -1403,52 +1475,56 @@ same style \PValue{section}.% \Macro{Before@sect}\Parameter{code} \end{Declaration} As\ChangedAt[2014/09]{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} already explained in \autoref{sec:maincls.structure} in -the description of the sectioning commands beginning with -\DescPageRef{maincls.cmd.chapter}, \KOMAScript{} provides additional -features for the optional argument of those commands. Therefore, it was -necessary to replace some \LaTeX{} kernel commands, especially +\Class{scrartcl}} already explained in \autoref{sec:maincls.structure} in the +description of the sectioning commands beginning with +\DescPageRef{maincls.cmd.chapter}, \KOMAScript{} provides additional features +for the optional argument of those commands. To achieve this, it was necessary +to replace some \LaTeX{} kernel commands, especially \Macro{secdef}\IndexCmd{secdef}\important{\Macro{secdef}} and \Macro{@startsection}\IndexCmd{@startsection}% \important{\Macro{@startsection}}. The meaning of the parameters of these commands can be found in the \LaTeX{} kernel manual \cite{latex:source2e}. -Unfortunately these commands are often redefined by other packages in a way -that collides with the functionality of \KOMAScript. So \KOMAScript{} not only -changes the definition of these commands but also defines the additional, +However, these commands are often completely redefined by other packages in a +way that clashes with the functionality of \KOMAScript. So \KOMAScript{} not +only changes the definition of these commands but also defines the additional, alternative commands \Macro{SecDef} and \Macro{scr@startsection}. Package -authors are permitted to use these commands like they would use the -corresponding \LaTeX{} kernel commands and therefore participate in the -additional features of \KOMAScript. Nevertheless these commands should not be -redefined, because they could be changed in future and so the redefinition would -impair \KOMAScript{} again. - -\KOMAScript{} internally uses \Macro{SecDef} and \Macro{scr@startsection} -instead of \Macro{secdef} and \Macro{@startsection}, e.\,g., defining -section-like commands by \DescRef{\LabelBase.cmd.DeclareSectionCommand}. So -later redefinition of \Macro{secdef} or \Macro{@startsection} will not -influence the sectioning commands of \KOMAScript. - -As an alternative to the redefinition of such commands, \KOMAScript{} provides -the execution of additional \PName{code} at several states of the -\KOMAScript{} replacements. The \PName{code} of each usage of -\Macro{At@startsection}, \Macro{Before@sect}, or \Macro{Before@ssect} will be -cumulated independently. Later removing of added \PName{code} is not -provided. - -The \PName{code} of \Macro{At@startsection} is executed immediately after -the evaluation of \PName{beforeskip} and calculation of the resulting -\Length{@tempskipa}, before adding the vertical gap itself. So you still may -change the value of \Length{@tempskipa}. - -The \PName{code} of \Macro{Before@sect} and -\Macro{Before@ssect} is executed just before \Macro{@sect} -and \Macro{@ssect} inside \Macro{scr@startsection}, respectively. At this state -the vertical gap of \Length{@tempskipa} has already been added using -\Macro{addvspace}. - -The commands \Macro{At@startsection}, \Macro{Before@sect}, and -\Macro{Before@ssect} are suggested for package authors.% +authors can use these commands as they would use the corresponding \LaTeX{} +kernel commands and therefore gain access to the additional features of +\KOMAScript. However, these commands should not be redefined, as they may +changed at any time, and then this redefinition could compromise +\KOMAScript{}'s functionality. + +\KOMAScript{} itself uses \Macro{SecDef} and \Macro{scr@startsection} instead +of \Macro{secdef} and \Macro{@startsection}, for example to define sectioning +commands with \DescRef{\LabelBase.cmd.DeclareSectionCommand}. So later +redefinitions of \Macro{secdef} or \Macro{@startsection} will not influence +the sectioning commands of \KOMAScript. + +As an alternative to redefining such commands, \KOMAScript{} offers the +possibility to add additional \PName{code} at several points in +\KOMAScript{}'s own replacements. The \PName{code} of all calls to +\Macro{At@startsection}\important{\Macro{At@startsection}\\ + \Macro{Before@sect}\\ + \Macro{Before@sect}}, \Macro{Before@sect} and \Macro{Before@sect} is +collected separately for each command. There is no provision for removing +\PName{code} once it has been inserted. + +The \PName{code} of the \Macro{At@startsection}% + \important{\Macro{At@startsection}\\ + \Macro{scr@startsection}} macro is used in the \Macro{scr@startsection} +command immediately after evaluating \PName{beforeskip} and calculating the +resulting \Length{@tempskipa} but before adding the vertical skip itself. So +you can still change the value of \Length{@tempskipa}. + +The \PName{code} of \Macro{Before@sect} or \Macro{Before@ssect} is executed +within \Macro{scr@startsection} just before calling \Macro{@sect} or +\Macro{@ssect}, respectively. At this point, the vertical skip of +\Length{@tempskipa} has already been added using \Macro{addvspace}. + +These three commands, \Macro{At@startsection}, \Macro{Before@sect}, and +\Macro{Before@ssect}, are designed as an interface for package authors and +released for them to use.% % \EndIndexGroup @@ -1459,30 +1535,32 @@ The commands \Macro{At@startsection}, \Macro{Before@sect}, and \begin{Declaration} \Macro{appendixmore} \end{Declaration}% -There is a peculiarity within the \DescRef{maincls.cmd.appendix} command in -the {\KOMAScript} classes. If the command \Macro{appendixmore} is defined, -this command is executed also by the \DescRef{maincls.cmd.appendix} -command. Internally the {\KOMAScript} classes +The \KOMAScript{} classes have an unusual feature within the +\DescRef{maincls.cmd.appendix} command. If the \Macro{appendixmore} command +is defined, \DescRef{maincls.cmd.appendix} will also execute this +it. Internally, the \KOMAScript{} classes \Class{scrbook}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} and -\Class{scrreprt} take advantage of this behaviour to implement the options -\DescRef{maincls.option.appendixprefix} (see \autoref{sec:maincls.structure}, -\DescPageRef{maincls.option.appendixprefix}). You\textnote{Attention!} should -take note of this in case you decide to define or redefine the macro -\Macro{appendixmore}. In case one of this option has been used, you will -receive an error message when using -\verb|\newcommand{\appendixmore}{|\dots\verb|}|. This behaviour is intended to -prevent you from disabling options without noticing it. +\Class{scrreprt} take advantage of this behaviour to implement the +\DescRef{maincls.option.appendixprefix} layout option (see +\autoref{sec:maincls.structure}, +\DescPageRef{maincls.option.appendixprefix}). You\textnote{Attention!} should +take note of this in case you decide to define or redefine the +\Macro{appendixmore} macro. If this option has been used, you will receive an +error message when using \verb|\newcommand{\appendixmore}{|\dots\verb|}|. This +behaviour is intended to prevent you from overriding the options without +realising it. \begin{Example} You do not want the chapters in the main part of the classes \Class{scrbook} - or \Class{scrreprt} to be introduced by a prefix line (see layout options - \DescRef{maincls.option.chapterprefix} in \autoref{sec:maincls.structure}, - \DescPageRef{maincls.option.chapterprefix}). For consistency you also - do not want such a line in the appendix either. Instead, you would like to - see the word ``Chapter'' in the language of your choice written in front of - the chapter letter and, simultaneously, in the page headings. Instead of - using layout option \DescRef{maincls.option.appendixprefix}, you would define in the - document preamble: + or \Class{scrreprt} to be introduced by a prefix line (see the + \DescRef{maincls.option.chapterprefix} layout option in + \autoref{sec:maincls.structure}, + \DescPageRef{maincls.option.chapterprefix}). For consistency, you also do + not want such a line in the appendix either. Instead, you would like to see + the word ``Chapter'' in the language of your choice written in front of the + chapter letter and, simultaneously, in the page headings. Instead of using + the \DescRef{maincls.option.appendixprefix} layout option, you define the + following in the document preamble: % \begin{lstcode} \newcommand*{\appendixmore}{% @@ -1499,8 +1577,8 @@ prevent you from disabling options without noticing it. This behaviour prevents the definition made above from invisibly changing the settings intended with the option. - It is also possible to get a similar behaviour of the appendix for - the class \Class{scrartcl}. You can write in the preamble of your + It is also possible to get a similar behaviour for the appendix of the class + \Class{scrartcl}. For example, you can write in the preamble of your document: \begin{lstcode}[moretexcs={ifthenelse,equal}] \newcommand*{\appendixmore}{% @@ -1510,7 +1588,7 @@ prevent you from disabling options without noticing it. \appendixname~\thesection\autodot\enskip}} \end{lstcode} - Redefined commands are explained in more detail in + The redefined commands are explained in more detail in \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.chapterformat} and \DescPageRef{maincls.cmd.chaptermarkformat}. @@ -1524,91 +1602,93 @@ prevent you from disabling options without noticing it. \begin{Declaration} \Macro{newbibstyle}\OParameter{parent style}\Parameter{name}%^^A - \Parameter{instructions}% + \Parameter{commands}% \Macro{newblock}% \Macro{@openbib@code}% \Macro{bib@beginhook}% \Macro{bib@endhook} \end{Declaration} -The standard classes\textnote{standard classes} already provide command -\Macro{newblock} for structuring of bibliography entries. The exact purpose of -this command depends on the class options. Using option -\Option{openbib}\important{\Option{openbib}} redefine commands -\Macro{@openbib@code} and \Macro{newblock} at the end of the used standard -class. These classes execute command \Macro{@openbib@code} at the -begin\,---\,or more precise: at the specification of the parameters of -the\,---\,list environment, that will be used for the bibliography. It should -be assumed, that many packages will execute this command in the same kind, if -they redefine the bibliography. - -The \KOMAScript{} classes do something similar. Nevertheless, they do not -redefine \Macro{@openbib@code} at the end of the class. Instead of, the -bibliography style \PValue{openstyle} is defined using -\Macro{newbibstyle}. The \PName{instructions}, that has been defined as part -of the implementation, contain the appropriate redefinition of -\Macro{@openbib@code} and \Macro{newblock}. Now, if this bibliography style -will be selected using option +The standard classes\textnote{standard classes} already provide the +\Macro{newblock} command to structure bibliography entries. The exact purpose +of this command depends on the class options. Using option +\Option{openbib}\important{\Option{openbib}} redefines the commands +\Macro{@openbib@code} and \Macro{newblock} itself at the end of the standard +class. The standard classes execute the \Macro{@openbib@code} command when +starting the bibliography list, or more precisely, when defining the +parameters for the list. You can assume that many packages which redefine the +bibliography will execute this command. + +The \KOMAScript{} classes\textnote{\KOMAScript} do something similar. However, +they do not redefine \Macro{@openbib@code} at the end of the class. Instead, +\Macro{newbibstyle} defines the \PValue{openstyle} bibliography style. The +\PName{commands} given in the implementation contain the appropriate +redefinition of \Macro{@openbib@code} and \Macro{newblock}. If you select this +bibliography style using the \OptionValueRef{maincls}{bibliography}{openstyle}% \IndexOption{bibliography~=\PValue{openstyle}}% -\important{\OptionValueRef{maincls}{bibliography}{openstyle}}, then the -\PName{instructions} will be executed immediately. This will redefine +\important{\OptionValueRef{maincls}{bibliography}{openstyle}} option, the +\PName{commands} will be executed immediately. This will redefine \Macro{@openbib@code} and \Macro{newblock}. -Beside \Macro{@openbib@code} and \Macro{newblock} also \Macro{bib@beginhook} -and \Macro{bib@endhook} may be redefined by the \PName{instructions} of the -style. Command \Macro{bib@beginhook} will be executed immediately after -heading and preamble of the bibliography, but before the begin of the list -with the bibliography entries. Command \Macro{bib@endhook} will be executed -immediately after this list at the end of the bibliography. If -\DescRef{maincls.cmd.BreakBibliography} (see +In addition to \Macro{@openbib@code} and \Macro{newblock}, +\Macro{bib@beginhook} and \Macro{bib@endhook} can also be redefined by the +\PName{commands} of the style. The \Macro{bib@beginhook} command is executed +immediately after the heading and preamble of the bibliography but before the +beginning of the list of bibliographic entries. The \Macro{bib@endhook} +command will be executed immediately after this list, at the end of the +bibliography. If \DescRef{maincls.cmd.BreakBibliography} (see \autoref{sec:maincls.bibliography}, -\DescPageRef{maincls.cmd.BreakBibliography}) intercepts the bibliography, -these commands will also executed at the begin and end of each part of the -bibliography, this would be immediately before and after +\DescPageRef{maincls.cmd.BreakBibliography}) is used to interrupt the +bibliography, these commands will also executed at the beginning and end of +each part of the bibliography, immediately before and after \DescRef{maincls.cmd.BreakBibliography}. -The commands \Macro{newblock}, \Macro{@openbib@code}, \Macro{bib@beginhook}, -and \Macro{bib@endhook} will be reset to an empty definition at the start of -each new bibliography style. After this the \PName{instructions} of the -\PName{parent style} of the bibliography style will be executed. After this -the \PName{instructions} of the bibliography style itself will be -executed. Because of this these commands has to be defined using -\Macro{renewcommand}\IndexCmd{renewcommand}\important{\Macro{renewcommand}} -not \Macro{newcommand} inside of argument \PName{instructions}. - -If the user declares additional \PName{instructions} using -\DescRef{maincls.cmd.AtEndBibliography}%\important[i]{\DescRef{maincls.cmd.AtEndBibliography}\\ -% \DescRef{maincls.cmd.AfterBibliographyPreamble}}% Passt bloeder Weise nicht! -\IndexCmd{AtEndBibliography} and -\DescRef{maincls.cmd.AfterBibliographyPreamble}\IndexCmd{AfterBibliographyPreamble} -to be executed after the preamble or at the end of the bibliography, the -\PName{instructions} of \DescRef{maincls.cmd.AfterBibliographyPreamble} will -be executed only once at the begin of the bibliography but after the -\Macro{bib@beginhook} \PName{instructions}, and the \PName{instructions} of +The \Macro{newblock}, \Macro{@openbib@code}, \Macro{bib@beginhook}, and +\Macro{bib@endhook} commands are initially defined to be empty when using a +new bibliography style. After this, the \PName{commands} of the \PName{parent +style} that was optionally specified when defining the style will be executed, +followed by the \PName{commands} for the bibliography style itself. As a +result, these commands must be defined, if necessary, with +\Macro{renewcommand}\IndexCmd{renewcommand}\important{\Macro{renewcommand}}, +not \Macro{newcommand}, inside the \PName{instructions} argument. + +If you use the +\DescRef{maincls.cmd.AtEndBibliography}\IndexCmd{AtEndBibliography} and +\DescRef{maincls.cmd.AfterBibliographyPreamble}% +\IndexCmd{AfterBibliographyPreamble} commands to declare additional +\PName{commands} to be executed after the preamble or at the end of the +bibliography, the \PName{commands} specified with +\DescRef{maincls.cmd.AfterBibliographyPreamble} will only be executed once, at +the beginning of the bibliography after the \Macro{bib@beginhook} +\PName{commands}, and the \PName{commands} of \DescRef{maincls.cmd.AtEndBibliography} will be executed only once at the end -of the bibliography but before \Macro{bib@endhook}. +of the bibliography, before \Macro{bib@endhook}. -Package\textnote{Example!} -\Package{multicol}\IndexPackage{multicol}\important{\Package{multicol}} (see -\cite{package:multicol}) could be used to define a bibliography style for -printing the bibliography with two columns: +For\textnote{Example!} example, the +\Package{multicol}\IndexPackage{multicol}\important{\Package{multicol}} +package (see \cite{package:multicol}) could be used to define a bibliography +style for printing the bibliography with two columns: % Umbruchkorrektur: listings korrigiert \begin{lstcode} \newbibstyle{twocolumstyle}{% \renewcommand*{\bib@beginhook}{\begin{multicols}{2}}% \renewcommand*{\bib@endhook}{\end{multicols}}}% \end{lstcode} -If also an \emph{open}-variation of this style should be defined, one may use -the provided heredity feature and specify a \PName{parent style}: +If you also want to define an open variation of this style, you can use +the possibilities of inheritance here and specify a \PName{parent style}: % Umbruchkorrektur: listings korrigiert \begin{lstcode} \newbibstyle{twocolumopenstyle}[openstyle]{% \renewcommand*{\bib@beginhook}{\begin{multicols}{2}}% \renewcommand*{\bib@endhook}{\end{multicols}}}% \end{lstcode} -These new defined styles may be selected using option -\DescRef{maincls.option.bibliography} as usual.% -% +You can then select these newly defined styles with the +\DescRef{maincls.option.bibliography} option as usual. + +Like\textnote{Achtung!} \DescRef{maincls.cmd.BreakBibliography}, these +commands lose all or part of their effect when \Environment{thebibliography} +is redefined, for example by using +\Package{biblatex}\IndexPackage{biblatex}\important{\Package{biblatex}}.% \EndIndexGroup diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle.tex index c9c2fb5f163..c362c2d42c4 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrbookreportarticle.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrbookreportarticle.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,88 +46,78 @@ % ============================================================================ \KOMAProvidesFile{scrbookreportarticle.tex} - [$Date: 2017-05-31 11:06:42 +0200 (Wed, 31 May 2017) $ + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (chapter: scrbook, scrreprt, scrartcl)] \translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm\and - Krickette Murabayashi\and Jana Schubert\and Jens H\"uhne} + Krickette Murabayashi\and Jana Schubert\and Jens H\"uhne\and Karl Hagen} -% Date of the translated German file: 2017-05-31 +% Date of the translated German file: 2018-02-01 \chapter{The Main Classes: \Class{scrbook}, \Class{scrreprt}, and - \Class{scrartcl}} -\labelbase{maincls} + \Class{scrartcl}} +\labelbase{maincls}% \BeginIndexGroup \BeginIndex{Class}{scrbook}% \BeginIndex{Class}{scrreprt}% \BeginIndex{Class}{scrartcl}% -%\AddSeeIndex{command}{gen}{\GuidecmdIndexShort}{cmd}% <-- set automatically -\AddSeeIndex{macro}{gen}{\GuidecmdIndexShort}{cmd}% \AddSeeIndex{instruction}{gen}{\GuidecmdIndexShort}{cmd}% - +\AddSeeIndex{macro}{gen}{\GuidecmdIndexShort}{cmd}% The main classes of the {\KOMAScript} bundle are designed as counterparts to the standard {\LaTeX} classes. This means that the {\KOMAScript} bundle -contains replacements for the three standard classes: +contains replacements for the three standard classes, \Class{book}\IndexClass{book}, \Class{report}\IndexClass{report}, and \Class{article}\IndexClass{article}. There is also a replacement for the -standard class \Class{letter}\IndexClass{letter}. The document class for -letters is described in a separate chapter, because it is fundamentally +standard \Class{letter}\IndexClass{letter} class. The document class for +letters is described in a separate chapter because it is fundamentally different from the three main classes (see \autoref{cha:scrlttr2}). -\iffalse% Umbruchkorrekturtext - The names of the {\KOMAScript} classes are composed of the prefix - ``\texttt{scr}'' and the abbreviated name of the corresponding standard - class. In order to restrict the length of the names to eight letters, the - vowels, starting with the last one, are left off as necessary. The - \autoref{tab:\LabelBase.overview} shows an overview of the correspondence - between the standard classes and the {\KOMAScript} classes. -\fi - The simplest way to use a {\KOMAScript} class instead of a standard one is to -substitute the class name in the \verb|\documentclass| command according to -\autoref{tab:\LabelBase.overview}. For example, you may replace -\Macro{documentclass}\PParameter{book} by -\Macro{documentclass}\PParameter{scrbook}. Normally, the document should be -processed without errors by {\LaTeX}, just like before the substitution. The -look, however, should be different. Additionally, the {\KOMAScript} classes -provide new possibilities and options that are described in the following -sections. +substitute the class name in the \verb|\documentclass| command in accordance +with \autoref{tab:\LabelBase.overview}. For example, you can replace +\Macro{documentclass}\PParameter{book} with +\Macro{documentclass}\PParameter{scrbook}. Normally, {\LaTeX} should process +the document without errors, just as before the substitution. The layout, +however, should be different. Additionally, the {\KOMAScript} classes provide +new possibilities and options that are described in the following sections. \begin{table} % \centering - \KOMAoptions{captions=topbeside} - \setcapindent{0pt} + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% % \caption \begin{captionbeside} - [Class correspondence]{\label{tab:\LabelBase.overview}Correspondence between - standard classes and {\KOMAScript} classes}% and \Script{} styles.} - [l] - \begin{tabular}[t]{ll} - \toprule - standard class & {\KOMAScript} class \\%& \Script-Stil (\LaTeX2.09)\\ - \midrule - \Class{article} & \Class{scrartcl} \\%& \File{script\textunderscore s} \\ - \Class{report} & \Class{scrreprt} \\%& \File{script} \\ - \Class{book} & \Class{scrbook} \\%& \File{script} \\ - \Class{letter} & \Class{scrlttr2} \\%& \File{script\textunderscore l} \\ - \bottomrule - \end{tabular} + [Class correspondence]{\label{tab:\LabelBase.overview}Correspondence between + standard classes and {\KOMAScript} classes} + [l] + \begin{tabular}[t]{ll} + \toprule + standard class & \KOMAScript{} class \\%& \Script-Stil (\LaTeX2.09)\\ + \midrule + \Class{article} & \Class{scrartcl} \\%& \File{script\textunderscore s} \\ + \Class{report} & \Class{scrreprt} \\%& \File{script} \\ + \Class{book} & \Class{scrbook} \\%& \File{script} \\ + \Class{letter} & \Class{scrlttr2} \\%& \File{script\textunderscore l} \\ + \bottomrule + \end{tabular} \end{captionbeside} \end{table} -Allow me an observation before proceeding with the descriptions of the -options. It is often the case that at the beginning of a document one is often -unsure which options to choose for that specific document. Some options, for -instance the choice of paper size, may be fixed from the beginning. But -already the question of the size of the text area and the margins could be -difficult to answer initially. On the other hand, the main business of an -author\,---\,planning the document structure, writing the text, preparing -figures, tables, lists, index, and other data\,---\,should be almost -independent of those settings. As an author you should concentrate initially -on this work. When that is done, you can concentrate on the fine points of -presentation. Besides the choice of options, this means correcting -hyphenation, optimizing page breaks, and the placement of tables and figures. +Let me say something before describing the classes. When beginning to write a +document, you are often unsure which specific options to choose. Some +settings, for instance the choice of paper size, may be fixed in advance. But +even the question of the appropriate page layout could be difficult to answer +initially. On the other hand, these settings should be nearly irrelevant, in +the beginning, to the main business of an author: planning the document +structure, writing the text, preparing figures, tables, lists, index, and +other data. As an author, you should concentrate initially on the content. +When that is done, you can take on the fine points of presentation. In +addition to the choice of options, this includes correcting hyphenation, +optimizing page breaks, and placing tables and figures. + + +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \LoadCommonFile{options}% \section{Early or Late Selection of Options} @@ -138,46 +128,49 @@ hyphenation, optimizing page breaks, and the placement of tables and figures. \LoadCommonFile{typearea}% \section{Page Layout} \begin{Declaration} - \Macro{flushbottom}% + \Macro{flushbottom} \Macro{raggedbottom} \end{Declaration} \begin{Explain} - In double-sided documents, it's preferred to have the same visual baseline - in not only the first lines of the text areas in a double-side spread, but - also in the last lines. If pages consist of text without paragraphs or - headlines only, this is the result in general. But a paragraph distance of - half of a line would be enough to prevent achieving this, if the difference - in the number of paragraphs on each page of the double-page spread is - odd-numbered. In this case at least some of the paragraph distances need to - be shrunk or stretched to fit the rule again. \TeX{} knows shrinkable and - stretchable distances for this purpose. \LaTeX{} provides an automatism for - this kind of vertical adjustment\Index{adjustment>vertical}. + In two-sided documents especially, it is preferable to have the same visual + baseline not only for the first lines of each text area in a two-page spread + but also for the last lines. If a page consists only of text without + paragraphs or headings, this is generally the result. But a paragraph + spacing of half a line would be enough to prevent you from achieving this + goal if the number of paragraphs on each page of the two-page spread differs + by an odd number. In this case, at least some of the paragraph distances + need to be stretched or shrunk to reach the target again. \TeX{} defines + stretchable and shrinkable distances for this purpose, and \LaTeX{} lets you + perform this kind of \emph{vertical adjustment}\Index{adjustment} + automatically. \end{Explain} -Using double-sided typesetting with option -\Option{twoside}\IndexOption{twoside}\important{\Option{twoside}} (see +Using two-sided printing with the +\Option{twoside}\IndexOption{twoside}\important{\Option{twoside}} option (see \autoref{sec:typearea.options}, \DescPageRef{typearea.option.twoside}) or -two-column typesetting with option -\Option{twocolumn}\IndexOption{twocolumn}\important{\Option{twocolumn}} (see -\DescPageRef{typearea.option.twocolumn}) switches on vertical adjustment -also. But\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} with compatibility selection to a \KOMAScript{} version -prior to 3.17 (see \autoref{sec:\LabelBase.compatibilityOptions}, +two-column formatting with the +\Option{twocolumn}\IndexOption{twocolumn}\important{\Option{twocolumn}} option +(see \DescPageRef{typearea.option.twocolumn}) also activates this vertical +adjustment. But\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} this does not apply with a compatibility setting for a +\KOMAScript{} version prior to 3.17 (see +\autoref{sec:\LabelBase.compatibilityOptions}, \DescPageRef{\LabelBase.option.version}, option -\DescRef{\LabelBase.option.version}\IndexOption{version}\important{\OptionValueRef{\LabelBase}{version}{3.17}}) -this is not the case, if you use \DescRef{\LabelBase.cmd.KOMAoption} or \DescRef{\LabelBase.cmd.KOMAoptions} to +\DescRef{\LabelBase.option.version}\IndexOption{version}% +\important{\OptionValueRef{\LabelBase}{version}{3.17}}) if you use +\DescRef{\LabelBase.cmd.KOMAoption} or \DescRef{\LabelBase.cmd.KOMAoptions} to change the setting of these options. -Alternatively, vertical adjustment may be switched on -at any time valid from the current page using -\Macro{flushbottom}. \Macro{raggedbottom} would have the opposite -effect, switching off vertical adjustment from the current page -on. This is also the default at one-sided typesetting. +You can also explicitly request vertical adjustment at any time starting with +the current page by using \Macro{flushbottom}. \Macro{raggedbottom} has the +opposite effect, switching off vertical adjustment starting with the current +page. This corresponds to the default for one-sided printing. -By the way, \KOMAScript{} uses a slightly modified kind of abdication of -vertical adjustment. This has been done to move footnotes to the bottom of the -text area instead of having them close to the last used text line.\iffree{}{ - More information about this may be found at +By the way, \KOMAScript{} uses a slightly modified method for adjusting the +vertical skip. This has been done to move footnotes to the bottom of the +text area instead of having them close to the last text line used. +\iffree{}{ + You can find more information about this at \autoref{sec:maincls-experts.addInfos}, \DescPageRef{maincls-experts.cmd.footnoterule}.}% % @@ -186,8 +179,7 @@ text area instead of having them close to the last used text line.\iffree{}{ \EndIndexGroup -\LoadCommonFile{fontsize} - +\LoadCommonFile{fontsize}% \section{Choosing the Document Font Size} \LoadCommonFile{textmarkup}% \section{Text Markup} @@ -196,38 +188,42 @@ text area instead of having them close to the last used text line.\iffree{}{ \section{Abstract} \seclabel{abstract} \BeginIndexGroup -\BeginIndex{}{summary}% \BeginIndex{}{abstract}% -Particularly\OnlyAt{\Class{scrartcl}\and\Class{scrreprt}} with -articles, more rarely with reports, there is a summary\Index{summary} -directly under the title and before the table of contents. When using an in-page -title, this summary is normally a kind of left- and right-indented block. In -contrast to this, a kind of chapter or section is printed using title pages. +Particularly with articles, more rarely with reports, there is an abstract, or +summary, directly beneath the title and before the table of contents. When +using an in-page title, this abstract is normally a kind of left- and +right-indented block. In comparison, the abstract appears as a chapter or +section when using title pages. \begin{Declaration} \OptionVName{abstract}{simple switch} \end{Declaration}% -In\ChangedAt{v3.00}{\Class{scrreprt}\and \Class{scrartcl}}% -\OnlyAt{\Class{scrreprt}\and\Class{scrartcl}} the standard classes the -\DescRef{\LabelBase.env.abstract} environment sets the text ``\abstractname'' centered -before the summary text\Index[indexmain]{summary}. This was normal practice in -the past. In the meantime, newspaper reading has trained readers to recognize -a displayed text at the beginning of an article or report as the -abstract. This is even more true when the text comes before the table of -contents. It is also surprising when precisely this title appears small and -centered. {\KOMAScript} provides the possibility of including or excluding the -abstract's title with the options \Option{abstract}. For \PName{simple - switch}, any value from -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} may be used. - -Books typically use another type of summary. In that case there is usually a -dedicated summary chapter at the beginning or end of the book. This chapter is -often combined with the introduction or a description of wider -prospects. Therefore, the class \Class{scrbook} has no \DescRef{\LabelBase.env.abstract} -environment. A\textnote{Hint!} summary chapter is also recommended for reports in a wider -sense, like a Master's or Ph.D. thesis.% -% +In\OnlyAt{\Class{scrreprt}\and\Class{scrartcl}} the standard +classes\textnote{\KOMAScript{} vs. standard classes}, the +\DescRef{\LabelBase.env.abstract} environment sets the text ``\abstractname'' +centred before the abstract text. This used to be the normal practice. Since +then, reading newspapers has trained us to recognize a suitably highlighted +text at the beginning of an article or report as the abstract. This is even +more true when the text comes before the table of contents. It is also +confusing if, of all things, this title appears small and centred. +{\KOMAScript}\ChangedAt{v3.00}{\Class{scrreprt}\and \Class{scrartcl}} offers +the option to include or exclude the abstract's title with the +\Option{abstract} option. For \PName{simple switch}, you can use any value +from \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. The +default for \KOMAScript{} is \PValue{false}. + +Books typically use a different kind of summary. There, you usually place an +appropriate chapter at the beginning or the end of the work. This chapter is +often combined with either the introduction or a description of a larger +prospectus. Therefore, the \Class{scrbook} class has no +\DescRef{\LabelBase.env.abstract} environment. A\textnote{Hint!} summary +chapter is also recommended for reports in a wider sense, such as a Master's +thesis or Ph.D. dissertation. See the commands +\DescRef{\LabelBase.cmd.chapter*}\IndexCmd{chapter*}, +\DescRef{\LabelBase.cmd.addchap}\IndexCmd{addchap}, and +\DescRef{\LabelBase.cmd.addchap*}\IndexCmd{addchap*} documented in +\autoref{sec:maincls.structure}, from \DescPageRef{\LabelBase.cmd.chapter*}.% \EndIndexGroup @@ -235,32 +231,32 @@ sense, like a Master's or Ph.D. thesis.% \begin{Environment}{abstract}\end{Environment} \end{Declaration}% \OnlyAt{\Class{scrartcl}\and \Class{scrreprt}}% -Some {\LaTeX} classes offer a special environment for this summary, the -\Environment{abstract} environment. This is output directly, as it is not a -component of the titles set by \DescRef{\LabelBase.cmd.maketitle}. -Please\textnote{Attention!} note that \Environment{abstract} is an -environment, not a command. Whether the summary has a heading or not is -determined by the option \DescRef{\LabelBase.option.abstract} (see above). - -With books (\Class{scrbook}) the summary is frequently a component of the -introduction or a separate chapter at the end of the document. Therefore no -\Environment{abstract} environment is provided. When using the class -\Class{scrreprt} it is surely worth considering whether one should not proceed -likewise. See commands \DescRef{\LabelBase.cmd.chapter*}\IndexCmd{chapter*} and -\DescRef{\LabelBase.cmd.addchap}\IndexCmd{addchap} or \DescRef{\LabelBase.cmd.addchap*} at -\autoref{sec:\LabelBase.structure} from \DescPageRef{\LabelBase.cmd.chapter*} -onwards. +Some {\LaTeX} classes provide a special environment for this summary: the +\Environment{abstract} environment. This is output directly, so it is not part +of the title created with \DescRef{\LabelBase.cmd.maketitle}. +Please\textnote{Attention!} note that \Environment{abstract} is an +environment, not a command. Whether the abstract has a heading or not is +determined by the \DescRef{\LabelBase.option.abstract} option (see above). + +For books, the abstract is usually part of the introduction or a separate +chapter at the end of the document. Therefore \Class{scrbook} does not provide +an \Environment{abstract} environment. When using the \Class{scrreprt} class, +it is definitely worth considering whether to proceed in the same way. See the +commands \DescRef{\LabelBase.cmd.chapter*}\IndexCmd{chapter*} and +\DescRef{\LabelBase.cmd.addchap}\IndexCmd{addchap}, or +\DescRef{\LabelBase.cmd.addchap*} in \autoref{sec:\LabelBase.structure} +from \DescPageRef{\LabelBase.cmd.chapter*} for more on this. When using an in-page title\Index{title>in-page} (see option \DescRef{\LabelBase.option.titlepage}, \autoref{sec:\LabelBase.titlepage}, -\DescPageRef{\LabelBase.option.titlepage}), the abstract is set using the -environment \Environment{quotation}\IndexEnv{quotation} (see -\autoref{sec:\LabelBase.lists}, \DescPageRef{\LabelBase.env.quotation}) -internally. Thereby paragraphs will be set with indentation of the first -line. If that first paragraph of the abstract should not be indented, this -indent may be disabled using -\Macro{noindent}\IndexCmd{noindent}\important{\Macro{noindent}} \iffree{just - after \Macro{begin}\PParameter{abstract}}{at the begin of the environment}.% +\DescPageRef{\LabelBase.option.titlepage}), the abstract is set internally +using the \DescRef{\LabelBase.env.quotation}\IndexEnv{quotation} environment +(see \autoref{sec:\LabelBase.lists}, \DescPageRef{\LabelBase.env.quotation}). +This way paragraphs will be set with the first line indented. If the first +paragraph of the abstract should not be indented, you can suppress this indent +by using \Macro{noindent}\IndexCmd{noindent}% +\important{\Macro{noindent}} \iffree{just after + \Macro{begin}\PParameter{abstract}}{at the beginning of the environment}.% % \EndIndexGroup % @@ -272,289 +268,339 @@ indent may be disabled using \BeginIndexGroup \BeginIndex{}{table of contents} -The table of contents is normally set after the document title and an -optional existing abstract. Often one may find additional lists of -floating environments, e.\,g., the list of tables and the list of -figures, after the table of contents (see +The title and optional abstract are normally followed by a table of contents. +Often you also find additional lists of the floating environments, such as +tables and figures, after the table of contents (see \autoref{sec:\LabelBase.floats}). +\iffalse% + Note that in addition to the options documented in this section, the + commands \DescRef{maincls-experts.cmd.DeclareSectionCommand}, + \DescRef{maincls-experts.cmd.DeclareNewSectionCommand}, + \DescRef{maincls-experts.cmd.RedeclareSectionCommand}, and + \DescRef{maincls-experts.cmd.ProvideSectionCommand} can also affect the + table of contents. See \autoref{sec:maincls-experts.experts}, + \DescPageRef{maincls-experts.cmd.DeclareSectionCommand}.% +\else% + In addition to the options documented in this section, the + \hyperref[cha:tocbasic]{\Package{tocbasic}}% + \important{\hyperref[cha:tocbasic]{\Package{tocbasic}}}% + \IndexPackage{tocbasic} package style selected and configured with + \DescRef{tocbasic.cmd.DeclareTOCStyleEntry}\IndexCmd{DeclareTOCStyleEntry}% + \important[O]{\DescRef{tocbasic.cmd.DeclareTOCStyleEntry}} (see + \DescPageRef{tocbasic.cmd.DeclareTOCStyleEntry}) also has a significant + impact on the appearance of the table of contents. Similarly, the commands + \DescRef{maincls-experts.cmd.DeclareSectionCommand}% + \important[O]{\DescRef{maincls-experts.cmd.DeclareSectionCommand}}% + \IndexCmd{DeclareSectionCommand}, + \DescRef{maincls-experts.cmd.ProvideSectionCommand}% + \IndexCmd{ProvideSectionCommand}, + \DescRef{maincls-experts.cmd.DeclareNewSectionCommand}% + \IndexCmd{DeclareNewSectionCommand} and + \DescRef{maincls-experts.cmd.RedeclareSectionCommand}% + \IndexCmd{RedeclareSectionCommand} documented in + \autoref{sec:maincls-experts.experts}, + \DescPageRef{maincls-experts.cmd.DeclareSectionCommand} can also affect the + table of contents.% +\fi + + \begin{Declaration} - \OptionVName{toc}{selection} + \OptionVName{toc}{setting} \end{Declaration} -\label{desc:\LabelBase.option.toc.listof}% -\label{desc:\LabelBase.option.toc.nolistof}% -\label{desc:\LabelBase.option.toc.listofnumbered}\nobreak -It is becoming increasingly common to find entries in the table of contents -for the lists of tables and figures, for the bibliography, and, sometimes, -even for the index. This is surely also related to the recent trend of putting -lists of figures and tables at the end of the document. Both lists are -similiar to the table of contents in structure and intention. I'm therefore -sceptical of this evolution. Since\important{\OptionValue{toc}{listof}} it -makes no sense to include only one of the lists of tables and figures in the -table of contents, there exists only one -\PName{selection}\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} \PValue{listof}\IndexOption{toc~=\PValue{listof}} that -causes entries for both types of lists to be included. This also includes any -lists produced with version~1.2e or later of the -\Package{float}\IndexPackage{float} package (see \cite{package:float}) or the -\Package{floatrow} (see \cite{package:floatrow}). -All\important{\OptionValue{toc}{listofnumbered}} these lists are unnumbered, -since they contain entries that reference other sections of the document. If -one wants to ignore this general agreement, one may use \PName{selection} -\PValue{listofnumbered}% -\IndexOption{toc~=\PValue{listofnumbered}}. - -\leavevmode\phantomsection\nobreak -\label{desc:\LabelBase.option.toc.index}\nobreak -The\important{\OptionValue{toc}{index}} option \OptionValue{index}{totoc} -causes an entry for the index to be included in the table of contents. The -index is unnumbered since it too only includes references to the contents of -the other sectional units. Despite\ChangedAt{v3.18}{\Class{scrbook}\and +It is becoming increasingly common to to include lists of tables and figures, +the bibliography, and sometimes even the index in the table of contents. This +is surely related to the recent trend of putting lists of figures and tables +at the end of the document. Both lists are similar to the table of contents in +structure and intention. I'm therefore sceptical of this evolution. +Since\important{\OptionValue{toc}{listof}} it makes no sense to include only +the list of tables or that of figures in the table of contents without the +other, there is only one \PName{setting}\ChangedAt{v3.00}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} +\PValue{listof}\IndexOption{toc~=\textKValue{listof}}, which causes entries +for both types of lists to be included. This also includes any lists produced +with version~1.2e or later of the \Package{float} package\IndexPackage{float} +from Version~1.2e (see \cite{package:float}) or \Package{floatrow} (see +\cite{package:floatrow}). None\important{\OptionValue{toc}{listofnumbered}} +of these lists are generally given a chapter number. If you want to ignore +this principle, use the \PName{setting} +\PValue{listofnumbered}\IndexOption{toc~=\textKValue{listofnumbered}}. + +\leavevmode\LabelOptionValue{toc}{index}\nobreak +The\important{\OptionValue{toc}{index}} +\OptionValue{toc}{index}\IndexOption{toc~=\textKValue{index}} option causes an +entry for the index to be included in the table of contents. The index is +unnumbered since it too only includes references to the contents of the other +sectioning levels. Despite\ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} -\important{\OptionValue{toc}{indexnumbered}}objection of the author, -\KOMAScript{} does also support to ignore this general agreement using -\OptionValue{toc}{indexnumbered}\IndexOption{toc~=\PValue{indexnumbered}}. - -\leavevmode\phantomsection\nobreak -\label{desc:\LabelBase.option.toc.bibliography}\nobreak -The bibliography is a different kind of listing. It does not list the contents -of the present document but refers instead to external -documents. For\important{\begin{tabular}{@{}r@{}} - \multicolumn{1}{@{}l@{}}{\Option{toc=}}\\ - ~\PValue{bibliographynumbered}\\ - \end{tabular}} that -reason, it could be argued that it qualifies as a chapter (or section) and, as -such, should be numbered. The option \OptionValue{toc}{bibliographynumbered}% -\IndexOption{toc~=\PValue{bibliographynumbered}} -has this effect, including the generation of the corresponding entry in the -table of contents. I personally think that this reasoning would lead us to -consider a classical list of sources also to be a separate chapter. On the -other hand, the bibliography is finally not something that was written by the -document's author. In\important{\OptionValue{toc}{bibliography}} view of this, the bibliography merits nothing more than -an unnumbered entry in the table of contents, and that can be achieved with -\OptionValue{toc}{bibliography}\IndexOption{toc~=\PValue{bibliography}}. - -\leavevmode\phantomsection\nobreak -\label{desc:\LabelBase.option.toc.graduated}\nobreak +\important{\OptionValue{toc}{indexnumbered}} the author's concerns, +\KOMAScript{} does support deviating from this principle with +\OptionValue{toc}{indexnumbered}\IndexOption{toc~=\textKValue{indexnumbered}}. + +\leavevmode\LabelOptionValue{toc}{bibliography}\nobreak The bibliography is a +slightly different kind of listing. It does not list the contents of the +present document but refers instead to external sources. +For\important{\OptionValue{toc}{bibliographynumbered}} that reason, it could +be argued that it qualifies as a chapter (or section) and, as such, should be +numbered. The \OptionValue{toc}{bibliographynumbered}% +\IndexOption{toc~=\textKValue{bibliographynumbered}} option has this effect, +and puts the appropriate entry in the table of contents. However, I think that +this reasoning would lead us to consider even a classic, annotated source list +to be a separate chapter. Moreover, the bibliography is ultimately not +something that you wrote yourself. +Therefore\important{\OptionValue{toc}{bibliography}} the bibliography merits, +at best, an unnumbered entry in the table of contents, and you can achieve +this achieved with +\OptionValue{toc}{bibliography}\IndexOption{toc~=\textKValue{bibliography}}. + +\leavevmode\LabelOptionValue{toc}{graduated}\nobreak The table of contents is normally\ChangedAt{v2.8q}{% \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% -\important{\OptionValue{toc}{graduated}} set up so that different sectional -units have different indentations. The section number is set left-justified in -a fixed-width field. This default setup is selected with the option -\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} -\OptionValue{toc}{graduated}\IndexOption{toc~=\PValue{graduated}}. - -\leavevmode\phantomsection\nobreak -\label{desc:\LabelBase.option.toc.flat}\nobreak -When there are many sections, the corresponding numbering tends to become very -wide, so that the reserved field overflows. The German FAQ \cite{DANTE:FAQ} -suggests that the table of contents should be redefined in such a -case. {\KOMAScript}\important{\OptionValue{toc}{flat}} offers an alternative -format that avoids the problem completely. If the option -\OptionValue{toc}{flat}\IndexOption{toc~=\PValue{flat}} is selected, then no variable indentation is applied -to the titles of the sectional units. Instead, a table-like organisation is -used, where all unit numbers and titles, respectively, are set in a -left-justified column. The space necessary for the unit numbers is thus -determined automatically.% - -The \autoref{tab:\LabelBase.toc} shows an overview of possible values for -\PName{selection} of \Option{toc}. +\important{\OptionValue{toc}{graduated}} formatted so that different levels of +sectioning commands have different indentations. The number for each level is +set left-justified in a fixed-width field. This default set-up is selected +with the\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} +\OptionValue{toc}{graduated}\IndexOption{toc~=\textKValue{graduated}} option. + +\leavevmode\LabelOptionValue{toc}{flat}\nobreak +If the sectioning level which appears in the table of contents is too deep, the +number for that level can be so wide that the space reserved for the number is +insufficient. The German FAQ \cite{DANTE:FAQ} suggests redefining the table of +contents in such a case. \KOMAScript{}\important{\OptionValue{toc}{flat}} +offers an alternative format that avoids the problem completely. If you use +the \OptionValue{toc}{flat}\IndexOption{toc~=\textKValue{flat}} option, no +graduated indentation is applied to the headings of the sectioning levels. +Instead, a table-like organisation is used, where all sectioning numbers and +headings are set in a left-justified column. The space necessary for the +section numbers is thus determined automatically. + +You can find an overview of all available values for the \PName{setting} of +\Option{toc}. in \autoref{tab:\LabelBase.toc}. \begin{desclist} - \desccaption[{Possible values of option \Option{toc}}]{% - Possible values of option \Option{toc} to set form and contents of the - table of contents\label{tab:\LabelBase.toc}% + \desccaption[{Available values of the \Option{toc} option}]{% + Available values of the \Option{toc} option to set the format and contents + of the table of contents\label{tab:\LabelBase.toc}% }{% - Possible values of option \Option{toc} (\emph{continuation})% + Available values of the \Option{toc} option (\emph{continued})% }% \entry{\PValue{bibliography}, \PValue{bib}}{% - The bibliography will be represented by an entry at the table of contents, - but will not be numbered.% - \IndexOption{toc~=\PValue{bibliography}}}% + The bibliography has an unnumbered entry in the table of contents.% + \IndexOption{toc~=\textKValue{bibliography}}}% \entry{\PValue{bibliographynumbered}, \PValue{bibnumbered}, \PValue{numberedbibliography}, \PValue{numberedbib}}{% - The bibliography will be represented by an entry at the table of contents - and will be numbered.% - \IndexOption{toc~=\PValue{bibliographynumbered}}}% + The bibliography has a numbered entry in the table of contents.% + \IndexOption{toc~=\textKValue{bibliographynumbered}}}% \entry{\PValue{chapterentrywithdots}, \PValue{chapterentrydotfill}}{% \ChangedAt[2014/12]{v3.15}{\Class{scrbook}\and \Class{scrreprt}}% - The chapter entries of classes \Class{scrbook} and \Class{scrreprt} also - use dots to separate the headings text from the page number.% - \IndexOption{toc~=\PValue{chapterentrywithdots}}}% + The chapter entries for the \Class{scrbook} and \Class{scrreprt} classes + also use dots to separate the heading text from the page numbers.% + \IndexOption{toc~=\textKValue{chapterentrywithdots}}}% \entry{\PValue{chapterentrywithoutdots}, \PValue{chapterentryfill}}{% \ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}}% - The chapter entries of classes \Class{scrbook} and \Class{scrreprt} - use white space to separate the headings text from the page number.% - \IndexOption{toc~=\PValue{chapterentrywithoutdots}}}% + The chapter entries of the \Class{scrbook} and \Class{scrreprt} classes + use white space to separate the heading text from the page numbers. This + corresponds to the default setting.% + \IndexOption{toc~=\textKValue{chapterentrywithoutdots}}}% \entry{\PValue{flat}, \PValue{left}}{% - The table of contents will be set in table form. The numbers of the - headings will be at the first column, the heading text at the second - column, and the page number at the third column. The amount of space - needed for the numbers of the headings will be determined by the detected - needed amount of space at the previous \LaTeX{} run.% - \IndexOption{toc~=\PValue{flat}}}% + The table of contents is set in table form. The numbers of the headings + are in the first column, the heading text in the second column, and the + page number in the third column. The amount of space needed for the + numbers of the headings is determined by the required amount of space + detected during the previous \LaTeX{} run.% + \IndexOption{toc~=\textKValue{flat}}}% \entry{\PValue{graduated}, \PValue{indent}, \PValue{indented}}{% - The table of contents will be set in hierarchical form. The amount of - space for the heading numbers is limited.% - \IndexOption{toc~=\PValue{graduated}}}% + The table of contents is set in hierarchical form. The amount of space for + the heading numbers is limited. This corresponds to the default setting.% + \IndexOption{toc~=\textKValue{graduated}}}% + \entry{\PValue{indenttextentries}, \PValue{indentunnumbered}, + \PValue{numberline}}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The \PValue{numberline} property (see \autoref{sec:tocbasic.toc}, + \DescPageRef{tocbasic.cmd.setuptoc}) is set for the table of contents. As + a result, unnumbered entries are left aligned with the text of numbered + entries of the same level.% + \IndexOption{toc~=\textKValue{numberline}}}% \entry{\PValue{index}, \PValue{idx}}{% - The index will be represented by an entry at the table of contents, but - will not be numbered.% - \IndexOption{toc~=\PValue{index}}}% + The index has an unnumbered entry in the table of contents.% + \IndexOption{toc~=\textKValue{index}}}% \entry{\PValue{indexnumbered}}{% \ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - The index will be represented by an entry at the table of contents and - will be numbered.% - \IndexOption{toc~=\PValue{index}}}% + The index has a numbered entry in the table of contents.% + \IndexOption{toc~=\textKValue{index}}}% + \entry{\PValue{leftaligntextentries}, \PValue{leftalignunnumbered}, + \PValue{nonumberline}}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The \PValue{numberline} property (see \autoref{sec:tocbasic.toc}, + \DescPageRef{tocbasic.cmd.setuptoc}) is deleted for the table of contents. + This places unnumbered entries left-aligned with the number of + numbered entries of the same level. This corresponds to the default + setting.% + \IndexOption{toc~=\textKValue{numberline}}}% \pventry{listof}{% - The lists of floating environments, e.\,g., the list of figures and the - list of tables, will be represented by entries at the table of contents, - but will not be numbered.% - \IndexOption{toc~=\PValue{listof}}}% + The lists of floating environments, e.\,g. figures and tables, have + unnumbered entries in the table of contents.% + \IndexOption{toc~=\textKValue{listof}}}% \entry{\PValue{listofnumbered}, \PValue{numberedlistof}}{% - The lists of floating environments, e.\,g., the list of figures and the - list of tables, will be represented by entries at the table of contents - and will be numbered.% - \IndexOption{toc~=\PValue{listofnumbered}}}% + The lists of floating environments, e.\,g. figures and tables, have + numbered entries in the table of contents.% + \IndexOption{toc~=\textKValue{listofnumbered}}}% \entry{\PValue{nobibliography}, \PValue{nobib}}{% - The bibliography will not be represented by an entry at the table of - contents.% - \IndexOption{toc~=\PValue{nobibliography}}}% + The bibliography does not have an entry in the table of contents. This + corresponds to the default setting.% + \IndexOption{toc~=\textKValue{nobibliography}}}% \entry{\PValue{noindex}, \PValue{noidx}}{% - The index will not be represented by an entry at the table of - contents.% - \IndexOption{toc~=\PValue{noindex}}}% + The index does not have an entry in the table of contents. This + corresponds to the default setting.% + \IndexOption{toc~=\textKValue{noindex}}}% \pventry{nolistof}{% - The lists of floating environments, e.\,g., the list of figures and the - list of tables, will not be represented by entries at the table of - contents.% - \IndexOption{toc~=\PValue{nolistof}}}% + The lists of floating environments, e.\,g. figures and tables, do not + have entries in the table of contents. This corresponds to the default + setting.% + \IndexOption{toc~=\textKValue{nolistof}}}% \entry{\PValue{sectionentrywithdots}, \PValue{sectionentrydotfill}}{% \ChangedAt[2014/12]{v3.15}{\Class{scrartcl}}% - The section entries of class \Class{scrartcl} also - use dots to separate the headings text from the page number.% - \IndexOption{toc~=\PValue{sectionentrywithdots}}}% + The section entries of the \Class{scrartcl} class also use dots to + separate the heading text from the page numbers.% + \IndexOption{toc~=\textKValue{sectionentrywithdots}}}% \entry{\PValue{sectionentrywithoutdots}, \PValue{sectionentryfill}}{% \ChangedAt{v3.15}{\Class{scrartcl}}% - The section entries of class \Class{scrartcl} - use white space to separate the headings text from the page number.% - \IndexOption{toc~=\PValue{sectionentrywithoutdots}}}% + The section entries of the \Class{scrartcl} class use white space to + separate the heading text from the page number. This corresponds to the + default setting.% + \IndexOption{toc~=\textKValue{sectionentrywithoutdots}}}% \end{desclist} % \EndIndexGroup \begin{Declaration} - \OptionVName{chapterentrydots}{simple switch}% + \OptionVName{chapterentrydots}{simple switch}\\ \OptionVName{sectionentrydots}{simple switch} \end{Declaration} These\ChangedAt[2014/12]{v3.15}{\Class{scrbook}\and \Class{scrreprt}} options -configure a dotted separation line between the text and the page number of the -chapter entries of classes \Class{scrbook} and -\Class{scrreprt}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}}, or of the -section entries of class \Class{scrartcl}\OnlyAt{\Class{scrartcl}} in the -table of contents. For \PName{simple switch}, any value from -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} may be -used. The default is \PValue{false}. It selects an empty gap instead of -dots. +configure a dotted connecting line between the text and page number of the +chapter entries for the \Class{scrbook} and +\Class{scrreprt}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} classes, or for +the section entries of the \Class{scrartcl}\OnlyAt{\Class{scrartcl}} class, in +the table of contents. For the \PName{simple switch}, you can use any value from +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. +The default is \PValue{false}. It selects an empty gap instead of dots. \BeginIndex{FontElement}{chapterentrydots}\LabelFontElement{chapterentrydots}% \BeginIndex{FontElement}{sectionentrydots}\LabelFontElement{sectionentrydots}% -If a dotted line is selected, you can change their font using element +If a dotted line is used, you can change its font using the element \FontElement{chapterentrydots}% \important[i]{\FontElement{chapterentrydots}\\ \FontElement{sectionentrydots}} or \FontElement{sectionentrydots}. The font -also depends on the element of the page number of the entry (see also -\autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont} -and \autoref{tab:\LabelBase.fontelements}, -\autopageref{tab:\LabelBase.fontelements}). The defaults of the elements are -shown in \autoref{tab:\LabelBase.tocelements}. Please note\textnote{Attention!} -that the dots of all entries are equally aligned only if all dots use the same -font.% +also depends on the element of the page number of the entry (see also +\DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont}, \autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}, as well as +\autoref{tab:maincls.fontelements}, +\autopageref{tab:maincls.fontelements}). The defaults of the elements are +shown in \autoref{tab:maincls.tocelements}, from +\autopageref{tab:maincls.tocelements}. Note\textnote{Attention!} that the dots +of all entries will be equally spaced only if all dots use the same font.% \EndIndexGroup \begin{Declaration} \Macro{tableofcontents} \end{Declaration}% -The production of the table of contents is done by the \Macro{tableofcontents} -command. To get a correct table of contents, at least two {\LaTeX} runs are -necessary after every change. The contents and the form of the table of -contents may be influenced with the above described option \DescRef{\LabelBase.option.toc}. After -changing the settings of this option, at least two \LaTeX{} runs are needed -again. - -The entry for the highest sectional unit below \DescRef{\LabelBase.cmd.part}, -i.\,e., \DescRef{\LabelBase.cmd.chapter} with -\Class{scrbook}\IndexClass{scrbook} and \Class{scrreprt}\IndexClass{scrreprt} -or \DescRef{\LabelBase.cmd.section} with \Class{scrartcl}\IndexClass -{scrartcl} is not indented. There are no dots between the text of the -sectional unit heading and the page number. The typographic reasons for this -are that the font is usually different, and the desire for appropriate -emphasis. The table of contents of this manual is a good example of these -considerations. +The table of contents is output by the \Macro{tableofcontents} command. To get +correct values in the table of contents requires at least two {\LaTeX} runs +after every change. The \DescRef{\LabelBase.option.toc} option described above +can also affect the extent and format of the table of contents. After changing +the settings of this option, at least two \LaTeX{} runs are needed again. + +Entries for \DescRef{\LabelBase.cmd.chapter}\IndexCmd{chapter} with +\Class{scrbook}\IndexClass{scrbook} and \Class{scrreprt}\IndexClass{scrreprt}, +or \DescRef{\LabelBase.cmd.section}\IndexCmd{section} with +\Class{scrartcl}\IndexClass{scrartcl}, and the sectioning level +\DescRef{\LabelBase.cmd.part}\IndexCmd{part} are not indented. Additionally, +there are no dots between the text of this heading and the page number. The +typographical logic for this behaviour is that the font is usually distinct +and appropriate emphasis is desirable. +However\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}, you can change this behaviour with the previously +documented options. The table of contents of this \iffree{guide}{book} is +created with the default settings and serves as an example. + \BeginIndex{FontElement}{partentry}\LabelFontElement{partentry}% \BeginIndex{FontElement}{chapterentry}\LabelFontElement{chapterentry}% \BeginIndex{FontElement}{sectionentry}\LabelFontElement{sectionentry}% -The font style\ChangedAt{v2.97c}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}}\important[i]{\FontElement{partentry}\\ +The\ChangedAt{v2.97c}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\important{\FontElement{partentry}\\ \FontElement{chapterentry}\\ - \FontElement{sectionentry}} is, however, affected by the settings of the -element \FontElement{partentry}, and for classes \Class{scrbook} and -\Class{scrreprt} by \FontElement{chapterentry}, and for class \Class{scrartcl} -by \FontElement{sectionentry}. % + \FontElement{sectionentry}} font style of the top two levels in the table of +contents is also affected by the settings for the \FontElement{partentry} +element, as well as by the \FontElement{chapterentry} element for the +\Class{scrbook} and \Class{scrreprt} classes, and by the +\FontElement{sectionentry} element for the \Class{scrartcl} class. \BeginIndex{FontElement}{partentrypagenumber}% \LabelFontElement{partentrypagenumber}% +\LabelFontElement{pagination}% \BeginIndex{FontElement}{chapterentrypagenumber}% \LabelFontElement{chapterentrypagenumber}% \BeginIndex{FontElement}{sectionentrypagenumber}% \LabelFontElement{sectionentrypagenumber}% -The font style of the page numbers may be set dissenting from these elements -using \FontElement{partentrypagenumber} and -\FontElement{chapterentrypagenumber} respectively -\FontElement{sectionentrypagenumber} (see \autoref{sec:\LabelBase.textmarkup}, -\DescPageRef{\LabelBase.cmd.setkomafont}, and -\autoref{tab:\LabelBase.fontelements}, -\autopageref{tab:\LabelBase.fontelements}). % -\BeginIndex{FontElement}{chapterentrydots}% -\BeginIndex{FontElement}{sectionentrydots}% -If the optional dots of the entries of \DescRef{\LabelBase.cmd.chapter} or -\DescRef{\LabelBase.cmd.section} are used, you can change their font using -element \FontElement{chapterentrydots}% -\important[i]{\FontElement{chapterentrydots}\\ - \FontElement{sectionentrydots}} or \FontElement{sectionentrydots}. The font -also depends on the element of the page number of the entry (see also -\autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont} -and \autoref{tab:\LabelBase.fontelements}, -\autopageref{tab:\LabelBase.fontelements}). The defaults of the elements are -shown in \autoref{tab:\LabelBase.tocelements}. Please note\textnote{Attention!} -that the dots of all entries are aligned same only if all dots use the same -font.% +You can set the font style of the page numbers separately from these elements +using \FontElement{partentrypagenumber}% +\important{\FontElement{partentrypagenumber}} and +\FontElement{chapterentrypagenumber}% +\important{\FontElement{chapterentrypagenumber}\\ + \FontElement{sectionentrypagenumber}}\,---\,for \Class{scrbook} and +\Class{scrreprt}\,---\,or \FontElement{sectionentrypagenumber}\,---\,for +\Class{scrartcl}\,---\, (see \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} in \autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}, or +\autoref{tab:maincls.fontelements}, \autopageref{tab:maincls.fontelements}). +If\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} you use dotted lines connecting the heading entries +(chapter or section depending on the class) to the page numbers using the +\DescRef{\LabelBase.option.toc}% +\IndexOption{toc~=\textKValue{chapterentrywithdots}}% +\IndexOption{toc~=\textKValue{sectionentrywithdots}} +\DescRef{\LabelBase.option.chapterentrydots}% +\IndexOption{chapterentrydots~=\PName{simple switch}} or +\DescRef{\LabelBase.option.sectionentrydots}% +\IndexOption{sectionentrydots~=\PName{simple switch}} option, you can change +their font style using the \DescRef{\LabelBase.fontelement.chapterentrydots}% +\IndexFontElement{chapterentrydots}% +\important{\DescRef{\LabelBase.fontelement.chapterentrydots}\\ + \DescRef{\LabelBase.fontelement.sectionentrydots}} and +\DescRef{\LabelBase.fontelement.sectionentrydots}% +\IndexFontElement{sectionentrydots} elements. The defaults for these +elements are found in \autoref{tab:maincls.tocelements}. \begin{table} % \centering % \caption \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% \begin{captionbeside} - [Font style defaults of the elements of the table of contents] - {\label{tab:\LabelBase.tocelements}% - Font style defaults of the elements of the table of contents}% + [Default font styles for the elements of the table of contents] + {\label{tab:maincls.tocelements}% + Default font styles for the elements of the table of contents} [l] \setlength{\tabcolsep}{.9\tabcolsep}% Umbruchoptimierung! \begin{tabular}[t]{ll} \toprule Element & Default font style \\ \midrule - \DescRef{\LabelBase.fontelement.partentry} & + \FontElement{partentry} & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{disposition}\Macro{large} \\ - \DescRef{\LabelBase.fontelement.partentrypagenumber} & \\ - \DescRef{\LabelBase.fontelement.chapterentry} & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{disposition}\\ - \DescRef{\LabelBase.fontelement.chapterentrydots} & \Macro{normalfont} \\ - \DescRef{\LabelBase.fontelement.chapterentrypagenumber} & \\ - \DescRef{\LabelBase.fontelement.sectionentry} & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{disposition}\\ - \DescRef{\LabelBase.fontelement.sectionentrydots} & \Macro{normalfont} \\ - \DescRef{\LabelBase.fontelement.sectionentrypagenumber} & \\ + \FontElement{partentrypagenumber} & \\ + \FontElement{chapterentry} & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{disposition}\\ + \FontElement{chapterentrydots} & \Macro{normalfont} \\ + \FontElement{chapterentrypagenumber} & \\ + \FontElement{sectionentry} & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{disposition} \\ + \FontElement{sectionentrydots} & \Macro{normalfont} \\ + \FontElement{sectionentrypagenumber} & \\ \bottomrule \end{tabular} \end{captionbeside} @@ -565,53 +611,64 @@ font.% \begin{Declaration} \Counter{tocdepth} + \Macro{parttocdepth} + \Macro{sectiontocdepth} + \Macro{subsectiontocdepth} + \Macro{subsubsectiontocdepth} + \Macro{paragraphtocdepth} + \Macro{subparagraphtocdepth} \end{Declaration}% -Normally, the units included in the table of contents are all the units from -\DescRef{\LabelBase.cmd.part} to \DescRef{\LabelBase.cmd.subsection} for the classes \Class{scrbook} and -\Class{scrreprt} or from \DescRef{\LabelBase.cmd.part} to \DescRef{\LabelBase.cmd.subsubsection} for the class -\Class{scrartcl}. The inclusion of a sectional unit in the table of contents -is controlled by the counter \Counter{tocdepth}. This has the value \(-\)1 for -\DescRef{\LabelBase.cmd.part}, 0 for \DescRef{\LabelBase.cmd.chapter}, and so on. By incrementing -or decrementing the counter, one can choose the lowest sectional unit level to -be included in the table of contents. The same happens with the standard -classes. - -Please note\textnote{Attention!} that for \DescRef{\LabelBase.cmd.part} the -values of \Counter{tocdepth} and -\DescRef{\LabelBase.counter.secnumdepth}\IndexCounter{secnumdepth} (see +Normally, the sectioning divisions included in the table of contents are all +those from \DescRef{\LabelBase.cmd.part} to +\DescRef{\LabelBase.cmd.subsection} for the \Class{scrbook} and +\Class{scrreprt} classes, or from \DescRef{\LabelBase.cmd.part} to +\DescRef{\LabelBase.cmd.subsubsection} for the \Class{scrartcl} class. Whether +or not to include a sectioning level in the table of contents is controlled by +the \Counter{tocdepth} counter. This has the value -1 for +\DescRef{\LabelBase.cmd.part}, 0 for \DescRef{\LabelBase.cmd.chapter}, and so +on. By incrementing or decrementing the counter, you can choose the lowest +sectioning level to include in the table of contents. Incidentally, the +standard classes work the same way. +Unlike\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\textnote{\KOMAScript{} vs. standard classes} with the +standard classes, with \KOMAScript{} you do not need to remember these values. +\KOMAScript{} defines a \Macro{\PName{level}tocdepth} command for each +sectioning level with the appropriate value which you can use to set +\Counter{tocdepth}. + +Please note\textnote{Attention!} that in +\Class{scrartcl}\OnlyAt{\Class{scrartcl}}, the values of \Counter{tocdepth} +and \DescRef{\LabelBase.counter.secnumdepth}\IndexCounter{secnumdepth} (see \autoref{sec:\LabelBase.structure}, -\DescPageRef{\LabelBase.counter.secnumdepth}) are not the same in -\Class{scrartcl}\OnlyAt{\Class{scrartcl}}. Therefore, you should not use -\DescRef{\LabelBase.cmd.partnumdepth}\IndexCmd{partnumdepth} to set the value -of \Counter{tocdepth}.% +\DescPageRef{\LabelBase.counter.secnumdepth}) for +\DescRef{\LabelBase.cmd.part} are not the same. This behaviour was copied from +the standard \Class{article} class for compatibility. Thus, for example, you +should not use \DescRef{\LabelBase.cmd.partnumdepth}\IndexCmd{partnumdepth} to +set the value of \Counter{tocdepth}.% \begin{Example} - Assume that you are preparing an article that uses the sectional - unit \DescRef{\LabelBase.cmd.subsubsection}. However, you do not want this sectional - unit to appear in the table of contents. The preamble of your + Suppose you are preparing an article that uses the sectioning level + \DescRef{\LabelBase.cmd.subsubsection}. However, you do not want this + sectioning level to appear in the table of contents. The preamble of your document might contain the following: \begin{lstcode} \documentclass{scrartcl} - \setcounter{tocdepth}{2} + \setcounter{tocdepth}{\subsectiontocdepth} \end{lstcode} - You set the counter \Counter{tocdepth} to 2 because you know that - this is the value for \DescRef{\LabelBase.cmd.subsection}. If you know that - \Class{scrartcl} normally includes all levels down to - \DescRef{\LabelBase.cmd.subsubsection} in the table of contents, you can simply - decrement the counter \Counter{tocdepth} by one: + Thus you set the \Counter{tocdepth} counter to the value of the + \Macro{subsectiontocdepth} command. That value is normally 2, but this way, + you do not have to remember it. + + If instead you simply want to include one less level in the table of + contents than you normally would, you can simply subtract one from the + default value of \Counter{tocdepth}: \begin{lstcode} \documentclass{scrartcl} \addtocounter{tocdepth}{-1} \end{lstcode} - How much you should add to or subtract from the \Counter{tocdepth} counter - can also be found by looking at the table of contents after the first - {\LaTeX} run. -\end{Example} -A\textnote{Hint!} small hint in order that you do not need to remember which -sectional unit has which number: in the table of contents count the number of -units required extra or less and then, as in the above example, use -\Macro{addtocounter} to add or subtract that number to or from -\Counter{tocdepth}.% -% + The\textnote{Hint!} value that you need to add to or subtract from + \Counter{tocdepth} is listed in the table of contents after at least two + \LaTeX{} runs. +\end{Example}% \EndIndexGroup % \EndIndexGroup @@ -619,161 +676,200 @@ units required extra or less and then, as in the above example, use \LoadCommonFile{parmarkup}% \section{Paragraph Markup} -\LoadCommonFile{oddorevenpage}% \section{Detection of Odd and Even Pages} +\LoadCommonFile{oddorevenpage}% \section{Detecting Odd or Even Pages} -\section{Head and Foot Using Predefined Page Styles} +\section{Headers and Footers Using Predefined Page Styles} \seclabel{pagestyle} -\BeginIndexGroup -\BeginIndex{}{page>style} +\BeginIndexGroup +\BeginIndex{}{page>style}% One of the general characteristics of a document is the page style. In -{\LaTeX} this means mostly the contents of headers and footers. +\LaTeX{} this primarily consists of the contents of headers and footers. + \begin{Declaration} - \OptionVName{headsepline}{simple switch}% + \OptionVName{headsepline}{simple switch} \OptionVName{footsepline}{simple switch} \end{Declaration}% -In\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} -order to have or not to have a rule separating the header from the text body, -use the option \Option{headsepline} with any value shown in -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. Activation -of the option will result in such a separation line. Similarly, activation of -option \Option{footsepline} switches on a rule above the foot -line. Deactivation of any of the options will deactivate the corresponding -rule. - -These options have no effect with the page styles \PValue{empty} and -\PValue{plain}, because there is no header in this case. Such a line always -has the effect of visually bringing header and text body closer together. That -does not mean that the header must now be moved farther from the text -body. Instead, the header should be considered as belonging to the text body -for the purpose of page layout calculations. {\KOMAScript} takes this into -account by automatically passing the option -\DescRef{typearea.option.headinclude} to the \Package{typearea} package -whenever the \Option{headsepline} option is used. \KOMAScript{} behaves -similar to \DescRef{typearea.option.footinclude} using -\Option{footsepline}. Package \Package{scrlayer-scrpage} (see -\autoref{cha:scrlayer-scrpage}) adds additional features to this.% +You\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} can use these options to specify whether a horizontal rule +appears beneath the header or above the footer. You can use any of the values +for simple switches shown in \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch}. Setting the \Option{headsepline} option to +true or invoking it with no value results in a line beneath the header. +Similarly, activating the \Option{footsepline} option results in a rule above +the footer. Deactivating either option switches off the respective rule. + +The\textnote{Attention!} \Option{headsepline} option naturally has no effect +with the \DescRef{\LabelBase.pagestyle.empty} and +\DescRef{\LabelBase.pagestyle.plain} page styles, which are described below, +because these styles explicitly dispense with a header\Index{page>header}. +Typographically, such a line has the effect of making the header appear to be +closer to the text. This does not mean that the header then needs to be moved +farther away from the body of the text\Index{text>body}. Instead, the header +should be considered as belonging to the text body for the purpose of +calculating the type area. \KOMAScript{} takes this into account by passing +the \Option{headsepline} option to the +\hyperref[cha:typearea]{\Package{typearea}}% +\important{\hyperref[cha:typearea]{\Package{typearea}}}\IndexPackage{typearea} +package, which then automatically executes the package option +\DescRef{typearea.option.headinclude}% +\IndexOption{headinclude}\important{\DescRef{typearea.option.headinclude}} +with the same value. The same applies to the footer separation line. Unlike +\Option{headsepline}, the \Option{footsepline} option also affects the +\PValue{plain} page style because \PValue{plain} prints a page number in the +footer. + +The options themselves do not automatically recalculate the type area. To +recalculate it, use the \DescRef{typearea.option.DIV} option with the values +\hyperref[desc:typearea.option.DIV.last]{\PValue{last}} or +\hyperref[desc:typearea.option.DIV.current]{\PValue{current}} (see +\DescPageRef{typearea.option.DIV.last}) or the +\DescRef{typearea.cmd.recalctypearea} command (see +\DescPageRef{typearea.cmd.recalctypearea}) in \autoref{cha:typearea}. + +The \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} +package (see \autoref{cha:scrlayer-scrpage}) offers further possibilities for +adjusting lines in headers and footers.% % \EndIndexGroup \begin{Declaration} - \Macro{pagestyle}\PParameter{page style}% + \Macro{pagestyle}\Parameter{page style} \Macro{thispagestyle}\Parameter{local page style} \end{Declaration}% -Usually one distinguishes four different page styles: +There are usually four different page styles: \begin{description} -\item[empty\BeginIndex{Pagestyle}{empty}\LabelPageStyle{empty}] is the page - style with entirely empty headers and footers. In {\KOMAScript} this is - completely identical to the standard classes. -\item[headings\BeginIndex{Pagestyle}{headings}\LabelPageStyle{headings}] is - the page style with running headings in the header. These are headings for - which titles are automatically inserted into the header. - \OnlyAt{\Class{scrbook}\and\Class{scrreprt}}With the classes - \Class{scrbook}\IndexClass{scrbook} and - \Class{scrreprt}\IndexClass{scrreprt} the titles of chapters and sections - are repeated in the header for double-sided layout\,---\,with {\KOMAScript} - on the outer side, with the standard classes on the inner side. The page - number is set on the outer side of the footer with {\KOMAScript}; with the - standard classes it is set on the inner side of the header. In one-sided - layouts only the titles of the chapters are used and are, with - {\KOMAScript}, centered in the header. The page numbers are set centered in - the footer with {\KOMAScript}. +\item[{\PageStyle{empty}% + \BeginIndex[indexmain]{Pagestyle}{empty}\LabelPageStyle{empty}}] is the + page style with completely empty headers and footers. In {\KOMAScript} + this is identical to the standard classes.% +\item[{\PageStyle{headings}% + \BeginIndex[indexmain]{Pagestyle}{headings}\LabelPageStyle{headings}}] is + the page style with running heads in the header. In this style, headings are + automatically\Index[indexmain]{running heads>automatic} inserted into the + header. \OnlyAt{\Class{scrbook}\and\Class{scrreprt}}% + With the classes \Class{scrbook}\IndexClass{scrbook} and + \Class{scrreprt}\IndexClass{scrreprt}, the headings of chapters and sections + are repeated in the header for two-sided printing\,---\,on the outer side + with {\KOMAScript}\textnote{\KOMAScript{} vs. standard classes}, on the + inner side with the standard classes. {\KOMAScript} puts the page number on + the outer side of the footer; the standard classes put it on the inner side + of the header. In one-sided printing, {\KOMAScript} uses only the chapter + headings, which are centred in the header, and puts the page numbers centred + in the footer. \OnlyAt{\Class{scrartcl}}\Class{scrartcl}\IndexClass{scrartcl} behaves - similarly, but starting a level deeper in the section hierarchy with + similarly but starts one a level deeper in the sectioning hierarchy, with sections and subsections, because the chapter level does not exist in this case. - While the standard classes automatically set running headings always - in capitals, {\KOMAScript} applies the style of the title. This has - several typographic reasons. Capitals as a decoration are actually - far too strong. If one applies them nevertheless, they should be set - in a one point smaller type size and with tighter spacing. The - standard classes do not take these points into consideration. - - Beyond this {\KOMAScript} classes support rules below the head and above the - foot using options \DescRef{\LabelBase.option.headsepline} and - \DescRef{\LabelBase.option.footsepline} which are described above. -\item[myheadings\BeginIndex{Pagestyle}{myheadings}\LabelPageStyle{myheadings}] - corresponds mostly to the page style \PValue{headings}, but the running - headings are not automatically produced\,---\,they have to be defined by the - user. The commands \Macro {markboth}\IndexCmd{markboth} and - \DescRef{\LabelBase.cmd.markright}\IndexCmd{markright} can be used for that - purpose (see below). -\item[plain\BeginIndex{Pagestyle}{plain}\LabelPageStyle{plain}] is the page - style with empty header and only a page number in the footer. With the - standard classes this page number is always centered in the footer. With - {\KOMAScript} the page number appears on double-sided\Index {double-sided} - layout on the outer side of the footer. The one-sided page style behaves - like the standard setup. + While the standard classes\textnote{\KOMAScript{} vs. standard classes} + automatically convert the running heads to upper-case letters, + {\KOMAScript} uses the capitalisation found in the headings. There are + several typographical reasons for this. Upper-case letters are actually far + too massive as a text decoration. If you use them anyway, they should be set + one point smaller and with slightly tighter spacing. The standard classes do + not take these points into consideration. + + In addition, the {\KOMAScript} classes support rules below the header and + above the footer with the \DescRef{\LabelBase.option.headsepline} and + \DescRef{\LabelBase.option.footsepline} options (see + \DescPageRef{\LabelBase.option.headsepline}).% +\item[{\PageStyle{myheadings}% + \BeginIndex[indexmain]{Pagestyle}{myheadings}\LabelPageStyle{myheadings}}] + mostly corresponds to the \PValue{headings} page style, but the running + heads are not generated automatically% + \Index[indexmain]{running heads>manual}\,---\,they have to be defined by the + user. You can use the \DescRef{\LabelBase.cmd.markboth}\IndexCmd{markboth} + and \DescRef{\LabelBase.cmd.markright}\IndexCmd{markright}\important{% + \DescRef{\LabelBase.cmd.markboth}\\ + \DescRef{\LabelBase.cmd.markright}} commands for that purpose (see + \DescPageRef{\LabelBase.cmd.markright}). +\item[{\PageStyle{plain}% + \BeginIndex[indexmain]{Pagestyle}{plain}\LabelPageStyle{plain}}] is the + page style with no running head\Index{running head} and only a page number% + \Index{page>number} in the footer. The\textnote{\KOMAScript{} vs. standard + classes} standard classes always centre this page number in the footer. + {\KOMAScript} puts the page number on the outer side of the footer in + two-sided\Index{two-sided} mode. {\KOMAScript} behaves like the + standard classes in one-sided printing.% \end{description} -The page style can be set at any time with the help of the \Macro{pagestyle} -command and takes effect with the next page that is output. If\textnote{Hint!} -one uses \Macro{pagestyle} just before a command, that results in an implicit -page break and if the new page style should be used at the resulting new page -first, a \DescRef{\LabelBase.cmd.cleardoublepage} just before -\Macro{pagestyle} will be useful. But usually one sets the page style only -once at the beginning of the document or in the preamble. +You\important{\Macro{pagestyle}} can set the page style at any time with the +help of the \Macro{pagestyle} command, and this setting takes effect with the +next page that is output. If\textnote{Hint!} you use \Macro{pagestyle} just +before a command that results in an implicit page break and if the new page +style should be used on the resulting new page, a +\DescRef{\LabelBase.cmd.cleardoublepage} just before \Macro{pagestyle} will be +useful. But usually you set the page style only once, at the beginning of the +document or in the preamble. To\important{\Macro{thispagestyle}} change the page style of the current page -only, one uses the \Macro{thispagestyle} command. This also happens -automatically at some places in the document. For example, the instruction -\Macro{thispagestyle}\PParameter{\DescRef{\LabelBase.cmd.chapterpagestyle}} is issued -implicitly on the first page of a chapter. - -Please\textnote{Attention!} note that the change between automatic and manual -running headings is no longer performed by page style changes when using the -\Package{scrlayer-scrpage} package, but instead via special instructions. The -page styles \PValue{headings} and \PValue{myheadings} should not be used -together with this package.% -% - -\BeginIndexGroup -\BeginIndex[indexother]{}{font>style}% +only, use the \Macro{thispagestyle} command. This occurs automatically at some +points in the document. For example, the +\Macro{thispagestyle}\PParameter{\DescRef{\LabelBase.cmd.chapterpagestyle}} +command is issued implicitly on the first page of a chapter. + +Note\textnote{Attention!} that when you use the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} +package, switching between automatic and manual running heads is no longer +accomplished by changing the page styles but with special instructions. You +should not use the \PValue{headings} and \PValue{myheadings} page styles with +this package. + +\BeginIndexGroup \BeginIndex[indexother]{}{font>style}% \BeginIndex{FontElement}{pageheadfoot}\LabelFontElement{pageheadfoot}% +\LabelFontElement{pagehead}% \BeginIndex{FontElement}{pagefoot}\LabelFontElement{pagefoot}% \BeginIndex{FontElement}{pagenumber}\LabelFontElement{pagenumber}% -In order to change the font style used in the header, footer, or for the page -number\ChangedAt{v2.8p}{% - \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% -, please use the interface described in \autoref{sec:\LabelBase.textmarkup}, -\DescPageRef{\LabelBase.cmd.setkomafont}. The same element is used for header -and footer, which you can designate with -\FontElement{pageheadfoot}\important{\FontElement{pageheadfoot}}. The element -for the page number within the header or footer is called -\FontElement{pagenumber}\important{\FontElement{pagenumber}}. The element -\FontElement{pagefoot}, that is additionally supported by the \KOMAScript{} -classes, will be used only if a page style has been defined that has text at -the foot line, using package -\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} (see +To change the font style used for the header, the footer, or the page +number\ChangedAt{v2.8p}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}, use the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see +\autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}). The same element, +\FontElement{pageheadfoot}\IndexFontElement{pageheadfoot}% +\important{\FontElement{pageheadfoot}}, is used for the header and the footer. +The element for the page number within the header or footer is called +\FontElement{pagenumber}\IndexFontElement{pagenumber}% +\important{\FontElement{pagenumber}}. The +\FontElement{pagefoot}\IndexFontElement{pagefoot}% +\important{\FontElement{pagefoot}} element, which is also provided by the +\KOMAScript{} classes, is used only if you define a page style with the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage} package in which the footer contains text (see \autoref{cha:scrlayer-scrpage}, \DescPageRef{scrlayer-scrpage.fontelement.pagefoot}). -The default settings can be found in -\autoref{tab:\LabelBase.defaultFontsHeadFoot}.% +You can find the default settings in +\autoref{tab:\LabelBase.defaultFontsHeadFoot}. % \begin{table} % \centering% +% \caption \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% -% \caption +% \addtokomafont{caption}{\raggedright}% \begin{captionbeside} - [{Default values for the elements of a page style}] - {\label{tab:\LabelBase.defaultFontsHeadFoot}% - Default values for the elements of a page style} + [{Default values for page style elements}] + {\label{tab:maincls.defaultFontsHeadFoot}% + \hspace{0pt plus 1ex}% + Default values for page style elements} [l] \begin{tabular}[t]{ll} \toprule - Element & Default value \\ + Element & Default \\ \midrule - \DescRef{\LabelBase.fontelement.pagefoot}\IndexFontElement{pagefoot} & + \FontElement{pagefoot}\IndexFontElement{pagefoot} & \\ - \DescRef{\LabelBase.fontelement.pageheadfoot}\IndexFontElement{pagefoothead} & + \FontElement{pageheadfoot}\IndexFontElement{pageheadfoot} & \Macro{normalfont}\Macro{normalcolor}\Macro{slshape} \\ - \DescRef{\LabelBase.fontelement.pagenumber}\IndexFontElement{pagenumber} & + \FontElement{pagenumber}\IndexFontElement{pagenumber} & \Macro{normalfont}\Macro{normalcolor}\\ \bottomrule \end{tabular} @@ -782,133 +878,143 @@ The default settings can be found in % \begin{Example} \leavevmode\phantomsection\xmpllabel{cmd.pagestyle}% - Assume that you want to set header and footer in a smaller type size + Suppose you want to set header and footer in a smaller type size and in italics. However, the page number should not be set in - italics but bold. Apart from the fact that the result will look - horrible, you can obtain this as follows: + italics but in bold. Apart from the fact that the result will look + horrible, you can do this as follows: \begin{lstcode} \setkomafont{pageheadfoot}{% - \normalfont\normalcolor\itshape\small - } + \normalfont\normalcolor\itshape\small} \setkomafont{pagenumber}{\normalfont\bfseries} \end{lstcode} - If you want only that, in addition to the default slanted variant, a smaller - type size is used, it is sufficient to use the following: + On the other hand, if you only want a smaller font to be used along with the + default slanted text, you can use the following: \begin{lstcode} \addtokomafont{pagehead}{\small} \end{lstcode} - As you can see, the last example uses the element - \FontElement{pagehead}\important{\FontElement{pagehead}}. You can achieve - the same result using \PValue{pageheadfoot} instead (see + As you can see, the previous example uses the + \FontElement{pagehead}\important{\FontElement{pagehead}} element. You can + achieve the same result using \PValue{pageheadfoot} instead (see \autoref{tab:\LabelBase.fontelements} on \autopageref{tab:\LabelBase.fontelements}). \end{Example} -It is not possible to use these methods to force capitals to be used -automatically for the running headings. For that, please use the -\Package{scrlayer-scrpage} package (see \autoref{cha:scrlayer-scrpage}, +It is not possible to use these methods to force upper-case letters to be used +automatically for the running heads. Although you can redefine +\DescRef{tocbasic.cmd.MakeMarkcase}\IndexCmd{MakeMarkcase}, in such cases you +should instead use the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} package (see +\autoref{cha:scrlayer-scrpage}, \DescPageRef{scrlayer-scrpage.option.markcase}). -If you define your own page styles, the commands +If\textnote{Hint!} you define your own page styles, the commands \DescRef{\LabelBase.cmd.usekomafont}\PParameter{pageheadfoot}, -\DescRef{\LabelBase.cmd.usekomafont}\PParameter {pagenumber}, and -\DescRef{\LabelBase.cmd.usekomafont}\PParameter{pagefoot} can be useful. If -you do not use the {\KOMAScript} package \Package{scrlayer-scrpage} (see -\autoref{cha:scrlayer-scrpage}) for that, but, for example, the package -\Package{fancyhdr}\IndexPackage{fancyhdr} (see \cite{package:fancyhdr}), you -can use these commands in your definitions. Thereby you can remain compatible -with {\KOMAScript} as much as possible. If you do not use these commands in -your own definitions, changes like those shown in the previous examples have -no effect. The package -\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} takes care to keep -the maximum possible compatibility with other packages itself. -% +\DescRef{\LabelBase.cmd.usekomafont}\PParameter{pagenumber}, and +\DescRef{\LabelBase.cmd.usekomafont}\PParameter{pagefoot} can be useful. In +particular, if you do not use the {\KOMAScript} package +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} (see +\autoref{cha:scrlayer-scrpage}) but use, for example, the +\Package{fancyhdr}\IndexPackage{fancyhdr}\important{\Package{fancyhdr}} +package (see \cite{package:fancyhdr}), you can use these commands in your +definitions. In this way you can maintain compatibility with {\KOMAScript} as +much as possible. If you do not use these commands in your own definitions, +changes such as those shown in the previous examples have no effect. The +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage} package tries to maintain maximum +compatibility as long as, for example, +\iffree{\Macro{thepage}}{\DescRef{\LabelBase-experts.cmd.thepage}}% +\IndexCmd{thepage} is not used directly for the page number rather than the +\iffree{\Macro{pagemark}}{\DescRef{\LabelBase-experts.cmd.pagemark}}% +\IndexCmd{pagemark} which is provided for it.% \EndIndexGroup % \EndIndexGroup \begin{Declaration} - \Macro{markboth}\Parameter{left mark}\Parameter{right mark}% + \Macro{markboth}\Parameter{left mark}\Parameter{right mark} \Macro{markright}\Parameter{right mark} \end{Declaration} -\BeginIndex{Pagestyle}{headings}% -\BeginIndex{Pagestyle}{myheadings}% -With page style \PageStyle{myheadings}\important{\PageStyle{myheadings}}% -\IndexPagestyle{myheadings}, there's no automatic setting of the running head. -Instead of this one would set it with the help of commands \Macro{markboth} -and \Macro{markright}. Thereby \PName{left mark} normally will be used at the -head of even pages and \PName{right mark} at the heads of odd pages. With -one-sided printing, only the \PName{right mark} exists. Using package -\Package{scrlayer-scrpage}% -\IndexPackage{scrlayer-scrpage}\important{\Package{scrlayer-scrpage}}, the -additional command \DescRef{scrlayer-scrpage.cmd.markleft}% -\IndexCmd{markleft}\important{\DescRef{scrlayer-scrpage.cmd.markleft}} exists. - -The commands may be used with other page styles too. Combination with automatic -running head, e.\,g., with page style \PageStyle{headings}, limits the effect -of the commands until the next automatic setting of the corresponding marks.% +The \DescRef{\LabelBase.pagestyle.myheadings}% +\important{\DescRef{\LabelBase.pagestyle.myheadings}}% +\IndexPagestyle{myheadings} page style does not set the running head. Instead, +you set it with the help of the \Macro{markboth} and \Macro{markright} +commands. This way the \PName{left mark} will normally be used in the header +of even pages and \PName{right mark} in the header of odd pages. With +one-sided printing, only the \PName{right mark} exists. With the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} +package, the \DescRef{scrlayer-scrpage.cmd.markleft}% +\IndexCmd{markleft}\important{\DescRef{scrlayer-scrpage.cmd.markleft}} command +is also available. + +You can use these commands with other page styles too. However, when combined +with automatic running heads, for example with the +\DescRef{\LabelBase.pagestyle.headings}\IndexPagestyle{headings} page style, +the effect of the commands lasts only until the next time the respective marks +are set automatically.% % \EndIndexGroup - \begin{Declaration} - \Macro{titlepagestyle}% - \Macro{partpagestyle}% - \Macro{chapterpagestyle}% + \Macro{titlepagestyle} + \Macro{partpagestyle} + \Macro{chapterpagestyle} \Macro{indexpagestyle} \end{Declaration}% \Index{title>page style}% \Index{part>page style}% \Index{chapter>page style}% \Index{index>page style}% -For some pages, a different page style is chosen with the help of the command -\DescRef{\LabelBase.cmd.thispagestyle}. Which page style this actually is, is -defined by these four macros, of which \Macro{partpagestyle} and -\Macro{chapterpagestyle}\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} are found -only with classes \Class{scrbook} and \Class{scrreprt}, but not in -\Class{scrartcl}. The default value for all four cases is \PValue{plain}. The -meaning of these macros can be taken from \autoref{tab:specialpagestyles}. +On some pages, a different page style is chosen automatically with the help of +the \DescRef{\LabelBase.cmd.thispagestyle} command. Which page style this +actually is, is defined by these four macros, of which \Macro{partpagestyle} +and \Macro{chapterpagestyle}\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} are +found only with classes \Class{scrbook} and \Class{scrreprt}, and not in +\Class{scrartcl}. The default value for all four cases is +\DescRef{\LabelBase.pagestyle.plain}\IndexPagestyle{plain}. You can find the +meaning of these macros in \autoref{tab:specialpagestyles}. % \begin{table} \centering - \caption{Macros to set up page style of special pages} + \caption{Macros to set up the page style of special pages} \label{tab:specialpagestyles} \begin{desctabular} \mentry{titlepagestyle}{Page style for a title page when using \emph{in-page} titles.}% - \mentry{partpagestyle}{Page style for the pages with \DescRef{\LabelBase.cmd.part} - titles.}% + \mentry{partpagestyle}{Page style for pages with + \DescRef{\LabelBase.cmd.part} titles.}% \mentry{chapterpagestyle}{Page style for the first page of a chapter.}% \mentry{indexpagestyle}{Page style for the first page of the index.}% \end{desctabular} \end{table} % -The page styles can be redefined with the \Macro{renewcommand} macro. +You can redefine the page styles with the \Macro{renewcommand} macro. \begin{Example} - Assume that you want the pages with a \DescRef{\LabelBase.cmd.part} heading to have - no number. Then you can use the following command, for example in - the preamble of your document: + Suppose you do not want the pages with a \DescRef{\LabelBase.cmd.part} + heading to be numbered. You can use the following command in the preamble of + your document: \begin{lstcode} \renewcommand*{\partpagestyle}{empty} \end{lstcode} As mentioned previously on \DescPageRef{\LabelBase.pagestyle.empty}, - the page style \PValue{empty} is exactly what is required in this - example. Naturally you can also use a user-defined page style. - - Assume you have defined your own page style for initial chapter pages - with the package \Package{scrlayer-scrpage} (see - \autoref{cha:scrlayer-scrpage}). You have given to this page style the - fitting name \PValue{chapter}. To actually use this style, you must - redefine the macro \Macro{chapterpagestyle} accordingly: + the \PValue{empty} page style is exactly what is required in this + example. Of course, you can also use a user-defined page style. + + Suppose you have defined your own page style for initial chapter pages + with the \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} package + (see \autoref{cha:scrlayer-scrpage}). You have given this page style the + fitting name of \PValue{chapter}. To actually use this style, you must + redefine \Macro{chapterpagestyle} in this way: \begin{lstcode} \renewcommand*{\chapterpagestyle}{chapter} \end{lstcode} - - Assume that you want the table of contents\Index{table of - contents}\textnote{table of contents} of a book to have no page - numbers. However, everything after the table of contents should work again - with the page style \PValue{headings}, as well as with \PValue{plain} on - every first page of a chapter. You can use the following commands: + + Suppose you do not want the table of contents\Index{table of contents}% + \textnote{table of contents} of a book to have page numbers. Everything + after the table of contents, however, should use the \PValue{headings} + page style, including the \PValue{plain} page style for the first + page of every chapter. You can use the following: \begin{lstcode} \clearpage \pagestyle{empty} @@ -918,33 +1024,50 @@ The page styles can be redefined with the \Macro{renewcommand} macro. \pagestyle{headings} \renewcommand*{\chapterpagestyle}{plain} \end{lstcode} - Instead of the above you may do a local redefinition using a group. The - advantage will be that you do not need to know the current page style before - the change to switch back at the end. + You can also keep the redefinition local by using a group. This method has + the advantage that you do not need to make any assumptions about the what + the previous page style was in order to restore it after your local change: \begin{lstcode} \clearpage \begingroup - \pagestyle{empty} - \renewcommand*{\chapterpagestyle}{empty} - \tableofcontents - \clearpage + \pagestyle{empty} + \renewcommand*{\chapterpagestyle}{empty} + \tableofcontents + \clearpage \endgroup \end{lstcode} + Note,\important{Attention!} however, that you never should put a numbered + sectioning command into a group. Otherwise you may get unpredictable results + with commands like \Macro{label}. - But\important{Attention!} notice that you never should put a numbered head - into a group. Otherwise you may get funny results with commands like - \Macro{label}. + On \DescPageRef{tocbasic.cmd.AfterTOCHead} in \autoref{sec:tocbasic.toc}, + you will discover the \DescRef{tocbasic.cmd.AfterTOCHead} command, which + makes a solution even easier: +\begin{lstcode} + \AfterTOCHead[toc]{% + \thispagestyle{empty}% + \pagestyle{empty}% + } +\end{lstcode}% + This takes advantage of the fact that if there are several + \DescRef{\LabelBase.cmd.thispagestyle} commands on the same page, the last + one always wins. \end{Example} \begin{Explain} - Whoever thinks that it is possible to put running headings on the - first page of a chapter by using the command + You might think that you can put running heads on the first page of a + chapter simply by using the \begin{lstcode} \renewcommand*{\chapterpagestyle}{headings} \end{lstcode} - should read more about the background of \Macro{rightmark} at - \autoref{sec:maincls-experts.addInfos}, - \DescPageRef{maincls-experts.cmd.rightmark}. + command. Before you try this, you should read \iffree{}{more about the + background to \DescRef{maincls-experts.cmd.rightmark} in + \autoref{sec:maincls-experts.addInfos} on + \DescPageRef{maincls-experts.cmd.rightmark}. Also, }the remarks on + \DescRef{scrlayer-scrpage-experts.cmd.rightfirstmark} starting on page + \DescPageRef{scrlayer-scrpage-experts.cmd.rightfirstmark} in + \autoref{cha:scrlayer-scrpage-experts}, \autoref{part:forExperts} + \iffree{}{provide important information}.% \end{Explain} % \EndIndexGroup @@ -953,27 +1076,24 @@ The page styles can be redefined with the \Macro{renewcommand} macro. \begin{Declaration} \Macro{pagenumbering}\Parameter{numbering style} \end{Declaration} -This command works the same way in {\KOMAScript} as in the standard -classes. More precisely it is a feature neither of the standard classes nor of -the \KOMAScript{} classes but of the {\LaTeX} kernel. You can specify with -this command the \PName{numbering style} of page numbers. - -The changes take effect immediately, hence starting with the -page that contains the command. It is recommended to use -\DescRef{\LabelBase.cmd.cleardoubleoddpage} to close the last page and start a new odd page -before. The possible settings can be found in -\autoref{tab:numberKind}. - -Using\textnote{Attention!} the command \Macro{pagenumbering} also resets the -page counter\Index{page>counter}\Index{page>number}. Thus the page number of -the next page which {\TeX} outputs will have the number 1 in the style -\PName{numbering style}. +This command works the same way in {\KOMAScript} as in the standard classes. +Strictly speaking, it is a feature of neither the standard classes nor the +\KOMAScript{} classes but of the {\LaTeX} kernel. This command is used to +change the \PName{numbering style} of page numbers. + +The changes take effect immediately, i.\,e., starting from the page that +contains the command. If necessary, you should first close the current page +with \DescRef{\LabelBase.cmd.clearpage} or better +\DescRef{\LabelBase.cmd.cleardoubleoddpage}% +\important{\DescRef{\LabelBase.cmd.cleardoubleoddpage}}% +\IndexCmd{cleardoubleoddpage}. You can find the available settings for +\PName{numbering style} in \autoref{tab:numberKind}. % \begin{table} -% \centering + % \centering \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% -% \caption + % \caption \begin{captionbeside} {\label{tab:numberKind}% Available numbering styles of page numbers} @@ -990,9 +1110,91 @@ the next page which {\TeX} outputs will have the number 1 in the style \end{tabular} \end{captionbeside} \end{table} -% + +Calling\textnote{Attention!} \Macro{pagenumbering} always resets the page +number\Index{page>number}. The current page becomes number 1 in the selected +\PName{numbering style}. In order that two-sided documents produce the correct +results on an even page, so that the left-hand page is not missing, you should +always add \DescRef{\LabelBase.cmd.cleardoubleoddpage}% +\important{\DescRef{\LabelBase.cmd.cleardoubleoddpage}}% +\IndexCmd{cleardoubleoddpage} before \Macro{pagenumbering}. The next section +provides more information about potentially inserted blank pages. + +\begin{Explain} + Let me say a word about a common mistake found in various templates + circulating on the Internet. If you encounter lines like the + following\,---\,without the initial comment naturally\,---\,this is an + unmistakable sign that the creator did not read or understand the + remark above: +\begin{lstcode} + % Attention! This example contains errors! + % Please note the explanation in the text! + \tableofcontents + \pagenumbering{arabic} + \setcounter{page}{1} +\end{lstcode} + Since \DescRef{\LabelBase.cmd.tableofcontents} outputs the table of contents + but does not automatically issue a page break at the end, the page numbering + is already changed on the last page of the table of contents. Because it + lacks a \DescRef{\LabelBase.cmd.cleardoubleoddpage} command before + \Macro{pagenumbering}, it receives a pagination of the Arabic number 1. + Additionally, the final line which sets the page numbering to 1 is + superfluous, since this is already done by \Macro{pagenumbering}. + + Sometimes\,---\,without the initial comment, naturally\,---\, you find: +\begin{lstcode} + % Attention! This example contains errors! + % Please note the explanation in the text! + \tableofcontents + \pagebreak + \pagenumbering{arabic} + \setcounter{page}{1} +\end{lstcode} + Here the creator tried to solve the problem with the final page of the table + of contents with the help of \Macro{pagebreak}\IndexCmd{pagebreak}. + + Unfortunately, this solution is not much better. Here there is a page break + after the last page of the table of contents. This may cause entries on the + last page of a two-sided document to have excess vertical spacing (see + \DescRef{\LabelBase.cmd.flushbottom}, + \DescPageRef{\LabelBase.cmd.flushbottom}). \Macro{pagebreak} is clearly + the wrong command here. + + Furthermore, \Macro{newpage}\IndexCmd{newpage} or + \DescRef{\LabelBase.cmd.clearpage} would not be sufficient for a two-sided + document. For example, if the last page of the table of contents had the + Roman numeral vii, the Arabic numbered right-side page 1 would immediately + follow the Roman numeral right-side page. A left-side page between the two + would be missing, which could cause serious problems with later printing. + + My advice: Avoid using templates that contain errors with respect to such + simple things. Incidentally, the correct way would be: +\begin{lstcode} + \tableofcontents + \cleardoubleoddpage + \pagenumbering{arabic} +\end{lstcode} + This also applies if \Class{scrartcl}\OnlyAt{\Class{scrartcl}} uses a class + that usually does not start a new page after the table of contents. If you + switch the page numbering, a new right-hand page must be started. If you do + not want such a change, you should keep the numbering style of pages + consistent throughout the document without changing it in between. +\iffalse% Umbruchkorrekturtext + For articles or other short documents, this is generally recommended. +\fi + + It is easier to change the numbering style when using + \Class{scrbook}\OnlyAt{\Class{scrbook}}. There you have the support of two + commands, \DescRef{\LabelBase.cmd.frontmatter}% + \important{\DescRef{\LabelBase.cmd.frontmatter}\\ + \DescRef{\LabelBase.cmd.mainmatter}}% + \IndexCmd{fontmatter} and \DescRef{\LabelBase.cmd.mainmatter}% + \IndexCmd{mainmatter}, for the most commonly used switching. For more + information, please see + \autoref{sec:maincls.separation}, + \DescPageRef{\LabelBase.cmd.mainmatter}.% +\end{Explain}% \EndIndexGroup -% \EndIndexGroup @@ -1000,126 +1202,130 @@ the next page which {\TeX} outputs will have the number 1 in the style \LoadCommonFile{footnotes}% \section{Footnotes} - -\section[Demarcation]{Demarcation\protect\OnlyAt{\Class{scrbook}}} +\section[Book Structure]{Book Structure\protect\OnlyAt{\Class{scrbook}}} \seclabel{separation} -\BeginIndexGroup -\BeginIndex{}{front matter}% -\BeginIndex{}{main matter}% -\BeginIndex{}{back matter}% -\BeginIndex{}{matter>front}% -\BeginIndex{}{matter>main}% -\BeginIndex{}{matter>back}% -Sometimes books are roughly separated into front matter, main matter, and -back matter. \KOMAScript{} provides this for \Class{scrbook} also. +Sometimes books are loosely divided into \emph{front matter}% +\Index{front matter}, \emph{main matter}\Index{main matter}, and +\emph{back matter}\Index{back matter}. \KOMAScript{} also provides this +capability for \Class{scrbook}. + \begin{Declaration} - \Macro{frontmatter}% - \Macro{mainmatter}% + \Macro{frontmatter} + \Macro{mainmatter} \Macro{backmatter} \end{Declaration}% -The macro \Macro{frontmatter}\important{\Macro{frontmatter}} introduces the -front matter in which roman numerals are used for the page numbers. Chapter -headings in a front matter are not numbered. The section titles which would be -numbered start at chapter 0, and would be consecutively numbered across -chapter boundaries. However, this is of no import, as the front matter is used -only for the title pages, table of contents\Index{table of contents}, lists of -figures\Index{list of>figures}\Index{figures>list of} and -tables\Index{tables>list of}, and a foreword\Index{foreword}. The foreword can -thus be set as a normal chapter. A foreword should never be divided into -sections but kept as short as possible. Therefore, in the foreword there is no -need for a deeper structuring than the chapter level. - -In case the user sees things differently and wishes to use numbered +The front matter includes all the material which appears before the main +text begins, including title pages, preface, and table of contents. It is +initiated with +\Macro{frontmatter}\important{\Macro{frontmatter}}. In the front matter, +Roman numerals are used for the page numbers, and chapter headings in +the header are not numbered. However, section headings are numbered +consecutively, starting from chapter 0. This typically does not matter, as the +front matter is used only for the title pages, table of contents% +\Index{table of contents}, lists of figures\Index{list of>figures}% +\Index{figures>list of} and tables\Index{tables>list of}, and a +preface\Index{preface} or foreword\Index{foreword}. The preface can thus be +created as a normal chapter. A preface should be as short as possible and +never divided into sections. The preface thus does not require a deeper level +of structure than the chapter. + +If you see things differently and want to use numbered sections\Index{section>number} in the chapters of the front matter, as of -version~2.97e\ChangedAt{v2.97e}{\Class{scrbook}}% +version~2.97e,\ChangedAt{v2.97e}{\Class{scrbook}}% \important{\OptionValueRef{\LabelBase}{version}{2.97e}} the section numbering no longer contains the chapter number. This change only takes effect when the compatibility option is set to at least version~2.97e (see option \DescRef{\LabelBase.option.version}, \autoref{sec:\LabelBase.compatibilityOptions}, -\DescPageRef{\LabelBase.option.version}). It is explicity noted that this -creates a confusion with chapter numbers! The use of \DescRef{\LabelBase.cmd.addsec} and -\DescRef{\LabelBase.cmd.section*} (see \autoref{sec:\LabelBase.structure}, -\DescPageRef{\LabelBase.cmd.section*} and \DescPageRef{\LabelBase.cmd.addsec}) -are thus, in the author's opinion, far more preferable. - -As of version~2.97e\ChangedAt{v2.97e}{\Class{scrbook}} the numbering of float -environments, such as tables\Index{table>number} and +\DescPageRef{\LabelBase.option.version}). It is explicitly noted that this +creates confusion with chapter numbers! The use of +\DescRef{\LabelBase.cmd.addsec} and \DescRef{\LabelBase.cmd.section*} (see +\autoref{sec:\LabelBase.structure}, \DescPageRef{\LabelBase.cmd.section*} and +\DescPageRef{\LabelBase.cmd.addsec}) are thus, in the author's opinion, +greatly preferable. + +As of version~2.97e\ChangedAt{v2.97e}{\Class{scrbook}} the numbering of +floating environments, such as tables\Index{table>number} and figures\Index{figure>number}, and equation numbers\Index{equation>number} in -the front matter also contain no chapter number part. To take effect this too -requires the corresponding compatibility setting (see option -\DescRef{\LabelBase.option.version}, +the front matter also contains no chapter-number part. To take effect, this +too requires the corresponding compatibility setting (see the +\DescRef{\LabelBase.option.version} option, \autoref{sec:\LabelBase.compatibilityOptions}, \DescPageRef{\LabelBase.option.version}). -\Macro{mainmatter}\important{\Macro{mainmatter}} introduces the main matter -with the main text. If there is no front matter, then this command can be -omitted. The default page numbering in the main matter uses Arabic numerals -(re)starting in the main matter at 1. +The part of the book with the main text is introduced +with \Macro{mainmatter}\important{\Macro{mainmatter}}. If there is no front +matter, you can omit this command. The default page numbering in the main +matter uses Arabic numerals and (re)starts the page count at 1 at the start of +the main matter. The back matter is introduced with -\Macro{backmatter}\important{\Macro{backmatter}}. Opinions differ in what -should be part of the back matter. So in some cases you will find only the +\Macro{backmatter}\important{\Macro{backmatter}}. Opinions differ as to what +belongs in the back matter. So in some cases you will find only the bibliography\Index{bibliography}, in some cases only the index\Index{index}, -and in other cases both of these as well as the appendices. The chapters in +and in other cases both of these as well as the appendices. The chapters in the back matter are similar to the chapters in the front matter, but page -numbering is not reset. If you do require separate page numbering you may use -the command \DescRef{\LabelBase.cmd.pagenumbering} from +numbering is not reset. If you do require separate page numbering, you can use +the \DescRef{\LabelBase.cmd.pagenumbering}% +\important{\DescRef{\LabelBase.cmd.pagenumbering}} command in \autoref{sec:\LabelBase.pagestyle}, -\DescPageRef{\LabelBase.cmd.pagenumbering}. -% -\EndIndexGroup +\DescPageRef{\LabelBase.cmd.pagenumbering}.% % \EndIndexGroup -\section{Structuring of Documents} -\seclabel{structure} +\section{Document Structure} +\seclabel{structure}% +\BeginIndexGroup +\BeginIndex{}{document structure} + +The structure refers to dividing a document into parts, chapters, sections, +and additional levels of structure. -Structuring of documents means to divide them into parts, chapters, sections, -and several other structural elements. \begin{Declaration} - \OptionVName{open}{method} + \OptionVName{open}{method} \end{Declaration}% -\OnlyAt{\Class{scrbook}\and\Class{scrreprt}}% -\KOMAScript{} classes \Class{scrbook} and \Class{scrreprt} give you the choice -of where to start\Index{chapter>start} a new chapter with double-sided -printing. By default \Class{scrreprt} starts a new chapter at the next -page. This is like \PName{method} \PValue{any}. However, \Class{scrbook} -starts new chapters at the next right-hand page. This is like \PName{method} -\PValue{right} and is usually used in books. But sometimes chapters should -start at the left-hand page of a double-page spread. This would be -accomplished with \PName{method} -\PValue{left}\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}}. An -overview of the supported methods may be found at -\autoref{tab:\LabelBase.open}. The table also describes the effect on -\DescRef{\LabelBase.cmd.cleardoublepage}, \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, -\DescRef{\LabelBase.cmd.cleardoublestandardpage}, \DescRef{\LabelBase.cmd.cleardoubleplainpage}, and -\DescRef{\LabelBase.cmd.cleardoubleemptypage} (see \autoref{sec:\LabelBase.emptypage}, +The\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} \KOMAScript{} classes +\Class{scrbook} and \Class{scrreprt} give you the choice of where to start a +new chapter with two-sided printing. By default \Class{scrreprt} starts a new +chapter\Index{chapter>start} on the next page. This is equivalent to +\PName{method} \PValue{any}. However, \Class{scrbook} starts new chapters at +the next right-hand page. This is equivalent to \PName{method} \PValue{right} +and is usually used in books. But sometimes chapters should start on the +left-hand page of a two-page spread. You can accomplish this with the +\PName{method} \PValue{left}\ChangedAt{v3.00}{\Class{scrbook}\and + \Class{scrreprt}}. You can find a summary of the available values in +\autoref{tab:\LabelBase.open}. The table also describes the effects of +\DescRef{\LabelBase.cmd.cleardoublepage}, +\DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, +\DescRef{\LabelBase.cmd.cleardoublestandardpage}, +\DescRef{\LabelBase.cmd.cleardoubleplainpage}, and +\DescRef{\LabelBase.cmd.cleardoubleemptypage} (see +\autoref{sec:\LabelBase.emptypage}, \DescPageRef{\LabelBase.cmd.cleardoublepage}). \begin{table} - \caption[{Available values for option \Option{open}}]{Available values for - option \Option{open} to select page breaks with interleaf pages using - \Class{scrbook} or \Class{scrreprt}} + \caption[{Available values for the \Option{open} option}]{Available values + for the \Option{open} option to select page breaks with interleaf pages + using \Class{scrbook} or \Class{scrreprt}} \begin{desctabular} \pventry{any}{% Parts, chapter, index, and back matter use - \DescRef{\LabelBase.cmd.clearpage} instead of - \DescRef{\LabelBase.cmd.cleardoublepage};% + \DescRef{\LabelBase.cmd.clearpage}, not + \DescRef{\LabelBase.cmd.cleardoublepage}; \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, \DescRef{\LabelBase.cmd.cleardoublestandardpage}, \DescRef{\LabelBase.cmd.cleardoubleplainpage}, \DescRef{\LabelBase.cmd.cleardoubleemptypage}, and - \DescRef{\LabelBase.cmd.cleardoublepage} behaves same like using + \DescRef{\LabelBase.cmd.cleardoublepage} behave the same as using \OptionValue{open}{right}.% - \IndexOption{open~=\PValue{any}}}% + \IndexOption{open~=\textKValue{any}}}% \pventry{left}{% - Part, chapter, index and back matter use - \DescRef{\LabelBase.cmd.cleardoublepage};% + Part, chapter, index, and back matter use + \DescRef{\LabelBase.cmd.cleardoublepage}; the commands \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, \DescRef{\LabelBase.cmd.cleardoublestandardpage}, \DescRef{\LabelBase.cmd.cleardoubleplainpage}, @@ -1127,10 +1333,10 @@ overview of the supported methods may be found at \DescRef{\LabelBase.cmd.cleardoublepage} result in a page break and add an interleaf page\Index{page>interleaf} if needed to reach the next left-hand page.% - \IndexOption{open~=\PValue{left}}}% + \IndexOption{open~=\textKValue{left}}}% \pventry{right}{% - Part, chapter, index and back matter use - \DescRef{\LabelBase.cmd.cleardoublepage};% + Part, chapter, index, and back matter use + \DescRef{\LabelBase.cmd.cleardoublepage}; the commands \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, \DescRef{\LabelBase.cmd.cleardoublestandardpage}, \DescRef{\LabelBase.cmd.cleardoubleplainpage}, @@ -1138,95 +1344,99 @@ overview of the supported methods may be found at \DescRef{\LabelBase.cmd.cleardoublepage} result in a page break and add an interleaf page\Index{page>interleaf} if needed to reach the next right-hand page.% - \IndexOption{open~=\PValue{right}}}% + \IndexOption{open~=\textKValue{right}}}% \end{desctabular} \label{tab:\LabelBase.open} \end{table} Since \LaTeX{} does not differentiate between left-hand and right-hand pages -in single-sided printing, the option does not have any influence in that case. +in one-sided printing, the option has no effect in that case. -In class \Class{scrartcl} the section is the first structural element below -the part. Because of this, \Class{scrartcl} does not support this option. +In the \Class{scrartcl} class, the section is the first structural element +below the part. For this reason, \Class{scrartcl} does not support this +option. % \EndIndexGroup \begin{Declaration} - \OptionVName{chapterprefix}{simple switch}% - \OptionVName{appendixprefix}{simple switch}% + \OptionVName{chapterprefix}{simple switch} + \OptionVName{appendixprefix}{simple switch} \Macro{IfChapterUsesPrefixLine}\Parameter{then code}\Parameter{else code} \end{Declaration}% With\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} the standard classes \Class{book} and \Class{report}, a chapter -title\Index[indexmain]{chapter>title} consists of a line with the word -``Chapter''\footnote{When using another language the word ``Chapter'' - is naturally translated to the appropriate language.} followed by -the chapter number. The title itself is set left-justified on the -following lines. The same effect is obtained in {\KOMAScript} with the -option \Option{chapterprefix}. Any value from table -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} may -be used as \PName{simple switch}. The default, however, is -\OptionValue{chapterprefix}{false}, which is opposite of the behaviour -of the standard classes, which would correspond to -\OptionValue{chapterprefix}{true}. -These options also affect the automatic -running titles in the headers (see \autoref{sec:\LabelBase.pagestyle}, +heading\Index[indexmain]{chapter>heading} consists of a line with the word +``Chapter''\footnote{When using another language the word ``Chapter'' is of +course translated to the appropriate language.} followed by the chapter +number. The heading itself is set left-justified on the following line. The +same effect is obtained in {\KOMAScript} with the \Option{chapterprefix} +option. You can use any value from \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch} as the \PName{simple switch}. The default, +however, is \OptionValue{chapterprefix}{false}, the opposite +behaviour\textnote{\KOMAScript{} vs. standard classes} of that of the standard +classes, which corresponds to \OptionValue{chapterprefix}{true}. These options +also affect the automatic running heads in the headers (see +\autoref{sec:\LabelBase.pagestyle}, \DescPageRef{\LabelBase.pagestyle.headings}). -Sometimes one wishes to have the -chapter titles in simplified form according to -\OptionValue{chapterprefix}{false}. But at the same time, one wishes a title -of an appendix\Index{appendix} to be preceded by a line with ``Appendix'' -followed by the appendix letter. This is achieved by using the -\Option{appendixprefix} option (see \autoref{tab:truefalseswitch}, -\autopageref{tab:truefalseswitch}). Since this results in an inconsistent -document layout, I advise against using this option. Final consequence of -using the option is, that \DescRef{\LabelBase.cmd.appendix} changes setting of option -\Option{chapterprefix}. +Sometimes you may want to use the simplified chapter headings produced by +\OptionValue{chapterprefix}{false} but at the same time to have the heading of +an appendix\Index{appendix} preceded by a line with ``Appendix'' followed by +the appendix letter. This is achieved by using the \Option{appendixprefix} +option (see \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}). +Since this results in an inconsistent document layout, I advise against using +this option. Ultimately, this option changes the \Option{chapterprefix} option +automatically at the beginning of the \DescRef{\LabelBase.cmd.appendix}. You\ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}} can execute code depending on the current setting for the chapter preceding line using \Macro{IfChapterUsesPrefixLine}. If \Option{chapterprefix} is currently -active, the \PName{then code} will be executed, otherwise the \PName{else - code}. +active, the \PName{then code} is executed; otherwise, the \PName{else code} is +executed. -\BeginIndex{FontElement}{chapterprefix}\LabelFontElement{chapterprefix}% -The font style of the chapter number line using -\OptionValue{chapterprefix}{true} or \OptionValue{appendixprefix}{true} may be -changed with element +\BeginIndex{FontElement}{chapterprefix}% +You can change the font style of the chapter number line that uses +\OptionValue{chapterprefix}{true} or \OptionValue{appendixprefix}{true} +by using the \FontElement{chapterprefix}\ChangedAt{v2.96a}{\Class{scrbook}\and - \Class{scrreprt}} using commands \DescRef{\LabelBase.cmd.setkomafont} and -\DescRef{\LabelBase.cmd.addtokomafont} (see + \Class{scrreprt}} element with the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, -\DescPageRef{\LabelBase.cmd.setkomafont}). Default is the usage of element -\DescRef{\LabelBase.fontelement.chapter}\IndexFontElement{chapter} (see -\DescPageRef{\LabelBase.cmd.chapter}, as well as +\DescPageRef{\LabelBase.cmd.setkomafont}). The default is to use the +\DescRef{\LabelBase.fontelement.chapter}\IndexFontElement{chapter} element +(see \DescPageRef{\LabelBase.cmd.chapter}, as well as \autoref{tab:\LabelBase.structureElementsFont}, -\autopageref{tab:\LabelBase.structureElementsFont}).% +\autopageref{tab:\LabelBase.structureElementsFont}). + +You can find additional settings for chapter headings in the explanation for +\DescRef{maincls-experts.cmd.RedeclareSectionCommand} and the commands +\DescRef{maincls-experts.cmd.chapterlineswithprefixformat} and +\DescRef{maincls-experts.cmd.chapterlinesformat} in +\autoref{sec:maincls-experts.experts}, \autoref{part:forExperts}.% \EndIndexGroup \begin{Declaration} - \OptionVName{headings}{selection} -\end{Declaration}% -The font size used for the titles\index{title}\index{document structure} is -relatively big, both with the standard classes and with {\KOMAScript}. Not -everyone likes this choice; moreover it is especially problematic for small -paper sizes. Consequently, {\KOMAScript} provides, besides the large title -font size defined by the -\OptionValue{headings}{big}\IndexOption{headings~=\PValue{big}}% + \OptionVName{headings}{setting} +\end{Declaration} +Headings\index{heading}\index{document structure} of sectioning levels +normally use a relatively large font size in both the standard classes and +{\KOMAScript}. This choice does not appeal to everyone and is especially +problematic for small paper sizes. Consequently, {\KOMAScript} provides, in +addition to the large headings defined by the +\OptionValue{headings}{big}\IndexOption{headings~=\textKValue{big}}% \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% -\important[i]{\OptionValue{headings}{big}\\ +\important{\OptionValue{headings}{big}\\ \OptionValue{headings}{normal}\\ - \OptionValue{headings}{small}} option, the two options -\OptionValue{headings}{normal}\IndexOption{headings~=\PValue{normal}} and -\OptionValue{headings}{small}\IndexOption{headings~=\PValue{small}}, that -allow for smaller title font sizes. The font sizes for headings resulting from -these options for \Class{scrbook} and \Class{scrreprt} are shown in + \OptionValue{headings}{small}} option, the options +\OptionValue{headings}{normal}\IndexOption{headings~=\textKValue{normal}} and +\OptionValue{headings}{small}\IndexOption{headings~=\textKValue{small}}, which +allow for smaller headings. The font sizes resulting from these options for +\Class{scrbook} and \Class{scrreprt} are shown in \autoref{tab:\LabelBase.structureElementsFont}, -\autopageref{tab:\LabelBase.structureElementsFont}. Respectively, the fonts of -the elements \DescRef{\LabelBase.fontelement.chapter}% +\autopageref{tab:\LabelBase.structureElementsFont}. Specifically, all three +settings reset the elements \DescRef{\LabelBase.fontelement.chapter}% \IndexFontElement{chapter}, \DescRef{\LabelBase.fontelement.section}\IndexFontElement{section}, \DescRef{\LabelBase.fontelement.subsection}\IndexFontElement{subsection}, @@ -1234,158 +1444,193 @@ the elements \DescRef{\LabelBase.fontelement.chapter}% \IndexFontElement{subsubsection}, \DescRef{\LabelBase.fontelement.paragraph}\IndexFontElement{paragraph}, and \DescRef{\LabelBase.fontelement.subparagraph}\IndexFontElement{subparagraph} -will be reset to these default. - -For \Class{scrartcl}, smaller -font sizes are generally used. \OnlyAt{\Class{scrbook}\and - \Class{scrreprt}}The spacing before and after chapter titles is also -influenced by these options. - -Chapter\important[i]{\begin{tabular}[t]{@{}l@{}} - \Option{headings=}\\ \quad\PValue{twolinechapter}\end{tabular}\\ - \begin{tabular}[t]{@{}l@{}} - \Option{headings=}\\ \quad\PValue{onelinechapter}\end{tabular}\\ - \begin{tabular}[t]{@{}l@{}} - \Option{headings=}\\ \quad\PValue{twolineappendix}\end{tabular}} -titles are also influenced by the options -\OptionValue{headings}{twolinechapter} and -\OptionValue{headings}{onelinechapter}, that are same as -\OptionValueRef{\LabelBase}{chapterprefix}{true} and -\OptionValueRef{\LabelBase}{chapterprefix}{false} (see above). The appendix -titles are influenced by \OptionValue{headings}{twolineappendix} and -\OptionValue{headings}{onelineappendix}\important[i]{% - \begin{tabular}[b]{@{}l@{}} - \Option{headings=}\\ \quad\PValue{onelineappendix} - \end{tabular}}, that are the same as the options -\OptionValueRef{\LabelBase}{appendixprefix}{true} and -\OptionValueRef{\LabelBase}{appendixprefix}{false} (see also above). - -The\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} method of beginning new -chapters may be switched by \OptionValue{headings}{openany}\important[i]{% +to the corresponding defaults. \Class{scrartcl}\OnlyAt{\Class{scrbook}\and + \Class{scrreprt}} generally uses slightly smaller headings. The spacing +before and after chapter headings is also reset by these options. + +\iffalse% + Chapter headings also have the \Option{headings} option with the + \PValue{twolinechapter} or \PValue{onelinechapter} settings, which are + equivalent to the + \OptionValueRef{\LabelBase}{chapterprefix}{true} and + \OptionValueRef{\LabelBase}{chapterprefix}{false} options. In the appendix + there are additional effects of the \PValue{onelineappendix} and + \PValue{twolineappendix} options upon the \Option{headings} option, which + corresponds to + \OptionValueRef{\LabelBase}{appendixprefix}{false} and + \OptionValueRef{\LabelBase}{appendixprefix}{true} (see also + above). % +\else% + Chapter headings\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} also + have\important{% + \OptionValue{headings}{twolinechapter}\\ + \OptionValue{headings}{onelinechapter}\\ + \OptionValue{headings}{twolineappendix}\\ + \OptionValue{headings}{onelineappendix}% + } the two options \OptionValue{headings}{twolinechapter} and + \OptionValue{headings}{onelinechapter}, which correspond to + \OptionValueRef{\LabelBase}{chapterprefix}{true} and + \OptionValueRef{\LabelBase}{chapterprefix}{false} explained above. For the + appendix, + \OptionValueRef{\LabelBase}{appendixprefix}{true} and + \OptionValueRef{\LabelBase}{appendixprefix}{false} serve as alternatives for + the \OptionValue{headings}{twolineappendix} and + \OptionValue{headings}{onelineappendix} options. % + \iffalse% + For the appendix, \OptionValue{headings}{twolineappendix} and + \OptionValue{headings}{onelineappendix} are available, which correspond to + the \OptionValueRef{\LabelBase}{appendixprefix}{true} and + \OptionValueRef{\LabelBase}{appendixprefix}{false} options (also see above). + \fi% + Of course, these options do not exist with \Class{scrartcl}% + \iffree{}{% Umbruchkorrekturtext + , since this class does not have chapters}% + .% +\fi + +The\ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} \OptionValue{headings}{standardclasses}% +\important{\OptionValue{headings}{standardclasses}} option adjusts the font +sizes of the headings to those of the standard classes. In addition, the font +for the \DescRef{\LabelBase.fontelement.disposition}% +\IndexFontElement{disposition} element is set to \Macro{bfseries}. It +therefore no longer uses a sans-serif font for the headings. If you use +\Class{scrbook}\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} or +\Class{scrreprt}, \OptionValue{headings}{twolinechapter} is also set and the +spacing between the chapter headings is adjusted to that of the standard +classes. + +You\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} can set the method to specify +the page on which new chapters begin with +\OptionValue{headings}{openany}\important{% \OptionValue{headings}{openany}\\ \OptionValue{headings}{openright}\\ \OptionValue{headings}{openleft}}, \OptionValue{headings}{openright}, and -\OptionValue{headings}{openleft} alternatively to option -\DescRef{\LabelBase.option.open} with the values \PValue{any}, +\OptionValue{headings}{openleft}, or alternatively with the +\DescRef{\LabelBase.option.open} option, which takes the values \PValue{any}, \PValue{right}, and \PValue{left} (see above). Another\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} special feature of \KOMAScript{} is the handling of the -optional argument of the structural commands \DescRef{\LabelBase.cmd.part}, \DescRef{\LabelBase.cmd.chapter}, -etc., down to \DescRef{\LabelBase.cmd.subparagraph}. Function and -meaning\important[i]{% - \begin{tabular}[t]{@{}l@{}} - \Option{headings=}\\\quad\PValue{optiontohead} - \end{tabular}\\ +optional argument of the sectioning commands \DescRef{\LabelBase.cmd.part}, +\DescRef{\LabelBase.cmd.chapter}, etc. down to +\DescRef{\LabelBase.cmd.subparagraph}. You can change its function and +meaning\important{\OptionValue{headings}{optiontohead}\\ \OptionValue{headings}{optiontotoc}\\ - \begin{tabular}[t]{@{}l@{}} - \Option{headings=}\\\quad\PValue{optiontoheadandtoc} - \end{tabular}% -} may be influenced by the options \OptionValue{headings}{optiontohead}% -\IndexOption{headings~=\PValue{optiontohead}}, -\OptionValue{headings}{optiontotoc}\IndexOption{headings~=\PValue{optiontotoc}}, -and \OptionValue{headings}{optiontoheadandtoc}% -\IndexOption{headings~=\PValue{optiontoheadandtoc}}. - -A summary of all the available selections of option \Option{headings} may be -found in \autoref{tab:\LabelBase.headings}. Examples are at the following -description of the structural commands. - + \OptionValue{headings}{optiontoheadandtoc}} with the options +\OptionValue{headings}{optiontohead}% +\IndexOption{headings~=\textKValue{optiontohead}}, +\OptionValue{headings}{optiontotoc}% +\IndexOption{headings~=\textKValue{optiontotoc}} and +\OptionValue{headings}{optiontoheadandtoc}% +\IndexOption{headings~=\textKValue{optiontoheadandtoc}}. + +See \autoref{tab:\LabelBase.headings} for a summary of all available settings +for the \Option{headings} option. The explanations of the sectioning commands +below contain examples using some of these settings. \begin{desclist} - \renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% - \desccaption[{Available values for option \Option{headings}}]{% - Available values for option \Option{headings} to select different kinds of - structural headings% + \desccaption[{Available values for the \Option{headings} option}]{% + Available values for the \Option{headings} option to format + section headings% \label{tab:\LabelBase.headings}% }{% - Available values for option \Option{headings} (\emph{continuation})% + Available values for the \Option{headings} option (\emph{continued})% }% \pventry{big}{% - Use very large headings with large distances above and below. - \IndexOption{headings~=\PValue{big}}}% + Use large fonts in the headings for each of the default sectioning levels + with wide spacing above and below the titles. + \IndexOption{headings~=\textKValue{big}}}% \pventry{normal}{% - Use mid-size headings with medium distances above and below. - \IndexOption{headings~=\PValue{normal}}}% + Use medium-sized fonts in the headings with medium spacing above and below + the titles. \IndexOption{headings~=\textKValue{normal}}}% \entry{\PValue{onelineappendix}, \PValue{noappendixprefix}, \PValue{appendixwithoutprefix}, \PValue{appendixwithoutprefixline}% - \IndexOption{headings~=\PValue{onelineappendix}}}{% - Chapter headings at the appendix will be set like other headings too.% + \IndexOption{headings~=\textKValue{onelineappendix}}}{% + Chapter headings in the appendix are set like other headings.% }% \entry{\PValue{onelinechapter}, \PValue{nochapterprefix}, \PValue{chapterwithoutprefix}, \PValue{chapterwithoutprefixline}% - \IndexOption{headings~=\PValue{onelinechapter}}}{% - Chapter headings will be set like other headings too.% + \IndexOption{headings~=\textKValue{onelinechapter}}}{% + Chapter titles are set like other headings.% }% \pventry{openany}{% The commands \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, \DescRef{\LabelBase.cmd.cleardoublestandardpage}, \DescRef{\LabelBase.cmd.cleardoubleplainpage}, \DescRef{\LabelBase.cmd.cleardoubleemptypage}, and - \DescRef{\LabelBase.cmd.cleardoublepage} behave same like using - \OptionValue{headings}{openright}.% - Parts, chapter, index, and back matter use - \DescRef{\LabelBase.cmd.clearpage} instead of + \DescRef{\LabelBase.cmd.cleardoublepage} generate a page break and insert + an interleaf page\Index{interleaf page} if needed to reach the next + right-hand page in two-sided printing, the same as in + \OptionValue{headings}{openright}. Parts, chapter, the index, and back + matter use \DescRef{\LabelBase.cmd.clearpage} instead of \DescRef{\LabelBase.cmd.cleardoublepage}.% - \IndexOption{headings~=\PValue{openany}}}% + \IndexOption{headings~=\textKValue{openany}}}% \pventry{openleft}{% The commands \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, \DescRef{\LabelBase.cmd.cleardoublestandardpage}, \DescRef{\LabelBase.cmd.cleardoubleplainpage}, \DescRef{\LabelBase.cmd.cleardoubleemptypage}, and - \DescRef{\LabelBase.cmd.cleardoublepage} generate a page break and if - needed insert an interleaf page to reach the next left-hand page at - double-page printing.% - Part, chapter, index and back matter use + \DescRef{\LabelBase.cmd.cleardoublepage} generate a page break and insert + an interleaf page if needed to reach the next left-hand page in two-sided + printing. Part, chapter, index and back matter use \DescRef{\LabelBase.cmd.cleardoublepage}.% - \IndexOption{headings~=\PValue{openleft}}}% + \IndexOption{headings~=\textKValue{openleft}}}% \pventry{openright}{% The commands \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, \DescRef{\LabelBase.cmd.cleardoublestandardpage}, \DescRef{\LabelBase.cmd.cleardoubleplainpage}, \DescRef{\LabelBase.cmd.cleardoubleemptypage}, and - \DescRef{\LabelBase.cmd.cleardoublepage} generate a page break and if - needed insert an interleaf page to reach the next right-hand page at - double-page printing.% - Part, chapter, index and back matter use + \DescRef{\LabelBase.cmd.cleardoublepage} generate a page break and insert + an interleaf page if needed to reach the next right-hand page in two-sided + printing. Part, chapter, index and back matter use \DescRef{\LabelBase.cmd.cleardoublepage}.% - \IndexOption{headings~=\PValue{openright}}}% + \IndexOption{headings~=\textKValue{openright}}}% \pventry{optiontohead}{% The\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} advanced functionality of the optional argument of the - structural commands \DescRef{\LabelBase.cmd.part} down to \DescRef{\LabelBase.cmd.subparagraph} will be - activated. By default the optional argument will be used for the running - head only.% - \IndexOption{headings~=\PValue{optiontohead}}% + sectioning commands \DescRef{\LabelBase.cmd.part} down to + \DescRef{\LabelBase.cmd.subparagraph} is activated. By default, the + optional argument is used only for the running head.% + \IndexOption{headings~=\textKValue{optiontohead}}% }% \entry{\PValue{optiontoheadandtoc}, \PValue{optiontotocandhead}% - \IndexOption{headings~=\PValue{optiontoheadandtoc}}}{% + \IndexOption{headings~=\textKValue{optiontoheadandtoc}}}{% The\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} advanced functionality of the optional argument of the - structural commands \DescRef{\LabelBase.cmd.part} down to \DescRef{\LabelBase.cmd.subparagraph} will be - activated. By default the optional argument will be used for the running - head and the table of contents.% + sectioning commands \DescRef{\LabelBase.cmd.part} down to + \DescRef{\LabelBase.cmd.subparagraph} is activated. By default, the + optional argument is used for the running head and the table of contents.% }% \pventry{optiontotoc}{% The\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} advanced functionality of the optional argument of the - structural commands \DescRef{\LabelBase.cmd.part} down to \DescRef{\LabelBase.cmd.subparagraph} will be - activated. By default the optional argument will be used for the table of - contents only.% - \IndexOption{headings~=\PValue{optiontohead}}% + sectioning commands \DescRef{\LabelBase.cmd.part} down to + \DescRef{\LabelBase.cmd.subparagraph} is activated. By default, the + optional argument is used only for the table of contents.% + \IndexOption{headings~=\textKValue{optiontohead}}% }% \pventry{small}{% - Use small headings with small distances above and below.% - \IndexOption{headings~=\PValue{small}}}% + Use small fonts in the headings with small spacing above and below the + titles.% + \IndexOption{headings~=\textKValue{small}}}% + \pventry{standardclasses}{% + \ChangedAt{v3.12}{\Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}}% + Reset the font settings for each of the standard sectioning levels and use + headings with the sizes of the standard classes. For chapter headings, + \Class{scrbook} und \Class{scrreprt} set + \OptionValue{headings}{twolinechapter}.% + }% \entry{\PValue{twolineappendix}, \PValue{appendixprefix}, \PValue{appendixwithprefix}, \PValue{appendixwithprefixline}% - \IndexOption{headings~=\PValue{twolineappendix}}}{% - Chapters at the appendix will be set with a number line with the contents - of \DescRef{\LabelBase.cmd.chapterformat}\IndexCmd{chapterformat}.% + \IndexOption{headings~=\textKValue{twolineappendix}}}{% + Chapter titles in the appendix are set with a number line whose format is + determined by + \DescRef{\LabelBase.cmd.chapterformat}\IndexCmd{chapterformat}.% }% \entry{\PValue{twolinechapter}, \PValue{chapterprefix}, \PValue{chapterwithprefix}, \PValue{chapterwithprefixline}% - \IndexOption{headings~=\PValue{twolinechapter}}}{% - Chapters will be set with a number line with the contents of + \IndexOption{headings~=\textKValue{twolinechapter}}}{% + Chapter titles are set with a number line whose format is determined by \DescRef{\LabelBase.cmd.chapterformat}\IndexCmd{chapterformat}.% }% \end{desclist} @@ -1394,66 +1639,60 @@ description of the structural commands. \begin{Declaration} - \OptionVName{numbers}{selection} + \OptionVName{numbers}{setting} \end{Declaration}% -\begin{Explain}% - In German, according to {\small DUDEN}, the numbering of sectional - units should have no period at the end if only arabic numbers are used - (see \cite[R\,3]{DUDEN}). On the other hand, if roman numerals or - letters are appear in the numbering, then a period should appear at the - end of the numbering (see \cite[R\,4]{DUDEN}). {\KOMAScript} has an - internal mechanism that tries to implement this somewhat complex - rule. The resulting effect is that, normally, after the sectional - commands \DescRef{\LabelBase.cmd.part} and \DescRef{\LabelBase.cmd.appendix} a switch is made to - numbering with an ending period. The information is saved in the - \File{aux} file and takes effect on the next {\LaTeX} run. -\end{Explain} - -In some cases the mechanism for placing or leaving off the ending period may -fail, or other languagues may have different -rules. Therefore\important[i]{\OptionValue{numbers}{endperiod}\\ - \OptionValue{numbers}{noendperiod}} it is possible to activate the use of -the ending period manually with the option -\OptionValue{numbers}{endperiod}\IndexOption{numbers~=\PValue{endperiod}} or -to deactivate it with -\OptionValue{numbers}{noendperiod}\IndexOption{numbers~=\PValue{noendperiod}}. -Default is \OptionValue{numbers}{autoendperiod}% -\IndexOption{numbers~=\PValue{autoendperiod}} with auto detection whether to -set the period or not. - -Please\textnote{Attention!} note that the mechanism only takes effect on the -next {\LaTeX} run. Therefore, before trying to use these options to forcibly -control the numbering format, a further run without changing any options -should be made. - -The\textnote{Attention!} available values are summarized in -\autoref{tab:\LabelBase.numbers}. Unlike most other selections, this -option may be changed at the document preamble, before -\Macro{begin}\PParameter{document}, only. +According to {\small DUDEN}, if only Arabic numerals are used to number +section headings\Index{headings}, the German practice is to have no point at +the end (see \cite[R\,3]{DUDEN}). On the other hand, if Roman numerals or +letters appear in the numbering, then a point should appear at the end of the +numbering (see \cite[R\,4]{DUDEN}). {\KOMAScript} has a mechanism that tries +to automate this somewhat complex rule. The result is that normally after +the sectioning commands \DescRef{\LabelBase.cmd.part} and +\DescRef{\LabelBase.cmd.appendix} the numbering switches to using a final +point. This information is saved in the \File{aux} file and takes effect on +the next {\LaTeX} run. + +Sometimes the mechanism for placing or omitting the final point may fail. +Sometimes other languages have different rules. Therefore you can force the +use of the final point with the option +\OptionValue{numbers}{endperiod}\IndexOption{numbers~=\textKValue{endperiod}}% +\important{\OptionValue{numbers}{endperiod}\\ +\OptionValue{numbers}{noendperiod}} or to prohibit it with +\OptionValue{numbers}{noendperiod}. + +Note\textnote{Attention!} that this mechanism only takes effect on the +next {\LaTeX} run. Therefore, before you try to use these options to force +the correct numbering format, you should always perform another \LaTeX{} run +without modifying the document. + +You can find a summary of the available values for the \PName{setting} of +\PName{numbers} in \autoref{tab:\LabelBase.numbers}. Unlike most other +settings, this option can only be set in the document preamble, i.\,e. before +\Macro{begin}\PParameter{document}. \begin{table} - \caption[{Available values of option \Option{numbers}}]{Available values of - option \Option{numbers} for selection of the period at the end of numbers - of structural headings} + \caption[{Available values for the \Option{numbers} option}]{Available values + of the \Option{numbers} option to configure the final points of the + numbers for section headings} \label{tab:\LabelBase.numbers} \begin{desctabular} \entry{\PValue{autoendperiod}, \PValue{autoenddot}, \PValue{auto}}{% - \KOMAScript{} decides, whether or not to set the period at the end of - the numbers. The numbers consists in Arabic digits only, the period will - be omitted. If there are alphabetic characters or roman numbers the - period will always be set. References to numbers will be set without - ending period always.% - \IndexOption{numbers~=\PValue{autoendperiod}}}% + \KOMAScript{} decides whether to set the point at the end of sectioning + command numbers. If there are only Arabic numerals, the point will + be omitted. If a letter or Roman numeral is found, the + point is set. However, references to these numbers are set without + a final point.% + \IndexOption{numbers~=\textKValue{autoendperiod}}}% \entry{\PValue{endperiod}, \PValue{withendperiod}, \PValue{periodatend}, \PValue{enddot}, \PValue{withenddot}, \PValue{dotatend}}{% - All numbers of structural commands and all dependent numbers will be set - with ending period. Only references will be set without the ending - period.% - \IndexOption{numbers~=\PValue{endperiod}}}% + All numbers of sectioning commands and their subordinate numbers are set + with a final point. Only references will be set without the final + point.% + \IndexOption{numbers~=\textKValue{endperiod}}}% \entry{\PValue{noendperiod}, \PValue{noperiodatend}, \PValue{noenddot}, \PValue{nodotatend}}{% - All the numbers are without ending period.% - \IndexOption{numbers~=\PValue{noendperiod}}}% + All numbers of sectioning commands are set without a final point.% + \IndexOption{numbers~=\textKValue{noendperiod}}}% \end{desctabular} \end{table} % @@ -1466,27 +1705,36 @@ option may be changed at the document preamble, before \end{Declaration}% As mentioned in \autoref{sec:\LabelBase.floats}, \DescPageRef{\LabelBase.option.listof}\OnlyAt{\Class{scrbook}\and - \Class{scrreprt}}, normally, every chapter entry generated with -\DescRef{\LabelBase.cmd.chapter} introduces vertical spacing into the lists of floats. Since -version~2.96a\ChangedAt{v2.96a}{\Class{scrbook}\and \Class{scrreprt}} this -applies also for the command \DescRef{\LabelBase.cmd.addchap}, if no compatibility option to an -earlier version was chosen (see option \DescRef{\LabelBase.option.version} in + \Class{scrreprt}}, every chapter that is created with +\DescRef{\LabelBase.cmd.chapter} normally inserts a vertical space in the +lists of floating environments (e.\,g., tables and figures). +Since version~2.96a,\important{\OptionValueRef{\LabelBase}{version}{2.96a}}% +\ChangedAt{v2.96a}{\Class{scrbook}\and \Class{scrreprt}} this also applies to +the \DescRef{\LabelBase.cmd.addchap} command unless you choose a compatibility +setting for an earlier version (see the \DescRef{\LabelBase.option.version} +option in \autoref{sec:\LabelBase.compatibilityOptions}, +\DescPageRef{\LabelBase.option.version}). + +In addition, you can use the \Option{chapteratlists} option to change the +vertical spacing by specifying the desired distance as the \PName{value}. +The default with \OptionValueRef{\LabelBase}{listof}{chaptergapsmall}% +\IndexOption{listof~=\textKValue{chaptergapsmall}} % +is 10\Unit{pt} (see the\DescRef{\LabelBase.option.version} option in \autoref{sec:\LabelBase.compatibilityOptions}, \DescPageRef{\LabelBase.option.version}). -Furthermore, now the option \Option{chapteratlists} can be used to change the -spacing, by passing the desired distance as \PName{value}. The default setting -with \OptionValueRef{\LabelBase}{listof}{chaptergapsmall}% -\IndexOption{listof~=\PValue{chaptergapsmall}} % -is 10\,pt. If \OptionValue{chapteratlists}{entry}% -\IndexOption{chapteratlists~=\PValue{entry}}% +If you use \OptionValue{chapteratlists}{entry}% +\IndexOption{chapteratlists~=\textKValue{entry}}% \important{\OptionValue{chapteratlists}{entry}} or \Option{chapteratlists} -without value is specified, then instead of a vertical distance, the chapter -entry itself will be entered into the lists. This will be done even if -there's no floating environment inside of the chapter. - -Please\textnote{Attention!} note that changes to the option will only become -effective in the lists following two more {\LaTeX} runs.% +without specifying a value, instead of a vertical space, the chapter entry +itself will be entered into the lists. Note that such an entry occurs even if +the chapter does not contain a floating environment. A method where only +chapters with floating environments are displayed in the respective list can +be found in the German-language \KOMAScript{} forum at +\cite{https://komascript.de/comment/5070}. + +Please\textnote{Attention!} note that changes to this option only takes +effect after two additional {\LaTeX} runs.% % \EndIndexGroup @@ -1503,218 +1751,227 @@ effective in the lists following two more {\LaTeX} runs.% \Index[indexmain]{part}% \Index[indexmain]{chapter}% \Index[indexmain]{section}% -The standard sectioning commands in {\KOMAScript} work in a similar -fashion to those of the standard classes. Thus, an alternative entry -for the table of contents and running headings can be specified as an -optional argument to the sectioning commands. - -In addition to this, with\ChangedAt{v3.10}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}}\textnote{\KOMAScript{} vs. standard - classes} option \important{\DescRef{\LabelBase.option.headings}} +The standard sectioning commands in {\KOMAScript} work the same way as those +in the standard classes. Thus, you can specify an alternative text for the +table of contents and running heads as an optional argument to the sectioning +commands. + +However, with\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\textnote{\KOMAScript{} vs. standard classes} the +\important{\DescRef{\LabelBase.option.headings}} \OptionValueRef{\LabelBase}{headings}{optiontohead}% -\IndexOption[indexmain]{headings~=\PValue{optiontohead}}, \KOMAScript{} -does not use -the optional argument \PName{short version} at the table of -contents, but for the running head only. Nevertheless, such a running head -needs an appropriate page style. See \autoref{sec:\LabelBase.pagestyle} and -\autoref{cha:scrlayer-scrpage} about this. With option +\IndexOption[indexmain]{headings~=\textKValue{optiontohead}} option, +\KOMAScript{} only uses the optional argument \PName{short version} in the +running head, not the table of contents. Of course, this text will only appear +if you use a page style\Index{page>style} that puts the corresponding +sectioning level in the running head. See \autoref{sec:\LabelBase.pagestyle} +and \autoref{cha:scrlayer-scrpage}. With the \OptionValueRef{\LabelBase}{headings}{optiontotoc}% -\IndexOption[indexmain]{headings~=\PValue{optiontotoc}}, \KOMAScript{} does not -use the -optional argument \PName{short version} for the running head, but -at the table of contents. Nevertheless, the entry will be shown only if -counter \DescRef{\LabelBase.counter.tocdepth} (see \autoref{sec:\LabelBase.toc}, -\DescPageRef{\LabelBase.counter.tocdepth}) is great enough. With option +\IndexOption[indexmain]{headings~=\textKValue{optiontotoc}} option, +\KOMAScript{} uses the optional argument \PName{short version} exclusively for +the table of contents and not the running head. However, the entry will be +shown only if the \DescRef{\LabelBase.counter.tocdepth} counter is great +enough (see \autoref{sec:\LabelBase.toc}, +\DescPageRef{\LabelBase.counter.tocdepth}). With the \OptionValueRef{\LabelBase}{headings}{optiontoheadandtoc}% -\IndexOption[indexmain]{headings~=\PValue{optiontoheadandtoc}}, \KOMAScript{} -uses the optional argument \PName{short version} in both the table of contents -and running head. All these three selections will also activate the extended -interpretation of the optional argument \PName{short version}, which is not -active by default. +\IndexOption[indexmain]{headings~=\textKValue{optiontoheadandtoc}} option, +\KOMAScript{} uses the optional argument \PName{short version} in both the +table of contents and the running head. These three options all activate the +extended interpretation of the optional argument \PName{short version}, which +is not active by default. The \ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} extended interpretation of the optional argument -determines whether there's an equality sign in \PName{short version}. If so, -the optional argument will be interpreted as \PName{option list} instead of -simple \PName{short version}. Thereby the three options -\OptionVName{head}{running head}\important{\Option{head}}, -\OptionVName{tocentry}{table of contents entry}\important{\Option{tocentry}}, -and \OptionVName{reference}{reference title}\important{\Option{reference}}% -\ChangedAt{v3.22}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} -are supported. Commas or equality signs inside of the values of those options -will be accepted only if they are enclosed by braces. - -Please\textnote{Attention!} note that this mechanism is only -functional as long as \KOMAScript{} controls the described -commands. From using a package that controls the sectioning commands -or the internal \LaTeX{} kernel commands for sectioning commands, -\KOMAScript{} can no longer provide this extended mechanism. This is -also valid for the always active extension of \KOMAScript{} to not -create entries to the table of contents % if the heading text -if the text of the -entry is empty. If you really want an entry with empty heading text, -you may use an invisible entry like \lstinline|\mbox{}| instead. +checks to see if there is an equals sign in \PName{short version}. If so, +the optional argument will be interpreted as an \PName{option list}. +Three options\,---\,\OptionVName{head}{running head}\important{\Option{head}\\ + \Option{tocentry}\\ + \Option{reference}}, \OptionVName{tocentry}{table of contents entry}, and +\OptionVName{reference}{reference title}% +\ChangedAt{v3.22}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% +\,---\,are supported with this format. To use commas or equals signs +within the values of those options, you must enclose them in braces. + +Please\textnote{Attention!} note that this mechanism only works as long as +\KOMAScript{} controls the sectioning commands. If you use package that +redefines the \KOMAScript{}'s or the internal \LaTeX{} kernel's sectioning +commands, \KOMAScript{} can no longer provide this extended mechanism. This +also applies to a \KOMAScript{} that is always active: sectioning commands +with no heading text\textnote{empty headings} do not create entries in the +table of contents. If you really want an entry with empty heading text, you +can use an invisible entry like \lstinline|\mbox{}|. \begin{Example} - Assume you're writing a document with some very extensive chapter - headings. These headings should be shown in the table of contents too. But - for the running head you want only single-line short headings. You will do - this using the optional argument of \Macro{chapter}. + Suppose you have a document with very long chapter headings. These headings + should appear in the table of contents, but you want to limit the running + head to short, single-line headings. You can do this with the optional + argument of \Macro{chapter}. \begin{lstcode} \chapter[short version of chapter heading] - {The Structural Sectioning Command - for Chapters Supports not only the - Heading Text itself but also a - Short Version with Selectable - Usage} + {The Sectioning Command for Chapters + Supports not only the Heading Text + Itself but also a Short Version Whose + Use can be Controlled} \end{lstcode} - Sometimes later you become aware that the automatic line breaking of this - heading is somehow inappropriate. Therefore you want to make the breaking - yourself. Nevertheless, the automatic line breaking should be still used at - the table of contents. With + A little later you realize that the line breaks for this long heading are + very inappropriate. You therefore want to choose the breaks + yourself. Nevertheless, you still want automatic line breaking in the table + of contents. With \begin{lstcode} \chapter[head={short version of chapter heading}, - tocentry={The Structural Sectioning + tocentry={The Sectioning Command for Chapters Supports not - only the Heading Text itself but - also a Short Version with - Selectable Usage}] - {The Structural\\ - Sectioning Command for Chapters\\ + only the Heading Text Itself but + also a Short Version Whose Use + can be Controlled}] + {The Sectioning\\ + Command for Chapters\\ Supports not only\\ - the Heading Text itself\\ + the Heading Text Itself\\ but also\\ - a Short Version\\ - with Selectable Usage} + a Short Version Whose\\ + Use can be Controlled} \end{lstcode} - you use independent entries for table of contents, running head, and the + you create separate entries for the table of contents, running head, and chapter heading itself. The arguments of the options \Option{head} and - \Option{tocentry} have been enclosed into braces, so the contents of the - options cannot influence the interpretation of the optional argument. + \Option{tocentry} have been enclosed in braces so their contents + can be arbitrary. - The recommendation of the braces in the example above will make more sense - with one more example. Assume you're using option - \OptionValueRef{\LabelBase}{headings}{optiontotoc} and now have a heading: + The need for braces in the example above is best illustrated by another + example. Suppose you chose the + \OptionValueRef{\LabelBase}{headings}{optiontotoc} option and set the title + this way: \begin{lstcode} \section[head=\emph{value}] {Option head=\emph{value}} \end{lstcode} - This would result in the entry ``Option head=\emph{value}'' at the table of - contents but ``\emph{value}'' at the running head. But surely you wanted the - entry ``head=\emph{value}'' at the table of contents and the complete - heading text at the running head. You may do this using braces: + This results in the entry ``Option head=\emph{value}'' in the table of + contents but ``\emph{value}'' in the running head. But surely you wanted the + entry ``head=\emph{value}'' in the table of contents and the complete + heading text in the running head. You can do this using braces: \begin{lstcode} \section[head{=}\emph{value}] {Option head=\emph{value}} \end{lstcode} - A similar case would be a comma. With the same - \DescRef{\LabelBase.option.headings} option like before: + A similar case concerns the comma. Using the same + \DescRef{\LabelBase.option.headings} option as before \begin{lstcode} \section[head=0, 1, 2, 3, \dots] {Natural Numbers Including the Zero} \end{lstcode} - would result in an error, because the comma would be interpreted as the - separator between the single options of the option list % + results in an error because the comma is interpreted as the + separator between the individual options of the option list % ``\lstinline|0, 1, 2, 3, \dots|''. But writing \begin{lstcode} \section[head={0, 1, 2, 3, \dots}] {Natural Numbers Including the Zero} \end{lstcode} - will change ``\lstinline|0, 1, 2, 3, \dots|'' into the argument of - option \Option{head}. + makes ``\lstinline|0, 1, 2, 3, \dots|'' the argument of + the \Option{head} option. \end{Example} -Similar\ChangedAt{v3.22}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} to setup the title of a running head using option -\Option{head} or to setup the title for the entry to the table of contents -using option \Option{tocentry} you can set the title of a reference with -package \Package{nameref}\IndexPackage{nameref}, -\Package{titleref}\IndexPackage{titleref}, or the -\Package{titleref}\IndexPackage{zref-titleref} module of package -\Package{zref}\IndexPackage{zref} using option \Option{reference}. Note, the -support for package \Package{titleref} is somehow rudimentary, and the package -is not fully compatible with \Package{hyperref}\IndexPackage{hyperref}. - -The title of the level part\important{\Macro{part}} (\Macro{part}) is -distinguished from other sectioning levels by being numbered independently -from the other parts. This means that the chapter level (in \Class{scrbook} or -\Class{scrreprt}), or the section level (in \Class{scrartcl}) is numbered -consecutively over all parts. Furthermore, for classes -\Class{scrbook}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} and -\Class{scrreprt}, the title of the part level together with the corresponding -preamble (see \Macro{setpartpreamble}, +Like\ChangedAt{v3.22}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} setting the title of a running head with the \Option{head} +option, or setting the title of a table-of-contents entry with the +\Option{tocentry} option, you can set the title of a reference with the +\Package{nameref}\IndexPackage{nameref}\important{\Package{nameref}\\ + \Package{titleref}\\ + \Package{zref-titleref}} or +\Package{titleref}\IndexPackage{titleref} packages, or with the +\Package{titleref}\IndexPackage{zref-titleref} module of the +\Package{zref}\IndexPackage{zref} package, using the \Option{reference}% +\important{\Option{reference}} option. Note that the support for the +\Package{titleref} package is rather rudimentary, since that package's +performance is poor compared to the other two, and it is not fully compatible +with \Package{hyperref}\IndexPackage{hyperref}\important{\Package{hyperref}}. + +The part-level title\important{\Macro{part}} (\Macro{part}) differs from other +sectioning levels by being numbered independently. This means that the chapter +level (in \Class{scrbook} or \Class{scrreprt}), or the section level (in +\Class{scrartcl}) is numbered consecutively over all parts. Furthermore, for +the \Class{scrbook}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} and +\Class{scrreprt} classes, the title of the part level together with the +corresponding preamble (see \DescRef{\LabelBase.cmd.setpartpreamble}, \DescPageRef{\LabelBase.cmd.setpartpreamble}) is set on a separate page. -\Macro{chapter}\important{\Macro{chapter}}\OnlyAt{\Class{scrbook}\and - \Class{scrreprt}} only exists in book or report classes, that is, in classes -\Class{book}, \Class{scrbook}, \Class{report} and \Class{scrreport}, but not -in the article classes \Class{article} and \Class{scrartcl}. In addition to -this, the command \Macro{chapter} in {\KOMAScript} differs substantially from -the version in the standard class. In the standard classes the chapter number -is used together with the prefix ``Chapter'', or the corresponding word in the -appropriate language, on a separate line above the actual chapter title -text. This overpowering\important[i]{\DescRef{\LabelBase.option.chapterprefix}\\ - \DescRef{\LabelBase.option.appendixprefix}} style is replaced in {\KOMAScript} by a simple -chapter number before the chapter heading text, but can be reverted by the -option \DescRef{\LabelBase.option.chapterprefix} (see +The \Macro{chapter}\important{\Macro{chapter}}\OnlyAt{\Class{scrbook}\and + \Class{scrreprt}} command only exists in the book and report classes, that +is, in \Class{book}, \Class{scrbook}, \Class{report} and \Class{scrreport}, +but not in the article classes \Class{article} and \Class{scrartcl}. +Furthermore, the \Macro{chapter}\textnote{\KOMAScript{} vs. standard classes} +command in {\KOMAScript} differs substantially from the version in the +standard classes. In the standard classes, the chapter number is used together +with the prefix ``Chapter'', or the corresponding word in the appropriate +language, on a separate line above the actual chapter title text. +\KOMAScript{} replaces this +overpowering\important{\DescRef{\LabelBase.option.chapterprefix}\\ + \DescRef{\LabelBase.option.appendixprefix}} style with a simple chapter +number before the chapter title, but you can restore the original behaviour +with the \DescRef{\LabelBase.option.chapterprefix} option (see \DescPageRef{\LabelBase.option.chapterprefix}). -Please\textnote{Attention!} note that \Macro{part} and \Macro{chapter} in -classes \Class{scrbook} and \Class{scrreprt} -\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} change the page style for one -page. The applied page style in {\KOMAScript} is defined in the macros -\DescRef{\LabelBase.cmd.partpagestyle} and \DescRef{\LabelBase.cmd.chapterpagestyle} (see +Please\textnote{Attention!} note that \Macro{part} and \Macro{chapter} in the +\Class{scrbook} and \Class{scrreprt} +\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} classes change the page style for +one page. The page style applied in {\KOMAScript} is defined in the macros +\DescRef{\LabelBase.cmd.partpagestyle} and +\DescRef{\LabelBase.cmd.chapterpagestyle} (see \autoref{sec:\LabelBase.pagestyle}, \DescPageRef{\LabelBase.cmd.titlepagestyle}). +\BeginIndexGroup \BeginIndex[indexother]{}{font}% \BeginIndex[indexother]{}{font>style}% \BeginIndex[indexother]{}{font>size}% \BeginIndex{FontElement}{part}\LabelFontElement{part}% \BeginIndex{FontElement}{partnumber}\LabelFontElement{partnumber}% \BeginIndex{FontElement}{chapter}\LabelFontElement{chapter}% +\BeginIndex{FontElement}{chapterprefix}\LabelFontElement{chapterprefix}% \BeginIndex{FontElement}{section}\LabelFontElement{section}% \BeginIndex{FontElement}{subsection}\LabelFontElement{subsection}% \BeginIndex{FontElement}{subsubsection}\LabelFontElement{subsubsection}% \BeginIndex{FontElement}{paragraph}\LabelFontElement{paragraph}% \BeginIndex{FontElement}{subparagraph}\LabelFontElement{subparagraph}% \BeginIndex{FontElement}{disposition}\LabelFontElement{disposition}% -The font of all headings\ChangedAt{v2.8p}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} can be changed with the commands +You\ChangedAt{v2.8p}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} can change the font style for all headings with the \DescRef{\LabelBase.cmd.setkomafont}\IndexCmd{setkomafont} and -\DescRef{\LabelBase.cmd.addtokomafont}\IndexCmd{addtokomafont} (see +\DescRef{\LabelBase.cmd.addtokomafont}\IndexCmd{addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, -\DescPageRef{\LabelBase.cmd.setkomafont}). In doing this, generally the -element \FontElement{disposition}\important{\FontElement{disposition}} is -used, followed by a specific element\important[s]{% +\DescPageRef{\LabelBase.cmd.setkomafont}). In doing so, the element +\FontElement{disposition}\important{\FontElement{disposition}} is applied +first, followed by the specific element\important{% \FontElement{part}\\ \FontElement{chapter}\\ \FontElement{section}\\ \FontElement{subsection}\\ \FontElement{paragraph}\\ - \FontElement{subparagraph}} for every section level (see + \FontElement{subparagraph}} for each sectioning level (see \autoref{tab:\LabelBase.fontelements}, -\autopageref{tab:\LabelBase.fontelements}). There is a separate element -\FontElement{partnumber} for the number part of parts. The font for the -element \FontElement{disposition} is predefined as +\autopageref{tab:\LabelBase.fontelements}). There is a separate elements, +\FontElement{partnumber}, for the number of the part heading, and +\FontElement{chapterprefix}, for the optional prefix line of chapter headings. +The initial definition for the \FontElement{disposition} element is \Macro{normalcolor}\linebreak[2]\Macro{sffamily}\linebreak[2]\Macro{bfseries}. -The default font size for the specific elements depends on the options +The default font sizes for the specific elements depends on the options \OptionValueRef{\LabelBase}{headings}{big}, -\OptionValueRef{\LabelBase}{headings}{normal} and +\OptionValueRef{\LabelBase}{headings}{normal}, and \OptionValueRef{\LabelBase}{headings}{small} (see -\DescPageRef{\LabelBase.option.headings}). The defaults are listed in +\DescPageRef{\LabelBase.option.headings}). They are listed in \autoref{tab:\LabelBase.structureElementsFont}. -% +% Umbruchkorrektur: Tabelle verschoben \begin{table} % \centering% +% \caption \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% -% \caption \begin{captionbeside}[{Default font sizes for different levels of document - structuring}]{Default font sizes for different levels of document - structuring in \Class{scrbook} and \Class{scrreprt}}[l] + sectioning}]{% + \label{tab:\LabelBase.structureElementsFont}% + Default font sizes for different levels of document sectioning in + \Class{scrbook} and \Class{scrreprt}}[l] \begin{tabular}[t]{lll} \toprule Class Option & Element & Default\\ @@ -1727,6 +1984,9 @@ The default font size for the specific elements depends on the options & \Macro{huge} \\ & \DescRef{\LabelBase.fontelement.chapter}\IndexFontElement{chapter} & \Macro{huge} \\ + & \DescRef{\LabelBase.fontelement.chapterprefix}% + \IndexFontElement{chapterprefix} + & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{chapter} \\ & \DescRef{\LabelBase.fontelement.section}\IndexFontElement{section} & \Macro{Large} \\ & \DescRef{\LabelBase.fontelement.subsection}% @@ -1744,6 +2004,8 @@ The default font size for the specific elements depends on the options & \DescRef{\LabelBase.fontelement.part} & \Macro{huge} \\ & \DescRef{\LabelBase.fontelement.partnumber} & \Macro{huge} \\ & \DescRef{\LabelBase.fontelement.chapter} & \Macro{LARGE} \\ + & \FontElement{chapterprefix}\IndexFontElement{chapterprefix} + & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{chapter} \\ & \DescRef{\LabelBase.fontelement.section} & \Macro{Large} \\ & \DescRef{\LabelBase.fontelement.subsection} & \Macro{large} \\ & \DescRef{\LabelBase.fontelement.subsubsection} & \Macro{normalsize} \\ @@ -1753,6 +2015,8 @@ The default font size for the specific elements depends on the options & \DescRef{\LabelBase.fontelement.part} & \Macro{LARGE} \\ & \DescRef{\LabelBase.fontelement.partnumber} & \Macro{LARGE} \\ & \DescRef{\LabelBase.fontelement.chapter} & \Macro{Large} \\ + & \FontElement{chapterprefix}\IndexFontElement{chapterprefix} + & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{chapter} \\ & \DescRef{\LabelBase.fontelement.section} & \Macro{large} \\ & \DescRef{\LabelBase.fontelement.subsection} & \Macro{normalsize} \\ & \DescRef{\LabelBase.fontelement.subsubsection} & \Macro{normalsize} \\ @@ -1761,250 +2025,331 @@ The default font size for the specific elements depends on the options \bottomrule \end{tabular} \end{captionbeside} - \label{tab:\LabelBase.structureElementsFont} \end{table} - +% \begin{Example} - Suppose you are using the class option - \OptionValueRef{\LabelBase}{headings}{big} and notice that the very big - headings of document parts are too bold. You could change this as follows: + Suppose you use the \OptionValueRef{\LabelBase}{headings}{big} class option + and notice that the very large headings of the document parts are too bold. + You could change this as follows: \begin{lstcode} \setkomafont{disposition}{\normalcolor\sffamily} \part{Appendices} \addtokomafont{disposition}{\bfseries} \end{lstcode} Using the command above you only switch off the font attribute -\textbf{bold} for a heading ``Appendices''. A much more comfortable +\textbf{bold} for a heading ``Appendices''. A much more convenient and elegant solution is to change all \Macro{part} headings at once. This is done either by: \begin{lstcode} \addtokomafont{part}{\normalfont\sffamily} \addtokomafont{partnumber}{\normalfont\sffamily} \end{lstcode} - or simply using: + or simply: \begin{lstcode} \addtokomafont{part}{\mdseries} \addtokomafont{partnumber}{\mdseries} \end{lstcode} -The last version is to be preferred because it gives you the correct result -even when you make changes to the \DescRef{\LabelBase.fontelement.disposition} +The second version is preferred because it gives you the correct result +even if you change the \DescRef{\LabelBase.fontelement.disposition} element\IndexFontElement{disposition}, for instance: \begin{lstcode} \setkomafont{disposition}{\normalcolor\bfseries} \end{lstcode} - With this change it is possible to set all section levels at once to no + With this change, it is possible to set all section levels at once to no longer use sans serif fonts. \end{Example} -Please be warned of misusing the possibilities of font switching to -mix fonts, font sizes and font attributes excessively. Picking the -most suitable font for a given task is a hard task even for -professionals and has almost nothing to do with the personal tastes of -non-experts. Please refer to the citation at the end of -\autoref{sec:typearea.tips}, \autopageref{sec:typearea.tips.cite} and -to the following explanation. +I strongly advise against using the ability to switch fonts in order to mix +fonts, font sizes, and font attributes wildly. Picking the right font for the +job is a matter for experts and has almost nothing to do with the personal +tastes of non-experts. See the citation at the end of +\autoref{sec:typearea.tips}, \autopageref{sec:typearea.tips.cite} and to the +following explanation. \begin{Explain} - It is possible to use different font types for different section - levels in {\KOMAScript}. Non-experts in typography should for very - good typographical reasons refrain absolutely from using these - possibilities. - - There is a rule in typography which states that one should mix as - few fonts as possible. Using sans serif for headings already seems - to be a breach of this rule. However, one should know that bold, - large serif letters are much too heavy for headings. Strictly - speaking, one would then have to at least use a normal instead of a - bold or semi-bold font. However, in deeper levels of the structuring, - a normal font may then appear too lightly weighted. On the other - hand, sans serif fonts in headings have a very pleasant appearance - and in fact find acceptance almost solely for headings. That is why - sans serif is the carefully chosen default in {\KOMAScript}. - - More variety should, however, be avoided. Font mixing is only for - professionals. In case you want to use other fonts than the standard {\TeX} - fonts\,---\,regardless of whether these are CM\Index{CM fonts}, EC\Index{EC - fonts}, or LM fonts\Index{LM fonts}\,---\,you should consult an expert, or - for safety's sake redefine the font for the element + It is possible to use different font types for different sectioning + levels in {\KOMAScript}. Non-experts in typography should absolutely avoid + doing so for excellent typographical reasons. + + A rule of typography states that you should mix as few fonts as possible. + Using sans serif for headings already seems to violate this rule. However, + you should realize that large, bold, serif letters are much too heavy for + headings. Strictly speaking, you should then use a normal instead of a bold + or semi-bold font. However, in deeper levels of the sectioning, a normal + font may then appear too light. On the other hand, sans serif fonts have a + very pleasant appearance in headings, and almost solely in headings. There + is, therefore, good reason why sans serif is the default in {\KOMAScript}. + + Greater variety should, however, be avoided. Font mixing is something for + professionals. For this reason, if you want to use fonts other than the + standard {\TeX} fonts\,---\,regardless of whether these are CM\Index{CM + fonts}, EC\Index{EC fonts}, or LM fonts\Index{LM fonts}\,---\,you should + consult an expert about the compatibility of the sans serif and serif fonts, + or redefine the element \DescRef{\LabelBase.fontelement.disposition}\IndexFontElement{disposition} - as seen in the example above. The author of this documentation considers the - commonly encountered combinations Times and Helvetica or Palatino with - Helvetica as unfavourable. + as a precautionary measure. The author considers the commonly encountered + combinations of Times and Helvetica or Palatino with Helvetica to be + awkward. \end{Explain} +\EndIndexGroup % \EndIndexGroup \begin{Declaration} - \Macro{part*}\Parameter{Heading}% - \Macro{chapter*}\Parameter{Heading}% - \Macro{section*}\Parameter{Heading}% - \Macro{subsection*}\Parameter{Heading}% - \Macro{subsubsection*}\Parameter{Heading}% - \Macro{paragraph*}\Parameter{Heading}% - \Macro{subparagraph*}\Parameter{Heading} + \Macro{part*}\Parameter{heading}% + \Macro{chapter*}\Parameter{heading}% + \Macro{section*}\Parameter{heading}% + \Macro{subsection*}\Parameter{heading}% + \Macro{subsubsection*}\Parameter{heading}% + \Macro{paragraph*}\Parameter{heading}% + \Macro{subparagraph*}\Parameter{heading} \end{Declaration}% -All disposition commands have starred versions, which are -unnumbered\Index{numbering}, and produce section headings which do not -show up in the table of contents\Index{table>of contents}\Index{contents>table - of} or in the -running heading\Index{header}. The absence of a running heading often -has an unwanted side effect. For example, if a chapter which is set -using \Macro{chapter*} spans several pages, then the running heading -of the previous chapter suddenly reappears. {\KOMAScript} offers a -solution for this which is described -below. \OnlyAt{\Class{scrbook}\and\Class{scrreprt}}\Macro{chapter*} -only exists in book and report classes, that is, \Class{book}, -\Class{scrbook}, \Class{report} and \Class{scrreport}, but not the -article classes \Class{article} and \Class{scrartcl}. - -Please\textnote{Attention!} note that \DescRef{\LabelBase.cmd.part} and \DescRef{\LabelBase.cmd.chapter} change -the page style for one page. The applied style is defined in the macros -\DescRef{\LabelBase.cmd.partpagestyle} and -\DescRef{\LabelBase.cmd.chapterpagestyle} in {\KOMAScript} (see -\autoref{sec:\LabelBase.pagestyle}, \DescPageRef{\LabelBase.cmd.titlepagestyle}). - -As for the possibilities of font switching\ChangedAt{v2.8p}{% - \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}}, % -the same explanations apply as were given above for the unstarred -variants. The structuring elements are named the same since they do -not indicate variants but structuring levels.% +The starred variants of all sectioning commands produce +unnumbered\Index{numbering} headings which do not appear in the table of +contents\Index{table>of contents}\Index{contents>table of} or in the running +head\Index{running head}. The absence of a running head often has an unwanted +side effect. If, for example, a chapter set using \Macro{chapter*} spans +several pages, then the running head of the previous chapter suddenly +reappears. {\KOMAScript} offers a solution for this problem, described below. +\Macro{chapter*}\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} only exists in +book and report classes, that is, \Class{book}, \Class{scrbook}, +\Class{report} and \Class{scrreport}, not in the article classes +\Class{article} and \Class{scrartcl}. + +Please\textnote{Attention!} note that \DescRef{\LabelBase.cmd.part} and +\DescRef{\LabelBase.cmd.chapter} change the page style for one page. While the +standard classes use the \PageStyle{plain} page style, {\KOMAScript} applies +the style defined in the \DescRef{\LabelBase.cmd.partpagestyle} and +\DescRef{\LabelBase.cmd.chapterpagestyle} macros (see +\autoref{sec:\LabelBase.pagestyle}, +\DescPageRef{\LabelBase.cmd.titlepagestyle}). + +The possibilities for switching fonts\ChangedAt{v2.8p}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} % +described above for the unstarred variants apply without change. The elements +use the same names since they do not indicate variants but structuring +levels.% % \EndIndexGroup -\iftrue% Umbruchkorrekturtext -In the standard classes\textnote{\KOMAScript{} vs. standard classes} there are -no further structuring commands. In particular, there are no commands which -can produce unnumbered chapters or sections which show up in the table of -contents and in the running heading.% +\iffalse% Umbruchkorrekturtext + In the standard classes\textnote{\KOMAScript{} vs. standard classes} there + are no further structuring commands. In particular, there are no commands + which can produce unnumbered chapters or sections which show up in the table + of contents and in the running heading.% \fi + \begin{Declaration} - \Macro{addpart}\OParameter{Short version}\Parameter{Heading}% - \Macro{addpart*}\Parameter{Heading}% - \Macro{addchap}\OParameter{Short version}\Parameter{Heading}% - \Macro{addchap*}\Parameter{Heading}% - \Macro{addsec}\OParameter{Short version}\Parameter{Heading}% - \Macro{addsec*}\Parameter{Heading}\textnote[n]{\KOMAScript{} vs. standard classes} + \Macro{addpart}\OParameter{short version}\Parameter{heading}% + \Macro{addpart*}\Parameter{heading}% + \Macro{addchap}\OParameter{short version}\Parameter{heading}% + \Macro{addchap*}\Parameter{heading}% + \Macro{addsec}\OParameter{short version}\Parameter{heading}% + \Macro{addsec*}\Parameter{heading} + \textnote[n]{\KOMAScript{} vs. standard classes} \end{Declaration}% -In addition to the commands of the standard classes, {\KOMAScript} -offers the new commands \Macro{addsec} and \Macro{addchap}. They are -similar to the standard commands \DescRef{\LabelBase.cmd.chapter} and -\DescRef{\LabelBase.cmd.section}, except that they are unnumbered. They thus produce -both a running heading and an entry in the table of contents. +In addition to the commands of the standard classes, {\KOMAScript} offers the +new commands \Macro{addpart}, \Macro{addsec} and \Macro{addchap}. They are +similar to the standard commands \DescRef{\LabelBase.cmd.part}\IndexCmd{part}% +\important{\DescRef{\LabelBase.cmd.part}, \DescRef{\LabelBase.cmd.chapter}, + \DescRef{\LabelBase.cmd.section}}, +\DescRef{\LabelBase.cmd.chapter}\IndexCmd{chapter} and +\DescRef{\LabelBase.cmd.section}\IndexCmd{section} except that they are +unnumbered. They thus produce both a running head and an entry in the table of +contents. The starred variants \Macro{addchap*} and \Macro{addsec*} are similar to the -standard commands \DescRef{\LabelBase.cmd.chapter*} and \DescRef{\LabelBase.cmd.section*} except for a tiny but -important difference: The running headings are deleted. This eliminates the -side effect of obsolete headers mentioned above. Instead, the running headings -on following pages remain empty. \OnlyAt{\Class{book}\and - \Class{scrreprt}}\Macro{addchap} and \Macro{addchap*} of course only exist -in book and report classes, namely \Class{book}, \Class{scrbook}, -\Class{report} and \Class{scrreport}, but not in the article classes -\Class{article} and \Class{scrartcl}. - -Similarly, the command \Macro{addpart} produces an unnumbered document -part with an entry in the table of contents. Since the running -headings are already deleted by \DescRef{\LabelBase.cmd.part} and \DescRef{\LabelBase.cmd.part*} the -problem of obsolete headers does not exist. The starred version -\Macro{addpart*} is thus identical to \DescRef{\LabelBase.cmd.part*} and is only -defined for consistency reasons. +standard commands \DescRef{\LabelBase.cmd.chapter*} and +\DescRef{\LabelBase.cmd.section*} except for a small but important difference: +the running heads are deleted. This eliminates the side effect of obsolete +headers mentioned above. Instead, the running heads on subsequent pages remain +empty. \OnlyAt{\Class{book}\and \Class{scrreprt}}\Macro{addchap} and +\Macro{addchap*} only exist, of course, in book and report classes, namely +\Class{book}, \Class{scrbook}, \Class{report} and \Class{scrreport}, not in +the article classes \Class{article} and \Class{scrartcl}. + +The \Macro{addpart} command produces an unnumbered document part with an +entry in the table of contents. Since the running heads are already deleted +by \DescRef{\LabelBase.cmd.part} and \DescRef{\LabelBase.cmd.part*} the +previously mentioned problem with obsolete headers does not exist. The starred +version \Macro{addpart*} is thus identical to \DescRef{\LabelBase.cmd.part*} +and is only defined for reasons of consistency. Please note\textnote{Attention!} that \Macro{addpart} and \Macro{addchap} and -their starred versions change the page style for one page. The particular page +their starred variants change the page style for one page. The particular page style is defined in the macros \DescRef{\LabelBase.cmd.partpagestyle} and \DescRef{\LabelBase.cmd.chapterpagestyle} (see -\autoref{sec:\LabelBase.pagestyle}, \DescPageRef{\LabelBase.cmd.chapterpagestyle}). +\autoref{sec:\LabelBase.pagestyle}, +\DescPageRef{\LabelBase.cmd.titlepagestyle}). +\iffree{\iffalse}{\csname iftrue\endcsname}% Umbruchkorrekturbeispiel + \begin{Example} + You write a book with a long afterword that spans several pages. This + should receive neither a running head nor an entry in the table of + contents. Therefore, you first use \DescRef{\LabelBase.cmd.chapter*}: +\begin{lstcode} + \documentclass{scrbook} + \usepackage{blindtext} + \begin{document} + \tableofcontents + \blinddocument + \chapter*{Afterword} + \Blindtext[10] + \end{document} +\end{lstcode} + However, you discover that the running head of the previous chapter + reappears on the second and third pages of the afterword. Naturally, you do + not want that. Therefore, you use \Macro{addchap*}: +\begin{lstcode} + \documentclass{scrbook} + \usepackage{blindtext} + \begin{document} + \tableofcontents + \blinddocument + \addchap*{Afterword} + \Blindtext[10] + \end{document} +\end{lstcode} + The complete postscript is now without a running head, if that is what you + want. But even that does not quite meet your expectations. A running head + would be nice. With +\begin{lstcode} + \documentclass{scrbook} + \usepackage{blindtext} + \begin{document} + \tableofcontents + \blinddocument + \addchap{Afterword} + \Blindtext[10] + \end{document} +\end{lstcode} + you now get both ``Afterword'' as the running head on the even pages and an + entry in the table of contents. But this entry bothers your publisher. He + insists that the afterword have no entry in the table of contents. Even if + that seems strange to you, you want to satisfy the publisher, so with + \OptionValueRef{\LabelBase}{headings}{optiontotocandhead} you first + activate the extended function for the optional argument and then + explicitly set an empty argument for the table of contents: +\begin{lstcode} + \documentclass[headings=optiontotocandhead] + {scrbook} + \usepackage{blindtext} + \begin{document} + \tableofcontents + \blinddocument + \addchap[tocentry={}]{Afterword} + \Blindtext[10] + \end{document} +\end{lstcode} + The running head is not changed by \OptionValue{tocentry}{\{\}}. Since + \Class{scrbook} automatically omits empty entries in the table of contents, + the publisher is now satisfied. + \end{Example}% +\fi -As for the possibilities of font switching\ChangedAt{v2.8p}{% - \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}}, % -the same explanations apply as given above for the normal structuring -commands. The elements are named the same since they describe not -variants but structuring levels.% +The possibilities for switching fonts\ChangedAt{v2.8p}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} % +described above for the unstarred variant of the sectioning commands apply +without change. The elements have the same names since they do not designate +variants but sectioning levels.% % \EndIndexGroup \begin{Declaration} - \Macro{minisec}\Parameter{Heading} + \Macro{minisec}\Parameter{heading} \end{Declaration}% -Sometimes a heading\Index{heading} is wanted which is highlighted but -also closely linked to the following text. Such a heading should not -be separated by a large vertical skip. +Sometimes you want a heading\Index{heading} that is highlighted but also +closely linked to the following text. Such a heading should not be separated +by a large vertical skip. -The command \Macro{minisec} is designed for this situation. This -heading is not associated with any structuring level. Such a -\emph{mini section} does not produce an entry in the table of contents -nor does it receive any numbering. +The \Macro{minisec} command is designed for this situation. This heading is +not associated with any sectioning level\textnote{no sectioning level}. Such a +\emph{mini-section} does not produce an entry in the table of contents, nor +does it receive any numbering. +\BeginIndexGroup \BeginIndex{FontElement}{minisec}\LabelFontElement{minisec}% -The font type of the structuring command \Macro{minisec} can be changed using -the element -\DescRef{\LabelBase.fontelement.disposition}\IndexFontElement{disposition} -(see \autoref{tab:\LabelBase.fontelements}, -\autopageref{tab:\LabelBase.fontelements}) and -\FontElement{minisec}\ChangedAt{v2.96a}{% - \Class{scrbook} \and\Class{scrreprt} \and\Class{scrartcl}}. Default setting -of element \FontElement{minisec} is empty, so the default of the element -\DescRef{\LabelBase.fontelement.disposition}\IndexFontElement{disposition} is -active.% -\EndIndex{FontElement}{minisec}% +You can change the font of the \Macro{minisec} command using the +\DescRef{\LabelBase.fontelement.disposition}% +\important{\DescRef{\LabelBase.fontelement.disposition}\\ +\FontElement{minisec}} and \FontElement{minisec}\ChangedAt{v2.96a}{% + \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} element (see +\autoref{tab:maincls.fontelements}, \autopageref{tab:maincls.fontelements}). +The default of the \FontElement{minisec} element is empty, so by default only +the \DescRef{\LabelBase.fontelement.disposition} element is used.% +\EndIndexGroup \begin{Example} You have developed a kit for building a mouse trap and want the documentation separated into a list of necessary items and an assembly description. You could write the following: \begin{lstcode} - \minisec{Items needed} - - \begin{flushleft} - 1 plank ($100\times 50 \times 12$)\\ - 1 spring-plug of a beer-bottle\\ - 1 spring of a ball-point pen\\ - 1 drawing pin\\ - 2 screws\\ - 1 hammer\\ - 1 knife - \end{flushleft} - - \minisec{Assembly} - At first one searches the mouse-hole and puts the drawing pin - directly behind the hole. Thus the mouse cannot escape during the - following actions. - - Then one knocks the spring-plug with the hammer into the mouse-hole. - If the spring-plug's size is not big enough in order to shut the - mouse-hole entirely, then one can utilize the plank instead and - fasten it against the front of the mouse-hole utilizing the two - screws and the knife. Instead of the knife one can use a - screw-driver instead. + \documentclass{scrartcl} + + \begin{document} + + \title{DIY Projects} + \author{Two Left Thumbs} + \date{\today} + \maketitle + + \section{Mousetrap} + + The first project is suitable for beginners and only requires + a few components that should be found in every household. + + \minisec{Material Required} + + \begin{flushleft} + 1 board ($100\times 50 \times 12$)\\ + 1 swing-top cap of a beer-bottle\\ + 1 ballpoint pen\\ + 1 push pin\\ + 2 screws\\ + 1 hammer\\ + 1 knife + \end{flushleft} + + \minisec{Assembly} + First, find the mouse hole and put the push pin directly behind + the hole so that the mouse cannot escape during the following + actions. + + Next tap the swing-top cap into the mouse hole with the hammer. + If the cap is not big enough to block the hole completely and + permanently, take the board instead and screw it to the front + of the mouse hole using the two screws and the knife. Of + course, you can use a screwdriver instead of a knife. The + ballpoint pen has fallen victim to animal welfare. + \end{document} \end{lstcode} - Which gives: + The main part, starting with the heading ``Material Required'' will look + like this: \begin{ShowOutput}[\baselineskip]\setlength{\parindent}{1em} - \minisec{Items needed} - - \begin{flushleft} - 1 plank ($100\times 50 \times 12$)\\ - 1 spring-plug of a beer-bottle\\ - 1 spring of a ball-point pen\\ - 1 drawing pin\\ - 2 screws\\ - 1 hammer\\ - 1 knife - \end{flushleft} - - \minisec{Assembly} - At first one searches the mouse-hole and puts the drawing pin - directly behind the hole. Thus the mouse cannot escape during the - following actions. - - Then one knocks the spring-plug with the hammer into the - mouse-hole. If the spring-plug's size is not big enough in order - to shut the mouse-hole entirely, then one can utilize the plank - instead and fasten it against the front of the mouse-hole - utilizing the two screws and the knife. Instead of the knife one - can use a screw-driver instead. + \minisec{Material Required} + + \begin{flushleft} + 1 board ($100\times 50 \times 12$)\\ + 1 swing-top cap of a beer-bottle\\ + 1 ballpoint pen\\ + 1 push pin\\ + 2 screws\\ + 1 hammer\\ + 1 knife + \end{flushleft} + + \minisec{Assembly} + First, find the mouse hole and put the push pin directly behind the hole + so that the mouse cannot escape during the following actions. + + Next tap the swing-top cap into the mouse hole with the hammer. If the cap + is not big enough to block the hole completely and permanently, take the + board instead and screw it to the front of the mouse hole using the two + screws and the knife. Of course, you can use a screwdriver instead of a + knife. The ballpoint pen has fallen victim to animal welfare. \end{ShowOutput} \end{Example} % @@ -2018,14 +2363,14 @@ active.% \end{Declaration}% In the standard classes\textnote{\KOMAScript{} vs. standard classes}, headings are set as justified text. That means that hyphenated words can occur and -headings with more than one line are stretched up to the text border. This is -a rather uncommon approach in typography. {\KOMAScript} therefore formats the +multi-line headings are stretched up to the text width. This approach is +rather uncommon in typography. {\KOMAScript} therefore sets the headings left aligned with hanging indentation using \Macro{raggedsection} -with the definition: +with the default: \begin{lstcode} \newcommand*{\raggedsection}{\raggedright} \end{lstcode} -This command can be redefined with \Macro{renewcommand}. +You can redefine this command with \Macro{renewcommand}. \begin{Example} You prefer justified headings, so you write in the preamble of your document: \begin{lstcode} @@ -2035,162 +2380,180 @@ This command can be redefined with \Macro{renewcommand}. \begin{lstcode} \let\raggedsection\relax \end{lstcode} - You will get a formatting of the headings which is very close to that - of the standard classes. It will become even closer when you combine - this change with the change of the element + You will get heading formatting which is very close to that of the standard + classes. It will become even closer when you combine this change with the + change to the \DescRef{\LabelBase.fontelement.disposition}\IndexFontElement{disposition} - mentioned above. + element mentioned above. \end{Example} Because\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}} some users want -for \DescRef{\LabelBase.cmd.chapter} another alignment than for all other -sections, you can change only \DescRef{\LabelBase.cmd.chapter} redefining -\Macro{raggedchapter}. The default of this command is usage of -\Macro{raggedsection}. So every change of \Macro{raggedsection} will also -change the alignment of chapter headings. - -Unlike all others, the headings of parts (\DescRef{\LabelBase.cmd.part}) will -be horizontally centered instead of set ragged right. This is because command -\Macro{raggedpart} is defined as +a different alignment for the \DescRef{\LabelBase.cmd.chapter} level than for +the other sectioning levels, you can change the +\DescRef{\LabelBase.cmd.chapter} justification separately by redefining +\Macro{raggedchapter}. By default, however, this command simply uses +\Macro{raggedsection}, so changing \Macro{raggedsection} indirectly affects +\Macro{raggedchapter}. + +By default, part headings (\DescRef{\LabelBase.cmd.part}) are set horizontally +centred rather than ragged right. This formatting is performed by the +\Macro{raggedpart} statement, which has the default definition \begin{lstcode} \let\raggedpart\centering \end{lstcode} -You may also redefine this using \Macro{renewcommand} too. +You can also redefine this command using \Macro{renewcommand}. \begin{Example} - You do not want different alignment at headings of - \DescRef{\LabelBase.cmd.part}. So you put + You want the headings for \DescRef{\LabelBase.cmd.part} to be formatted the + same as any other sectioning command. To do so, put \begin{lstcode} \renewcommand*{\raggedpart}{\raggedsection} \end{lstcode} - into the preamble of your document. In\textnote{Hint!} this case, - and unlike in the example above, \Macro{let} has not been used, because - \Macro{let} would give \Macro{raggedpart} the current meaning of - \Macro{raggedsection}. Further changes of \Macro{raggedsection} would then - stay disregarded at the usage of \Macro{raggedpart}. Doing the redefinition - using \Macro{renewcommand} gives \Macro{raggedpart} the meaning of - \Macro{raggedsection} not at definition time, but each time - \Macro{raggedpart} will be used. + in the preamble of your document. In\textnote{Hint!} this case, and unlike + in the example above, we did not use \Macro{let} because \Macro{let} would + set \Macro{raggedpart} to the underlying value of \Macro{raggedsection}. + Subsequent changes to \Macro{raggedsection} would then not change the + behaviour of \Macro{raggedpart}. By redefining with \Macro{renewcommand}, + \Macro{raggedpart} will use the current meaning of \Macro{raggedsection} at + the time it is used rather than when it was redefined. \end{Example}% % \EndIndexGroup \begin{Declaration} - \Macro{partformat}% - \Macro{chapterformat}% - \Macro{sectionformat}% - \Macro{subsectionformat}% - \Macro{subsubsectionformat}% - \Macro{paragraphformat}% - \Macro{subparagraphformat}% - \Macro{othersectionlevelsformat}\Parameter{sectioning - name}\Parameter{}\Parameter{counter output}% - \Macro{IfUsePrefixLine}\Parameter{then code}\Parameter{else code}% + \Macro{partformat} + \Macro{chapterformat} + \Macro{sectionformat} + \Macro{subsectionformat} + \Macro{subsubsectionformat} + \Macro{paragraphformat} + \Macro{subparagraphformat} + \Macro{othersectionlevelsformat}\Parameter{sectioning name}\Parameter{} + \Parameter{counter output} + \Macro{IfUsePrefixLine}\Parameter{then code}\Parameter{else code} \Macro{autodot} \end{Declaration}% -\Index{part>number}% -\Index{chapter>number}% -\Index{section>number}% -{\KOMAScript} has added a further logical level on top of -\Macro{the\PName{sectioning name}} to the output of the sectioning -numbers. The counters for the respective heading are not merely output. They -are formatted using the commands \Macro{partformat}, \Macro{chapterformat} -down to \Macro{subparagraphformat}\ChangedAt{v3.17}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}}. -\OnlyAt{\Class{scrbook}\and\Class{scrreprt}}Of course the command -\Macro{chapterformat} like \Macro{thechapter} does not exist in the class -\Class{scrartcl} but only in the classes \Class{scrbook} and \Class{scrreprt}. - -As described for option \DescRef{\LabelBase.option.numbers}\important{\DescRef{\LabelBase.option.numbers}} at the -beginning of this section (see \DescPageRef{\LabelBase.option.numbers}), -periods in section numbers should be handled for the German-speaking region -according to the rules given in \cite{DUDEN}. The command \Macro{autodot} in -{\KOMAScript} ensures that these rules are followed. In all levels -except for \DescRef{\LabelBase.cmd.part}, a dot is followed by a further \Macro{enskip}. This -corresponds to a horizontal skip of 0.5\Unit{em}. +{\KOMAScript} adds another logical layer above \Macro{the\PName{sectioning + name}} to format the sectioning numbers. The counters for each heading are +not merely output. They are formatted using the commands \Macro{partformat}, +\Macro{chapterformat}, down to +\Macro{subparagraphformat}\ChangedAt{v3.17}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}}. Of course the \Macro{chapterformat} +command, like \Macro{thechapter}, does not exist in the \Class{scrartcl} +class, but only in the \Class{scrbook} and \Class{scrreprt} +classes.\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} + +As already explained for the \DescRef{\LabelBase.option.numbers}% +\important{\DescRef{\LabelBase.option.numbers}} option at the beginning of +this section (see \DescPageRef{\LabelBase.option.numbers}), {\KOMAScript}'s +handling of points in section numbers implements the rules given in +\cite{DUDEN}, which are standard in German-language typography, in the +\Macro{autodot} command. In all levels except for +\DescRef{\LabelBase.cmd.part}, a point is followed by a further +\Macro{enskip}. This corresponds to a horizontal skip of 0.5\Unit{em}. Since \KOMAScript~3.17\ChangedAt{v3.17}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} the command + \Class{scrreprt}\and \Class{scrartcl}}, the command \Macro{othersectionlevelsformat} is used only in rare circumstances, i.\,e., if the corresponding format command to a section command does not exist or is -\Macro{relax}. This should not happen for all section commands defined by -\KOMAScript{} itself. Therefore the command is not officially documented any -longer. Nevertheless, if a compatibility level prior to 3.17 (see option +\Macro{relax}. This should not happen for any section commands defined by +\KOMAScript{} itself. Therefore the command is no longer officially +documented. Nevertheless, if you select a compatibility level prior to +3.17\important{\OptionValueRef{\LabelBase}{version}{3.17}} (see option \DescRef{\LabelBase.option.version}, \autoref{sec:\LabelBase.compatibilityOptions}, -\DescPageRef{\LabelBase.option.version}) has been selected, commands -\Macro{sectionformat} down to \Macro{subparagraphformat} are ignored by -\KOMAScript{}. In this case \Macro{othersectionlevelsformat} indeed will be -used. - -The formatting commands can be redefined using \Macro{renewcommand} to -fit them to your personal needs. The following original definitions -are used by the {\KOMAScript} classes: +\DescPageRef{\LabelBase.option.version}), commands \Macro{sectionformat} down +to \Macro{subparagraphformat} are ignored by \KOMAScript{}. Instead, these +layers will continue to use \Macro{othersectionlevelsformat}. + +You can redefine the formatting commands using \Macro{renewcommand} to fit +them to your personal needs. The following default definitions are used by the +{\KOMAScript} classes: \begin{lstcode} \newcommand*{\partformat}{\partname~\thepart\autodot} \newcommand*{\chapterformat}{% \mbox{\chapappifchapterprefix{\nobreakspace}\thechapter \autodot\IfUsePrefixLine{}{\enskip}}} \newcommand*{\sectionformat}{\thesection\autodot\enskip} + \newcommand*{\subsectionformat}{% + \thesubsection\autodot\enskip} + \newcommand*{\subsubsectionformat}{% + \thesubsubsection\autodot\enskip} + \newcommand*{\paragraphformat}{\theparagraph\autodot\enskip} + \newcommand*{\subparagraphformat}{% + \thesubparagraph\autodot\enskip} \newcommand*{\othersectionlevelsformat}[3]{% #3\autodot\enskip} \end{lstcode} -The definitions of the lower levels correspond to -\Macro{sectionformat}. -Because\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}} of -\Macro{IfUsePrefixLine} command \Macro{chapterformat} should not be used -outside of \DescRef{\LabelBase.cmd.chapter}. \Macro{IfUsePrefixLine} is only valid inside -section commands of \KOMAScript{}. In this case, it executes the \PName{then - code} if a prefix line for the number is used, but \PName{else code} -otherwise. +Because\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}} it uses +\Macro{IfUsePrefixLine}, \Macro{chapterformat} should not be used outside of +\DescRef{\LabelBase.cmd.chapter}. \Macro{IfUsePrefixLine} is only valid inside +\KOMAScript{} sectioning commands. Within those commands, it executes the +\PName{then code} if a prefix line for the number is used and the \PName{else +code} otherwise. -Do\textnote{Attention!} not forget to change \Macro{newcommand} into -\Macro{renewcommand} if you like to re-define one of the commands. +Please also remember\textnote{Attention!} to replace \Macro{newcommand} with +\Macro{renewcommand} if you want to redefine one of the commands above. \begin{Example} - Assume that when using \DescRef{\LabelBase.cmd.part} you do not want the word - ``Part'' written in front of the part number. You could use the + Suppose you do not want the word ``Part'' written in front of the part + number when you use \DescRef{\LabelBase.cmd.part}. You can put the following command in the preamble of your document: \begin{lstcode} \renewcommand*{\partformat}{\thepart\autodot} \end{lstcode} - Strictly speaking, you could do without \Macro{autodot} at this point and - insert a fixed dot instead. As \DescRef{\LabelBase.cmd.part} is numbered with roman numerals, - according to \cite{DUDEN} a period has to be applied. However, you thereby - give up the possibility to use one of the options - \OptionValueRef{\LabelBase}{numbers}{endperiod} and - \OptionValueRef{\LabelBase}{numbers}{noendperiod} and optionally depart from - the rules. More details concerning class options can be found at + In fact, you could do without \Macro{autodot} here and insert a fixed point + instead. Since \DescRef{\LabelBase.cmd.part} is numbered with Roman numerals, + it must be followed by a point according to \cite{DUDEN}. However, by using + \Macro{autodot} you retain the ability to use the + \DescRef{\LabelBase.option.numbers}% + \important{\DescRef{\LabelBase.option.numbers}} option + \OptionValueRef{\LabelBase}{numbers}{endperiod} and thus deviate from + the rule. You can find more details concerning class options on \DescPageRef{\LabelBase.option.numbers}. - An additional possibility could be to place the section numbers in the - left margin in such a way that the heading text is left aligned with - the surrounding text. This can be accomplished with: + Another possibility is to place the section numbers in the left margin in + such a way that the heading text is left aligned with the surrounding text. + You can accomplish this with: \begin{lstcode} \renewcommand*{\sectionformat}{% \makebox[0pt][r]{\thesection\autodot\enskip}} \renewcommand*{\subsectionformat}{% \makebox[0pt][r]{\thesubsection\autodot\enskip}} \renewcommand*{\subsubsectionformat}{% - \makebox[0pt][r]{\thesubsubsection\autodot\enskip}} + \makebox[0pt][r]{% + \thesubsubsection\autodot\enskip}} \renewcommand*{\paragraphformat}{% \makebox[0pt][r]{\theparagraph\autodot\enskip}} \renewcommand*{\paragraphformat}{% - \makebox[0pt][r]{\thesubparagraph\autodot\enskip}} + \makebox[0pt][r]{% + \thesubparagraph\autodot\enskip}} \end{lstcode} - See \cite{latex:usrguide} for more information about the optional arguments - of \Macro{makebox}. + The optional arguments of the \Macro{makebox} command require \LaTeX{} to + create a zero-width box with right-justified content. As a result, the + contents of the box are output to the left of the current position.% + \iffree{}{ %Umbruchkorrekturtext + This popular trick avoids the need first to measure the width of the + number and the spacing, and then to change the current position + appropriately with \Macro{hspace}.} + You can find more about the optional arguments of \Macro{makebox} in + \cite{latex:usrguide}. \end{Example} -If you would like to change more than only the printing of the counter of a -heading, please have a look at -\DescRef{maincls-experts.cmd.chapterlineswithprefixformat}, -\DescRef{maincls-experts.cmd.chapterlinesformat}, -\DescRef{maincls-experts.cmd.sectionlinesformat}, and -\DescRef{maincls-experts.cmd.sectioncatchphraseformat} in -\autoref{sec:maincls-experts.experts} from -\DescPageRef{maincls-experts.cmd.chapterlineswithprefixformat}.% +For formatting changes in the headings that go beyond merely formatting the +unit number, please refer to +\DescRef{maincls-experts.cmd.partlineswithprefixformat}% +\IndexCmd{partlineswithprefixformat}, +\DescRef{maincls-experts.cmd.chapterlineswithprefixformat}% +\IndexCmd{chapterlineswithprefixformat} and +\DescRef{maincls-experts.cmd.chapterlinesformat}\IndexCmd{chapterlinesformat}, +as well as +\DescRef{maincls-experts.cmd.sectionlinesformat}\IndexCmd{sectionlinesformat} +and its \DescRef{maincls-experts.cmd.sectioncatchphraseformat}% +\IndexCmd{sectioncatchphraseformat} format in +\autoref{sec:maincls-experts.experts}, starting from +\DescPageRef{maincls-experts.cmd.partlineswithprefixformat}.% \EndIndexGroup @@ -2198,28 +2561,26 @@ heading, please have a look at \Macro{chapappifchapterprefix}\Parameter{additional text}% \Macro{chapapp} \end{Declaration}% -These\OnlyAt{\Class{scrbook}\and\Class{scrreprt}}% -\ChangedAt{v2.8o}{\Class{scrbook}\and\Class{scrreprt}} two commands -are not only used internally by {\KOMAScript} but are also provided to -the user. Later it will be shown how they can be used, for example, to -redefine other commands. - -Using the layout option -\OptionValueRef{\LabelBase}{chapterprefix}{true}\important{\DescRef{\LabelBase.option.chapterprefix}} -(see \DescPageRef{\LabelBase.option.chapterprefix}) -\Macro{chapappifchapterprefix} outputs the word -``Chapter''\Index{chapter>heading} in the main part of the document in the -current language, followed by \PName{additional text}. In the +These\ChangedAt{v2.8o}{\Class{scrbook}\and\Class{scrreprt}} two commands are +used internally by {\KOMAScript} and also made available to the user. Later, +you will see how to use them, for example to redefine other commands.% +\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} + +If you use the layout option \OptionValueRef{\LabelBase}{chapterprefix}{true}% +\important{\DescRef{\LabelBase.option.chapterprefix}} (see +\DescPageRef{\LabelBase.option.chapterprefix}), \Macro{chapappifchapterprefix} +outputs the word ``Chapter''\Index{chapter>heading} in the body of the text in +the current language, followed by \PName{additional text}. In the appendix\Index{appendix}, the word ``Appendix'' in the current language is output instead, followed by \PName{additional text}. If the option \OptionValue{\LabelBase}{chapterprefix}{false} is set, then nothing is output. -The command \Macro{chapapp} always outputs the word ``Chapter'' or -``Appendix''. In this case the selection of option -\DescRef{\LabelBase.option.chapterprefix} has no effect. +The \Macro{chapapp} command always outputs the word ``Chapter'' or +``Appendix'', regardless of the setting of the +\DescRef{\LabelBase.option.chapterprefix} option. -Since chapters only exist in the classes \Class{scrbook} and -\Class{scrreprt}, these commands only exist in these classes.% +Since chapters only exist in the classes \Class{scrbook} and \Class{scrreprt}, +these commands only exist in these classes.% % \EndIndexGroup @@ -2235,104 +2596,101 @@ Since chapters only exist in the classes \Class{scrbook} and \Macro{subsectionmarkformat} \end{Declaration}% \begin{Explain}% - As mentioned in \autoref{sec:\LabelBase.pagestyle} the page style - \PValue{headings} works with automatic running heads\Index{running - head}. For this, the commands \Macro{chaptermark} and \Macro{sectionmark}, - or \Macro{sectionmark} and \Macro{subsectionmark}, respectively, are - defined. Every structuring command (\DescRef{\LabelBase.cmd.chapter}, - \DescRef{\LabelBase.cmd.section}, etc.) automatically carries out the - respective \Macro{\dots mark} command. The parameter passed contains the - text of the section heading\Index{heading}. The respective section number is - added automatically in the \Macro{\dots mark} command. The formatting is - done according to the section level with one of the three commands - \Macro{chaptermarkformat}, \Macro{sectionmarkformat}, or - \Macro{subsectionmarkformat}. - - Please note\textnote{Attention!}, the running heads of + As mentioned in \autoref{sec:\LabelBase.pagestyle}, the + \DescRef{\LabelBase.pagestyle.headings}\IndexPagestyle{headings}% + \important{\DescRef{\LabelBase.pagestyle.headings}} page style works with + automatic running heads\Index{running heads>automatic}. For this, the + commands \Macro{chaptermark} and \Macro{sectionmark}, or \Macro{sectionmark} + and \Macro{subsectionmark}, are defined accordingly. Every sectioning + command (\DescRef{\LabelBase.cmd.chapter}, \DescRef{\LabelBase.cmd.section}, + etc.) automatically executes the corresponding \Macro{\dots mark} command. + The parameter passed contains the text of the section heading% + \Index{heading}. The corresponding section number is added automatically in + the \Macro{\dots mark} command. The formatting is done according to the + sectioning level with one of the three commands \Macro{chaptermarkformat}, + \Macro{sectionmarkformat}, or \Macro{subsectionmarkformat}. + + Note\textnote{Attention!} that the running heads of \DescRef{\LabelBase.cmd.addchap}\IndexCmd{addchap} and \DescRef{\LabelBase.cmd.addsec}\IndexCmd{addsec} are also based on - \Macro{chaptermark} and \Macro{addsecmark} but locally set counter - \DescRef{\LabelBase.counter.secnumdepth} to a value that makes chapters - respectively sections not numbered. You should pay attention for this - especially if you redefine \Macro{chaptermark} or \Macro{sectionmark} (see - \Macro{ifnumbered} on \DescPageRef{\LabelBase.cmd.ifnumbered}). The star - variants \DescRef{\LabelBase.cmd.addchap*} and - \DescRef{\LabelBase.cmd.addsec*} use additional commands \Macro{addchapmark} - and \Macro{addsecmark} that are defined also basing on \Macro{chaptermark} - and \Macro{sectionmark} with local changes of - \DescRef{\LabelBase.counter.secnumdepth}. - - \OnlyAt{\Class{scrbook}\and\Class{scrreprt}}Of course there is no command - \Macro{chaptermark} or \Macro{chaptermarkformat} in - \Class{scrartcl}. \OnlyAt{\Class{scrartcl}}Accordingly, - \Macro{subsectionmark} and \Macro{subsectionmarkformat} exist only in - \Class{scrartcl}. This changes when you use the \Package{scrlayer-scrpage} - package (see \autoref{cha:scrlayer-scrpage}).\par + \Macro{chaptermark} and \Macro{sectionmark}. However, the + \DescRef{\LabelBase.counter.secnumdepth} counter is set locally to a value + that switches off the numbering of chapters or sections. You should consider + this, for example, if you redefine \Macro{chaptermark} or + \Macro{sectionmark} (see \Macro{ifnumbered} on + \DescPageRef{\LabelBase.cmd.ifnumbered}). The starred variants + \DescRef{\LabelBase.cmd.addchap*} and \DescRef{\LabelBase.cmd.addsec*} use + additional commands \Macro{addchapmark} and \Macro{addsecmark} that are also + defined based on \Macro{chaptermark} and \Macro{sectionmark} with local + changes of \DescRef{\LabelBase.counter.secnumdepth}. + + Although\OnlyAt{\Class{scrartcl}} there is no \Macro{chaptermark} or + \Macro{chaptermarkformat} command in \Class{scrartcl}, there are two + commands, \Macro{subsectionmark} and \Macro{subsectionmarkformat}, which + exist only in \Class{scrartcl}. However using the + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + \IndexPackage{scrlayer-scrpage} package changes this (see + \autoref{cha:scrlayer-scrpage}). \end{Explain} -Similar to \DescRef{\LabelBase.cmd.partformat} down to -\DescRef{\LabelBase.cmd.subparagraphformat} for formatting the numbers in the -headings, the commands \Macro{chaptermarkformat} (not in \Class{scrartcl}), -\Macro{sectionmarkformat}, and \Macro{subsectionmarkformat} (only in -\Class{scrartcl}) define the formatting of the sectioning numbers in the -automatic running heads. They can be adapted to your personal needs with -\Macro{renewcommand}. The original definitions for the {\KOMAScript} classes -are: +Just as numbers in the sectioning-command headers are formatted with +\DescRef{\LabelBase.cmd.partformat} down to +\DescRef{\LabelBase.cmd.subparagraphformat}, \Macro{chaptermarkformat}, +\Macro{sectionmarkformat}, and \Macro{subsectionmarkformat} define the +formatting of the sectioning numbers in the automatic running heads. They can +be adapted to your personal needs with \Macro{renewcommand}. The original +definitions for the {\KOMAScript} classes are: \begin{lstcode} \newcommand*{\chaptermarkformat}{% \chapappifchapterprefix{\ }\thechapter\autodot\enskip} - \newcommand*{\sectionmarkformat}{\thesection\autodot\enskip} + \newcommand*{\sectionmarkformat}{% + \thesection\autodot\enskip} \newcommand*{\subsectionmarkformat}{% \thesubsection\autodot\enskip} \end{lstcode} \begin{Example} - Suppose you want to prepend the word ``Chapter'' to the chapter - number in the running heading. For example you could insert the - following definition in the preamble of your document: + Suppose you want the word ``Chapter'' to precede the chapter number in the + running head. You could put the following definition in the preamble of your + document: \begin{lstcode} \renewcommand*{\chaptermarkformat}{% \chapapp~\thechapter\autodot\enskip} \end{lstcode} \end{Example} -As you can see, both the commands -\DescRef{\LabelBase.cmd.chapappifchapterprefix} and -\DescRef{\LabelBase.cmd.chapapp} explained above are used here.% -% +As you can see, both \DescRef{\LabelBase.cmd.chapapp} and +\DescRef{\LabelBase.cmd.chapappifchapterprefix}, explained above, are used +here.% \EndIndexGroup \begin{Declaration} - \Counter{secnumdepth}% - \Macro{partnumdepth}% - \Macro{chapternumdepth}% - \Macro{sectionnumdepth}% - \Macro{subsectionnumdepth}% - \Macro{subsubsectionnumdepth}% - \Macro{paragraphnumdepth}% + \Counter{secnumdepth} + \Macro{partnumdepth} + \Macro{chapternumdepth} + \Macro{sectionnumdepth} + \Macro{subsectionnumdepth} + \Macro{subsubsectionnumdepth} + \Macro{paragraphnumdepth} \Macro{subparagraphnumdepth} \end{Declaration}% -\BeginIndex{}{numbering}% -Section levels in the classes \Class{scrbook}\IndexClass{scrbook} and -\Class{scrreport}\IndexClass{scrreprt} are, by default, numbered from -\DescRef{\LabelBase.cmd.part}\IndexCmd{part}\IndexCmd{chapter}\IndexCmd{section} -down to \DescRef{\LabelBase.cmd.subsection}\IndexCmd{subsection}. In class -\Class{scrartcl}\IndexClass{scrartcl} the default numbering is from +\BeginIndex{}{Nummerierung}% +Normally, the \Class{scrbook}\IndexClass{scrbook} and +\Class{scrreport}\IndexClass{scrreprt} classes number the section headings +from \DescRef{\LabelBase.cmd.part}\IndexCmd{part}\IndexCmd{chapter}% +\IndexCmd{section} down to +\DescRef{\LabelBase.cmd.subsection}\IndexCmd{subsection} and the +\Class{scrartcl}\IndexClass{scrartcl} class numbers them from \DescRef{\LabelBase.cmd.part} down to -\DescRef{\LabelBase.cmd.subsubsection}\IndexCmd{subsubsection}. The actual -depth to which headings will be numbered is controlled by the \LaTeX{} counter -\Counter{secnumdepth}. Since version~3.12 \KOMAScript{} provides the commands -\Macro{partnumdepth} to \Macro{subparagraphnumdepth} which return the number -that corresponds to the level they bear in their name. This saves users the -trouble of having to remember abstract numbers and allows them to define the -depth to which headings should be numbered with relative ease. - -\KOMAScript{} provides the commands \Macro{partnumdepth} to -\Macro{subparagraphnumdepth} so\ChangedAt{v3.12}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} users do not have to remember -abstract numbers, to be able to define the section level down to which -headings should be numbered. These commands stand for the corresponding -numbers of the section levels.% +\DescRef{\LabelBase.cmd.subsubsection}\IndexCmd{subsubsection}. The actual +depth to which headings are numbered is controlled by the \LaTeX{} counter +\Counter{secnumdepth}. + +To\ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} +save users the trouble of having to remember abstract numbers, the commands +\Macro{partnumdepth} to \Macro{subparagraphnumdepth} return the appropriate +number for the section level in their name. + \begin{Example} - For a book project you want the section levels from part down to the section + For a book project, you want the section levels from part down to section to be numbered. To achieve this, you have to set counter \Counter{secnumdepth} to the value represented by \Macro{sectionnumdepth} in the preamble of your document: @@ -2340,37 +2698,34 @@ numbers of the section levels.% \setcounter{secnumdepth}{\sectionnumdepth} \end{lstcode} \end{Example} -Redefining these commands is not allowed. Doing so could lead to unexpected -results not only with \KOMAScript{} but also with third party packages. Thus, -it is recommended to never redefine any of them. - -Do not confuse the counters \Counter{secnumdepth} and -\DescRef{\LabelBase.counter.tocdepth}, please refer to the explanation -concerning the counter \DescRef{\LabelBase.counter.tocdepth} in -\autoref{sec:\LabelBase.toc}, -\DescPageRef{\LabelBase.counter.tocdepth}. Actually, depending on the class -you are using, the meaning of the values of the counters \Counter{secnumdepth} -and \DescRef{\LabelBase.counter.tocdepth} may deviate from one another for the -same section level.% +No provision is made for redefining these commands. Doing so could lead to +unexpected results, not only with \KOMAScript{} but also with third party +packages. Thus, you should never redefine them. + +Do\textnote{Attention!} not confuse the \Counter{secnumdepth} and +\DescRef{\LabelBase.counter.tocdepth} counters (see +\autoref{sec:\LabelBase.toc}, \DescPageRef{\LabelBase.counter.tocdepth}). +Depending on the class you are using, the meaning of the values of the +\Counter{secnumdepth} and \DescRef{\LabelBase.counter.tocdepth} counters may +differ for the same section level.% +% \EndIndexGroup - \begin{Declaration} \Macro{ifnumbered}\Parameter{section level}% \Parameter{then code}\Parameter{else code}% \Macro{ifunnumbered}\Parameter{section level}% \Parameter{then code}\Parameter{else code} \end{Declaration} -After\ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} describing above how to define down to which section level -headings are numbered, the commands \Macro{ifnumbered} and -\Macro{ifunnumbered} can be used to execute code depending on whether a -\PName{section level} is numbered or not. If the current setting of -\DescRef{\LabelBase.counter.secnumdepth} stipulates that a \PName{section - level} will be numbered, the \PName{then code} after \Macro{ifnumbered} gets -executed. If it is not numbered, the \PName{else code} gets executed. The +The\ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} commands \Macro{ifnumbered} and \Macro{ifunnumbered} +determine which section-level headings are numbered, using the technique +described above, and execute code depending on whether a \PName{section level} +is numbered or not. If a \PName{section level} is numbered with the current +settings, \Macro{ifnumbered} executes the \PName{then code}. If the section +level is unnumbered, the \PName{else code} is executed. The \Macro{ifunnumbered} command behaves in exactly the opposite manner, executing -the \PName{then code} if the current level is not numbered and the \PName{else +the \PName{then code} if the current level is unnumbered and the \PName{else code} if it is. The \PName{section level} parameter is simply the \LaTeX{} name of a section like \PValue{part}, \PValue{chapter}, \PValue{section}, \PValue{subsection}, \PValue{subsubsection}, \PValue{paragraph} oder @@ -2379,36 +2734,36 @@ name of a section like \PValue{part}, \PValue{chapter}, \PValue{section}, \PValue{subparagraph}. \KOMAScript{} itself uses these tests, for example, in the definition of -\DescRef{\LabelBase.cmd.chaptermark}\IndexCmd{chaptermark} within page style -\PageStyle{headings}\IndexPagestyle{headings}. This indirectly guarantees that -headings inserted by \DescRef{\LabelBase.cmd.addchap} do not set a number -inside the running head (see also \DescRef{\LabelBase.cmd.addchapmark}, +\DescRef{\LabelBase.cmd.chaptermark}\IndexCmd{chaptermark} in the +\DescRef{\LabelBase.pagestyle.headings}\IndexPagestyle{headings} page style. +This indirectly ensures that headings inserted by +\DescRef{\LabelBase.cmd.addchap} do not set a number inside the running head +(see also \DescRef{\LabelBase.cmd.addchapmark}, \DescPageRef{\LabelBase.cmd.addchapmark}).% \EndIndexGroup \begin{Declaration} \Macro{setpartpreamble}% - \OParameter{position}\OParameter{width}\Parameter{preamble}% + \OParameter{position}\OParameter{width}\Parameter{preamble} \Macro{setchapterpreamble}% \OParameter{position}\OParameter{width}\Parameter{preamble} \end{Declaration}% Parts\OnlyAt{\Class{scrbook}\and \Class{scrreprt}}\Index{part>preamble}\Index{chapter>preamble} and chapters -in {\KOMAScript} can be started with a \PName{preamble}. This is particularly -useful when you are using a two column layout with the class option -\Option{twocolumn}\IndexOption{twocolumn}, since the heading together with the -\PName{preamble} is always set in a one column layout. The \PName{preamble} -can comprise more than one paragraph. The command to output the -\PName{preamble} has to be placed before the respective \DescRef{\LabelBase.cmd.part}, +in {\KOMAScript} can be given a \PName{preamble}. This is particularly useful +when you are using a two-column format with the class option +\Option{twocolumn}\IndexOption{twocolumn}, since the heading and the +\PName{preamble} are always set in a one-column layout. The \PName{preamble} +can contain more than one paragraph. The command to set the \PName{preamble} +must come before the respective \DescRef{\LabelBase.cmd.part}, \DescRef{\LabelBase.cmd.addpart}, \DescRef{\LabelBase.cmd.chapter}, or \DescRef{\LabelBase.cmd.addchap} command. \begin{Example} - You are writing a report about the condition of a company. You - organize the report in such a way that every department gets its own - partial report. Every one of these parts should be introduced by an - abstract on the corresponding title page. You could write the - following: + You are writing a report about the condition of a company. You organize the + report in such a way that every department gets its own partial report. + Each of these parts should be introduced by an abstract on the corresponding + title page. You could write the following: \begin{lstcode} \setpartpreamble{% \begin{abstract} @@ -2423,10 +2778,10 @@ can comprise more than one paragraph. The command to output the (see \DescPageRef{\LabelBase.option.headings}) and the options for the \DescRef{\LabelBase.env.abstract} environment\IndexEnv{abstract} (see \autoref{sec:\LabelBase.abstract}, - \DescPageRef{\LabelBase.option.abstract}), the result would look - similar to: + \DescPageRef{\LabelBase.option.abstract}), the result will look something + like this: \begin{ShowOutput}\centering - {\LARGE\usekomafont{disposition} Part III.\par\vspace{20pt}} + {\LARGE\usekomafont{disposition} Part III.\par\vspace{14pt}} {\LARGE\usekomafont{disposition} Department for Word Processing\strut\par} \begin{quote}\small \vspace{4ex} @@ -2440,46 +2795,53 @@ can comprise more than one paragraph. The command to output the \end{quote} \end{ShowOutput} \end{Example} -Please\textnote{Attention!} note that it is \emph{you} who is responsible for -the spaces between the heading, preamble and the following text. Please note -also that there is no \DescRef{\LabelBase.env.abstract} environment in the -class \Class{scrbook} (see \autoref{sec:\LabelBase.abstract}, +Please\textnote{Attention!} note that \emph{you} are responsible for the +spacing between the heading, preamble, and the following text. Note also that +there is no \DescRef{\LabelBase.env.abstract} environment in the +\Class{scrbook} class (see \autoref{sec:\LabelBase.abstract}, \DescPageRef{\LabelBase.env.abstract}). -The\ChangedAt{v2.8p}{\Class{scrbook}\and\Class{scrreprt}} first -optional argument \PName{position} determines the position at which -the preamble is placed with the help of one or two letters. For the -vertical placement there are two possibilities at present: +The\ChangedAt{v2.8p}{\Class{scrbook}\and\Class{scrreprt}} first optional +argument, \PName{position}, determines the position at which the preamble +is placed with the help of one or two letters. For vertical placement +there are two possibilities at present: \begin{labeling}[~--]{\quad\PValue{o}}\itemsep=0pt \item [\quad\texttt{o}] above the heading \item [\quad\texttt{u}] below the heading \end{labeling} -You can insert one preamble above and another below a heading. For the -horizontal placement you have the choice between three alignments: +You can therefore put one preamble above and another below a heading. For +horizontal placement you have three options: \begin{labeling}[~--]{\quad\PValue{o}}\itemsep=0pt \item [\quad\texttt{l}] left-aligned \item [\quad\texttt{r}] right-aligned -\item [\quad\texttt{c}] centered +\item [\quad\texttt{c}] centred \end{labeling} -However, this does not output the text of the \PName{preamble} in such -a manner, but inserts a box whose width is determined by the second -optional argument \PName{width}. If you leave out this second argument -the whole text width is used. In that case the option for horizontal -positioning will have no effect. You can combine exactly one letter -from the vertical with one letter from the horizontal positioning. - -A more often usage of \Macro{setchapterpreamble} would be something like a -smart slogan or dictum to a heading. The command -\DescRef{\LabelBase.cmd.dictum}\IndexCmd{dictum}, that may be used for this, -will be described at the next section. You will also find an example there. +This setting does not affect the alignment of the text in the +\PName{preamble}. Instead, it aligns the box that contains the preamble. The +width of this box is determined by the second optional argument, +\PName{width}. If you omit this second argument, the box uses the full text +width. In that case, the option for horizontal positioning has no effect. You +can combine exactly one letter from the vertical with one letter from the +horizontal positioning. + +A typical use for \Macro{setchapterpreamble} would be something like an +epigraph, a wise saying, or a dictum. The +\DescRef{\LabelBase.cmd.dictum}\IndexCmd{dictum} command, which you can use +for this purpose, is described in the next section. You will also find an +example there. Please note\textnote{Attention!} that a \PName{preamble} placed above the -chapter headings will be set into the already existing vertical space above -the heading. The heading will not be moved down. It is you who is responsible -for ensuring that the preamble is small enough and the space is -sufficient. See also \DescRef{maincls-experts.cmd.chapterheadstartvskip} in +heading is set within the existing vertical space above the heading. The +heading will not be moved down. You are therefore responsible for ensuring +that the \PName{preamble} is not too large and that the space above the +heading is sufficient. See also the \Option{beforeskip} setting for +\DescRef{maincls-experts.cmd.RedeclareSectionCommand} in \autoref{sec:maincls-experts.experts}, -\DescPageRef{maincls-experts.cmd.chapterheadstartvskip} for this.% +\autoref{tab:maincls-experts.declarechapterstyle.keys}, +\autopageref{tab:maincls-experts.declarechapterstyle.keys}. +% +% +\EndIndexGroup % \EndIndexGroup @@ -2488,39 +2850,40 @@ sufficient. See also \DescRef{maincls-experts.cmd.chapterheadstartvskip} in \LoadCommonFile{lists}% \section{Lists} - -\section{Math} +\section{Mathematics} \seclabel{math}% \BeginIndexGroup \BeginIndex{}{equations}% \BeginIndex{}{formulas}% \BeginIndex{}{mathematics}% -There are no math environments implemented in the \KOMAScript{} -classes. Instead of this, the math features of the \LaTeX{} kernel have been -supported. With this also, the options \DescRef{\LabelBase.option.leqno} and -\DescRef{\LabelBase.option.fleqn} are available. - -You will not find a description of the math environments of the \LaTeX{} kernel -here. If you want to use \Environment{displaymath}\IndexEnv{displaymath}, -\Environment{equation}\IndexEnv{equation}, and -\Environment{eqnarray}\IndexEnv{eqnarray} you should read a short introduction -into \LaTeX{} like \cite{lshort}. But\textnote{Hint!} if you want more than -very simple mathematics, usage of package \Package{amsmath} would be -recommended (see \cite{package:amsmath}). +\KOMAScript{} classes do not provide their own environments for formulas, +systems of equations, or similar mathematical elements. Instead, \KOMAScript{} +relies fully on the maths features of the \LaTeX{} kernel. This also applies to +the the options \DescRef{\LabelBase.option.leqno} and +\DescRef{\LabelBase.option.fleqn}. + +You will not find a description of the maths environments of the \LaTeX{} +kernel here. If you want to use +\Environment{displaymath}\IndexEnv{displaymath}, +\Environment{equation}\IndexEnv{equation}, or +\Environment{eqnarray}\IndexEnv{eqnarray} you should read an introduction to +\LaTeX{} like \cite{lshort}. But\textnote{Hint!} if you want more than very +simple mathematics, you should use the \Package{amsmath} package (see +\cite{package:amsmath}). \begin{Declaration} \Option{leqno} \end{Declaration}% -Equations are normally numbered\Index{equation>number} on the right. The -standard option \Option{leqno} causes the standard option file -\File{leqno.clo} to be loaded. The equations are then numbered on the -left. This\textnote{Attention!} option has to be used as an optional argument -of \DescRef{\LabelBase.cmd.documentclass}. Usage as an argument of -\DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption} is -not supported. This would not make sense, because the recommended math package -\Package{amsmath} supports the option at loading time only too and would not -react on run-time changes of the option. +Equations are normally numbered\Index{equation>number} on the right. The +\Option{leqno} option loads the standard option file \File{leqno.clo}. The +equations are then numbered on the left. You\textnote{Attention!} must use +this option as an optional argument of \DescRef{\LabelBase.cmd.documentclass}. +Using it as an argument of \DescRef{\LabelBase.cmd.KOMAoptions} or +\DescRef{\LabelBase.cmd.KOMAoption} is not supported. The latter +would not make sense because the recommended maths package \Package{amsmath} +can only respond to this option at load time and does not react to run-time +changes of the option. % \EndIndexGroup @@ -2528,293 +2891,296 @@ react on run-time changes of the option. \begin{Declaration} \Option{fleqn} \end{Declaration}% -Displayed equations\Index{equation>alignment} are normally centered. The -standard option \Option{fleqn} causes the standard option file -\File{fleqn.clo} to be loaded. Displayed equations are then -left-justified. This option may be used as an optional argument of -\DescRef{\LabelBase.cmd.documentclass} but not as an argument of -\DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption}. -The latter would not make sense, because the recommended math package -\Package{amsmath} supports the option at loading time only too and would not -react on run-time changes of the option. +Displayed equations\Index{equation>alignment} are normally centred. The +standard option \Option{fleqn} loads the standard option file +\File{fleqn.clo}. Displayed equations are then left-justified. +You\textnote{Attention!} must use this option as an optional argument of +\DescRef{\LabelBase.cmd.documentclass}. Using it as an argument of +\DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption} is +not supported. The latter would not make sense because the recommended maths +package \Package{amsmath} can only respond to this option at load time and +does not react to run-time changes of the option. % \EndIndexGroup % \EndIndexGroup -\section{Floating Environments of Tables and Figures} +\section{Floating Environments for Tables and Figures} \seclabel{floats} \BeginIndexGroup \BeginIndex{}{floats}% \BeginIndex{}{tables}% \BeginIndex{}{figures}% -With the floating environments, {\LaTeX} offers a very capable and comfortable -mechanism for automatic placement of figures\Index{figure} and -tables\Index{table}. +With the floating environments, {\LaTeX} offers a powerful and convenient +mechanism to arrange figures\Index{figure} and tables\Index{table} +automatically. % Im Deutschen ist hier ein Absatz, den wir nicht uebernehmen! -But\textnote{Attention!} often these floating environments\Index[indexmain] -{floating environments} are slightly misunderstood by beginners. They often -ask for a fixed position of a table or figure within the text. However, since -these floating environments are being referenced in the text this is not -necessary in most cases. It is also not sensible because such an object can -only be set on the page if there is enough space left for it. If this is not -the case the object would have to be shifted onto the next page, thereby -possibly leaving a huge blank space on the page before. - -Often\textnote{Attention!} one finds in a document for every floating object -the same optional argument for positioning the object. This also makes no -sense. In such cases one should rather change the standard parameter -globally. For more details refer to \cite{DANTE:FAQ}. +Frequently,\textnote{Attention!} beginners do not properly understand these +floating environments\Index[indexmain]{floating environments}. They often ask +to specify the exact position of a table or figure within the text. However, +this is usually unnecessary, since the text will contain references to these +floating environments. It is also not sensible because such an object can only +be set on the page if there is enough space left for it. If this is not the +case, the object would have to be shifted onto the next page, possibly leaving +a huge empty space on the previous page. + +Often\textnote{Attention!} a document will use the same optional argument to +position every floating object. This also makes no sense. In such cases, you +should instead change the default value globally. For more details, see +\cite{DANTE:FAQ}. + +One\textnote{Attention!} final, important note before starting this section: +most of mechanisms described here, which extend the capabilities of the +standard classes, no longer work correctly when used with packages that modify +the appearance of figure and table captions. This should be self-evident, but +it is often overlooked. -One\textnote{Attention!} last important note before starting this section: -most mechanisms described here which extend the capabilities of the standard -classes no longer work correctly when used together with packages which modify -the typesetting of captions of figures and tables. This should be self -evident, but it is often not understood. \begin{Declaration} - \OptionVName{captions}{selection} + \OptionVName{captions}{setting} \end{Declaration} -The standard classes format titles of floating environments, which are placed -with \DescRef{\LabelBase.cmd.caption}\IndexCmd{caption} (see below), like signatures. They -differentiate between one-line and multi-line table or figure -captions. One-line captions are centered while multi-line captions are -left-justified. - -\leavevmode\phantomsection\nobreak -\label{desc:\LabelBase.option.captions.tableheading}\nobreak -For tables, however, headings are often used. That's because there may -be tables that span several pages. Surely the reader wants to know the -purpose of the table at the first page already. Furthermore tables -will be read row by row from top down to bottom. So there are at least -two good reasons to generally use table -headings. \KOMAScript{}\important{\OptionValue{captions}{tableheading}} -therefor supports option \OptionValue{captions}{tableheading}% -\IndexOption{captions~=\PValue{tableheading}}, which changes the -caption format into headings at tables only. - -Please note\textnote{Attention!} that multi-page tabulars may not use any -floating environment. To have an automatic page break at any kind of tabular you -also need additional packages like \Package{longtable}\IndexPackage{longtable} -(see \cite{package:longtable}) or \Package{tabu}\IndexPackage{tabu} (see -\cite{package:tabu}). - -You may switch back\important[i]{\begin{tabular}[t]{@{}l@{}} - \Option{captions=}\\ - \quad\PValue{tablesignature} - \end{tabular}} to the default table signatures using -\OptionValue{captions}{tablesignature}% -\IndexOption{captions~=\PValue{tablesignature}}. -Note\textnote{Attention!} that using any of these options does not change the position of -the caption from above the top of the table to below the bottom of the -table or vice versa. It only affects whether the text is formatted as -a caption for use above or below a table. Whether the text is in fact -placed above or below a table is set through the position of the -\DescRef{\LabelBase.cmd.caption} command inside the \Environment{table} environment. This may -change using package \Package{float}\IndexPackage{float} and command -\Macro{restylefloats} (see \cite{package:float}). - -Of course similar features exist\ChangedAt{v3.09}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} for figures using options +In the standard classes, the titles of floating environments, which are +formatted with the \DescRef{\LabelBase.cmd.caption}\IndexCmd{caption} command +(see below), are set off from the float with vertical spacing appropriate for +putting the caption beneath the float, like a signature. They also distinguish +between one-line and multi-line captions. One-line captions are centred while +multi-line captions are left-justified. + +\leavevmode\LabelOptionValue{captions}{tableheading}\nobreak% +For tables, however, you want the caption% +\important{\Option{captions}{tableheading}} to appear as a heading instead of +a signature. That's because tables can span multiple pages. With such tables, +the reader wants to know the purpose of the table on the first page. +Furthermore, tables are usually read row by row, from top to bottom. So there +are normally at least two good reasons to provide all tables with headings. +\KOMAScript{} therefore offers the \OptionValue{captions}{tableheading}% +\IndexOption{captions~=\textKValue{tableheading}} option, which changes the +formatting of table captions for use above the table. + +Note\textnote{Attention!} that multi-page tabulars cannot use a floating +environment. To have an automatic page break in a tabular you need an +additional package like \Package{longtable}\IndexPackage{longtable} (see +\cite{package:longtable}) or \Package{supertabular}\IndexPackage{supertabular} +(see \cite{package:supertabular}). + +You\important{\OptionValue{captions}{tablesignature}} can switch back to the +default caption formatting using \OptionValue{captions}{tablesignature}% +\IndexOption{captions~=\textKValue{tablesignature}}. Note\textnote{Attention!} +that these options change only the formatting, not the actual position of the +caption. Whether the caption is placed above or below a float depends solely +upon where you use the \DescRef{\LabelBase.cmd.caption} command inside float +environment. However, this can change when using the \Package{float}% +\IndexPackage{float} package with the \Macro{restylefloats} command (see +\cite{package:float}). + +Of course\important{\OptionValue{captions}{figureheading}\\ + \OptionValue{captions}{figuresignature}}, corresponding functions +exist\ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} for figures using the options \OptionValue{captions}{figureheading}% -\IndexOption{captions~=\PValue{figureheading}} and +\IndexOption{captions~=\textKValue{figureheading}} and \OptionValue{captions}{figuresignature}% -\IndexOption{captions~=\PValue{figuresignature}}. Nevertheless, -figures like photos will be viewed as a whole, and a diagram or graph -will mostly be examined from left bottom to the right. Therefore, in -general, signatures should be used and it would not be useful to change -the caption format from signatures to headings. - -Nevertheless sometimes all floating environments shall use headings. For this -\KOMAScript{} supports\ChangedAt{v3.09}{\Class{scrbook}\and +\IndexOption{captions~=\textKValue{figuresignature}}. However, figures such as +photos tend to be viewed as a whole, and a diagram or graph will mostly be +examined starting from the lower left. Therefore, it only rarely makes sense +to change the caption format for figures alone from signatures to headings. + +Sometimes, however, all floating environments should use headings. Therefore +\KOMAScript{} provides\ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} -options\important[i]{\OptionValue{captions}{heading}\\ - \OptionValue{captions}{signature}} -\OptionValue{captions}{heading}\IndexOption{captions~=\PValue{heading}} and -\OptionValue{captions}{signature}\IndexOption{captions~=\PValue{signature}} to -switch the format of every floating environment. These options may be used -also inside a floating environment but before using \DescRef{\LabelBase.cmd.caption}. - -Note\textnote{Attention!}\OnlyAt{\Package{float}}\IndexPackage{float} that -when using the \Package{float} package, the options -\OptionValue{captions}{tablesignature} and -\OptionValue{captions}{tableheading} cease to act correctly when -\Macro{restylefloat} is applied to tables. More details of the \Package{float} -package and \Macro{restylefloat} can be found in -\cite{package:float}. Additional support in {\KOMAScript} for the -\Package{float} package may be found at the explanation of \PValue{komaabove} -(see \DescPageRef{\LabelBase.floatstyle.komaabove}). - -\leavevmode\phantomsection\nobreak -\label{desc:\LabelBase.option.captions.nooneline}\nobreak -\label{desc:\LabelBase.option.captions.oneline}\nobreak -Furthermore, \KOMAScript{} supports to switch off the distinguish of captions -with only one line or more than one line using option -\OptionValue{captions}{nooneline}\IndexOption{captions~=\PValue{nooneline}}% -\important{\OptionValue{captions}{nooneline}}. This may be useful, if one-line -captions should not be centered. The default of centering one-line captions -corresponds to \OptionValue{captions}{oneline}. - -Another special feature of \KOMAScript{} is to alternatively put the caption -neither above nor below the floating object but beside -it. For this you need Environment\important{\DescRef{\LabelBase.env.captionbeside}} -\DescRef{\LabelBase.env.captionbeside}\IndexEnv{captionbeside}, that will be described -from \DescPageRef{\LabelBase.env.captionbeside}. Several settings -for this environment may be done also using \Option{caption}. You may find all -the available \PName{settings} at \autoref{tab:\LabelBase.captions}. +options\important{\OptionValue{captions}{heading}\\ + \OptionValue{captions}{signature}} +\OptionValue{captions}{heading}\IndexOption{captions~=\textKValue{heading}} +and \OptionValue{captions}{signature}% +\IndexOption{captions~=\textKValue{signature}} to switch the format of every +floating environment. These options can also be used inside a floating +environment. + +Please note\textnote{Achtung!}\OnlyAt{\Package{float}}\IndexPackage{float} +when using the \Package{float} package that the settings for signatures or +headings will no longer work once \Macro{restylefloat} is applied to tables or +figures. For details about the \Package{float} package and +\Macro{restylefloat}, please refer to \cite{package:float}. This also applies +to \DescRef{\LabelBase.cmd.caption} within new floating environments defined +with \Package{float}. You can find additional support which \KOMAScript{} +provides when using the \Package{float} package in the explanation of +\PValue{komaabove} (see \DescPageRef{\LabelBase.floatstyle.komaabove}). As an +alternative to \Package{float}, you can also consult +\DescRef{\LabelBase.cmd.captionof} (see +\DescPageRef{\LabelBase.cmd.captionof}) and +\DescRef{tocbasic.cmd.DeclareNewTOC} (see +\DescPageRef{tocbasic.cmd.DeclareNewTOC}). Additionally, when using +\Package{float}, the +\hyperref[cha:scrhack]{\Package{scrhack}}\IndexPackage{scrhack}% +\important{\hyperref[cha:scrhack]{\Package{scrhack}}} package is +expressly recommended (see \autoref{cha:scrhack} from +\autopageref{cha:scrhack} in \autoref{part:forExperts}). + +\leavevmode +\LabelOptionValue{captions}{nooneline}\nobreak +\LabelOptionValue{captions}{oneline}\nobreak +Furthermore\important{\OptionValue{captions}{nooneline}}, \KOMAScript{} offers +the option to disable the distinction between one-line and multi-line captions +using the \OptionValue{captions}{nooneline}% +\IndexOption{captions~=\textKValue{nooneline}}% +\important{\OptionValue{captions}{nooneline}} option. This can be useful, for +example, if you do not want one-line captions to be centred. The default, +where one-line captions are centred, corresponds to +\OptionValue{captions}{oneline}. + +Another special feature of \KOMAScript{} is the ability to put the caption +beside the floating object rather than above or below it. For this, you need +the environment\important{\DescRef{\LabelBase.env.captionbeside}} +\DescRef{\LabelBase.env.captionbeside}\IndexEnv{captionbeside}, which is +explained starting on \DescPageRef{\LabelBase.env.captionbeside}. The settings +for this environment can also be changed with the \Option{caption} option. You +can find the available values for the corresponding \PName{settings} in +\autoref{tab:\LabelBase.captions}. % \begin{desclist} - \desccaption[{Available values for option \Option{captions}}]{% - Available values for option \Option{captions} to select formation of - captions as headings or signatures at floating environments% + \desccaption[{Available values for the \Option{captions}} option]{% + Available values for the \Option{captions} option for setting formatting of + captions as headings or signatures in floating environments% \label{tab:\LabelBase.captions}% }{% - Available values for option \Option{captions} (\emph{continuation})% + Available values for the \Option{captions} option (\emph{continued})% }% \entry{\PValue{bottombeside}, \PValue{besidebottom}}{% - Captions and contents of environment - \DescRef{\LabelBase.env.captionbeside} (see - \autoref{sec:\LabelBase.floats}, - \DescPageRef{\LabelBase.env.captionbeside}) will be vertically align - depending on the bottommost base lines.% - \IndexOption{captions~=\PValue{bottombeside}}}% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see + \autoref{sec:\LabelBase.floats}, + \DescPageRef{\LabelBase.env.captionbeside}) are vertically aligned with + the bottommost baseline of the contents of the floating environment.% + \IndexOption{captions~=\textKValue{bottombeside}}}% \entry{\PValue{centeredbeside}, \PValue{besidecentered}, \PValue{middlebeside}, \PValue{besidemiddle}}{% - Captions and contents of environment - \DescRef{\LabelBase.env.captionbeside} (see + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see \autoref{sec:\LabelBase.floats}, - \DescPageRef{\LabelBase.env.captionbeside}) will be vertically centered% - \IndexOption{captions~=\PValue{centeredbeside}}}% + \DescPageRef{\LabelBase.env.captionbeside}) are vertically aligned with + the center of the contents of the floating environment.% + \IndexOption{captions~=\textKValue{centeredbeside}}}% \entry{\PValue{figureheading}, \PValue{figureabove}, \PValue{abovefigure}, \PValue{topatfigure}% - \IndexOption{captions~=\PValue{figureheading}}}{% + \IndexOption{captions~=\textKValue{figureheading}}}{% \ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - Captions of figures will use heading formation\,---\,maybe in discrepancy - to \OptionValue{captions}{signature}.% + Captions for figures use heading format\,---\,possibly deviating from + \OptionValue{captions}{signature}.% }% \entry{\PValue{figuresignature}, \PValue{belowfigure}, \PValue{bottomatfiggure}% - \IndexOption{captions~=\PValue{figuresignature}}}{% + \IndexOption{captions~=\textKValue{figuresignature}}}{% \ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - Captions of figures will use signature formation\,---\,maybe in - discrepancy to \OptionValue{captions}{headings}.% + Captions for figures use signature format\,---\,possibly deviating + from \OptionValue{captions}{headings}.% }% \entry{\PValue{heading}, \PValue{above}, \PValue{top}% - \IndexOption{captions~=\PValue{heading}}}{% + \IndexOption{captions~=\textKValue{heading}}}{% \ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} Captions of floating environments will use heading - formation. Nevertheless this does not influence whether they are really - placed at the top or at the bottom of the object. This options also + \Class{scrartcl}} Captions for floating environments use formatting + suitable for use in a heading. This setting does not control whether they + are placed at the top or the bottom of the object. This option also implies \OptionValue{captions}{tableheading} and \OptionValue{captions}{figureheading}.% }% \entry{\PValue{innerbeside}, - \PValue{besideinner}\IndexOption{captions~=\PValue{innerbeside}}}{% - Captions of environment \DescRef{\LabelBase.env.captionbeside} (siehe + \PValue{besideinner}\IndexOption{captions~=\textKValue{innerbeside}}}{% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see \autoref{sec:\LabelBase.floats}, - \DescPageRef{\LabelBase.env.captionbeside}) will be placed innermost - beside the contents of the environment at double-side printing. At - single-side printing \OptionValue{captions}{leftbeside} will be used.% + \DescPageRef{\LabelBase.env.captionbeside}) are placed inside of and next + to the contents of the environment in two-sided printing. In one-sided + printing, \OptionValue{captions}{leftbeside} is used.% }% \entry{\PValue{leftbeside}, - \PValue{besideleft}\IndexOption{captions~=\PValue{leftbeside}}}{% - Captions of environment \DescRef{\LabelBase.env.captionbeside} (siehe + \PValue{besideleft}\IndexOption{captions~=\textKValue{leftbeside}}}{% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see \autoref{sec:\LabelBase.floats}, - \DescPageRef{\LabelBase.env.captionbeside}) will be placed left beside the - contents of the environment.% + \DescPageRef{\LabelBase.env.captionbeside}) are placed to the left of + the contents of the floating environment.% }% \pventry{nooneline}{% - Captions with only one line will not be handled different from captions - with more than one line.% - \IndexOption{captions~=\PValue{nooneline}}}% + Single-line captions are handled the same as multi-line captions.% + \IndexOption{captions~=\textKValue{nooneline}}}% \pventry{oneline}{% - Captions with only one line will be centered horizontally.% - \IndexOption{captions~=\PValue{oneline}}}% + Single-line captions are centred horizontally.% + \IndexOption{captions~=\textKValue{oneline}}}% \entry{\PValue{outerbeside}, \PValue{besideouter}% - \IndexOption{captions~=\PValue{outerbeside}}}{% - Captions of environment \DescRef{\LabelBase.env.captionbeside} (siehe + \IndexOption{captions~=\textKValue{outerbeside}}}{% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see \autoref{sec:\LabelBase.floats}, - \DescPageRef{\LabelBase.env.captionbeside}) will be placed outermost - beside the contents of the environment at double-side printing. At - single-side printing \OptionValue{captions}{rightbeside} will be used.% + \DescPageRef{\LabelBase.env.captionbeside}) are placed outside of and + next to the contents of the environment in two-sided printing. In + one-sided printing, \OptionValue{captions}{rightbeside} is used.% }% \entry{\PValue{rightbeside}, \PValue{besideright}% - \IndexOption{captions~=\PValue{rightbeside}}}{% - Captions of environment \DescRef{\LabelBase.env.captionbeside} (siehe + \IndexOption{captions~=\textKValue{rightbeside}}}{% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see \autoref{sec:\LabelBase.floats}, - \DescPageRef{\LabelBase.env.captionbeside}) will be placed right beside - the contents of the environment.% + \DescPageRef{\LabelBase.env.captionbeside}) are placed to the right of the + contents of the floating environment.% }% \entry{\PValue{signature}, \PValue{below}, \PValue{bot}, \PValue{bottom}% - \IndexOption{captions~=\PValue{signature}}}{% + \IndexOption{captions~=\textKValue{signature}}}{% \ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - Captions of floating environments will use signature - formation. Nevertheless this does not influence whether they are really - placed at the top or at the bottom of the object. This options also - implies \OptionValue{captions}{tablesignature} and - \OptionValue{captions}{figuresignature}.% + Captions for floating environments use signature format. This setting + does not control whether they are placed at the top or the bottom of the + object. This options also implies \OptionValue{captions}{tablesignature} + and \OptionValue{captions}{figuresignature}.% }% \entry{\PValue{tableheading}, \PValue{tableabove}, \PValue{abovetable}, \PValue{abovetabular}, \PValue{topattable}% - \IndexOption{captions~=\PValue{tableheading}}}{% - Captions of tables will use heading formation\,---\,maybe in discrepancy - to \OptionValue{captions}{signature}.% + \IndexOption{captions~=\textKValue{tableheading}}}{% + Captions for tables use heading format\,---\,possibly deviating from + \OptionValue{captions}{signature}.% }% \entry{\PValue{tablesignature}, \PValue{belowtable}, \PValue{belowtabular}, \PValue{bottomattable}% - \IndexOption{captions~=\PValue{tablesignature}}}{% - Captions of tables will use signature formation\,---\,maybe in discrepancy - to \OptionValue{captions}{heading}.% + \IndexOption{captions~=\textKValue{tablesignature}}}{% + Captions for tables use signature format\,---\,possibly deviating + from \OptionValue{captions}{heading}.% }% \entry{\PValue{topbeside}, \PValue{besidetop}}{% - Captions and contents of environment - \DescRef{\LabelBase.env.captionbeside} (see + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see \autoref{sec:\LabelBase.floats}, - \DescPageRef{\LabelBase.env.captionbeside}) will be vertically align - depending on the topmost base lines.% - \IndexOption{captions~=\PValue{topbeside}}}% + \DescPageRef{\LabelBase.env.captionbeside}) are vertically aligned to the + baseline at the top of the floating environment.% + \IndexOption{captions~=\textKValue{topbeside}}}% \end{desclist}% % \EndIndexGroup \begin{Declaration} - \Macro{caption}\OParameter{entry}\Parameter{title}% - \Macro{captionbelow}\OParameter{entry}\Parameter{title}% + \Macro{caption}\OParameter{entry}\Parameter{title} + \Macro{captionbelow}\OParameter{entry}\Parameter{title} \Macro{captionabove}\OParameter{entry}\Parameter{title} \end{Declaration}% -In the standard classes caption text \PName{title} of tables and -figures is inserted with the \Macro{caption} command below the table -or figure. In general this is correct for figures. Opinions differ as -to whether captions of tables are to be placed above or, consistent -with captions of figures\Index{caption>of figure}, below the -table\Index{caption>of table}. That is the reason why +In the standard classes, tables and figures are given captions with the +\Macro{caption} command placed below the table or figure. For figures, this is +generally correct. For tables, opinions differ as to whether captions should +be placed above the table or, consistent with captions of +figures\Index{caption>of figure}, below it\Index{caption>of table}. Therefore {\KOMAScript}\textnote{\KOMAScript{} vs. standard classes}, unlike the standard classes, offers \Macro{captionbelow} for captions below and \Macro{captionabove} for captions above tables or figures. -Not only for tables but also for figures or all kind of floating environments -the behaviour of \Macro{caption} may be modified using option -\DescRef{\LabelBase.option.captions}\IndexOption{captions} described at the beginning of this -section. For -compatibility reasons the default behaviour of \Macro{caption} used -with all kinds of floating environments is similar to -\Macro{captionbelow}. Nevertheless it -is recommended\textnote{Hint!} to use table headings and therefor switch -behaviour of \Macro{caption} inside table environments into -\Macro{captionabove} using option -\OptionValueRef{\LabelBase}{captions}{tableheading}. Alternatively you may use -\Macro{captionabove} instead of \Macro{caption} inside of every -\Environment{table} environment. +For tables and figures, or in general for all floating environments, you can +control the behaviour of \Macro{caption} with the +\DescRef{\LabelBase.option.captions}\IndexOption{captions} option described at +the beginning of this section. For compatibility reasons, the default +behaviour of \Macro{caption} for all floating environments is like +\Macro{captionbelow}. However, you\textnote{Hint!} should use the +\OptionValueRef{\LabelBase}{captions}{tableheading} option, which switches the +behaviour of \Macro{caption} inside table environments to +\Macro{captionabove}. Alternatively, you can use \Macro{captionabove} instead +of \Macro{caption} inside every \Environment{table} environment. % \begin{Example} - Instead of using captions below a table you want to place your + Instead of using captions below a table, you want to place your captions above it\Index{table>caption}, because you have tables which span more then one page. In the standard classes you could only write: @@ -2828,7 +3194,7 @@ behaviour of \Macro{caption} inside table environments into \end{tabular} \end{table} \end{lstcode} - Then you would get the unsatisfying result: + Then you would get this unsatisfying result: \begin{ShowOutput}\centering {\usekomafont{caption}{\usekomafont{captionlabel}\tablename~30.2:} This is an example table.}\\ @@ -2860,13 +3226,12 @@ behaviour of \Macro{caption} inside table environments into \end{tabular} \end{ShowOutput} Since you want all your tables typeset with captions above, you could - of course use the option \OptionValueRef{\LabelBase}{captions}{tableheading} instead (see - \DescPageRef{\LabelBase.option.captions.tableheading}). Then you can use - \Macro{caption} as you would in the standard classes. You will get - the same result as with \Macro{captionabove}. + of course use the \OptionValueRef{\LabelBase}{captions}{tableheading} option + instead (see \DescPageRef{\LabelBase.option.captions.tableheading}). Then + you can use \Macro{caption} as you would in the standard classes. You will + get the same result as with \Macro{captionabove}. \end{Example} -\BeginIndexGroup \BeginIndex[indexother]{}{font>style}% \BeginIndex{FontElement}{caption}\LabelFontElement{caption}% \BeginIndex{FontElement}{captionlabel}\LabelFontElement{captionlabel}% @@ -2875,20 +3240,19 @@ The font style\ChangedAt{v2.8p}{% and the label\,---\,``Figure'' or ``Table'', followed by the number and the delimiter\,---\,can be changed with the commands \DescRef{\LabelBase.cmd.setkomafont} and -\DescRef{\LabelBase.cmd.addtokomafont} (see \autoref{sec:\LabelBase.textmarkup}, +\DescRef{\LabelBase.cmd.addtokomafont} (see +\autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont}). The respective elements for this -are \FontElement{caption}\important{\FontElement{caption}} and -\FontElement{captionlabel}\important{\FontElement{captionlabel}} (see -\autoref{tab:\LabelBase.fontelements}, \autopageref{tab:\LabelBase.fontelements}). -First the font style for the element \FontElement{caption} is applied to the -element \FontElement{captionlabel} too. After this the font style of -\FontElement{captionlabel} is applied on the respective element. The default -settings are listed in \autoref{tab:\LabelBase.captionFont}. +are \FontElement{caption}\important[i]{\FontElement{caption}\\ + \FontElement{captionlabel}} and \FontElement{captionlabel} (see +\autoref{tab:\LabelBase.fontelements}, +\autopageref{tab:\LabelBase.fontelements}). The font style for the element +\FontElement{caption} is applied to the element \FontElement{captionlabel} +before the font style of \FontElement{captionlabel} itself is applied. The +default settings are listed in \autoref{tab:\LabelBase.captionFont}. % \begin{table} % \centering% - \KOMAoptions{captions=topbeside}% - \setcapindent{0pt} % \caption \begin{captionbeside} {Font defaults for the elements of figure or table captions} @@ -2919,10 +3283,7 @@ settings are listed in \autoref{tab:\LabelBase.captionFont}. \end{lstcode} As you can see, simple extensions of the default definitions are possible. -\end{Example} -% -\EndIndexGroup -% +\end{Example}% \EndIndexGroup @@ -2934,38 +3295,39 @@ settings are listed in \autoref{tab:\LabelBase.captionFont}. \Macro{captionaboveof}\Parameter{float type}\OParameter{entry}% \Parameter{title} \end{Declaration}% -\KOMAScript{} supports a command -\Macro{captionof}\ChangedAt{v3.05}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} similar to packages -\Package{caption}\IndexPackage{caption} and -\Package{capt-of}\IndexPackage{capt-of}. You may use this command to place a -floating environment caption with corresponding entry into the list of that -kind of floating environment but even inside a another floating environment or -outside any floating environment. In difference to \DescRef{\LabelBase.cmd.caption} the kind of -floating environment has to be set as first parameter. - -Furthermore, \KOMAScript{} provides the additional commands +Like\ChangedAt{v3.05}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} the \Package{caption}\IndexPackage{caption} and +\Package{capt-of}\IndexPackage{capt-of} packages, \KOMAScript{} offers the +\Macro{captionof} command, with which you can put a caption for a floating +environment, together with an entry in the corresponding environment list, +outside of the floating environment or even in a different floating +environment. Unlike \DescRef{\LabelBase.cmd.caption}, the type of floating +environment must be specified as the first parameter. + +In addition, \KOMAScript{} also provides the commands \Macro{captionaboveof}\ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} and \Macro{captionbelowof}. These are -like \Macro{captionabove} and \Macro{captionbelow} but with the additional -features and parameter of \Macro{captionof}. - -Of course \KOMAScript\ChangedAt{v3.09a}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} takes care of the \PValue{heading} -and \PValue{signature} setting of option -\DescRef{\LabelBase.option.captions}. But this feature may be lost, loading package -\Package{capt-of} or \Package{caption}. Please note the manual of package -\Package{caption} for this! -% +like \DescRef{\LabelBase.cmd.captionabove} and +\DescRef{\LabelBase.cmd.captionbelow} but with the additional features and +parameter of \Macro{captionof}. + +Of course\ChangedAt{v3.09a}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} \Macro{captionof} takes into account the \PValue{heading} +and \PValue{signature} settings of the \DescRef{\LabelBase.option.captions} +option. But this feature may be lost if you load the +\Package{capt-of}\IndexPackage{capt-of} or +\Package{caption}\IndexPackage{caption} packages. When using +\Package{caption}, you must follow the instructions for that package (see +\cite{package:caption})! \begin{Example} - Assumed you want to create a floating object with a table and a figure side - by side. As you know, there are now mixed floating environment. Therefor you - use a \Environment{figure} environment primarily: + Suppose you want to create a floating object with a table and a figure next + to each other. Since there are no mixed floating environments, you primarily + use a \Environment{figure} environment: \begin{lstcode} \begin{figure} \begin{minipage}{.5\linewidth} \centering - \rule{4cm}{3cm} + \rule{4cm}{5cm} \caption{A rectangle}\label{fig:rechteck} \end{minipage}% \begin{minipage}{.5\linewidth} @@ -2977,28 +3339,28 @@ and \PValue{signature} setting of option \label{tab:rechteck} \begin{tabular}{ll} Width: & 4\,cm\\ - Height: & 3\,cm + Height: & 5\,cm \end{tabular} \end{minipage} \end{figure} \end{lstcode} - Two \Environment{minipage} environments have been used to have figure and - table side by side. The\textnote{Attention!} percent char after the end of - the first \Environment{minipage} is important. Without an additional - inter-word distance would be made between the \Environment{minipage} + Two \Environment{minipage} environments were used to place the figure + and the table side by side. The\textnote{Attention!} percent sign after the + end of the first \Environment{minipage} is important. Without it, an + additional space would appear between the \Environment{minipage} environments. - The figure signature has been done using \DescRef{\LabelBase.cmd.caption}. The table heading - has been done using \Macro{captionaboveof} with first argument - \PValue{table}. Because of this \KOMAScript{} knows, that despite the - \Environment{figure} environment a table caption should be made. - - The optional argument of \Macro{captionaboveof} does make the entry into the - list of tables. Without the optional argument, the last mandatory argument - would have been used for the list of tables too. Although this caption text - is sufficient for the environment itself, it would be very useful at the - list of tables. Therefor a somehow more detailed description has been used - for the list of tables using the optional argument. The + The figure caption was created with \DescRef{\LabelBase.cmd.caption}. The + table caption was created with \Macro{captionaboveof} with \PValue{table} + as the first argument. Because of this, \KOMAScript{} knows that this is a + table caption even though it is inside the \Environment{figure} environment. + + The optional argument of \Macro{captionaboveof} creates an entry in the + list of tables. Without the optional argument, the caption specified in the + final mandatory argument would have been used for the list of tables too. + Although this caption text is sufficient for the environment itself, it + would not be very meaningful in the list of tables. Therefore, a different + title is used for the list of tables using the optional argument. \autoref{fig:\LabelBase.captionaboveof} shows the result of the example code.% \begin{figure} % \centering @@ -3006,16 +3368,16 @@ and \PValue{signature} setting of option \KOMAoptions{captions=bottombeside}% \setcapindent{0pt}% \begin{captionbeside} - [{Example: Usage of \Macro{captionaboveof} inside another floating + [{Example: Using \Macro{captionaboveof} inside another floating environment}] - {Example: Usage of \Macro{captionaboveof} inside another floating + {Example: Using \Macro{captionaboveof} inside another floating environment\label{fig:\LabelBase.captionaboveof}} [l] \begin{minipage}[b]{.66\linewidth}% \raisebox{\depth}{\fbox{\KOMAoptions{captions=oneline}% \begin{minipage}{.5\dimexpr\linewidth-2\fboxsep-2\fboxrule\relax} \centering - \rule{4cm}{3cm} + \rule{4cm}{5cm} \caption[Example: A rectangle]{A rectangle}\label{fig:\LabelBase.rechteck} \end{minipage}% \begin{minipage}{.5\dimexpr\linewidth-2\fboxsep-2\fboxrule\relax} @@ -3024,115 +3386,120 @@ and \PValue{signature} setting of option figure~\ref{fig:\LabelBase.rechteck}]{Rectangle size} \label{tab:\LabelBase.rechteck} \begin{tabular}{ll} - Width: & 4\,cm\\ - Height: & 3\,cm + Width: & 4\,cm\\ + Height: & 5\,cm \end{tabular} \end{minipage}}}% \end{minipage}% \end{captionbeside}% \end{figure}% \end{Example}% -A non-floating table with a caption may be produced in the same kind like the -table inside a figure environment in the example above. In such a case also a -\Environment{minipage} environment should be used, to avoid page breaks -between table caption an tabular. An additional \Environment{flushleft} -environment around the \Environment{minipage} environment may be used, to have -a pleasing distance above and below is and to avoid the paragraph indentation -of the \Environment{minipage} environment.% -% +You can produce a non-floating table with a caption in the same way as the +table inside a figure environment in the example above. In such a case, a +\Environment{minipage} environment should also be used to avoid page breaks +between the caption and the table. In addition, you should embed the +\Environment{minipage} environment in a \Environment{flushleft} environment +both to achieve a pleasing separation between the surrounding text and to +avoid the paragraph indentation of the \Environment{minipage} environment.% \EndIndexGroup \begin{Declaration} - \begin{Environment}{captionbeside}% - \OParameter{entry}\Parameter{title}% - \OParameter{placement}\OParameter{width}% - \OParameter{offset} + \begin{Environment}{captionbeside} + \OParameter{short title} + \Parameter{caption text} + \OParameter{placement} + \OParameter{width} + \OParameter{offset} \end{Environment} \labelsuffix[*]% - \begin{Environment}{captionbeside}% - \OParameter{entry}\Parameter{title}% - \OParameter{placement}\OParameter{width}% - \OParameter{offset}\PValue{*}% + \begin{Environment}{captionbeside} + \OParameter{short title} + \Parameter{caption text} + \OParameter{placement} + \OParameter{width} + \OParameter{offset}\PValue{*}% \end{Environment} \end{Declaration} -Apart\ChangedAt{v2.8q}{% - \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} from -captions above and below the figure, one often finds captions, in -particular with small figures, which are placed beside the figure. In -general in this case both the baseline of the figure and of the -caption are aligned at the bottom. With some fiddling and the use of -two \Macro{parbox} commands this could also be achieved in the -standard classes. However, {\KOMAScript} offers a special environment -for this which can be used within the floating environment. The first -optional parameter \PName{entry} and the obligatory parameter -\PName{title} mean the same as the corresponding parameters of -\DescRef{\LabelBase.cmd.caption}, \DescRef{\LabelBase.cmd.captionabove} or \DescRef{\LabelBase.cmd.captionbelow}. The -caption text \PName{title} is placed beside the content of the -environment in this case. - -Whether the caption text \PName{title} is placed on the left or the -right can be determined by the parameter \PName{placement}. Exactly +In addition\ChangedAt{v2.8q}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} to captions above and below the figure, you will often +find captions, in particular for small figures, which are placed beside the +figure. The bottom edge of the caption is normally aligned with the bottom of +the figure. Of course, you can achieve the same thing in the standard classes +with some fiddling and the use of two \Macro{parbox} commands. However, +\KOMAScript{} offers a special environment for this which you can use within +the floating environments. The first optional parameter, +\PName{short title}\important{\PName{short title}\\\PName{caption text}}, and +the required parameter \PName{caption text} have the same meaning as the +corresponding parameters of \DescRef{\LabelBase.cmd.caption}, +\DescRef{\LabelBase.cmd.captionabove} or +\DescRef{\LabelBase.cmd.captionbelow}. The \PName{caption text} is +placed beside the content of the environment in this case. + +The \PName{placement}\important{\PName{placement}} parameter can determine +whether the \PName{caption text} is placed on the left or the right. Exactly one of the following letters is allowed: -\begin{labeling}[~--]{\quad\PValue{o}}\setlength{\itemsep}{0pt}% -\item[\PValue{l}] left -\item[\PValue{r}] right -\item[\PValue{i}] inner margin in two-sided layout -\item[\PValue{o}] outer margin in two-sided layout +\begin{labeling}[~--]{\quad\PValue{o}}\setlength{\itemsep}{-1\parsep plus 1ex}% + \item[\PValue{l}] left + \item[\PValue{r}] right + \item[\PValue{i}] inner margin in two-sided printing + \item[\PValue{o}] outer margin in two-sided printing \end{labeling} -Default setting is to the right of the content of the environment. This -default\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} my be changed using option -\DescRef{\LabelBase.option.captions}\IndexOption{captions}\important{\DescRef{\LabelBase.option.captions}} (see +The default placement is to the right of the content of the environment. You +can change this default\ChangedAt{v3.00}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} using the +\DescRef{\LabelBase.option.captions}\IndexOption{captions}% +\important{\DescRef{\LabelBase.option.captions}} option (see \DescPageRef{\LabelBase.option.captions}) with values like -\PValue{innerbeside}\IndexOption[indexmain]{captions~=\PValue{innerbeside}}, -\PValue{leftbeside}\IndexOption[indexmain]{captions~=\PValue{leftbeside}}, -\PValue{outerbeside}\IndexOption[indexmain]{captions~=\PValue{outerbeside}}, +\PValue{innerbeside}\IndexOption[indexmain]{captions~=\textKValue{innerbeside}}, +\PValue{leftbeside}\IndexOption[indexmain]{captions~=\textKValue{leftbeside}}, +\PValue{outerbeside}\IndexOption[indexmain]{captions~=\textKValue{outerbeside}}, and -\PValue{rightbeside}\IndexOption[indexmain]{captions~=\PValue{rightbeside}}. +\PValue{rightbeside}\IndexOption[indexmain]{captions~=\textKValue{rightbeside}}. If either \PValue{o} or \PValue{i} are used you may need to run {\LaTeX} twice to obtain the correct placement. -Per default the content of the environment and the caption text -\PName{title} fill the entire available text width. However, using the -optional parameter \PName{width}, it is possible to adjust the width -used. This width could even be larger than the current text width. - -When supplying a \PName{width} the used width is usually centered with -respect to the text width. Using the optional parameter -\PName{offset}, you can shift the environment relative to the left -margin. A positive value corresponds to a shift to the right, whereas -a negative value corresponds to a shift to the left. An \PName{offset} -of 0\Unit{pt} gives you a left-aligned output. - -Adding a star to the optional parameter \PName{offset} makes the the -value mean a shift relative to the right margin on left hand pages in -two-sided layout. A positive value corresponds to a shift towards the -outer margin, whereas a negative value corresponds to a shift towards -the inner margin. An \PName{offset} of 0\Unit{pt} means alignment with -the inner margin. As mentioned before, in some cases it takes two -{\LaTeX} runs for this to work correctly. +Normally\important{\PName{width}}, the content of the environment and the +\PName{caption text} fill the entire available text width. However, you can +specify a different width using the optional parameter \PName{width}. This can +be greater than the current text width. + +When specifying a \PName{width}\important{\PName{width}\\\PName{offset}}, the +width used is usually centred with respect to the body text. Using the +optional parameter \PName{offset}, you can shift the environment relative to +the left margin. A positive value corresponds to a shift to the right, whereas +a negative value corresponds to a shift to the left. An \PName{offset} of +0\Unit{pt} gives you a left-aligned output. + +If\important{\PValue{*}} you add a star to the optional \PName{offset} +parameter, the value represents a shift relative to the right margin on +left-hand pages in a two-sided layout. A positive value corresponds to a shift +towards the outer margin, whereas a negative value corresponds to a shift +towards the inner margin. An \PName{offset} of 0\Unit{pt} means alignment with +the inner margin. This variant may require two {\LaTeX} runs to achieve the +correct offset. The default vertical alignment is bottom. This means that the bottommost base -lines of the contents of the environment and of the caption are aligned. This -setting\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} may be changed using option -\DescRef{\LabelBase.option.captions}\IndexOption{captions} (see -\DescPageRef{\LabelBase.option.captions}) with value -\PValue{topbeside}\IndexOption[indexmain]{captions~=\PValue{topbeside}}, +lines of the contents of the environment and of the caption are aligned. +You\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} can change this setting using the +\DescRef{\LabelBase.option.captions}\IndexOption{captions}% +\important{\DescRef{\LabelBase.option.captions}} option (see +\DescPageRef{\LabelBase.option.captions}) with the value +\PValue{topbeside}\IndexOption[indexmain]{captions~=\textKValue{topbeside}}, \PValue{centeredbeside}% -\IndexOption[indexmain]{captions~=\PValue{centeredbeside}}, or -\PValue{bottombeside}\IndexOption[indexmain]{captions~=\PValue{bottombeside}}. With -setting \PValue{topbeside} the topmost base lines of the environment contents -and caption will be aligned. With \PValue{centeredbeside} they will be -centered vertically. In this context it should be known, that the base line of -a pictures is mostly at the bottom of the picture. This may be changed, -e.\,g., using \Macro{raisebox}\IndexCmd{raisebox}. +\IndexOption[indexmain]{captions~=\textKValue{centeredbeside}}, or +\PValue{bottombeside}% +\IndexOption[indexmain]{captions~=\textKValue{bottombeside}}. +With the setting \PValue{topbeside}, the topmost base lines of the environment +contents and caption will be aligned. With \PValue{centeredbeside}, they will +be centred vertically. In this context, note that the base line of a figure is +usually the bottom of the figure. You can change this using, for example, +\Macro{raisebox}\IndexCmd{raisebox}. \begin{Example} - An example for the usage of the \Environment{captionbeside} environment - can be found in \autoref{fig:\LabelBase.captionbeside}. - This figure was typeset with: + You can find an example using the \Environment{captionbeside} environment in + \autoref{fig:\LabelBase.captionbeside}. This figure was typeset with: \begin{lstcode} \begin{figure} \begin{captionbeside}[Example: Figure beside description]% @@ -3161,30 +3528,35 @@ e.\,g., using \Macro{raisebox}\IndexCmd{raisebox}. \end{captionbeside} \label{fig:\LabelBase.captionbeside} \end{figure} - The total width is thus the currently available width + The total width is thus the currently available width of \PValue{\Macro{linewidth}}. However, this width is shifted - $\Length{marginparwidth} - + \Length{marginparsep}$ to the outside. The caption text or description is - placed on the inner side beside the figure. The figure itself is - shifted 2\Unit{em} into the outer margin. + $\Length{marginparwidth} + \Length{marginparsep}$ to the outside. The + caption text or description is placed on the inner side beside the figure. + The figure itself is shifted 2\Unit{em} into the outer margin. - With \Macro{dimexp} a \eTeX{} command has been used. This should not be a - problem at all, because \KOMAScript{} itself needs \eTeX{} and every almost +\iffalse% Umbruchkorrekturtext + The \Macro{dimexp} macro is an \eTeX{} command. This should not be a + problem at all because \KOMAScript{} itself requires \eTeX{} and every almost up-to-date \LaTeX{} distribution uses \eTeX already. +\fi \hyperref[fig:\LabelBase.captionbesidecentered]% {Figure~\ref*{fig:\LabelBase.captionbesidecentered}} - shows a centered caption with: + shows a centred caption with: \begin{lstcode} \KOMAoption{captions}{centeredbeside} \end{lstcode} - Even if you are not a typographer you may see, that this is not a - recommended suggestion. +\iffalse % Umbruchalternativen + Even a typographical novice will immediately realize that you should + usually avoid this alignment. +\else + This is certainly not a recommended solution. +\fi \begin{figure} \begin{captionbeside}[Example: Description centered beside figure]% {A figure description which is neither above nor - below, but centered beside the figure}[i][\linewidth][2em]* + below, but centred beside the figure}[i][\linewidth][2em]* \fbox{% \parbox[b][5\baselineskip][c]{.25\textwidth}{% \hspace*{\fill}\KOMAScript\hspace*{\fill}\par}} @@ -3192,9 +3564,11 @@ e.\,g., using \Macro{raisebox}\IndexCmd{raisebox}. \label{fig:\LabelBase.captionbesidecentered} \end{figure} - In opposite to the centered example, the top aligned from - \autoref{fig:\LabelBase.captionbesidetop} may be used. To show how to change - the baseline using \Macro{raisebox}, the complete example code follows: + In contrast, you can use the top-aligned format seen in + \autoref{fig:\LabelBase.captionbesidetop}. To illustrate how to shift the + baseline using \Macro{raisebox}, here is a complete example. You can apply + this not only to a substitute figure, as previously shown, but also, for + example, to \Macro{includegraphics} (see \cite{package:graphics}). \begin{lstcode} \documentclass[captions=topbeside]{scrbook} \usepackage[english]{babel} @@ -3233,55 +3607,61 @@ e.\,g., using \Macro{raisebox}\IndexCmd{raisebox}. \end{captionbeside} \label{fig:\LabelBase.captionbesidetop} \end{figure} - You may use such a movement not only at graphics replacements like show, but - also using \Macro{includegraphics} (see \cite{package:graphics}). \end{Example} % \EndIndexGroup \begin{Declaration} - \begin{Environment}{captionofbeside}% - \Parameter{float type}% - \OParameter{entry}\Parameter{title}% - \OParameter{placement}\OParameter{width}% - \OParameter{offset} + \begin{Environment}{captionofbeside} + \Parameter{float type} + \OParameter{short title} + \Parameter{caption text} + \OParameter{placement} + \OParameter{width} + \OParameter{offset} + \begin{Body}\BodyDots\end{Body} \end{Environment} \labelsuffix[*]% - \begin{Environment}{captionofbeside}% - \Parameter{float type}% - \OParameter{entry}\Parameter{title}% - \OParameter{placement}\OParameter{width}% - \OParameter{offset}\PValue{*}% + \begin{Environment}{captionofbeside} + \Parameter{float type} + \OParameter{short title} + \Parameter{caption text} + \OParameter{placement} + \OParameter{width} + \OParameter{offset}\PValue{*}% + \begin{Body}\BodyDots\end{Body} \end{Environment} \end{Declaration} -This\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} environment corresponds to -\DescRef{\LabelBase.env.captionbeside} in the same manner like -\Macro{captionof} corresponds to \DescRef{\LabelBase.cmd.caption}. The float -type is not defined by a floating environment but by the first mandatory -argument.% +As\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} is the case for \DescRef{\LabelBase.cmd.caption}, there is +a variant for \DescRef{\LabelBase.cmd.captionof} where the \PName{float type} +is not defined by using it within a floating environment of this type, so you +can specify a suitable environment for \DescRef{\LabelBase.env.captionbeside} +with \Environment{captionofbeside}. In contrast to +\DescRef{\LabelBase.env.captionbeside}, the \PName{float type} must be +specified as an additional, first argument.% % \EndIndexGroup - \begin{Declaration} \FloatStyle{komaabove}% \FloatStyle{komabelow} \end{Declaration}% If you use\OnlyAt{\Package{float}} the \Package{float}\IndexPackage{float} -package the appearance of the float environments is solely defined by the -\emph{float} style. This includes whether captions above or below are used. In -the \Package{float} package there is no predefined style which gives you the -same output and offers the same setting options (see below) as {\KOMAScript}. -Therefore {\KOMAScript} defines the two additional styles \PValue{komaabove} -and \PValue{komabelow}. When using the \Package{float} package these styles -can be activated just like the styles \PValue{plain}\IndexFloatstyle{plain}, -\PValue{boxed}\IndexFloatstyle{boxed} or \PValue{ruled}\IndexFloatstyle{ruled} -defined in \Package{float}. For details refer to \cite{package:float}. The -style \PValue{komaabove} inserts \DescRef{\LabelBase.cmd.caption}, \DescRef{\LabelBase.cmd.captionabove} and -\DescRef{\LabelBase.cmd.captionbelow} above, whereas \PValue{komabelow} inserts them below the -float content. +package, the appearance of the float environments is solely defined by the +\emph{float} style. This includes whether captions appear above or below. In +the \Package{float} package, there is no predefined style which gives you the +same output and offers the same setting options (see below) as \KOMAScript{}. +Therefore \KOMAScript{} defines the two additional styles, \PValue{komaabove} +and \PValue{komabelow}. When using the \Package{float} package, you can +activate these styles just like the styles +\PValue{plain}\IndexFloatstyle{plain}, \PValue{boxed}\IndexFloatstyle{boxed}, +or \PValue{ruled}\IndexFloatstyle{ruled} defined in \Package{float}. For +details refer to \cite{package:float}. The style \PValue{komaabove} inserts +\DescRef{\LabelBase.cmd.caption}, \DescRef{\LabelBase.cmd.captionabove}, and +\DescRef{\LabelBase.cmd.captionbelow} above, whereas \PValue{komabelow} +inserts them below the float content. % \EndIndexGroup @@ -3289,21 +3669,20 @@ float content. \begin{Declaration} \Macro{captionformat} \end{Declaration}% -In {\KOMAScript} there are different ways to change the formatting of -the caption text. The definition of different font styles was already -explained above. This or the caption delimiter between the label and -the label text itself is specified in the macro \Macro{captionformat}. -In contrast to all other \Macro{\dots}format commands, in this case it -does not contain the counter but only the items which follow it. The -original definition is: +In {\KOMAScript} there are various ways to change the formatting of +the caption text. The definition of different font styles has already +been explained above. The delimiter or delimiters between the label and +actual caption text is specified by the macro \Macro{captionformat}. +In contrast to all other \Macro{\dots}format commands, this is not the counter +but only the items which follow it. The original definition is: \begin{lstcode} \newcommand*{\captionformat}{:\ } \end{lstcode} -This too can be changed with \Macro{renewcommand}. +You can change this too with \Macro{renewcommand}. \begin{Example} - For some inexplicable reasons you want a dash with spaces before and - after instead of a colon followed by a space as label delimiter. You - define: + For some inexplicable reason, you want a dash surrounded by spaces + instead of a colon followed by a space as a label delimiter. You + therefore define: \begin{lstcode} \renewcommand*{\captionformat}{~--~} \end{lstcode} @@ -3317,33 +3696,30 @@ This definition should be put in the preamble of your document. \Macro{figureformat}% \Macro{tableformat} \end{Declaration}% -It was already mentioned that \DescRef{\LabelBase.cmd.captionformat} does not -contain formatting for the label itself. This situation should under no -circumstances be changed using redefinitions of the commands for the output of -counters, \Macro{thefigure} or \Macro{thetable}. Such a redefinition would -have unwanted side effects on the output of \Macro{ref} or the table of -contents, list of figures and list of tables. To deal with the situation, -{\KOMAScript} offers two \Macro{\dots format} commands instead. These are -predefined as follows: -% Umbruchkorrektur: listings +It has already been mentioned that \DescRef{\LabelBase.cmd.captionformat} does +not contain formatting for the label itself. You should not alter this by +redefining the commands for the output of the \Macro{thefigure} or +\Macro{thetable} counters. Such a redefinition would have unwanted side +effects on the output of \Macro{ref}, the table of contents, the list of +figures, and the list of tables. Instead, {\KOMAScript} offers two +\Macro{\dots format} commands. These have the following defaults: \begin{lstcode} \newcommand*{\figureformat}{\figurename~\thefigure\autodot} \newcommand*{\tableformat}{\tablename~\thetable\autodot} \end{lstcode} -They also can be adapted to your personal preferences with -\Macro{renewcommand}. +They can also be customised to your requirements with \Macro{renewcommand}. \begin{Example} - From time to time captions without any label and of course without - delimiter are desired. In {\KOMAScript} it takes only the following - definitions to achieve this: + From time to time, it is required to have captions without labels or + delimiters. With {\KOMAScript} the following definitions suffice to + achieve this: \begin{lstcode} \renewcommand*{\figureformat}{} \renewcommand*{\tableformat}{} \renewcommand*{\captionformat}{} \end{lstcode} It should be noted, however, that although no numbering is output, the - internal counters are nevertheless incremented. This becomes important - especially if this redefinition is applied only to selected + internal counters are nevertheless incremented. This becomes especially + important if this redefinition is applied only to selected \Environment{figure} or \Environment{table} environments. \end{Example} % @@ -3355,52 +3731,50 @@ They also can be adapted to your personal preferences with \Macro{setcapindent*}\Parameter{xindent}% \Macro{setcaphanging} \end{Declaration}% -As mentioned previously, in the standard classes the captions are set -in a non-hanging style, that is, in multi-line captions the second and -subsequent lines start directly beneath the label. The standard -classes provide no direct mechanism to change this behaviour. In -{\KOMAScript}, on the contrary, beginning at the second line all lines -are indented by the width of the label so that the caption text is -aligned. - -This behaviour, which corresponds to the usage of \Macro{setcaphanging}, can -easily be changed by using the command \Macro{setcapindent} or -\Macro{setcapindent*}. Here the parameter \PName{indent} determines the -indentation of the second and subsequent lines. If you want a line break after -the label and before the caption text, then you can define the indentation -\PName{xindent} of the caption text with the starred version of the command -instead: \Macro{setcapindent*}. -Using a negative value of \PName{indent} instead, a line break is also -inserted before the caption text and only the first line of the -caption text but not subsequent lines are indented by -the absolute value of \PName{indent}. - -Whether one-line captions are set as captions with more than one line or are +As mentioned previously, in the standard classes the captions are set in a +non-hanging style. In other words, in multi-line captions the second and +subsequent lines start directly beneath the label. The standard classes +provide no direct mechanism to change this behaviour. In {\KOMAScript}, on the +contrary, beginning at the second line all lines are indented by the width of +the label so that the caption text is aligned. + +You can change this behaviour, which corresponds to using +\Macro{setcaphanging}, at any time with the \Macro{setcapindent} or +\Macro{setcapindent*} command. Here the parameter \PName{indent} determines +the indentation of the second and subsequent lines. If you want a line break +after the label and before the caption text, then you can define the +indentation \PName{xindent} of the caption text with the starred version of +the command instead: \Macro{setcapindent*}. + +A negative value of \PName{indent}, on the other hand, results in a line break +before the caption text, and only the first line of the caption text, not +subsequent lines, is indented by the absolute value of \PName{indent}. + +Whether one-line captions are set the same way as multi-line captions or are treated separately is specified with the option \DescRef{\LabelBase.option.captions}. For details please refer to the -explanations of these option at +explanations of these option on \DescPageRef{\LabelBase.option.captions.oneline}. \begin{Example} - For the examples please refer to - figures~\ref{fig:\LabelBase.caption.first} to - \ref{fig:\LabelBase.caption.last}. As you can see the usage of a fully - hanging indentation is not advantageous when combined with narrow - column width. To illustrate, the source code for the second figure - is given here with a modified caption text: + The illustrations~\ref{fig:\LabelBase.caption.first} to + \ref{fig:\LabelBase.caption.last} show the effects of different settings. As + you can see, using a fully hanging indentation with a narrow column width is + awkward. To illustrate, the source code for the second figure is given here + with a modified caption text: \begin{lstcode} \begin{figure} \setcapindent{1em} \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} - \caption{Example with slightly indented caption - starting at the second line} + \caption{Example with partially indented caption + starting from the second line} \end{figure} \end{lstcode} -As can be seen the formatting can also be changed locally within the -\Environment{figure} environment\IndexEnv{figure}. The change then -affects only the current figure. Following figures once again use the -default settings or global settings set, for example, in the preamble -of the document. This also of course applies to tables. + As you can see, the formatting can also be changed locally within the + \Environment{figure} environment\IndexEnv{figure}. The change then affects + only the current figure. Subsequent figures once again use the default + settings or global settings that you set, for example, in the preamble. This + also, of course, applies to tables. \begin{figure} \typeout{^^J--- Ignore underfull and overfull \string\hbox:} \addtokomafont{caption}{\small} @@ -3409,18 +3783,18 @@ of the document. This also of course applies to tables. \begin{minipage}{.9\linewidth} \begin{minipage}[t]{.48\linewidth}\sloppy \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} - \caption[Example: Default figure caption]% - {\sloppy Equivalent to the standard setting, similar to the - usage of \Macro{setcaphanging}} + \caption[Example: Default caption]% + {\sloppy With the default setting, like using + \Macro{setcaphanging}} \label{fig:\LabelBase.caption.first} \end{minipage} \hspace{.02\linewidth} \begin{minipage}[t]{.48\linewidth}\sloppy \setcapindent{1em} \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} - \caption[Example: Figure caption with slightly hanging indention]% - {With slightly hanging indentation starting at the second line - using \Macro{setcapindent}\PParameter{1em}} + \caption[Example: Caption with partially hanging indention]% + {With partially hanging indentation starting from the second line + by using \Macro{setcapindent}\PParameter{1em}} \end{minipage} \end{minipage} @@ -3429,9 +3803,8 @@ of the document. This also of course applies to tables. \begin{minipage}[t]{.48\linewidth}\sloppy \setcapindent*{1em} \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} - \caption[Example: Figure caption with hanging indention and line - break]% - {With hanging indentation starting at the second line and line + \caption[Example: Caption with hanging indention and line break]% + {With hanging indentation starting from the second line and line break before the description using \Macro{setcapindent*}\PParameter{1em}} \end{minipage} @@ -3439,9 +3812,8 @@ of the document. This also of course applies to tables. \begin{minipage}[t]{.48\linewidth}\sloppy \setcapindent{-1em} \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} - \caption[Example: Figure caption with hanging indention at the second - line]% - {With indentation in the second line only and line break + \caption[Example: Caption with indention in the second line]% + {With indentation only in the second line and a line break before the description using \Macro{setcapindent}\PParameter{-1em}} \label{fig:\LabelBase.caption.last} @@ -3458,263 +3830,410 @@ of the document. This also of course applies to tables. \begin{Declaration} \Macro{setcapwidth}\OParameter{justification}\Parameter{width}% \Macro{setcapdynwidth}\OParameter{justification}\Parameter{width}% - \Macro{setcapmargin}\OParameter{margin left}\Parameter{margin}% - \Macro{setcapmargin*}\OParameter{margin inside}\Parameter{margin} + \Macro{setcapmargin}\OParameter{left margin}\Parameter{margin}% + \Macro{setcapmargin*}\OParameter{inside margin}\Parameter{margin} \end{Declaration} Using\ChangedAt{v2.8q}{% \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} these three -commands you can specify the width and justification of the caption -text. In general the whole text width or column width is available -for the caption. +commands, you can specify the width and justification of the caption +text. Normally, the entire text or column width is available for the caption. -With\important{\Macro{setcapwidth}} the command \Macro{setcapwidth} you can -decrease this \PName{width}. The obligatory argument determines the maximum -\PName{width} of the caption. As an optional argument you can supply exactly +With\important{\Macro{setcapwidth}} the \Macro{setcapwidth} command, you can +decrease this \PName{width}. The mandatory argument determines the maximum +\PName{width} of the caption. As an optional argument, you can supply exactly one letter which specifies the horizontal justification. The possible -justifications are given in the following list. -\begin{labeling}[~--]{\quad\PValue{o}}\rightskip=1em -\item[\PValue{l}] left-aligned -\item[\PValue{c}] centered +justifications are given in the following list: +\begin{labeling}[~--]{\quad\PValue{o}}% + \itemsep=.5\topsep plus .5\topsep minus .5\topsep + \rightskip=1em +\item[\PValue{l}] left-justified +\item[\PValue{c}] centred \item[\PValue{r}] right-aligned -\item[\PValue{i}] alignment at the inner margin in double-sided output -\item[\PValue{o}] alignment at the outer margin in double-sided output +\item[\PValue{i}] aligned to the inner margin in two-sided printing +\item[\PValue{o}] aligned to the outer margin in two-sided printing \end{labeling} -The justification inside and outside corresponds to left-aligned and -right-aligned, respectively, in single-sided -output. Within\textnote{Attention!} -\Package{longtable}\IndexPackage{longtable}% -\important{\Package{longtable}} tables the justification inside or outside -does not work correctly. In particular, the captions on subsequent pages of -such tables are aligned according to the format of the caption on the first -page of the table. This is a conceptual problem in the implementation of -\Package{longtable}. - -Please\ChangedAt{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}}\textnote{Attention!} note, \Macro{setcapwidth} sets the -width immediately to the value of parameter \PName{width} like -\Macro{setlength} would do. If you instead want the value of \PName{width} -when the caption is set, you can use \Macro{setcapdynwidth}. There can be -differences in the result, if you, e.\,g., use lengths like \Length{linewidth} -or other commands as argument \PName{width}. - -With\important{\Macro{setcapmargin}} the command \Macro{setcapmargin} you can -specify a \PName{margin} which is to be left free next to the description in -addition to the normal text margin. If you want margins with different widths -at the left and right side you can specify these using the optional argument -\PName{margin left}. The starred version \Macro{setcapmargin*} defines instead -of a \PName{margin left} a \PName{margin inside} in a double-sided layout. In -case of \Package{longtable}\IndexPackage{longtable}% -\important{\Package{longtable}} tables you have to deal with the same problem -with justification inside or outside as mentioned with the macro -\Macro{setcapwidth}. Furthermore, the usage of \Macro{setcapmargin} or -\Macro{setcapmargin*} switches on the option -\OptionValueRef{\LabelBase}{captions}{nooneline} (see -\DescPageRef{\LabelBase.option.captions.nooneline}) for the captions which are +Inside and outside justification corresponds to left-aligned and right-aligned +justification, respectively, in one-sided printing. +Within\textnote{Attention!} \Package{longtable}\IndexPackage{longtable}% +\important{\Package{longtable}} tables, inside and outside justification does +not work correctly. In particular, the captions on subsequent pages of such +tables are aligned according to the format of the caption on the first page of +the table. This is a conceptual problem in the implementation of the +\Package{longtable} package. + +Note\ChangedAt{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\textnote{Attention!} that \Macro{setcapwidth} immediately +sets the width to the value of the \PName{width} parameter at the time of the +assignment, as \Macro{setlength} does. If\important{\Macro{setcapdynwidth}} +you instead want to use the current value of \PName{width} when the caption is +set, you should use \Macro{setcapdynwidth}. There can be significant +differences in the result if, for example, you use lengths like +\Length{linewidth} or other commands as \PName{width} arguments. + +With\important{\Macro{setcapmargin}} the \Macro{setcapmargin} command, instead +of specifying the width of the caption text, you can specify a \PName{margin} +to be set next to the caption text in addition to the normal text margin. If +you want margins with different widths on the left and right sides, you can +use the optional argument to specify a \PName{left margin} that differs from +\PName{margin}. Instead of a \PName{left margin}, the starred version +\Macro{setcapmargin*} defines an \PName{inside margin} in a two-sided layout. +The same problem arises here with with inside and outside justification inside +\Package{longtable}\IndexPackage{longtable}\important{\Package{longtable}} +tables that occurs with \Macro{setcapwidth}. Furthermore, using +\Macro{setcapmargin} or \Macro{setcapmargin*} activates the +\OptionValueRef{\LabelBase}{captions}{nooneline} option (see +\DescPageRef{\LabelBase.option.captions.nooneline}) for captions which are typeset with this margin setting. -You\textnote{Hint!} can also submit negative values for \PName{margin} and -\PName{margin left} or \PName{margin inside}. This has the effect of the -caption expanding into the margin. - -Experts\textnote{Hint!} and advanced users may find a tricky usage of -\Macro{setcapwidth} in +You\textnote{Hint!} can also specify negative values for \PName{margin} and +\PName{left margin} or \PName{inside margin}. This has the effect of making +the caption protrude into the margin.% +\iffalse\par% Anhang wurde entfernt. +Experts\textnote{Hint!} and advanced users can find a a somewhat tricky +application of \Macro{setcapwidth} in \iffree{\cite{book:komascript}}{\autoref{cha:floattricks}, \autopageref{cha:floattricks}}.% +\fi% % \EndIndexGroup +\begin{Declaration} + \Macro{setcaptionalignment}\OParameter{float type}\Parameter{alignment} +\end{Declaration} +Normally\ChangedAt{v3.25}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}, multi-line\textnote{alignment of multi-line captions} +captions are fully justified. This corresponds to +\Macro{setcaptionalignment}\PParameter{j}. Sometimes, however, you want a +different alignment, for example ragged right. An appropriate change is +possible at any time with \Macro{setcaptionalignment}. You can specify exactly +one of the letters listed in \autoref{tab:maincls.captionalignment} for the +\PName{alignment}. If you specify an unknown \PName{alignment}, you will +receive an error message. +% +\begin{table} +% \centering + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% + \begin{captionbeside} + [{Alignments for multi-line captions of floating environments}] + {\label{tab:maincls.captionalignment}% + Alignments for multi-line captions of floating environments} + [l] + \begin{tabular}[t]{ll} + \toprule + c & centred \\ + j & fully justified \\ + l & left justified \\ + r & right justified \\ + C & centred with \Package{ragged2e} \\ + J & fully justified with \Package{ragged2e} \\ + L & left justified with \Package{ragged2e} \\ + R & right justified with \Package{ragged2e} \\ + \bottomrule + \end{tabular} + \end{captionbeside} +\end{table} + +The four possibilities with the +\Package{ragged2e}\important{\Package{ragged2e}}\IndexPackage{ragged2e} +package are only available if that package was loaded before you use +\Macro{setcaptionalignment}. Otherwise, they are converted to the +corresponding options without \Package{ragged2e}. For safety reasons, a +warning is issued in this case. + +When using this command without\textnote{without optional parameter} the +optional parameter, the result depends on whether the call occurs inside our +outside of a floating environment. Within a floating environment, the +alignment is then set for this floating environment. Outside, on the other +hand, the optional parameter is assumed to be empty. + +Using this command with an empty\textnote{empty optional parameter} optional +parameter, or outside a floating environment and also without any optional +parameter, sets the general alignment. This is used whenever the current +floating environment type does not define an alignment. + +If you only want to set the alignment of a particular type of floating +environment\textnote{with \PName{float type}} without changing the +\PName{alignment} for other types of floating environments, then the type of +floating environment, e.\,g., \PValue{figure} or \PValue{table}, is given as +the optional parameter \PName{float type}. +% +\begin{Example} + You want captions to be centred under the images even if they are + multi-line. To text this for a single image, use\textnote{in the + floating environment}: +\begin{lstcode} + \begin{figure} + \centering + \setcaptionalignment{c} + \includegraphics{example-image} + \caption{\blindtext} + \end{figure} +\end{lstcode} + Since you are satisfied with the result, you move the\textnote{in the + preamble} +\begin{lstcode} + \setcaptionalignment{c} +\end{lstcode} + command to the document preamble. Thereafter, however, you decide you do not + like this change for table captions at all. Therefore, you use\textnote{only + for figures} +\begin{lstcode} + \setcaptionalignment[figure]{c} +\end{lstcode} + to limit the centring to figures. + + A little later, you realize that the centring is not so suitable. Instead, + you now prefer to have ragged right alignment. So you change the alignment + again: +\begin{lstcode} + \setcaptionalignment[figure]{l} +\end{lstcode} + However, you do not like the fact that the lines are very different in + length. This is caused by the lack of hyphenation, causing long words to + wrap completely onto the next line, leaving large gaps. You want to allow + hyphenation as needed. This is easy to achieve with the help of the + \Package{ragged2e}\important{\Package{ragged2e}}\IndexPackage{ragged2e} + package. However, it is not enough to use +\begin{lstcode} + \usepackage{ragged2e} +\end{lstcode} + to load the package. Using the \Option{newcommands} option when loading the + package does not help. Instead, the \PName{alignment} must also be changed: +\begin{lstcode} + \usepackage{ragged2e} + \setcaptionalignment[figure]{L} +\end{lstcode} + Note\textnote{Attention!} the upper-case letter for the \PName{alignment}. +\end{Example} +\EndIndexGroup + \begin{Declaration} \Option{origlongtable} \end{Declaration}% \BeginIndex{Package}{longtable}% -If the table captions produced by the \Package{longtable} package (see -\cite{package:longtable}) should not be redefined by the {\KOMAScript} +If you do not want the table captions produced by the \Package{longtable} +package (see \cite{package:longtable}) to be redefined by the {\KOMAScript} classes, activate the \Option{origlongtable} option. This\textnote{Attention!} -option has to be used at the optional argument of -\DescRef{\LabelBase.cmd.documentclass}. It may not be used as a setting of +option must be used in the optional argument of +\DescRef{\LabelBase.cmd.documentclass}. It cannot be used as a setting of \DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoptions}. % \EndIndexGroup +% +\EndIndexGroup \begin{Declaration} \OptionVName{listof}{setting} \end{Declaration} -\BeginIndex{}{tables>list of}\BeginIndex{}{list of>tables}% -\BeginIndex{}{figures>list of}\BeginIndex{}{list of>figures}% Normally\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} lists of floating environments\,---\,like list of tables -or list of figures will neither get an entry at the table of contents nor have -a number at the heading. More information about that may be found in -\autoref{sec:\LabelBase.toc}. Alternative to the view from the table of -contents to the lists of floating environments, you may reconsider a view from -the lists of floating environments into the table of contents. Because of -this, there are not only the options -\OptionValueRef{\LabelBase}{toc}{nolistof}% -\IndexOption{toc~=\PValue{nolistof}}, -\OptionValueRef{\LabelBase}{toc}{listof}\IndexOption{toc~=\PValue{listof}}, + \Class{scrartcl}} lists of floating environments\,---\,like +tables\Index{tables>list of} or figures\Index{figures>list of}\,---\,are +neither numbered nor included in the table of contents. You can find more +information about this behaviour in \autoref{sec:\LabelBase.toc}. As an +alternative to the settings \OptionValueRef{\LabelBase}{toc}{nolistof}% +\IndexOption{toc~=\textKValue{nolistof}}, +\OptionValueRef{\LabelBase}{toc}{listof}\IndexOption{toc~=\textKValue{listof}}, and \OptionValueRef{\LabelBase}{toc}{listofnumbered}% -\IndexOption{toc~=\PValue{listofnumbered}} described in -\autoref{sec:\LabelBase.toc}, \DescPageRef{\LabelBase.option.toc.listof}, but -also \OptionValue{listof}{notoc}, \OptionValue{listof}{totoc}, and -\OptionValue{listof}{numbered} with the same meaning. - -By default the headings of the lists of floating environments use the topmost -level below \DescRef{\LabelBase.cmd.part}. This is the chapter level at -\Class{scrbook} and \Class{scrreprt} and the section level at -\Class{scrartcl}. With\ChangedAt{v3.06}{\Class{scrbook}\and +\IndexOption{toc~=\textKValue{listofnumbered}} mentioned there, you can also +look at this behaviour from perspective of the lists themselves. Therefore +you can achieve the same results with the settings +\OptionValue{listof}{notoc}, \OptionValue{listof}{totoc}, and +\OptionValue{listof}{numbered}. + +By default, the headings in the lists of floating environments use the topmost +level below \DescRef{\LabelBase.cmd.part}. This is the chapter level in +\Class{scrbook} and \Class{scrreprt} and the section level in +\Class{scrartcl}. By contrast,\ChangedAt{v3.06}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} -\OptionValue{listof}{leveldown}\important{\OptionValue{listof}{leveldown}} a -one step lower level will be used instead. +\OptionValue{listof}{leveldown}\important{\OptionValue{listof}{leveldown}} +uses the next lower level to be used instead. +\important{\OptionValue{listof}{standardlevel}}% +\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% +\OptionValue{listof}{standardlevel} switches back to the default sectioning +level, if necessary. \begin{Example} - At a book you want to move the list of figures and the list of tables as - sub-lists into a common list named ``Figures and Tables''. With + In a book, you want to put the list of figures and the list of tables as + sub-lists into a common list named ``Figures and Tables''. Simply use: \begin{lstcode} \KOMAoption{listof}{leveldown} \end{lstcode} - you first declare to use the section instead of the chapter level for both - lists and then you use: + to use the section instead of the chapter level for both lists, and put the + following at the appropriate place in your document: \begin{lstcode} \addchap*{Figures and Tables} \listoffigures \listoftables \end{lstcode} - for the new list, that contains the list of figures and the list of - tables. More information about the command \DescRef{\LabelBase.cmd.addchap*} - may be found in \autoref{sec:\LabelBase.structure} at + You can find more information about the \DescRef{\LabelBase.cmd.addchap*} + command in \autoref{sec:\LabelBase.structure} on \DescPageRef{\LabelBase.cmd.addchap*}. \end{Example} Normally\ChangedAt{v2.8q}{% \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} the lists of -floating environments use a constant with to place the caption number of the -entries. Additionally all entries will be indented a little bit. This -corresponds to setting -\OptionValue{listof}{graduated}\IndexOption{listof~=\PValue{graduated}}. - -If the numbers of the figures or tables, become very wide\,---\,i.\,e., if you -have a lot of tables or figures\,---\, their may be not enough width -predefined. There's\important{\OptionValue{listof}{flat}} a setting -\OptionValue{listof}{flat}\IndexOption{listof~=\PValue{flat}} for the lists of -floating environment similar to -\OptionValueRef{\LabelBase}{toc}{flat}\IndexOption{toc~=\PValue{flat}} for the -table of contents. Thereby the needed with for printing the number will be -determined at each \LaTeX{} run. See option -\OptionValueRef{\LabelBase}{toc}{flat}, \autoref{sec:\LabelBase.toc}, -\DescPageRef{\LabelBase.option.toc.flat} for information about how it -works. Please\textnote{Attention!} note again, that you need more than one -\LaTeX{} runs until the lists of floating environments will become their final -result. - -Setting \OptionValue{listof}{entryprefix}\ChangedAt{v3.06}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} will automatically activate -\OptionValue{listof}{flat} -too. Normally\important{\OptionValue{listof}{entryprefix}} it would not make -sense to add the prefix ``figure'' to each entry of the list of figures and -the prefix ``table'' to each entry of the list of tables, because nothing else -than figures would be and should be expected at the list of figures and -nothing else than tables would be and should be expected at the list of -tables. So this prefixes would not give any additional information and for this -would not be useful. Nevertheless, such prefixes may be added using option -\OptionValue{listof}{entryprefix}. With this all entries of the same list will -get the same prefix. The prefix will depend on the file extension of the -helper file, that will be used for the corresponding list. For the list of -figures the file extension would be ``\File{lof}'' and therefor -\Macro{listoflofentryname} would be used. For the list of tables, the file -extension would be ``\File{lot}'' and \Macro{listoflotentryname} would be -used. - -Within classes \Class{scrbook} and \Class{scrreprt}\OnlyAt{\Class{scrbook}\and - \Class{scrreprt}} \KOMAScript{} adds a vertical gap to the lists of floating -environments whenever a new chapter starts. This behaviour, that is same at -the standard classes, structures the lists by chapters. At \KOMAScript{} it -corresponds to setting \ChangedAt{v3.00}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} +floating environments use a fixed-width space for the caption number of the +entries. At the same time, all entries are somewhat indented. This behaviour +corresponds to the +\OptionValue{listof}{graduated}\IndexOption{listof~=\textKValue{graduated}} +setting. + +If the numbers become very wide, for example because you have many tables or +figures, the space provided may at some point no longer be sufficient. +\KOMAScript{} offers the setting \OptionValue{listof}{flat}% +\important{\OptionValue{listof}{flat}}\IndexOption{listof~=\textKValue{flat}} +for lists of floating environments, comparable to +\OptionValueRef{\LabelBase}{toc}{flat}\IndexOption{toc~=\textKValue{flat}} for +the table of contents. The width required to print the number is +determined automatically and the space is adjusted accordingly. See the +\OptionValueRef{\LabelBase}{toc}{flat} option, \autoref{sec:\LabelBase.toc}, +\DescPageRef{\LabelBase.option.toc.flat} for more information about side +effects and how it works. Note\textnote{Attention!} again that you need more +than one \LaTeX{} run before the lists of floating environments reach +their final state. + +The \OptionValue{listof}{entryprefix}\ChangedAt{v3.06}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} setting automatically activates +\OptionValue{listof}{flat} too. +Normally\important{\OptionValue{listof}{entryprefix}}, it does not make sense +to add a prefix such as ``figure'' or ``table'' to each entry in the lists of +floating environments because, of course, only figures are included in the +list of figures and only tables are included in the list of tables. Such a +prefix provides no additional information and is thus omitted by default. +However, you can add such prefixes using the +\OptionValue{listof}{entryprefix} option. With this, all entries in the same +list will get the same prefix. The prefix depends on the file extension of the +auxiliary file that is used for the corresponding list. For the list of +figures, the file extension is ``\File{lof}'' and therefore +\Macro{listoflofentryname} is used. For the list of tables, the file extension +is ``\File{lot}'' and \Macro{listoflotentryname} is used. + +For the \Class{scrbook} and \Class{scrreprt}\OnlyAt{\Class{scrbook}\and + \Class{scrreprt}} classes, \KOMAScript{} adds a vertical space to the lists +of floating environments whenever a new chapter starts. This behaviour, which +also exists in the standard classes, groups the lists by chapters. In +\KOMAScript{}, it corresponds to setting \ChangedAt{v3.00}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}}% \OptionValue{listof}{chaptergapsmall}% -\IndexOption{listof~=\PValue{chaptergapsmall}}. In this case a gap of width -10\Unit{pt} will be used. With\important{\OptionValue{listof}{chaptergapline}} -option \OptionValue{listof}{chaptergapline}% -\IndexOption{listof~=\PValue{chaptergapline}} a gap of the height of one -standard text line will be -used. The\important{\OptionValue{listof}{nochaptergap}} gap may be switched of -with \OptionValue{listof}{nochaptergap}% -\IndexOption{listof~=\PValue{nochaptergap}}. Option\important{\OptionValue{listof}{chapterentry}} +\LabelOptionValue{listof}{chaptergapsmall}% +\important{\OptionValue{listof}{chaptergapsmall}}% +\IndexOption{listof~=\textKValue{chaptergapsmall}}. In this case, is uses a +fixed vertical space of 10\Unit{pt}. +With\important{\OptionValue{listof}{chaptergapline}} the +\OptionValue{listof}{chaptergapline}% +\IndexOption{listof~=\textKValue{chaptergapline}} option, you instead get a +vertical space the height of one standard text line. With +\OptionValue{listof}{nochaptergap}% +\IndexOption{listof~=\textKValue{nochaptergap}}% +\important{\OptionValue{listof}{nochaptergap}}, you can completely remove the +vertical space. The\important{\OptionValue{listof}{chapterentry}} \OptionValue{listof}{chapterentry}% -\IndexOption{listof~=\PValue{chapterentry}} is somehow special. Instead of a -gap it adds the table of contents entry for the chapter additionally to the -lists of floating environments. Please\textnote{Attention!} note, that this -would also happen, if the chapter does not have any floating -environment. Additional influence of chapters to the lists of floating -environments is available with option -\DescRef{\LabelBase.option.chapteratlists}. See -\autoref{sec:\LabelBase.structure}, -\DescPageRef{\LabelBase.option.chapteratlists} for more information about -that. - -An overview about all settings to option \Option{listof} may be found at +\IndexOption{listof~=\textKValue{chapterentry}} option is a special feature. +Instead of a vertical space, the table of contents entry for the chapter is +inserted into the lists of floating environments. Note\textnote{Attention!} +that this happens even if the chapter does not contain a floating environment. +You can find a method where only chapters containing floating environments +appear in the respective lists at \cite{https://komascript.de/comment/5070}. +You can achieve a more direct control over what appears in the lists of +floating environments with the \DescRef{\LabelBase.option.chapteratlists} +option, which is explained in \autoref{sec:\LabelBase.structure}, on +\DescPageRef{\LabelBase.option.chapteratlists}. + +You can find an overview of all settings for the \Option{listof} option in \autoref{tab:\LabelBase.listof}. \begin{desclist} - \desccaption[{Available values for option \Option{listof}}]{% - Available values for option \Option{listof} to modify contents and - formation of the lists of floating environments\label{tab:\LabelBase.listof}% + \desccaption[{Available values for the \Option{listof} option}]{% + Available values for the \Option{listof} option for modifying the format + and contents of the lists of floating + environments\label{tab:\LabelBase.listof}% }{% - Available values for option \Option{listof} (\emph{continuation})% + Available values for the \Option{listof} option (\emph{continued})% }% \entry{\PValue{chapterentry}, \PValue{withchapterentry}}{% - Marks chapter starts at the lists of floating environments by a copy of - their entries to the table of contents.% - \IndexOption{listof~=\PValue{chapterentry}}}% + Indicates the beginning of chapters in the lists of floating environments + with copies of their table-of-contents entries.% + \IndexOption{listof~=\textKValue{chapterentry}}}% \entry{\PValue{chaptergapline}, \PValue{onelinechaptergap}}{% - Marks chapter starts at the lists of floating environments by a vertical - gap of the height of one standard text line.% - \IndexOption{listof~=\PValue{chaptergapline}}}% + Indicates the beginning of chapters in the lists of floating environments + with a vertical space the height of one standard text line.% + \IndexOption{listof~=\textKValue{chaptergapline}}}% \entry{\PValue{chaptergapsmall}, \PValue{smallchaptergap}}{% - Marks chapter starts at the lists of floating environments by a small - vertical gap.% - \IndexOption{listof~=\PValue{chaptergapsmall}}}% + Indicates the beginning of chapters in the lists of floating environments + with a small vertical space.% + \IndexOption{listof~=\textKValue{chaptergapsmall}}}% \entry{\PValue{entryprefix}}{% \ChangedAt{v3.06}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - Adds a prefix depending on the file extension of the list to each entry of - the lists of floating environments. The prefix additionally depends on the - language, e.\,g., in English ``Figure'' would be used for the entries to - the list of figures and ``Table'' for the entries to the list of - tables. Both prefixes will be followed by a white space.% - \IndexOption{listof~=\PValue{entryprefix}}}% + Adds a prefix before the number of each floating-environment list entry. + The prefix is usually language-dependent, e.\,g., in English ``Figure'' is + used for the list of figures and ``Table'' for the list of tables, each + followed by a white space.% + \IndexOption{listof~=\textKValue{entryprefix}}}% \entry{\PValue{flat}, \PValue{left}}{% - The lists of floating environments will be printed like a kind of - table. The caption numbers will be the first column, the caption texts the - second column, and the page numbers the last column. The width of the first - column depends on the previous \LaTeX{} run.% - \IndexOption{listof~=\PValue{flat}}}% + Prints the lists of floating environments in tabular form. The caption + numbers are the first column, the caption texts the second column, and the + page numbers the third column. The space reserved for the caption numbers + depends on the previous \LaTeX{} run.% + \IndexOption{listof~=\textKValue{flat}}}% \entry{\PValue{graduated}, \PValue{indent}, \PValue{indented}}{% - The lists of floating environments will be printed in hierarchical - form. The width for the caption numbers will be limited.% - \IndexOption{listof~=\PValue{graduated}}}% + Prints the lists of floating environments in a hierarchical form. The + space reserved for the caption numbers is limited.% + \IndexOption{listof~=\textKValue{graduated}}}% \entry{\PValue{leveldown}}{% - The lists of floating environments will use a heading of one step lower - sectioning level than default.% - \IndexOption{listof~=\PValue{leveldown}}}% + Uses headings that are one level lower in the sectioning hierarchy than + the default for lists of floating environments.% + \IndexOption{listof~=\textKValue{leveldown}}}% + \entry{\PValue{indenttextentries}, \PValue{indentunnumbered}, + \PValue{numberline}}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The \PValue{numberline} property (see \autoref{sec:tocbasic.toc}, + \DescPageRef{tocbasic.cmd.setuptoc}) is set for the lists of floating + environments such as figures and tables. As a result, unnumbered entries + are left-aligned with the text of numbered entries of the same level. + However, the \KOMAScript{} classes themselves do not put unnumbered + entries in these lists. This option therefore affects only entries that + are generated not by the \KOMAScript{} classes themselves but with the + help of \DescRef{tocbasic.cmd.addxcontentsline} (see + \autoref{sec:tocbasic.toc}, \DescPageRef{tocbasic.cmd.addxcontentsline}).% + \IndexOption{toc~=\textKValue{numberline}}}% + \entry{\PValue{leftaligntextentries}, \PValue{leftalignunnumbered}, + \PValue{nonumberline}}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The \PValue{nonumberline} property (see \autoref{sec:tocbasic.toc}, + \DescPageRef{tocbasic.cmd.setuptoc}) is set for the lists of floating + environments. This will place unnumbered entries left-aligned with the + number of numbered entries. However, the \KOMAScript{} classes themselves + do not put unnumbered entries in these lists. This option therefore + affects only entries that are generated not by the \KOMAScript{} classes + themselves but with the help of \DescRef{tocbasic.cmd.addxcontentsline} + (see \autoref{sec:tocbasic.toc}, + \DescPageRef{tocbasic.cmd.addxcontentsline}).% + \IndexOption{toc~=\textKValue{nonumberline}}}% \entry{\PValue{nochaptergap}, \PValue{ignorechapter}}{% - Chapter starts are not marked at the lists of floating environments.% - \IndexOption{listof~=\PValue{nochaptergap}}}% - \entry{\PValue{notoc}, \PValue{plainheading}}{% - The lists of floating environments, e.\,g., list of figures and list of - tables do not generate an entry at the table of contents.% - \IndexOption{listof~=\PValue{notoc}}}% + The beginnings of chapters are not marked in the lists of floating + environments.% + \IndexOption{listof~=\textKValue{nochaptergap}}}% + \entry{\PValue{notoc}, \PValue{nottotoc}, \PValue{plainheading}}{% + The lists of floating environments do not generate entries in the table of + contents.% + \IndexOption{listof~=\textKValue{nottotoc}}}% \entry{\PValue{numbered}, \PValue{totocnumbered}, \PValue{tocnumbered}, - \PValue{numberedtotoc}}{% - The lists of floating environments, e.\,g., list of figures and list of - tables, would get a numbered heading and therefor generate an entry at the - table of contents.% - \IndexOption{listof~=\PValue{numbered}}}% + \PValue{numberedtoc}, \PValue{numberedtotoc}}{% + The lists of floating environments receive numbered entries in the table + of contents.% + \IndexOption{listof~=\textKValue{numbered}}}% + \entry{\PValue{standardlevel}}{% + The lists use the normal sectioning level.% + \IndexOption{listof~=\textKValue{standardlevel}}}% \entry{\PValue{totoc}, \PValue{toc}, \PValue{notnumbered}}{% - The lists of floating environments, e.\,g., list of figures and list of - tables, would generate an entry at the table of contents, but their - headings are not numbered.% - \IndexOption{listof~=\PValue{totoc}}}% + The lists of floating environment generate entries in the table of + contents, but their headings are unnumbered.% + \IndexOption{listof~=\textKValue{totoc}}}% \end{desclist} % \EndIndexGroup @@ -3724,69 +4243,67 @@ An overview about all settings to option \Option{listof} may be found at \Macro{listoftables}% \Macro{listoffigures} \end{Declaration} -\BeginIndex{}{tables>list of}\BeginIndex{}{list of>tables}% -\BeginIndex{}{figures>list of}\BeginIndex{}{list of>figures}% -These commands generate a list of tables or figures. Changes in the document -that modify these lists will require two {\LaTeX} runs in order to take -effect. The layout of the lists can be influenced by the option -\DescRef{\LabelBase.option.listof}\important{\DescRef{\LabelBase.option.listof}} -with values \PValue{graduated} or \PValue{flat} (see -\DescPageRef{\LabelBase.option.listof}). Moreover, the values \PValue{listof} -and \PValue{listofnumbered} of option -\DescRef{\LabelBase.option.toc}\important{\DescRef{\LabelBase.option.toc}} -(see \autoref{sec:\LabelBase.toc}) as well as the values \PValue{totoc} and -\PValue{numbered} of the previous described option -\DescRef{\LabelBase.option.listof} have influence to the lists of floating -environments. - -Mostly\textnote{Hint!} the lists of floating environment may be found after -the table of contents. But some publishers like to have these lists at the -appendix. Nevertheless the author of this guide prefers to find them +These commands generate a list of tables or figures. Changes affecting these +lists will require two \LaTeX{} runs to take effect. The layout of the lists +can be influenced by the \DescRef{\LabelBase.option.listof}% +\important{\DescRef{\LabelBase.option.listof}} option with the values +\PValue{graduated} or \PValue{flat} (see +\DescPageRef{\LabelBase.option.listof}). In addition, the \PValue{listof} and +\PValue{listofnumbered} values of the \DescRef{\LabelBase.option.toc}% +\important{\DescRef{\LabelBase.option.toc}} option (see +\autoref{sec:\LabelBase.toc}), as well as the \PValue{totoc} and +\PValue{numbered} values of the \DescRef{\LabelBase.option.listof} option +described above indirectly affect these lists. + +As\textnote{Hint!} a rule, you will find the lists of the floating +environments immediately after the table of contents. In some documents, they +go into the appendix. However, the author of this guide prefers them immediately after the table of contents.% -\EndIndexGroup % \EndIndexGroup -\LoadCommonFile{marginpar}% \section{Margin Notes} +\LoadCommonFile{marginpar}% \section{Marginal Notes} \section{Appendix} \seclabel{appendix} \BeginIndexGroup -\BeginIndex{}{appendix} - -The appendix of a document contains mainly the enclosures to the -document. These are typically bibliography, index, glossary. But only for this -parts nobody would and should start an appendix, because the formation of -these already distinguishes them from the main document. But if there are -additional elements at the appendix, i.\,e., cited third party documents, -endnotes, figures or tabulars, the standard elements like the bibliography +\BeginIndex{}{Appendix} + +The appendix of a document mostly consists of supplements to the document. +Typical parts of an appendix include a bibliography, an index, and a glossary. +However you should not start an appendix for these parts alone because their +format already distinguishes them from the main document. But if there are +additional elements in the appendix, such as quoted third-party documents, +endnotes, figures, or tabulars, the standard elements such as the bibliography should also be part of the appendix. + \begin{Declaration} \Macro{appendix} \end{Declaration}% -The appendix in the standard as well as the {\KOMAScript} classes is -introduced with \Macro{appendix}. This command switches, among other things, -the chapter numbering to upper case letters, also ensuring that the rules -according to \cite{DUDEN} are followed (for German-speaking regions). These -rules are explained in more detail in the description of the option -\DescRef{\LabelBase.option.numbers} in \autoref{sec:\LabelBase.structure}, -\DescPageRef{\LabelBase.option.numbers}. - -Die output of the chapter headings\OnlyAt{\Class{scrbook}\and - \Class{scrreprt}} in the appendix are influenced by the options -\DescRef{\LabelBase.option.chapterprefix} and -\DescRef{\LabelBase.option.appendixprefix}. See +The appendix is started in the standard as well as the {\KOMAScript} classes +with \Macro{appendix}. Among other things, this command changes the chapter +numbering to upper-case letters while ensuring that the rules according to +\cite{DUDEN} for numbering the sectioning levels are followed (for +German-speaking regions). These rules are explained in more detail in the +description of the \DescRef{\LabelBase.option.numbers} option in +\autoref{sec:\LabelBase.structure}, \DescPageRef{\LabelBase.option.numbers}. + +The format of the chapter headings\OnlyAt{\Class{scrbook}\and + \Class{scrreprt}} in the appendix is influenced by the +\DescRef{\LabelBase.option.chapterprefix}% +\important{\DescRef{\LabelBase.option.chapterprefix}\\ + \DescRef{\LabelBase.option.appendixprefix}} and +\DescRef{\LabelBase.option.appendixprefix} options. See \autoref{sec:\LabelBase.structure}, \DescPageRef{\LabelBase.option.appendixprefix} for more information. Please\textnote{Attention!} note that \Macro{appendix} is a command, -\emph{not} an environment! This command does not expect any -argument. Chapters and sections in the appendix uses -\DescRef{\LabelBase.cmd.chapter} and \DescRef{\LabelBase.cmd.section} just as -does the main text.% +\emph{not} an environment! This command does not expect an argument. Chapters +and sections in the appendix use \DescRef{\LabelBase.cmd.chapter} and +\DescRef{\LabelBase.cmd.section}, just as in the main text.% % \EndIndexGroup % @@ -3798,125 +4315,127 @@ does the main text.% \BeginIndexGroup \BeginIndex{}{bibliography} -The bibliography opens up external resources. Mainly bibliographies will be -made by program \BibTeX{} or biber using an external file in database like -structure. Thereby \BibTeX{} style influences not only the formation of the -bibliography entries but also their sorting. Using an additional bibliography -style like \Package{natbib}\IndexPackage{natbib}, +The bibliography makes external sources accessible. As a rule, the +bibliography is created from an external file with a database-like structure +using the \BibTeX{} program. You can use the \BibTeX{} style to change both +the format of the entries and their sorting. If you use an additional +bibliography package like \Package{natbib}\IndexPackage{natbib}, \Package{babelbib}\IndexPackage{babelbib}, or -\Package{biblatex}\IndexPackage{bublatex} limits the influence of -\KOMAScript{} to the bibliography hardly. In such cases it is important so see -the manual of the bibliography package! General information about bibliography -may be found in \cite{lshort}. +\Package{biblatex}\IndexPackage{biblatex}, \KOMAScript{}'s influence over the +bibliography disappears. In such cases, you must follow the manual of the +relevant bibliography package. You can find general information about +bibliographies in \cite{lshort}. \begin{Declaration} - \OptionVName{bibliography}{selection} + \OptionVName{bibliography}{setting} \end{Declaration} -For a start, \PName{selection}\ChangedAt{v3.00}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} may be any already defined -bibliography formation style. There are two predefined formation styles at -\KOMAScript{}. You should not misconceive them with the styles used by -\BibTeX\Index{BibTeX=\BibTeX} which you may select using -\Macro{bibstyle}. While \BibTeX{} influences not only the sorting but also the +For a start,\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} you can select any predefined bibliography style in +\PName{setting}. There are two such bibliography styles predefined in +\KOMAScript{}. You should not confuse them with the styles used by +\BibTeX\Index{BibTeX=\BibTeX}, which you select with +\Macro{bibstyle}. While \BibTeX{} determines both the sorting and the contents of the bibliography, \KOMAScript{} influences only some basic -features of the bibliography or a tiny amount of formation features of the -entries to the bibliography. +features of the bibliography and few properties of the entry format. -Option\important{\OptionValue{bibliography}{oldstyle}} +The\important{\OptionValue{bibliography}{oldstyle}} \OptionValue{bibliography}{oldstyle}% -\IndexOption{bibliography~=\PValue{oldstyle}} selects a compact formation of -the bibliography entries. In this case command -\DescRef{maincls-experts.cmd.newblock}\IndexCmd{newblock} inside of the entries will only result in -a small horizontal distance. The name is a result of the fact, that this is -the mostly used classic kind of bibliography. In opposite to -this\important[i]{\begin{tabular}[t]{@{}l@{}} - \Option{bibliography=}\\ - \quad\PValue{openstyle}\end{tabular}}% +\IndexOption{bibliography~=\textKValue{oldstyle}} option selects a compact +format for bibliography entries. In this case, using the +\DescRef{maincls-experts.cmd.newblock}\IndexCmd{newblock} command results in +only a small glue between the entries. The name comes from the fact that this +is the most common classic form of a bibliography. +In\important{\OptionValue{bibliography}{openstyle}} contrast, the \OptionValue{bibliography}{openstyle}% -\IndexOption{bibliography~=\PValue{openstyle}}. selects a more modern and open -kind of bibliography. The name is a result of the fact, that command -\DescRef{maincls-experts.cmd.newblock} inserts a paragraph break. The entries will be more -structured by this. They are less compact and seem more relaxed or -open. Information about definition of new formation styles may be found in -description of command \DescRef{maincls-experts.cmd.newbibstyle} in -\autoref{sec:maincls-experts.experts} at +\IndexOption{bibliography~=\textKValue{openstyle}} setting selects a more +modern and open kind of bibliography. The name comes from the fact that the +\DescRef{maincls-experts.cmd.newblock} command inserts a paragraph break. The +bibliography entries appear more structured. They are less compact and seem +more relaxed or open. Information about defining new bibliography styles can +be found in the description of the \DescRef{maincls-experts.cmd.newbibstyle} +command in \autoref{sec:maincls-experts.experts}, \DescPageRef{maincls-experts.cmd.newbibstyle}. -Beside the formation style one more feature may be selected using -\PName{selection}. The bibliography is a kind of contents list. But instead of -listing contents of the document itself, it references to external -contents. Because of this, someone may say, that -the\important[i]{\begin{tabular}[t]{@{}l@{}} - \Option{bibliography=}\\ - \quad\PValue{totocnumbered} - \end{tabular}} bibliography is a chapter -or section on its own and should have a chapter or section number. You may -select this with option \OptionValue{bibliography}{totocnumbered}% -\IndexOption{bibliography~=\PValue{totocnumbered}} which will therefor also -generate an entry to the table of contents.In my opinion the bibliography is -nothing you've written on your own and so does not merits a numbered entry to -the table of contents. A entry without number may be set with option -\OptionValue{bibliography}{totoc}% -\IndexOption{bibliography~=\PValue{totoc}}. Nevertheless, the default would be -neither a number nor an entry to the table of contents and corresponds to +In addition to the formatting style, you can select one more feature using +\PName{setting}. The bibliography is a kind of list of contents. But instead +of listing the contents of the document itself, it references external works. +With this reasoning, you could argue that the bibliography is a separate +chapter or section and therefore deserves a chapter or section number. The +\OptionValue{bibliography}{numbered}% +\important{\OptionValue{bibliography}{numbered}}% +\IndexOption{bibliography~=\textKValue{numbered}} setting does exactly that, +including creating an entry in the table of contents. In my opinion, a +traditional, annotated source list should by this reasoning be a separate +chapter too. Moreover, the bibliography is ultimately nothing you've written +yourself and so merits at most an unnumbered entry in the table of contents, +which is achieved with the \OptionValue{bibliography}{totoc}% +\IndexOption{bibliography~=\textKValue{totoc}} option. The default setting, +where the bibliography is produced as an unnumbered chapter and does not +receive an entry in the table of contents corresponds to \OptionValue{bibliography}{nottotoc}% -\IndexOption{bibliography~=\PValue{nottotoc}}. For more information see option -\DescRef{\LabelBase.option.toc} in \autoref{sec:\LabelBase.toc}, especially values -\PValue{bibliographynumbered}, \PValue{bibliography}, and -\PValue{nobibliography} to this option at +\IndexOption{bibliography~=\textKValue{nottotoc}}. For more information, see +the \DescRef{\LabelBase.option.toc} option in \autoref{sec:\LabelBase.toc}, +especially the \PValue{bibliographynumbered}, \PValue{bibliography}, +and\PValue{nobibliography} values for this option on \DescPageRef{\LabelBase.option.toc.bibliography}. Sometimes\ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} it is not usefull to have one bibliography for the whole -document but a bibliography at every chapter of a document made using -\Class{scrbook} or \Class{scrreprt}. In that case -you'd\important{\OptionValue{bibliography=leveldown}} need the bibliography -itself not to be a chapter but one level below, a section. You may achieve -this using Option \OptionValue{bibliography}{leveldown}% -\IndexOption{bibliography~=\PValue{leveldown}}. You may use this also if you'd -combine several lists and the bibliography together below one heading. So this -option is also available with \Class{scrartcl}. - -A summary of all available values for option \Option{bibliography} may be -found in \autoref{tab:\LabelBase.bibliography}. Nevertheless you should note, -that additional values may be generated using + \Class{scrartcl}} a document made using \Class{scrbook} or \Class{scrreprt} +will have a bibliography for every chapter rather than one bibliography for +the whole document. In that case, it makes sense for the bibliography +itself\important{\OptionValue{bibliography=leveldown}} to be not a chapter but +a section. You can achieve this using the +\OptionValue{bibliography}{leveldown}% +\IndexOption{bibliography~=\textKValue{leveldown}} option. You can also use +this if you want the bibliography to appear with other lists under a common +heading, therefore this option is also available with \Class{scrartcl}. + +You can find a summary of available values for the \Option{bibliography} +option in \autoref{tab:\LabelBase.bibliography}. Note, however, that you can +define new values with \DescRef{maincls-experts.cmd.newbibstyle}\IndexCmd{newbibstyle}. \begin{table} - \caption[{Available values of option \Option{bibliography}}]{% - Predefined values of option \Option{bibliography} to select the formation - of the bibliography} + \caption[{Available values for the \Option{bibliography} option}]{% + Predefined values for the \Option{bibliography} option for setting the + bibliography format} \label{tab:\LabelBase.bibliography} \begin{desctabular} \pventry{leveldown}{% \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - The bibliography will use a heading of one step lower section level than - default.% - \IndexOption{bibliography~=\PValue{leveldown}}}% - \pventry{nottotoc}{% - The bibliography will neither have an entry at the table of contents nor - a number,% - \IndexOption{bibliography~=\PValue{nottotoc}}}% + The bibliography uses a sectioning command one level lower than + the default.% + \IndexOption{bibliography~=\textKValue{leveldown}}}% + \entry{\PValue{notoc}, \PValue{nottotoc}, \PValue{plainheading}}{% + The bibliography receives neither an entry in the table of contents nor + a number.% + \IndexOption{bibliography~=\textKValue{nottotoc}}}% + \entry{\PValue{numbered}, \PValue{tocnumbered}, \PValue{totocnumbered}, + \PValue{numberedtoc}, \PValue{numberedtotoc}}{% + The bibliography receives an entry in the table of contents and a + number.% + \IndexOption{bibliography~=\textKValue{numbered}}}% \pventry{oldstyle}{% - The bibliography will use the classic, compact formation, where - \DescRef{maincls-experts.cmd.newblock}\IndexCmd{newblock} generates an - expandable horizontal distance only.% - \IndexOption{bibliography~=\PValue{oldstyle}}}% + The bibliography uses the classic, compact formation, where + \DescRef{maincls-experts.cmd.newblock}\IndexCmd{newblock} generates only + a horizontal glue.% + \IndexOption{bibliography~=\textKValue{oldstyle}}}% \pventry{openstyle}{% - The bibliography will use the structured, open formation, where + The bibliography uses the structured, open format where \DescRef{maincls-experts.cmd.newblock}\IndexCmd{newblock} generates a paragraph break.% - \IndexOption{bibliography~=\PValue{openstyle}}}% - \pventry{totoc}{% - The bibliography will have an entry at the table of contents but no + \IndexOption{bibliography~=\textKValue{openstyle}}}% + \pventry{standardlevel}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The bibliography uses the standard sectioning command level.% + \IndexOption{bibliography~=\textKValue{standardlevel}}}% + \entry{\PValue{toc}, \PValue{totoc}, \PValue{notnumbered}}{% + The bibliography receives an entry in the table of contents but no number.% - \IndexOption{bibliography~=\PValue{totoc}}}% - \pventry{totocnumbered}{% - The bibliography will have an entry at the table of contents and a - number at the heading.% - \IndexOption{bibliography~=\PValue{totocnumbered}}}% + \IndexOption{bibliography~=\textKValue{totoc}}}% \end{desctabular} \end{table} % @@ -3926,29 +4445,28 @@ that additional values may be generated using \begin{Declaration} \Macro{setbibpreamble}\Parameter{preamble} \end{Declaration}% -The command \Macro{setbibpreamble} can be used to set a preamble for the -bibliography\Index{bibliography}. This can be achieved by placing the preamble -before the command for issuing the bibliography. However, it need not be -directly in front of it. For example, it could be placed at the beginning of -the document. Similar\textnote{Attention!} to the options +You can use the \Macro{setbibpreamble} command to set a preamble for the +bibliography\Index{bibliography}. This preamble must be placed before the +command for issuing the bibliography. However, it need not be directly +in front of it. For example, it could be placed at the beginning of +the document. Like\textnote{Attention!} the \OptionValueRef{\LabelBase}{bibliography}{totoc} and -\OptionValueRef{\LabelBase}{bibliography}{totocnumbered}, this command can -only be successful if you have not loaded a package which prevents this by -redefining the \Environment{thebibliography} environment. Even though the -\Package{natbib} package\IndexPackage{natbib} makes unauthorized use of -internal macros of {\KOMAScript} it could be achieved that -\Macro{setbibpreamble} works with the current version of \Package{natbib} (see -\cite{package:natbib}). +\OptionValueRef{\LabelBase}{bibliography}{totocnumbered} options, this command +only works if you have not loaded a package which prevents this from happening +by redefining the \Environment{thebibliography} environment. Although the +\Package{natbib} package\IndexPackage{natbib} uses undocumented, internal +{\KOMAScript} macros, \Macro{setbibpreamble} could still work with the current +version of \Package{natbib} (see \cite{package:natbib}). \begin{Example} - You want to point out that the sorting of the references in the - bibliography is not according to their occurrence in the text, but - in alphabetical order. You use the following command: + You want to point out that the bibliographical references are sorted + alphabetically by the names of the authors. You therefore use the following + command: \begin{lstcode} \setbibpreamble{References are in alphabetical order. References with more than one author are sorted according to the first author.\par\bigskip} \end{lstcode} - The \Macro{bigskip}\IndexCmd{bigskip} command makes sure that the + The \Macro{bigskip}\IndexCmd{bigskip} command ensures that the preamble and the first reference are separated by a large vertical space.% \end{Example}% @@ -3962,13 +4480,14 @@ internal macros of {\KOMAScript} it could be achieved that This\textnote{Attention!}\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} command exists only if the environment \Environment{thebibliography} has not been redefined by another -package. It provides a break at the bibliography. The \PName{interruption - code} will be expanded inside a group. Such a break may be, e.\,g., a -heading using \DescRef{\LabelBase.cmd.minisec}. Unfortunately it is not -possible to add this command to the \BibTeX{} database using, e.\,g., a -special kind of \BibTeX{} entry. Because of this, users may use is currently -only if they make the bibliography on their own. Because of this usage is very -limited.% +package. With this instruction, you can insert a break into the +bibliography. The \PName{interruption code} will be expanded inside a +group. Such a break may be, for example, a heading using +\DescRef{\LabelBase.cmd.minisec}. Unfortunately there is currently no way to +have this command automatically generated, for example by using a special +entry in the \BibTeX{} database. Therefore, it can currently only be used by +users who edit the bibliography directly. For this reason, its usefulness is +very limited.% % \EndIndexGroup @@ -3978,23 +4497,22 @@ limited.% \Macro{AtEndBibliography}\Parameter{code} \end{Declaration} In\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} -some cases it may be useful to add some \PName{code} after the bibliography -preamble or just before the end of the bibliography. This may be achieved -using one of this instructions. +some cases, it may be useful to add some \PName{code} after the bibliography +preamble or just before the end of the bibliography. This is possible with the +help of these two instructions. \begin{Example} - You want to set the bibliography not justified but ragged right. This may be - achieved using: + You want to set the bibliography not justified but ragged right. You can + achieve this with: \begin{lstcode} \AfterBibliographyPreamble{\raggedright} \end{lstcode} - You may place this instruction anywhere before the - bibliography. Nevertheless it is recommended to do so at the preamble of the - document or inside your own package. + You can put this instruction anywhere before the bibliography. However, it is + recommended to do so in the preamble of the document or a separate package. \end{Example} The\textnote{Attention!} functionality of this instruction depends on -cooperation with packages modifying the bibliography, if such a package should -be used (see \autoref{sec:maincls-experts.coexistence}, -\DescPageRef{maincls-experts.cmd.AfterBibliographyPreamble}).% +cooperation with packages modifying the bibliography, if you use such a +package\iffree{}{(see \autoref{sec:maincls-experts.coexistence}, +\DescPageRef{maincls-experts.cmd.AfterBibliographyPreamble})}.% % \EndIndexGroup % @@ -4004,54 +4522,83 @@ be used (see \autoref{sec:maincls-experts.coexistence}, \section{Index} \seclabel{index} \BeginIndexGroup -\BeginIndex{}{index} -For general information about making an index see \cite{lshort}, -\cite{makeindex}, and \cite{xindy}. Using a package, that redefines commands -or environments for the index, may limit the influence of \KOMAScript{} to the -index hardly. This would be valid, e.\,g., for usage of package -\Package{index}\IndexPackage{index} but not for usage of package -\Package{splitidx}\IndexPackage{splitidx} (see \cite{package:splitindex}). +For general information about making a keyword index, see \cite{lshort}, +\cite{makeindex}, and \cite{xindy}. Using a package that redefines +commands or environments for the index \KOMAScript{}'s ability to influence +the index may disappear. This applies, for example, when using the +\Package{index}\IndexPackage{index} package, but not when using the +\Package{splitidx}\IndexPackage{splitidx} package (see +\cite{package:splitindex}). \begin{Declaration} - \OptionVName{index}{selection}% + \OptionVName{index}{setting}% \end{Declaration} \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% -The index is chapter (\Class{scrbook} or \Class{scrreprt}) or section -(\Class{scrartcl}) without heading number or entry at the table of contents by -default or option -\OptionValue{index}{default}\IndexOption{index~=\PValue{default}}. -The\important{\OptionValue{index}{totoc}} index does not need an entry at the -table of contents, because it should always be the last element of a -document. Nevertheless, such an entry may be achieved using option -\OptionValue{index}{totoc}\IndexOption{index~=\PValue{totoc}}. +By default or with \OptionValue{index}{default}% +\IndexOption{index~=\textKValue{default}}, the index is an unnumbered chapter +(\Class{scrbook} or \Class{scrreprt}) or section (\Class{scrartcl}) without an +entry in the table of contents. Since\important{\OptionValue{index}{totoc}} +the index usually comes last in a book or similar document, it does not +actually need an entry in the table of contents. Nevertheless, if you want to +do this, for example because you are working with a multi-index keyword +dictionary such as the one that appears in this \iffree{guide}{book}, you can +create this with the +\OptionValue{index}{totoc}\IndexOption{index~=\textKValue{totoc}} option. You\ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} can even number the index using option -\OptionValue{index}{numbered}\IndexOption{index~=\PValue{numbered}}. See also -option \DescRef{\LabelBase.option.toc} with value \PValue{index} or -\PValue{indexnumbered} in \autoref{sec:\LabelBase.toc} from -\DescPageRef{\LabelBase.option.toc.index} onward. - -A summary of all available values for option \Option{index} may be found in -\autoref{tab:\LabelBase.index}. + \Class{scrartcl}} can even number the index using the +\OptionValue{index}{numbered}\IndexOption{index~=\textKValue{numbered}} +setting. See also the \DescRef{\LabelBase.option.toc} option with the +\PValue{index} or \PValue{indexnumbered} values in +\autoref{sec:\LabelBase.toc} starting at +\DescPageRef{\LabelBase.option.toc.index}. + +For example, if you create multiple indexes with +\Package{splitidx}\IndexPackage{splitidx} (see \cite{package:splitindex}), +it may be useful to group them under a common heading. To make this possible, +\OptionValue{index}{leveldown}% +\ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\important{\OptionValue{index}{leveldown}} places the index +one sectioning level deeper than usual. In \Class{scrbook} and +\Class{scrreprt}, it is no longer a chapter but a section; with +\Class{scrartcl}, a subsection. The \OptionValue{index}{standardlevel}% +\ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\important{\OptionValue{index}{standardlevel}} option is +the counterpart to this and cancels any instance of +\OptionValue{index}{leveldown} used previously. + +You can find a summary of the available values for the \PName{setting} of +\Option{index} in \autoref{tab:maincls.index}. \begin{table} - \caption{Available values of option \Option{index}}% - \label{tab:\LabelBase.index} + \caption{Available values for the \Option{index} option} + \label{tab:maincls.index} \begin{desctabular} - \entry{\PValue{default}, \PValue{nottotoc}, \PValue{plainheading}}{% - The index will not have an entry at the table of contents.% - \IndexOption{index~=\PValue{default}}}% - \entry{\PValue{numbered}, \PValue{totocnumbered}}{% + \pventry{leveldown}{% + \ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The index is moved down by one sectioning level.% + \IndexOption{index~=\textKValue{leveldown}}% + }% + \entry{\PValue{notoc}, \PValue{nottotoc}, \PValue{plainheading}}{% + The index does not receive an entry in the table of contents.% + \IndexOption{index~=\textKValue{nottotoc}}}% + \entry{\PValue{numbered}, \PValue{tocnumbered}, \PValue{totocnumbered}, + \PValue{numberedtoc}, \PValue{numberedtotoc}}{% + \ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The index receives an entry in the table of contents and is numbered.% + \IndexOption{index~=\textKValue{numbered}}}% + \pventry{standardlevel}{% \ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - The index will have an entry at the table of contents and also will have - a heading number.% - \IndexOption{index~=\PValue{numbered}}}% - \entry{\PValue{totoc}, \PValue{toc}, \PValue{notnumbered}}{% - The index will have an entry at the table of contents, but will not have - a heading number.% - \IndexOption{index~=\PValue{totoc}}}% + The index is at the usual sectioning level.% + \IndexOption{index~=\textKValue{standardlevel}}% + }% + \entry{\PValue{toc}, \PValue{totoc}, \PValue{notnumbered}}{% + The index receives an entry in the table of contents without being + numbered.% + \IndexOption{index~=\textKValue{totoc}}}% \end{desctabular} \end{table} % @@ -4061,9 +4608,9 @@ A summary of all available values for option \Option{index} may be found in \begin{Declaration} \Macro{setindexpreamble}\Parameter{preamble} \end{Declaration}% -Similarly to the bibliography you can use a preamble to the +As with the bibliography, you can also provide a preamble to the index. This is often the case if you have more than one index or if -you use different kinds of referencing by highlighting the page +you mark different kinds of references by highlighting the page numbers in different ways. \begin{Example} You have a document in which terms are both defined and used. The @@ -4071,31 +4618,38 @@ numbers in different ways. your reader aware of this fact. Thus you insert a preamble for the index: \begin{lstcode} - \setindexpreamble{In \textbf{bold} printed page numbers are - references to the definition of terms. Other page numbers - indicate the use of a term.\par\bigskip} + \setindexpreamble{All page numbers printed in \textbf{bold} + refer to definitions of terms. Page numbers printed + normally refer to pages where the term is used.\par\bigskip} \end{lstcode} \end{Example} -Please note that the page style of the first page of the index is changed. The -applied page style is defined in the macro +Note\textnote{Attention!} that the page style is changed for the first page +of the index. The page style that is applied is defined in the macro \DescRef{\LabelBase.cmd.indexpagestyle} (see \autoref{sec:\LabelBase.pagestyle}, \DescPageRef{\LabelBase.cmd.indexpagestyle}). -The production, sorting and output of the index is done by the -standard {\LaTeX} packages and additional programs. Similar to the -standard classes {\KOMAScript} only provides the basic macros and -environments.% +The usual \LaTeX{} packages and additional programs are responsible for +creating, sorting, and outputting the index.% +\iftrue % Umbruchoptimierung + \iffree{}{ % + For example, the \Package{imakeidx}\IndexPackage{imakeidx} package + (see \cite{package:imakeidx}), which among other things automates the + invocation of the \File{makeindex} or \File{xindy} program, is highly + recommended. This eliminates a common source of error, particularly for + \LaTeX{} beginners.% + } + {\KOMAScript}, like the standard classes, provides only the basic macros + and environments for them.% +\fi % \EndIndexGroup % \EndIndexGroup % -% \EndIndexGroup - \endinput %%% Local Variables: @@ -4105,5 +4659,3 @@ environments.% %%% ispell-local-dictionary: "english" %%% TeX-master: "../guide" %%% End: - -% LocalWords: endnotes interleaf diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrdatetime.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrdatetime.tex index 2cd16e0229d..7acd9f2bf79 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrdatetime.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrdatetime.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrdatetime.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrdatetime.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,52 +46,53 @@ % ============================================================================ \KOMAProvidesFile{scrdatetime.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (chapter: scrdate, scrtime)] -\translator{Markus Kohm\and Gernot Hassenpflug} +\translator{Markus Kohm\and Gernot Hassenpflug\and Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-02-05 -\chapter{The Day of the Week Using \Package{scrdate}} +\chapter{The Day of the Week with \Package{scrdate}} \labelbase{scrdate} \BeginIndexGroup \BeginIndex{Package}{scrdate} -With version~3.05a the functionality of this package enhanced a lot. Beside of -the current day of the week\Index{day>of the week} this package provides the -day of the week of every date of the Gregorian calendar now. +Originally, the \Package{scrdate} package could only give the day of the week +for the current date. Nowadays, it offers this and more for any date in the +Gregorian calendar. \begin{Declaration} \Macro{CenturyPart}\Parameter{year}\\% \Macro{DecadePart}\Parameter{year}% \end{Declaration}% -The\ChangedAt{v3.05a}{\Package{scrdate}} command \Macro{CenturyPart} offers -the value of the century digits\,---\,hundreds and thousands\,---\,of a -\PName{year}. The command \Macro{DecadePart} in difference offers the other -digits which are the units and tens. The number of digits of \PName{year} does -not care. The value may be assigned to a counter or may be used for -calculations, i.\,e., using \Macro{numexpr}\IndexCmd{numexpr}. For -output\textnote{Attention!} of an Arabic number of the value prefix it with -\Macro{the}\IndexCmd{the}. +The\ChangedAt{v3.05a}{\Package{scrdate}} \Macro{CenturyPart} command returns +the value of the century digits\,---\,thousands and hundreds\,---\,of a +\PName{year}. The \Macro{DecadePart} command, on the other hand, gives the +value of the remaining digits, i.\,e. the tens and the units. The +\PName{year} can have any number of digits. You can assign the value directly +to a counter or use it for calculations with +\Macro{numexpr}\IndexCmd{numexpr}. To output\textnote{Attention!} it as an +Arabic number, you should prefix it with \Macro{the}\IndexCmd{the}. \begin{Example} - You want to calculate and output the century of the current year. + You want to calculate and print the century of the current year. \begin{lstcode} - The year \the\year\ is the year \the\DecadePart{\year} + The year \the\year\ is year \the\DecadePart{\year} of the \engord{\numexpr\CenturyPart{\year}+1\relax} century. \end{lstcode} The result would be: \begin{quote} - The year \the\year\ is the year \the\DecadePart{\year} + The year \the\year\ is year \the\DecadePart{\year} of the \engordnumber{\numexpr\CenturyPart{\year}+1\relax} century. \end{quote} - Package \Package{engord}\IndexPackage{engord} has been used for this - example. See \cite{package:engord} for more information. + This example uses the \Package{engord}\IndexPackage{engord} package. + See \cite{package:engord} for more information. \end{Example} -Please\textnote{Attention!} note, that within used method of counting the -year~2000 is the year~0\,---\,and therefore the first year\,---\,of the -21st~century.% +Note\textnote{Attention!} that the counting method used here treats the year +2000 as year~0\,---\,and therefore the first year\,---\,of the 21st~century. +If necessary, however, you can make a correction with \Macro{numexpr}, as +shown for the ordinal number in the example.% \EndIndexGroup @@ -99,17 +100,17 @@ year~2000 is the year~0\,---\,and therefore the first year\,---\,of the \Macro{DayNumber}\Parameter{year}\Parameter{month}\Parameter{day}\\% \Macro{ISODayNumber}\Parameter{ISO-date}% \end{Declaration}% -These\ChangedAt{v3.05a}{\Package{scrdate}} two commands offers the value of -the number of the day of the week\Index{day>of the week} of any date. The -differ only in the kind of date declaration. Command \Macro{DayNumber} needs -\PName{year}, \PName{month}, and \PName{day} as separate parameters. Command -\Macro{ISODayNumber} expects an \PName{ISO-date} as a single argument. The -expected format of the \PName{ISO-date} is: +These\ChangedAt{v3.05a}{\Package{scrdate}} two commands return the value of +the day-of-the-week\Index{day>of the week} number for any date. They differ +only in the method of specifying the date. While the \Macro{DayNumber} command +requires the \PName{year}, \PName{month}, and \PName{day} as separate +parameters, the \Macro{ISODayNumber} command expects an \PName{ISO-date} as a +single argument, \PName{ISO-date}, using the ISO notation \PName{year}\texttt{-}\PName{month}\texttt{-}\PName{day}. It does not matter -whether \PName{month} or \PName{day} have one or two digits. The result of -both commands may be assigned to a counter or used for calculations, i.\,e., -using \Macro{numexpr}\IndexCmd{numexpr}. For output\textnote{Attention!} of an -Arabic number of the value prefix it with \Macro{the}\IndexCmd{the}. +if the \PName{month} or \PName{day} have one or two digits. You can use the +result of both commands to assign directly to a counter or for calculations +using \Macro{numexpr}\IndexCmd{numexpr}. To print\textnote{Attention!} it as +an Arabic number, you should prefix it with \Macro{the}\IndexCmd{the}. \begin{Example} You want to know the number of the day of the week of the 1st~May~2027. @@ -124,28 +125,29 @@ Arabic number of the value prefix it with \Macro{the}\IndexCmd{the}. \end{quote} \end{Example} -A special feature is to walk a number of days into future or past from a given -date. +It is particularly worth noting that you can even step a specified number of +days into the future or or the past from a given date. \begin{Example} - You want to know the number of the day of the week, that will be in 12~days - and that will be 24~days before the 24th~December~2027. + You want to know the number of the day of the week 12~days from now + and 24~days before the 24th~December~2027. \begin{lstcode} - In 12~days the number of the day of the week - will be \the\DayNumber{\year}{\month}{\day+12} and + In 12~days, the number of the day of the week + will be \the\DayNumber{\year}{\month}{\day+12}, and 24~days before the 24th~December~2027 it will be \the\ISODayNumber{2027-12-24-24}. \end{lstcode} - The result may be, e.\,g.: + The result could be, for example: \begin{quote} - In 12~days the number of the day of the week - will be \the\DayNumber{\year}{\month}{\day+12} and + In 12~days, the number of the day of the week + will be \the\DayNumber{\year}{\month}{\day+12}, and 24~days before the 24th~December~2027 it will be \the\ISODayNumber{2027-12-24-24}. \end{quote} \end{Example} -The days of the week are numbered: Sunday\,=\,0, Monday\,=\,1, Tuesday\,=\,2, -Wednesday\,=\,3, Thursday\,=\,4, Friday\,=\,5, and Saturday\,=\,6.% +The days of the week are numbered as follows: Sunday\,=\,0, Monday\,=\,1, +Tuesday\,=\,2, Wednesday\,=\,3, Thursday\,=\,4, Friday\,=\,5, and +Saturday\,=\,6.% % \EndIndexGroup @@ -155,48 +157,48 @@ Wednesday\,=\,3, Thursday\,=\,4, Friday\,=\,5, and Saturday\,=\,6.% \Macro{DayName}\Parameter{year}\Parameter{month}\Parameter{day}\\% \Macro{ISODayName}\Parameter{ISO-date}% \end{Declaration}% -Usually\ChangedAt{v3.05a}{\Package{scrdate}} you do not want to know the number -of the day of the week, but the name of the day of the week. Because of this, -the command \Macro{DayNameByNumber} offers the name of the day of the week -corresponding with a number. The number may be the result of \Macro{DayNumber} -or \Macro{ISODayNumber}. The two commands \Macro{DayName} and -\Macro{ISODayName} directly offer the name of the day of the week of a given -date. +Usually\ChangedAt{v3.05a}{\Package{scrdate}} you are less interested in the +number of the day of the week than in its name. Therefore, the +\Macro{DayNameByNumber} command returns the name of the day of the week +corresponding to a day-of-the-week number. This number can be the result, for +example, of \Macro{DayNumber} or \Macro{ISODayNumber}. The two commands +\Macro{DayName} and \Macro{ISODayName} directly return the name of the day of +the week of a given date. \begin{Example} You want to know the name of the day of the week of the 24th~December~2027. \begin{lstcode} - Please pay you bill until \ISODayName{2027-12-24}, - 24th~December~2027. + Please pay by \ISODayName{2027-12-24}, + 24th~December~2027 the amount of \dots. \end{lstcode} The result will be: \begin{quote} - Please pay you bill until \ISODayName{2027-12-24}, - 24th~December~2027. + Please pay by \ISODayName{2027-12-24}, + 24th~December~2027 the amount of \dots. \end{quote} \end{Example} -Again a special feature is to make some calculations inside the argument of -\Macro{DayName}. +Once again, it is particularly worth noting that you can perform calculations, +to a certain extent: \begin{Example} - You want to know the names of the days of the week, that will be in 12~days - and that will be 24~days before the 24th~December~2027. + You want to know the names of the day of the week 12~days from now + and 24~days before the 24th~December~2027. \begin{lstcode} - In 12~days the name of the day of the week - will be \DayName{\year}{\month}{\day+12} and + In 12~days, the name of the day of the week + will be \DayName{\year}{\month}{\day+12}, and 24~days before the 24th~December~2027 it will be - \ISODayName{2027-12-24-24}. Nevertheless two weeks - and three days after a Wednesday a - \DayNameByNumber{3+2*7+3} will follow. + \ISODayName{2027-12-24-24}, while two weeks + and three days after a Wednesday will be a + \DayNameByNumber{3+2*7+3}. \end{lstcode} - The result may be, e.\,g.: + The result could be, for example: \begin{quote} - In 12~days the name of the day of the week - will be \DayName{\year}{\month}{\day+12} and + In 12~days, the name of the day of the week + will be \DayName{\year}{\month}{\day+12}, and 24~days before the 24th~December~2027 it will be - \ISODayName{2027-12-24-24}. Nevertheless two weeks - and three days after a Wednesday a - \DayNameByNumber{3+2*7+3} will follow. + \ISODayName{2027-12-24-24}, while two weeks + and three days after a Wednesday will be a + \DayNameByNumber{3+2*7+3}. \end{quote} \end{Example}% % @@ -209,54 +211,52 @@ Again a special feature is to make some calculations inside the argument of \Macro{todaysname}% \Macro{todaysnumber}% \end{Declaration}% -In the prior examples the current date have been given cumbersomely and -explicitly using the \TeX{} registers \Macro{year}\IndexCmd{year}, -\Macro{month}\IndexCmd{month}, and \Macro{day}\IndexCmd{day}. The commands +In the previous examples, the current date was always specified cumbersomely +using the \TeX{} registers \Macro{year}\IndexCmd{year}, +\Macro{month}\IndexCmd{month}, and \Macro{day}\IndexCmd{day}. The \Macro{ISOToday}\ChangedAt{v3.05a}{\Package{scrdate}} and \Macro{IsoToday} -offers the current date in ISO-notation directly. These commands differ in the -number of digits for numbers less than 10 only. \Macro{ISOToday} prefixes -numbers less than 10 for the month and day with a 0. In opposite to this -\Macro{IsoToday} will show numbers less than 10 for the month and day with one -digit only. Command \Macro{todaysname} directly offers the name of the current -day of the week. Command \Macro{todaysnumber} offers the number of that name -instead. More information about usability of this value may be found at -previous description of \DescRef{scrdate.cmd.DayNumber} and \DescRef{scrdate.cmd.ISODayNumber}. +commands directly return the current date in ISO-notation. These commands +differ only in the fact that \Macro{ISOToday} always outputs a two-digit month +and day, while \Macro{IsoToday} outputs single-digit numbers for values less +than 10. The \Macro{todaysname} command directly returns the name of the +current day of the week, while \Macro{todaysnumber} returns the number of the +current day of the week. You can find more information about using this value +in the explanations of \DescRef{scrdate.cmd.DayNumber} and +\DescRef{scrdate.cmd.ISODayNumber}. \begin{Example} - I want to show you the name of the weekday in which this document has been - type-set: - \begin{lstlisting} - I have done the {\LaTeX} run of this document - on a \todaysname. - \end{lstlisting} - This will result in, e.\,g.: + I want to show you on what day of the week this document was typeset: +\begin{lstlisting} + This document was created on a \todaysname. +\end{lstlisting} + This will result, for example, in: \begin{quote} - I have done the {\LaTeX} run of this document - on a \todaysname. + This document was created on a \todaysname. \end{quote} \end{Example} -Note that the package is not able to decline words. The known terms -are the nominative singular that may be used, e.\,g., in the date of a -letter. Given this limitation, the example above can work correctly -only for some languages. +For languages that have a case system for nouns, note that the package cannot +decline words. The terms are given in the form appropriate for displaying a +date in a letter, which is the nominative singular for the currently supported +languages. Given this limitation, the example above will not work correctly if +translated directly into some other languages. \begin{Explain} - The\textnote{Hint!} names of the weekdays are saved in capitalized form, - i.\,e., the first letter is a capital letter, all the others are lowercase - letters. But for some languages you may need the names completely in - lowercase. You may achieve this using the standard {\LaTeX} command - \Macro{MakeLowercase}\IndexCmd{MakeLowercase}% - \important{\Macro{MakeLowercase}}, e.\,g.: + The\textnote{Hint!} names of the weekdays in \Package{scrdate} all have + initial capital letters. If you need the names completely in lower case, for + example because that is the convention in the relevant language, simply wrap + the command with the \LaTeX{} \Macro{MakeLowercase}\IndexCmd{MakeLowercase}% + \important{\Macro{MakeLowercase}} command: % Umbruchkorrektur: listings \begin{lstcode} \MakeLowercase{\todaysname} \end{lstcode} - This converts the whole argument into lower case letters. Of course, this - may be done also using previous described commands + This converts the whole argument into lower-case letters. Of course, you can + also do this for \DescRef{scrdate.cmd.DayNameByNumber}\IndexCmd{DayNameByNumber}, - \DescRef{scrdate.cmd.DayName}\IndexCmd{DayName} and - \DescRef{scrdate.cmd.ISODayName}\IndexCmd{ISODayName}.% + \DescRef{scrdate.cmd.DayName}\IndexCmd{DayName}, and + \DescRef{scrdate.cmd.ISODayName}\IndexCmd{ISODayName} commands described + above.% \end{Explain}% \EndIndexGroup @@ -264,23 +264,24 @@ only for some languages. \begin{Declaration} \Macro{nameday}\Parameter{name} \end{Declaration}% -Analogous to how the output of \Macro{today} can be modified using -\DescRef{maincls.cmd.date}\IndexCmd{date}, so the output of \DescRef{scrdate.cmd.todaysname} -can be changed to \PName{name} by using \Macro{nameday}. +Just as you can directly modify the output of \Macro{today} with +\DescRef{maincls.cmd.date}\IndexCmd{date}, so you can change the output of +\DescRef{scrdate.cmd.todaysname} to \PName{name} with \Macro{nameday}. \begin{Example} You change the current date to a fixed value using - \DescRef{maincls.cmd.date}. You are not interested in the actual name of - the day, but want only to show that it is a workday. So you set: + \DescRef{maincls.cmd.date}. You are not interested in the actual name of the + day, but want only to show that it is a workday. So you write: \begin{lstlisting} \nameday{workday} \end{lstlisting} - After this the previous example will result in: + After this, the previous example will result in: \begin{quote}\nameday{workday} - I have done the {\LaTeX} run of this document on a \todaysname. + This document was created on a \todaysname. \end{quote} \end{Example} -There's no such command for changing the result of -\DescRef{scrdate.cmd.ISOToday}\IndexCmd{ISOToday} or \DescRef{scrdate.cmd.IsoToday}\IndexCmd{IsoToday}. +There's no corresponding command to change the result of +\DescRef{scrdate.cmd.ISOToday}\IndexCmd{ISOToday} or +\DescRef{scrdate.cmd.IsoToday}\IndexCmd{IsoToday}.% \EndIndexGroup @@ -291,7 +292,7 @@ There's no such command for changing the result of \Parameter{Friday}\Parameter{Saturday} \Parameter{Sunday}% \end{Declaration} -Currently the package \Package{scrdate} knows the following languages: +Currently the \Package{scrdate} package recognizes the following languages: \begin{itemize}\setlength{\itemsep}{.5\itemsep} \item Croatian (\PValue{croatian}), \item Czech (\PValue{czech}\ChangedAt{v3.13}{\Package{scrdate}}), @@ -310,61 +311,57 @@ Currently the package \Package{scrdate} knows the following languages: \item Italian (\PValue{italian}), \item Norwegian (\PValue{norsk}), \item Polish (\PValue{polish}\ChangedAt{v3.13}{\Package{scrdate}}), +\item Slovak (\PValue{slovak}), \item Spanish (\PValue{spanish}), \item Swedish (\PValue{swedish}). \end{itemize} -If you want to configure it for other languages, you may use this command. The -first argument is the name of the language and the other arguments are the -names of the corresponding days. +You can also configure it for additional languages. To do so, the first +argument of \Macro{newdaylanguage} is the name of the language, and the other +arguments are the names of the corresponding days of the week. -In the current implementation it does not matter whether you load -\Package{scrdate} before or after -\Package{german}\IndexPackage{german}, -\Package{ngerman}\IndexPackage{ngerman}, -\Package{babel}\IndexPackage{babel} or similar packages. In both cases the -correct language will be used. +In the current implementation, it does not matter whether you load +\Package{scrdate} before or after \Package{ngerman}\IndexPackage{ngerman}, +\Package{babel}\IndexPackage{babel}, or similar packages. In each case the +correct language will be used provided it is supported. \begin{Explain} - To explain a little bit more exactly: while you are using a language - selection which works in a compatible way to - \Package{babel}\IndexPackage{babel} or - \Package{ngerman}\IndexPackage{ngerman}, the correct language will be used - by \Package{scrdate}. If you are using another language selection you will - get (US-)English names. + To be more precise, as long as you select a language in a way that is + compatible with \Package{babel}\IndexPackage{babel}, \Package{scrdate} will + use the correct language. If this is not the case, you will get (US) English + names. \end{Explain} -By the way: If you found a suitable definition for a language, that has not -been defined before, please mail it to the \KOMAScript{} author. There is a -good chance, that he will add support for the language to \Package{scrdate}.% +Of course, if you create definitions for a language that was previously +unsupported, please mail them to the author of \KOMAScript{}. There is a good +chance that future versions of \KOMAScript{} will add support for that +language.% \EndIndexGroup % \EndIndexGroup -\chapter{Getting the Time with Package \Package{scrtime}} +\chapter{The Current Time with \Package{scrtime}} \labelbase{scrtime} \BeginIndexGroup \BeginIndex{Package}{scrtime} -This package provides an answer to the question of the current time. Since -version~3.05 this package uses the option interface already known from -the \KOMAScript{} classes and several other \KOMAScript{} packages. See for -example \autoref{sec:typearea.options} for more information. +This package lets you find the current time. Starting with version~3.05, the +package also supports the option interface already familiar from the +\KOMAScript{} classes and various other \KOMAScript{} packages. See, for +example, \autoref{sec:typearea.options} for more information. \begin{Declaration}% \Macro{thistime}\OParameter{delimiter}% \Macro{thistime*}\OParameter{delimiter} \end{Declaration}% -\Macro{thistime} results in the current time\Index{time}. The -delimiter between the values of hour, minutes and seconds can be given -in the optional argument. The default symbol of the delimiter is -``\PValue{:}''. - -\Macro{thistime*} works in almost the same way as \Macro{thistime}. -The only difference is that unlike with \Macro{thistime}, with -\Macro{thistime*} the value of the minute field is not preceded by a -zero when its value is less than 10. Thus, with \Macro{thistime} the -minute field has always two places. +\Macro{thistime} returns the current time\Index{time} in hours and minutes. +The delimiter between the values of hour, minutes and seconds can be given in +the optional argument. The default is the character ``\PValue{:}''. + +\Macro{thistime*} works in almost the same way as \Macro{thistime}. The only +difference is that, unlike \Macro{thistime}, \Macro{thistime*} does not add a +leading zero to the minute field when its value is less than 10. Thus, with +\Macro{thistime} the minute field has always two places. \begin{Example} The line \begin{lstlisting} @@ -399,37 +396,40 @@ minute field has always two places. \Macro{settime}\Parameter{time} \end{Declaration}% \Macro{settime} sets the output of \DescRef{scrtime.cmd.thistime} and -\DescRef{scrtime.cmd.thistime*} to the value \PName{time}. Now the optional -parameter of \DescRef{scrtime.cmd.thistime} or \DescRef{scrtime.cmd.thistime*} is ignored, since -the result of \DescRef{scrtime.cmd.thistime} or \DescRef{scrtime.cmd.thistime*} was completely -determined using \Macro{settime}.% +\DescRef{scrtime.cmd.thistime*} to a fixed value. In this case, the optional +parameter of \DescRef{scrtime.cmd.thistime} or \DescRef{scrtime.cmd.thistime*} +is ignored, since the complete string returned by +\DescRef{scrtime.cmd.thistime} or \DescRef{scrtime.cmd.thistime*} has been +explicitly defined. \Macro{settime}.% \EndIndexGroup \begin{Declaration} - \OptionVName{12h}{simple-switch}% + \OptionVName{12h}{simple switch}% \end{Declaration}% \BeginIndex{Option}{24h}% -With option \Option{12h}\ChangedAt{v3.05a}{\Package{scrtime}} one can select -whether the result of \DescRef{scrtime.cmd.thistime} and \DescRef{scrtime.cmd.thistime*} is in 12- or in -24-hour format. The option understands the values for simple-switch listed in -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. The option -without a value is same like \OptionValue{12h}{true} and therefore -12-hour-format will be used. The default is \Option{24h}. - -You may use this option either as a global option in the optional argument of +With the \Option{12h}\ChangedAt{v3.05a}{\Package{scrtime}} option, you can +select whether to print the time given by \DescRef{scrtime.cmd.thistime} and +\DescRef{scrtime.cmd.thistime*} in 12- or 24-hour format. The option accepts +the values for simple switches listed in \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch}. Using the option without a value is +equivalent to \OptionValue{12h}{true}, and therefore activates the +12-hour-format. The default, however, is \Option{24h}. + +You can set this option globally in the optional argument of \DescRef{typearea.cmd.documentclass}, as a package option in the optional -argument of \DescRef{typearea.cmd.usepackage} or after loading the package -using \DescRef{typearea.cmd.KOMAoptions} or \DescRef{typearea.cmd.KOMAoption} -(see, e.\,g., \autoref{sec:typearea.options}, -\DescPageRef{typearea.cmd.KOMAoptions}). The option has no effect on the -results of \DescRef{scrtime.cmd.thistime} and \DescRef{scrtime.cmd.thistime*} -if \DescRef{scrtime.cmd.settime} is used. - -Only\textnote{Attention!} for compatibility with former releases of -\Package{scrtime} also option \Option{24h} will switch to 24-hour format if -used in the optional argument of \Macro{documentclass} or -\Macro{usepackage}. Nevertheless, you should not use this option any longer.% +argument of \DescRef{typearea.cmd.usepackage}, or even after loading the +package using \DescRef{typearea.cmd.KOMAoptions} or +\DescRef{typearea.cmd.KOMAoption} (see, e.\,g. \autoref{sec:typearea.options}, +\DescPageRef{typearea.cmd.KOMAoptions}). However the option no longer has any +effect on the if you call \DescRef{scrtime.cmd.settime}. After invoking this +command, the time is output only with the value and in the format specified +there. + +For\textnote{Attention!} the sake of compatibility with earlier versions of +\Package{scrtime}, the option \Option{24h} will switch to 24-hour format if +used in the optional argument of \Macro{documentclass} or \Macro{usepackage}. +However, you should not use this option any longer.% \EndIndexGroup % \EndIndexGroup diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrextend.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrextend.tex index 95d01f243d1..f168ad4ddd8 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrextend.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrextend.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrextend.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrextend.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,57 +46,69 @@ % ====================================================================== \KOMAProvidesFile{scrextend.tex} - [$Date: 2017-05-11 15:48:59 +0200 (Thu, 11 May 2017) $ + [$Date: 2018-03-27 11:46:14 +0200 (Tue, 27 Mar 2018) $ KOMA-Script package scrextend] -\translator{Markus Kohm} +\translator{Markus Kohm\and Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-01-24 -\chapter[{\KOMAScript{} Features for other Classes with Package - \Package{scrextend}}]{Making Basic Feature of the \KOMAScript{} Classes - Available with Package \Package{scrextend} while Using Other Classes} +\chapter[{\KOMAScript{} Features for Other Classes with \Package{scrextend}}] + {Using Basic Features of the \KOMAScript{} Classes in Other Classes with the + \Package{scrextend} Package} \labelbase{scrextend} \BeginIndexGroup% \BeginIndex{Package}{scrextend}% -There are several features, that are shared by all \KOMAScript{} classes. This -means not only the classes \Class{scrbook}, \Class{scrreprt}, and -\Class{scrartcl}, that has been made as a drop-in replacement for the standard -classes \Class{book}, \Class{report}, and \Class{article}, but also for -several features of the \KOMAScript{} class \Class{scrlttr2}, the successor of -\Class{scrlettr}, that may be used for letters. These basic features, that may -be found in the above-named classes, are also provided by package -\Package{scrextend} since \KOMAScript{} release~3.00. This package should not -be used together with a \KOMAScript{} class, but may be used together with -many other classes. Package \Package{scrextend} would recognize, if it would -be used with a \KOMAScript{} class, and would terminate with a warning message -in that case. - -There is no warranty for compatibility of \Package{scrextend} with every -class. The package has been designed primary to extend the standard classes -and derived classes. Anyway, before using \Package{scrextend} you should -make sure that the used class does not already provide the feature you need. - -Beside the features from this chapter, there are additional common features, -that are mainly provides for authors of classes and packages. These may be -found in \autoref{cha:scrbase} from \autopageref{cha:scrbase}. The package -\Package{scrbase}\important{\Package{scrbase}}, that has been described at -that chapter, was designed to be used mainly by authors of classes and -packages. Package \Package{scrextend} and all \KOMAScript{} classes also use -that package. - -\KOMAScript{} classes and package \Package{scrextend} also load package -\Package{scrlfile}\important{\Package{scrlfile}} described in -\autoref{cha:scrlfile} from \autopageref{cha:scrlfile}. Because of this the -features of that package are also available when using \Package{scrextend}. +There are some features that are common to all \KOMAScript{} classes. This +applies not only to the \Class{scrbook}, \Class{scrreprt}, and +\Class{scrartcl} classes, which are intended to replace the standard classes +\Class{book}, \Class{report}, and \Class{article}, but also to a large extend +the \KOMAScript{} class \Class{scrlttr2}, the successor to \Class{scrlettr}, +which is intended for letters. These basic features, which can be found in the +classes mentioned above, are also provided by package \Package{scrextend} from +\KOMAScript{} version~3.00 onward. This\textnote{Attention!} package should +not be used with \KOMAScript{} classes. It is intended for use with other +classes only. If you attempt to load the package with a \KOMAScript{} class, +\Package{scrextend} will detect this and reject loading it with a warning +message. + +The fact that \hyperref[cha:scrlttr2]{\Package{scrletter}}% +\IndexPackage{scrletter} can be used not only with \KOMAScript{} classes but +also with the standard classes is partly due to \Package{scrextend}. If +\hyperref[cha:scrlttr2]{\Package{scrletter}} detects that it is not being used +with a \KOMAScript class, it automatically loads \Package{scrextend}. Doing +so makes all required \KOMAScript{} classes available. + +Of course, there is no guarantee that \Package{scrextend} will work with all +classes. The package has been designed primarily to extend the standard +classes and those derived from them. In any case, before you use +\Package{scrextend}, you should first make sure that the class you are using +does not already provide the feature you need. + +In addition to the features described in this chapter, there are a few more +that are primarily intended for authors of classes and packages. These can be +found in \autoref{cha:scrbase}, starting on \autopageref{cha:scrbase}. The +\hyperref[cha:scrbase]{\Package{scrbase}}% +\important{\hyperref[cha:scrbase]{\Package{scrbase}}}\IndexPackage{scrbase} +package documented there is used by all \KOMAScript{} classes and the +\Package{scrextend} package. + +All \KOMAScript{} classes and the \Package{scrextend} package also load the +\hyperref[cha:scrlfile]{\Package{scrlfile}}% +\important{\hyperref[cha:scrlfile]{\Package{scrlfile}}}\IndexPackage{scrlfile} +package described in \autoref{cha:scrlfile} starting on +\autopageref{cha:scrlfile}. Therefore the features of this package are also +available when using \Package{scrextend}. \iftrue % Umbruchkorrekturtext -In difference to the above, only the \KOMAScript{} classes \Class{scrbook}, -\Class{scrreprt}, and \Class{scrartcl} load package \Package{tocbasic} (see -\autoref{cha:tocbasic} from \autopageref{cha:tocbasic}), that has been -designed to be used by authors of classes and packages too. Because of this -\Package{scrextend} does not provide the features of this package. Nevertheless -you may use \Package{tocbasic} together with \Package{scrextend}.% +In contrast, only the \KOMAScript{} classes \Class{scrbook}, \Class{scrreprt}, +and \Class{scrartcl} load the \hyperref[cha:tocbasic]{\Package{tocbasic}} +package (see \autoref{cha:tocbasic} starting on \autopageref{cha:tocbasic}), +which is designed for authors of classes and packages. For this reason, the +features defined there are found only in those classes and not in +\Package{scrextend}. Of course you can still use +\hyperref[cha:tocbasic]{\Package{tocbasic}} together with +\Package{scrextend}.% \fi \LoadCommonFile{options}% \section{Early or late Selection of Options} @@ -107,33 +119,32 @@ you may use \Package{tocbasic} together with \Package{scrextend}.% \section{Optional, Extended Features} \seclabel{optionalFeatures} -Package \Package{scrextend} provides some optional, extended features. Such -features are not available by default, but may be activated -additionally. These features are optional, i.\,e., because the conflict with -features of the standard classes of often used packages. +The \Package{scrextend} package provides some optional, extended features. +These features are not available by default but can be activated. These +features are optional because, for example, they may conflict with features of +the standard classes of other commonly used packages. \begin{Declaration} \OptionVName{extendedfeature}{feature} \end{Declaration} -With this option an extended \PName{feature} of \Package{scrextend} may be -activated. Option \Option{extendedfeature} is available only while loading the -package \Package{scrextend}. User have to set the option in the optional -argument of \DescRef{\LabelBase.cmd.usepackage}\OParameter{optional - argument}\PParameter{scrextend}. % +With this option, you can activate an extended \PName{feature} of +\Package{scrextend}. This option is available only while loading +\Package{scrextend}. You must therefore specify this option in the optional +argument of \DescRef{\LabelBase.cmd.usepackage}\PParameter{scrextend}. % \iffree{% - An overview of all available optional features is shown in + An overview of all available features is shown in \autoref{tab:scrextend.optionalFeatures}. \begin{table} - \caption[{optional available extended features of - \Package{scrextend}}]{overview of the optional available extended + \caption[{available extended features of + \Package{scrextend}}]{overview of the optional extended features of \Package{scrextend}} \label{tab:scrextend.optionalFeatures} \begin{desctabular} \entry{\PName{title}}{% - extends the title pages to the features of the \KOMAScript{} classes; - this means not only the commands for the title page but also option - \DescRef{\LabelBase.option.titlepage} (see + title pages have the additional features of the \KOMAScript{} classes; + this applies not only to the commands for the title page but also to + the \DescRef{\LabelBase.option.titlepage} option (see \autoref{sec:scrextend.titlepage}, from \autopageref{sec:scrextend.titlepage})% }% @@ -142,13 +153,11 @@ argument of \DescRef{\LabelBase.cmd.usepackage}\OParameter{optional }{% \par% Currently the only available extended \PName{feature} is - \PValue{title}\IndexOption[indexmain]{extendedfeature~=\PValue{title}}% - \important[i]{\begin{tabular}[t]{@{}r@{}} - \KOption{extendedfeature}\hspace*{1em}\\\PValue{title}\end{tabular}}. - This \PName{feature} provides the title pages of the \KOMAScript{} - classes. See \autoref{sec:scrextend.titlepage} from - \autopageref{sec:scrextend.titlepage} for description of these kind of title - pages.% + \PValue{title}\IndexOption[indexmain]{extendedfeature~=\textKValue{title}}% + \important{\OptionValue{extendedfeature}{title}}. + This \PName{feature} gives title pages the features of the \KOMAScript{} + classes, as described in \autoref{sec:scrextend.titlepage} starting on + \autopageref{sec:scrextend.titlepage}.% }% % \EndIndexGroup @@ -164,29 +173,30 @@ argument of \DescRef{\LabelBase.cmd.usepackage}\OParameter{optional \LoadCommonFile{oddorevenpage}% \section{Detection of Odd and Even Pages} -\section{Head and Foot Using Predefined Page Styles} +\section{Choosing a Predefined Page Style} \seclabel{pagestyle} One of the basic features of a document is the page -style\Index[indexmain]{page>style}. Page style in \LaTeX{} means mainly header -and footer of the page. Package \Package{scrextend} does not define any page -style, but it uses and expects the definition some page styles. +style\Index[indexmain]{page>style}. In \LaTeX{}, the page style primarily +determines the content of headers and footers. The \Package{scrextend} package +does not define any page styles itself. Instead it uses the page styles of the +\LaTeX{} kernel. \begin{Declaration} \Macro{titlepagestyle} \end{Declaration}% \Index{title>page style}% -Some pages have a different page style automatically selected using -\DescRef{maincls.cmd.thispagestyle}. With \Package{scrextend} this will be -used currently for the page with the in-page title if and only if option +On some pages \DescRef{maincls.cmd.thispagestyle}\IndexCmd{thispagestyle} +automatically selects a different page style. Currently, \Package{scrextend} +only does this for title pages, and only if \OptionValueRef{\LabelBase}{extendedfeature}{title} has been used (see \autoref{sec:scrextend.optionalFeatures}, \DescPageRef{scrextend.option.extendedfeature}). In this case the page style -stored at \DescRef{maincls.cmd.thispagestyle} will be used. Default for +specified in \DescRef{maincls.cmd.thispagestyle} will be used. The default for \DescRef{maincls.cmd.thispagestyle} is -\PageStyle{plain}\IndexPagestyle{plain}. This page style is predefined by the -\LaTeX{} kernel. So it should be available always.% +\PageStyle{plain}\IndexPagestyle{plain}. This page style is defined by the +\LaTeX{} kernel, so it should always be available.% \EndIndexGroup \LoadCommonFile{interleafpage}% \section{Interleaf Pages} diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrhack.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrhack.tex index c45340f6dd8..a7dfac605c5 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrhack.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrhack.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrhack.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrhack.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,197 +46,211 @@ % ============================================================================ \KOMAProvidesFile{scrhack.tex} - [$Date: 2017-03-31 12:00:24 +0200 (Fri, 31 Mar 2017) $ + [$Date: 2018-03-27 11:46:14 +0200 (Tue, 27 Mar 2018) $ KOMA-Script guide (chapter: scrhack)] -\translator{Markus Kohm} +\translator{Markus Kohm\and Karl Hagen} -% Date of the translated German file: 2017-01-02 -\chapter{Hacks for Third-Party Packages by Package \Package{scrhack}} +% Date of the translated German file: 2018-02-05 +\chapter{Improving Third-Party Packages with \Package{scrhack}} \labelbase{scrhack} \BeginIndexGroup \BeginIndex{Package}{scrhack} -Some packages from other authors could have problems with \KOMAScript{}. In my -opinion some packages could be improved. With some packages this makes only -sense, if \KOMAScript{} was used. With some other packages the package author -has another opinion. Sometimes proposals was never answered. Package -\Package{scrhack} contains all those improvement proposals for other -packages. This means, \Package{scrhack} redefines macros of packages from -other authors! The redefinitions are only activated, if those packages were -loaded. Users can prevent \Package{scrhack} from redefining macros of -individual packages. - -\section{State of Development Note} +Some packages from other authors do not work well with \KOMAScript{}. It is +often very tedious for the author of \KOMAScript{} to convince the authors of +these packages to make specific improvements. This also applies to packages +whose development has been discontinued. That's why the \Package{scrhack} was +created. This package alters the commands and definitions of other to work +better with \KOMAScript{}. Some changes are also useful when using other +classes. + +\section{Development Status} \label{scr:scrhack.draft} -Though this package is part of \KOMAScript{} for long time and though it has -been used by lot of users, there's one problem with it. While redefinition of -macros of foreign packages, it depend on the exact definition an usage of -those macros. This means additionally, that it depends on dedicated releases -of those packages. If a unknown release of such a package will be used, -\Package{scrhack} eventually could not do the needed patch. Contrary, in -extreme cases the patch can cause errors and fault. +Although this package has been part of \KOMAScript{} for long time and is used +by many users, there's one problem with it. Redefining macros from third-party +packages depends on knowing the exact definition and use of those macros. This +also means that it depends on specific versions of those packages. If you use +a unknown version of such a package, \Package{scrhack} may not be able to +execute the required patch. In extreme cases, patching an unknown version can +lead to an error. -So \Package{scrhack} has to be continuously modified to fit new releases of -foreign packages and will never be finished. Because of this \Package{scrhack} -will stay in beta state forever. Though the usage will generally be a -benefit, the correct function could not be guaranteed forever. +Because \Package{scrhack} must be continuously modified to accommodate new +releases of third-party packages, it can never be considered complete. +Therefore \Package{scrhack} will remain permanently in a beta version. +Although its use will generally be a benefit, its correct functioning cannot +be permanently guaranteed. \LoadCommonFile{options}% \section{Early or late Selection of Options} -\section{Usage of \Package{tocbasic}} +\section{Using \Package{tocbasic}} \seclabel{improvement} -In the early days of \KOMAScript{} users asked for handling lists of floats, -that will be generated using package -\Package{float}\IndexPackage{float}\important{\Package{float}}, like list of -figures and list of tables, that are generated by \KOMAScript{} itself. At -that time the \KOMAScript{} author contacted the author of \Package{float}, to -submit a proposal of an interface with support for such an extention. A -somehow modified version of that interface has been implemented with commands +In the early days of \KOMAScript{}, users wanted to handle lists of floating +environments created with the +\Package{float}\IndexPackage{float}\important{\Package{float}} package in the +same way as the list of figures and list of tables created by \KOMAScript{} +itself. At that time the author of \KOMAScript{} contacted the author of +\Package{float} to propose an interface to support such an extension. A +somewhat modified form of that interface was implemented with the \Macro{float@listhead}\IndexCmd[indexmain]{float@listhead} and -\Macro{float@addtolists}\IndexCmd[indexmain]{float@addtolists}. - -Sometimes later it has appeared, that those two commands were not flexible -enough to support all of the comprehensive features supported by -\KOMAScript. Unfortunately the author of \Package{float} has finalized the -development already, so nobody should expect furthor changes of this package. - -Other package authors have also inherited these commands. Thereby it appeared, -that the implementation in some packages, even in package \Package{float}, -will need a certain package loading order, though all these packages are not -related to each other. Wrong loading order could result in an error or break the -functionality of the commands. - -To clear all these disadvantages and problems, \KOMAScript{} officially does not -support this old interface any more. Instead, \KOMAScript{} warns if the old -interface is used. At the same time package -\Package{tocbasic}\IndexPackage{tocbasic}\important{\Package{tocbasic}} (see -\autoref{cha:tocbasic}) has been designed and implemented as a central -interface for management of table of contents, lists of floats and similar -lists. Usage of this package provides much more advantages and features than -the two old commands that have been mentioned above. - -Though the effort using that package is very small, the authors of most of the -packages, that are using the old interface, have not done so -currently. Because of this \Package{scrhack} contains appropriate -modifications of packages +\Macro{float@addtolists}\IndexCmd[indexmain]{float@addtolists} commands. + +Later it became apparent that these two commands were not flexible enough to +fully support all of \KOMAScript's capabilities. Unfortunately, the author of +\Package{float} had already ceased development by that point, so further +changes to this package cannot be expected. + +Other package authors have also adopted these two commands, and it became +apparent that the implementation in some packages, including \Package{float}, +means that all these packages can only be loaded in a specific order, even +though they are otherwise unrelated to each other. + +To overcome all these disadvantages and problems, \KOMAScript{} no longer +officially supports this old interface. Instead, \KOMAScript{} warns if the +old interface is used. At the same time, the +\Package{tocbasic}\IndexPackage{tocbasic}\important{\Package{tocbasic}} +package (see \autoref{cha:tocbasic}) has been designed and implemented as a +central interface for managing of table of contents and similar content lists. +This package provides many more advantages and features than the two old +commands. + +Although the effort to use this package is very small, so far the authors of +most of the packages that use the old interface have not made any adjustments. +Therefore \Package{scrhack} contains appropriate modifications of the \Package{float}\IndexPackage{float}\important{\Package{float}, - \Package{floatrow}, \Package{listings}}, +\Package{floatrow}, \Package{listings}}, \Package{floatrow}\IndexPackage{floatrow}, and -\Package{listings}\IndexPackage{listings}. Loading \Package{scrhack} is enough -to make these packages recognize not only setting of \KOMAScript{} option +\Package{listings}\IndexPackage{listings} packages. Merely loading +\Package{scrhack} is sufficient to make these packages recognize not only the +setting of the \KOMAScript{} option \DescRef{maincls.option.listof}\IndexOption{listof~=\PName{setting}}, but also -language switching of package \Package{babel}\IndexPackage{babel}. More -information about the features provided by the changeover to package -\Package{tocbasic} can be found in \autoref{sec:tocbasic.toc}. - -If the modification for any of the packages is not wanted or causes problems, -then it can be deactivated selectively with option -\OptionValue{float}{false}\IndexOption[indexmain]{float~=\PValue{false}}, -\OptionValue{floatrow}{false}\IndexOption[indexmain]{floatrow~=\PValue{false}}, +to react to the language switching features of the +\Package{babel}\IndexPackage{babel} package. You can find more information +about the features available by switching packages to \Package{tocbasic} in +\autoref{sec:tocbasic.toc}. + +If you do not want this modification for any of the packages, or if it causes +problems, you can deactivate it selectively with the +\OptionValue{float}{false}\IndexOption[indexmain]{float~=\textKValue{false}}, +\OptionValue{floatrow}{false}\IndexOption[indexmain]{floatrow~=\textKValue{false}}, or -\OptionValue{listings}{false}\IndexOption[indexmain]{listings~=\PValue{false}}. -Please note\textnote{Attention!} that changing these options after loading the -corresponding package would not do it! +\OptionValue{listings}{false}\IndexOption[indexmain]{listings~=\textKValue{false}} +option. Note\textnote{Attention!} that changing these options after loading +the associated package has no effect! -\section{Incorrect Expectations to \Macro{@ptsize}} +\section{Incorrect Assumptions about \Macro{@ptsize}} \seclabel{ptsize} -Some packages always expect that the class-internal macro -\Macro{@ptsize}\IndexCmd{@ptsize} is not only defined but also expands to an -integer. For compatibility, \KOMAScript{} defines \Macro{@ptsize} even if the -basic font size is neither 10\Unit{pt} nor 11\Unit{pt} nor -12\Unit{pt}. \KOMAScript{} also provides non-integer font sizes. So -\Macro{@ptsize} can expand to a non-integer number, too. - -Package\ChangedAt{v3.17}{\Package{scrhack}} -\Package{setspace}\IndexPackage[indexmain]{setspace} is one of the packages -that fail with non-integer number expansion of \Macro{@ptsize}. Additionally -the line stretching of that package always depends on the basic font size even -if setting is made in the context of another font size. Package -\Package{scrhack} solves both problems by redefining \Macro{onehalfspacing} -and \Macro{doublespacing} using always the current font size while setting the -stretch. - -If the modification for the package is not wanted or causes problems, -then it can be deactivated selectively with option -\OptionValue{setspace}{false}\IndexOption[indexmain]{setspace~=\PValue{false}}. -Please note\textnote{Attention!} that changing these option after loading -\Package{setspace} would not do it! If you use \Package{setspace} with -either option \Option{onehalfspacing} or \Option{doublespacing} you have to -load \Package{scrhack} before it. - - -\section{Special Case \Package{hyperref}} +Some packages assume that the class-internal macro +\Macro{@ptsize}\IndexCmd{@ptsize} both is defined and expands to an integer. +For compatibility, \KOMAScript{} defines \Macro{@ptsize} even if the basic +font size is something other than 10\Unit{pt}, 11\Unit{pt}, or 12\Unit{pt}. +\KOMAScript{} also allows non-integer font sizes. So \Macro{@ptsize} can, of +course, also expand to a non-integer number. + +One\ChangedAt{v3.17}{\Package{scrhack}} of the packages that cannot cope with +a non-integer \Macro{@ptsize} is +\Package{setspace}\IndexPackage[indexmain]{setspace}. Additionally, the values +set by this package are always dependent on the basic font size, even if the +setting is made in the context of another font size. The \Package{scrhack} +package solves both problems by redefining \Macro{onehalfspacing} and +\Macro{doublespacing} to set the spacing relative to the actual font size. + +If you do not want this modification for the package, or if it causes +problems, you can deactivate it selectively with the +\OptionValue{setspace}{false}\IndexOption[indexmain]{setspace~=\textKValue{false}} +option. Note\textnote{Attention!} that changing this option after loading +\Package{setspace} has no effect! Likewise, if you use \Package{setspace} with +either the \Option{onehalfspacing} or \Option{doublespacing} option, you must +load \Package{scrhack} first. + + +\section{Older Versions of \Package{hyperref}} \seclabel{hyperref} -Before version~6.79h package \Package{hyperref} set the link anchors after -instead of before the heading of star version commands like -\DescRef{maincls.cmd.part*}, \DescRef{maincls.cmd.chapter*}, and so on. In -the meantime this problem have been solved at the \KOMAScript{} author's -suggestion. But because the \KOMAScript{} author was not patient enough to -wait more than a year for the change of \Package{hyperref}, a corresponding -patch has been added to \Package{scrhack}. This can be deactivated by -\OptionValue{hyperref}{false}. Nevertheless, it is recommended to use the -current \Package{hyperref} release. In this case \Package{scrhack} does -automatically deactivate the not longer needed patch.% +Versions of \Package{hyperref} before 6.79h set the link +anchors after the heading of the starred versions of commands like +\DescRef{maincls.cmd.part*}, \DescRef{maincls.cmd.chapter*}, etc. instead of +before them. Since then, this problem has been resolved at the suggestion of +\KOMAScript{}'s author. But because the change took more than a year, a patch +was added to \Package{scrhack}. Although this can also be deactivated with +\OptionValue{hyperref}{false}, you should instead use the current +\Package{hyperref} release. In this case \Package{scrhack} automatically +deactivates this unnecessary patch.% \section{Inconsistent Handling of \Length{textwidth} and \Length{textheight}} \seclabel{lscape} -Package\ChangedAt{v3.18}{\Package{scrhack}} -\Package{lscape}\IndexPackage[indexmain]{lscape} defines an environment -\Environment{landscape}\IndexEnv{landscape} to set the page contents but not -head and foot landscape. Inside this environment it changes -\Length{textheight}\IndexLength{textheight} to the value of -\Length{textwidth}, but it does not change \Length{textwidth} to the former -value of \Length{textheight}. This is inconsistent. As far as I know, -\Length{textwidth} is unchanged because setting it to \Length{textheight} -could blame other packages or user commands. But changing \Length{textheight} -could also blame other packages or user commands and indeed it breaks, e.\,g., -\Package{showframe}\IndexPackage{showframe} and -\Package{scrlayer}\IndexPackage{scrlayer}. So best would be, not to change -\Length{textheight}, too. \Package{scrhack} uses package \Package{xpatch} (see -\cite{package:xpatch}) to modify the environment start macro \Macro{landscape} -appropriately. - -If the modification for the package is not wanted or causes problems, -then it can be deactivated selectively with option -\OptionValue{lscape}{false}\IndexOption[indexmain]{lscape~=\PValue{false}}. -Please note\textnote{Attention!} that changing this option after loading -\Package{lscape} has an effect only, if it is not \PValue{false} while -loading \Package{lscape} respectively \Package{scrhack}, if -\Package{scrhack} is loaded after \Package{lscape}. - -Please note\textnote{Attention!}, -\Package{pdflscape}\IndexPackage[indexmain]{pdflscape} also uses -\Package{lscape} and therefore is influenced by \Package{scrhack}, too.% +The\ChangedAt{v3.18}{\Package{scrhack}} +\Package{lscape}\IndexPackage[indexmain]{lscape} package defines a +\Environment{landscape}\IndexEnv{landscape} environment to set the page +contents, but not the header or footer in landscape mode. Inside this +environment, \Length{textheight}\IndexLength{textheight} is set to the value +of \Length{textwidth}, but \Length{textwidth} is not set to the former value +of \Length{textheight}. This is inconsistent. As far as I know, +\Length{textwidth} is left unchanged because setting it to \Length{textheight} +could interfere with other packages or user commands. But changing +\Length{textheight} also has this potential, and indeed it breaks, for +example, \Package{showframe}\IndexPackage{showframe} and +\Package{scrlayer}\IndexPackage{scrlayer}. Thus it would be best if +\Length{textheight} too remained unchanged. \Package{scrhack} uses the +\Package{xpatch} package (see \cite{package:xpatch}) to modify the +\Macro{landscape} environment's start macro appropriately. + +If you do not want this modification, or if it causes problems, you can +deactivate it with the +\OptionValue{lscape}{false}\IndexOption[indexmain]{lscape~=\textKValue{false}} +option. Note\textnote{Attention!} that changing \Option{lscape} subsequently +with \DescRef{\LabelBase.cmd.KOMAoption}\IndexCmd{KOMAoption} or +\DescRef{\LabelBase.cmd.KOMAoptions}\IndexCmd{KOMAoptions} has an effect only +if it was not \PValue{false} while loading \Package{lscape}. + +Incidentally, the \Package{pdflscape}\IndexPackage[indexmain]{pdflscape} +package also uses \Package{lscape}, so \Package{scrhack} affects the +functioning of this package too.% \section{Special Case \Package{nomencl}} \label{sec:nomencl} -The\ChangedAt{v3.23}{\Package{scrhack}} hack for package -\Package{nomencl}\IndexPackage[indexmain]{nomencl} is a somehow special -case. First of all it extends \Package{nomencl}'s option \Option{intoc} to -respect \KOMAScript's option -\OptionValueRef{maincls}{toc}{indentunnumbered}. As a sidestep it also -reserves the file extensions \File{nlo} and \File{nls} for package -\Package{tocbasic} (see \DescRef{tocbasic.cmd.addtotoclist}, -\autoref{sec:tocbasic.basics}, -\DescPageRef{tocbasic.cmd.addtotoclist}). Furthermore, you can use several -features for the file extension \File{nls} using -\DescRef{tocbasic.cmd.setuptoc}. For example, you can use -\DescRef{tocbasic.cmd.setuptoc}\PParameter{nls}\PParameter{numbered} to not -only add an entry to the table of contents but also number the headings of the -nomenclature. As an side effect the nomenclature also gets a running head if -automatic running heads are activated, e.\,g., using page style -\DescRef{maincls.pagestyle.headings}. All these extension are done by a small -patch of environment \Environment{thenomenclature}. -% +The\ChangedAt{v3.23}{\Package{scrhack}} hack for the +\Package{nomencl}\IndexPackage[indexmain]{nomencl} represents a somewhat +special case. First, it ensures that the optional table of contents entry for +the nomenclature observes the \OptionValueRef{maincls}{toc}{indentunnumbered} +option. Somewhat incidentally, it also reserves the file extensions \File{nlo} +and \File{nls} for the owner \PValue{nomencl} (see +\DescRef{tocbasic.cmd.addtotoclist}, \autoref{sec:tocbasic.basics}, +\DescPageRef{tocbasic.cmd.addtotoclist}). + +It also changes the \Environment{thenomenclature}\IndexEnv{thenomenclature} +environment to use +\DescRef{tocbasic.cmd.tocbasic@listhead}\IndexCmd{tocbasic@listhead} for the +heading (see \autoref{sec:tocbasic.internals}, +\DescPageRef{tocbasic.cmd.tocbasic@listhead}). In this way, the hack lets you +set various attribute for the \File{nls} extension using +\DescRef{tocbasic.cmd.setuptoc}\IndexCmd{setuptoc}% +\important{\DescRef{tocbasic.cmd.setuptoc}}. For example, not only can you +enter the nomenclature in the table of contents with +\DescRef{tocbasic.cmd.setuptoc}\PParameter{nls}\PParameter{numbered}, but you +can also number it immediately. You can find more about +\DescRef{tocbasic.cmd.setuptoc} and its available settings in +\autoref{sec:tocbasic.toc}, starting on \DescPageRef{tocbasic.cmd.setuptoc}. +As a small but important side effect, this patch also gives the nomenclature +also matching running head, if automatic running heads are activated, for +example by using the \DescRef{maincls.pagestyle.headings} page style. + +This rather simple patch is an example of how packages that do not define +floating environments can still benefit from \Package{tocbasic}. However, you +do not want this change, or if it causes problems, you can deactivate it with +the \OptionValue{nomencl}{false}% +\IndexOption[indexmain]{nomencl~=\textKValue{false}} option. +The\textnote{Achtung!} setting of the option when \Package{nomencl} is loaded +is crucial! Later changes to the option with +\DescRef{\LabelBase.cmd.KOMAoption} or \DescRef{\LabelBase.cmd.KOMAoptions} +have no influence and will lead to a corresponding warning.% \EndIndexGroup \endinput diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrjura.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrjura.tex index 98320e6a3ab..1d19af010aa 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrjura.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrjura.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrjura.tex -% Copyright (c) Markus Kohm, 2011-2017 +% Copyright (c) Markus Kohm, 2011-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrjura.tex -% Copyright (c) Markus Kohm, 2011-2017 +% Copyright (c) Markus Kohm, 2011-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,32 +46,32 @@ % ====================================================================== \KOMAProvidesFile{scrjura.tex}% - [$Date: 2017-05-08 11:47:04 +0200 (Mon, 08 May 2017) $ + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (chapter: scrjura)] -\translator{Alexander Willand\and Markus Kohm} +\translator{Alexander Willand\and Markus Kohm\and Karl Hagen} -% Date of the translated German file: 2017-05-08 +% Date of the translated German file: 2018-02-06 -\chapter{Support for the Law Office by \Package{scrjura}} +\chapter{Support for the Law Office with \Package{scrjura}} \labelbase{scrjura} \BeginIndexGroup \BeginIndex{Package}{scrjura} -In case you'd like to write a contract\Index{contract}, the bylaws of a -company or of the club, an act of law or a whole commentary, the package -\Package{scrjura} will provide typographical support. Despite the fact that -\Package{scrjura} is intended as a broad help for juridical documents, the -contract is the central element of the package. Particular attention is being -paid to the clause with numbered title and numbered paragraphs\,---\,if -a clause consists of more than one paragraph\,---, even numbered sentences, -entries in the table of contents and cross references according to German -standards. +If you want to write a contract\Index{contract}, the articles of association +for a company or an association, a law, or a legal commentary, the package +\Package{scrjura} will provide typographical support. Although +\Package{scrjura} is intended to provide general help for legal documents, the +contract is the central element of the package. Particular attention is paid +to clauses, titles, and numbered provisions\,---\,if there are several of +them in a clause\,---, numbered sentences, entries in the table of +contents, and cross references according to German standards. -The package has been developed in cooperation with Dr Alexander Willand, -lawyer in Karlsruhe. +The package has been developed in cooperation with Dr Alexander Willand of +Karlsruhe. Many of its features go back to constructive inquiries from Prof +Heiner Richter of the Hochschule Stralsund University of Applied Sciences. -Note\textnote{Attention!} that the package cooperates with +Note\textnote{Attention!} that the package works with \Package{hyperref}\IndexPackage{hyperref}. Nevertheless, \Package{hyperref} has to be loaded after \Package{scrjura} as usual. @@ -82,29 +82,30 @@ has to be loaded after \Package{scrjura} as usual. \section{Table of Contents} \label{sec:scrjura.toc} -The package \Package{scrjura} provides entries into the table of contents. +The headings of clauses can also be added automatically to the table of +contents, if desired. \begin{Declaration} \OptionVName{juratotoc}{simple switch}% \OptionVName{juratotoc}{level number} \end{Declaration} -A clause\Index{clause} is being shown in the table of contents only, if its -\PName{level number} is smaller or equal to the counter +Clauses\Index{clause} are shown in the table of contents only if their +\PName{level number} is less than or equal to the \DescRef{maincls.counter.tocdepth}% -\important{\DescRef{maincls.counter.tocdepth}}\IndexCounter{tocdepth} (see -\autoref{sec:maincls.toc}, \DescPageRef{maincls.counter.tocdepth}). Default -for the \PName{level number} is 10000, which as well will be used, if the -option is switched off by the \PName{simple - switch}\important{\OptionValue{juratotoc}{false}} (see +\important{\DescRef{maincls.counter.tocdepth}}\IndexCounter{tocdepth} counter +(see \autoref{sec:maincls.toc}, \DescPageRef{maincls.counter.tocdepth}). By +default, the \PName{level number} is 10000, which is also used if the option +is switched off with the \PName{simple +switch}\important{\OptionValue{juratotoc}{false}} (see \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}). Because the -counter \DescRef{maincls.counter.tocdepth} usually has a one digit value, -clause entries are not shown in the table of contents. - -If you switch on the option using the \PName{simple - switch}\important{\OptionValue{juratotoc}{true}}, as a default \PName{level - number} 2 is used, so that clauses are shown in the table of contents on the -same level as subsections. If the counter \DescRef{maincls.counter.tocdepth} -has default values as well, clauses are shown with all \KOMAScript{} classes.% +\DescRef{maincls.counter.tocdepth} counter usually has a one-digit value, +clause entries are therefore not normally displayed in the table of contents. + +If you switch on the option using the \PName{simple switch}% +\important{\OptionValue{juratotoc}{true}}, the \PName{level number} 2 is used +so that clauses are shown in the table of contents on the same level as +subsections. For the default setting of \DescRef{maincls.counter.tocdepth}, +clauses are then shown in all \KOMAScript{} classes.% \EndIndexGroup @@ -112,9 +113,10 @@ has default values as well, clauses are shown with all \KOMAScript{} classes.% \OptionVName{juratocindent}{indent}% \OptionVName{juratocnumberwidth}{number width} \end{Declaration} -These two options can be used to determine the indentation in the table of -contents as well as the reserved space for the numbers there. Defaults are the -values for the subsection entries in \Class{scrartcl}.% +These two options can be used to determine the indentation for the clause +entries in the table of contents as well as the space reserved for the numbers +there. The defaults are the same as for subsection entries in +\Class{scrartcl}.% \EndIndexGroup @@ -123,24 +125,24 @@ values for the subsection entries in \Class{scrartcl}.% \BeginIndexGroup \BeginIndex{}{contract} -The main mechanism of \Package{scrjura} only work inside of the contract -environment. +The essential mechanisms of \Package{scrjura} are available only inside the +contract environment. \begin{Declaration} \begin{Environment}{contract}\end{Environment} \end{Declaration} -Till this date, this is the one and only environment for legal practitioner -provided by \Package{scrjura}. Using it will activate the automatic numbering -of paragraphs and the commands \DescRef{\LabelBase.cmd.Clause} and -\DescRef{\LabelBase.cmd.SubClause} will become a form, which will be -documented below. - -The\textnote{Attention!} environment \DescRef{\LabelBase.env.contract} must -not be nested in itself. Within the document the environment may be used -several times. In this case the clauses within the environment are treated as -if they were within the same environment. Ending the environment means just a -break and with beginning a new environment in the same document the former -environment is continued. A break inside a clause is not possible.% +Currently, this is the one and only environment for \Package{scrjura}. Using +it activates automatic numbering of paragraphs and the +\DescRef{\LabelBase.cmd.Clause} and \DescRef{\LabelBase.cmd.SubClause} +commands, which will be documented below, are given concrete form. + +The\textnote{Attention!} \DescRef{\LabelBase.env.contract} environment must +not be nested within itself. Within a document, however, you can use the +environment several times. The clauses within these environments are treated +as if they were within a single environment. As a result, ending the +environment really only temporarily interrupts it, and the old environment is +continued by the beginning of a new environment. However, you cannot end the +environment within a clause.% \EndIndexGroup @@ -151,15 +153,14 @@ The whole document becomes a contract if you use this option while loading the package with \DescRef{\LabelBase.cmd.usepackage}% \important{\DescRef{\LabelBase.cmd.usepackage}} or as a global option with \DescRef{\LabelBase.cmd.documentclass}% -\important{\DescRef{\LabelBase.cmd.documentclass}}. The document behaves as -if you started the contract environment right after the beginning of the -document. - -Neither\textnote{Attention!} you can use this option with -\DescRef{\LabelBase.cmd.KOMAoption} nor with -\DescRef{\LabelBase.cmd.KOMAoptions}, so that it is not possible to switch the -option off in this way. Please use the \DescRef{\LabelBase.env.contract} -environment directly.% +\important{\DescRef{\LabelBase.cmd.documentclass}}. The document then behaves +exactly as if it contained one \DescRef{\LabelBase.env.contract} environment. + +Note\textnote{Attention!} that you cannot set the \Option{contract} option +with \DescRef{\LabelBase.cmd.KOMAoption} or +\DescRef{\LabelBase.cmd.KOMAoptions}. Thus you cannot switch the option off +again. Instead, you should use a \DescRef{\LabelBase.env.contract} environment +directly.% \EndIndexGroup @@ -167,42 +168,48 @@ environment directly.% \label{sec:scrjura.clause} \index{section|seealso{clause}} -With \Package{scrjura} clauses\footnote{% - In English, the word ``section'' also is used in an act of law or in an - agreement. To distinguish \DescRef{maincls.cmd.section} of most document - classes from the section in \Package{scrjura}, we decided to call the - section in the latter simply ``clause''.} in a legal sense only exist inside -of contracts, meaning inside of the environment -\DescRef{\LabelBase.env.contract}. +Clauses\footnote{% + In English, a ``clause'' in a legal document is a section, paragraph, or + phrase that relates to a particular point. Although it is common in English + to also use the terms ``article'' or ``section'' for what we here call a + ``clause'', we use the latter term throughout to avoid confusion with the + \Class{article} class and the \DescRef{maincls.cmd.section} and + \DescRef{maincls.cmd.paragraph} sectioning divisions of most document + classes.} in a legal sense are defined in \Package{scrjura} only within +contracts, that is inside the \DescRef{\LabelBase.env.contract} environment or +other environments declared with +\DescRef{\LabelBase.cmd.DeclareNewJuraEnvironment} (see +\autoref{sec:\LabelBase.newenv}, +\DescPageRef{\LabelBase.cmd.DeclareNewJuraEnvironment}). \begin{Declaration} \Macro{Clause}\OParameter{options}% \Macro{SubClause}\OParameter{options} \end{Declaration} -These are the most important commands inside of a contract. Without using -further \PName{options} the command \Macro{Clause} creates the heading of a -clause, which consists only of the sign »\S«, followed by its number. In -contrast to this the command \Macro{SubClause} creates the heading of a clause -with the last number used by \Macro{Clause} and adds a lowercase -letter. \Macro{SubClause} mainly is intended for cases where an act or a -contract is amended and not only clauses are changed or deleted, but between -existing clauses new ones are inserted without changing the numbering. - -Both commands except as \PName{options} a list separated by commas of -properties. An overview over possible properties is provided by -\autoref{tab:scrjura.Clause.options}. For the most important of them we will -go into the details. +These are the most important commands inside of a contract. Without using any +additional \PName{options}, \Macro{Clause} creates the heading of a clause, +which consists of the sign »\S«, followed by its number. In contrast, +\Macro{SubClause} creates the heading of a clause with the last number used by +\Macro{Clause} and adds a lower-case letter. \Macro{SubClause} is mainly +intended for cases where an act or a contract is amended and not only are +clauses changed or deleted but new clauses are inserted between existing ones +without completely changing the numbering. + +Both commands accept a a comma-separated list of \PName{options}. An overview +of the available properties is shown in \autoref{tab:scrjura.Clause.options}. +The most important of them will be discussed in more detail. \begin{table} - \caption{Possible properties for the optional argument of \Macro{Clause} and + \caption{Available properties for the optional argument of \Macro{Clause} and \Macro{SubClause}} \label{tab:scrjura.Clause.options} \begin{desctabular} \entry{\Option{dummy}}{% - The heading will not be printed but counted in the automatic numbering.% + The heading will not be printed but is counted in the automatic + numbering.% }% \entry{\OptionVName{head}{running head}}{% - If running heads are available, \PName{running head} is used instead of + If running heads are active, this \PName{running head} is used instead of the clause \PName{title}.% }% \entry{\Option{nohead}}{% @@ -221,150 +228,149 @@ go into the details. Changes the vertical \PName{skip} after the clause heading.% }% \entry{\OptionVName{title}{title}}{% - Additional to the clause number a clause \PName{title} will be printed. - This is also used as default for the \PName{running head} and the - \PName{entry} in the table of contents.% + The clause \PName{title} will be printed in addition to the clause + number. This is also used as the default for the \PName{running head} + and the \PName{entry} in the table of contents.% }% \entry{\OptionVName{tocentry}{entry}}{% - Independent from the clause \PName{title}, an \PName{entry} into the + Regardless of the clause \PName{title}, an \PName{entry} into the table of contents will be made, if such entries are activated.% }% \end{desctabular} \end{table} -A skip of two lines is inserted before the heading and afterwards a skip of -one line as a default. Via the options +By default, a skip of two lines is inserted before the heading and a skip of +one line afterwards. You can change the size of these skips with the \Option{preskip}\important[i]{\Option{preskip}, \Option{postskip}} and -\Option{postskip} these skips can be changed. The new values are not only -valid for the current clause but beginning with the actual clause until the -end of the current contract environment. It is possible as well to set these -keys in advance by writing +\Option{postskip} options. The new values apply not only to the current +clause but from the current clause until the end of the current contract +environment. You can also make the appropriate settings in advance with \begin{flushleft}\quad\small \textbf{\Macro{setkeys}}\PParameter{contract}% \PParameter{preskip=\PName{skip},\\ \normalsize\quad\small \hspace{11.5em}postskip=\PName{skip}} \end{flushleft} -independently from a clause and outside of a contract environment as well. -Also it is possible to set the keys inside of the preamble after loading -\Package{scrjura}. But it is not possible to set these options while loading -the package or by using \DescRef{\LabelBase.cmd.KOMAoptions} or +regardless of the specific clause and outside of a contract environment. You +can also set these options inside the preamble after loading +\Package{scrjura}, but you cannot set them while loading the package or by +using \DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption}. \BeginIndex{FontElement}{contract.Clause}\LabelFontElement{contract.Clause}% \BeginIndex{FontElement}{Clause}\LabelFontElement{Clause}% -The headings use as a default the fonts -\Macro{sffamily}\Macro{bfseries}\Macro{large}. The fonts can be changed using -the element -\FontElement{contract.Clause}\important{\FontElement{contract.Clause}} with -the help of \DescRef{\LabelBase.cmd.setkomafont}% +By default, clause headings use the font style +\Macro{sffamily}\Macro{bfseries}\Macro{large}. You can change this font style +at any time using the +\FontElement{contract.Clause}\important{\FontElement{contract.Clause}} element +with \DescRef{\LabelBase.cmd.setkomafont}% \important[i]{\DescRef{\LabelBase.cmd.setkomafont}, - \DescRef{\LabelBase.cmd.addtokomafont}} and +\DescRef{\LabelBase.cmd.addtokomafont}} and \DescRef{\LabelBase.cmd.addtokomafont} (see \autoref{sec:maincls.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont}). Inside the -\DescRef{\LabelBase.env.contract} environment instead of -\FontElement{contract.Clause} simply -\FontElement{Clause}\important{\FontElement{Clause}} may be used.% +\DescRef{\LabelBase.env.contract} environment, you can also use +\FontElement{Clause}\important{\FontElement{Clause}} instead of +\FontElement{contract.Clause}.% \EndIndex{FontElement}{Clause}% \EndIndex{FontElement}{contract.Clause} -With the options \Option{title}\important[i]{\Option{title}, \Option{head}, - \Option{tocentry}}, \Option{head}, and \Option{tocentry} a clause may get in -addition to the number a title. It\textnote{Attention!} is recommended to put -the value of these options inside brackets. Failing this, e.g., commas may -lead to confusion between different options. Empty values for \Option{head} -and \Option{tocentry} cause an empty entry. If one would like to avoid an -entry, the options \Option{nohead}\important[i]{\Option{nohead}, - \Option{notocentry}} and \Option{notocentry} have to be used. - -Instead of the running numbers the option -\Option{number}\important{\Option{number}} manually sets the number of a -clause. This will have no impact on the numbers of the subsequent clauses. -Empty numbers are not possible. Fragile commands inside \PName{number} have to -be protected with \Macro{protect}. It\textnote{Attention!} is recommended only -to use numbers and letters as assignment to \Option{number}. - -With the option \Option{dummy}\important{\Option{dummy}} the output of the -whole heading of a clause can be suppressed. The automatic numbering will -count this clause nonetheless. Thus you can skip a clause in the automatic -numbering with\textnote{Example} +With the \Option{title}\important[i]{\Option{title}, \Option{head}, + \Option{tocentry}}, \Option{head}, and \Option{tocentry} options, you can +title a clause in addition to the number. You\textnote{Attention!} should put +the value of each options inside curly brackets. Otherwise, for example, +commas which are meant to be part of the value will be confused with the +delimiters between different options. Empty values for \Option{head} and +\Option{tocentry} cause empty entries. If you want to avoid an entry, use the +\Option{nohead}\important[i]{\Option{nohead}, \Option{notocentry}} and +\Option{notocentry} options. + +Instead of consecutive numbers, you can also set a clause number manually with +the \Option{number}\important{\Option{number}} option. However, this does not +affect the numbers of the subsequent clauses. Empty numbers are not possible. +Fragile commands inside \PName{number} have to be protected with +\Macro{protect}. You\textnote{Attention!} should use only numbers and letters +as a \Option{number}. + +With the \Option{dummy}\important{\Option{dummy}} option, you can suppress the +output of the whole heading of a clause. The automatic numbering, however, +will still count this clause. In this way, you can skip an automatically +numbered clause with\textnote{Example} \begin{lstcode} \Clause{dummy} \end{lstcode} -in case the clause has been deleted in a later version of a contract. +in case the clause corresponding clause has been deleted in a later version of +a contract. -Note\textnote{Attention!}, only the values \PValue{true} and \PValue{false} -may be used in combination with \Option{dummy}. All other values will be -ignored, but may throw up an error.% +Note\textnote{Attention!} that the \Option{dummy} option only accepts the +values \PValue{true} and \PValue{false}. All other values are usually ignored, +but can lead to an error message in the worst case scenario.% \EndIndexGroup \begin{Declaration} \Macro{Clauseformat}\Parameter{number} \end{Declaration} -As already mentioned the clauses and subclauses usually are being numbered. -The format of the number is done with the help of the command -\Macro{Clauseformat}, which expects as one and only argument the number. The -default is defined as +As already mentioned, clauses and subclauses are normally numbered. The number +is formatted with the help of the \Macro{Clauseformat} command, which expects +the number as the only argument. The default is the following: \begin{lstcode} \newcommand*{\Clauseformat}[1]{\S~#1} \end{lstcode} -and, as you see, it is only the \Macro{S}\IndexCmd{S} followed by a -non-breaking space and the number. In case of redefinition take care to keep -it expandable.% +This produces the section mark, \Macro{S}\IndexCmd{S} (\S), followed by a +non-breaking space and the number. If you redefine this command, be sure it +remains expandable.% \EndIndexGroup \begin{Declaration} \OptionVName{juratitlepagebreak}{simple switch} \end{Declaration}% -Usually a page break inside a heading is prohibited. Some jurists may need -page breaks inside of clause headings. Such a break may be allowed using -\Option{juratitlepagebreak}\important{\Option{juratitlepagebreak}}. The -possible values for \PName{simple switch} are printed in +Usually, page breaks are prohibited within heading of all kinds. However, some +lawyers require page breaks within clause headings. You can allow such a break +by using \Option{juratitlepagebreak}\important{\Option{juratitlepagebreak}}. +You can find the available values for \PName{simple switch} in \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}.% \EndIndexGroup \begin{Declaration} \OptionVName{clausemark}{value} \end{Declaration}% -Clauses are a kind of inferior structure with an independent numbering -they will not have running headlines as a default. Running headlines -are possible and may be created with alternative properties. The -possible \PName{values} and their meaning are listed in -\autoref{tab:scrjura.clausemark}.% +Since clauses are a subordinate structure with independent numbering, they do +not produce running heads by default. You can, however, create running heads +with various settings. You can find the available \PName{values} and their +meanings in \autoref{tab:scrjura.clausemark}.% % \begin{table} - \caption{Possible values for option \Option{clausemark} for activation of + \caption{Available values for the \Option{clausemark} option to activate running heads}% \label{tab:scrjura.clausemark}% \begin{desctabular} \entry{\PValue{both}}{% Clauses generate left and right marks for running heads, if the document provides automatic running heads.% - \IndexOption{clausemark~=\PValue{both}}% + \IndexOption{clausemark~=\textKValue{both}}% }% \entry{\PValue{false}, \PValue{off}, \PValue{no}}{% Clauses do not generate marks for running heads and therefore do not change running heads.% - \IndexOption{clausemark~=\PValue{false}}% + \IndexOption{clausemark~=\textKValue{false}}% }% \entry{\PValue{forceboth}}{% Clauses use \DescRef{maincls.cmd.markboth} to generate left and right marks for running heads even if the document does not provide automatic running heads for the current page style.% - \IndexOption{clausemark~=\PValue{forceboth}}% + \IndexOption{clausemark~=\textKValue{forceboth}}% }% \entry{\PValue{forceright}}{% Clauses use \DescRef{maincls.cmd.markright} to generate right marks for running heads even if the document does not provide automatic running heads for the current page style.% - \IndexOption{clausemark~=\PValue{forceright}}% + \IndexOption{clausemark~=\textKValue{forceright}}% }% \entry{\PValue{right}}{% Clauses generate right marks for running heads, if the document provides automatic running heads.% - \IndexOption{clausemark~=\PValue{right}}% + \IndexOption{clausemark~=\textKValue{right}}% }% \end{desctabular} \end{table} @@ -374,17 +380,16 @@ possible \PName{values} and their meaning are listed in \subsection{Paragraphs} \label{sec:scrjura.par} - \BeginIndexGroup -\BeginIndex{}{paragraph>number}% -Within clauses the paragraphs are being numbered automatically. With this, the -paragraphs are a strongly structuring element, similar to -\DescRef{maincls.cmd.paragraph} or \DescRef{maincls.cmd.subparagraph} known, -e.\,g., from article classes. Contracts usually use a vertical skip between -paragraphs. The package \Package{scrjura} does not provide its own mechanism -for this. Instead, it uses the option \DescRef{maincls.option.parskip}% -\IndexOption{parskip}\important{\DescRef{maincls.option.parskip}} of the -\KOMAScript{} classes (see \autoref{sec:maincls.parmarkup}, +\BeginIndex{}{paragraph>numbering}% +Within clauses, \Package{scrjura} usually numbers paragraphs automatically. +With this, the paragraphs provide a powerful structuring element, similar to +\DescRef{maincls.cmd.paragraph} or \DescRef{maincls.cmd.subparagraph} in +normal documents. For this reason, contracts usually use a vertical skip +between paragraphs. The \Package{scrjura} package does not provide its own +mechanism for this. Instead, it uses the \DescRef{maincls.option.parskip}% +\IndexOption{parskip}\important{\DescRef{maincls.option.parskip}} option of +the \KOMAScript{} classes (see \autoref{sec:maincls.parmarkup}, \DescPageRef{maincls.option.parskip}). @@ -392,27 +397,33 @@ for this. Instead, it uses the option \DescRef{maincls.option.parskip}% \OptionVName{parnumber}{value} \end{Declaration} The default numbering of paragraphs is \OptionValue{parnumber}{auto} and -\OptionValue{parnumber}{true}. Once in a while it might be necessary to switch -off the automatic numbering. This is done with \OptionValue{parnumber}{false}% +\OptionValue{parnumber}{true}. Sometimes you may need to disable the automatic +numbering. You can do this with \OptionValue{parnumber}{false}% \important{\OptionValue{parnumber}{false}}% -\IndexOption{parnumber~=\PValue{false}}. In this case the numbering of -sentences will be reseted. +\IndexOption{parnumber~=\textKValue{false}}. In this case, only the sentence +numbering is reset. -To realise this way of numbering paragraphs it has been necessary to gear into -the paragraph building mechanism of \LaTeX. In rare cases there is a negative -impact, which can be avoided by switching to \OptionValue{parnumber}{manual}% +To implement this option, it has been necessary to hook into the +paragraph-building mechanism of \LaTeX. In some rare cases, this can have a +negative effect. If so, you can undo the change with +\OptionValue{parnumber}{manual}% \important{\OptionValue{parnumber}{manual}}% -\IndexOption{parnumber~=\PValue{manual}}. On the other hand \LaTeX itself -sometimes undoes the change. In those cases one has to activate it again with -\OptionValue{parnumber}{auto}% +\IndexOption{parnumber~=\textKValue{manual}}. On the other hand, \LaTeX{} +itself sometimes undoes the change. In those cases you can activate it again +with \OptionValue{parnumber}{auto}% \important{\OptionValue{parnumber}{auto}}% -\IndexOption{parnumber~=\PValue{auto}}. - -In a clause which consist of only one paragraph, the paragraph usually -has no number. This does only work if there are not two clauses with an -identical number in a document. Note that the number of paragraphs in a clause -is not available before the end of the clause. Therefore you need a least two -\LaTeX{} runs to get the correct, automatic paragraph numbering.% +\IndexOption{parnumber~=\textKValue{auto}}. + +Clauses that consist of a single paragraph do not automatically receive a +paragraph number. For this to work, there must not be two clauses with an +identical number in a document. However should you ever need such numbering, +you should switch to another contract environment (see +\DescRef{\LabelBase.cmd.DeclareNewJuraEnvironment}, +\autoref{sec:\LabelBase.newenv}, +\DescPageRef{\LabelBase.cmd.DeclareNewJuraEnvironment}). +Note\textnote{Attention!} that the number of paragraphs in a clause is not +available before the end of the clause. Therefore you need a least two +\LaTeX{} runs before the automatic paragraph numbering is correct.% \EndIndexGroup @@ -422,20 +433,43 @@ is not available before the end of the clause. Therefore you need a least two \Macro{parformat}% \Macro{parformatseparation} \end{Declaration}% -For numbering the paragraphs inside a clause we use the counter -\Counter{par}. The output of \Macro{thepar} will display an arabic number, -because the default is \Macro{arabic}\PParameter{par}. \Macro{parformat} -provides the format, which is \Macro{thepar} in rounded brackets. For -numbering a paragraph manually, use \Macro{parformat} as well. It makes sense -to call \Macro{parformat} with a following \Macro{nobreakspace} or a tilde. - -The\ChangedAt{v0.7}{\Package{scrjura}} output of \Macro{parformat} is followed -by one or more delimiter(s). These are provided by -\Macro{parformatseparation}, which currently consists of -\Macro{nonbreakspace}, the non-breakable inter word distance. - -Package\textnote{Attention!} \Package{scrjura} assumes internally, that -\Macro{thepar} is an arabic number. Don't redefine!% +For numbering the paragraphs inside a clause we use the \Counter{par} counter. +The output of \Macro{thepar} will display an Arabic number, because the +default is \Macro{arabic}\PParameter{par}. \Macro{parformat} provides the +format, which is \Macro{thepar} in rounded brackets. When numbering a +paragraph manually, you should also use \Macro{parformat}. It makes sense to +call \Macro{parformat} with a subsequent \Macro{parformatseparation}, or at +least a \Macro{nobreakspace} or tilde. + +With\ChangedAt{v0.7}{\Package{scrjura}} automatic numbering, \Macro{parformat} +is followed by \Macro{parformatseparation}, which currently consists of +\Macro{nonbreakspace}, the non-breakable space. + +\BeginIndex{FontElement}{parnumber}\LabelFontElement{parnumber}% +The paragraph number is usually printed using the currently active font. +However, you can change this default for the \FontElement{parnumber} element +at any time with \DescRef{\LabelBase.cmd.setkomafont}% +\important[i]{\DescRef{\LabelBase.cmd.setkomafont}, +\DescRef{\LabelBase.cmd.addtokomafont}} and +\DescRef{\LabelBase.cmd.addtokomafont} (see +\autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}).% +\EndIndex{FontElement}{parnumber}% + +Note\textnote{Attention!} that \Package{scrjura} assumes internally that +\Macro{thepar} is an Arabic number. Therefore you should definitely not +redefine it!% +\EndIndexGroup + + +\begin{Declaration} + \Macro{withoutparnumber} +\end{Declaration} +If the paragraph number is not printed, \Package{scrjura} executes the +\Macro{withoutparnumber} command at the beginning of the new paragraph. The +initial definition of this command is empty. This means it is a kind of dummy +command that does nothing. It has been implemented because of a user request. +Most users can ignore this command.% \EndIndexGroup @@ -443,23 +477,23 @@ Package\textnote{Attention!} \Package{scrjura} assumes internally, that \Macro{ellipsispar}\OParameter{number}% \Macro{parellipsis} \end{Declaration} -Sometimes\ChangedAt{v0.7}{\Package{scrjura}}\,---\,particularly in -comparisons\,---\,it is desirable to omit paragraphs, but to mark the -omission. Those omitted paragraphs\Index{paragraph>omission} shall be included -in the counter of the paragraphs. The package \Package{scrjura} provides the -command \Macro{ellipsispar} to do this. - -By default \Macro{ellipsispar} omits precisely one paragraph. Using the -optional argument multiple paragraphs may be omitted. In any case the output -shows just one not numbered paragraph, which only consists of the ellipsis +Sometimes\ChangedAt{v0.7}{\Package{scrjura}}\,---\,particularly in comparative +commentaries\,---\,it is desirable to omit paragraphs but to mark the +omission. Those omitted paragraphs\Index{paragraph>omission} should be taken +into account by the paragraph counter. The package \Package{scrjura} provides +the command \Macro{ellipsispar} to do this. + +By default, \Macro{ellipsispar} omits precisely one paragraph. Using the +optional argument, you can omit multiple paragraphs. In any case, the output +shows just one unnumbered paragraph, which consists only of the ellipsis defined by \Macro{parellipsis}. The automatic numbering of paragraphs takes the \PName{number} of omitted paragraphs into account. \begin{Example} - Supposed you are writing a »comment« of the German\footnote{We have decided - to translate it into English. But please remember, it is only an example - not of existing law but of a technical realisation with - \Package{scrjura}.} penal code, but only paragraph 3 of §~2. Nevertheless - you'd like to hint at the omission. This can be done this way: + Suppose you are writing a comment on the German\footnote{Please remember, + this translation does not refer to an existing law but is only an example + of how you might realise such a commentary with \Package{scrjura}.} penal + code, but only on paragraph 3 of \S~2. Nevertheless, you'd like to indicate + the omission indirectly. You can do this with: \begin{lstcode} \documentclass[parskip=half]{scrartcl} \usepackage{scrjura} @@ -468,9 +502,9 @@ the \PName{number} of omitted paragraphs into account. \Clause{title={Temporal application},number=2} \ellipsispar[2] - If, subsequent to the commission of a criminal - offence, the law provides for a lighter penalty, - that penalty shall be applicable. + If the law that applies at the time the criminal act is + committed is changed before the verdict, then the most + lenient law shall be applicable. \ellipsispar[3] \end{contract} @@ -480,8 +514,8 @@ the \PName{number} of omitted paragraphs into account. \end{Example} The ellipsis is by default \Macro{textellipsis}\IndexCmd{textellipsis}, if -such a command is defined. If not, \Macro{dots} will be -used. \Macro{parellipsis} may be redefined with \Macro{renewcommand}.% +such a command is defined. If not, \Macro{dots} is used. You can redefine +\Macro{parellipsis} at any time with \Macro{renewcommand}.% \EndIndexGroup % \EndIndexGroup @@ -490,38 +524,38 @@ used. \Macro{parellipsis} may be redefined with \Macro{renewcommand}.% \subsection{Sentences} \label{sec:scrjura.sentence} -\BeginIndexGroup +\BeginIndexGroup% \BeginIndex{}{sentence>number}% -In a contract the paragraphs consist of one or more sentences. In German acts -of law it is common to number the sentences as well. Regarding -\Package{scrjura}, an automatic numbering is cumbersome and error-prone and -has not been implemented yet. +Paragraphs in contracts consist of one or more sentences, some of which may +also be numbered. However, as automatic numbering is cumbersome and +error-prone, it has not yet been implemented in +\Package{scrjura}. Semi-automatic numbering, however, is supported. \begin{Declaration} \Counter{sentence}% \Macro{thesentence}% \Macro{Sentence} \end{Declaration} -Manual numbering of sentences is done with the command \Macro{Sentence}. It -adds one to the counter \Counter{sentence}. As a default, \Macro{thesentence} -is printed as an arabic number. +Manual numbering of sentences is done with the \Macro{Sentence} command. It +adds one to the \Counter{sentence} counter. By default, \Macro{thesentence} +is printed as an Arabic number. Using\textnote{Hint!} \Package{babel}\IndexPackage{babel} offers an easy way -to define a short hand for \Macro{Sentence}:% +to define a shorthand for \Macro{Sentence}:% \phantomsection\label{sec:scrjura.shorthandexample}% \begin{lstcode}[moretexcs={useshorthands,defineshorthand}] \useshorthands{'} \defineshorthand{'S}{\Sentence\ignorespaces} \end{lstcode} -With this definition any space after \lstinline|'S| will be ignored. It is -even possible to use the dot as abbrevation for dot and new number of the -following sentence: +With this definition, any space after \lstinline|'S| will be ignored. You can +even use the dot as an abbreviation for a dot and a new sentence number: \begin{lstcode}[moretexcs={useshorthands,defineshorthand}] \defineshorthand{'.}{. \Sentence\ignorespaces} \end{lstcode} -These abbrevations have been tried and tested. For details regarding -\Macro{useshorthands} and \Macro{defineshorthands} please consult the manual -of the package \Package{babel} (see \cite{package:babel}).% +For details regarding \Macro{useshorthands} and \Macro{defineshorthands}, +please consult the manual of the \Package{babel} package (see +\cite{package:babel}). You can find an example of their application in +\autoref{sec:scrjura.example}, \autopageref{sec:scrjura.example}.% \EndIndexGroup % \EndIndexGroup @@ -529,12 +563,13 @@ of the package \Package{babel} (see \cite{package:babel}).% \EndIndexGroup -\section{Cross References} +\section{Cross-References} \label{sec:scrjura.ref} -The conventional mechanism to set cross references using +The conventional mechanism to set cross-references using \Macro{label}\IndexCmd{label}\important{\Macro{label}}, \Macro{ref}, and -\Macro{pageref} does not suffice. \Package{scrjura} provides more commands. +\Macro{pageref} does not suffice for clauses, paragraphs, and sentences. +Therefore \Package{scrjura} provides additional commands. \begin{Declaration} \Macro{ref}\Parameter{label}% @@ -544,8 +579,8 @@ The conventional mechanism to set cross references using \end{Declaration} The commands \Macro{refL}, \Macro{refS}, and \Macro{refN} give a full reference to clause, paragraph and sentence. \Macro{refL} is a long text, -\Macro{refS} a short text and \Macro{refN} an abbreviated, numeric -form. \Macro{ref} defaults to \Macro{refL}.% +\Macro{refS} a short text, and \Macro{refN} an abbreviated, numeric form. +\Macro{ref} defaults to \Macro{refL}.% \EndIndexGroup @@ -553,9 +588,9 @@ form. \Macro{ref} defaults to \Macro{refL}.% \Macro{refClause}\Parameter{label}% \Macro{refClauseN}\Parameter{label} \end{Declaration} -For a cross reference to to a clause without displaying paragraph and -sentences as well. \Macro{refClause} puts a section symbol (\S) in front of -the reference, while \Macro{refClauseN} does not.% +These commands reference a clause without displaying the paragraph or +sentences. \Macro{refClause} puts a section mark (\S) in front of the +reference, while \Macro{refClauseN} does not.% \EndIndexGroup @@ -565,14 +600,15 @@ the reference, while \Macro{refClauseN} does not.% \Macro{refParS}\Parameter{label}% \Macro{refParN}\OParameter{number format}\Parameter{label} \end{Declaration} -You can make a cross reference to a paragraph using \Macro{refParL}, -\Macro{refParS} and \Macro{refParN}. The differences between the forms -correspond to the differences between \DescRef{\LabelBase.cmd.refL}, -\DescRef{\LabelBase.cmd.refN} and \DescRef{\LabelBase.cmd.refS}. A special -feature is the optional argument of \Macro{refParN}. Usually the numeric -reference to a paragraph uses a roman number. The optional argument allows to -set a different \PName{number format}, it may make sense to use arabic -numbers. \Macro{refPar} defaults to \Macro{refParL}.% +You can reference just a paragraph with \Macro{refParL}, \Macro{refParS} and +\Macro{refParN}. The differences between the forms correspond to the +differences between \DescRef{\LabelBase.cmd.refL}, +\DescRef{\LabelBase.cmd.refN} and \DescRef{\LabelBase.cmd.refS}. A feature +worth noting is the optional argument of \Macro{refParN}. Usually the numeric +reference to a paragraph uses a Roman number. You can, however, specify a +different \PName{number format} in the optional argument. This option +primarily makes sense to use Arabic numbers. By default, \Macro{refPar} is +\Macro{refParL}.% \EndIndexGroup @@ -582,9 +618,9 @@ numbers. \Macro{refPar} defaults to \Macro{refParL}.% \Macro{refSentenceS}\Parameter{label}% \Macro{refSentenceN}\Parameter{label} \end{Declaration} -You can make a cross reference to a sentence with \Macro{refSentenceL}, -\Macro{refSentenceS}, or \Macro{refSentenceN}. Again we have a long text form, -a short text form and a numerical form. \Macro{refSentence} defaults to +You can reference a sentence with \Macro{refSentenceL}, \Macro{refSentenceS}, +or \Macro{refSentenceN}. Again, there is a long text form, a short text form, +and a numerical form. By default, \Macro{refSentence} is \Macro{refSentenceL}.% \EndIndexGroup @@ -593,87 +629,88 @@ a short text form and a numerical form. \Macro{refSentence} defaults to \OptionVName{ref}{value} \end{Declaration} The results of \DescRef{\LabelBase.cmd.ref}, \DescRef{\LabelBase.cmd.refPar}, -and \DescRef{\LabelBase.cmd.refSentence} depend on the \PName{value} of option -\Option{ref}. Defaults are \DescRef{\LabelBase.cmd.refL}, -\DescRef{\LabelBase.cmd.refParL} and -\DescRef{\LabelBase.cmd.refSentenceL}. For possible values and their meaning -see \autoref{tab:scrjura.ref}.% +and \DescRef{\LabelBase.cmd.refSentence} depend on the \PName{value} of the +\Option{ref} option. The defaults are \DescRef{\LabelBase.cmd.refL}, +\DescRef{\LabelBase.cmd.refParL} and \DescRef{\LabelBase.cmd.refSentenceL}. +You can find the available values and their meaning in +\autoref{tab:scrjura.ref}.% % \begin{table} %\begin{desclist} % \desccaption \caption[{% - Possible values for option \Option{ref} to configure the cross reference + Available values for the\Option{ref} option to configure the cross-reference format% }]{% - Possible values for option \Option{ref} to configure the cross reference - format of \DescRef{\LabelBase.cmd.ref}, \DescRef{\LabelBase.cmd.refPar}, - and \DescRef{\LabelBase.cmd.refSentence}% + Available values for the \Option{ref} option to configure the + cross-reference format of \DescRef{\LabelBase.cmd.ref}, + \DescRef{\LabelBase.cmd.refPar}, and \DescRef{\LabelBase.cmd.refSentence}% \label{tab:scrjura.ref}% }% \begin{desctabular} \entry{\PValue{long}}{% - Combination of \PValue{parlong} and \PValue{sentencelong}.% - \IndexOption{ref~=\PValue{long}}% + A combination of \PValue{parlong} and \PValue{sentencelong}.% + \IndexOption{ref~=\textKValue{long}}% }% \entry{\PValue{numeric}}{% - Combination of \PValue{parnumeric} and \PValue{sentencenumeric}.% - \IndexOption{ref~=\PValue{numeric}}% + A combination of \PValue{parnumeric} and \PValue{sentencenumeric}.% + \IndexOption{ref~=\textKValue{numeric}}% }% \entry{\PValue{clauseonly}, \PValue{onlyclause}, \PValue{ClauseOnly}, \PValue{OnlyClause}}{% - Combination of \PValue{paroff} and \PValue{sentenceoff}; note that + A combination of \PValue{paroff} and \PValue{sentenceoff}. Note that \DescRef{\LabelBase.cmd.refPar} and \DescRef{\LabelBase.cmd.refSentence} - have empty results!% - \IndexOption{ref~=\PValue{long}}% + produce empty results!% + \IndexOption{ref~=\textKValue{long}}% }% \entry{\PValue{parlong}, \PValue{longpar}, \PValue{ParL}}{% Paragraphs are referenced in long textual form.% - \IndexOption{ref~=\PValue{parlong}}% + \IndexOption{ref~=\textKValue{parlong}}% }% \entry{\PValue{parnumeric}, \PValue{numericpar}, \PValue{ParN}}{% Paragraphs are referenced in simple numerical form.% - \IndexOption{ref~=\PValue{parnumeric}}% + \IndexOption{ref~=\textKValue{parnumeric}}% }% \entry{\PValue{paroff}, \PValue{nopar}}{% - Paragraphs have not reference. Note that \DescRef{\LabelBase.cmd.refPar} - has an empty result!% - \IndexOption{ref~=\PValue{paroff}}% + Paragraphs have no reference. Note that \DescRef{\LabelBase.cmd.refPar} + produces an empty result!% + \IndexOption{ref~=\textKValue{paroff}}% }% \entry{\PValue{parshort}, \PValue{shortpar}, \PValue{ParS}}{% Paragraphs are referenced in short textual form.% - \IndexOption{ref~=\PValue{parshort}}% + \IndexOption{ref~=\textKValue{parshort}}% }% \entry{\PValue{sentencelong}, \PValue{longsentence}, \PValue{SentenceL}}{% Sentences are referenced in long textual form.% - \IndexOption{ref~=\PValue{parlong}}% + \IndexOption{ref~=\textKValue{parlong}}% }% \entry{\PValue{sentencenumeric}, \PValue{numericsentence}, \PValue{SentenceN}}{% Sentences are referenced in simple numeric form.% - \IndexOption{ref~=\PValue{sentencenumeric}}% + \IndexOption{ref~=\textKValue{sentencenumeric}}% }% \entry{\PValue{sentenceoff}, \PValue{nosentence}}{% Sentences have no reference. Note that - \DescRef{\LabelBase.cmd.refSentence} has an empty result!% - \IndexOption{ref~=\PValue{sentenceoff}}% + \DescRef{\LabelBase.cmd.refSentence} produces an empty result!% + \IndexOption{ref~=\textKValue{sentenceoff}}% }% \entry{\PValue{sentenceshort}, \PValue{shortsentence}, \PValue{SentenceS}}{% Sentences are referenced in short textual form.% - \IndexOption{ref~=\PValue{sentenceshort}}% + \IndexOption{ref~=\textKValue{sentenceshort}}% }% \entry{\PValue{short}}{% - Combination if \PValue{parshort} and \PValue{sentenceshort}.% - \IndexOption{ref~=\PValue{value}}% + A combination of \PValue{parshort} and \PValue{sentenceshort}.% + \IndexOption{ref~=\textKValue{value}}% }% \end{desctabular} \end{table} \begin{Example} - Supposed you would like to reference to paragraphs in the form ``paragraph 1 - in clause 1''. As scrjura lacks of a predefined command for this, you have - to build your own definitions out of what's given:% + Suppose you always want to reference paragraphs in the form ``paragraph 1 + in clause 1''. As there is no predefined command for this, you have + to create your own definition from the available options. You can achieve + this easily with:% \begin{lstcode} \newcommand*{\refParM}[1]{% paragraph~\refParN[arabic]{#1} @@ -684,14 +721,14 @@ see \autoref{tab:scrjura.ref}.% \DescRef{\LabelBase.cmd.refParL}.% \end{Example}% -\hyperref[tab:scrjura.refexamples]{Table~\ref*{tab:scrjura.refexamples}} -provides examples of the output of the fundamental commands, not configured.% +You can find examples of results of the basic commands in +\autoref{tab:scrjura.refexamples}.% % \begin{table} \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% - \begin{captionbeside}{Example outputs of the \Option{ref}-independent cross - reference commands}[l] + \begin{captionbeside}{Example outputs of the \Option{ref}-independent + cross-reference commands}[l] \begin{tabular}[t]{ll} \toprule Command & Example output \\ @@ -720,65 +757,111 @@ provides examples of the output of the fundamental commands, not configured.% \section{Additional Environments} \label{sec:scrjura.newenv} -There are users of \Package{scrjura} who use it to draft neither contracts nor -commentaries on certain acts of law, but a compilation of, -e.\,g., different laws, which does not necessarly use the section prefix (\S) -before the title of each clause. Maybe somebody would like to write -something like ``Art. XY'' and needed an indpendent counter for each -contract environment. +Some users do not use \Package{scrjura} to draft contracts or commentaries on +individual laws but to examine different types of laws, which may not +necessarily use the section prefix (\S) before the title of each clause but +perhaps something like ``Art.'' or ``IAS'', and so forth. An independent +counter is also required for each of these different clause types. \begin{Declaration} \Macro{DeclareNewJuraEnvironment}\Parameter{name}\OParameter{options}% \Parameter{start commands}\Parameter{end commands} \end{Declaration} -This\ChangedAt{v0.9}{\Package{scrjura}} command allows to define new and -independent environments of the type contract. The argument \PName{name} is -the name of the new environment, of course. \PName{start commands} are -commands which will be executed at the beginning of the environment, as if -they were added directly after \Macro{begin}\Parameter{name}. Correspondingly -\PName{end commands} will be executed at the end of the environment, as if -added directly before \Macro{end}\Parameter{name}. Without any \PName{options} -the new environment behaves similiar to the \DescRef{\LabelBase.env.contract} -environment, but with its own counters. It is possible to set \PName{options} -in a comma separated list. Currently the following \PName{options} are -supported: -\begin{description} -\item[\OptionVName{Clause}{instruction}:] Defines on which \PName{instruction} - inside the environment the command \DescRef{\LabelBase.cmd.Clause} is being - mapped. The \PName{instruction} expects exactly one argument. To use it - correctly, a deeper knowledge and understanding of the internal functions of - \Package{scrjura} is needed. Furthermore the requirements for - \PName{instruction} may change in future versions. It is recommended not to - use this option.% -\item[\OptionVName{SubClause}{instruction}:] See explanation for - \Option{Clause} above. -\item[\OptionVName{Sentence}{instruction}:] Defines on which - \PName{instruction} inside the environment the command - \DescRef{\LabelBase.cmd.Sentence} is being mapped. The \PName{instruction} - must not have an argument. Typically it should add one to the counter - \Counter{sentence}\IndexCounter{sentence} (using - \Macro{refstepcounter}\IndexCmd{refstepcounter}) and display it - somehow. Please avoid undesirable spaces. -\item[\OptionVName{ClauseNumberFormat}{instruction}:] Formats the numbers of - clauses. Expects exactly one argument, the number of the clause. If the - \PName{instruction} implements a series of instructions and the number is - the last argument of a that series, you may directly use the series of - instructions as \PName{instruction}. -\end{description} +You\ChangedAt{v0.9}{\Package{scrjura}} can use this command to define new and +independent environments for contracts or other legal texts. The argument +\PName{name} is the name of the new environment, of course. The \PName{start +commands} are commands which will be executed at the beginning of the +environment, as if they were added directly after +\Macro{begin}\Parameter{name}. Correspondingly \PName{end commands} will be +executed at the end of the environment, as if added directly before +\Macro{end}\Parameter{name}. Without any \PName{options} the new environment +behaves like the \DescRef{\LabelBase.env.contract} environment, but with its +own counters. It is possible to set \PName{options} in a comma-separated list. +See \autoref{tab:\LabelBase.DeclareNewJuraEnvironment} for the currently +supported \PName{options}. + +\begin{desclist} + \desccaption{Options provided by \Macro{DeclareNewJuraEnvironment} for new + contract environments\label{tab:\LabelBase.DeclareNewJuraEnvironment}}% + {Options of \Macro{DeclareNewJuraEnvironment} (\emph{continued})}% + \entry{\OptionVName{Clause}{command}}{% + Defines the \PName{command} to which the \DescRef{\LabelBase.cmd.Clause} + command is mapped within the environment. This \PName{command}, like the + one documented for \DescRef{\LabelBase.env.contract}, expects exactly one + argument. To use it correctly requires advanced knowledge of the + \Package{scrjura}'s internal functioning. Furthermore, the requirements + for the \PName{command} may change in future versions. Therefore it is + recommended not to use this option!% + }% + \entry{\OptionVName{ClauseFont}{commands}}{% + \leavevmode\BeginIndex{FontElement}{\PName{Name}.Clause}% + \LabelFontElement{\PName{Name}.Clause}% + If this option is used, a new + \FontElement{\PName{Name}.Clause}\IndexFontElement{\PName{Name}.Clause} + element is defined using + \DescRef{maincls-experts.cmd.newkomafont}\IndexCmd{newkomafont}, with the + \PName{commands} used as its default setting. If the element was + previously defined as an alias (see + \DescRef{maincls-experts.cmd.aliaskomafont} in + \autoref{sec:maincls-experts.experts}, + \DescPageRef{maincls-experts.cmd.aliaskomafont}), it will become an + independent element instead. If it has already been defined as an + independent element, \DescRef{\LabelBase.cmd.setkomafont} is used to set + the \PName{commands} a new font settings. Please note the limitations for + font settings in \autoref{sec:\LabelBase.textmarkup}, + \DescPageRef{\LabelBase.cmd.setkomafont}. + \EndIndex{FontElement}{\PName{Name}.Clause}% + }% + \entry{\OptionVName{SubClause}{command}}{% + Defines the \PName{command} to which the + \DescRef{\LabelBase.cmd.SubClause} command is mapped within the + environment. This \PName{command}, like the one documented for + \DescRef{\LabelBase.env.contract}, expects exactly one argument. To use it + correctly requires advanced knowledge of the \Package{scrjura}'s internal + functioning. Furthermore, the requirements for the \PName{command} may + change in future versions. Therefore it is recommended not to use this + option!% + }% + \entry{\OptionVName{Sentence}{command}}{% + Defines the \PName{command} to which the + \DescRef{\LabelBase.cmd.Sentence} is mapped within the environment. This + \PName{command} must not have an argument. Typically it should add one to + the \Counter{sentence}\IndexCounter{sentence} (using + \Macro{refstepcounter}\IndexCmd{refstepcounter}) counter and display it + appropriately. It is particularly important to avoid adding unwanted + spaces.% + }% + \entry{\OptionVName{ClauseNumberFormat}{command}}{% + Formats the numbers of clauses within the environment. The \PName{command} + should expect exactly one argument: the number of the clause. If the + \PName{command} implements a series of commands and the number is the last + argument of a that series, you can directly use the series of commands as + \PName{command}.% + } +\end{desclist} \begin{Example} - To define the environment we mentioned in the preface of this section, - for articles, it is sufficient to write: + To define the environment for articles we mentioned in the preface of this + section, it is sufficient to write: \begin{lstcode} - \DeclareNewJuraEnvironment{Artikel}[ClauseNumberFormat=Art.]{}{} + \DeclareNewJuraEnvironment{Article}[ClauseNumberFormat=Art.]{}{} \end{lstcode} - In case paragraphs have to be separated by space between the - paragraphs, \Package{scrjura} together with a \KOMAScript{} document class - allows to write: + If we are using a \KOMAScript{} class and want to separate the paragraphs in + this environment with space instead of using paragraph indentation, we can + use: \begin{lstcode} - \DeclareNewJuraEnvironment{Artikel}[ClauseNumberFormat=Art.~] + \DeclareNewJuraEnvironment{Article}[ClauseNumberFormat=Art.~] {\KOMAoptions{parskip}}{} \end{lstcode} - In cross references will ``Art.'' be used instead of ``\S'', of course.% + In cross-references, ``Art.'' will of course be used instead of ``\S''.% + + The new environment is used like \DescRef{\LabelBase.env.contract}: +\begin{lstcode} + \begin{Article} + \Clause + Human dignity is inviolable. To respect and protect people is a + duty of all state authority. + \end{Article} +\end{lstcode} \end{Example}% \EndIndexGroup @@ -786,19 +869,19 @@ supported: \section{Support for Different Languages} \label{sec:scrjura.babel} -The package \Package{scrjura} has been developed in cooperation with an German -lawyer. Therefore primarily it has provided the languages \PValue{german}, +The \Package{scrjura} package has been developed in cooperation with a German +lawyer. Therefore it initially supported only the languages \PValue{german}, \PValue{ngerman}, \PValue{austrian}, and \PValue{naustrian}. Nevertheless, it has been designed to support common language packages like -\Package{babel}\important{\Package{babel}}\IndexPackage{babel}. Users can make -language adjustments simply using \DescRef{scrbase.cmd.providecaptionname} -(see \autoref{sec:scrbase.languageSupport}, -\DescPageRef{scrbase.cmd.providecaptionname}). But if you have definite -information about the correct juristic terms and conventions of a language, it -is recommended to contact the \KOMAScript{} author. This has been happened for -English and therefore in the meantime \Package{scrjura} also provides terms -for languages \PValue{english}, \PValue{american}, \PValue{british}, -\PValue{canadian}, \PValue{USenglish}, and \PValue{UKenglish}. +\Package{babel}\important{\Package{babel}}\IndexPackage{babel}. Users can +easily make changes by using \DescRef{scrbase.cmd.providecaptionname} (see +\autoref{sec:scrbase.languageSupport}, +\DescPageRef{scrbase.cmd.providecaptionname}). If you have definitive +information about the correct legal terms and conventions of a language, +please contact the \KOMAScript{} author. Support for English has been added in +this way, and so \Package{scrjura} now also provides terms for the languages +\PValue{english}, \PValue{american}, \PValue{british}, \PValue{canadian}, +\PValue{USenglish}, and \PValue{UKenglish}. \begin{Declaration} \Macro{parname}% @@ -807,13 +890,12 @@ for languages \PValue{english}, \PValue{american}, \PValue{british}, \Macro{sentenceshortname} \end{Declaration} These are the language-dependent terms used by \Package{scrjura}. The meaning -of the terms and the English defaults are shown in -\autoref{tab:scrjura.captionnames}. The package itself uses +of the terms and their English defaults are shown in +\autoref{tab:scrjura.captionnames}. The package itself defines them by using \DescRef{scrbase.cmd.providecaptionname} inside -\Macro{begin}\PParameter{document} to define them. So pre-definitions for the -same language but before loading \Package{scrjura} will not be changed. If -you use \Package{scrjura} with a language setting currently not supported, the -package throws an error.% +\Macro{begin}\PParameter{document} only if other requirements have not already +been met. If you use \Package{scrjura} with an unsupported language, the +package will throw an error.% % \begin{table} \KOMAoptions{captions=topbeside}% @@ -845,164 +927,163 @@ package throws an error.% \section{A Detailed Example} \label{sec:scrjura.example} -Remember the letter from \autoref{cha:scrlttr2}. A club member has written to -the board because of the general meeting that is regulated by the club -statutes. Such club statutes are a kind of contract and you can realise them -using \Package{scrjura}.\footnote{Please note, the example is still in German - and has to be translated. Currently we have had not enough manpower to do - the translation. Nevertheless, the contents of the example does not matter - but the technical realisation.} +You may remember the letter from \autoref{cha:scrlttr2}, in which a club +member wanted to remind the board about an overdue meeting that was prescribed +by the club's by-laws. Such club by-laws are a kind of contract, and you can +create them using \Package{scrjura}. \lstinputcode[{xleftmargin=2em,% linerange=1-2}]{scrjuraexample.tex}% We use class \Class{scrartcl}. Because paragraph distance instead of paragraph -indentation is usual in club statutes we load the class with option +indentation is usual in club by-laws, we load the class with option \OptionValueRef{maincls}{parskip}{half} (see \autoref{sec:maincls.parmarkup}, \DescPageRef{maincls.option.parskip}). \lstinputcode[{xleftmargin=2em,% linerange=4-4}]{scrjuraexample.tex}% -The club rules are in German. Therefore package \Package{babel} with option -\Option{ngerman} is used, too. +The club rules are in British English. Therefore we load the \Package{babel} +package with the \Option{british} option too. \lstinputcode[{xleftmargin=2em,% linerange={6-7,9-9}}]{scrjuraexample.tex}% -Default settings for the fonts are made. Additionally package -\Package{textcomp} is loaded, because it does not only provide a usable Euro -sign but also an improved section sign (\S). +We make some default font settings and load the \Package{textcomp} package +because it provides an improved section mark (\S) and\,---\,something that may +be useful in other circumstances\,---\,a usable Euro symbol for some fonts. -\lstinputcode[{moretexcs=SelectInputMappings,xleftmargin=2em,% - linerange=11-15}]{scrjuraexample.tex}% -We want to input special characters and umlauts without commands. To do so, we -let \LaTeX{} detect the input encoding. Alternatively we could use package -\Package{inputenc}. +%\lstinputcode[{moretexcs=SelectInputMappings,xleftmargin=2em,% +% linerange=11-15}]{scrjuraexample.tex}% +Although it is not relevant for English, if we were writing an another +language, we would want to input non-ASCII characters directly. To do so, we +could let \LaTeX{} detect the input encoding with the \Package{selinput} or +set it with the \Package{inputenc} packages. \lstinputcode[{xleftmargin=2em,% - linerange=17-17}]{scrjuraexample.tex}% -Later in the document we want lists numbered not with arabic numbers but with -lower letters. We can do this easily with package \Package{enumerate}. + linerange=11-11}]{scrjuraexample.tex}% +Later in the document, we want lists numbered not with Arabic numbers but with +lower-case letters. We can do this easily with the \Package{enumerate} package. \lstinputcode[{moretexcs={useshorthands,defineshorthand},% xleftmargin=2em,% - linerange=19-27}]{scrjuraexample.tex}% -Now, it is time for \Package{scrjura}. With option -\OptionValueRef{\LabelBase}{clausemark}{forceboth} we enforce left an right -clause marks for the running head. On the other hand we do not want -\DescRef{maincls.cmd.section} to change the marks for the running -head. Therefore we use page style \PageStyle{myheadings}. This page style + linerange=13-21}]{scrjuraexample.tex}% +Now it is time for \Package{scrjura}. The +\OptionValueRef{\LabelBase}{clausemark}{forceboth} option forces clauses to +create left and right marks for the running head. On the other hand, we do not +want \DescRef{maincls.cmd.section} to change the marks for the running head. +Therefore we use the \PageStyle{myheadings} page style. This page style generally does not provide automatic running heads. -Later we also want a table of contents with the clauses. This can be achieved -with option \DescRef{\LabelBase.option.juratotoc}. Doing so we will see, that -the clause number width is to large for default of the entry into the table of -contents. With \OptionValueRef{\LabelBase}{juratocnumberwidth}{2.5em} we -declare a larger reserved width. +Later, we also want a table of contents with the clauses. This can be achieved +with the \DescRef{\LabelBase.option.juratotoc} option. Doing so we will see +that the default width for these numbers is insufficient for the clause +numbers in the table of contents. With +\OptionValueRef{\LabelBase}{juratocnumberwidth}{2.5em}, we reserve more space. -The definition of short hands has already been shown in -\autoref{sec:scrjura.shorthandexample}. We also use this to make the input -easier and more readable. +The definition of shorthands has already been explained in +\autoref{sec:scrjura.shorthandexample}. In this example we do the same thing +to simplify the input. \lstinputcode[{xleftmargin=2em,% - linerange=29-29}]{scrjuraexample.tex}% -It is time to begin the document. + linerange=23-23}]{scrjuraexample.tex}% +It is time to begin the actual document. \lstinputcode[{xleftmargin=2em,% - linerange=31-35}]{scrjuraexample.tex}% -Like other documents the statutes have a title. We make it with the usual -\KOMAScript{} commands from \autoref{sec:maincls.titlepage} (see down from + linerange=25-29}]{scrjuraexample.tex}% +Like other documents, the by-laws have a title. We created it with the usual +\KOMAScript{} commands (see \autoref{sec:maincls.titlepage}, starting on \autopageref{sec:maincls.titlepage}). \lstinputcode[{xleftmargin=2em,% - linerange=37-37}]{scrjuraexample.tex}% -As already stated, we want to have a table of contents. + linerange=31-31}]{scrjuraexample.tex}% +As already mentioned, we want to create a table of contents. \lstinputcode[{xleftmargin=2em,% - linerange=39-43}]{scrjuraexample.tex}% -Preambles are not unusual in club statutes. Here we use -\DescRef{maincls.cmd.addsec} to realise it, because we want to have an entry -into the table of contents. + linerange=33-37}]{scrjuraexample.tex}% +Preambles are not unusual in club by-laws. Here we use +\DescRef{maincls.cmd.addsec} to create one because we want it to have an entry +in the table of contents. \lstinputcode[{xleftmargin=2em,% - linerange=45-45}]{scrjuraexample.tex}% -Here we use a tiny trick. The articles of the club statutes should be numbered -with uppercase letters instead of arabic numbers. This is the same like the -numbering of appendix sections of an article with \Class{scrartcl}. + linerange=39-39}]{scrjuraexample.tex}% +Here we use a small trick. The articles of the club by-laws should be numbered +with upper-case letters instead of Arabic numbers, just as +the appendix sections of an article using \Class{scrartcl} are. \lstinputcode[{xleftmargin=2em,% - linerange=47-49}]{scrjuraexample.tex}% + linerange=41-43}]{scrjuraexample.tex}% We begin the contract with the first article. \lstinputcode[{xleftmargin=2em,% - linerange=50-59}]{scrjuraexample.tex}% + linerange=44-54}]{scrjuraexample.tex}% The first clause has a number and a title. We will do the same with all following clauses. -The first paragraph of the clause is very usual. Because it is not the only -paragraph, the output is done with a number before the text. Note that the -numbering of the first paragraph needs at least two \LaTeX{} runs like you -will for the table of contents. +The first paragraph of the clause contains nothing unusual. Because it is not +the only paragraph, every paragraph will be automatically preceded by a +paragraph number. Note that the numbering the first paragraph requires at +least two \LaTeX{} runs. Since this is the case for the table of contents as +well, this does not create any additional problems. -In the second paragraph we have two sentences. Here we can see the short hands -\texttt{'S} and \texttt{'.} in action. The first one does only generate the -sentence number. The second one does not only print the full stop but also the +In the second paragraph we have two sentences. Here we can see the shorthands +\texttt{'S} and \texttt{'.} in action. The first one only generates the +sentence number. The second one generates not only the full stop but also the sentence number. With this, both sentences are numbered. \lstinputcode[{xleftmargin=2em,% - linerange=60-75}]{scrjuraexample.tex}% -The second clause: also with several paragraphs with one or more -sentences. The second paragraph additionally has a numbered list. At the last -paragraph we used a label, because we want to reference it later. + linerange=55-70}]{scrjuraexample.tex}% +The second clause: again this contains several paragraphs, some of which +include several sentences. The second paragraph also has a numbered list. In +the last paragraph, we set a label, because we want to reference it later. \lstinputcode[{xleftmargin=2em,% - linerange=77-84}]{scrjuraexample.tex}% -The third clause has something special: a cross reference. Here we use the -long form with clause, paragraph and sentence. If we would decide, that -sentences should not be referenced, we could use option -\OptionValueRef{\LabelBase}{ref}{nosentence} globally. + linerange=72-78}]{scrjuraexample.tex}% +The third clause contains something special: a cross-reference. Here we use +the long form with clause, paragraph, and sentence. If we decided later that +sentences should not be included in the reference, we could use the +\OptionValueRef{\LabelBase}{ref}{nosentence} option to set this globally. \lstinputcode[{xleftmargin=2em,% - linerange=86-87}]{scrjuraexample.tex}% -Here we have a special kind of clauses. In prior versions of the club statutes -this was a real clause. But then it has been removed. Nevertheless, the + linerange=80-81}]{scrjuraexample.tex}% +Here we have a special kind of clause. In earlier versions of the club by-laws, +this was a real clause, but it was later removed. However, the numbering of the following clauses should not be changed by removing this one. Therefore the \DescRef{\LabelBase.cmd.Clause} statement has not been removed but supplemented by option \Option{dummy}. With this, we also can set -a label despite the clause will not be printed. +a label even though the clause will not be printed. \lstinputcode[{xleftmargin=2em,% - linerange=88-92}]{scrjuraexample.tex}% -Another article starts. To avoid problems with the paragraph numbering we + linerange=82-86}]{scrjuraexample.tex}% +Another article begins. To avoid problems with the paragraph numbering, we interrupt the \DescRef{\LabelBase.env.contract} environment. \lstinputcode[{xleftmargin=2em,% - linerange=93-93}]{scrjuraexample.tex}% -The first clause of the next article also has been removed. + linerange=87-87}]{scrjuraexample.tex}% +The first clause of the next article also has been deleted. \lstinputcode[{xleftmargin=2em,% - linerange=95-104}]{scrjuraexample.tex}% -We have a real clause again. We cross reference one of the removed -clauses and also use a label. + linerange=89-98}]{scrjuraexample.tex}% +Here we have a real clause again. We cross-reference one of the deleted +clauses and also set a label. \lstinputcode[{xleftmargin=2em,% - linerange=107-112}]{scrjuraexample.tex}% + linerange=100-104}]{scrjuraexample.tex}% Once more, this is a special kind of clause. This time we have not removed a -clause but added one without renumbering of the following clauses. To do so, +clause but added one without renumbering the following clauses. To do so, we use \DescRef{\LabelBase.cmd.SubClause}. Therefore the clause number is the same like the previous one but with an appended ``a''. \lstinputcode[{xleftmargin=2em,% - linerange=114-134}]{scrjuraexample.tex}% + linerange=106-126}]{scrjuraexample.tex}% The other clauses of this article are very usual. You already know all the features used for them. \lstinputcode[{xleftmargin=2em,% - linerange=136-150}]{scrjuraexample.tex}% -More articles with known features are following. + linerange=128-141}]{scrjuraexample.tex}% +There follows another article no special features. \lstinputcode[{xleftmargin=2em,% - linerange=152-152}]{scrjuraexample.tex}% -Then the \LaTeX{} document ends. You can see three pages from the front of the -document in \autoref{fig:scrjura.example}.% + linerange=143-143}]{scrjuraexample.tex}% +Then the \LaTeX{} document ends. You can see first three pages in +\autoref{fig:scrjura.example}.% % \begin{figure} \setcapindent{0pt}% @@ -1014,10 +1095,10 @@ document in \autoref{fig:scrjura.example}.% height=.49\textheight,keepaspectratio]{scrjuraexample}}\par \smallskip} \begin{captionbeside}[{% - Example: Three pages from the front of the example club statutes of + Example: First three pages of the example club by-laws of \protect\autoref{sec:scrjura.example}% }]{% - Three pages from the front of the example club statutes of + First three pages of the example club by-laws of \protect\autoref{sec:scrjura.example}% }% [l] @@ -1031,10 +1112,10 @@ document in \autoref{fig:scrjura.example}.% \frame{\includegraphics[page=2,width=.482\textwidth]{scrjuraexample}}\par \smallskip} \begin{captionbeside}[{% - Example: Three pages from the front of the example club statutes of + Example: First three pages of the example club by-laws of \protect\autoref{sec:scrjura.example}% }]{% - Three pages from the front of the example club statutes of + First three pages of the example club by-laws of \protect\autoref{sec:scrjura.example}% }% [l] @@ -1048,15 +1129,14 @@ document in \autoref{fig:scrjura.example}.% \section{State of Development} \label{sec:scrjura.draft} -Since \KOMAScript~3.24 package \Package{scrjura} shares the version number of -the classes and other important packages of \KOMAScript. Nevertheless, you -should note: Neither the cooperation with other packages nor the cooperation -of the \DescRef{\LabelBase.env.contract} environment with all kind of \LaTeX{} -environments or document classes has been tested. The main reason for this is -that the package is very special and the package author does not have any -requirement to use it. So all changes, all features, all improvement can only -base on detailed user feedback and only about two and a half users are willing -to send such feedback.% +Since \KOMAScript~3.24, the \Package{scrjura} package has shared the version +number of the classes and other important packages of \KOMAScript. +Nevertheless, you should note that so far, the interaction of the +\DescRef{\LabelBase.env.contract} environment with the many different settings +possible with other \LaTeX{} environments, packages, or classes has not been +tested. The main reason for this is that \Package{scrjura} is very specialised +and far beyond the author's ordinary practice. So the author mostly relies on +detailed user feedback.% \EndIndexGroup \endinput @@ -1068,6 +1148,4 @@ to send such feedback.% %%% ispell-local-dictionary: "en_GB" %%% TeX-PDF-mode: t %%% TeX-master: "guide.tex" -%%% End: - -% LocalWords: reseted +%%% End: diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrjuraexample.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrjuraexample.tex index b9d700eaef5..013d1b60bcf 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrjuraexample.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrjuraexample.tex @@ -1,19 +1,13 @@ \documentclass[fontsize=12pt,pagesize,parskip=half] {scrartcl} -\usepackage[ngerman]{babel} +\usepackage[british]{babel} \usepackage[T1]{fontenc} \usepackage{lmodern} \usepackage{charter,helvet} \usepackage{textcomp} -\usepackage{selinput} -\SelectInputMappings{ - adieresis={ä}, - germandbls={ß}, -} - \usepackage{enumerate} \usepackage[clausemark=forceboth, @@ -28,124 +22,121 @@ \begin{document} -\subject{Satzung} -\title{VfVmai} -\subtitle{Verein für Vereinsmaierei mit ai n.e.V.} +\subject{By-Laws} +\title{CfCH} +\subtitle{Club for Club Hoppers} \date{11.\,11.\,2011} \maketitle \tableofcontents -\addsec{Präambel} +\addsec{Preamble} -Die Vereinslandschaft in Deutschland ist vielfältig. -Doch leider mussten wir feststellen, dass es dabei oft -am ernsthaften Umgang mit der Ernsthaftigkeit krankt. +The club landscape in England is diverse. But we have +unfortunately been forced to conclude that it often +suffers seriously when dealing with seriousness. \appendix -\section{Allgemeines} +\section{Overview} \begin{contract} -\Clause{title={Name, Rechtsform, Sitz des Vereins}} +\Clause{title={Name, Legal Form, Headquarters}} -Der Verein führt den Namen »Verein für Vereinsmaierei mit -ai n.e.V.« und ist in keinem Vereinsregister eingetragen. +The name of this club shall be the ``Club for Club +Hoppers'' and is not registered in any club register. -'S Der Verein ist ein nichtwirtschaftlicher, unnützer -Verein'. Er hat keinen Sitz und muss daher stehen. +'S The club is a non-economic, useless club'. It has no +headquarters because its members heads are in their +hindquarters. -Geschäftsjahr ist vom 31.~März bis zum 1.~April. +The fiscal year is from March 31st through April 1st. -\Clause{title={Zweck des Vereins}} +\Clause{title={Purpose of the Club}} -'S Der Verein ist zwar sinnlos, aber nicht zwecklos'. -Vielmehr soll er den ernsthaften Umgang mit der -Ernsthaftigkeit auf eine gesunde Basis stellen. +'S The club is pointless but not useless'. Rather, +it should put the serious handling of seriousness on a +sound footing. -Zu diesem Zweck kann der Verein +For this purpose, the club members can \begin{enumerate}[\qquad a)] -\item in der Nase bohren, -\item Nüsse knacken, -\item am Daumen lutschen. +\item pick their noses, +\item crack nuts, +\item such their thumbs. \end{enumerate} -Der Verein ist selbstsüchtig und steht dazu. +The club is selfish and stands by it. -Der Verein verfügt über keinerlei Mittel.\label{a:mittel} +The club has no financial means.\label{a:mittel} -\Clause{title={Vereinsämter}} +\Clause{title={Club Officers}} -Die Vereinsämter sind Ehrenämter. +The club officers hold honorary positions. -'S Würde der Verein über Mittel verfügen -(siehe \ref{a:mittel}), so könnte er einen -hauptamtlichen Geschäftsführer bestellen'. Ohne -die notwendigen Mittel ist dies nicht möglich. +'S If the club had resources (see \ref{a:mittel}), it +could afford a full-time manager'. Without the necessary +funds, this is not possible. -\Clause{title={Vereinsmaier},dummy} +\Clause{title={Club Hopper},dummy} \label{p.maier} \end{contract} -\section{Mitgliedschaft} +\section{Membership} \begin{contract} -\Clause{title={Mitgliedsarten},dummy} +\Clause{title={Types of Members},dummy} -\Clause{title={Erwerb der Mitgliedschaft}} +\Clause{title={Becoming a Member}} -Die Mitgliedschaft kann jeder zu einem angemessenen -Preis von einem der in \refClause{p.maier} -genannten Vereinsmaier erwerben.\label{a.preis} +Everyone can purchase a membership from one of the +associations listed in \refClause{p.maier}.\label{a.preis} -'S Zum Erwerb der Mitgliedschaft ist ein formloser -Antrag erforderlich'. Dieser Antrag ist in grüner -Tinte auf rosa Papier einzureichen. +'S To become a member, an informal application is +required'. This application should be submitted in green +ink on pink paper. -Die Mitgliedschaft kann nicht abgelehnt werden. +Membership applications cannot be rejected. -\SubClause{title={Ergänzung zu vorstehendem - Paragraphen}} +\SubClause{title={Amendment to the Previous Clause}} -'S Mit Abschaffung von \refClause{p.maier} verliert -\ref{a.preis} seine Umsetzbarkeit'. Mitgliedschaften -können ersatzweise vererbt werden. +'S With the repeal of \refClause{p.maier}, +\ref{a.preis} has become impractical'. In its place, +memberships can be inherited. -\Clause{title={Ende der Mitgliedschaft}} +\Clause{title={Termination of Membership}} -'S Die Mitgliedschaft endet mit dem Leben'. Bei nicht -lebenden Mitgliedern endet die Mitgliedschaft nicht. +'S Membership ends with one's life'. For non-living +members, membership does not end. -\Clause{title={Mitgliederversammlung}} +\Clause{title={General Meeting}} -Zweimal jährlich findet eine Mitgliederversammlung statt. +A general meeting shall take place twice per year. -Der Abstand zwischen zwei Mitgliederversammlungen -beträgt höchstens 6~Monate, 1~Woche und 2~Tage. +The interval between two general meetings shall be +no more than 6~months, 1~week, and 2~days. -Frühestens 6~Monate nach der letzten Mitgliederversammlung -hat die Einladung zur nächsten Mitgliederversammlung zu -erfolgen. +The invitation to the next general meeting shall be sent +no earlier than 6~months from the previous general +meeting. -\SubClause{title={Ergänzung zur Mitgliederversammlung}} +\SubClause{title={Amendment to the General Meeting}} -Die Mitgliederversammlung darf frühstens 2~Wochen nach -letztem Eingang der Einladung abgehalten werden. +The general meeting may be held at the earliest 2~weeks after +the invitation is received. \end{contract} -\section{Gültigkeit} +\section{Validity} \begin{contract} -\Clause{title={In Kraft treten}} +\Clause{title={Effective Date}} -Diese Satzung tritt am 11.\,11.\,2011 um 11:11~Uhr -in Kraft. +These articles will enter into force on 11.\,11.\,2011 at +11:11~am. -'S Sollten irgendwelche Bestimmungen dieser Satzung im -Widerspruch zu einander stehen, tritt die Satzung am -11.\,11.\,2011 um 11:11~Uhr und 11~Sekunden wieder -außer Kraft'. Der Verein ist in diesem Fall als -aufgelöst zu betrachten. +'S If any provision of these by-laws is in conflict with +any other, the by-laws will be repealed on +11.\,11.\,2011 at 11:11~am and 11~seconds'. The club is +considered to be dissolved in this case. \end{contract} diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn-example.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn-example.tex index 512e36dab09..164c646e1f0 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn-example.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn-example.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrlayer-notecolumn-example.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrlayer-notecolumn-example.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -47,13 +47,6 @@ % % ============================================================================ \documentclass{scrartcl} -\usepackage[ngerman]{babel} -\usepackage{selinput} -\SelectInputMappings{ - adieresis={ä}, - germandbls={ß}, -} -\usepackage[T1]{fontenc} \usepackage{lmodern} \usepackage{xcolor} @@ -81,51 +74,48 @@ \begin{document} -\title{Kommentar zum GüdaVaS} +\title{Commentary on the SCRACH} \author{Professor R. O. Tenase} -\date{11.\,11.\,2011} +\date{11/11/2011} \maketitle \tableofcontents -\section{Vormerkung} -Das GüdaVaS ist ohne jeden Zweifel das wichtigste Gesetz, das in -Spaßmaniern in den letzten eintausend Jahren verabschiedet wurde. -Die erste Lesung fand bereits am 11.\,11\,1111 im obersten -spaßmanischen Kongress statt, wurde aber vom damalige Spaßvesier -abgelehnt. Erst nach Umwandlung der spaßmanischen, aberwitzigen Monarchie -in eine repräsentative, witzige Monarchie durch W. Itzbold, den -urkomischen, am 9.\,9.\,1999 war der Weg für dieses Gesetz endlich frei. +\section{Preamble} +The SCRACH is without doubt the most important law on the manners of humour +that has been passed in the last thousand years. The first reading took place +on 11/11/1111 in the Supreme Manic Fun Congress, but the law was rejected by +the Vizier of Fun. Only after the ludicrous, Manic Fun monarchy was +transformed into a representative, witty monarchy by W. Itzbold, on 9/9/1999 +was the way finally clear for this law. -\section{Analyse} +\section{Analysis} \begin{addmargin}[0pt]{.333\textwidth} \makenote[paragraphs]{% \protect\begin{contract} - \protect\Clause{title={Kein Witz ohne Publikum}} - Ein Witz kann nur dort witzig sein, wo er auf ein Publikum trifft. + \protect\Clause{title={No Joke without an Audience}} + A joke can only be funny if is has an audience. \protect\end{contract} } - Dies ist eine der zentralsten Aussagen des Gesetzes. Sie ist derart - elementar, dass es durchaus angebracht ist, sich vor der Weisheit der - Verfasser zu verbeugen. + This is one of the most central statements of the law. It is so fundamental + that it is quite appropriate to bow to the wisdom of the authors. \syncwithnotecolumn[paragraphs]\bigskip \makenote[paragraphs]{% \protect\begin{contract} - \protect\Clause{title={Komik der Kultur}} - \setcounter{par}{0}Die Komik eines Witzes kann durch das kulturelle - Umfeld, in dem er erzählt wird, bestimmt sein. + \protect\Clause{title={Humor of a Culture}} + \setcounter{par}{0}The humour of a joke can be determined by the + cultural environment in which it is told. - Die Komik eines Witzes kann durch das kulturelle Umfeld, in dem er - spielt, bestimmt sein. + The humour of a joke can be determined by the cultural environment in + which it acts. \protect\end{contract} } - Die kulturelle Komponente eines Witzes ist tatsächlich nicht zu - vernachlässigen. Ãœber die politische Korrektheit der Nutzung des kulturellen - Umfeldes kann zwar trefflich gestritten werden, nichtsdestotrotz ist die - Treffsicherheit einer solchen Komik im entsprechenden Umfeld frappierend. Auf - der anderen Seite kann ein vermeintlicher Witz im falschen kulturellen - Umfeld auch zu einer echten Gefahr für den Witzeerzähler werden. + The cultural component of a joke is, in fact, not negligible. Although the + political correctness of using the cultural environment can easily be + disputed, nonetheless the accuracy of such comedy in the appropriate + environment is striking. On the other hand, a supposed joke in the wrong + cultural environment can also be a real danger for the joke teller. \end{addmargin} \end{document} diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn.tex index a181dd5780d..47cc29a8aa8 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-notecolumn.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrlayer-notecolumn.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2013-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrlayer-notecolumn.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2013-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,233 +46,190 @@ % ============================================================================ \KOMAProvidesFile{scrlayer-notecolumn.tex} - [$Date: 2014-03-07 09:40:24 +0100 (Fri, 07 Mar 2014) $ + [$Date: 2018-02-05 01:50:56 -0800 (Mon, 05 Feb 2018) $ KOMA-Script guide (chapter:scrlayer-notecolumn)] -\translator{Markus Kohm\and Arndt Schubert} +\translator{Markus Kohm\and Arndt Schubert\and Karl Hagen} -% Date of the translated German file: 2017-02-08 +% Date of the translated German file: 2018-02-05 \chapter{Note Columns with \Package{scrlayer-notecolumn}} \labelbase{scrlayer-notecolumn} + \BeginIndexGroup -\BeginIndex{}{note>columns}% \BeginIndex{Package}{scrlayer-notecolumn}% -Up to version~3.11b \KOMAScript{} supported note columns only by marginal -notes that get their contents from \DescRef{maincls.cmd.marginpar} and \DescRef{maincls.cmd.marginline} -(see \autoref{sec:maincls.marginNotes}, -\DescPageRef{maincls.cmd.marginline}). This kind of note columns has -several disadvantages: +Through version~3.11b, \KOMAScript{} supported note columns only in the form +of marginal notes that get their contents from \DescRef{maincls.cmd.marginpar} +and \DescRef{maincls.cmd.marginline} (see \autoref{sec:maincls.marginNotes}, +\DescPageRef{maincls.cmd.marginline}). This kind of note column has several +disadvantages: \begin{itemize} -\item Marginal notes can be output only completely on one page. Page - breaks\textnote{page break} inside marginal notes are not - possible. Sometimes this results in margin notes located close to the lower - page margin. +\item Marginal notes must be set completely on a single page. Page + breaks\textnote{page break} inside marginal notes are not possible. This + sometimes causes the marginal notes to protrude into the lower margin. \item Marginal notes near page breaks sometimes float to the next page and - then in - case of two-sided layout with alternating marginal notes can be output at - the wrong margin.\textnote{put it into the correct margin}. This problem can - be solved by additional packages like - \Package{mparhack}\IndexPackage{mparhack} or usage of \Macro{marginnote} - provided by package \Package{marginnote}\IndexPackage{marginnote}. + then, in the case of two-sided printing, cause alternate marginal columns to + appear in the wrong margin.\textnote{assignment to the correct margin}. This + problem can be solved with the additional package + \Package{mparhack}\IndexPackage{mparhack} or by using \Macro{marginnote} + from the \Package{marginnote}\IndexPackage{marginnote} package (see + \cite{package:marginnote}). \item Marginal notes inside floating environments\textnote{floating environments} or footnotes\textnote{footnotes} are not possible. This - problem can be solved using \Macro{marginnote} of package - \Package{marginnote}\IndexPackage{marginnote}, too. -\item There is only one marginal note column\textnote{several note columns} or - at most two, if you work with \Macro{reversemarginpar} and - \Macro{normalmarginpar}. You should know, that \Macro{reversemarginpar} is - of less usability on two-sided documents. + problem can also be solved with \Macro{marginnote} of the + \Package{marginnote}\IndexPackage{marginnote} package. +\item There is only one marginal note column\textnote{several note columns}, + or at most two if you use \Macro{reversemarginpar} and + \Macro{normalmarginpar}. Note that \Macro{reversemarginpar} is of less + utility with two-sided documents. \end{itemize} -Usage of \Package{marginnote}\IndexPackage{marginnote} results in one more -problem. Because the package does not have any collision detection, marginal -notes that are set near to each other can partially or totally -overlap. Moreover, usage of \Macro{marginnote} sometimes and depending on the -used settings can result in changes of the baseline distance of the normal -text. - -Package \Package{scrlayer-notecolumn} should solve all these problems. To do -so, it uses the basic functionality of -\Package{scrlayer}\IndexPackage{scrlayer}. Nevertheless, there is a -disadvantage of using this package:\textnote{Attention!} Notes can be output -only on pages that use a \Package{scrlayer} based page style. This -disadvantage may be easily resolved and maybe changed into an advantage using -\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage}. +Using \Package{marginnote}\IndexPackage{marginnote} leads to one more problem. +Because the package does not have any collision detection, marginal notes that +are set near to each other can partially or totally overlap. Moreover, +depending on the settings used, \Macro{marginnote} sometimes changes the +baseline distance of the normal text. + +The \Package{scrlayer-notecolumn} package should solve all these problems. To +do so, it relies on the basic functionality of +\hyperref[cha:scrlayer]{\Package{scrlayer}}\IndexPackage{scrlayer}% +\important{\hyperref[cha:scrlayer]{\Package{scrlayer}}}. However, using this +package has a drawback:\textnote{Attention!} you can only output notes on +pages that use a page style based on +\hyperref[cha:scrlayer]{\Package{scrlayer}}. This disadvantage, however, can +easily be resolved, or even turned into an advantage, with the help of +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}}% +\IndexPackage{scrlayer-scrpage}. \section{Note about the State of Development} \seclabel{draft} -Originally the package has been made as a so called \emph{proof of +This package was originally developed as a so-called \emph{proof of concept}\textnote{proof of concept} to demonstrate the potential of -\Package{scrlayer}. Despite the fact that it currently is in a very early -state of development, the stability of most parts is less a question of -\Package{scrlayer-notecolumn} but of \Package{scrlayer}. Nevertheless it is -assumed that there are still bugs in \Package{scrlayer-notecolumn}. You are -welcome to report such bugs whenever you find one. Some of the disabilities -are caused by minimisation of complexity. As an example note columns can break -to several pages, but there is not a new line break of the paragraphs. \TeX{} -itself does not provide this. - -Because the package is more experimental\textnote{experimental}, the user -manual belongs to the second part of \iffree{the \KOMAScript{} manual}{this - book}, recommended for experienced users. If you are a beginner or -a user on the way to become an expert\textnote{for experts}, some explanations -could be ambiguous or incomprehensible. \iffree{Please understand that I try - to minimise the effort in time and work for the manual of an experimental - package.} +\hyperref[cha:scrlayer]{\Package{scrlayer}}% +\important{\hyperref[cha:scrlayer]{\Package{scrlayer}}}. Although it is still +in its early stages of development, most of its stability is less a question +of \Package{scrlayer-notecolumn} than of +\hyperref[cha:scrlayer]{\Package{scrlayer}}. Nevertheless, you can assume that +there are still bugs in \Package{scrlayer-notecolumn}. Please report such bugs +whenever you find them. Some of the package's shortcomings are caused by the +attempt to minimise complexity. For example, although note columns can break +across several pages, there is no new paragraph break. \TeX{} itself does not +provide this. + +Because the package is rather experimental\textnote{experimental}, its +instructions are found here in the second part of \iffree{the \KOMAScript{} +manual}{this book}. Accordingly, it is primarily directed towards experienced +users. If you are a beginner or a user on the way to become an +expert\textnote{for experts}, some of the following explanations may be +unclear or even incomprehensible. +\iffree{Please understand that I want to keep the effort spent on the manual + to something halfway bearable when it comes to experimental packages.}{% + However, this should be enough to solve simple tasks with + \Package{scrlayer-notecolumn}. At the same time, developers will hopefully + find useful stimulus for their own ideas.} + +\iffalse% Umbruchoptimierung +Note also\textnote{Attention!} that the author of \KOMAScript{} does not +guarantee the further development of this package and offers only limited +support for it. This is the nature of a package written solely for the +purposes of demonstration.% +\fi \LoadCommonFile{options}% \section{Early or late Selection of Options} \LoadCommonFile{textmarkup}% \section{Text Markup} -\section{Declaration of new Note Columns} +\section{Declaring New Note Columns} \seclabel{declaration} -Loading the package already declares a note column named \PValue{marginpar} -automatically. The name already adumbrates that this note column is placed in -the area of the normal marginal note column used by \DescRef{maincls.cmd.marginpar} and -\DescRef{maincls.cmd.marginline}. It even recognises the setting of \Macro{reversemarginpar} -and \Macro{normalmarginpar} page by page instead of note by note. So these -switches are irrelevant when the user defines a note but relevant when the -package outputs the note during \LaTeX's page building. If you want to use -notes at the left and at the right margin within one page, you should declare -at least one more note column. - -The default settings for every newly declared note column is the same like -that of the predefined \PValue{marginpar}. But you can easily change them -during declaration. - -You should note\textnote{Attention!} that note columns can be output only on -pages that use a page style made with package -\Package{scrlayer}\IndexPackage{scrlayer}. Package -\Package{scrlayer-notecolumn} automatically loads \Package{scrlayer}, which by -default provides only page style \PageStyle{empty}\IndexPagestyle{empty}. If -you need additional page styles, the use of -\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} is recommended. +Loading the package automatically declares a note column named +\PValue{marginpar}. As the name implies, this note column is placed in the +area of the normal marginal column used by \DescRef{maincls.cmd.marginpar} and +\DescRef{maincls.cmd.marginline}. The \Macro{reversemarginpar} and +\Macro{normalmarginpar} settings are also taken into account, but only for all +the notes on a page instead of note by note. The relevant setting is the one +that applies at the end of the page, namely during the output of the note +column. If you want to have notes in both the left and right margin of the +same page, you should define a second note column. + +The default settings for all newly declared note columns are the same as the +defaults for \PValue{marginpar}. % +\iftrue% Umbruchoptimierung +But you can easily change them during their initialisation.% +\fi + +Note\textnote{Attention!} that note columns can be output only on pages that +use a page style based on the +\hyperref[cha:scrlayer]{\Package{scrlayer}}\IndexPackage{scrlayer}% +\important{\hyperref[cha:scrlayer]{\Package{scrlayer}}} package. The +\Package{scrlayer-notecolumn} package automatically loads +\hyperref[cha:scrlayer]{\Package{scrlayer}}, which by default provides only +\PageStyle{empty}\IndexPagestyle{empty} page style. If you need additional +page styles, \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} is +recommended. \begin{Declaration} \Macro{DeclareNoteColumn}% - \OParameter{option list}\Parameter{note column name}% + \OParameter{option~list}\Parameter{note~column~name}% \Macro{DeclareNewNoteColumn}% - \OParameter{option list}\Parameter{note column name}% + \OParameter{option~list}\Parameter{note~column~name}% \Macro{ProvideNoteColumn}% - \OParameter{option list}\Parameter{note column name}% + \OParameter{option~list}\Parameter{note~column~name}% \Macro{RedeclareNoteColumn}% - \OParameter{option list}\Parameter{note column name}% + \OParameter{option~list}\Parameter{note~column~name}% \end{Declaration} -These commands can be used to declare note columns. \Macro{DeclareNoteColumn} -declares the note column independent of whether or not they already -exist. \Macro{DeclareNewNoteColumn} throws an error message if \PName{note - column name} has already been used for another note -column. \Macro{ProvideNoteColumn} simply does nothing in the same -case. \Macro{RedeclareNoteColumn} can be used only to declare an already -existing note column again. - -By the way: Already existing notes of a already existing note column are not -lost if you re-declare it using \Macro{DeclareNoteColumn} or -\Macro{RedeclareNoteColumn}. +You can use these commands to create note columns. \Macro{DeclareNoteColumn} +creates the note column regardless of whether it already exists. +\Macro{DeclareNewNoteColumn} throws an error if the \PName{note column name} +has already been used for another note column. \Macro{ProvideNoteColumn} +simply does nothing in that case. You can use \Macro{RedeclareNoteColumn} only +to reconfigure an existing note column. + +By the way, when reconfiguring existing note columns with +\Macro{DeclareNoteColumn} or \Macro{RedeclareNoteColumn}, the notes that have +already been generated for this column are retained. -\BeginIndexGroup \BeginIndex{FontElement}{notecolumn.\PName{note column name}}% \BeginIndex{FontElement}{notecolumn.marginpar}% -\LabelFontElement{notecolumn.marginpar}% -Declaring a new note column does also define a new element of which you can -change the font attributes using \DescRef{\LabelBase.cmd.setkomafont} and -\DescRef{\LabelBase.cmd.addtokomafont} if such a element does not already -exist. The name of the new element is \PValue{notecolumn.}\PName{note column - name}. Because of this the predefined note column \PValue{marginnote} has a -element \FontElement{notecolumn.marginpar}. The initial setting of the -element's font can be done using option \Option{font} as part of the -\PName{option list}.% -\EndIndexGroup - - -The \PName{option list} is a comma separated list of keys with or without -values, also known as options. The available options are shown in -\autoref{tab:scrlayer-notecolumn.note.column.options}. Option\textnote{default: - option \Option{marginpar}} \Option{marginpar} is set by default. But you can -overwrite this default with your individual settings. - -\begin{table} - \caption[Options for the declaration of note columns]% - {% - Options for the declaration of note columns% - }% - \label{tab:scrlayer-notecolumn.note.column.options}% - \begin{desctabular} - \entry{\OptionVName{font}{font declaration}}{% - The initial font attributes to be used for the note column. Everything, - that is allowed to be set by \DescRef{\LabelBase.cmd.setkomafont} or - \DescRef{\LabelBase.cmd.addtokomafont} can be used as \PName{font - declaration} (see \autoref{sec:maincls.textmarkup}, - \DescPageRef{maincls.cmd.setkomafont}). Note that - \Macro{normalfont}\Macro{normalsize} will be used before. So you don't - need one of them at your own initialisation.\par% - Default: \emph{empty}% - }% - \entry{\Option{marginpar}}{% - Sets up \Option{position} and \Option{width} to use the marginal note - column of \DescRef{maincls.cmd.marginpar}. Note that this option does - not expect or allow any value.\par% - Default: \emph{yes}% - }% - \entry{\Option{normalmarginpar}}{% - Sets up \Option{position} and \Option{width} to use the normal marginal - note column and ignore \Macro{reversemarginpar} and - \Macro{normalmarginpar}. Note that this option does not expect or allow - any value.\par% - Default: \emph{no}% - }% - \entry{\OptionVName{position}{offset}}{% - Sets up the horizontal offset of the note column from the left edge of - the paper. The \PName{horizontal offset} can be either a \LaTeX{} - length, a \TeX{} dimension, a \TeX{} skip, a length value, or a - dimensional expression using \texttt{+}, \texttt{-}, \texttt{*}, - \texttt{/} and parenthesis (see \cite[section~3.5]{manual:eTeX} for more - information about dimensional expressions). The value will be calculated - at usage time not at definition time.\par% - Default: \emph{by option \Option{marginpar}}% - }% - \entry{\Option{reversemarginpar}}{% - Sets up \Option{position} and \Option{width} to use the reverse marginal - note column and ignore \Macro{reversemarginpar} and - \Macro{normalmarginpar}. Note that this option does not expect or allow - any value.\par% - Default: \emph{no}% - }% - \entry{\OptionVName{width}{length}}{% - Sets up the horizontal size of the note column. You can use the same - values for \PName{size} like for \PName{offset} of option - \Option{position}.\par% - Default: \emph{by option \Option{marginpar}}% - }% - \end{desctabular} -\end{table} - -Because note columns are implemented using \Package{scrlayer}, each note -column also defines a layer\Index{layer}. The name\textnote{layer's name} of -the layer is the same as the name of the element, +Declaring a new note column always defines a new element for changing its font +attributes with \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont}, if such an element does not yet exist. +The name of the element is \PValue{notecolumn.}\PName{note column name}. For +this reason, the default note column \PValue{marginnote} has the +element\textnote{element name} \FontElement{notecolumn.marginpar}. You can +directly specify the initial setting of the element's font when declaring a +note column by using the \Option{font} option within the \PName{option list}.% +\EndIndex{FontElement}{notecolumn.marginpar}% +\EndIndex{FontElement}{notecolumn.\PName{note column name}}% + +The \PName{option list} is a comma-separated list of keys with or without +values, also known as options. The available options are listed in +\autoref{tab:scrlayer-notecolumn.note.column.options}, +\autopageref{tab:scrlayer-notecolumn.note.column.options}. +The\textnote{default: option \Option{marginpar}} \Option{marginpar} option is +set by default, but you can overwrite this default with your individual +settings. + +Because note columns are implemented using \Package{scrlayer}, a +layer\Index{layer} is created for each note column. The layer +name\textnote{layer name} is the same as the name of the element, \PValue{notecolumn.}\PName{note column name}. For more information about -layers see \autoref{sec:scrlayer.layers}, from +layers see \autoref{sec:scrlayer.layers}, starting on \autopageref{sec:scrlayer.layers}. % \begin{Example} - Assuming, you are a German professor of weird rights and like to write a - paper about the new ``Gesetz über die ausgelassene Verbreitung allgemeiner - Späße e'', GüdaVaS. The main focus of the work should consist of comments to - each section. So you use a two-columned layout. The comments would be the - main text in the main column. The sections should be placed in a smaller - note column on the right side of the main column using a smaller - font\iffree{ and a different colour}{}. + Suppose you are a professor of comedy law and want to write a treatise on + the new ``Statute Concerning the Riotous Airing of Common Humour'', SCRACH + for short. The better part of the work will consist of commentary on + individual paragraphs of the statute. You decide on a two-column layout, + with the comments in the main column and the paragraphs placed in a smaller + note column on the right of the main column using a font that is + smaller\iffree{ and in a different colour}{}. \begin{lstcode} \documentclass{scrartcl} - \usepackage[ngerman]{babel} - \usepackage{selinput} - \SelectInputMappings{ - adieresis={ä}, - germandbls={ß}, - } - \usepackage[T1]{fontenc} \usepackage{lmodern} \usepackage{xcolor} @@ -300,168 +257,232 @@ layers see \autoref{sec:scrlayer.layers}, from \color{blue} ]{paragraphs} \end{lstcode} - The paper should be a single-sided article. The German language (new - spelling) is selected with package \Package{babel}\IndexPackage{babel}. The - input encoding is selected and detected with package - \Package{selinput}\IndexPackage{selinput} automatically. The font is Latin - Modern in 8-bit coding.\iffree{ The colour selection uses package - \Package{xcolor}\IndexPackage{xcolor}.}{} - - For usage of package \Package{scrjura}\IndexPackage{scrjura} to typeset laws - and contracts see \iffree{the German manual of that - package}{\autoref{cha:scrjura}}. - - Next package \Package{scrlayer-notecolumn}\textnote{note columns with - \Package{scrlayer-notecolumn}} is loaded. The required width of the note - column is calculated within - \DescRef{typearea-experts.cmd.AfterCalculatingTypearea} after package - \Package{typearea}'s each new calculation of the typing area. It should be - one third of the typing area minus the distance between the main text and - the note column. % - - With all this information we define the new note column. For - the positions we simply use a dimension expression. Doing so, we have to - note that \Length{oddsidemargin} is not the total left margin but for - historical reasons the left margin minus 1\Unit{inch}. So we have to add - this value. - - That is all of the declaration. But we have to note that currently the note - column would be output inside the typing area. This means that the note - column would overwrite the text. + The treatise should be a one-sided article. The font is Latin Modern, and + the colour selection uses the \Package{xcolor}\IndexPackage{xcolor} package. + + For formatting legal texts\textnote{legal texts with + \hyperref[cha:scrjura]{\Package{scrjura}}} with the + \hyperref[cha:scrjura]{\Package{scrjura}}\IndexPackage{scrjura} package, see + \autoref{cha:scrjura}. + + Since this document uses a page style\textnote{page style with + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} with a + page number, the + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + \IndexPackage{scrlayer-scrpage} package is loaded. Thus, note columns can be + output on all pages. + + Next, the \Package{scrlayer-notecolumn}\textnote{note columns with + \Package{scrlayer-notecolumn}} package is loaded. The required width of the + note column is calculated with + \DescRef{typearea-experts.cmd.AfterCalculatingTypearea}% + \IndexPackage{typearea}\IndexCmd{AfterCalculatingTypearea} after any + recalculation\textnote{type area with + \hyperref[cha:typearea]{\Package{typearea}}}% + \IndexPackage{typearea} of the type area. It should be one third of the type + area minus the distance between the main text and the note column. % + + With this information, we define the new note column. For the positions, we + use a simple dimension expression. Note that \Length{oddsidemargin} is not + the total left margin but for historical reasons the left margin minus + 1\Unit{inch}. So we have to add this value. + + This concludes the definition. Note that the note column would currently be + placed inside the type area. This means that the note column would overwrite + the text. \begin{lstcode} \begin{document} - \title{Kommentar zum GüdaVaS} + \title{Commentary on the SCRACH} \author{Professor R. O. Tenase} - \date{11.\,11.~2011} + \date{11/11/2011} \maketitle \tableofcontents - \section{Vormerkung} - Das GüdaVaS ist ohne jeden Zweifel das wichtigste - Gesetz, das in Spaßmanien in den letzten eintausend - Jahren verabschiedet wurde. Die erste Lesung fand - bereits am 11.\,11.~1111 im obersten spaßmanischen - Kongress statt, wurde aber vom damaligen Spaßvesier - abgelehnt. Erst nach Umwandlung der spaßmanischen, - aberwitzigen Monarchie in eine repräsentative, - witzige Monarchie durch W. Itzbold, - den Urkomischen, am 9.\,9.~1999 war der Weg für - dieses Gesetz endlich frei. + \section{Preamble} + The SCRACH is without doubt the most important law + on the manners of humour that has been passed in + the last thousand years. The first reading took + place on 11/11/1111 in the Supreme Manic Fun + Congress, but the law was rejected by the Vizier + of Fun. Only after the ludicrous, Manic Fun + monarchy was transformed into a representative, + witty monarchy by W. Itzbold, on 9/9/1999 was + the way finally clear for this law. \end{lstcode} - Because the text area has not been reduced\textnote{Attention!}, the - preamble is output with the whole width of the typing area. To test this, - you can temporarily add: + Because\textnote{Attention!} the text area was not reduced, the preamble is + output extending over the whole width of the type area. To test this, you + can temporarily add: \begin{lstcode} \end{document} \end{lstcode} \end{Example} % -Until now, the example does not give any answer to the question, how the text -of the comments will be printed with a smaller width. You will find this in -the continuation of the example below.% +In the example, the question of how the text for the commentary can be set in +a narrower column remains unresolved. You will discover how to do this by +continuing the example below.% +% +%\begin{table}% Umbruchoptimierung: Tabelle hinter das Beispiel verschoben +\begin{desclist} + \desccaption{% +% \caption[Available settings for declaring note columns]{% + Available settings for declaring note columns% +% }% + \label{tab:scrlayer-notecolumn.note.column.options}% + }{% + Available settings for declaring note columns + (\emph{continued})% + }% +% \begin{desctabular} + \entry{\OptionVName{font}{font attribute}}{% + The font attributes of the note column set with + \DescRef{\LabelBase.cmd.setkomafont}. For possible values, refer to + \autoref{sec:maincls.textmarkup}, + \DescPageRef{maincls.cmd.setkomafont}.\par% + Default: \emph{empty}% + }% + \entry{\Option{marginpar}}{% + Sets \Option{position} and \Option{width} to correspond to the marginal + note column of \DescRef{maincls.cmd.marginpar}. Switching between + \Macro{reversemarginpar}\IndexCmd{reversemarginpar} and + \Macro{normalmarginpar}\IndexCmd{normalmarginpar} is only considered at + the end of the page when the note column is output. Note that this + option does not expect or allow any value.\par% + Default: \emph{yes}% + }% + \entry{\Option{normalmarginpar}}{% + Sets \Option{position} and \Option{width} to use the normal marginal + note column and ignore \Macro{reversemarginpar} and + \Macro{normalmarginpar}. Note that this option does not expect or allow + a value.\par% + Default: \emph{no}% + }% + \entry{\OptionVName{position}{offset}}{% + Sets the horizontal offset of the note column from the left edge of the + paper. The \PName{offset} can be a complex expression as long as it is + fully expandable and expands to a length or a dimensional expression at + the time the note column is output. See \cite[section~3.5]{manual:eTeX} + for more information about dimensional expressions.\par% + Default: \emph{through the \Option{marginpar} option}% + }% + \entry{\Option{reversemarginpar}}{% + Sets \Option{position} and \Option{width} to use the reverse marginal + note column of \DescRef{maincls.cmd.marginpar} with the + \Macro{reversemarginpar} setting. Note that this option does not expect + or allow a value.\par% + Default: \emph{no}% + }% + \entry{\OptionVName{width}{length}}{% + Sets the width of the note column. The \PName{length} can be a complex + expression as long as it is fully expandable and expands to a length or + a dimensional expression at the time the note column is output. See + \cite[section~3.5]{manual:eTeX} for more information about dimensional + expressions.\par% + Default: \emph{through the \Option{marginpar} option}% + }% +% \end{desctabular} +%\end{table} +\end{desclist} \EndIndexGroup \section{Making a Note} \seclabel{makenote} -After having declared a note column, we can make notes for this column. But -these notes will not be output immediately. Instead of this, they are written -into a helper file with extension ``\File{.slnc}''. If you want to know the -exactly workout: First they are written to the \File{aux}-file and while -reading the \File{aux}-file inside of \Macro{end}\PParameter{document} they -will be copied to the \File{slnc}-file. Thereby setting of -\Macro{nofiles}\IndexCmd{nofiles} will be respected. At the next \LaTeX{} run, -the helper file will be read step by step depending on the progress of the -document and at the end of the page the note will be output. - -But you should note\textnote{Attention!} that note columns are output only in -pages with a page style of package -\Package{scrlayer}\IndexPackage{scrlayer}. This package will be loaded by -\Package{scrlayer-notecolumn} automatically and by default provides only one -page style, \PageStyle{empty}\IndexPagestyle{empty}. Usage of additional -package \Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} is -recommended, if you need more page styles. +After you declare a note column, you can create notes for this column. But +these notes are not be output immediately. Initially, they are written to an +auxiliary file with extension ``\File{.slnc}''. Specifically, they are first +written to the \File{aux}-file and, when the \File{aux}-file is read inside +\Macro{end}\PParameter{document}, they are copied to the \File{slnc}-file. If +necessary, the \Macro{nofiles}\IndexCmd{nofiles} setting is also taken into +account. At the next \LaTeX{} run, this auxiliary file will be read piece by +piece, according to the progress of the document, and at the end of the page +the notes for that page will be output. + +Note\textnote{Attention!}, however, that note columns are output only on pages +whose page style is based on the \Package{scrlayer}\IndexPackage{scrlayer} +package. This package is loaded automatically by \Package{scrlayer-notecolumn} +and by default provides only the \PageStyle{empty}\IndexPagestyle{empty} page +style. If you need additional page styles, the +\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} package is +recommended. \begin{Declaration} - \Macro{makenote}\OParameter{note column name}\Parameter{note}\\ - \Macro{makenote*}\OParameter{note column name}\Parameter{note}\\ + \Macro{makenote}\OParameter{note-column name}\Parameter{note}\\ + \Macro{makenote*}\OParameter{note-column name}\Parameter{note}\\ \end{Declaration} -This command may be used to make a new \PName{note}. The current vertical -position is used as the vertical position of the start of the -\PName{note}. The horizontal position depends only on the defined position of -the note column. To work correct, the package needs +You can use this command to make a new \PName{note}. The current vertical +position is used as the vertical position for the start of the \PName{note}. +The horizontal position for the note results from the defined position of the +note column. To work correctly, the package relies on \Macro{pdfsavepos}\IndexCmd{pdfsavepos}, \Macro{pdflastypos}\IndexCmd{pdflastypos}, and -\Macro{pdfpageheight}\IndexLength{pdfpageheight}. Without these primitives -\Package{scrlayer-notecolumn} cannot be used. The primitives should act -exactly as they would using PDF\TeX. +\Macro{pdfpageheight}\IndexLength{pdfpageheight} or their equivalent in newer +Lua\TeX{} versions. Without these commands, \Package{scrlayer-notecolumn} will +not work. The primitives should act exactly as they would using pdf\TeX. -However, if the package recognises a collision\textnote{collision avoidance} -with the output of a former \PName{note}, then the new \PName{note} will be -delayed until the end of the former \PName{note}. If the \PName{note} does not -fit into the page\textnote{page break}\Index{page>break}, it will be moved at -whole or only at part to the next page. +However, if the package detects a collision\textnote{collision avoidance} with +a previous \PName{note} in the same note column, the new \PName{note} is moved +below that earlier \PName{note}. If the \PName{note} does not fit on the +page\textnote{page break}\Index{page>break}, it will be moved completely or +partially to the next page. The optional argument \PName{note column name} determines which note column -should be used for the \PName{note}. The predefined note column -\PValue{marginpar} is used, if the optional argument is omitted.% +should be used for the \PName{note}. If the optional argument is omitted, the +default note column \PValue{marginpar} is used.% \begin{Example} - Let's add a commented section into the example of the previous section. The - section itself is put into the note column: + Let's add a commented paragraph to the example of the previous section. The + paragraph itself should be placed in the newly defined note column: \begin{lstcode} - \section{Analyse} + \section{Analysis} \begin{addmargin}[0pt]{.333\textwidth} \makenote[paragraphs]{% \protect\begin{contract} \protect\Clause{% - title={Kein Witz ohne Publikum}% + title={No Joke without an Audience}% } - Ein Witz kann nur dort witzig sein, wo er - auf ein Publikum trifft. + A joke can only be funny if is has an + audience. \protect\end{contract}% } - Dies ist eine der zentralsten Aussagen des - Gesetzes. Sie ist derart elementar, dass es - durchaus angebracht ist, sich vor der Weisheit - der Verfasser zu verbeugen. + This is one of the most central statements of + the law. It is so fundamental that it is quite + appropriate to bow to the wisdom of the authors. \end{lstcode} - Environment - \DescRef{maincls.env.addmargin}\IndexEnv{addmargin}\textnote{column - width by \DescRef{maincls.env.addmargin}}, which is described in - \autoref{sec:maincls.lists}, \DescPageRef{maincls.env.addmargin}, is - used to reduce the width of the main text by the width of the section - column. - - Here you can see one of the few problems of using - \Macro{makenote}. Because the mandatory argument will be written into a - helper file, commands\textnote{fragile commands} inside this argument - unfortunately can \emph{break}. To avoid this, it is recommended to use - \Macro{protect} in front of all commands that should not expand while - writing the helper file. Otherwise using a command inside this argument - could result in an error message. - - In principle you could finish this example already with: + The \DescRef{maincls.env.addmargin}\IndexEnv{addmargin}% + \textnote{column width with \DescRef{maincls.env.addmargin}} environment, + which is described in \autoref{sec:maincls.lists}, + \DescPageRef{maincls.env.addmargin}, is used to reduce the width of the main + text by the width of the column for the paragraphs. + + Here you can see one of the few problems of using \Macro{makenote}. Because + the mandatory argument is written to an auxiliary file, + commands\textnote{fragile commands} inside this argument can, unfortunately, + \emph{break}. To avoid this, you should use \Macro{protect} in front of all + commands that should not expand when written to the auxiliary file. + Otherwise, using a command inside this argument could result in error + messages. + + In principle you could now finish this example with \begin{lstcode} \end{addmargin} \end{document} \end{lstcode} - to see a first result. + to see a preliminary result. \end{Example} -If you'll test this example, you will see that the \PName{paragraphs} column -is longer than the comment. If you would\textnote{Attention!} add one more -paragraph with one more section and comment, you may have the problem, that -the new command will be put immediately after the comment above and not after -the section. So the new section would move away from the corresponding -comment. Next we will get a solution of this problem. - -The\ChangedAt{v0.1.2583}{\Package{scrlayer-notecolumn}} problem with breaking -commands, that has been mentioned in the example above, does not occur with -the star variant \Macro{makenote*}. Is uses \Macro{detokenize} to avoid -expansion of commands. But this means also that you should not use commands, -which change their definition inside the document, in the \PName{note}.% +If you test this example, you will see that the column for the legal text is +longer than that of the commentary. If\textnote{Attention!} you add another +section with another paragraph, you may encounter the problem that the +commentary will not continue below the legal text but immediately after the +previous comment. Next you will find a solution to this problem. + +The\ChangedAt{v0.1.2583}{\Package{scrlayer-notecolumn}} problem with fragile +commands mentioned in the example above does not occur with the starred +variant\important{\Macro{makenote*}}. It uses \Macro{detokenize} to prevent +the expansion of commands. But this also means that you should not use +commands in the \PName{note} that change their definition within the +document.% \EndIndexGroup @@ -469,105 +490,102 @@ which change their definition inside the document, in the \PName{note}.% \Macro{syncwithnotecolumn}\OParameter{note column name} \end{Declaration} This command adds a -synchronisation\textnote{synchronisation}\Index{synchronisation} point into -the note column and into the main text of the document. Whenever a -synchronisation point is found while output of a note column or the main text, -a mark will be generated that consists of the current page and the current -vertical position. - -Together with the generation of synchronisation points it is recognised -whether a mark has been set into the note column or the main text while the -previous \LaTeX{} run. If so, the values will be compared. If the mark of the -note column is lower at the current page or on a later page, the main text -will be moved down to the position of the mark. - -It is recommended to use synchronisation points\textnote{Note!} not inside -paragraphs of the main text but only between paragraphs. If you use +synchronisation\textnote{synchronisation}\Index{synchronisation} point in a +note column and in the main text of the document. Whenever a synchronisation +point is reached during the output of a note column or the main text, a mark +will be generated that consists of the current page and the current vertical +position. + +In parallel with the generation of synchronisation points, +\Package{scrlayer-notecolumn} determines whether a mark has been set in the +note column or the main text during the previous \LaTeX{} run. If so, it +compares their values. If the mark of the note column is lower on the current +page or on a later page, the main text will be moved down to the position of +the mark. + +As a rule,\textnote{Hint!} you should not place synchronisation points within +paragraphs of the main text but only between them. If you nonetheless use \Macro{syncwithnotecolumn} inside a paragraph, the synchronisation point will be delayed until the current line has been output. This behaviour is similar -to the usage of, e.\,g., \Macro{vspace}\IndexCmd{vspace}. - -Because recognition of synchronisation points can be done first at the next -\LaTeX{} run,\textnote{several \LaTeX{} runs}, the mechanism needs at least -three \LaTeX{} runs. Because of the new synchronisation later synchronisation -points may be moved. This would result in the need of additional \LaTeX{} -runs. You should have a look at the message: ``\LaTeX{} Warning: Label(s) may -have changed. Rerun to get cross-references right.''to find out whether or not -additional \LaTeX{} runs are needed. - -If you do not use the optional argument, the predefined note column -\PValue{marginpar} will be used. Please note, an empty optional argument is -not the same as omitting the optional argument! - -You must not use\textnote{Attention!} \Macro{syncwithnotecolumn} inside a note -itself, this means inside the mandatory Argument of +to that of, e.\,g., \Macro{vspace}\IndexCmd{vspace} in this respect. + +Because synchronisation points are not recognized until the next \LaTeX{} +run\textnote{several \LaTeX{} runs}, this mechanism requires at least three +\LaTeX{} runs. Any new synchronisation may also result in shifts of later +synchronisation points, which in turn will require additional \LaTeX{} runs. +Such shifts are usually indicated by the message: ``\LaTeX{} Warning: Label(s) +may have changed. Rerun to get cross-references right.'' But reports about +undefined labels may also indicate the need for another \LaTeX{} run. + +If you omit the optional argument, the default note column \PValue{marginpar} +will be used. Note\textnote{Attention!} that an empty optional argument is not +the same as omitting the optional argument! + +You cannot use\textnote{Attention!} \Macro{syncwithnotecolumn} inside a note +itself, that is, inside the mandatory argument of \Macro{makenote}\IndexCmd{makenote}! Currently the package cannot recognise -such a mistake and would result in synchronisation point movement at each -\LaTeX{} run. So the process will never terminate. So synchronise two or more -note columns, you have to synchronise each of them with the main text. The -recommended command for this will be described next.% +such a mistake, and it causes new shifts of the synchronisation point with +each \LaTeX{} run, so the process will never terminate. To synchronise two or +more note columns, you have to synchronise each of them with the main text. +The recommended command for this is described below.% % \begin{Example} - Let's extend the example above, now by adding a synchronisation point - and one more section with one more comment: + Let's extend the example above by first adding a synchronisation point + and then another paragraph with a comment: \begin{lstcode} \syncwithnotecolumn[paragraphs]\bigskip \makenote[paragraphs]{% \protect\begin{contract} - \protect\Clause{title={Komik der Kultur}} + \protect\Clause{title={Humor of a Culture}} \setcounter{par}{0}% - Die Komik eines Witzes kann durch das - kulturelle Umfeld, in dem er erzählt wird, - bestimmt sein. + The humour of a joke can be determined by the + cultural environment in which it is told. - Die Komik eines Witzes kann durch das - kulturelle Umfeld, in dem er spielt, - bestimmt sein. + The humour of a joke can be determined by the + cultural environment in which it acts. \protect\end{contract} } - Die kulturelle Komponente eines Witzes ist - tatsächlich nicht zu vernachlässigen. Über die - politische Korrektheit der Nutzung des - kulturellen Umfeldes kann zwar trefflich - gestritten werden, nichtsdestotrotz ist die - Treffsicherheit einer solchen Komik im - entsprechenden Umfeld frappierend. Auf der - anderen Seite kann ein vermeintlicher Witz im - falschen kulturellen Umfeld auch zu einer - echten Gefahr für den Witzeerzähler werden. + The cultural component of a joke is, in fact, not + negligible. Although the political correctness of + using the cultural environment can easily be + disputed, nonetheless the accuracy of such comedy + in the appropriate environment is striking. On + the other hand, a supposed joke in the wrong + cultural environment can also be a real danger + for the joke teller. \end{lstcode} - Beside the synchronisation point a vertical distance is added by - \Macro{bigskip} to better separate the section and the corresponding - comments. - - Again\textnote{Attention}, one more potential problem is shown. Because the - note columns uses boxes, that are build and split, counters\textnote{counter - in note column} inside note columns can sometimes jitter. In the example - the first paragraph would be numbered 2 instead of 1. This can easily be - fixed by a courageous reset of the counter. - - Now, the example is almost finished. You just have to finish the - environments: + In addition to the synchronisation point, a vertical skip has been added + with \Macro{bigskip} to better distinguish each paragraph and the + corresponding comments. + + Further\textnote{Attention}, this example illustrates another potential + problem. Because the note columns uses boxes that are assembled and + disassembled, counters\textnote{counter in note column} inside note columns + can sometimes jitter. In the example, therefore, the first paragraph would + be numbered 2 instead of 1. This, however, can easily be fixed by a direct + reset of the corresponding counter. + + The example is almost complete. You just have to close the environments: \begin{lstcode} \end{addmargin} \end{document} \end{lstcode} - In fact, all other section of the law should also be commented. But let us - focus on the main purpose. + In reality, of course, all the remaining section of the law should also be + commented. But let us focus on the main purpose. \end{Example} -But stop! What, if the section in the \PName{paragraphs} -note column wouldn't fit to the last page? Would it be output on the next -pages? We will answer this question in the next paragraph.% +But stop! What if, in this example, the \PName{paragraphs} would no longer fit +on the page? Would it be printed on the next page? We will answer this +question in the next section.% \EndIndexGroup \begin{Declaration} \Macro{syncwithnotecolumns}\OParameter{list of note column names} \end{Declaration} -This command will synchronise the main text with all note columns of the -comma-separated \PName{list of note column names}. To do so, the main text -will be synchronised with the note column, that have the mark closest to the -end of the document. As a side effect the note columns will be synchronised +This command synchronises the main text with all note columns of the +comma-separated \PName{list of note column names}. The main text +will be synchronised with the note column whose mark is closest to the +end of the document. As a side effect, the note columns will be synchronised with each other. If the optional argument is omitted or empty (or begins with \Macro{relax}), @@ -575,93 +593,97 @@ synchronisation will be done with all currently declared note columns.% \EndIndexGroup -\section{Force Output of Note Columns} +\section{Forced Output of Note Columns} \seclabel{clearnotes} -Sometimes it is necessary to have not only the normal note column output but -to be able to output all notes that haven't been output already. An example -for this effort could be that large notes result in moving lots of notes to -new pages. A good occasion to force the output\textnote{force output} could be -the end of a chapter or the end of the document. +In addition to the normal output of note columns described in the previous +section, you may sometimes need to output all collected notes that have +not yet been output. This is especially useful when large notes cause more and +more notes to be moved down to new pages. A good time to force the +output\textnote{force output} is, for example, the end of a chapter or the end +of the document. \begin{Declaration} \Macro{clearnotecolumn}\OParameter{note column name} \end{Declaration} -This command can be used to force the output of all notes\textnote{delayed - notes} of a selected note column that haven't been output until the end of -the current page, but has been made in this page or previous pages. To force -the output empty pages will be generated. During the output of the delayed -notes of the selected note column, notes of other note columns are also output, -but only as long as there are still delayed notes of the selected note column. - -During the output of the delayed notes, notes may be output by mistake that -have been placed to one of the inserted empty pages in the previous \LaTeX{} -run. This will be solved automatically by one of the next \LaTeX{} -runs. You can realise such movement of notes by the message: ``\LaTeX{} -Warning: Label(s) may have changed. Rerun to get cross-references right.'' - -The note column related to the output, is given by the optional -argument, \PName{note column name}. If this argument is omitted, the notes of -the predefined note column \PValue{marginpar} will be output. - -Attentive readers\textnote{forced output cs. synchronisation} will have noticed -that the forced output is something similar to the synchronisation. But if the -forced output really results in an output you will be at the start of a new -page and not just at the end of the output afterwards. Nevertheless, a -forced output terminates with less \LaTeX{} runs.% +This command prints all notes\textnote{pending notes} of a particular note +column that have not yet been output by the end of the current page but which +were created on that or a previous page. Blank pages are generated as needed +to output these pending notes. During the output of the pending notes of this +note column, notes of other note columns may also be output, but only as +necessary to output the pending notes of the specified note column. + +During the output of the pending notes, notes created in the previous \LaTeX{} +run on the pages that are now replaced by the inserted blank pages may be +output by mistake. This will be corrected automatically in one of the +subsequent \LaTeX{} runs. Such shifts are usually indicated by the message: +``\LaTeX{} Warning: Label(s) may have changed. Rerun to get cross-references +right.'' + +The note column whose pending notes are to be output is indicated by the +optional argument \PName{note column name}. If this argument is omitted, the +notes of the default note column \PValue{marginpar} will be output. + +The attentive reader\textnote{forced output vs. synchronisation} will have +noticed that the forced output of a note column is not unlike synchronisation. +But if the forced output actually results in an output, it will be at the +start of a new page and not just below the previous output. Nonetheless, a +forced output usually results in fewer \LaTeX{} runs.% \EndIndexGroup \begin{Declaration} \Macro{clearnotecolumns}\OParameter{list of note column names} \end{Declaration} -This command is similar to \DescRef{\LabelBase.cmd.clearnotecolumn} with the -difference that the optional argument is not only the name of one note column -but a comma-separated \PName{list of note column names}. It forces the output -of the notes of all these note columns. +This command is similar to \DescRef{\LabelBase.cmd.clearnotecolumn}, but the +the optional argument here can be not only the name of one note column but a +comma-separated \PName{list of note column names}. The pending notes of all +these note columns are then ouput. -If you omit the optional argument, all delayed notes of all note columns will -be output.% +If you omit the optional argument or leave it empty, all pending notes of all +note columns will be output.% \EndIndexGroup \begin{Declaration} \OptionVName{autoclearnotecolumns}{simple switch} \end{Declaration} -Usually you would like to force the output of notes whenever a document +As a rule, pending notes will always be output if a document implicitly\,---\,e.\,g. because of a \DescRef{maincls.cmd.chapter} -command\,---\,or explicitly executes \DescRef{maincls.cmd.clearpage}. Note -that this is also the case at the end of the document inside -\Macro{end}\PParameter{document}. Option \Option{autoclearnotecolumns} manages -whether or not \DescRef{maincls.cmd.clearpage} should also executes -\DescRef{\LabelBase.cmd.clearnotecolumns} without any optional argument. - -According to the author's preference the option is active by -default. But you can change this with proper values for simple switches (see -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}) at any time. - -You should note, that deactivation of the option can result in lost notes at -the end of the document. So you should insert -\DescRef{\LabelBase.cmd.clearnotecolumns} before -\Macro{end}\PParameter{document} if you deactivate the option. - -This should answer the question from the end of the last section. By default -the section would be output even if it would need the output of one more -page. But because this would be done after the end of the -\DescRef{maincls.env.addmargin} environment, the forced output could overlap -with main text after that environment. So it would be useful to either add one -more synchronisation point or to force the output explicitly immediately at -the end of the \DescRef{maincls.env.addmargin} environment. +command\,---\,or explicitly executes \DescRef{maincls.cmd.clearpage}. This is +also the case at the end of the document within +\Macro{end}\PParameter{document}. The \Option{autoclearnotecolumns} option can +be used to control whether \DescRef{\LabelBase.cmd.clearnotecolumns} should be +executed automatically without arguments when running +\DescRef{maincls.cmd.clearpage}. + +Since this is generally the desired behaviour, the option is active by +default. But you can change this with the appropriate value for a simple +switch (see \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}) +at any time. + +Note\textnote{Attention!} that disabling the automatic output of pending notes +can result in lost notes at the end of the document. So in this case you +should insert \DescRef{\LabelBase.cmd.clearnotecolumns} before +\Macro{end}\PParameter{document} fore safety's sake. + +The question from the end of the last section should now be answered. If the +paragraph is to be completely output, it had to be wrapped to the next page. +This is, of course, the default setting. However, since this would happen +after the end of the \DescRef{maincls.env.addmargin} environment, the forced +output could still overlap with subsequent text. So in the example it would +make sense to add another synchronisation point after the +\DescRef{maincls.env.addmargin} environment. The result of the example is shown in \autoref{fig:scrlayer-notecolumn.example}.\iffree{}{ Only the colour has been - changed from blue into grey.} +changed from blue to grey.} \begin{figure} \KOMAoptions{captions=bottombeside}% \setcapindent{0pt}% - \begin{captionbeside}[{An example page to the example of - \autoref{cha:scrlayer-notecolumn}}]{An example page to the example of + \begin{captionbeside}[{A sample page for the example in + \autoref{cha:scrlayer-notecolumn}}]{A sample page for the example in this chapter\label{fig:scrlayer-notecolumn.example}}[l] \frame{\includegraphics[width=.5\textwidth,keepaspectratio]% {scrlayer-notecolumn-example}} diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-scrpage-experts.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-scrpage-experts.tex index fb3282f1d70..c9cdc98c8aa 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-scrpage-experts.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-scrpage-experts.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrlayer-scrpage-experts.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2013-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrlayer-scrpage-experts.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2013-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -44,48 +44,51 @@ % ============================================================================ \KOMAProvidesFile{scrlayer-scrpage-experts.tex}% - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (chapter: scrlayer-scrpage-experts)] -\translator{Markus Kohm} +\translator{Markus Kohm\and Karl Hagen} -% Date version of the translated file: 2015-03-31 +% Date version of the translated file: 2018-01-31 \chapter[{Additional Features of \Package{scrlayer-scrpage}}] {Additional Features\ChangedAt{v3.12}{\Package{scrlayer-scrpage}} with - package \Package{scrlayer-scrpage}} + the \Package{scrlayer-scrpage} package} \labelbase{scrlayer-scrpage-experts} % \BeginIndexGroup \BeginIndex{Package}{scrlayer-scrpage}% -Package \Package{scrlayer-scrpage} provides features that have not been -described in \autoref{cha:scrlayer-scrpage} of this \iffree{user - guide}{book}'s \autoref{part:forAuthors}. In general, the average user will -not need those extensions and some of them are only provided for -compatibility with \Package{scrpage2}. +The \Package{scrlayer-scrpage} package offers many features beyond what has +been described in \autoref{cha:scrlayer-scrpage} of \autoref{part:forAuthors} +of this \iffree{guide}{book}. However, the average user will not normally need +these extensions, and some of them are only provided for compatibility with +\Package{scrpage2}. The documentation here in \autoref{part:forExperts} serves +to deepen and broaded your knowledge, and its mastery goes beyond basic +skills. -\LoadCommonFile{pagestylemanipulation}% \section{Manipulation of Defined Page Styles} +\LoadCommonFile{pagestylemanipulation}% \section{Manipulating Defined Page Styles} -\section{Definition of new Pairs of Page Styles} +\section{Defining New Pairs of Page Styles} \seclabel{pagestyle.pairs} -In \autoref{sec:scrlayer-scrpage.predefined.pagestyles} the page styles -\PageStyle{scrheadings} and \PageStyle{plain.scrheadings} have been -described. These can be seen as a pair of page styles, with -\PageStyle{scrheadings} being the main page style with a running head and -\PageStyle{plain.scrheadings} being the corresponding \PageStyle{plain} page -style without running head but generally with pagination. Additionally to the -configuration of these page styles, \Package{scrlayer-scrpage} provides also -the feature of defining new such pairs of page styles. Thereby the name of the -main page style, e.\,g., \PageStyle{scrheadings}, can be seen as the name of the -pair of page styles. - -Most users will not need more than the predefined pair -\PageStyle{scrheadings}. So the commands of this section may be understood as -an addition for special cases. And as each such case is very special, -this section also lacks of handsome examples. Nevertheless, if the support -will show me a real nice example in the future, I perhaps could use it in -the future. However, I'm almost sure that all such cases could also be -solved using the predefined pair only. +The two page styles \PageStyle{scrheadings} and \PageStyle{plain.scrheadings} +were described in \autoref{sec:scrlayer-scrpage.predefined.pagestyles}. You +can view them as a kind of pair, with \PageStyle{scrheadings} intended as the +main page style for a running head and \PageStyle{plain.scrheadings} the +corresponding \PageStyle{plain} page style without a running head but +generally with pagination. In addition to configuring this predefined pair, +\Package{scrlayer-scrpage} also lets you define additional pairs of page +styles. The name of the main page style, for example \PageStyle{scrheadings}, +also serves as the name of the page-style pair. + +\iffree{ + The vast majority of users will not need more than the one predefined + page-style pair, \PageStyle{scrheadings}. So the commands documented in this + section are therefore extensions for special cases. Since I have not come + across any suitable applications while writing this manual, there are no + detailed examples. Should I ever run across a particularly nice application + while providing support, I will happily include it in future versions. At + the same time, however, I'm virtually certain that all such cases could also + be solved using the predefined pair only.}{} \begin{Declaration} \Macro{defpairofpagestyles}% @@ -97,54 +100,58 @@ solved using the predefined pair only. \Macro{providepairofpagestyles}% \OParameter{parent pair}\Parameter{name}\Parameter{definition} \end{Declaration} -With these commands you may define pairs of page styles similar to -\PageStyle{scrheadings} and \PageStyle{plain.scrheadings}. Thereby -\PName{name} is the name of the main page style that is similar to -\PageStyle{scrheadings}. The name of the corresponding \PageStyle{plain} page -style will be prefixed by \PValue{plain.} automatically. So \PName{name} is -not only the name of the pair of page styles, but also the name of the main -page style of that pair, while \PValue{plain.}\PName{name} is the name of the -\PageStyle{plain} page style of this pair. - -If the optional argument \PName{parent pair} is given, the settings of the -pair of page styles with that name are the initial settings of the new pair of -page styles. So the new pair inherits the configuration of the \PName{parent - pair}. - -Reading \autoref{sec:scrlayer-scrpage.predefined.pagestyles} might have -created the impression that the described commands are related to -\PageStyle{scrheadings} and \PageStyle{plain.scrheadings} only. However, if -there exist more pairs of page styles, these commands are related to the pair -that has been activated last. In fact, this is the case for \DescRef{scrlayer-scrpage.cmd.lehead}, -\DescRef{scrlayer-scrpage.cmd.cehead}, \DescRef{scrlayer-scrpage.cmd.rehead}, \DescRef{scrlayer-scrpage.cmd.lohead}, \DescRef{scrlayer-scrpage.cmd.cohead}, -\DescRef{scrlayer-scrpage.cmd.rohead}, \DescRef{scrlayer-scrpage.cmd.lefoot}, \DescRef{scrlayer-scrpage.cmd.cefoot}, \DescRef{scrlayer-scrpage.cmd.refoot}, -\DescRef{scrlayer-scrpage.cmd.lofoot}, \DescRef{scrlayer-scrpage.cmd.cofoot}, \DescRef{scrlayer-scrpage.cmd.rofoot}, \DescRef{scrlayer-scrpage.cmd.ihead}, \DescRef{scrlayer-scrpage.cmd.chead}, -\DescRef{scrlayer-scrpage.cmd.ohead}, \DescRef{scrlayer-scrpage.cmd.ifoot}, \DescRef{scrlayer-scrpage.cmd.cfoot}, and \DescRef{scrlayer-scrpage.cmd.ofoot} of -\autoref{sec:scrlayer-scrpage.predefined.pagestyles}. - -All those commands and the below described commands -\DescRef{\LabelBase.cmd.clearmainofpairofpagestyles}, \DescRef{\LabelBase.cmd.clearplainofpairofpagestyles}, and -\DescRef{\LabelBase.cmd.clearpairofpagestyles} are also designed to be used inside the argument -\PName{definition}. In that case, they are a kind of default configuration of -the pair of page styles that is executed each time the pair will be -activated. A pair of page styles is activated, if one of the page styles of -the pair will be activated, which is mostly done by using +You can use these commands to define pairs of page styles similar to +\PageStyle{scrheadings} and \PageStyle{plain.scrheadings}, where \PName{name} +is the name of the main page style corresponding to \PageStyle{scrheadings}. +The name of the equivalent \PageStyle{plain} page style will be prefixed by +\PValue{plain.} automatically. So \PName{name} is not only the name of the +pair of page styles, but also the name of the main page style of that pair, +while \PValue{plain.}\PName{name} is the name of the \PageStyle{plain} page +style of this pair. + +If you provide the optional \PName{parent pair} argument, this is the name of +a page-style pair whose settings are used to initialise the new page-style +pair. So the new pair inherits the configuration of the \PName{parent pair}. + +Although \autoref{sec:scrlayer-scrpage.predefined.pagestyles} might have +created the impression that the commands described there apply only to +\PageStyle{scrheadings} and \PageStyle{plain.scrheadings} only, this is true +only so long as those two page styles are the only defined page-style pair. As +soon as there are multiple page-style pairs, +\DescRef{scrlayer-scrpage.cmd.lehead}, \DescRef{scrlayer-scrpage.cmd.cehead}, +\DescRef{scrlayer-scrpage.cmd.rehead}, \DescRef{scrlayer-scrpage.cmd.lohead}, +\DescRef{scrlayer-scrpage.cmd.cohead}, \DescRef{scrlayer-scrpage.cmd.rohead}, +\DescRef{scrlayer-scrpage.cmd.lefoot}, \DescRef{scrlayer-scrpage.cmd.cefoot}, +\DescRef{scrlayer-scrpage.cmd.refoot}, \DescRef{scrlayer-scrpage.cmd.lofoot}, +\DescRef{scrlayer-scrpage.cmd.cofoot}, \DescRef{scrlayer-scrpage.cmd.rofoot}, +\DescRef{scrlayer-scrpage.cmd.ihead}, \DescRef{scrlayer-scrpage.cmd.chead}, +\DescRef{scrlayer-scrpage.cmd.ohead}, \DescRef{scrlayer-scrpage.cmd.ifoot}, +\DescRef{scrlayer-scrpage.cmd.cfoot}, and \DescRef{scrlayer-scrpage.cmd.ofoot} +all refer to page-style pair that was most recently activated. + +In addition to those eighteen commands mentioned above, the three commands +described below, \DescRef{\LabelBase.cmd.clearmainofpairofpagestyles}, +\DescRef{\LabelBase.cmd.clearplainofpairofpagestyles}, and +\DescRef{\LabelBase.cmd.clearpairofpagestyles}, are designed to be used inside +the \PName{definition} argument. In this case, they represent a kind of +default configuration of the page-style pair that is executed each time the +pair is activated. You activate a page-style pair by activating either one two +page styles in the pair. Typically, you do so with \DescRef{maincls.cmd.pagestyle}\IndexCmd{pagestyle}. -Please note that the commands of -\autoref{sec:scrlayer-scrpage.pagestyle.content} are for general -purpose. Therefore, they are related to every page style that has been defined -using \Package{scrlayer-scrpage}. - -Whereas \Macro{defpairofpagestyles} will define a pair no matter if the -corresponding page styles are already defined, \Macro{newpairofpagestyles} and -\Macro{providepairofpagestyles} will define the pair only, if the page styles -are currently undefined. If at least one of the page styles is already -defined, the new definition of \Macro{providepairofpagestyles} will be -ignored, but usage of \Macro{newpairofpagestyles} would result in an error -message. To redefine already existing pairs of page styles you may use -\Macro{renewpairofpagestyles}. With this an error would be thrown, if at least -one of the page styles of the pair does not already exist.% +Note that the commands of \autoref{sec:scrlayer-scrpage.pagestyle.content} on +\autopageref{sec:scrlayer-scrpage.pagestyle.content} are general in nature and +apply to all page styles defined with \Package{scrlayer-scrpage}. + +Although \Macro{defpairofpagestyles} defines a page-style pair regardless of +whether the corresponding page styles already exist, +\Macro{newpairofpagestyles} and \Macro{providepairofpagestyles} do so only if +the page styles are currently undefined. If at least one of the page styles is +already defined, the new definition of \Macro{providepairofpagestyles} will be +ignored, whereas using \Macro{newpairofpagestyles} results in an error +message. To redefine existing page-style pairs, you can use +\Macro{renewpairofpagestyles}. With this an is thrown if either one of the two +page styles of the pair does not already exist.% \EndIndexGroup @@ -153,333 +160,52 @@ one of the page styles of the pair does not already exist.% \Macro{clearplainofpairofpagestyles}% \Macro{clearpairofpagestyles} \end{Declaration} -Command \Macro{clearmainofpairofpagestyles} will configure the main page style -of the lastly activated pair of page styles to be empty. In contrast to this -\Macro{clearplainofpairofpagestyles} will configure the \PageStyle{plain} page -style of the lastly activated pair of page styles to be empty. Last but not -least \Macro{clearpairofpagestyle} will configure both page styles of the -lastly activated pair of page styles to be empty. - -But please note\textnote{Attention!} that none of these commands will remove -the definitions of argument \PName{definition} that has been used when -defining the pair of page styles (see above). So if you activate the pair of -page styles again, those definitions will be used again! - -These commands may be used inside of \PName{definition} themselves. But you -may use them outside the definition of a pair of page styles too. In this case -they are related to the lastly activated pair of page styles. - -\BeginIndex{Cmd}{clearscrheadings}% -\BeginIndex{Cmd}{clearscrplain}% -\BeginIndex{Cmd}{clearscrheadfoot}% -The commands \Macro{clearscrheadings}, \Macro{clearscrplain}, and -\Macro{clearscrheadfoot} are aliases for these commands provided only for -compatibility with \Package{scrpage2}. Nevertheless, they are deprecated and -should not be used.% -% +The \Macro{clearmainofpairofpagestyles} command sets the main page style of +the most recently activated page-style pair to be empty. In contrast, the +\Macro{clearplainofpairofpagestyles} command sets the \PageStyle{plain} page +style of the active page-style pair to be empty. Finally, +\Macro{clearpairofpagestyle} sets both page styles of the activate pair to be +empty. + +But note\textnote{Attention!} that none of these commands removes the +definitions of the \PName{definition} argument that was specified when +defining the page-style pair (see above). So if you activate the pair of page +styles again, those definitions will be used again! + +You can use these commands inside the \PName{definition} of the page-style +pair explained above. But you can also use them outside this definition. In +this case, they refer to the most recently activated page-style pair.% \EndIndexGroup -\section{Definition of Simple Page Styles with Three Parts in Head and Foot } -\seclabel{pagestyle.triple} - -Beside predefined page styles and the definition of new pairs of page styles, -package \Package{scrlayer-scrpage} also provides the definition of page styles -with three parts in head and foot. But this user interface exists for -compatibility with \Package{scrpage2} only. However, it has been extended -beyond the functionality of \Package{scrpage2} to provide a more consistent -set of commands. Nevertheless, for new documents it is recommended to instead -use the advanced features described in the previous section. - -\begin{Declaration} - \Macro{deftriplepagestyle}\Parameter{name of the page style}% - \OParameter{thickness of the outer line}% - \OParameter{thickness of the inner line}% - \Parameter{inner head element}% - \Parameter{centre head element}% - \Parameter{outer head element}% - \Parameter{inner foot element}% - \Parameter{centre foot element}% - \Parameter{outer foot element}% - \Macro{newtriplepagestyle}\Parameter{name of the page style}% - \OParameter{thickness of the outer linen}% - \OParameter{thickness of the inner linen}% - \Parameter{inner head element}% - \Parameter{centre head element}% - \Parameter{outer head element}% - \Parameter{inner foot element}% - \Parameter{centre foot element}% - \Parameter{outer foot element}% - \Macro{renewtriplepagestyle}\Parameter{name of the page style}% - \OParameter{thickness of the outer line}% - \OParameter{thickness of the inner line}% - \Parameter{inner head element}% - \Parameter{centre head element}% - \Parameter{outer head element}% - \Parameter{inner foot element}% - \Parameter{centre foot element}% - \Parameter{outer foot element}% - \Macro{providetriplepagestyle}\Parameter{name of the page style}% - \OParameter{thickness of the outer line}% - \OParameter{thickness of the inner line}% - \Parameter{inner head element}% - \Parameter{centre head element}% - \Parameter{outer head element}% - \Parameter{inner foot element}% - \Parameter{centre foot element}% - \Parameter{outer foot element} -\end{Declaration} -With these commands you can define a single page style, whose head and foot -are parted into three elements: an inner element, a centre element, and an -outer element. The contents of the elements are stated via three mandatory -arguments for the head and three mandatory arguments for the foot. - -Each of the two inner elements will be printed right aligned on left pages and -left aligned on right pages. The centre elements will be printed centred in -the head respectively foot of left and right pages. Each of the two outer -elements will be printed left aligned on left pages and right aligned on right -pages. - -Please note once again:\textnote{Attention!} There are only right pages in -single side layout! - -The two optional arguments can be used to activate horizontal lines in the -head and foot of the page style. To do so, you put the wanted thickness of the -line as an optional argument. The first optional argument is the -\PName{thickness of the outer line} in both, the page head and footer. In the -page head it will be printed above the head contents. In the page footer it -will be printed below the foot contents. The second optional argument is the -\PName{thickness of the inner line}. This will be printed below the page head -and additionally above the page footer. If you have only one optional -argument, this is the \PName{thickness of the inner line}. In this case no -outer line will be printed. And if you omit both optional arguments, both -lines will be omitted. - -Please note\textnote{Attention!}, an empty optional argument is not the same -like omitting the optional argument! Empty optional arguments are not allowed -in this case. But you may use simple dimension expressions as explained for -\KOMAScript{} option \DescRef{scrlayer-scrpage.option.headwidth} (see -\autoref{sec:scrlayer-scrpage.pagestyle.content}, -\DescPageRef{scrlayer-scrpage.option.headwidth}) for the optional -arguments. - -\hyperref[fig:scrlayer-scrpage.triplepagestyle]% -{Figure~\ref*{fig:scrlayer-scrpage.triplepagestyle}} shows a sketch for the -interpretation of the arguments on a schematic double page. Thereby -``\texttt{outer}'', ``\texttt{inner}'', and ``\texttt{centre}'' are example -contents. The corresponding arrows illustrate the expansion of those -contents. The \iffree{coloured }{}texts inside the pages are only the names of -the arguments of these commands. The related arrows \iffree{in the same colour -}{} point to the corresponding elements of the page. - -\begin{figure} - \centering - \begin{picture}(\textwidth,80mm) - \put(0,50mm){% - %\ - \begin{picture}(\textwidth,30mm)(0,-10mm) - \thinlines - \small - % linke Seite - \put(0,20mm){\line(1,0){.49\textwidth}}% - \put(0,0){\line(0,1){20mm}}% - \multiput(0,0)(0,-1mm){10}{\line(0,-1){.5mm}}% - \put(.49\textwidth,5mm){\line(0,1){15mm}}% - \put(.05\textwidth,15mm){\thicklines\line(1,0){.415\textwidth}}% - \put(.05\textwidth,10mm){\makebox(0em,5mm)[l]{\slshape outer\strut$\longrightarrow$}}% - \put(.465\textwidth,10mm){\makebox(0em,5mm)[r]{\slshape $\longleftarrow$inner\strut}}% - \put(.2575\textwidth,10mm){\makebox(0em,5mm)[c]{\slshape $\longleftarrow$centre\strut$\longrightarrow$}}% - \put(.05\textwidth,10mm){\thicklines\line(1,0){.415\textwidth}}% - % rechte Seite - \put(0.51\textwidth,20mm){\line(1,0){.49\textwidth}}% - \put(0.51\textwidth,5mm){\line(0,1){15mm}}% - \multiput(\textwidth,0)(0,-1mm){10}{\line(0,-1){.5mm}}% - \put(\textwidth,0mm){\line(0,1){20mm}}% - \put(.535\textwidth,15mm){\thicklines\line(1,0){.415\textwidth}}% - \put(.535\textwidth,10mm){\makebox(0em,5mm)[l]{\slshape inner\strut$\longrightarrow$}}% - \put(.95\textwidth,10mm){\makebox(0em,5mm)[r]{\slshape $\longleftarrow$outer\strut}}% - \put(.7425\textwidth,10mm){\makebox(0em,5mm)[c]{\slshape $\longleftarrow$centre\strut$\longrightarrow$}}% - \put(.535\textwidth,10mm){\thicklines\line(1,0){.415\textwidth}}% - % commands for both pages - \iffree{\color{red}}{}% - \put(.5\textwidth,0){\makebox(0,\baselineskip)[c]{\PName{inner head element}}}% - \put(.5\textwidth,-5mm){\makebox(0,\baselineskip)[c]{\PName{centre - head element}}}% - \put(.5\textwidth,-10mm){\makebox(0,\baselineskip)[c]{\PName{outer - head element}}}% - \put(\dimexpr.5\textwidth-2em,.5\baselineskip){% - \put(-1.5em,.5\baselineskip){\vector(0,1){7mm}}% - \put(-3.5em,-1\baselineskip){\line(-1,0){\dimexpr .25\textwidth-6.5em\relax}}% - \put(-\dimexpr - .25\textwidth-3em\relax,-1\baselineskip){\vector(0,1){\dimexpr - 7mm+1.5\baselineskip\relax}} - \put(-3.25em,-2.25\baselineskip){\line(-1,0){\dimexpr .45\textwidth-8em\relax}}% - \put(-\dimexpr - .45\textwidth-4.75em\relax,-2.25\baselineskip){\vector(0,1){\dimexpr - 7mm+2.75\baselineskip\relax}} - }% - \put(\dimexpr.5\textwidth+2em,.5\baselineskip){% - \put(1.5em,.5\baselineskip){\vector(0,1){7mm}}% - \put(3.5em,-1\baselineskip){\line(1,0){\dimexpr .25\textwidth-6.5em\relax}} - \put(\dimexpr - .25\textwidth-3em\relax,-1\baselineskip){\vector(0,1){\dimexpr - 7mm+1.5\baselineskip\relax}} - \put(3.25em,-2.25\baselineskip){\line(1,0){\dimexpr .45\textwidth-8em\relax}} - \put(\dimexpr - .45\textwidth-4.75em\relax,-2.25\baselineskip){\vector(0,1){\dimexpr - 7mm+2.75\baselineskip\relax}} - }% - \end{picture} - % - }% - \put(0,0){% - \begin{picture}(\textwidth,30mm) - \thinlines - \small - % linke Seite - \put(0,0){\line(1,0){.49\textwidth}}% - \put(0,0){\line(0,1){20mm}}% - \multiput(0,20mm)(0,1mm){10}{\line(0,1){.5mm}}% - \put(.49\textwidth,0){\line(0,1){15mm}}% - \put(.05\textwidth,15mm){\thicklines\line(1,0){.415\textwidth}}% - \put(.05\textwidth,10mm){\makebox(0em,5mm)[l]{\slshape outer\strut$\longrightarrow$}}% - \put(.465\textwidth,10mm){\makebox(0em,5mm)[r]{\slshape $\longleftarrow$inner\strut}}% - \put(.2575\textwidth,10mm){\makebox(0em,5mm)[c]{\slshape $\longleftarrow$centre\strut$\longrightarrow$}}% - \put(.05\textwidth,10mm){\thicklines\line(1,0){.415\textwidth}}% - % rechte Seite - \put(.51\textwidth,0){\line(1,0){.49\textwidth}}% - \put(.51\textwidth,0){\line(0,1){15mm}}% - \put(\textwidth,0){\line(0,1){20mm}}% - \multiput(\textwidth,20mm)(0,1mm){10}{\line(0,1){.5mm}}% - \put(.535\textwidth,15mm){\thicklines\line(1,0){.415\textwidth}}% - \put(.535\textwidth,10mm){\makebox(0em,5mm)[l]{\slshape inner\strut$\longrightarrow$}}% - \put(.95\textwidth,10mm){\makebox(0em,5mm)[r]{\slshape $\longleftarrow$outer\strut}}% - \put(.7425\textwidth,10mm){\makebox(0em,5mm)[c]{\slshape $\longleftarrow$centre\strut$\longrightarrow$}}% - \put(.535\textwidth,10mm){\thicklines\line(1,0){.415\textwidth}}% - % commands for both pages - \iffree{\color{red}}{}% - \put(.5\textwidth,20mm){\makebox(0,\baselineskip)[c]{\PName{inner foot - element}}}% - \put(.5\textwidth,25mm){\makebox(0,\baselineskip)[c]{\PName{centre - foot element}}}% - \put(.5\textwidth,30mm){\makebox(0,\baselineskip)[c]{\PName{outer foot - element}}}% - \put(\dimexpr.5\textwidth-2em,.5\baselineskip){% - \put(-1.5em,\dimexpr 20mm-.5\baselineskip\relax){\vector(0,-1){6mm}}% - \put(-3.5em,25mm){\line(-1,0){\dimexpr .25\textwidth-6.5em\relax}}% - \put(-\dimexpr .25\textwidth-3em\relax,25mm){\vector(0,-1){\dimexpr - .5\baselineskip + 11mm\relax}}% - \put(-3em,30mm){\line(-1,0){\dimexpr .45\textwidth-7.5em\relax}}% - \put(-\dimexpr .45\textwidth-4.5em\relax,30mm){\vector(0,-1){\dimexpr - .5\baselineskip + 16mm\relax}}% - }% - \put(\dimexpr.5\textwidth+2em,.5\baselineskip){% - \put(1.5em,\dimexpr 20mm-.5\baselineskip\relax){\vector(0,-1){6mm}}% - \put(3.5em,25mm){\line(1,0){\dimexpr .25\textwidth-6.5em\relax}}% - \put(\dimexpr .25\textwidth-3em\relax,25mm){\vector(0,-1){\dimexpr - .5\baselineskip + 11mm\relax}}% - \put(3em,30mm){\line(1,0){\dimexpr .45\textwidth-7.5em\relax}}% - \put(\dimexpr .45\textwidth-4.5em\relax,30mm){\vector(0,-1){\dimexpr - .5\baselineskip + 16mm\relax}}% - }% - \end{picture} - }% - \thinlines\small\iffree{\color{blue}}{}% - \put(0.055\textwidth,45mm){\vector(0,1){25mm}}% - \put(0.945\textwidth,45mm){\vector(0,1){25mm}}% - \put(0.055\textwidth,45mm){\vector(0,-1){30mm}}% - \put(0.945\textwidth,45mm){\vector(0,-1){30mm}}% - \put(0.055\textwidth,45mm){\line(1,0){\dimexpr - .445\textwidth-7.5em\relax}}% - \put(0.945\textwidth,45mm){\line(-1,0){\dimexpr - .445\textwidth-7.5em\relax}}% - \put(0.5\textwidth,45mm){\makebox(0,0)[c]{\PName{thickness of the inner lines}}}% - \iffree{\color{green}}{}% - \put(0.025\textwidth,40mm){\line(0,1){35mm}}% - \put(0.025\textwidth,75mm){\vector(1,0){3.75mm}}% - \put(0.975\textwidth,40mm){\line(0,1){35mm}}% - \put(0.975\textwidth,40mm){\line(0,1){35mm}}% - \put(0.975\textwidth,75mm){\vector(-1,0){3.75mm}}% - \put(0.025\textwidth,40mm){\line(0,-1){30mm}}% - \put(0.025\textwidth,10mm){\vector(1,0){3.75mm}}% - \put(0.975\textwidth,40mm){\line(0,-1){30mm}}% - \put(0.975\textwidth,40mm){\line(0,-1){30mm}}% - \put(0.975\textwidth,10mm){\vector(-1,0){3.75mm}}% - \put(0.025\textwidth,40mm){\line(1,0){\dimexpr - .475\textwidth-7.5em\relax}}% - \put(0.975\textwidth,40mm){\line(-1,0){\dimexpr - .475\textwidth-7.5em\relax}}% - \put(0.5\textwidth,40mm){\makebox(0,0)[c]{\PName{thickness of the outer lines}}}% - \end{picture} - \caption[{Elements of a three parts page style}]{Schematic double page with - the elements of a tripartite page style of commands - \Macro{deftriplepagestyle}, \Macro{newtriplepagestyle}, - \Macro{providetriplepagestyle}, and \Macro{renewtriplepagestyle}} - \label{fig:scrlayer-scrpage.triplepagestyle} -\end{figure} - -Using the described commands it is not possible to draw only a single line, -e.\,g., only below the page head but not above the page footer. If you need -to do so, please consult the previous or following section. - -The length of a single element\textnote{Attention!} is not limited by the -existence of a neighbour element. So in unfortunate circumstances it can -happen that one elements overwrites a neighbour element or even both of -them. The user himself is responsible to avoid such inappropriate usage. With -automatic running heads this could, e.\,g., be done using the optional -argument of the section commands. See the manual of the document class for -more information about those commands. - -Command \Macro{deftriplepagestyle} defines a page style independent from -whether or not a page style with the same \PName{name of the page style} -already exists. In difference to this \Macro{newtriplepagestyle} and -\Macro{providetriplepagestyle} define the page style only, if the \PName{name - of the page style} is not the name of an already defined page -style. Otherwise \Macro{providepagestyle} simply does nothing, but -\Macro{newtriplepagestyle} throws an error. Command -\Macro{renewtriplepagestyle} is something like the opposite of -\Macro{newtriplepagestyle}. It throws an error, if there has not been -a page style with the \PName{name of the page style} before, and defines the -page style only, if there has been already a page style with the given name. - -\BeginIndex{Cmd}{deftripstyle}% -The command \Macro{deftriplestyle} of \Package{scrpage2} corresponds to -\Macro{deftriplepagestyle}. Because of unification reasons it has been renamed -and should not be used with it's old name any longer. Using the old name would -result in a warning message. Nevertheless, the result would be the expected -one.% -\EndIndexGroup - - -\section{Definition of Complex Page Styles} +\section{Defining Complex Page Styles} \seclabel{pagestyle.experts} -Beside predefined page styles, the definition of new pairs of page styles and -the deprecated definition of page styles with tripartite head and foot, the -package \Package{scrlayer-scrpage} additionally provides basic features to -define new page styles. All already described page style definitions of -\Package{scrlayer-scrpage} use internally these basic features. Because of the -complexity of this user interface it is recommended for advanced users only. -As all most all imaginable use cases of page styles can handled using the -features described previous section, less advanced users may skip this -section. +In addition to the predefined page styles, \Package{scrlayer-scrpage} also +provides a more basic interface for defining new page styles. The page-style +definitions discussed so far use this interface internally, as do the obsolete +commands in \autoref{sec:\LabelBase.pagestyle.triple}. +\Package{scrlayer-scrpage}. Because of its complexity, however, only advanced +users should try to use it directly. Less experienced users can already +achieve almost everything possible with this low-level interface by using the +possibilities described previously. \begin{Declaration} \Macro{defpagestyle}% - \Parameter{name}\Parameter{head specification}\Parameter{foot specification}% + \Parameter{name}\Parameter{header specification}\Parameter{footer specification}% \Macro{newpagestyle}% - \Parameter{name}\Parameter{head specification}\Parameter{foot specification}% + \Parameter{name}\Parameter{header specification}\Parameter{footer specification}% \Macro{providepagestyle}% - \Parameter{name}\Parameter{head specification}\Parameter{foot specification}% + \Parameter{name}\Parameter{header specification}\Parameter{footer specification}% \Macro{renewpagestyle}% - \Parameter{name}\Parameter{head specification}\Parameter{foot specification}% + \Parameter{name}\Parameter{header specification}\Parameter{footer specification}% \end{Declaration} -These commands can be used to define a single page style with maximum -flexibility. Thereby \PName{name} is the name of the page style that should -be defined. +You can use these commands to define a single page style with maximum +flexibility, where \PName{name} is the name of the page style that you want to +define. -The arguments \PName{head specification} and \PName{foot specification} have -identical structure: +The parameters \PName{header specification} and \PName{footer specification} +have identical structure: \begin{quote}\raggedright \texttt{% (\PName{length of the line above},\PName{thickness of the line above})\%\\ @@ -489,89 +215,89 @@ identical structure: (\PName{length of the line below},\PName{thickness of the line below})% } \end{quote} -The arguments in the round brackets are options. This means, you may omit them +The arguments in the round brackets are optional. That is, you can omit them together with the brackets. In that case, the length and thickness of the -corresponding horizontal line would be given by the \KOMAScript{} options +corresponding horizontal rules are based on the \KOMAScript{} options \DescRef{scrlayer-scrpage.option.headtopline}, \DescRef{scrlayer-scrpage.option.headsepline}, -\DescRef{scrlayer-scrpage.option.footsepline} or +\DescRef{scrlayer-scrpage.option.footsepline}, and \DescRef{scrlayer-scrpage.option.footbotline} (see \autoref{sec:scrlayer-scrpage.pagestyle.content}, \DescPageRef{scrlayer-scrpage.option.headtopline}). -All three arguments in the curly brackets are mandatory. They hold arbitrary -content specifications depending on the page and the layout settings. But for -page styles with running heads usage of +All three arguments in curly brackets are mandatory and are used depending on +the page and the layout settings. Their content can be anything you want. For +page styles with running heads, however, you should use \DescRef{scrlayer-scrpage.cmd.headmark}, \DescRef{scrlayer-scrpage.cmd.leftmark}, or -\DescRef{scrlayer-scrpage.cmd.rightmark} is recommended inside the -specification. Section numbers or section headings must not be used in the -specifications. Due to the asynchronous page building of \LaTeX, using them -could result in wrong numbers or texts in the page header or footer. - -Command \Macro{defpagestyle} defines the page style no matter if a page style -with the same \PName{name} already exists. Command \Macro{newpagestyle} would -throw an error, if such a page style already exists. In contrast to this, -\Macro{providepagestyle} simple does nothing in such a case. In contrast to -\Macro{newpagestyle} command \Macro{renewpagestyle} throws an error, if a page -style with the \PName{name} does not already exist, and therefore may be used -to redefine an existing page style. - -All these commands are based on the command -\DescRef{scrlayer.cmd.DeclarePageStyleByLayers}\IndexCmd{DeclarePageStyleByLayers} of package -\Package{scrlayer}. \hyperref[tab:scrlayer-scrpage-experts.layersperstyle]{Table~\ref*{tab:scrlayer-scrpage-experts.layersperstyle}} -shows the layers that are defined for a page style \PName{name}. More -information about layers and layer page styles can be found starting on -\autopageref{cha:scrlayer} in \autoref{cha:scrlayer} of -\autoref{part:forExperts}.% +\DescRef{scrlayer-scrpage.cmd.rightmark} inside the specification. Under no +circumstances should you directly put the number or text of a sectioning +command here. Because of the \LaTeX{}'s asynchronous page construction, the +wrong numbers or text can appear in the header or footer if you do so. + +The \Macro{defpagestyle} command defines the page style regardless of whether +it already exists or not. In contrast, \Macro{newpagestyle} throws an error if +a page style of the same \PName{name} already exists. On the other hand, +\Macro{providepagestyle} simply ignores the definition if the \PName{name} has +already been used for a page style. Conversely, \Macro{renewpagestyle} can +only redefine an existing page style. For a new \PName{name}, it throws an +error. + +All four commands are based on the +\DescRef{scrlayer.cmd.DeclarePageStyleByLayers}% +\IndexCmd{DeclarePageStyleByLayers} command of the +\hyperref[cha:scrlayer]{\Package{scrlayer}}\IndexPackage{scrlayer} package. +You can find the layers that are defined for a page style \PName{name} in +\autoref{tab:scrlayer-scrpage-experts.layersperstyle}, and more information +about layers and layer-page in \autoref{cha:scrlayer}, starting on +\autopageref{cha:scrlayer}.% \begin{table} % \KOMAoptions{captions=topbeside} % \setcapindent{0pt} % \begin{captionbeside} \caption - [{The layers \Package{scrlayer-scrpage} defines to a page style}] - {The layers \Package{scrlayer-scrpage} defines to a page style - \PName{name}% - \label{tab:scrlayer-scrpage-experts.layersperstyle}} + [{The layers \Package{scrlayer-scrpage} defines for a page style}] + {The layers \Package{scrlayer-scrpage} defines for a \PName{name} page + style\label{tab:scrlayer-scrpage-experts.layersperstyle}} % [l] \begin{tabular}{ll} \toprule Name of the layer & Meaning of the layer \\ \midrule - \PName{Name}\PValue{.head.above.line} - & horizontal line above the page head\\ - \PName{Name}\PValue{.head.odd} - & page head of odd pages in two-side layout\\ - \PName{Name}\PValue{.head.even} - & page head of even pages in two-side layout\\ - \PName{Name}\PValue{.head.oneside} - & page head in single-side layout\\ - \PName{Name}\PValue{.head.below.line} - & horizontal line below the page head\\ - \PName{Name}\PValue{.foot.above.line} - & horizontal line above the page foot\\ - \PName{Name}\PValue{.foot.odd} - & page foot of odd pages in two-side layout\\ - \PName{Name}\PValue{.foot.even} - & page foot of even pages in two-side layout\\ - \PName{Name}\PValue{.foot.oneside} - & page foot in single-side layout\\ - \PName{Name}\PValue{.foot.below.line} - & horizontal line below the page foot\\ + \PName{name}\PValue{.head.above.line} + & horizontal line above the header\\ + \PName{name}\PValue{.head.odd} + & header of odd pages in two-sided printing\\ + \PName{name}\PValue{.head.even} + & header of even pages in two-sided printing\\ + \PName{name}\PValue{.head.oneside} + & header in one-sided printing\\ + \PName{name}\PValue{.head.below.line} + & horizontal line below the header\\ + \PName{name}\PValue{.foot.above.line} + & horizontal line above the footer\\ + \PName{name}\PValue{.foot.odd} + & footer of odd pages in two-sided printing\\ + \PName{name}\PValue{.foot.even} + & footer of even pages in two-sided printing\\ + \PName{name}\PValue{.foot.oneside} + & footer in one-sided printing\\ + \PName{name}\PValue{.foot.below.line} + & horizontal line below the footer\\ \bottomrule \end{tabular} % \end{captionbeside} \end{table} \begin{Example} - Assume you want to colour the whole background of page style - \PageStyle{scrheadings}' head. Because you read the introduction to - this chapter, you know, that \PageStyle{scrheadings} last but not least is a - layer page style with, e.\,g., layers \PValue{scrheadings.head.even}, - \PValue{scrheadings.head.odd}, and \PValue{scrheadings.head.oneside}. So you - define three more layers for the backgrounds and add them at the very - beginning of the page style: + Suppose you want to set a background colour for the header of the + \PageStyle{scrheadings} page style. From the introduction to this chapter + and \autoref{tab:scrlayer-scrpage-experts.layersperstyle}, you know that + \PageStyle{scrheadings} is a layer page style that includes the layers + \PValue{scrheadings.head.even}, \PValue{scrheadings.head.odd}, and + \PValue{scrheadings.head.oneside}. You now define three more layers for + their backgrounds and add them at the beginning of the page style: \begin{lstcode} \documentclass{scrartcl} \usepackage[automark]{scrlayer-scrpage} @@ -602,13 +328,13 @@ information about layers and layer page styles can be found starting on \blinddocument \end{document} \end{lstcode} - As you can see, the example uses three layers, so the position and size of - that background layers may simply be copied from the corresponding head - layer using option \Option{clone}. This is much easier than using only one - background layer and dynamically calculate the position time by time. + As you can see, the example uses three layers so that the position and size + of the background layers could simply be copied from the corresponding + header layer using the \Option{clone} option. This is easier than using only + one background layer and dynamically calculating its position each time. - In this example the coloured background is printed using a \Macro{rule} - command. The size arguments of this \Macro{rule} are given by + The coloured background itself was created using a \Macro{rule} command. The + size arguments of this \Macro{rule} are given by \DescRef{scrlayer.cmd.layerwidth} and \DescRef{scrlayer.cmd.layerheight} which contain the current width and height of the layer itself. The optional argument of \Macro{rule} is used to move the rule down by the height of a @@ -617,27 +343,44 @@ information about layers and layer page styles can be found starting on % Instead of using new layers to colour the background in the example above, \Macro{colorbox} and \DescRef{scrlayer-scrpage.cmd.chead} could have been -used. It is recommended to build such a solution as an exercise. Another -approach could be to add the background layers one by one and just before the -contents layers. You may do this as an exercise too.% +used. You can work out a solution using this method as an exercise. Likewise, +you could have added the background layers individually just before the +corresponding content layer. You can implement this as an exercise too.% \EndIndexGroup +\section{Defining Simple Page Styles with a Tripartite Header and Footer} +\seclabel{pagestyle.triple} + +\LoadNonFree{scrlayer-scrpage-experts}{1} + +\section{Legacy Features of \Package{scrpage2}} +\seclabel{obsolete} + +\begin{Explain} + The \Package{scrlayer-scrpage} package contains some legacy features that + derive from \Package{scrpage2} and exist only to be as compatible as possible + with that package. Users only need to understand these features if they want + to edit an old document based on \Package{scrpage2}. You\textnote{Attention!} + should not use the items documented here in new documents! +\end{Explain} \begin{Declaration} \KOption{hmode}\PValue{simple switch} \end{Declaration} -Package \Package{scrpage2} outputs page heads and page foots in horizontal -mode always. In opposite to this \Package{scrlayer-scrpage} does not switch -into horizontal mode itself, but the output of horizontal material will do -so. Nevertheless, you can activate option \Option{hmode} gain compatibility to -\Package{scrpage2} in this -aspect. But this would have side effects, i.\,e., white -spaces at the start of the output or the vertical alignment of the output. - -The options allows for the standard values for simple switches that are given -at \autoref{tab:truefalseswitch} on \autopageref{tab:truefalseswitch}. The -option is deactivated by default.% +The \Package{scrpage2} package always outputs headers and footers in +horizontal mode. In contrast, \Package{scrlayer-scrpage} in the default +setting only switches into horizontal mode when horizontal material is output. +However, if you activate the \Option{hmode} option, \Package{scrlayer-scrpage} +will behave like \Package{scrpage2} and switch to horizontal mode before any +output. This can affect both the processing of white space at the beginning of +the output and vertical alignment. + +The options recognizes the standard values for simple switches listed in +\autoref{tab:truefalseswitch} on \autopageref{tab:truefalseswitch}. The option +is deactivated by default.% \EndIndexGroup + +\LoadNonFree{scrlayer-scrpage-experts}{0} % \EndIndexGroup diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-scrpage.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-scrpage.tex index b7254e0df94..d3c50bfef00 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-scrpage.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer-scrpage.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrlayer-scrpage.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2013-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrlayer-scrpage.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2013-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -44,192 +44,215 @@ % ============================================================================ \KOMAProvidesFile{scrlayer-scrpage.tex}% - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (chapter: scrlayer-scrpage)] -\translator{Markus Kohm\and Jana Schubert\and Jens H\"uhne} +\translator{Markus Kohm\and Jana Schubert\and Jens H\"uhne\and Karl Hagen} -% Date version of the translated file: 2015-03-31 +% Date version of the translated file: 2018-02-13 -\chapter[{Adapting Page Headers and Footers with \Package{scrlayer-scrpage}}] - {Adapting\ChangedAt{v3.12}{\Package{scrlayer-scrpage}} Page Headers and +\chapter[{Headers and Footers with \Package{scrlayer-scrpage}}] + {Headers\ChangedAt{v3.12}{\Package{scrlayer-scrpage}} and Footers with \Package{scrlayer-scrpage}} \labelbase{scrlayer-scrpage} % \BeginIndexGroup \BeginIndex{Package}{scrlayer-scrpage}% - -Until version 3.11b of \KOMAScript, package \Package{scrpage2} has been the -recommended way to customise page headers and footers beyond the options -provided by the page styles \PageStyle{headings}, \PageStyle{myheadings}, -\PageStyle{plain}, and \PageStyle{empty} of the standard \KOMAScript{} -classes. Until 2001 there was also package \Package{scrpage} as a supported -solution for the same purpose. It was then made obsolete and in 2013, more -than ten years later, it was finally removed from the regular -\KOMAScript~distribution. - -In 2013 package \Package{scrlayer}\IndexPackage{scrlayer} became a basic -module of \KOMAScript. That package provides a layer scheme and a new page -style scheme based upon the layer scheme. Nevertheless, the flexibility it -provides and the resulting complexity may be too demanding for the average -user to handle. More about \Package{scrlayer} may be found in -\autoref{cha:scrlayer} of \autoref{part:forExperts}. Potential problems with -the controllability of \Package{scrlayer} apart, there are lots of users who -are already familiar with the user interface of package \Package{scrpage2}. - -As a consequence the additional package \Package{scrlayer-scrpage} provides a -user interface, which is largely compatible with \Package{scrpage2} and based -on \Package{scrlayer}. Thus, if you are already familiar with \Package{scrpage2} -and refrain from using dirty tricks, like calling internal commands of -\Package{scrpage2} directly, it should be easy for you to use -\Package{scrlayer-scrpage} as a drop-in replacement. Most examples covering -\Package{scrpage2} in \LaTeX{} books or online resources should also work -with \Package{scrlayer-scrpage} either directly or with only minor -code changes provided that they stick to the standard interfaces. - -Apart from the aforementioned \KOMAScript{} packages, you could in principle -also use \Package{fancyhdr}\IndexPackage{fancyhdr} (see -\cite{package:fancyhdr}) in conjunction with a \KOMAScript{} class. However, -\Package{fancyhdr}\ has no support for several \KOMAScript{} features, e.\,g., -the element scheme (see \DescRef{\LabelBase.cmd.setkomafont}, +\begin{Explain} + Until version 3.11b of \KOMAScript, the \Package{scrpage2}% + \IndexPackage[indexmain]{scrpage2}\important{\Package{scrpage2}} package was + the recommended way to customise headers and footers beyond the options + provided by the \PageStyle{headings}, \PageStyle{myheadings}, + \PageStyle{plain}, and \PageStyle{empty} page styles of the \KOMAScript{} + classes. + \iffalse% + The still older \Package{scrpage}\IndexPackage{scrpage} package was marked + obsolete in 2001 and removed from the regular \KOMAScript{} distribution in + 2013.\par + \fi% + Since 2013, the \hyperref[cha:scrlayer]{\Package{scrlayer}}% + \important{\hyperref[cha:scrlayer]{\Package{scrlayer}}}% + \IndexPackage{scrlayer} package has been included as a basic module of + \KOMAScript. This package provides a layer model and a new page-style model + based upon it. However, the package's interface is almost too flexible and + consequently not easy for the average user to comprehend. For more + information about this interface, see \autoref{cha:scrlayer} in + \autoref{part:forExperts}. However, a few of the options that are actually + part of \Package{scrlayer}, and which are therefore taken up again in that + chapter, are also documented here because they are required to use + \Package{scrlayer-scrpage}. + + Many users are already familiar with the commands from \Package{scrpage2}. + For this reason, \Package{scrlayer-scrpage} provides a method for + manipulating headers and footers which is based on \Package{scrlayer}, is + largely compatible with \Package{scrpage2}, and at the same time greatly + expands the user interface. If you are already familiar with + \Package{scrpage2} and refrain from direct calls to its internal commands, + you can usually use \Package{scrlayer-scrpage} as a drop-in replacement. + This also applies to most examples using \Package{scrpage2} found in + \LaTeX{} books or on the Internet.% + \iffalse% + \iffree{}{\par With the release of this book, \Package{scrlayer-scrpage} + for \KOMAScript{} is recommended as the tool of choice when it comes to + changing the predefined page styles. Using the obsolete package + \Package{scrpage2}\IndexPackage[indexmain]{scrpage2}% + \important{\Package{scrpage2}} is now deprecated. Therefore, the + commands for this outdated package are no longer part of this book. If + you encounter older documents that still use \Package{scrpage2}, + consider switching to \Package{scrlayer-scrpage}. Notwithstanding, this + chapter does contain some hints for using \Package{scrpage2}.}% + \fi +\end{Explain} + +In addition to \Package{scrlayer-scrpage}\iffree{ or \Package{scrpage2}}{}, +you could also use \Package{fancyhdr}\IndexPackage{fancyhdr} (see +\cite{package:fancyhdr}) to configure the headers and footers of pages. +However, this package has no support for several \KOMAScript{} features, +for example the element scheme (see \DescRef{\LabelBase.cmd.setkomafont}, \DescRef{\LabelBase.cmd.addtokomafont}, and -\DescRef{\LabelBase.cmd.usekomafont} in \autoref{sec:maincls.textmarkup}, from +\DescRef{\LabelBase.cmd.usekomafont} in \autoref{sec:maincls.textmarkup}, \DescPageRef{maincls.cmd.setkomafont}) or the configurable numbering format -for dynamic headers (see option \DescRef{maincls.option.numbers} and, e.\,g., -\DescRef{\LabelBase.cmd.chaptermarkformat} in \autoref{sec:maincls.structure}, -\DescPageRef{maincls.option.numbers} and +for dynamic headers (see the \DescRef{maincls.option.numbers} option and, +for example, \DescRef{\LabelBase.cmd.chaptermarkformat} in +\autoref{sec:maincls.structure}, \DescPageRef{maincls.option.numbers} and \DescPageRef{maincls.cmd.chaptermarkformat}). Hence, if you are using a -\KOMAScript{} class, the usage of package \Package{scrlayer-scrpage} is -recommended. Of course you can use \Package{scrlayer-scrpage} with other -classes, namely the \LaTeX{} standard classes, too. - -Besides the features described in this chapter, \Package{scrlayer-scrpage} -provides several more that are likely only of minor interest to the average -user and for this reason are described from -\autopageref{cha:scrlayer-scrpage-experts} onwards in -\autoref{cha:scrlayer-scrpage-experts} of \autoref{part:forExperts}. -Nevertheless, should the options described in \autoref{part:forAuthors} be -insufficient for your purposes you are encouraged to examine -\autoref{cha:scrlayer-scrpage-experts}. +\KOMAScript{} class, you should use the new \Package{scrlayer-scrpage} +package. \iffree{If you have problems, you can still use +\Package{scrpage2}.}{\ignorespaces} Of course, you can also use +\Package{scrlayer-scrpage} with other classes, such as the standard \LaTeX{} +ones. + +Apart from the features described in this chapter, \Package{scrlayer-scrpage} +provides several more functions that are likely only of interest to a very +small number of users and therefore are described in +\autoref{cha:scrlayer-scrpage-experts} of \autoref{part:forExperts}, starting +at \autopageref{cha:scrlayer-scrpage-experts}. Nevertheless, if the options +described in \autoref{part:forAuthors} are insufficient for your purposes, you +should examine \autoref{cha:scrlayer-scrpage-experts}. \LoadCommonFile{options} % \section{Early or late Selection of Options} -\LoadCommonFile{headfootheight} % \section{Head and Foot Width} +\LoadCommonFile{headfootheight} % \section{Header and Footer Height} \LoadCommonFile{textmarkup} % \section{Text Markup} -\section{Usage of Predefined Page Styles} +\section{Using Predefined Page Styles} \seclabel{predefined.pagestyles} -The easiest way to your desired design for page header and footer with +The easiest way to create custom headers and footers with \Package{scrlayer-scrpage} is to use one of the predefined page styles. +% +\iffalse % Umbruchoptimierung + This section introduces the page styles defined by the + \Package{scrlayer-scrpage} package as it loads. It also explains the + commands that you can use to create basic settings for these page + styles. You can find further options, commands, and background information + in the following sections and in + \autoref{sec:scrlayer-scrpage-experts.pagestyle.pairs} in + \autoref{part:forExperts}.% +\fi \begin{Declaration} \PageStyle{scrheadings}% \PageStyle{plain.scrheadings} \end{Declaration} -Package \Package{scrlayer-scrpage} provides two page styles, which may be -reconfigured to meet your individual reqirements. Let's first of all discuss -page style \PageStyle{scrheadings} which has been designed as a style using -running heads. Its defaults are similar to the page style -\PageStyle{headings}\IndexPagestyle{headings} of the \LaTeX standard classes -or the \KOMAScript{} classes. What exactly gets printed in the header or -footer can be configured via the commands and otions described hereafter. - -The second page style to be mentioned here is \PageStyle{plain.scrheadings}, -which has been designed to be a style with no running head. Its defaults are -very similar to page style \PageStyle{plain}\IndexPagestyle{plain} of \LaTeX's -standard classes or the \KOMAScript{} classes. The following will describe the -commands and options you may use to adjust the contents of the header and -footer . - -You could of course configure \PageStyle{scrheadings} to be a page style +The \Package{scrlayer-scrpage} package provides two page styles that you can +reconfigure to your liking. The first page style is +\PageStyle{scrheadings}\important{\PageStyle{scrheadings}}, which is intended +as a page style with running heads. Its defaults are similar to the page style +\PageStyle{headings}\IndexPagestyle{headings} of the standard \LaTeX{} or +\KOMAScript{} classes. You can configure exactly what appears in the header or +footer with the commands and options described below. + +The second page style is \PageStyle{plain.scrheadings}% +\important{\PageStyle{plain.scrheadings}}, which is intended to be a style +with no running head. Its defaults resemble those of the +\PageStyle{plain}\IndexPagestyle{plain} page style of the standard or +\KOMAScript{} classes. You can configure exactly what appears in the header or +footer with the commands and options described below. + +You could, of course, configure \PageStyle{scrheadings} to be a page style without a running head and \PageStyle{plain.scrheadings} to be a page style -using running heads. It is, however, far more expedient to adhere to the -conventions mentioned above, if for the only reason that both page styles -mutually influence one another. Once you have opted to apply one of these -page styles, \PageStyle{scrheadings} will become accessible as -\PageStyle{headings} and the page style \PageStyle{plain.scrheadings} will -become accessible as \PageStyle{plain}. Thus, if you use a class or package -that automatically switches between \PageStyle{headings} and -\PageStyle{plain}, you only need to select \PageStyle{scrheadings} or -\PageStyle{plain.scrheadings} once and the switching class or package will -then switch between \PageStyle{scrheadings} and \PageStyle{plain.scrheadings} -without even being aware of these page styles. Patches or other adaptions of -classes (or packages) will not be necessary. This pair of page styles may thus -serve as a drop-in replacement for \PageStyle{headings} and \PageStyle{plain}. -Should additional similar pairs be required I'd like to point you to -\autoref{sec:scrlayer-scrpage-experts.pagestyle.pairs} in -\autoref{part:forExperts} for further reference. - -For users of the older \Package{scrpage2}, I'd like to mention that, for -compatibility with \Package{scrpage2}, page style -\PageStyle{plain.scrheadings} may also be used under its alias name of -\PageStyle{scrplain}\IndexPagestyle[indexmain]{scrplain}.% -\iffree{}{ If you use \Package{scrpage2}\IndexPackage{scrpage2}, however, - \PageStyle{plain.scrheadings} will not be available. Its function is - completely taken over by pagestyle \PageStyle{scrplain}.} -% +with a running head. It is, however, advisable to adhere to the conventions +mentioned above. The two page styles mutually influence one another. Once you +apply one of these page styles, \PageStyle{scrheadings} will become accessible +as \PageStyle{headings}\important{\PageStyle{headings}}% +\IndexPagestyle{headings} and the page style \PageStyle{plain.scrheadings} +will become accessible as \PageStyle{plain}\important{\PageStyle{plain}}% +\IndexPagestyle{plain}. Thus, if you use a class or package that automatically +switches between \PageStyle{headings} and \PageStyle{plain}, you only need to +select \PageStyle{scrheadings} or \PageStyle{plain.scrheadings} once. Direct +patches to the corresponding classes or packages are not necessary. This pair +of page styles can thus serve as a drop-in replacement for +\PageStyle{headings} and \PageStyle{plain}. If you need more such pairs, +please refer to \autoref{sec:scrlayer-scrpage-experts.pagestyle.pairs} in +\autoref{part:forExperts}.% \EndIndexGroup \begin{Declaration} - \Macro{lehead}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{cehead}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{rehead}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{lohead}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{cohead}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{rohead}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content} + \Macro{lehead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cehead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{rehead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{lohead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cohead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{rohead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content} \end{Declaration} -The contents of the header of page style \PageStyle{plain.scrheadings} and -\PageStyle{scrheadings} can be defined using these commands. Thereby the -optional argument defines the content of an element of page style -\PageStyle{plain.scrheadings}, while the mandatory argument sets the content -of the corresponding element of page style \PageStyle{scrheadings}. - -Contents of left\,---\,so called even\,---\,pages can be set with -\Macro{lehead}, \Macro{cehead}, and \Macro{rohead}. Remark: The ``\texttt{e}'' -at the second position of the commands' names means ``\emph{even}''. - -Contents of right\,---\,so called odd\,---\,pages can be set with -\Macro{lohead}, \Macro{cohead}, and \Macro{rohead}. Remark: The ``\texttt{o}'' -at the second position of the commands' names means ``\emph{odd}''. - -Please note\textnote{Attention!} that there are only odd pages within single -side layouts independent of whether or not they have an odd page number. - -Each header consists of a left aligned element that will be defined by -\Macro{lehead} respectively \Macro{lohead}. Remark: The ``\texttt{l}'' at the -first position of the commands' names means ``\emph{left aligned}''. - -Similarly each header has a centred element that will be defined by -\Macro{cehead} respectively \Macro{cohead}. Remark: The ``\texttt{c}'' at the -first position of the command' names means ``\emph{centred}''. - -Similarly each header has a right aligned element that will be defined by -\Macro{rehead} respectively \Macro{rohead}. Remark: The ``\texttt{r}'' at the -first position of the commands' names means ``\emph{right aligned}''. +You can set the contents of the header for the +\DescRef{\LabelBase.pagestyle.plain.scrheadings} and +\DescRef{\LabelBase.pagestyle.scrheadings} page styles with these commands. +The optional argument sets the content of an element of the +\DescRef{\LabelBase.pagestyle.plain.scrheadings} page style, while the +mandatory argument sets the content of the corresponding element of the +\DescRef{\LabelBase.pagestyle.scrheadings} page style. + +The contents of even\,---\,or left-hand\,---\,pages\textnote{left-hand pages} +can be set with \Macro{lehead}, \Macro{cehead}, and \Macro{rehead}. The +``\texttt{e}'' appearing as the second letter of the commands' names stands +for ``\emph{even}''. + +The contents of odd\,---\,or right-hand\,---\,pages\textnote{right-hand pages} +can be set with \Macro{lohead}, \Macro{cohead}, and \Macro{rohead}. The +``\texttt{o}'' appearing as the second letter of the commands' names stands +for ``\emph{odd}''. + +Note\textnote{Attention!} that in one-sided printing, only right-hand pages +exist, and \LaTeX{} designates these as odd pages regardless of their page +number. + +Each header consists of a left-aligned\textnote{left aligned} element that can +be set with \Macro{lehead} or \Macro{lohead}. The ``\texttt{l}'' appearing as +the first letter of the commands' names stands for ``\emph{left aligned}''. + +Similarly, each header has a centred\textnote{centred} element that can be set +with \Macro{cehead} or \Macro{cohead}. The ``\texttt{c}'' appearing as the +first letter of the command' names stands for ``\emph{centred}''. + +Likewise, each header has a right-aligned\textnote{right aligned} element that +can be set with \Macro{rehead} or \Macro{rohead}. The ``\texttt{r}'' appearing +as the first letter of the commands' names stands for ``\emph{right +aligned}''. +\BeginIndexGroup \BeginIndex{FontElement}{pagehead}\LabelFontElement{pagehead}% \BeginIndex{FontElement}{pageheadfoot}\LabelFontElement{pageheadfoot}% -However, these elements do not have their own font attributes that may be -changed using commands \DescRef{\LabelBase.cmd.setkomafont} and +These elements do not have individual font attributes that you can +change using the commands \DescRef{\LabelBase.cmd.setkomafont} and \DescRef{\LabelBase.cmd.addtokomafont} (see \autoref{sec:maincls.textmarkup}, -\DescPageRef{maincls.cmd.setkomafont}), but are grouped in an element named -\FontElement{pagehead}. And before the font of that element additionally the -font of element \FontElement{pageheadfoot} will be used. See -\autoref{tab:scrlayer-scrpage.fontelements} for the font default of these +\DescPageRef{maincls.cmd.setkomafont}). Instead, they use an element named +\FontElement{pagehead}. Before this element is applied, the +\FontElement{pageheadfoot} element will also be applied. See +\autoref{tab:scrlayer-scrpage.fontelements} for the defaults of these elements.% -\EndIndex{FontElement}{pageheadfoot}% -\EndIndex{FontElement}{pagehead}% +\EndIndexGroup -The semantics of the described commands within two-sided layouts are also -sketched in \autoref{fig:scrlayer-scrpage.head}.% +The meaning of each command for headers in two-sided printing is illustrated +in \autoref{fig:scrlayer-scrpage.head}.% % \begin{figure}[tp] \centering @@ -242,7 +265,7 @@ sketched in \autoref{fig:scrlayer-scrpage.head}.% \multiput(0,0)(0,-1mm){10}{\line(0,-1){.5mm}}% \put(.49\textwidth,5mm){\line(0,1){15mm}}% \put(.05\textwidth,10mm){% - \iffree{\color{red}}{}% + \color{ImageRed}% \put(-.5em,0){\line(1,0){4em}}% \multiput(3.5em,0)(.25em,0){5}{\line(1,0){.125em}}% \put(-.5em,0){\line(0,1){\baselineskip}}% @@ -251,7 +274,7 @@ sketched in \autoref{fig:scrlayer-scrpage.head}.% \makebox(4em,5mm)[l]{\Macro{lehead}}% }% \put(.465\textwidth,10mm){% - \iffree{\color{blue}}{}% + \color{ImageBlue}% \put(-4em,0){\line(1,0){4em}}% \multiput(-4em,0)(-.25em,0){5}{\line(1,0){.125em}}% \put(0,0){\line(0,1){\baselineskip}}% @@ -260,7 +283,7 @@ sketched in \autoref{fig:scrlayer-scrpage.head}.% \put(-4.5em,0){\makebox(4em,5mm)[r]{\Macro{rehead}}}% }% \put(.2525\textwidth,10mm){% - \iffree{\color{green}}{}% + \color{ImageGreen}% \put(-2em,0){\line(1,0){4em}}% \multiput(2em,0)(.25em,0){5}{\line(1,0){.125em}}% \multiput(-2em,0)(-.25em,0){5}{\line(1,0){.125em}}% @@ -275,7 +298,7 @@ sketched in \autoref{fig:scrlayer-scrpage.head}.% \put(\textwidth,0){\line(0,1){20mm}}% \multiput(\textwidth,0)(0,-1mm){10}{\line(0,-1){.5mm}}% \put(.5325\textwidth,10mm){% - \iffree{\color{blue}}{}% + \color{ImageBlue}% \put(0,0){\line(1,0){4em}}% \multiput(4em,0)(.25em,0){5}{\line(1,0){.125em}}% \put(0,0){\line(0,1){\baselineskip}}% @@ -284,7 +307,7 @@ sketched in \autoref{fig:scrlayer-scrpage.head}.% \put(.5em,0){\makebox(4em,5mm)[l]{\Macro{lohead}}}% }% \put(.965\textwidth,10mm){% - \iffree{\color{red}}{}% + \color{ImageRed}% \put(-4em,0){\line(1,0){4em}}% \multiput(-4em,0)(-.25em,0){5}{\line(1,0){.125em}}% \put(0,0){\line(0,1){\baselineskip}}% @@ -293,7 +316,7 @@ sketched in \autoref{fig:scrlayer-scrpage.head}.% \put(-4.5em,0){\makebox(4em,5mm)[r]{\Macro{rohead}}}% }% \put(.75\textwidth,10mm){% - \iffree{\color{green}}{}% + \color{ImageGreen}% \put(-2em,0){\line(1,0){4em}}% \multiput(2em,0)(.25em,0){5}{\line(1,0){.125em}}% \multiput(-2em,0)(-.25em,0){5}{\line(1,0){.125em}}% @@ -303,53 +326,53 @@ sketched in \autoref{fig:scrlayer-scrpage.head}.% \put(-2em,0){\makebox(4em,5mm)[c]{\Macro{cohead}}}% }% % commands for both pages - \iffree{\color{blue}}{}% + \color{ImageBlue}% \put(.5\textwidth,0){\makebox(0,\baselineskip)[c]{\Macro{ihead}}}% - \iffree{\color{green}}{}% + \color{ImageGreen}% \put(.5\textwidth,-5mm){\makebox(0,\baselineskip)[c]{\Macro{chead}}} - \iffree{\color{red}}{}% + \color{ImageRed}% \put(.5\textwidth,-10mm){\makebox(0,\baselineskip)[c]{\Macro{ohead}}} \put(\dimexpr.5\textwidth-2em,.5\baselineskip){% - \iffree{\color{blue}}{}% + \color{ImageBlue}% \put(0,0){\line(-1,0){1.5em}}% \put(-1.5em,0){\vector(0,1){5mm}}% - \iffree{\color{green}}{}% + \color{ImageGreen}% \put(0,-1.25\baselineskip){\line(-1,0){\dimexpr .25\textwidth-2em\relax}}% \put(-\dimexpr .25\textwidth-2em\relax,-1.25\baselineskip){\vector(0,1){\dimexpr 5mm+1.25\baselineskip\relax}} - \iffree{\color{red}}{}% + \color{ImageRed}% \put(0,-2.5\baselineskip){\line(-1,0){\dimexpr .45\textwidth-4em\relax}}% \put(-\dimexpr .45\textwidth-4em\relax,-2.5\baselineskip){\vector(0,1){\dimexpr 5mm+2.5\baselineskip\relax}} }% \put(\dimexpr.5\textwidth+2em,.5\baselineskip){% - \iffree{\color{blue}}{}% + \color{ImageBlue}% \put(0,0){\line(1,0){1.5em}}% \put(1.5em,0){\vector(0,1){5mm}}% - \iffree{\color{green}}{}% + \color{ImageGreen}% \put(0,-1.25\baselineskip){\line(1,0){\dimexpr .25\textwidth-2em\relax}} \put(\dimexpr .25\textwidth-2em\relax,-1.25\baselineskip){\vector(0,1){\dimexpr 5mm+1.25\baselineskip\relax}} - \iffree{\color{red}}{}% + \color{ImageRed}% \put(0,-2.5\baselineskip){\line(1,0){\dimexpr .45\textwidth-4em\relax}} \put(\dimexpr .45\textwidth-4em\relax,-2.5\baselineskip){\vector(0,1){\dimexpr 5mm+2.5\baselineskip\relax}} }% \end{picture} - \caption[Commands to define the page head]% - {The meaning of the commands to define the contents of the page head - of the page styles sketched on a schematic double page} + \caption[Commands for setting the page header]% + {The meaning of the commands for setting the contents of page headers + shown on a two-page schematic} \label{fig:scrlayer-scrpage.head} \end{figure} % \begin{Example} - Assume you're writing a short article and you want the title of that - article to be shown left aligned and the author's name to be - shown right aligned at the page head. You may for example use: + Suppose you're writing a short article and you want the author's name to + appear on the left side of the page and the article's title to appear + right. You can write, for example: \begin{lstcode} \documentclass{scrartcl} \usepackage{scrlayer-scrpage} @@ -362,29 +385,30 @@ sketched in \autoref{fig:scrlayer-scrpage.head}.% \maketitle \end{document} \end{lstcode} - But what happens: On the first page there's only a page number at the page - foot, but the header is empty! + But what happens? On the first page there's only a page number in the + footer, while the header remains empty! - The explanation is very easy. Document class \Class{scrartcl} switches to - page style \PageStyle{plain} for the page with the title head. After command + The explanation is simple: The \Class{scrartcl} class, like the default + \Class{article} class, switches to the \PageStyle{plain} page style for the + page which contains the title. After the command \DescRef{maincls.cmd.pagestyle}\PParameter{scrheadings} in the preamble of - the short document this will actually result in page style - \PageStyle{plain.scrheadings}. Using a \KOMAScript{} class the default of - this page style is an empty page header and a page number in the footer. In - the example code the optional arguments of \Macro{lohead} and \Macro{rohead} - are omitted. So page style \PageStyle{plain.scrheadings} remains unchanged - as default and the result for the first page is indeed correct. - - Please add some text below \DescRef{maincls.cmd.maketitle} until a second - page will be printed. Alternatively you may just add - \Macro{usepackage}\PParameter{lipsum}\IndexPackage{lipsum} into the document + our example, this actually refers to the + \DescRef{\LabelBase.pagestyle.plain.scrheadings} page style. The default for + this page style when using a \KOMAScript{} class is an empty page header and + a page number in the footer. In the example, the optional arguments of + \Macro{lohead} and \Macro{rohead} are omitted, so the + \DescRef{\LabelBase.pagestyle.plain.scrheadings} page style remains + unchanged and the result for the first page is actually correct. + + Now add enough text to the example after \DescRef{maincls.cmd.maketitle} + so that a second page is printed. You can simply add + \Macro{usepackage}\PParameter{lipsum}\IndexPackage{lipsum} to the document preamble and \Macro{lipsum}\IndexCmd{lipsum} below - \DescRef{maincls.cmd.maketitle}. You will see that the head of the second - page will show the author and the document title as we wanted. + \DescRef{maincls.cmd.maketitle}. You will see that the header of the second + page now contains the author and the document title as we wanted. - To see the difference you should also add an optional argument to - \Macro{lohead} and \Macro{rohead} containing some content. To do so, change - the example above: + For comparison, you should also add the optional argument to + \Macro{lohead} and \Macro{rohead}. Change the example as follows: \begin{lstcode} \documentclass{scrartcl} \usepackage{scrlayer-scrpage} @@ -399,48 +423,56 @@ sketched in \autoref{fig:scrlayer-scrpage.head}.% \maketitle \end{document} \end{lstcode} - Now, you also get a page header above the title head of the first - page. That is because you have reconfigured page style - \PageStyle{plain.scrheadings} with the two optional arguments. Most of you - will also recognise that it would be better to leave this page style - unchanged, because the running head above the document title is certainly + Now you have a header on the first page just above the title itself. + That is because you have reconfigured page style + \DescRef{\LabelBase.pagestyle.plain.scrheadings} with the two optional + arguments. As you probably appreciate, it would be better to leave this page + style unchanged, as a running head above the document title is rather annoying. + + By the way, as an alternative to configuring + \DescRef{\LabelBase.pagestyle.plain.scrheadings} you could, if you were + using a \KOMAScript{} class, have changed the page style for pages that + contain title headers. See \DescRef{maincls.cmd.titlepagestyle}% + \important{\DescRef{maincls.cmd.titlepagestyle}}% + \IndexCmd{titlepagestyle} in \autoref{sec:maincls.pagestyle}, + \DescPageRef{maincls.cmd.titlepagestyle}. \end{Example} -Allow me an important note:\textnote{Attention!} You should never put a -section heading or section number directly into the page head using a new -declaration by one of these commands. This could result in a wrong number or -heading text in the running head, because of the asynchronous page generation -and output of \TeX. Instead you should use the mark mechanism and ideally you -should use it together with the automatism described in the following -section.% +Note\textnote{Attention!} that you should never put a section +heading or section number directly into the header using one of these +commands. Because of the asynchronous way that \TeX{} lays out and outputs +pages, doing so can easily result in the wrong number or heading text in the +running head. Instead you should use the mark mechanism, ideally in +conjunction with the procedures explained in the next section.% \EndIndexGroup \begin{Declaration} - \Macro{lehead*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{cehead*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{rehead*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{lohead*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{cohead*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{rohead*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content} + \Macro{lehead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cehead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{rehead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{lohead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cohead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{rohead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content} \end{Declaration} -The previously described commands have also a version with -star\ChangedAt{v3.14}{\Package{scrlayer-scrpage}} that differs only if you -omit the optional argument \PName{plain.scrheadings's content}. In this case -the version without star does not change the content of -\PageStyle{plain.scrheadings}. The version with star on the other hand uses -the obligatory argument \PName{scrheading's content} also as default for -\PageStyle{plain.scrheadings}. So, if both arguments should be the same, you -can simply use the star version with the obligatory argument only.% +The starred versions\ChangedAt{v3.14}{\Package{scrlayer-scrpage}} of the +previously described commands differ from the ordinary versions only if you +omit the optional argument \PName{plain.scrheadings content}. In this case, +the version without the star does not change the contents of +\DescRef{\LabelBase.pagestyle.plain.scrheadings}. The starred version, on the +other hand, uses the mandatory argument \PName{scrheading content} +for \DescRef{\LabelBase.pagestyle.plain.scrheadings} as well. So if both +arguments should be the same, you can simply use the starred version with only +the mandatory argument.% \begin{Example} - You can shorten the previous example using the star version of + You can shorten the previous example using the starred versions of \DescRef{\LabelBase.cmd.lohead} and \DescRef{\LabelBase.cmd.rohead}: \begin{lstcode} \documentclass{scrartcl} @@ -453,73 +485,76 @@ can simply use the star version with the obligatory argument only.% \author{John Doe} \maketitle \end{document} -\end{lstcode} -\end{Example} - -The obsolete package \Package{scrpage2}\important{\Package{scrpage2}} does not -provide this feature.% -% +\end{lstcode}% +\end{Example}% \EndIndexGroup \begin{Declaration} - \Macro{lefoot}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{cefoot}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{refoot}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{lofoot}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{cofoot}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{rofoot}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content} + \Macro{lefoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cefoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{refoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{lofoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cofoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{rofoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content} \end{Declaration} -The contents of the footer of page style \PageStyle{plain.scrheadings} and -\PageStyle{scrheadings} can be defined using these commands. Thereby the -optional argument defines the content of an element of page style -\PageStyle{plain.scrheadings}, while the mandatory argument sets the content -of the corresponding element of page style \PageStyle{scrheadings}. - -Contents of left\,---\,so called even\,---\,pages can be set with -\Macro{lefoot}, \Macro{cefoot}, and \Macro{rohead}. Remark: The ``\texttt{e}'' -at the second position of the commands' names means ``\emph{even}''. - -Contents of odd pages can be set with \Macro{lofoot}, \Macro{cofoot}, and -\Macro{rofoot}. Remark: The ``\texttt{o}'' at the second position of the -commands' names means ``\emph{odd}''. - -Please note\textnote{Attention!} that there are only odd pages within single -side layouts independent of whether or not they have an odd page number. - -Each footer consists of a left aligned element that will be defined by -\Macro{lefoot} respectively \Macro{lofoot}. Remark: The ``\texttt{l}'' at the -first position of the commands' names means ``\emph{left aligned}''. - -Similarly each footer has a centred element that will be defined by -\Macro{cefoot} respectively \Macro{cofoot}. Remark: The ``\texttt{c}'' at the -first position of the command' names means ``\emph{centred}''. - -Similarly each footer has a right aligned element that will be defined by -\Macro{refoot} respectively \Macro{rofoot}. Remark: The ``\texttt{r}'' at the -first position of the commands' names means ``\emph{right aligned}''. +You can define the contents of the footer for +\DescRef{\LabelBase.pagestyle.scrheadings} and +\DescRef{\LabelBase.pagestyle.plain.scrheadings} with these commands. The +optional argument defines the content of an element of +\DescRef{\LabelBase.pagestyle.plain.scrheadings}, while the mandatory argument +sets the content of the corresponding element of +\DescRef{\LabelBase.pagestyle.scrheadings}. + +The contents of even\,---\,or left-hand\,---\,pages\textnote{left-hand page} +are set with \Macro{lefoot}, \Macro{cefoot}, and \Macro{refoot}. The +``\texttt{e}'' appearing as the second letter of the commands' names stands +for ``\emph{even}''. + +The contents of odd\,---\,or right-hand\,---\,pages\textnote{right-hand page} +are set with \Macro{lofoot}, \Macro{cofoot}, and \Macro{rofoot}. The +``\texttt{o}'' appearing as the second letter of the commands' names stands +for ``\emph{odd}''. + +Note\textnote{Attention!} that in one-sided printing, only right-hand pages +exist, and \LaTeX{} designates these as odd pages regardless of their page +number. + +Each footer consists of a left-aligned\textnote{left aligned} element that can +be set with \Macro{lefoot} or \Macro{lofoot}. The ``\texttt{l}'' appearing as +the first letter of the commands' names stands for ``\emph{left aligned}''. + +Similarly, each footer has a centred\textnote{centred} element that can be set +with \Macro{cefoot} or \Macro{cofoot}. The ``\texttt{c}'' in the first letter +of the command' names stands for ``\emph{centred}''. + +Likewise, each footer has a right-aligned\textnote{right aligned} element that +can be set with \Macro{refoot} or \Macro{rofoot}. The ``\texttt{r}'' in the +first letter of the commands' names stands for ``\emph{right aligned}''. +\BeginIndexGroup \BeginIndex{FontElement}{pagefoot}\LabelFontElement{pagefoot}% \BeginIndex{FontElement}{pageheadfoot}\LabelFontElement[foot]{pageheadfoot}% -However, these elements do not have their own font attributes that may be -changed using commands \DescRef{\LabelBase.cmd.setkomafont} and -\DescRef{\LabelBase.cmd.addtokomafont} (see \autoref{sec:maincls.textmarkup}, -\DescPageRef{maincls.cmd.setkomafont}), but are grouped in an element named -\FontElement{pagefoot}. And before the font of that element additionally the -font of element \FontElement{pageheadfoot} will be used. See -\autoref{tab:scrlayer-scrpage.fontelements} for the defaults of the fonts of -these elements.% -\EndIndex{FontElement}{pageheadfoot}% -\EndIndex{FontElement}{pagefoot}% - -The semantics of the described commands within two-sided layouts are also -sketched in \autoref{fig:scrlayer-scrpage.foot}.% +However, these elements do not have individual font attributes that can be +changed with the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see +\autoref{sec:maincls.textmarkup}, \DescPageRef{maincls.cmd.setkomafont}). +Instead, they use an element named +\FontElement{pagefoot}\important{\FontElement{pagefoot}}. Before this element +is applied, the font element +\FontElement{pageheadfoot}\important{\FontElement{pageheadfoot}} is also +applied. See \autoref{tab:scrlayer-scrpage.fontelements} for the defaults of +the fonts of these elements.% +\EndIndexGroup + +The meaning of each command for footers in two-sided printing is illustrated +in \autoref{fig:scrlayer-scrpage.foot}.% % \begin{figure}[bp] \centering @@ -532,7 +567,7 @@ sketched in \autoref{fig:scrlayer-scrpage.foot}.% \multiput(0,20mm)(0,1mm){10}{\line(0,1){.5mm}}% \put(.49\textwidth,0){\line(0,1){15mm}}% \put(.05\textwidth,5mm){% - \iffree{\color{red}}{}% + \color{ImageRed}% \put(-.5em,0){\line(1,0){4em}}% \multiput(3.5em,0)(.25em,0){5}{\line(1,0){.125em}}% \put(-.5em,0){\line(0,1){\baselineskip}}% @@ -541,7 +576,7 @@ sketched in \autoref{fig:scrlayer-scrpage.foot}.% \makebox(4em,5mm)[l]{\Macro{lefoot}}% }% \put(.465\textwidth,5mm){% - \iffree{\color{blue}}{}% + \color{ImageBlue}% \put(-4em,0){\line(1,0){4em}}% \multiput(-4em,0)(-.25em,0){5}{\line(1,0){.125em}}% \put(0,0){\line(0,1){\baselineskip}}% @@ -550,7 +585,7 @@ sketched in \autoref{fig:scrlayer-scrpage.foot}.% \put(-4.5em,0){\makebox(4em,5mm)[r]{\Macro{refoot}}}% }% \put(.2525\textwidth,5mm){% - \iffree{\color{green}}{}% + \color{ImageGreen}% \put(-2em,0){\line(1,0){4em}}% \multiput(2em,0)(.25em,0){5}{\line(1,0){.125em}}% \multiput(-2em,0)(-.25em,0){5}{\line(1,0){.125em}}% @@ -565,7 +600,7 @@ sketched in \autoref{fig:scrlayer-scrpage.foot}.% \put(\textwidth,0){\line(0,1){20mm}}% \multiput(\textwidth,20mm)(0,1mm){10}{\line(0,1){.5mm}}% \put(.5325\textwidth,5mm){% - \iffree{\color{blue}}{}% + \color{ImageBlue}% \put(0,0){\line(1,0){4em}}% \multiput(4em,0)(.25em,0){5}{\line(1,0){.125em}}% \put(0,0){\line(0,1){\baselineskip}}% @@ -574,7 +609,7 @@ sketched in \autoref{fig:scrlayer-scrpage.foot}.% \put(.5em,0){\makebox(4em,5mm)[l]{\Macro{lofoot}}}% }% \put(.965\textwidth,5mm){% - \iffree{\color{red}}{}% + \color{ImageRed}% \put(-4em,0){\line(1,0){4em}}% \multiput(-4em,0)(-.25em,0){5}{\line(1,0){.125em}}% \put(0,0){\line(0,1){\baselineskip}}% @@ -583,7 +618,7 @@ sketched in \autoref{fig:scrlayer-scrpage.foot}.% \put(-4.5em,0){\makebox(4em,5mm)[r]{\Macro{rofoot}}}% }% \put(.75\textwidth,5mm){% - \iffree{\color{green}}{}% + \color{ImageGreen}% \put(-2em,0){\line(1,0){4em}}% \multiput(2em,0)(.25em,0){5}{\line(1,0){.125em}}% \multiput(-2em,0)(-.25em,0){5}{\line(1,0){.125em}}% @@ -593,45 +628,45 @@ sketched in \autoref{fig:scrlayer-scrpage.foot}.% \put(-2em,0){\makebox(4em,5mm)[c]{\Macro{cofoot}}}% }% % both pages - \iffree{\color{blue}}{}% + \color{ImageBlue}% \put(.5\textwidth,15mm){\makebox(0,\baselineskip)[c]{\Macro{ifoot}}}% - \iffree{\color{green}}{}% + \color{ImageGreen}% \put(.5\textwidth,20mm){\makebox(0,\baselineskip)[c]{\Macro{cfoot}}} - \iffree{\color{red}}{}% + \color{ImageRed}% \put(.5\textwidth,25mm){\makebox(0,\baselineskip)[c]{\Macro{ofoot}}} \put(\dimexpr.5\textwidth-2em,.5\baselineskip){% - \iffree{\color{blue}}{}% + \color{ImageBlue}% \put(0,15mm){\line(-1,0){1.5em}}% \put(-1.5em,15mm){\vector(0,-1){5mm}}% - \iffree{\color{green}}{}% + \color{ImageGreen}% \put(0,20mm){\line(-1,0){\dimexpr .25\textwidth-2em\relax}}% \put(-\dimexpr .25\textwidth-2em\relax,20mm){\vector(0,-1){10mm}}% - \iffree{\color{red}}{}% + \color{ImageRed}% \put(0,25mm){\line(-1,0){\dimexpr .45\textwidth-4em\relax}}% \put(-\dimexpr .45\textwidth-4em\relax,25mm){\vector(0,-1){15mm}}% }% \put(\dimexpr.5\textwidth+2em,.5\baselineskip){% - \iffree{\color{blue}}{}% + \color{ImageBlue}% \put(0,15mm){\line(1,0){1.5em}}% \put(1.5em,15mm){\vector(0,-1){5mm}}% - \iffree{\color{green}}{}% + \color{ImageGreen}% \put(0,20mm){\line(1,0){\dimexpr .25\textwidth-2em\relax}}% \put(\dimexpr .25\textwidth-2em\relax,20mm){\vector(0,-1){10mm}}% - \iffree{\color{red}}{}% + \color{ImageRed}% \put(0,25mm){\line(1,0){\dimexpr .45\textwidth-4em\relax}}% \put(\dimexpr .45\textwidth-4em\relax,25mm){\vector(0,-1){15mm}}% }% \end{picture} - \caption[Commands to define the page footer]% - {The meaning of the commands to define the contents of the page - footer of the page styles sketched on a schematic double page}% + \caption[Commands for setting the page footer]% + {The meaning of the commands for setting the contents of page + footers shown on a two-page schematic}% \label{fig:scrlayer-scrpage.foot} \end{figure} % \begin{Example} - Let's return to the example of the short article. Assuming you want to print - the publisher at the left side of the page footer, you would change the - example above into: + Let's return to the example of the short article. Let's say you want to + specify the publisher in the left side of the footer. You would change the + example above to: \begin{lstcode} \documentclass{scrartcl} \usepackage{scrlayer-scrpage} @@ -647,49 +682,51 @@ sketched in \autoref{fig:scrlayer-scrpage.foot}.% \lipsum \end{document} \end{lstcode} - Once again the publisher is not printed on the first page with the title - head. For the reason see the explanation about \Macro{lohead} in the example - above. And again the solution to print the publisher on the first page would - be similar: + Once again the publisher is not printed on the first page with the title. + The reason is the same as in the example with + \DescRef{\LabelBase.cmd.lohead} above. And the solution for getting the + publisher on the first page is similar: \begin{lstcode} \lofoot[Smart Alec Publishing] {Smart Alec Publishing} \end{lstcode} - But now you also want to replace the slanted font used in page head and - footer by a upright smaller font. This may be done using: + Now you decide\textnote{font change}\important{\FontElement{pageheadfoot}}% + \IndexFontElement{pageheadfoot} that the header and footer should use an + upright but smaller font in place of the default slanted font: \begin{lstcode} \setkomafont{pageheadfoot}{\small} \end{lstcode} - Furthermore, the head but not the footer should be bold: + In addition, the header, but not the footer, should be bold: \begin{lstcode} \setkomafont{pagehead}{\bfseries} \end{lstcode} - For the last command it is important to have it just after - \Package{scrpage-scrlayer} has been loaded, because the \KOMAScript{} class - already defines \DescRef{\LabelBase.fontelement.pagehead} and - \DescRef{\LabelBase.fontelement.pageheadfoot} but with the same - meaning. Only loading \Package{scrpage-scrlayer} changes the meaning of - \DescRef{\LabelBase.fontelement.pagehead} and makes it an element - independent of \DescRef{\LabelBase.fontelement.pageheadfoot}. - - Now, please add one more \Macro{lipsum} and add option \Option{twoside} to - the loading of \Class{scrartcl}. First of all, you will see the page number - moving from the middle of the page footer to the outer margin, due to the - changed defaults of \PageStyle{scrheadings} and - \PageStyle{plain.scrheadings} using double-sided layout and a \KOMAScript{} - class. - - Simultaneously the author, document title and publisher will vanish from - page~2. It only appears on page~3. This is a consequence of using only - commands for odd pages. You can recognise this by the ``\texttt{o}'' on the - second position of the commands' names. - - Now, we could simply copy those commands and replace the ``\texttt{o}'' by + It is important\textnote{Attention!} that this command does not occur until + after \Package{scrpage-scrlayer} has been loaded because the \KOMAScript{} + class defines \DescRef{\LabelBase.fontelement.pagehead} as an alias for + \DescRef{\LabelBase.fontelement.pageheadfoot}. Only by loading + \Package{scrpage-scrlayer} will \DescRef{\LabelBase.fontelement.pagehead} + become an element independent of + \DescRef{\LabelBase.fontelement.pageheadfoot}. + + Now add one more \Macro{lipsum} and the + \Option{twoside}\IndexOption{twoside}\important{\Option{twoside}} option + when loading \Class{scrartcl}. First of all, you will see the page number + moves from the centre to the outer margin of the page footer, due to the + changed defaults of \DescRef{\LabelBase.pagestyle.scrheadings} and + \DescRef{\LabelBase.pagestyle.plain.scrheadings} for two-sided printing with + a \KOMAScript{} class. + + Simultaneously, the author, document title, and publisher will vanish from + page~2. They only appear on page~3. That's because we've only used + commands for odd pages. You can recognise this by the ``\texttt{o}'' in the + second position of the command names. + + Now, we could simply copy those commands and replace the ``\texttt{o}'' with an ``\texttt{e}'' to define the contents of \emph{even} pages. But with - double sided layout it makes more sense to use mirror-inverted elements. So - the left element of an odd page should become the right element of the even - page and visa versa. To achieve this, we also replace the first letter - ``\texttt{l}'' by ``\texttt{r}'': + two-sided printing, it makes more sense to use mirror-inverted elements, + i.\,e. the left element of an even page should become the right element of + the odd page and visa versa. To achieve this, we also replace the first + letter ``\texttt{l}'' with ``\texttt{r}'': \begin{lstcode} \documentclass[twoside]{scrartcl} \usepackage{scrlayer-scrpage} @@ -712,45 +749,45 @@ sketched in \autoref{fig:scrlayer-scrpage.foot}.% \end{lstcode} \end{Example} % -After reading the example it may appear to you that it is somehow -uncomfortable to duplicate commands to have the same contents on mirror -positions of the page header or footer of a double page. Therefore you will -learn to know an easier solution for this standard case next. - -Before allow me an important note:\textnote{Attention!} You should never put a -section heading or section number directly into the page's footer using a new -declaration by one of these commands. This could result in a wrong number or -heading text in the running footer, because of the asynchronous page -generation and output of \TeX. Instead you should use the mark mechanism -ideally together with the automatism described in the following section.% +Since it is a bit cumbersome to define left and right pages separately in +cases such as the previous example, a simpler solution for this common case is +introduced below. + +Allow me once again an important note:\textnote{Attention!} you should +never put a section heading or section number directly into the footer using +one of these commands. Because of the asynchronous way that \TeX{} lays out and +outputs pages, doing so can easily result in the wrong number or heading text +in the running head. Instead you should use the mark mechanism, ideally in +conjunction with the procedures explained in the next section.% \EndIndexGroup \begin{Declaration} - \Macro{lefoot*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{cefoot*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{refoot*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{lofoot*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{cofoot*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{rofoot*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content} + \Macro{lefoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cefoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{refoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{lofoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cofoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{rofoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content} \end{Declaration} -The previously described commands have also a version with -star\ChangedAt{v3.14}{\Package{scrlayer-scrpage}} that differs only if you -omit the optional argument \PName{plain.scrheadings's content}. In this case -the version without star does not change the content of -\PageStyle{plain.scrheadings}. The version with star on the other hand uses -the obligatory argument \PName{scrheading's content} also as default for -\PageStyle{plain.scrheadings}. So, if both arguments should be the same, you -can simply use the star version with the obligatory argument only. +The starred versions\ChangedAt{v3.14}{\Package{scrlayer-scrpage}} of the +previously described commands differ only if you omit the optional argument +\OParameter{plain.scrheadings content}. In this case, the version without the +star does not change the contents of +\DescRef{\LabelBase.pagestyle.plain.scrheadings}. The starred version, on the +other hand, uses the mandatory argument \PName{scrheading content} for +\DescRef{\LabelBase.pagestyle.plain.scrheadings} as well. So if both arguments +should be the same, you can simply use the starred version with just the +mandatory argument.% \begin{Example} - You can shorten the previous example using the star version of + You can shorten the previous example using the star versions of \DescRef{\LabelBase.cmd.lofoot} and \DescRef{\LabelBase.cmd.refoot}: \begin{lstcode} \documentclass[twoside]{scrartcl} @@ -771,50 +808,46 @@ can simply use the star version with the obligatory argument only. \end{document} \end{lstcode} \end{Example} - -The obsolete package \Package{scrpage2}\important{\Package{scrpage2}} does not -provide this feature.% % \EndIndexGroup \begin{Declaration} - \Macro{ohead}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{chead}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{ihead}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{ofoot}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{cfoot}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{ifoot}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content} + \Macro{ohead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{chead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{ihead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{ofoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cfoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{ifoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content} \end{Declaration} -To define the contents of page headers and footers of odd and the even pages -of a double-sided layout using the commands described before, you would have to -define the contents of the even page different from the contents of the odd -page. But in general the pages should be symmetric. An element, that should be -printed left aligned on an even page, should be right aligned on an odd page -and vise versa. Elements, that are centred on odd pages, should be centred on -even pages too. +To configure the headers and footers for two-sided printing with the +previously described commands, you would have to configure the left and right +sides separately from one another. In most cases, however, the left and right +sides are more or less symmetrical. An item that appears on the left of an +even page should appear on the right of an odd page and vice versa. Centred +elements are usually centred on both sides. To simplify the definition of such symmetric page styles, -\Package{scrlayer-scrpage} provides a kind of abbreviation. Command -\Macro{ohead} is same like usage of both \DescRef{\LabelBase.cmd.lehead} and -\DescRef{\LabelBase.cmd.rohead}. Command \Macro{chead} is same like -\DescRef{\LabelBase.cmd.cehead} and \DescRef{\LabelBase.cmd.cohead}. And -command \Macro{ihead} is same like \DescRef{\LabelBase.cmd.rehead} and -\DescRef{\LabelBase.cmd.lohead}. The corresponding commands for the page -footer are defined accordingly. A sketch of these commands can be found also -in \autoref{fig:scrlayer-scrpage.head} on -\autopageref{fig:scrlayer-scrpage.head} and -\autoref{fig:scrlayer-scrpage.foot} on \autopageref{fig:scrlayer-scrpage.foot} -together with the relationships of all the page header and footer commands. +\Package{scrlayer-scrpage} has shortcuts. The \Macro{ohead} command +corresponds to a call to both \DescRef{\LabelBase.cmd.lehead} and +\DescRef{\LabelBase.cmd.rohead}. The \Macro{chead} command corresponds to a +call to both \DescRef{\LabelBase.cmd.cehead} and +\DescRef{\LabelBase.cmd.cohead}. And the \Macro{ihead} command corresponds to +a call to both \DescRef{\LabelBase.cmd.rehead} and +\DescRef{\LabelBase.cmd.lohead}. The same applies to the equivalent commands +for the page footer. An outline of these relationships can also be found in +\autoref{fig:scrlayer-scrpage.head} on \autopageref{fig:scrlayer-scrpage.head} +and \autoref{fig:scrlayer-scrpage.foot} on +\autopageref{fig:scrlayer-scrpage.foot}. % \begin{Example} - You can simplify the example before using the new commands: + You can simplify the previous example using the new commands: \begin{lstcode} \documentclass[twoside]{scrartcl} \usepackage{scrlayer-scrpage} @@ -831,46 +864,48 @@ together with the relationships of all the page header and footer commands. \lipsum\lipsum \end{document} \end{lstcode} - As you can see, you can spare half of the commands but get the same result. -\end{Example} -% -In single-sided layouts all pages are odd pages. So in LaTeX's single-sided -mode these commands are synonymous for the odd page commands. Therefore in -most cases you will only need these six commands instead of the twelve -described before. - -Once again, allow me an important note:\textnote{Attention!} You should never -put a section heading or section number directly into the page head or -page foot using a new declaration by one of these commands. This could result in -a wrong number or heading text in the running header or footer, because of the -asynchronous page generation and output of \TeX. Instead you should use the -mark mechanism ideally together with the automatism described in the following -section.% +\iffalse% + As you can see, you can use half the number of commands but get the same + result. % +\fi% +\end{Example}% +Because one-sided printing treats all pages as odd pages, these commands are +synonymous with the corresponding right-side commands when in one-sided mode. +Therefore in most cases you will only need these six commands instead of the +twelve described before. + +Allow me once again an important note:\textnote{Attention!} you should never +put a section heading or section number directly into the footer using one of +these commands. Because of the asynchronous way that \TeX{} lays out and +outputs pages, doing so can easily result in the wrong number or heading text +in the running head. Instead you should use the mark mechanism, ideally in +conjunction with the procedures explained in the next section.% \EndIndexGroup \begin{Declaration} - \Macro{ohead*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{chead*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{ihead*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{ofoot*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{cfoot*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content}% - \Macro{ifoot*}\OParameter{plain.scrheadings's content}% - \Parameter{scrheadings's content} + \Macro{ohead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{chead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{ihead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{ofoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cfoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{ifoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content} \end{Declaration} -The previously described commands have also a version with -star\ChangedAt{v3.14}{\Package{scrlayer-scrpage}} that differs only if you -omit the optional argument \PName{plain.scrheadings's content}. In this case -the version without star does not change the content of -\PageStyle{plain.scrheadings}. The version with star on the other hand uses -the obligatory argument \PName{scrheading's content} also as default for -\PageStyle{plain.scrheadings}. So, if both arguments should be the same, you -can simply use the star version with the obligatory argument only.% +The previously described commands also have starred +versions\ChangedAt{v3.14}{\Package{scrlayer-scrpage}} that differ only if you +omit the optional argument \OParameter{plain.scrheadings content}. In this +case, the version without a star does not change the content of +\DescRef{\LabelBase.pagestyle.plain.scrheadings}. The version with the star, +on the other hand, also uses the mandatory argument \PName{scrheadings +content} for \DescRef{\LabelBase.pagestyle.plain.scrheadings}. So if both +arguments should be the same, you can simply use the starred version with only +the mandatory argument.% \begin{Example} You can shorten the previous example using the star version of @@ -889,157 +924,168 @@ can simply use the star version with the obligatory argument only.% \maketitle \lipsum\lipsum \end{document} -\end{lstcode} -\end{Example} - -The obsolete package \Package{scrpage2}\important{\Package{scrpage2}} does not -provide this feature.% -% +\end{lstcode}% +\end{Example}% \EndIndexGroup \begin{Declaration} \OptionVName{pagestyleset}{setting} \end{Declaration} +\BeginIndex{Option}{pagestyleset~=KOMA-Script}% \BeginIndex{Option}{pagestyleset~=standard}% -In the examples above you can already find some information about the defaults -of \PageStyle{scrheadings}\IndexPagestyle{scrheadings} and -\PageStyle{plain.scrheadings}\IndexPagestyle{plain.scrheadings}. Indeed -\Package{scrlayer-scrpage} provides two different defaults yet. You may select -one of those defaults manually using option \Option{pagestyleset}. - -If \PName{setting} is \PValue{KOMA-Script} the defaults will be used that -would also be activated automatically if a \KOMAScript{} class has been -detected. In this case and within double-sided layout \PageStyle{scrheadings} -uses running heads outer aligned in the page head. The page number will be -printed outer aligned in the page footer. Within single-sided layout the -running head will be printed in the middle of the page head and the page -number in the middle of the page footer. Upper and lower case will be used for -the automatic running head as given by the words you have typed. This would be -same like using Option -\OptionValueRef{\LabelBase}{markcase}{used}\IndexOption{markcase~=used}. -Page style \PageStyle{plain.scrheadings} has not got running heads, but the -page numbers will be printed in the same manner. - -If \PName{setting} is \PValue{standard} the defaults will be used that are -similar to page style \PageStyle{headings} and \PageStyle{plain} of the -standard classes. This \PName{setting} will also be activated automatically if -the option has not been used and \KOMAScript{} class cannot be -detected. Within double-sided layout thereby \PageStyle{scrheadings} uses -running heads aligned inner in the page head and the page numbers will be -printed\,---\,also in the page head\,---\,aligned outer. Within single-sided -layout \PageStyle{scrheadings} is the same. But because of single side layout -knows only odd pages, the running head will be aligned left always and the -page number will be aligned right. In spite of typographic objection, the -automatic running head will be converted into upper cases like they would -using -\OptionValueRef{\LabelBase}{markcase}{upper}\IndexOption{markcase~=upper}. -Within single side layout page style \PageStyle{plain.scrheadings} differs a -lot from \PageStyle{scrheading}, because the page number will be printed in -the middle of the page footer. Using double side layout page style -\PageStyle{plain.scrheadings} differs from standard classes' -\PageStyle{plain}. The standard classes would print the page number in the -middle of the page footer. But this would not harmonise with the -\PageStyle{scrheadings}, so \PageStyle{plain.scrheadings} does not print a -page number. But like \PageStyle{plain} it does not print a running head. - -Please note\textnote{Attention!} that together with this option page style -\PageStyle{scrheadings} will be activated. This will be also the case, if you -use the option inside the document. - -\BeginIndex{Option}{komastyle}% -\BeginIndex{Option}{standardstyle}% -Options \Option{komastyle} and \Option{standardstyle}, provided by -\Package{scrpage}, are defined only for compatibility reasons in -\Package{scrlayer-scrpage}. But they are implemented using option -\Option{pagestyleset}. They are deprecated and you should not use them.% +The examples above refer several times to the default settings of the page +styles \DescRef{\LabelBase.pagestyle.scrheadings}\IndexPagestyle{scrheadings} +and \DescRef{\LabelBase.pagestyle.plain.scrheadings}% +\IndexPagestyle{plain.scrheadings}. In fact, \Package{scrlayer-scrpage} +currently provides two different defaults for these page styles. You can +select them manually with the \Option{pagestyleset} option. + +The +\PValue{KOMA-Script}\important{\OptionValue{pagestyleset}{KOMA-Script}} +\PName{setting} selects the defaults, which are also set automatically if the +option is not specified and a \KOMAScript{} class is detected. In two-sided +printing, \DescRef{\LabelBase.pagestyle.scrheadings} uses outer-aligned +running heads in the header and outer-aligned page numbers in the footer. +In one-sided printing, the running head will be printed in the +middle of the header and the page number in the middle of the footer. Upper- +and lower-case letters are used in the automatic running heads as they +actually appear in the sectioning headings. This corresponds to the +\OptionValueRef{\LabelBase}{markcase}{used}\IndexOption{markcase~=used}% +\important{\OptionValueRef{\LabelBase}{markcase}{used}} option. The +\DescRef{\LabelBase.pagestyle.plain.scrheadings} page style has no running +heads, but the page numbers are printed in the same manner. + +However, if the \hyperref[cha:scrlttr2]{\Class{scrlttr2}}% +\important{\hyperref[cha:scrlttr2]{\Class{scrlttr2}}}% +\IndexClass{scrlttr2} class is detected, the default settings are based on the +page styles of that class. See \autoref{sec:scrlttr2.pagestyle}, +\autopageref{sec:scrlttr2.pagestyle}. + +The +\PValue{standard}\important{\OptionValue{pagestyleset}{standard}} +\PName{setting} selects defaults that match the page styles of the standard +classes. This is also activated automatically if the option has not been +specified and no \KOMAScript{} class is detected. In this case, for two-sided +printing \DescRef{\LabelBase.pagestyle.scrheadings} uses running heads +inner-aligned in the header, and the page numbers will be printed\,---\,also +in the header\,---\,outer-aligned. One-sided printing uses the same settings, +but since only right-hand pages exist in this mode, the running head will +always be left-aligned and the page number right-aligned. The automatic +running heads\,---\,despite considerable typographic objections\,---\,are +converted to capital letters, as they would be with +\OptionValueRef{\LabelBase}{markcase}{upper}\IndexOption{markcase~=upper}% +\important{\OptionValueRef{\LabelBase}{markcase}{upper}}. In one-sided +printing, the \DescRef{\LabelBase.pagestyle.plain.scrheadings} page style +differs considerably from \DescRef{\LabelBase.pagestyle.scrheadings} because +the page number is printed in the middle of the footer. +Unlike\textnote{\KOMAScript{} vs. standard classes} the \PageStyle{plain} page +style in the standard classes, +\DescRef{\LabelBase.pagestyle.plain.scrheadings} omits the page number in +two-sided printing. The standard classes print the page number in the middle +of the footer, which does not match the rest of the page styles in two-sided +printing. +\iffalse % Umbruchkorrekturtext + If you want the page number back +\begin{lstcode} + \cfoot[\pagemark]{} +\end{lstcode} + will restore it. % +\fi% +The running head is omitted in \DescRef{\LabelBase.pagestyle.plain.scrheadings}. + +Note\textnote{Attention!} that using this option activates the +\DescRef{\LabelBase.pagestyle.scrheadings}\IndexPagestyle{scrheadings}% +\important{\DescRef{\LabelBase.pagestyle.scrheadings}} page style. +\iffalse% Umbruchkorrektur + This also applies if you use the option within the document.% +\fi % \EndIndexGroup -\LoadCommonFile{pagestylemanipulation} % \section{Manipulation of Defined Page Styles} +\LoadCommonFile{pagestylemanipulation} % \section{Manipulating Defined Page Styles} \begin{Declaration} \OptionVName{headwidth}{width\textup{:}offset\textup{:}offset}% \OptionVName{footwidth}{width\textup{:}offset\textup{:}offset} \end{Declaration} -By default the page head\Index{head>width} and foot\Index{foot>width} are as -wide as the type area. This can be changed using these \KOMAScript{} -options. The value \PName{width} is the wanted width of the head respective -foot. The \PName{offset} defines how much the head or foot should be moved -towards the outer\,---\,in single side layout to the right\,---\,margin. All -three\ChangedAt{v3.14}{\Package{scrlayer-scrpage}} values are optional and can -be omitted. If you omit a value, you can also omit the corresponding colon -left beside. If there is only one \PName{offset} it is used for both, odd and -even pages. Otherwise, the first \PName{offset} is used for odd and the second -\PName{offset} for even pages in two-side mode. If you only use one value -without colon, this will be the \PName{width}. - -For the \PName{width} as well as the \PName{offset} you can use any valid -length value, \LaTeX{} length, \TeX{} dimension or \TeX{} skip. In addition -you may use an \eTeX{} dimension expression with basic arithmetic operations -\texttt{+}, \texttt{-}, \texttt{*}, \texttt{/}, and parenthesis. See -\cite[section~3.5]{manual:eTeX} for more information on such expressions. See -\autoref{sec:scrlayer-scrpage.options} for more information on using, -e.\,g., a \LaTeX{} length as an option value. The \PName{width} can -alternatively be one of the symbolic values shown in -\autoref{tab:scrlayer-scrpage.symbolic.values}. - -By default the head and the foot are as wide as the text area. The default -\PName{offset} depends on the used \PName{width}. In single side layout -generally the half of the difference of \PName{width} and the width of the -text area will be used. This results in horizontal centring the page head -above or the page footer below the text area. In difference to this, in double -side layout generally a third of the difference of \PName{offset} and the -width of the text area will be used. But if \PName{width} is the width of the -whole text area plus the marginal note column, default \PName{offset} will be -zero. If you think, this is complicated, you should simply use an explicit -\PName{offset}. +By default the header\Index{header>width} and footer\Index{footer>width} are +as wide as the type area. However, you can change this using these +\KOMAScript{} options. The value \PName{width} is the desired width of the +header or footer. The \PName{offset} defines how far the header or footer +should be moved towards the outer\,---\,in one-sided printing to the +right\,---\,margin. All three\ChangedAt{v3.14}{\Package{scrlayer-scrpage}} +values are optional and can be omitted. If you omit a value, you can also omit +the associated colon to the left of it. If only one \PName{offset} is +specified, it is used for both odd and even pages. Otherwise, the first +\PName{offset} is used for odd and the second \PName{offset} for even pages in +two-sided mode. If you only use one value without a colon, this will be the +\PName{width}. + +For both the \PName{width} and the \PName{offset} you can use any valid length +value, \LaTeX{} length, \TeX{} dimension, or \TeX{} skip. In addition, you can +use an \eTeX{} dimension expression with the basic arithmetic operations +\texttt{+}, \texttt{-}, \texttt{*}, \texttt{/}, and parentheses. See +\cite[section~3.5]{manual:eTeX} for more information on such expressions. See +\autoref{sec:scrlayer-scrpage.options} for more information on using a +\LaTeX{} length as an option value. The \PName{width} can also be one of the +symbolic values shown in \autoref{tab:scrlayer-scrpage.symbolic.values}. + +By default the header and the footer are the width of the text area. The +default \PName{offset} depends on the selected \PName{width}. One-sided +printing typically uses half the difference between \PName{width} and the +width of the text area. This centres the header horizontally above the text +area. Two-sided printing, on the other hand, uses only a third of the +difference between \PName{width} and the width of the text area. However, if +\PName{width} is the width of the whole text area and the marginal note +column, the default \PName{offset} will be zero. If this is too complicated +for you, you should simply specify the desired \PName{offset} yourself. % \begin{table} \centering - \caption[Symbolic values for options \Option{headwidth} and - \Option{footwidth}]{Possible symbolic values for the \PName{width} value of - options \Option{headwidth} and \Option{footwidth}} + \caption[Symbolic values for the \Option{headwidth} and \Option{footwidth} + options]{Available symbolic values for the \PName{width} value of options + \Option{headwidth} and \Option{footwidth}} \label{tab:scrlayer-scrpage.symbolic.values} \begin{desctabular} - \ventry{foot}{% - the current width of the page foot% + \entry{\PValue{foot}}{% + the current width of the footer% }% - \ventry{footbotline}{% - the current length of the horizontal line below the page foot% + \entry{\PValue{footbotline}}{% + the current length of the horizontal line below the footer% }% - \ventry{footsepline}{% - the current length of the horizontal line above the page foot% - } \ventry{head}{% - the current width of the page head% + \entry{\PValue{footsepline}}{% + the current length of the horizontal line above the footer% + } \entry{\PValue{head}}{% + the current width of the header% }% - \ventry{headsepline}{% - the current length of the horizontal line below the page head% + \entry{\PValue{headsepline}}{% + the current length of the horizontal line below the header% }% - \ventry{headtopline}{% - the current length of the horizontal line above the page head% + \entry{\PValue{headtopline}}{% + the current length of the horizontal line above the header% }% - \ventry{marginpar}{% - the current width of the marginal note column including the distance + \entry{\PValue{marginpar}}{% + the width of the marginal note column including the distance between the text area and the marginal note column% }% - \ventry{page}{% - the current width of the page considering a binding correction of - package \Package{typearea} (see option \DescRef{typearea.option.BCOR} in - \autoref{sec:typearea.typearea}, - \DescPageRef{typearea.option.BCOR})% + \entry{\PValue{page}}{% + the width of the page taking into account any binding correction defined + with the help of the \Package{typearea} package (see the + \DescRef{typearea.option.BCOR} option in + \autoref{sec:typearea.typearea}, \DescPageRef{typearea.option.BCOR})% }% - \ventry{paper}{% - the current width of the paper without considering a binding correction% + \entry{\PValue{paper}}{% + the width of the paper without considering any binding correction% }% - \ventry{text}{% - the current width of the text area% + \entry{\PValue{text}}{% + the width of the text area% }% - \ventry{textwithmarginpar}{% - the current width of the text area plus the marginal note column - including the distance between them (note: in this case and only in this - case the default of \PName{offset} would be zero)% + \entry{\PValue{textwithmarginpar}}{% + the width of the text area including the marginal note column and + the distance between the two (Note: only in this case is + the default for \PName{offset} zero)% }% \end{desctabular} \end{table} @@ -1053,66 +1099,51 @@ zero. If you think, this is complicated, you should simply use an explicit \OptionVName{footsepline}{thickness\textup{:}length}% \OptionVName{footbotline}{thickness\textup{:}length} \end{Declaration} -The \KOMAScript{} classes provide only a separation line below the page head -and above the page head, and you may only switch each of these lines on or -off. But package \Package{scrlayer-scrpage} provides four such horizontal -lines: one above the head, one below the head, one above the foot, and one -below the foot. And you can not only switch them on an off, but also configure -the \PName{length} and \PName{thickness} of each of these lines. +\BeginIndex{Option}{headtopline~=\PName{thickness\textup{:}length}}% +\BeginIndex{Option}{headsepline~=\PName{thickness\textup{:}length}}% +\BeginIndex{Option}{footsepline~=\PName{thickness\textup{:}length}}% +\BeginIndex{Option}{footbotline~=\PName{thickness\textup{:}length}}% +The \KOMAScript{} classes provide only one separation line below the header +and another above the footer, and you can only switch these lines on or off. +But the \Package{scrlayer-scrpage} package also lets you place lines above the +header and below the footer. And for all four lines, you can not only switch +them on an off but also configure their \PName{length} and \PName{thickness}. Both values are optional. If you omit the \PName{thickness}, a default value -of 0.4\Unit{pt} will be used, a so called \emph{hairline}. If you omit the -\PName{length}, the width of the head respective the foot will be used. If you +of 0.4\Unit{pt} is used, producing a so-called \emph{hairline}. If you omit +the \PName{length}, the width of the header or footer will be used. If you omit both, you can also omit the colon. If you use only one value without -colon, this will be the \PName{thickness}. - -For sure, the \PName{length} can be not only shorter than the current width of -the page head respectively the page foot, but also longer. See additionally -options \DescRef{\LabelBase.option.ilines}\IndexOption{ilines}, -\DescRef{\LabelBase.option.clines}\IndexOption{clines}, and +colon, this is the \PName{thickness}. + +Of course, the \PName{length} can be not just shorter than the current width +of the header or footer but also longer. See also the options +\DescRef{\LabelBase.option.ilines}\IndexOption{ilines}% +\important{\DescRef{\LabelBase.option.ilines}, +\DescRef{\LabelBase.option.clines}, \DescRef{\LabelBase.option.olines}}, +\DescRef{\LabelBase.option.clines}\IndexOption{clines} and \DescRef{\LabelBase.option.olines}\IndexOption{olines} later in this section. +\BeginIndexGroup \BeginIndex{FontElement}{headtopline}\LabelFontElement{headtopline}% \BeginIndex{FontElement}{headsepline}\LabelFontElement{headsepline}% \BeginIndex{FontElement}{footsepline}\LabelFontElement{footsepline}% \BeginIndex{FontElement}{footbotline}\LabelFontElement{footbotline}% -Beside the length and thickness also the colour of the lines can be -changed. First of all the colour depends on the colour of the head or -foot. But independent from those or additional to them the settings of the -corresponding elements \FontElement{headtopline}, \FontElement{headsepline}, -\FontElement{footsepline}, and \FontElement{footbotline} will be used. You may -change these using command \DescRef{\LabelBase.cmd.setkomafont} or -\DescRef{\LabelBase.cmd.addtokomafont} (see \autoref{sec:maincls.textmarkup} -from \DescPageRef{maincls.cmd.setkomafont}). By default those settings -are empty, which means no change of the current font or colour. Change of font -in opposite to colour would not make sense and is not recommended for these -elements.% -\EndIndex{FontElement}{footbotline}% -\EndIndex{FontElement}{footsepline}% -\EndIndex{FontElement}{headsepline}% -\EndIndex{FontElement}{headtopline}% - -\BeginIndex{Cmd}{setheadtopline}% -\BeginIndex{Cmd}{setheadsepline}% -\BeginIndex{Cmd}{setfootsepline}% -\BeginIndex{Cmd}{setfootbotline}% -Package \Package{scrpage2} has additionally to the options that do not take -any values, also four commands -\Macro{setheadtopline}\IndexCmd[indexmain]{setheadtopline}, -\Macro{setheadsepline}\IndexCmd[indexmain]{setheadsepline}, -\Macro{setfootsepline}\IndexCmd[indexmain]{setfootsepline}, and -\Macro{setfootbotline}\IndexCmd[indexmain]{setfootbotline}. These have a first -optional argument for the \PName{length}, a second mandatory argument for the -\PName{thickness}, and a third optional argument for the setting of font or -colour. Package \Package{scrlayer-scrpage} does also provide those -commands. Nevertheless, these commands are deprecated and should not be used -any longer. To get it clear: These commands have never been made to -switch the lines on or off. They have been made to configure already switched -on lines. Users often ignored this!% -\EndIndex{Cmd}{setfootbotline}% -\EndIndex{Cmd}{setfootsepline}% -\EndIndex{Cmd}{setheadsepline}% -\EndIndex{Cmd}{setheadtopline}% +In addition to the length and thickness, you can also change the colour of the +lines. Initially the colour depends on the colour of the header or footer. In +addition to this, however, the settings of the corresponding elements +\important[i]{\FontElement{headtopline}\\ + \FontElement{headsepline}\\ + \FontElement{footsepline}\\ + \FontElement{footbotline}} \FontElement{headtopline}, +\FontElement{headsepline}, \FontElement{footsepline} and +\FontElement{footbotline} are applied. You can +change these using the \DescRef{\LabelBase.cmd.setkomafont} or +\DescRef{\LabelBase.cmd.addtokomafont} commands (see +\autoref{sec:maincls.textmarkup}, \DescPageRef{maincls.cmd.setkomafont}). +By default these elements are empty, so they do not change the current font or +colour. Font changes at this point, unlike colour changes, make little sense +anyway and are therefore not recommended for these elements.% +\EndIndexGroup % \EndIndexGroup @@ -1123,10 +1154,10 @@ on lines. Users often ignored this!% \OptionVName{plainfootsepline}{simple switch}% \OptionVName{plainfootbotline}{simple switch} \end{Declaration} -These options can be used to inherit the settings of the lines also for the -\PageStyle{plain} page style. Possible values for \PName{simple switch} can be -found in \autoref{tab:truefalseswitch} on -\autopageref{tab:truefalseswitch}. If a option is activated, the +You can use these options to apply the settings for the lines to the +\PageStyle{plain} page style. You can find the available values for +\PName{simple switch} in \autoref{tab:truefalseswitch} on +\autopageref{tab:truefalseswitch}. If one of these options is activated, the \PageStyle{plain} page style will use the line settings given by the options and commands described above. If the option is deactivated, the \PageStyle{plain} will not show the corresponding line.% @@ -1138,14 +1169,14 @@ and commands described above. If the option is deactivated, the \Option{clines}% \Option{olines} \end{Declaration} -You have already been told that the horizontal lines above or below the page -head or foot can be shorter or longer than the page head or page foot -itself. Only the answer to the question about the alignment of those lines is -still missing. By default all lines are left aligned at single side layout and -aligned to the inner margin of the head or foot at double side layout. This -is same like using option \Option{ilines}. Alternatively, you can use option -\Option{clines} to centre the lines in the head or foot, or option -\Option{olines} to align them right respectively to the outer margin.% +As previously explained, dividing lines for the header or footer can be longer +or shorter than the width of the header or footer respectively. But the +question remains how these lines are aligned. By default, all lines are +aligned to the left margin in one-sided printing and to the inner margin in +two-sided printing. This corresponds to using the \Option{ilines} option. +Alternatively, you can use the \Option{clines} option to centre the lines with +respect to the width of the header or footer, or the \Option{olines} option to +align them to the outer (or right) margin.% \EndIndexGroup % \EndIndexGroup diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex index 77492066753..65c8cf865d6 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrlayer.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2013-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrlayer.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2013-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,111 +46,110 @@ % ============================================================================ \KOMAProvidesFile{scrlayer.tex} - [$Date: 2017-08-08 11:47:52 +0200 (Tue, 08 Aug 2017) $ + [$Date: 2018-02-28 13:23:23 +0100 (Wed, 28 Feb 2018) $ KOMA-Script guide (chapter:scrlayer)] -\translator{Markus Kohm} +\translator{Markus Kohm\and Karl Hagen} -% Date of the translated German file: 2017-08-08 +% Date of the translated German file: 2018-02-01 -\chapter[{Defining Layers and Page Styles Using \Package{scrlayer}}]% -{Defining Layers and Page Styles Using \Package{scrlayer}% -} +\chapter[{Defining Layers and Page Styles with \Package{scrlayer}}] + {Defining\ChangedAt{v3.12}{\Package{scrlayer}} Layers and Page Styles with + \Package{scrlayer}} \labelbase{scrlayer} + \BeginIndexGroup \BeginIndex{Package}{scrlayer}% \BeginIndex{}{layer}% -Most users of graphics software already know layer models for pages or working -sheets. \LaTeX{} itself does not know layers, but there are already packages -like \Package{eso-pic} or \Package{textpos}, that provide a kind of -background or foreground layer. \Package{scrlayer} is another package, -that provides such background and foreground layers, but in difference -to the other packages mentioned above these layers are part of the -page style definition. With this you may simply switch between usage -of layers by switching the page style. - -To do so, the package also supports a low level interface to define page -styles using a layer stack, to put layers onto a page style's layer stack, to -put layers at the lowest position of a page style's layer stack, to put layers -before or after a layer of a page style's layer stack, to remove a layer from -a page style's layer stack and to remove doublets of layers of a page style's -layer stack. In short words: The page style interface of \Package{scrlayer} -provides commands to define layer-stack-based page styles and to manage those -layer stacks. - -Nevertheless, using the layers directly is recommended for advanced users only. -End user interfaces for beginners or average users are provided by additional -packages, that load \Package{scrlayer} on their own. See +Most users of graphics software are already familiar with the layer model for +a page. Such a model is rather alien to \LaTeX{} itself, but some packages, +like \Package{eso-pic} or \Package{textpos}, provide a kind of +background or foreground layer. \Package{scrlayer} is another package that +provides such background and foreground layers, but unlike the packages +mentioned above, these layers are part of the page style. As a result, you can +switch between different layers simply by switching the page style. + +To do so, the package also supports a low-level interface for defining page +styles that are based on a stack or list of layers, for adding layers to such +a layer stack, either at the top or the bottom, or before or after a specific +layer, and for removing individual layers and duplicates from a stack. In a +nutshell, the page style interface of \Package{scrlayer} provides commands to +define page styles based on a stack of layers and to manage those stacks. + +Nevertheless, using the layers directly is recommended for advanced users +only. Interfaces for beginners and average users are provided by additional +packages that in turn load \Package{scrlayer}. See \autoref{cha:scrlayer-scrpage} in \autoref{part:forAuthors} of this \iffree{manual}{book}. -\section{State of Development Note} -\seclabel{draft} - -Development of this package has not been finished yet. Parts of the package -are even still experimental. Because of this, especially internal -functionality may be changed in future. Most likely the package will be -extended. And because of the early state of development, you should not expect -a complete and finished user manual. Nevertheless, this manual, which is -recommended for advanced users and developers, describes the current state of -development and the released parts of \Package{scrlayer}. Everything, not -documented here, should not be used for anything else but testing. \LoadCommonFile{options} % \section{Early or Late Selection of Options} -\section{Some Generic Information} -\seclabel{generic} +\section{Generic Information} +\seclabel{generic.information} -The package needs some generic information about the class. Class authors may -help \Package{scrlayer} by setting this information. Otherwise the package tries -to detect the information itself. This works, e.g., for the standard classes -and the \KOMAScript{} classes. But it may or may not fail with other classes. +The package needs some generic information about the class being used. Class +authors can help \Package{scrlayer} by providing the appropriate information. +Otherwise the package will try to determine this information for itself. This +works, for example, for the standard and the \KOMAScript{} classes. It may +work with other classes, or it may fail in whole or in part. -This section describes some of the information, that class authors may -provide. Generally users need not to care about this. +This section describes some of the information that class authors can provide. +Normally, users should not have to worry about it. \begin{Declaration} \Macro{if@chapter}\ \PName{then code}\ \textMacro{else}\ % \PName{else code}\ \textMacro{fi}% \end{Declaration} -If \Macro{if@chapter} is \Macro{iftrue}, \Package{scrlayer} will additionally -consider the chapter level, e.g., processing option -\DescRef{\LabelBase.option.automark}. If it is defined, but differs from -\Macro{iftrue}, only part, section, subsection, sub\dots subsection, -paragraph, subparagraph, sub\dots subparagraph will be considered. If the -macro is not defined, \Package{scrlayer} searches for -\DescRef{maincls.cmd.chapter}. If \DescRef{maincls.cmd.chapter} is defined and -not \Macro{relax}, \Package{scrlayer} will define \Macro{if@chapter} to -\Macro{iftrue}, otherwise \Macro{if@chapter} will become \Macro{iffalse}.% +If \Macro{if@chapter} is defined and corresponds to +\Macro{iftrue}\IndexCmd{iftrue}, \Package{scrlayer} takes the chapter level +into account when, for example, processing the +\DescRef{\LabelBase.option.automark} option. If it is defined but is not +\Macro{iftrue}, \Package{scrlayer} handles only the +\DescRef{maincls.cmd.part}, \DescRef{maincls.cmd.section}, +\DescRef{maincls.cmd.subsection}, \Macro{sub\dots subsection}, +\DescRef{maincls.cmd.paragraph}, \DescRef{maincls.cmd.subparagraph}, +\Macro{sub\dots subparagraph} sectioning units. If the macro is undefined, +\Package{scrlayer} searches for \DescRef{maincls.cmd.chapter}. If +\DescRef{maincls.cmd.chapter} is defined and does not correspond to +\Macro{relax}, \Package{scrlayer} defines \Macro{if@chapter} to +\Macro{iftrue}. Otherwise \Macro{if@chapter} becomes +\Macro{iffalse}\IndexCmd{iffalse}.% \EndIndexGroup \begin{Declaration} - \Macro{if@mainmatter}\ \PName{then code}\ \textMacro{else}\ % - \PName{else code}\ \textMacro{fi}% + \Macro{if@mainmatter}\ \PName{then code}\ % + \textMacro{else}\ \PName{else code}\ \textMacro{fi}% \end{Declaration} -Classes like \Class{book} define \DescRef{maincls.cmd.frontmatter}, -\DescRef{maincls.cmd.mainmatter}, and \DescRef{maincls.cmd.backmatter}. They -also use \Macro{if@mainmatter} to distinguish whether or not the current -matter is the main matter. Classes like \Class{report} and \Class{article} do -not have \DescRef{maincls.cmd.frontmatter}, \DescRef{maincls.cmd.mainmatter}, -or \DescRef{maincls.cmd.backmatter} and therefore also do not have -\Macro{if@mainmatter}. - -For \Package{scrlayer} it's easier not to test always for the existence of the -matter commands, but to use \Macro{if@mainmatter} even with classes like -\Class{report} and \Class{article}, simply set to \Macro{iftrue}. So if -\Macro{if@mainmatter} is not defined, it will be defined to \Macro{iftrue}. - -Some classes have \DescRef{maincls.cmd.frontmatter}, +Classes like \Class{book} or \Class{scrbook} provide +\DescRef{maincls.cmd.frontmatter}\IndexCmd{frontmatter}, +\DescRef{maincls.cmd.mainmatter}\IndexCmd{mainmatter}, and +\DescRef{maincls.cmd.backmatter}\IndexCmd{backmatter} to switch between the +front, main, and end parts of a book. Typically, these classes also use +\Macro{if@mainmatter} internally to decide whether the current text is part of +the main body of the document or not. Classes like \Class{report} and +\Class{article} have no \DescRef{maincls.cmd.frontmatter}, +\DescRef{maincls.cmd.mainmatter}, or \DescRef{maincls.cmd.backmatter} and +therefore also lack \Macro{if@mainmatter}. + +It is easier for \Package{scrlayer} to avoid constantly testing for the +existence of these commands to decide whether to work in the main matter or +not, and instead to use \Macro{if@mainmatter}\IndexCmd{iftrue} with classes +like \Class{report} and \Class{article}. So if \Macro{if@mainmatter} is not +defined, \Package{scrlayer} defines it as a synonym for \Macro{iftrue}. + +Some classes, however, define \DescRef{maincls.cmd.frontmatter}, \DescRef{maincls.cmd.mainmatter}, or \DescRef{maincls.cmd.backmatter} but not -\Macro{if@mainmatter}. In this case \Package{scrlayer} also defines +\Macro{if@mainmatter}. In this case, \Package{scrlayer} also defines \Macro{if@mainmatter} to be \Macro{iftrue} and it extends definition of \DescRef{maincls.cmd.frontmatter}, \DescRef{maincls.cmd.mainmatter}, and -\DescRef{maincls.cmd.backmatter} to set \Macro{if@mainmatter} properly. Other -matter commands are not known, not tested, and not extended. So if there are -other matter commands \Package{scrlayer} needs help of the class author to set -\Macro{if@mainmatter} correctly.% +\DescRef{maincls.cmd.backmatter} to set \Macro{if@mainmatter} properly. +However, if there are other, comparable commands for switching between +different document parts. \Package{scrlayer} will not recognize them, does not +test for them, and therefore cannot extend them appropriately. In this case, +\Package{scrlayer} needs help of the class author to set \Macro{if@mainmatter} +correctly.% \EndIndexGroup @@ -158,103 +157,115 @@ other matter commands \Package{scrlayer} needs help of the class author to set \Macro{DeclareSectionNumberDepth}\Parameter{level name}% \Parameter{level depth} \end{Declaration} -Generally each section level is related to an integer number indicating its -depth in the document structure. \LaTeX{} needs this to manage hierarchic -section levels. But normally only the document class, that defines the section -commands, itself knows that \PName{level depth} of a section level and uses -these numerical values inside the corresponding commands, when needed. - -But \Package{scrlayer} also needs information about the section hierarchy. -With command \Macro{DeclareSectionNumberDepth} you can map -the name of a heading level to a \PName{level depth}. With standard class -book, e.g., the \PName{level name} could be \PValue{part}, \PValue{chapter}, -\PValue{section}, \PValue{subsection}, \PValue{subsubsection}, -\PValue{paragraph}, or \PValue{subparagraph} and the corresponding -\PName{level depth}s would be -1, 0, 1, 2, 3, 4, and 5. - -Package \Package{scrlayer} tries to determine the \PName{level depth}s on its -own while loading and again while \Macro{begin}\PParameter{document}. But, if -it fails, i.\,e., if completely different section commands are used, it would -be useful, to be able to define the relationship explicitly. For such cases -\Macro{DeclareSectionNumberDepth} gives the class author the opportunity to -define the relationship explicitly.% +Generally each section level is assigned an integer number indicating its +depth in the document structure. \LaTeX{} needs this to manage the hierarchy +of the section levels. But normally these values are known only to the +particular class that defines the section commands. This class then uses the +appropriate numbers inside the corresponding commands. + +The \Package{scrlayer} package also needs information about the section +hierarchy. With the help of \Macro{DeclareSectionNumberDepth}, you can map the +name of a heading level to a corresponding \PName{level depth}. For example, +for the standard \Class{book} class, the \PName{level name}s would be +\PValue{part}, \PValue{chapter}, \PValue{section}, \PValue{subsection}, +\PValue{subsubsection}, \PValue{paragraph}, and \PValue{subparagraph}, and the +corresponding \PName{level depth}s would be -1, 0, 1, 2, 3, 4, and 5. + +The \Package{scrlayer} package tries to determine the \PName{level depth}s on +its own while loading and again during \Macro{begin}\PParameter{document}. But +if this fails, for example because you use completely different sectioning +commands, you can define the relationship explicitly with +\Macro{DeclareSectionNumberDepth}.% \EndIndexGroup -\section{Declaration of Layers} +\section{Declaring Layers} \seclabel{layers} -A layer is a kind of virtual sheet of transparent paper (in opposite to a -physical sheet of paper). One layer is stacked onto another layer and opaque -material on one layer may hide material on the layers below. The stack of all -layers together makes the physical page. Package \Package{scrlayer} -provides two such layer stacks for each page: a background layer stack and a -foreground layer stack. The background layer stack is behind the normal page -contents, the foreground layer stack is above the normal page contents. So the -normal contents is a kind of a separating layer between the background layer -stack and the foreground layer stack. - -A layer has several attributes, which are the answers to some basic questions: -\begin{description} -\item[Is the layer part of the background or the - foreground?\textnote{background or foreground}]% - During page building background layers will be printed first, followed by - the main contents and the foreground layers. Therefore, in the output the - background layers show up behind the main contents and the foreground layers - in front of the main contents. By default, a layer is both, a background - layer \emph{and} a foreground layer and therefore will be printed - twice. Normally, it makes sense to restrict the layer in this aspect. -\item[What is the position of the layer?\textnote{horizontal and vertical - position}]% - There are some attributes to define the horizontal and the vertical position - of a layer. -\item[What is the size of the layer?\textnote{horizontal and vertical size}]% - As for the position there are several attributes to define the width and - height of a layer. So a layer can also be smaller or larger than the paper - and it can be placed everywhere on the paper. -\item[How is a layer aligned on the paper?\textnote{alignment}]% - This question is answered by the alignment attribute. The horizontal position - can be relative from the left edge of the paper either to the left edge of - the layer or to the centre of the layer or to the right edge of the - layer. Also the vertical position can be relative from the to edge of the - paper either to the top edge of the layer or to the centre of the layer or - to the bottom edge of the layer. -\item[Is the layer intended for text or picture output?\textnote{text or - picture}]% - This question is also related to the position. For picture output users - often expect the origin at the bottom left corner of the layer. But this - would not be suitable for text output. So the origin of a text layer is the - height of a standard text line below the top left corner of the - layer. Picture layers on the other hand span a - \Environment{picture}\IndexEnv{picture} environment and provide addition - positioning commands. -\item[Should the layer be printed on left or right pages?\textnote{left or - right page}]% - By default a layer will be printed on both, left and right pages. Note, that - \LaTeX{} names left pages as even pages and right pages as odd pages and - that there are no left or even pages in single-sided mode. -\item[Should the layer be printed in single-side mode or two-side - mode?\textnote{single-side or two-side}]% - By default a layer will be printed in both, single-side mode and two-side - mode. Nevertheless, an even page layer will never be printed in single-side - mode and therefore is not really a two-side mode layer. -\item[Should the layer be printed on float pages or non-float - pages?\textnote{float page or non-float page}]% - \LaTeX{} produces float pages for float environments like tables or figures, - if they are allowed to be printed on a page without normal page contents - (see option \PValue{p} for \Environment{figure} or \Environment{table}). So - from some point of view a float page is a page, that may itself - flow. Non-float pages are not pages without floats, but pages, that are not - float pages. They may contain floats inside the text, on the top of the - page, or on the bottom of the page. Very large floats may seem to be page - floats, while in reality they are top floats. -\item[What are the contents of the layer?\textnote{contents}]% - The corresponding attribute are the commands that produce the output. -\end{description} -So we have eight questions that immediately result in attributes yet. Below in -this manual we will describe additional attributes. However, they are just -defined for convenience and can be expressed by a combination of these primary -attributes. +A layer is an abstract model of a page. Unlike a real, physical sheet of +paper, this page is completely transparent. Typically, multiple layers are +stacked atop one another and opaque material on one layer hides material on +the layers below. The stack of layers is then merged to form the physical +page. The \Package{scrlayer} package provides two such stacks for each page: a +background stack and a foreground stack. The background stack is printed +beneath the normal page content, while the foreground stack is printed above +it. The normal page content is therefore a kind of a dividing layer between +the two layer stacks. + +A layer has several attributes that can be understood as answers to some basic +questions: +\iffree{\begin{description}}{% + \begingroup + \RedeclareSectionCommand[beforeskip=.5\baselineskip plus .25\baselineskip + minus .1\baselineskip]{paragraph}% + \renewcommand*\item[4][]{\paragraph*{#3{#4}#1}}% + }% +\item[Does the layer belong to the foreground or the background?]% + \leavevmode\textnote{foreground or background}\hskip 0pt + Background layers are output before the normal content of the page. + Therefore they appear behind or beneath the normal content of the page. + Foreground layers are then output after the normal content. Therefore they + appear on top of the normal content of the page. By default, a layer is both + a background layer \emph{and} a foreground layer and therefore is printed + twice. Usually it makes sense to limit the layer explicitly to either the + foreground or the background. +\item[What is the position of the layer?]% + \leavevmode\textnote{horizontal and vertical position}\hskip 0pt + To answer this question, there are attributes to define the layer's + horizontal and vertical position. +\item[How big is the layer?\textnote{horizontal and vertical size}]% + As with the position, there are also attributes to define the width and + height of a layer. Thus a layer can be smaller or larger than the paper + and it can be placed at different positions on the paper. +\item[How are the horizontal and vertical positions measured?]% + \leavevmode\textnote{alignment}\hskip 0pt + This question is answered by the alignment attribute. The horizontal + position can be measured from the left edge of the paper to the left edge of + the layer, to the centre of the layer, to the right edge of the layer. + Similarly, the vertical position can be measured from the top edge of the + paper to the top edge of the layer, the centre of the layer, or the bottom + edge of the layer. +\item[Is the layer intended for text or picture output?]% + \leavevmode\textnote{text or picture}\hskip 0pt + This question is closely related to the position. For example, users often + expect the origin for a picture to be at the lower left corner of the layer. + But this would not be suitable for text output. Therefore the origin of a + text layer is the height of a standard text line below the top left corner + of the layer. Picture layers, on the other hand, create a + \Environment{picture}\IndexEnv{picture} environment in which additional + positioning commands are available. +\item[Should the layer be printed on left or right pages?]% + \leavevmode\textnote{left or right page}\hskip 0pt + By default a layer will be printed on all pages. Note that \LaTeX{} treats + even pages as left-side pages and odd pages as right-side pages, but in + one-sided printing, only right-hand pages exist regardless of the page + number. +\item[Should the layer be printed in one-sided or two-sided mode?]% + \leavevmode\textnote{one-sided or two-sided}\hskip 0pt + By default a layer will be printed in both one-sided and two-sided + printing. Nonetheless, a layer that is restricted to even pages will never + be printed in one-sided printing and therefore is not a one-sided layer. +\item[Should the layer be printed on float pages or normal pages?]% + \leavevmode\textnote{float page or normal page}\hskip 0pt + \LaTeX{} produces float pages for objects from environments like tables or + figures if they are allowed to appear on a page without normal page contents + (see option \PValue{p} for \Environment{figure} or \Environment{table}). In + effect, the entire page is allowed to float within the document. Normal + pages in this sense are all pages that are not float pages. Normal pages can + also contain floats at the top, in the middle, or at the bottom of the page. + Very large floats can give the impression of being page floats, while in + reality they are floating environments placed at the top of a normal page. +\item[What are the contents of the layer?]% + \leavevmode\textnote{contents}\hskip 0pt + The corresponding attribute simply contains what should be printed whenever + the layer is output. +\iffree{\end{description}}{% + \endgroup\par\bigskip\noindent\ignorespaces +}% +These eight questions immediately give rise to a number of attributes. Later +\iffree{in this guide}, we will describe additional attributes. However, they +are only defined for convenience and can be expressed by a combination of +these primary attributes. \begin{Declaration} @@ -264,100 +275,96 @@ attributes. \Macro{RedeclareLayer}\OParameter{option list}\Parameter{layer name}% \Macro{ModifyLayer}\OParameter{option list}\Parameter{layer name} \end{Declaration} -These commands can be used to define a layer. The \PName{layer name} has to be -fully expandable and should expand to letters only. Some additional characters -are tolerated, but are not recommended. +These commands can be used to define layers. The \PName{layer name} must be +fully expandable and should expand to ASCII letters only. Some additional +characters are accepted, but their use is only recommended for advanced users. -Command \Macro{DeclareLayer} does not care whether or not a layer with the +The \Macro{DeclareLayer} command does not care whether or not a layer with the given \PName{layer name} already exists. It will under all circumstances -define the layer with the attribute defined by the \PName{option list}. An -\PName{option} can be either a key or a key followed by an equal sign followed -by a value. Several options may be concatenated to a \PName{option list} and -have to be separated by comma. If you'd like to have a comma or a white space -inside the value of an option, you should put the value inside curly +define the layer with the attributes specified in the \PName{option list}. An +\PName{option} can be either a key or a key followed by an equal sign and +a value. Multiple options are separated by commas. To use a comma or a white +space within the value of an option, you must put the value inside curly brackets. See \autoref{tab:scrlayer.layerkeys} for more information on keys, values, and the corresponding attributes. -In contrast to \Macro{DeclareLayer} using \Macro{DeclareNewLayer} results in -an error, if a layer with the same \PName{layer name} already exists. So you -may prevent yourself using the same \PName{layer name} more than once by -mistake. This would be useful, e.\,g., if a class or package also defines -layers internally. - -If you use \Macro{ProvideLayer} instead of \Macro{DeclareLayer}, the -declaration will be ignored in case a layer with the same layer name already -exists. It could be paraphrased by: \emph{declare the layer only if it has not - been declared already.} - -If an existing layer should be redefined, \Macro{RedeclareLayer} or -\Macro{ModifyLayer} can be used. \Macro{RedeclareLayer} would simply define -the layer as if it would be defined newly. In difference to this, -\Macro{ModifyLayer} would change only those attributes, that are represented -by an option of the \PName{option list}. All other attributes will stay -unchanged and will not be reset to the initial default value. Using either -\Macro{RedeclareLayer} or \Macro{ModifyLayer} will result in an error, in case -there has not been a layer with \PName{layer name} defined before. +Unlike \Macro{DeclareLayer}, \Macro{DeclareNewLayer} reports an error if a +layer with the same \PName{layer name} already exists. This prevents the user +from accidentally using the same \PName{layer name} more than once. This +is especially useful when classes or packages also define layers internally. + +In contrast, \Macro{ProvideLayer} only defines a layer if there is no layer +with the same name already. If the name is in use for another layer, the new +definition is ignored. Therefore this command has the meaning, \emph{define + the layer only if it does not already exist.} + +If you want to redefine an existing layer, you can use \Macro{RedeclareLayer} +or \Macro{ModifyLayer}. With \Macro{RedeclareLayer}, the layer is first reset +to the default settings and then completely redefined via the specified +options list. In contrast, \Macro{ModifyLayer} does not reset the layer. +Only those attributes which are explicitly set in the \PName{option list} will +be changed. Applying either command to a previously undefined \PName{layer + name} results in an error. \begin{desclist} \desccaption{% - Options for the definition of page layers with description of the + Options for defining page layers and the meaning of the corresponding layer attribute\label{tab:scrlayer.layerkeys}% }{% - Options for the definition of layers (\emph{Continuation})% + Options for defining layers (\emph{continued})% }% \entry{% \ChangedAt{v3.16}{\Package{scrlayer}}% \OptionVName{addcontents}{Code}}{% - Value \PName{code} will be added (or appended) at the very end of the - current value of attribute \Option{contents}. So the new content will be - generated behind the end of the already existing content. For more - information about the handling of \PName{code} see option - \Option{contents}.% + The specified \PName{code} will be appended to the current value of the + \Option{contents} attribute, so the new content will appear at the end of + the existing content. For more information about the handling of + \PName{code} see the \Option{contents} option.% }% \entry{% \ChangedAt{v3.16}{\Package{scrlayer}}% \OptionVName{addheight}{additional height}}{% - The current value of attribute \Option{height} will be increased by the - value of this option. You can use the same kind of values as for + The current value of the \Option{height} attribute will be increased by + the value of this option. You can use the same kind of values as for \Option{height}.% }% \entry{% \ChangedAt{v3.16}{\Package{scrlayer}}% \OptionVName{addhoffset}{additional horizontal offset}}{% - The current value of attribute \Option{hoffset} will be increased by the - value of this option. You can use the same kind of values as for + The current value of the \Option{hoffset} attribute will be increased by + the value of this option. You can use the same kind of values as for \Option{hoffset}.% }% \entry{% \ChangedAt{v3.16}{\Package{scrlayer}}% \OptionVName{addvoffset}{additional vertical offset}}{% - The current value of attribute \Option{voffset} will be increased by the - value of this option. You can use the same kind of values as for + The current value of the \Option{voffset} attribute will be increased by + the value of this option. You can use the same kind of values as for \Option{voffset}.% }% \entry{% \ChangedAt{v3.16}{\Package{scrlayer}}% \OptionVName{addwidth}{additional width}}{% - The current value of attribute \Option{width} will be increased by the - value of this option. You can use the same kind of values as for + The current value of the \Option{width} attribute will be increased by + the value of this option. You can use the same kind of values as for \Option{width}.% }% \nentry{\KOption{align}{\PName{alignment characters}}}{% The \PName{alignment characters} define the desired alignment of the - layer. Each \PName{alignment character} influences either, how argument - \PName{length} of option \Option{hoffset} or \Option{voffset} will be - used. Several \PName{alignment characters} may be used together (without - comma or space) and will be interpreted in the order of occurrence. No - macros should be used here! Valid \PName{alignment character}s are: + layer. Each \PName{alignment character} determines how the \PName{length} + of either the \Option{hoffset} or the \Option{voffset} option is + interpreted. Multiple \PName{alignment character}s can be used together + (without spaces or commas) and are evaluated in the order they occur. + Macros are not permitted in the value of the option. Valid + \PName{alignment character}s are: \begin{description} - \item[\PValue{b} --] align the layer at its bottom edge; the - value of - \Option{voffset} is interpreted as the distance from the top edge of the - paper to the bottom edge of the layer. + \item[\PValue{b} --] align the layer at its bottom edge; the value of + \Option{voffset} is the distance from the top edge of the paper to the + bottom of the layer. \item[\PValue{c} --] align the layer at its centre; the values of \Option{voffset} and \Option{hoffset} are interpreted as the distance from the top left corner of the paper to the centre of the layer. - \item[\PValue{l} --] align the layer at its left edge: the value of + \item[\PValue{l} --] align the layer at its left edge; the value of \Option{hoffset} is interpreted as the distance from the left edge of the paper to the left edge of the layer. \item[\PValue{r} --] align the layer at its right edge; the value of @@ -371,228 +378,227 @@ there has not been a layer with \PName{layer name} defined before. \entry{\KOption{area}{% \Parameter{hoffset}\Parameter{voffset}% \Parameter{width}\Parameter{height}}}{% - The composed option results in \OptionValue{hoffset}{\PName{hoffset}}, - \OptionValue{voffset}{\PName{voffset}}, - \OptionValue{width}{\PName{width}}, \OptionValue{height}{\PName{height}}.% + This composite option sets the primary attributes + \OptionValue{hoffset}{horizontal offset}, \OptionValue{voffset}{vertical + offset}, \OptionValue{width}{width}, \OptionValue{height}{height}.% }% \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% \Option{backandforeground}}{% - This option removes any foreground or background restriction of the layer. - Generally usage of this option makes no sense, but it is provided for - completeness of the user interface. The option does not expect any value.% + This option removes the restriction of a layer to the foreground or the + background. In general, this option makes little sense, but it is provided + for the sake of a complete user interface. This option does not expect or + allow a value.% }% \entry{\Option{background}}{% - Print the layer only in the background, but not in the foreground. This - makes a background-only layer in opposite to the default of layers which - are both, background and foreground layers and therefore would be printed - twice. The option does not expect any value. By the default the attribute - is not set.% + This option displays the layer in the background only. The default is to + display layers in both the background and the foreground. This option does + not expect or allow a value.% }% \entry{\Option{bottommargin}}{% - The composed option sets \Option{hoffset}, \Option{voffset}, - \Option{width}, \Option{height}, and \Option{align} to horizontally span - the paper from the left edge to the right and vertically span the area - below the footer down to the bottom edge of the paper.% + This composite option sets the primary attributes \Option{hoffset}, + \Option{voffset}, \Option{width}, \Option{height}, and \Option{align} so + that the layer spans the paper horizontally from the left edge to the + right and vertically from immediately beneath the footer to the bottom + edge of the paper.% }% \entry{\KOption{clone}{\PName{layer name}}}{% - The composed option sets all primary attributes of the layer to the same + This composite option sets all primary attributes of the layer to the same values as the primary attributes of the layer with the given \PName{layer - name}. Note, that \PName{layer name} has to be fully expandable and - should expand to letters only. Some additional characters are tolerated, - but are not recommended!% + name}. See the notes on the \PName{layer name} at the beginning of the + explanation for \Macro{DeclareLayer}. The layer to be cloned must also + already exist.% }% \entry{\KOption{contents}{\PName{code}}}{% - The \PName{code} will be expanded whenever the layer is printed. So the - \PName{code} is what you will see. Code validity is not checked. So errors - in \PName{code} may result in several failures on each page, that prints - the layer.% + The specified \PName{code} will be expanded whenever the layer is printed. + This \PName{code} defines what you see for the layer. No tests are made to + see if the code is valid. Errors in the \PName{code} can therefore lead to + multiple error messages on each page that prints the layer.% }% \entry{\Option{evenpage}}{% - Print the layer on even pages only, but not on odd pages. The option does - not expect any value. By the default the option is not set and therefore - layers would be printed on odd pages and on even pages. Note, that this - attribute subsumes \Option{twoside}.% + This option causes the layer to appear on even pages only, unlike the + default, where a layer will appear on both even and odd pages. Since even + pages only appear in two-sided printing, this option implies + \Option{twoside}. This option does not expect or allow a value.% }% \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% \Option{everypage}}{% - This is a combination of \Option{oddorevenpage} and - \Option{floatornonfloatpage}. The option does not expect any value.% + This option is a combination of \Option{oddorevenpage} and + \Option{floatornonfloatpage}. This option does not expect or allow a + value.% }% \entry{\Option{everyside}}{% - This option removes any restriction of the layer to single side or double - side printing. This is also the default of layers. The option does not - expect any value.% + This option removes any restriction of the layer to one-sided or two-sided + printing. This is the default setting. This option does not expect or + allow a value.% }% \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% \Option{floatornonfloatpage}}{% This option removes any restriction of the layer to float or non-float - pages. So the layer will be printed independent of whether a page is a - float page or not. This is also the default of layers. The option does - not expect any value.% + pages and restores the default setting. This option does not expect or + allow a value.% }% \entry{\Option{floatpage}}{% - Print the layer on float pages only, but not on other pages. The option - does not expect any value. By the default the attribute is not set and - therefore layers would be printed on float pages and on non-float pages.% + This option restricts the layer to appearing on float pages only. The + default setting is for layers to appear on both float and non-float pages. + This option does not expect or allow a value.% }% \entry{\Option{foot}}{% - The composed option sets \Option{hoffset}, \Option{voffset}, - \Option{width}, \Option{height}, and \Option{align} to horizontally span - the text area and vertically span the page footer defined by the new - \LaTeX{} length \Length{footheight}.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the page footer over the width of the text area. This option does + not expect or allow a value.% }% \entry{\Option{footskip}}{% - The composed option sets \Option{hoffset}, \Option{voffset}, - \Option{width}, \Option{height}, and \Option{align} to horizontally span - the text area and vertically span the distance between the text area and - the page footer (note, that this is not the same like \Length{footskip}).% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the vertical distance between the text area and the page footer over + the width of the text area. Note, however, that although the height of + this area depends on \Length{footskip}, it is not the same. This option + does not expect or allow a value.% }% \entry{\Option{foreground}}{% - Print the layer only in the foreground, but not in the background. This - makes a foreground-only layer in opposite to the default of layers which - are both, background and foreground layers and therefore would be printed - twice. The option does not expect any value. By the default the attribute - is not set.% + This option displays the layer in the foreground only. The default is to + display layers in both the background and the foreground. The option does + not expect or allow a value.% }% \entry{\Option{head}}{% - The composed option sets \Option{hoffset}, \Option{voffset}, - \Option{width}, \Option{height}, and \Option{align} to horizontally span - the text area and vertically span the page head defined by usual \LaTeX{} - length \Length{headheight}.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the vertical area of the page header for the width of the text area. + The height corresponds to the length \Length{headheight}. This option does + not expect or allow a value.% }% \entry{\Option{headsep}}{% - The composed option sets \Option{hoffset}, \Option{voffset}, - \Option{width}, \Option{height}, and \Option{align} to horizontally span - the text area and vertically span the distance between the page head and - the text area.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the vertical distance between the page header and the text area for + the width of the text area. The height corresponds to the length + \Length{headsep}. This option does not expect or allow a value.% }% \entry{\KOption{height}{\PName{length}}}{% - Sets the height of the layer. Note, that \PName{length} can either be a - \LaTeX{} length, declared using \Macro{newlength}, or a \TeX{} length, - declared using \Macro{newdimen} or \Macro{newskip}, a length value like - 10\,pt, or a dimensional expression using +, -, /, *, (, and ). For more - information about valid dimensional expressions see - \cite[section~3.5]{manual:eTeX}.% + Sets the height of the layer. Note that the \PName{length} can be a + \LaTeX{} length declared with \Macro{newlength}, a \TeX{} length declared + with \Macro{newdimen} or \Macro{newskip}, a length value like 10\,pt, or a + dimensional expression using +, -, /, *, (, and ). For more information + about valid dimensional expressions see \cite[section~3.5]{manual:eTeX}.% }% \entry{\KOption{hoffset}{\PName{length}}}{% - Sets the offset of the layer (depending on \Option{align} either left edge - of the layer, middle of the layer or right edge of the layer) from the - left edge of the paper. See \Option{height} for more information about - valid content of \PName{length}.% + Sets the distance of the layer from the left edge of the paper. How the + distance is measured depends on the \Option{align} option. See the + \Option{height} option for more information about valid expressions for + \PName{length}.% }% \entry{\Option{innermargin}}{% - The composed option sets \Option{hoffset}, \Option{voffset}, - \Option{width}, \Option{height}, and \Option{align} to horizontally span - the distance between the right edge of text area and the right edge of the - paper on even pages or the distance between the left edge of the paper and - the left edge of the text area on odd pages and vertically span the whole - paper from the top edge to the bottom edge.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the inner margin, from the edge of the page to the edge of the text + area and from the top to the bottom of the page. In one-sided printing, + the inner margin corresponds to the left margin. This option does not + expect or allow a value.% }% \entry{\Option{leftmargin}}{% - The composed option sets \Option{hoffset}, \Option{voffset}, - \Option{width}, \Option{height}, and \Option{align} to horizontally span - the distance between the left edge of the paper and the left edge of the - text area and vertically span the whole paper from the top edge to the - bottom edge.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the left margin, from the left edge of the paper to the left edge of + the text area and from the top of the paper to the bottom. This option + does not expect or allow a value.% }% \entry{\ChangedAt{v3.19}{\Package{scrlayer}}% \OptionVName{mode}{mode}}{% - The primary option defines the \PName{mode} for the layer output. Default - is \OptionValue{mode}{text}. The Baseline of the first text line will be - placed the height of one standard text line below the top edge of the - layer. Therefore the text output will be top aligned in the layer. In - \PValue{picture} \PName{mode} the layer spans a \Environment{picture} - environment with the origin in the bottom left corner of the layer. The - also available \PValue{raw} \PName{mode} current is the same like - \PValue{text} \PName{mode}. - - Changing\textnote{Attention!} the \PName{mode} of a layer generally can - move the contents. Additionally, i.\,e., \PValue{picture} \PName{mode} + This primary option defines the \PName{mode} in which the layer's content + is output. The default is \OptionValue{mode}{text}. The baseline of the + first text line is placed the height of one standard text line below the + top edge of the layer, so the text is usually neatly aligned with the top + of the layer. In \PValue{picture} \PName{mode}, on the other hand, the + layer spans a \Environment{picture} environment with the origin at the + bottom left corner of the layer. The \PValue{raw} \PName{mode} is also + also defined. By default it corresponds to \PValue{text} \PName{mode}. + Changing\textnote{Attention!} the \PName{mode} of a layer usually results + the contents shifting. Furthermore, the \PValue{picture} \PName{mode} provides additional commands that result in errors with another - \PName{mode}. Therefore, generally it makes no sense to change the - \PName{mode} of a layer after it's initial declaration!% + \PName{mode}. Therefore it usually makes no sense to change the + \PName{mode} of a layer after its initial declaration!% }% \entry{\Option{nonfloatpage}}{% - Restricts the layer to pages, that are not float pages. The option does - not expect any value. By the default the attribute is not set and - therefore layers would be printed on float pages and on non-float pages.% + This option restricts the layer to pages that are not float pages. The + default is for the layer to appear on both float and non-float pages. This + option does not expect or allow a value.% }% \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% \Option{oddorevenpage}}{% - Removes any restriction of the layer to odd or even pages. So it will be - printed independently of whether a page is odd or even. This is also the - default of layers. The option does not expect any value.% + This option removes any restriction of the layer to odd or even pages, + restoring the default behaviour that the layer should appear on both odd + and even pages. The option does not expect or allow a value.% }% \entry{\Option{oddpage}}{% - Print the layer on odd pages only, but not on even pages. The option does - not expect any value. By the default the option is not set and therefore - layers would be printed on odd pages and on even pages.% + This option restricts the layer to odd pages only. The default is for + layers to appear on both odd pages and on even pages. Note that in + one-sided printing, all pages are odd, regardless of the page number. This + option does not expect or allow a value.% }% \entry{\Option{oneside}}{% - Print the layer in single-side mode only, but not in two-side mode. The - option does not expect any value. By the default the attribute is not set - and therefore layers would be printed in single-side and two-side mode.% + This option restricts the layer to one-sided printing only. The default is + for layers to appear in both one-sided and two-sided printing. This option + does not expect or allow a value.% }% \entry{\Option{outermargin}}{% - The composed option sets \Option{hoffset}, \Option{voffset}, - \Option{width}, \Option{height}, and \Option{align} to horizontally span - the distance between the left edge of the paper and the left edge of the - text area on even pages or the distance between the right edge of the text - area and the right edge of the paper on odd pages and vertically span the - whole paper from the top edge to the bottom edge.% + The composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the outer margin of the page, from the top to the bottom of the + paper. The outer margin corresponds to the right margin in one-sided + printing. This option does not expect or allow a value.% }% \entry{\Option{page}}{% - The composed option sets \Option{hoffset}, \Option{voffset}, - \Option{width}, \Option{height}, and \Option{align} to horizontally and - vertically span the whole paper from the left edge to the right edge and - the top edge to the bottom edge.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the the whole paper. This option does not expect or allow a value.% }% \entry{\ChangedAt{v3.16}{\Package{scrlayer}}% \OptionVName{pretocontents}{code}}{% - Value \PName{code} will be added at the very beginning of the current - value of attribute \Option{contents}. So the new content will be generated - in front of the already existing content. For more information about the - handling of \PName{code} see option \Option{contents}.% + The value of \PName{code} is prefixed the current value of the + \Option{contents} attribute, so the new content will appear before the + existing content. For more information about the handling of \PName{code}, + see the \Option{contents} option.% }% \entry{\Option{rightmargin}}{% - The composed option sets \Option{hoffset}, \Option{voffset}, - \Option{width}, \Option{height}, and \Option{align} to horizontally span - the distance between the right edge of text area and the right edge of the - paper and vertically span the whole paper from the top edge to the bottom - edge.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the right margin, from the right edge of the text area to the right + edge of the paper and from the top to the bottom edge of the paper. This + option does not expect or allow a value.% }% \entry{\Option{textarea}}{% - The composed option sets \Option{hoffset}, \Option{voffset}, - \Option{width}, \Option{height}, and \Option{align} to horizontally and - vertically span the whole text area from the left edge to the right edge - and the top edge to the bottom edge.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the entire text area. This option does not expect or allow a value.% }% \entry{\Option{topmargin}}{% - The composed option sets \Option{hoffset}, \Option{voffset}, - \Option{width}, \Option{height}, and \Option{align} to horizontally span - the whole page from the left edge to the right edge and vertically span - the distance between the top edge of the paper and the page head.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the vertical distance between the top edge of the paper to the + header for the entire width of the paper. This option does not expect or + allow a value.% }% \entry{\Option{twoside}}{% - Print the layer in two-side mode only, but not in single-side mode. The - option does not expect any value. By the default the attribute is not set - and therefore layers would be printed in single-side and two-side mode.% + This option restricts the layer to two-sided printing. The default is for + layers to appear in both one-sided and two-sided printing. This option + does not expect or allow a value.% }% \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% \Option{unrestricted}}{% - This option removes all output restrictions of the layer. It is a - combination of \Option{backandforeground}, \Option{everyside}, and - \Option{floatornonfloatpage}. The option does not expect any value.% + This option removes all output restrictions. It is a combination of + \Option{backandforeground}, \Option{everyside}, and + \Option{floatornonfloatpage}. This option does not expect or allow a + value.% }% \entry{\KOption{voffset}{\PName{length}}}{% - Sets the offset of the layer (depending on \Option{align} either top edge - of the layer, middle of the layer or bottom edge of the layer) from the - top edge of the paper. See \Option{height} for more information about - valid content of \PName{length}.% + Sets the distance of the layer from the top of the paper. How the distance + is measured depends on the \Option{align} option. See the \Option{height} + option for more information about valid expressions for \PName{length}.% }% \entry{\KOption{width}{\PName{length}}}{% - Sets the width of the layer. See \Option{height} for more information - about valid content of \PName{length}.% + Sets the width of the layer. See the \Option{height} option for more + information about valid expressions for \PName{length}.% }% \end{desclist} % @@ -607,46 +613,48 @@ there has not been a layer with \PName{layer name} defined before. \Macro{layerwidth}% \Macro{layerheight}% \end{Declaration} -These commands are valid during output of the layer's contents only. So they -can only be used inside the \PName{code} of option \Option{contents} of the -previously described commands. In this case they give the effective alignment, -position and dimension of the layer, that will be used for the -output. However, the effective dimension of the layer's contents may differ, -i.\,e., if the contents are oversized or do not fill the layer -completely. +These commands are only valid in the \PName{code} specified with +\Option{contents}, \Option{addcontents}, or \Option{pretocontents}. In this +case, they contain the layer's actual alignment, position, and dimensions that +will be used for the output. However, this is not necessarily the actual +dimensions of the layer's contents, e.\,g., if the contents are oversized or +do not fill the layer completely. The primary layer attribute \PValue{align} is mapped to \Macro{layerhalign}\ChangedAt{v3.19}{\Package{scrlayer}} and \Macro{layervalign}. The horizontal values \PValue{l} and \PValue{r} are -copied to \Macro{layerhalign}. The vertical values \PValue{r} and \PValue{b} -are copied to \Macro{layervalign}. The also horizontal and vertical value -\PValue{c} is copied to both commands. If \PValue{align} has contradictory -values, only the last one is copied. Therefore the resulting -\Macro{layerhalign} is either \PValue{l}, \PValue{c}, or \PValue{r} and the -resulting \Macro{layervalign} is either \PValue{r}, \PValue{c}, or \PValue{b}. - -Redefinition of the commands to change the stored values is strictly forbidden -and would result in unpredictable issues.% +copied to \Macro{layerhalign}. The vertical values \PValue{t} and \PValue{b} +are copied to \Macro{layervalign}. The value \PValue{c}, which is both +horizontal and vertical, is copied to both commands. If there are several +conflicting values for \PValue{align}, only the last one is copied. Thus the +resulting \Macro{layerhalign} is either \PValue{l}, \PValue{c}, or \PValue{r}, +and the resulting \Macro{layervalign} is either \PValue{r}, \PValue{c}, or +\PValue{b}. + +Redefining\textnote{Attention!} these instructions to change the values stored +in them is not permitted, as it would lead to unpredictable results.% \EndIndexGroup \begin{Declaration} \Macro{LenToUnit}\Parameter{length} \end{Declaration} -This\ChangedAt{v3.19}{\Package{scrlayer}} command has been copied from -\Package{eso-pic}\IndexPackage{eso-pic} 2.0f. It converts lengths into -multiples of \Length{unitlength}. It can be used everywhere \LaTeX{} -expects \Environment{picture} coordinates or \Length{unitlength}-depending -values. For more information see \cite{package:eso-pic} and the following -descriptions of \Macro{putUR}, \Macro{putLL}, and \Macro{putLR}. If the -command is already defined, e.\,g., by loading \Package{eso-pic} before +This\ChangedAt{v3.19}{\Package{scrlayer}} command originally came from +\Package{eso-pic}\IndexPackage{eso-pic}~2.0f. It converts lengths into +multiples of \Length{unit length} and can therefore be used everywhere \LaTeX{} +expects \Environment{picture} coordinates or \Length{unit length}-dependent +values. For more information, see \cite{package:eso-pic} and the descriptions +of \Macro{putUR}, \Macro{putLL}, and \Macro{putLR} below. If the command is +already defined, e.\,g., by loading \Package{eso-pic} before \Package{scrlayer}, the package does not define it again.% - +\iffalse% Umbruchkorrekturtext +\par It should be noted at this point that using package \Package{picture}\IndexPackage{picture}\textnote{\Package{picture}} (see \cite{package:picture}) supersedes \Macro{LenToUnit} more or less. The package -extends environment \Environment{picture} and the picture commands to accept -\LaTeX{} lengths directly.% +extends environment \Environment{picture} and the picture commands so that you +can use \LaTeX{} lengths directly for coordinates.% +\fi \EndIndexGroup @@ -658,180 +666,198 @@ extends environment \Environment{picture} and the picture commands to accept \Macro{putC}\Parameter{content} \end{Declaration} You\ChangedAt{v3.19}{\Package{scrlayer}} can use these commands inside the -value of primary layer option \PValue{contents}, if the layer is declared with -\OptionValue{mode}{picture}. In that case, \Macro{putUL} places the +value of \PValue{contents} layer option if the layer is declared with +\OptionValue{mode}{picture}. In this case, \Macro{putUL} places the \PName{content} relative to the upper left corner of the layer and therefore -is the same like +is the same as \lstinline[breaklines=false]|\put(0,\LenToUnit{\layerheight})|. \Macro{putUR} places the \PName{content} relative to the upper right corner of the layer and -therefore is the same like -\lstinline[breaklines=false]|\put(\LenToUnit{\layerwidth},\LenToUnit{\layerheight})|. +therefore is the same as +\lstinline[breaklines=false] +|\put(\LenToUnit{\layerwidth},\LenToUnit{\layerheight})|. \Macro{putLL} places the \PName{content} relative to the lower left corner of -the layer and therefore is the same like +the layer and therefore is the same as \lstinline[breaklines=false]|\put(0,0)|. \Macro{putLR} places the \PName{content} relative to the lower right corner and therefore is the same -like \lstinline[breaklines=false]|\put(\LenToUnit{\layerwidth},0)|. Last but -not least \Macro{putC} places the \PName{content} relative to the centre of +as \lstinline[breaklines=false]|\put(\LenToUnit{\layerwidth},0)|. Last but +not least, \Macro{putC} places the \PName{content} relative to the centre of the layer.% \begin{Example} - You want to investigate, how accurate + You want to determine exactly how accurately \OptionValueRef{typearea}{DIV}{classic} sets the height of the text area to - the width of the page size. So you declare a layer that not only border the - text area, but also places a circle with paper width as diameter dimension - into the centre of the text area: + the width of the page size. You declare a layer that both borders the text + area and places a circle with a diameter of the paper width in the centre of + the text area: \begin{lstcode} -\documentclass[DIV=classic]{scrartcl} -\usepackage{pict2e} -\usepackage{scrlayer} -\DeclareNewLayer[% - textarea,background,mode=picture, - contents={% - \putLL{\line(1,0){\LenToUnit{\layerwidth}}}% - \putLR{\line(0,1){\LenToUnit{\layerheight}}}% - \putUR{\line(-1,0){\LenToUnit{\layerwidth}}}% - \putUL{\line(0,-1){\LenToUnit{\layerheight}}}% - \putC{\circle{\LenToUnit{\paperwidth}}}% - } -]{showtextarea} -\DeclareNewPageStyleByLayers{test}{showtextarea} -\pagestyle{test} -\begin{document} -\null -\end{document} + \documentclass[DIV=classic]{scrartcl} + \usepackage{pict2e} + \usepackage{scrlayer} + \DeclareNewLayer[% + textarea,background,mode=picture, + contents={% + \putLL{\line(1,0){\LenToUnit{\layerwidth}}}% + \putLR{\line(0,1){\LenToUnit{\layerheight}}}% + \putUR{\line(-1,0){\LenToUnit{\layerwidth}}}% + \putUL{\line(0,-1){\LenToUnit{\layerheight}}}% + \putC{\circle{\LenToUnit{\paperwidth}}}% + } + ]{showtextarea} + \DeclareNewPageStyleByLayers{test}{showtextarea} + \pagestyle{test} + \begin{document} + \null + \end{document} \end{lstcode} - You will see that \Package{typearea}'s mapping to an integer \PName{DIV} + You will notice that \Package{typearea}'s mapping to an integer \PName{DIV} value is very accurate in this example. \end{Example} -For more information about the sketched Middle Age method of generating a text -area see \autoref{sec:typearea.circleConstruction}, +Incidentally, you will find more information about late medieval book-page +canon sketched in the example in \autoref{sec:typearea.circleConstruction}, \autopageref{sec:typearea.circleConstruction}. -For more information about command -\Macro{DeclareNewPageStyleByLayers}\IndexCmd{DeclareNewPageStyleByLayers} see -the description later in \autoref{sec:scrlayer.pagestyles}, -\DescPageRef{scrlayer.cmd.DeclareNewPageStyleByLayers}. In short: It -defines a new page style using the newly declared layer.% +The \Macro{DeclareNewPageStyleByLayers}\IndexCmd{DeclareNewPageStyleByLayers} +command just used in the example defines a new page style using the newly +declared layer. It will be explained in \autoref{sec:scrlayer.pagestyles}, +\DescPageRef{scrlayer.cmd.DeclareNewPageStyleByLayers}.% \EndIndexGroup \begin{Declaration} - \Macro{GetLayerContents}\Parameter{layer name} + \Macro{GetLayerContents}\Parameter{layer~name} \end{Declaration} -This\ChangedAt{v3.16}{\Package{scrlayer}} command results in the whole content -of a layer. You have to note\textnote{Attention!} that using this +This\ChangedAt{v3.16}{\Package{scrlayer}} command returns the whole contents +of a layer. It is important to note\textnote{Attention!} that using this command inside the \PName{code} of the layer attributes \Option{contents}, \Option{addcontents}, or \Option{pretocontents} can result in -an infinite recursion, if the content of the current layer is referenced. You -yourself should avoid such situations!% +infinite recursion when referencing the contents of the current layer. You +are responsible for avoiding such situations!% \EndIndexGroup \begin{Declaration} - \Macro{IfLayerExists}% - \Parameter{string}\Parameter{then-code}\Parameter{else-code} + \Macro{IfLayerExists}\Parameter{layer~name} + \Parameter{then-code}\Parameter{else-code} \end{Declaration} -This command may be used to execute code depending on whether or not a layer -has been defined already. If the layer exists \PName{then-code} will be -executed, otherwise \PName{else-code}. Note, the command cannot really -test whether a layer exists. It uses a heuristic, that will never be false -negative, but may be false positive. Nevertheless, if it is false positive -something went wrong, either an incompatible package has been used or the user -made something he should not do.% +This command can be used to execute code depending on whether or not a layer +with the specified \PName{layer name} exists. If the layer exists, the +\PName{then-code} will be executed; otherwise, the \PName{else-code} will be +executed. Note that the command cannot really test whether a layer exists. +Instead it uses a heuristic which will never yield a false negative but which, +in extreme cases, could yield a false positive. +\iffalse% Umbruchvarianten +Nevertheless, if the test yields a false positive, something has gone wrong. +For example, this could indicate an incompatible package or that the user is +doing something he or she should not.% +\else +False positives indicate a problem, such as the use of an incompatible package +or a bad choice of internal macro names by the user. +\fi \EndIndexGroup \begin{Declaration} - \Macro{DestroyLayer}\Parameter{layer name} + \Macro{DestroyLayer}\Parameter{layer~name} \end{Declaration} -This command sets all macros corresponding with the layer with given -\PName{layer name} to \Macro{relax}, if a layer with that name exists. As a -result the layer cannot be used any longer. It does not matter, if the layer -is still part of the layer list of a page style, because such destroyed layers -will be ignored. Nevertheless, destroyed layers may be defined again using -\DescRef{\LabelBase.cmd.DeclareNewLayer} or -\DescRef{\LabelBase.cmd.ProvideLayer}, but cannot be changed using +If a layer with the given \PName{layer name} exists, all macros belonging to +it will be set to \Macro{relax}. In page styles already defined with +\Package{scrlayer}, such destroyed layers are ignored. Destroyed layers can be +redefined using \DescRef{\LabelBase.cmd.DeclareNewLayer} or +\DescRef{\LabelBase.cmd.ProvideLayer}, but they can no longer be changed using \DescRef{\LabelBase.cmd.RedeclareLayer} or -\DescRef{\LabelBase.cmd.ModifyLayer} any longer. +\DescRef{\LabelBase.cmd.ModifyLayer}. The command is intended to be used inside -\DescRef{\LabelBase.cmd.scrlayerOnAutoRemoveInterface} to remove layers, which have been -defined using removable macros of an interface, whenever the interface would -be removed.% +\DescRef{\LabelBase.cmd.scrlayerOnAutoRemoveInterface} (see +\autoref{sec:scrlayer.enduserinterfaces}, +\DescPageRef{scrlayer.cmd.scrlayerOnAutoRemoveInterface}) +to remove layers defined using removable macros of an interface along with +that interface.% \EndIndexGroup \begin{Declaration} \Macro{layercontentsmeasure}% \end{Declaration} -The command \Macro{layercontentsmeasure} prints a ruler at each layer edge, of -which the top and left one is labelled with centimeters, the right and bottom -one with inches. This command is used internally, if option -\DescRef{\LabelBase.option.draft}\IndexOption{draft} is enabled. The rulers -will be drawn behind the content of each layer. It can also be used as -exclusive content of a layer.% +The \Macro{layercontentsmeasure} command prints a ruler at each layer edge, of +which the top and left one is labelled in centimetres and the right and bottom +one in inches. This command is used internally if the +\DescRef{\LabelBase.option.draft}\IndexOption{draft} option is enabled. The +rulers are drawn behind the content of each layer. This command can also be +used as exclusive content of a layer.% \EndIndexGroup -\section{Declaration and Management of Page Styles} +\section{Declaring and Managing Page Styles} \seclabel{pagestyles} -Until now we know layers, but we do not know how to use them. The -perhaps astonishing answer is: with page styles. In \LaTeX{}, page -styles usually define heads and foots of odd and even pages. - -The head and foot of odd pages will be printed on pages with odd -page number in two-side mode or on all pages in single-side mode. This is -something like the layer attributes \Option{oddpage} and \Option{evenpage}. - -The page head will be printed before the main contents of a page. The page -footer will be printed after the main contents of a page. So this is something -like the layer attributes \Option{background} and \Option{foreground}. - -So it suggests itself to declare page styles as a list of layers. But instead of -having only four attributes \Option{oddpage}, \Option{evenpage}, -\Option{background}, and \Option{foreground} all the attributes of layers -shown in \autoref{sec:scrlayer.layers} may be used. - -The outcome of all such considerations is that layer page styles are one type -of page styles \Package{scrlayer} provides. A layer page style consists of -layers and several \emph{hooks}. For description of layers see -\autoref{sec:scrlayer.layers}. The \emph{hooks} are points in the expansion -or execution of page styles you may add additional code to. Advanced users -know this already from commands like \Macro{AtBeginDocument} (see -\cite{latex:usrguide}) or \Macro{BeforeClosingMainAux} (see +\BeginIndexGroup +\BeginIndex{}{page>style}% +We now understand how to define and manage layers, but so far we do not know +how they are used. The possibly surprising answer is, with page styles. In +\LaTeX{}, page styles usually define headers and footers of the page. + +The header and footer of odd or right-hand pages\textnote{even or odd page} +are printed on pages with odd page numbers in two-sided printing or on all +pages in one-sided printing. This is directly comparable to the layer +options\important[i]{\Option{evenpage}\\\Option{oddpage}} \Option{oddpage} and +\Option{evenpage}. + +The page header\textnote{header or footer} is output before the main page +contents. The page footer is output after the main page contents. This +corresponds directly to the layer +options\important[i]{\Option{background}\\\Option{foreground}} +\Option{background} and \Option{foreground}. + +Therefore it makes sense to define page styles as lists of layers. But instead +of just the four options mentioned above, you can use all the properties +explained in \autoref{sec:scrlayer.layers}, \autoref{tab:scrlayer.layerkeys}, +on \autopageref{tab:scrlayer.layerkeys}. + +As a result of these considerations, layer page +styles\textnote{layer page style}\Index{page style>layer}% +\Index{layer>page style}\Index{page>style} are one type of page style that +\Package{scrlayer} provides. A layer page style consists of layers as well as +several hooks. The layers have already been described in +\autoref{sec:scrlayer.layers}. The hooks\Index[indexmain]{hooks}% +\textnote{hooks} are points in the expansion or execution of page styles to +which you can add code. Experienced users already know this concept from +commands like \Macro{AtBeginDocument} (see \cite{latex:usrguide}) or +\DescRef{scrlfile.cmd.BeforeClosingMainAux} (see \DescPageRef{scrlfile.cmd.BeforeClosingMainAux}). -Alias page styles are another type of page styles provided by -\Package{scrlayer}. An alias page style wraps another page style. In other -words, the name of an alias page style is an alias name of another page style, -the aliased or original page style. Because of this, the manipulation of an -alias page style results in the manipulation of the original page style. If -the original page style is an alias page style too, the manipulation will -result in the manipulation of the aliased page style of that original page -style and so on until a real page style will be manipulated. Aliasing is not -restricted to \Package{scrlayer} page styles, but possible for all page -styles. +Page-style aliases are another type of page style which \Package{scrlayer} +provides. A page-style alias is actually a different page style. In other +words, the name of a page-style alias is an alternative name for another +page-style alias or for a page style. As a result, manipulating a page-style +alias results in manipulating the original page style. If the original page +style is itself an alias, its manipulation again results in the manipulation +of the alias's original page style, and so on until a real page style is +finally changed. The term \emph{real page style}\textnote{real page style} is +used to distinguish it from a page-style alias. All page styles that are not +page-style aliases are real page styles. Aliases can be defined for all page +styles, not just those defined with \Package{scrlayer}. \begin{Declaration} \Macro{currentpagestyle} \end{Declaration} -Package scrlayer patches \DescRef{maincls.cmd.pagestyle} to set -\Macro{currentpagestyle} to the currently active page style. Note, -\DescRef{maincls.cmd.thispagestyle} does not change -\Macro{currentpagestyle}. But if you use \DescRef{maincls.cmd.thispagestyle} -the result of \Macro{currentpagestyle} may be changed while executing the -\LaTeX{} output routine. However, this change will only occur, if -\Macro{currentpagestyle} has been actively protected from expansion up to -execution of the output routine. - -Note, the layer page styles described later in this section, will not need the -patch of \DescRef{maincls.cmd.pagestyle} to set \Macro{currentpagestyle}. The -patch has been made for usage with other page styles. Additionally, -\Macro{currentpagestyle} is empty before the first -\DescRef{maincls.cmd.pagestyle} after loading \Package{scrlayer}. So if you -define an end user page style interface, it may be useful to use an implicit -\DescRef{maincls.cmd.pagestyle} to set the current page style to a default -page style.% +The \Package{scrlayer} package patches the \DescRef{maincls.cmd.pagestyle} +command so that it sets \Macro{currentpagestyle} to the currently active page +style. Note that \DescRef{maincls.cmd.thispagestyle} does not change +\Macro{currentpagestyle}. If you use \DescRef{maincls.cmd.thispagestyle}, +however, \Macro{currentpagestyle} can change within the \LaTeX{} output +routine. However, this change will only occur if \Macro{currentpagestyle} has +been actively protected from expansion until the execution of the output +routine. + +Note that the layer page styles described later in this section do not rely on +this \DescRef{maincls.cmd.pagestyle} extension because they redefine +\Macro{currentpagestyle} themselves. This patch was made so that other, +non-\Package{scrlayer} page styles can use \Macro{currentpagestyle}. +Additionally, \Macro{currentpagestyle} is empty after loading +\Package{scrlayer} and before using \DescRef{maincls.cmd.pagestyle} for the +first time. Therefore, when defining an end-user interface, you may find it +useful to set the current page style to a default with an implicit +\DescRef{maincls.cmd.pagestyle} statement.% \EndIndexGroup @@ -839,201 +865,248 @@ page style.% \Macro{BeforeSelectAnyPageStyle}\Parameter{code}% \Macro{AfterSelectAnyPageStyle}\Parameter{code}% \end{Declaration} -The command \Macro{BeforeSelectAnyPageStyle} adds \PName{code} to the hook -that will be executed inside of \DescRef{maincls.cmd.pagestyle} just before -the page style will be selected. You may use \texttt{\#1} as a placeholder for -the argument of \DescRef{maincls.cmd.pagestyle}. - -The command \Macro{AfterSelectAnyPageStyle} is similar, but the \PName{code} -will be executed just after the page style has been selected and after -\DescRef{\LabelBase.cmd.currentpagestyle} has been set to the name of the real -page style. - -Note\textnote{Attention!}, \PName{code} of both commands will be executed only -if a page style will be selected using \DescRef{maincls.cmd.pagestyle}, but -not, e.\,g., if a page style will be selected using -\DescRef{maincls.cmd.thispagestyle}. Note also, you cannot remove \PName{code} -from the hook after adding it. But the \PName{code} will be added locally, so -you may use a group to limit the scope of \PName{code}.% +The \Macro{BeforeSelectAnyPageStyle} command adds \PName{code} to the hook% +\textnote{hook} that will be executed inside \DescRef{maincls.cmd.pagestyle}, +just before the page style is selected. Within the \PName{code}, you can use +\texttt{\#1} as a place-holder for the argument of +\DescRef{maincls.cmd.pagestyle}. + +The \Macro{AfterSelectAnyPageStyle} command works similarly, but the +\PName{code} will be executed just after the page style has been selected and +after \DescRef{\LabelBase.cmd.currentpagestyle} has been set to the name of +the real page style. + +Note\textnote{Attention!} that the \PName{code} of both commands is executed +only if a page style is selected with \DescRef{maincls.cmd.pagestyle} and not +if it is chosen in a different way, e.\,g., using +\DescRef{maincls.cmd.thispagestyle}. Note also that you cannot remove +\PName{code} from the hook after adding it. But the \PName{code} will be added +locally, so you can use a group to limit the scope of the \PName{code}.% \EndIndexGroup \begin{Declaration} - \Macro{DeclarePageStyleAlias}% - \Parameter{alias page style name}\Parameter{original page style name}% - \Macro{DeclareNewPageStyleAlias}% - \Parameter{alias page style name}\Parameter{original page style name}% - \Macro{ProvidePageStyleAlias}% - \Parameter{alias page style name}\Parameter{original page style name}% - \Macro{RedeclarePageStyleAlias}% - \Parameter{alias page style name}\Parameter{original page style name} + \Macro{DeclarePageStyleAlias}\Parameter{page~style~alias~name} + \Parameter{original~page~style~name} + \Macro{DeclareNewPageStyleAlias}\Parameter{page~style~alias~name} + \Parameter{original~page~style~name} + \Macro{ProvidePageStyleAlias}\Parameter{page~style~alias~name} + \Parameter{original~page~style~name} + \Macro{RedeclarePageStyleAlias}\Parameter{page~style~alias~name} + \Parameter{original page style name} \end{Declaration} -These commands may be used to define a page style with name \PName{alias page - style name} that is simply an alias for an already existing page style with +\BeginIndex{}{page style>alias}% +\BeginIndex{}{alias>page style}% +These commands can be used to define a page style with name \PName{page style + alias name} that is simply an alias for an existing page style with the name \PName{original page style name}. If there is already a page style -\PName{alias page style name}, then using \Macro{DeclarePageStyleAlias} or +\PName{page style alias name}, using \Macro{DeclarePageStyleAlias} or \Macro{RedeclarePageStyleAlias} will destroy the alias before recreating it. -\Macro{DeclareNewPageStyleAlias} will throw an error message, if a page style -\PName{alias page style name} has already been defined before. It does not -matter if the already defined page style is a layer page style, an alias page -style or another page style. - -\Macro{ProvidePageStyleAlias} will define the alias only if a page style -\PName{alias page style name} has not been defined before. If a page style -\PName{alias page style name} already exists nothing will be done. - -\Macro{RedeclarePageStyleAlias} expects an already existing page style -\PName{alias page style name}. It will destroy that page style and afterwards -define the alias. If the page style \PName{alias page style name} does not -exist, then you will get an error.% +\Macro{DeclareNewPageStyleAlias} will throw an error message if a page style +\PName{page style alias name} has already been defined. It does not matter if +the previously defined page style is a layer-page style, a page style alias, +or another page style. + +\Macro{ProvidePageStyleAlias} will define the alias only if the +\PName{page style alias name} page style has not been defined before. If the +\PName{page style alias name} page style already exists, nothing will be done. + +\Macro{RedeclarePageStyleAlias} expects an existing +\PName{page style alias name} page style. It will destroy that page style and +afterwards define the alias. If the \PName{page style alias name} page style +does not exist, you will get an error.% +\iffree{\csname @tempswafalse\endcsname}{\csname @tempswatrue\endcsname}% +\csname if@tempswa\endcsname% Umbruchkorrekturtext + \begin{Example} + Suppose you write a class and use the \PageStyle{chapter} page style for the + first page of each chapter. By default, this page style should match the + \PageStyle{plain} page style. Therefore, you can use the \Package{scrlayer} + package and use +\begin{lstcode} + \DeclareNewPageStyleAlias{chapter}{plain} +\end{lstcode} + to define the \PageStyle{chapter} page style as an alias for the + \PageStyle{plain} page style. If, on the other hand, you later decide that + the \PageStyle{chapter} plage style should correspond to the + \PageStyle{empty} page style, you can achieve this with: +\begin{lstcode} + \RedeclarePageStyleAlias{chapter}{empty} +\end{lstcode}% + \end{Example}% +\fi \EndIndexGroup \begin{Declaration} - \Macro{DestroyPageStyleAlias}\Parameter{page style name}% + \Macro{DestroyPageStyleAlias}\Parameter{page~style~name}% \end{Declaration} -This command makes the page style with given \PName{page style name} -\LaTeX-undefined, if it is an alias for another page style. Afterwards, the -page style may be defined newly with, e.g., \Macro{DeclareNewAliasPageStyle} -or \Macro{ProvideAliasPageStyle}. - -The command is intended to be used inside of -\DescRef{\LabelBase.cmd.scrlayerOnAutoRemoveInterface} to remove page styles that have been -declared by an interface and use removable macros of that interface.% +\BeginIndex{}{page style>alias}% +\BeginIndex{}{alias>page style}% +This command renders the page style named \PName{page style name} undefined +for \LaTeX{} if it is an alias for another page style. Afterwards, the page +style can be newly defined with +\DescRef{\LabelBase.cmd.DeclareNewPageStyleAlias} or +\DescRef{\LabelBase.cmd.ProvidePageStyleAlias}. + +This command is intended to be used inside the argument code of +\DescRef{\LabelBase.cmd.scrlayerOnAutoRemoveInterface} to remove page styles +that have been declared as part of an end-user interface when removing this +interface automatically.% \EndIndexGroup \begin{Declaration} - \Macro{GetRealPageStyle}\Parameter{page style name}% + \Macro{GetRealPageStyle}\Parameter{page~style~name}% \end{Declaration} -The command will result in the (recursive) real page name of the page style, -if the page style with given name \PName{page style name} is an alias of -another page style. In all other cases, even if there's no alias and no page -style named \PName{page style name}, the result would be simply \PName{page - style name}. The command is fully expandable and may be used, e.g., in the -second argument of \Macro{edef}.% +\BeginIndex{}{page style>alias}% +\BeginIndex{}{alias>page style}% +This command will result in the (recursive) real page name of the page style +if \PName{page style name} is an alias of another page style. In all other +cases, even if there's no alias and no page style named \PName{page style + name}, the result is simply \PName{page style name}. The command is fully +expandable and may be used, e.g., in the second argument of \Macro{edef}.% \EndIndexGroup \begin{Declaration} - \Macro{DeclarePageStyleByLayers}% - \OParameter{option list}\Parameter{page style name}\Parameter{layer list}% - \Macro{DeclareNewPageStyleByLayers}% - \OParameter{option list}\Parameter{page style name}\Parameter{layer list}% - \Macro{ProvidePageStyleByLayers}% - \OParameter{option list}\Parameter{page style name}\Parameter{layer list}% - \Macro{RedeclarePageStyleByLayers}%^ - \OParameter{option list}\Parameter{page style name}\Parameter{layer list}% + \Macro{DeclarePageStyleByLayers}\OParameter{option list} + \Parameter{page style name} + \Parameter{layer list} + \Macro{DeclareNewPageStyleByLayers}\OParameter{option list} + \Parameter{page style name} + \Parameter{layer list} + \Macro{ProvidePageStyleByLayers}\OParameter{option list} + \Parameter{page style name} + \Parameter{layer list} + \Macro{RedeclarePageStyleByLayers}\OParameter{option list} + \Parameter{page style name} + \Parameter{layer list} \end{Declaration} -These commands declare a page style with \PName{page style name}. The page +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +These commands declare a page style named \PName{page style name}. The page style will consist of the layers given in \PName{layer list}, a comma -separated list of layer names. Note, the \PName{page style name} and the -layer names at the \PName{layer list} must be fully expandable and should -expand to letters. Several other characters are tolerated, but, -nevertheless, not recommended. - -The \PName{option list} is a comma separated list of -\OptionValue{\PName{key}}{\PName{value}} options. These options may be used to -set additional features. Currently they are used to set the code that should -be expanded or executed at several \emph{hooks}. See the introduction to this -section for more general information about \emph{hooks}. See +separated list of layer names. Note\textnote{Attention!} that the \PName{page + style name} and the layer names in the \PName{layer list} must be fully +expandable and should expand to letters. Several other characters are also +accepted, but their use is recommended only for experienced users. + +The \PName{option list} is a comma-separated list of options in the form +\texttt{\PName{key}=\PName{value}}. These options may be used to set +additional features. Currently they are used to set the code that should be +expanded or executed at several hooks\Index{hooks}. See the introduction to +this section for more general information about hooks. See \autoref{tab:scrlayer.pagestyle.hooks} for detailed information on specific hooks. \begin{desclist} \desccaption{% - The \emph{hook} options for page styles (in order of + Hook options for page styles (in order of execution)\label{tab:scrlayer.pagestyle.hooks}% }{% - The \emph{hook} options for page styles (\emph{Continuation})% + Hook options for page styles (\emph{continued})% }% \entry{\OptionVName{onselect}{code}}{% - Execute \PName{code} whenever the page style is selected using, e.g., - \DescRef{maincls.cmd.pagestyle}. Note\textnote{Attention!}, - \DescRef{maincls.cmd.thispagestyle} does not select the page style - immediately, but asynchronously inside \LaTeX's output routine.% + The \PName{code} of this hook\Index{hook} is executed whenever the page + style is selected, for example with \DescRef{maincls.cmd.pagestyle}. Note + that \DescRef{maincls.cmd.thispagestyle} itself does not directly select a + page style. In this case, the page style is only activated within \LaTeX's + output routine.% }% \entry{\OptionVName{oninit}{code}}{% - Execute \PName{code} whenever the output of page style's layers is - initialised. Note\textnote{Attention!}, this is done twice for every page: - once for background layers and once for foreground layers.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers is initialised. Note that this happens twice + for each page: once for background layers and once for foreground layers.% }% \entry{\OptionVName{ononeside}{code}}{% - Execute \PName{code} whenever the output of page style's layers in - single-side mode is initialised. Note\textnote{Attention!}, this is done - twice for every page: once for background layers and once for foreground - layers.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers in one-sided printing is initialised. Note that + this happens twice for each page: once for background layers and once for + foreground layers.% }% \entry{\OptionVName{ontwoside}{code}}{% - Execute \PName{code} whenever the output of page style's layers in - two-side mode is initialised. Note\textnote{Attention!}, this is done - twice for every page: once for background layers and once for foreground - layers.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers in two-sided printing is initialised. Note that + this happens twice for each page: once for background layers and once for + foreground layers.% }% \entry{\OptionVName{onoddpage}{code}}{% - Execute \PName{code} whenever the output of page style's layers on an odd - page is initialised. Note\textnote{Attention!}, this is done twice for - every page: once for background layers and once for foreground - layers. Note\textnote{Attention!} also that in single-side mode all pages - are odd pages, not only pages with odd page numbers.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers on an odd page is initialised. Note that this + happens twice for each page: once for background layers and once for + foreground layers. Note also that in one-sided printing all pages are odd + pages, not just those with odd page numbers.% }% \entry{\OptionVName{onevenpage}{code}}{% - Execute \PName{code} whenever the output of page style's layers on an even - page is initialised. Note\textnote{Attention!}, this is done twice for - every page: once for background layers and once for foreground - layers. Note\textnote{Attention!} also that there are not even pages in - single-side mode, but all pages are odd pages, not only pages with odd - page numbers.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers on an even page is initialised. Note that this + happens twice for each page: once for background layers and once for + foreground layers. Note also that in one-sided printing there are no even + pages. Instead, all pages are treated as odd pages, not just those with + odd page numbers.% }% \entry{\OptionVName{onfloatpage}{code}}{% - Execute \PName{code} whenever the output of page style's layers on a float - page are initialised. Note\textnote{Attention!}, this is be done twice for - every page: once for background layers and once for foreground - layers. Note\textnote{Attention!} also that float pages are only those - pages with p-placed floating objects.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers on a float page is initialised. Note that this + happens twice for each page: once for background layers and once for + foreground layers. Note also that float pages are only those pages with + one or more p-placed floating environments.% }% \entry{\OptionVName{onnonfloatpage}{code}}{% - Execute \PName{code} whenever the output of page style's layers on a - non-float page is initialised. Note\textnote{Attention!}, this is done - twice for every page: once for background layers and once for foreground - layers. Note\textnote{Attention!} also that non-float pages are all pages - that are not float-pages. Those pages may have t-placed, h-placed, - b-placed, or no floating objects.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers on a non-float page is initialised. Note that + this happens twice for each page: once for background layers and once for + foreground layers. Note also that float pages are only the pages on which + one or more p-placed floating environments are output. Other pages may + well have t-, h-, or b-placed floating environments.% }% \entry{\OptionVName{onbackground}{code}}{% - Execute \PName{code} whenever the output of page style's layers in the - background of a page is initialised. Note\textnote{Attention!}, this is - done once for every page.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's background layers is initialised. Note that this + happens once each page.% }% \entry{\OptionVName{onforeground}{code}}{% - Execute \PName{code} whenever the output page style's layers in the - foreground of a page is initialised. Note\textnote{Attention!}, this is - done once for every page.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's foreground layers is initialised. Note that this + happens once each page.% }% \end{desclist} -The difference of \Macro{DeclarePageStyleByLayers} and -\Macro{DeclareNewPageStyleByLayers} is that -\Macro{DeclareNewPageStyleByLayers} will result in an error, if a page style -with name \PName{page style name} already exists. Note, declaring a page -style, which is an alias of another page style (see -\Macro{DeclareAliasPageStyle} prior in this section), will not re-declare the -page style itself, but it's real page style (see -\DescRef{\LabelBase.cmd.GetRealPageStyle} prior in this section). - -The difference of \Macro{DeclarePageStyleByLayers} and -\Macro{ProvidePageStyleByLayers} is that \Macro{ProvidePageStyleByLayers} -will simply do nothing, if there's already a page style with name \PName{page - style name}. In difference to \Macro{DeclareNewPageStyleByLayers} it will not -raise an error. - -The difference of \Macro{DeclarePageStyleByLayers} and -\Macro{RedeclarePageStyleByLayers} is, that \Macro{RedeclarePageStyleByLayers} -may be used only if the real page style of \PName{page style name} already -exists. Otherwise an error occurs. - -Please have also a look at the notes to following pseudo page style +\iffalse% Umbruchvarianten + While the \Macro{DeclarePageStyleByLayers} command always defines the page + style, \Macro{DeclareNewPageStyleByLayers} generates an error message if a + page style with the same name already exists. Note\textnote{Attention!} that + the declaration of a page style that is already an alias for another page + style (see, for example, \Macro{DeclareAliasPageStyle} earlier in this + section) will redefine not the specified page style alias but the real page + style (see \DescRef{\LabelBase.cmd.GetRealPageStyle} earlier in this + section).% +\else% + The \Macro{DeclarePageStyleByLayers} command defines the page style + regardless of whether a page style of \PName{page style name} already + exists. If necessary, the existing page style is completely + redefined. However, if a page style alias \PName{page style name} already + exists, the associated real page style, not the page style alias itself, is + redefined (see \DescRef{\LabelBase.cmd.GetRealPageStyle} earlier in this + section). + + The \Macro{DeclareNewPageStyleByLayers} command differs if a page style of + the same name already exists. Regardless of whether it is a real or an alias + page style, an error will be reported in this case. +\fi + +In contrast, \Macro{ProvidePageStyleByLayers} preserves the page style +unchanged if a page style with name \PName{page style name} already exists. If +no such page style exists, it is defined as in +\Macro{DeclarePageStyleByLayers}. + +The \Macro{RedeclarePageStyleByLayers} in turn expects that a page style of +of the name \PName{page style name} already exists and then redefines its real +page style. However, if no page style of the specified name exists, an error +message results. + +Also note the remarks below about the pseudo-page style \PageStyle{@everystyle@}.% \EndIndexGroup @@ -1042,25 +1115,35 @@ Please have also a look at the notes to following pseudo page style \PageStyle{@everystyle@}% \PageStyle{empty} \end{Declaration} -There are two default layer page styles that are somehow special. The first -one is \PageStyle{@everystyle@}. This page style should not be used like any -other page style, but the layers of this page style will be used by all the -other layer page styles. So adding a layer to this page style is similar to -adding this layer to all other layer page styles even the empty one. There's -one difference: Layer referencing commands of the page style interface like -\DescRef{\LabelBase.cmd.ForEachLayerOfPageStyle}, -\DescRef{\LabelBase.cmd.AddLayersToPageStyleBeforeLayer}, or -\DescRef{\LabelBase.cmd.AddLayersToPageStyleAfterLayer} process only the -layers of the page style that has been referenced but not the layers -implicated by \PageStyle{@everystyle@}. - -The other somehow special page style is \PageStyle{empty}. Normally page style -\PageStyle{empty} is defined by the \LaTeX{} kernel, to be a page style -without page head or page foot. Package \Package{scrlayer} re-defines it to be -a layer page style without any layer. Nevertheless, you may use it like every -other layer page style too. The main advantage above the \LaTeX{} kernel's -empty page style is that it also executes the layers of special layer page -style \PageStyle{@everysel@}.% +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +The \Package{scrlayer} package defines two specific page styles worth noting. +The first of these is \PageStyle{@everystyle@}% +\important{\PageStyle{@everystyle@}}. This page style should never be used +like a normal page style, for example with \DescRef{maincls.cmd.pagestyle} or +\DescRef{maincls.cmd.thispagestyle}, or as the target of a page-style alias. +Instead, the layers and hooks\Index{hooks} of this page style are used by all +other layer page styles. The hooks of \PageStyle{@everystyle@} are placed in +front of their respective hooks, and the layers in front of the respective +layers, of the active page style. + +Thus adding a layer to the pseudo-page style \PageStyle{@everystyle@} or code +to a hook of this page style is like adding a layer or hook code to all layer +page styles, even the empty one. There's one crucial difference: commands that +reference the layers of a page style which include +\DescRef{\LabelBase.cmd.ForEachLayerOfPageStyle}, e.\,g., the commands +\DescRef{\LabelBase.cmd.AddLayersToPageStyleBeforeLayer} or +\DescRef{\LabelBase.cmd.AddLayersToPageStyleAfterLayer}, disregard the layers +of the page style \PageStyle{@everystyle@} when applied to a different layer +page style. + +The second, slightly different page style is \PageStyle{empty}. Normally the +\LaTeX{} kernel defines the \PageStyle{empty} page style to have an empty +header and footer. The \Package{scrlayer} package redefines this page style as +a layerless page style. Nonetheless, you can use it like any other layer page +style. The main advantage of the layer page style over the original page +style from the \LaTeX{} kernel is that it also executes the hooks and layers +of the psuedo-layer page style \PageStyle{@everystyle@}.% \EndIndexGroup @@ -1076,13 +1159,23 @@ style \PageStyle{@everysel@}.% \OptionVName{onpsbackground}{code}% \OptionVName{onpsforeground}{code} \end{Declaration} -There's also a \KOMAScript{} option for each of those \texttt{hooks}. The -names of the \KOMAScript{} options are similar to the names of the page style -options, but with ``\texttt{ps}'' inserted behind ``\texttt{on}''. The value -of the \KOMAScript{} options are the initial defaults of the corresponding -\texttt{hooks}. These defaults will be extended at every declaration of page -style hook options via \PName{option list}. You may remove the default, using -\DescRef{\LabelBase.cmd.ModifyLayerPageStyleOptions} described later in this section.% +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +There is also a \KOMAScript{} option for each of the hooks\Index{hooks} in +\autoref{tab:scrlayer.pagestyle.hooks}% +\iftrue +. The names of the \KOMAScript{} options are similar to those for declaring +page style layers, except that a ``\texttt{ps}'' is inserted after +``\texttt{on}'' at the beginning of the name +\else +, into the names of which a ``\texttt{ps}'' is inserted +\fi +. The values of these \KOMAScript{} options are used as the initial values for +the corresponding hooks. These initial values are then extended by all the +values assigned to the corresponding hooks in the \PName{option list} of the +declaration commands. You can remove the default with +\DescRef{\LabelBase.cmd.ModifyLayerPageStyleOptions}, which is explained later +in this section.% \EndIndexGroup @@ -1090,13 +1183,14 @@ style hook options via \PName{option list}. You may remove the default, using \OptionVName{singlespacing}{simple switch} \end{Declaration} If\ChangedAt{v3.24}{\Package{scrlayer}\and \Package{scrlayer-scrpage}} a -document is printed with increased line-spread, e.g., using package -\Package{setspace}\IndexPackage{setspace}, often the page head and foot should -be printed single-spaced. This is surely true if the page head and foot -consist of only a single line. In those cases you can use \KOMAScript{} option -\Option{singlespacing}. Nevertheless, the default is -\OptionValue{singlespacing}{false}! The option influences always all page -styles. If you want single-spacing for only some page styles, use +document is printed with increased line spacing, e.\,g., using the +\Package{setspace}\IndexPackage{setspace}\important{\Package{setspace}} +package, it is often undesirable for the header and footer to be printed with +this increased spacing. This is particularly true if the header and footer +consist of only a single line. In this case you can use \KOMAScript{} option +\Option{singlespacing}. However, the default\textnote{default} is +\OptionValue{singlespacing}{false}! The option generally applies to all layer +page styles. If you want single-spacing for only some page styles, use \OptionValue{oninit}{\Macro{linespread}\PParameter{1}\Macro{selectfont}} for those page styles.% \EndIndexGroup @@ -1107,38 +1201,41 @@ those page styles.% \Macro{ForEachLayerOfPageStyle}\Parameter{page style name}\Parameter{code}% \Macro{ForEachLayerOfPageStyle*}\Parameter{page style name}\Parameter{code} \end{Declaration} -As long as \KOMAScript{} option \Option{deactivatepagestylelayers} has not -been activated command \Macro{ForEachLayerOfPageStyle} can be used to process -\PName{code} for every member layer of \PName{page style name}'s layers -list. Inside of \PName{code} the place holder \PValue{\#1} may be used to -reference the name of the current layer. +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +As long as the \KOMAScript{} option \Option{deactivatepagestylelayers} is not +enabled, the \Macro{ForEachLayerOfPageStyle} command can execute arbitrary +\PName{code} for each layer of the page style named \PName{page style name}. +Inside of \PName{code}, the place holder \PValue{\#1} serves as a +reference to the name of the current layer. \begin{Example} - If you want to print the names of all layers of page style - \PValue{scrheadings}, you may us: + If you want to print the names of all layers of the \PValue{scrheadings} + page style as a comma-separated list, you can use: \begin{lstcode} \let\commaatlist\empty \ForEachLayerOfPageStyle{scrheadings}{% \commaatlist#1\gdef\commaatlist{, }} \end{lstcode} \end{Example} -Usage of \Macro{gdef} instead of \Macro{def} is necessary in the example -above, because \Macro{ForEachLayerOfPageStyle} executes the \PName{code} -inside of a group to minimise side effects. Here \Macro{gdef} redefines -\Macro{commaatlist} globally, so it would be still valid at the execution of -\PName{code} for the next layer. +In\textnote{Attention!} the example above, we had to use \Macro{gdef} instead +of \Macro{def} because \Macro{ForEachLayerOfPageStyle} executes the +\PName{code} inside a group to minimise side effects. However, \Macro{gdef} +redefines \Macro{commaatlist} globally so the change will persist when the +\PName{code} for the next layer is executed. Alternatively,\ChangedAt{v3.18}{\Package{scrlayer}} you can use \Macro{def} -but the star variant \Macro{ForEachLayerOfPageStyle*}. This type does not use -an additional group for executing \PName{code}. On the other hand the user has -to take care on side effects of \PName{code}, i.\,e., deactivation of all -layers using \OptionValue{deactivatepagestylelayers}{true} in \PName{code} -would persist after \Macro{ForEachLayerOfPageStyle*}. - -Several other commands of \Package{scrlayer} also -use \Macro{ForEachLayerOfPageStyle} internally. So these also do not process -any layer if \KOMAScript{} option \Option{deactivatepagestylelayers} would be -activated. So you may use this options, e.g., to hide all layers of all layer -page styles.% +with the starred variant \Macro{ForEachLayerOfPageStyle*}. This form dispenses +with the extra group when executing \PName{code}. However, the user then has +to take make sure that the \PName{code} has no unwanted side effects. In +particular, deactivating all layers using +\OptionValue{deactivatepagestylelayers}{true} within \PName{code} would +persist beyond the call to \Macro{ForEachLayerOfPageStyle*}. + +Various \Package{scrlayer} commands also use \Macro{ForEachLayerOfPageStyle} +internally. Their behaviour can therefore also be changed using the +\KOMAScript{} option \Option{deactivatepagestylelayers}. With this option, +you can temporarily disable and thus hide all layers of all layer page +styles.% \EndIndexGroup @@ -1152,32 +1249,39 @@ page styles.% \Macro{RemoveLayersFromPageStyle}% \Parameter{page style name}\Parameter{layer list}% \end{Declaration} -You can use these commands to add layers to a layer page style or to remove -layers from a layer page style. The page style will be referenced by -\PName{page style name}. The layers are given by a comma separated -\PName{layer list}. - -The commands \Macro{AddLayersToPageStyle} and \Macro{AddLayersAtEndOfPageStyle} -add all layers of the comma separated list of layers \PName{layer list} at -the end of the layer list of layer page style \PName{page style - name}. Logically the added layers would be above or in front of the old -layers of the page style. Nevertheless, new background layers would be behind -the text layer and therefore behind all foreground layers. - -Command \Macro{AddLayersAtBeginOfPageStyle} adds the new layers at the begin -of the layer list of the page style. Note, the layers -will be added in the order of the \PName{layer list}. The first layer at -\PName{layer list} will be added first, the second layer will be added second -and so on. So with \Macro{AddLayersAtBeginOfPageStyle} the last layer at -\PName{layer list} will become the new first layer of the layer list of layer -page style \PName{page style name}. - -Command \Macro{RemoveLayersFromPageStyle} may be used to remove layers from -the layer list of layer page style \PName{page style name} instead of adding -them. Note, layers, which are part of \PName{layer list}, but not part of -the page style's layer list, will be ignored. But adding or removing layers -from a page style, which is not a layer page style or an alias of a layer page -style, would be a mistake and result in an error message.% +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +You can use these commands to add layers to a layer page style or to remove +layers from a layer page style. The page style is referenced by its +\PName{page style name}. The layers are given by a comma-separated +\PName{layer list}. + +Both the \Macro{AddLayersToPageStyle} and the +\Macro{AddLayersAtEndOfPageStyle}\textnote{add at the end} commands insert the +new layers at the bottom of the page style's layer list. Logically, the newly +added layers lie above or in front of the old layers. Background layers, of +course, still are logically behind the text layer and thus behind all +foreground layers. + +In contrast, the \Macro{AddLayersAtBeginOfPageStyle}\textnote{add at the + beginning} command inserts the new layers at the top of the page style's +layer list. The layers are separately inserted to the top of the list in the +same order they appear in the \PName{layer list} parameter. This means that +the last layer in the \PName{layer list} parameter will become the first, and +thus the lowest, layer of the page style. + +\iffalse% Umbruchkorrekturtext (beim Aktiveren muss unten \textnote{remove} +% entfernt werden!) +The \Macro{RemoveLayersFromPageStyle} command is exactly the opposite. It +removes\textnote{remove} the specified page-style levels.% +\fi + +The \Macro{RemoveLayersFromPageStyle}\textnote{remove} command removes layers +from the layer list of the page style named \PName{page style name}. +Attempting to remove layers which are not part of the page style's layer list +will be ignored. But attempting to add layers to or remove layers from a page +style that is neither a layer page style nor a page-style alias is an error +and will be reported as such.% \EndIndexGroup @@ -1189,29 +1293,46 @@ style, would be a mistake and result in an error message.% \Parameter{page style name}\Parameter{layer list}% \Parameter{reference layer name} \end{Declaration} -These commands are similar to the commands described before, but they do not -add the layers at the begin or end of the layer list of a layer page style, -but just before or after a reference layer at the layer list of a layer page -style. Note, in this case the order of the \PName{layer list} will be -same in the layer list of \PName{page style name} after adding. If the -reference layer named \PName{reference layer name} is not part of the layer -list of the layer page style, nothing happens.% +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +\iffalse% Umbruchvarianten +These two commands are similar to the previous ones, but they take an +additional parameter, \Parameter{reference layer name}. The layer list of +the page style named in \Parameter{page style name} is searched for this +reference layer. % +\else% +These commands are similar to the previous ones. The existing layers of the +page style, however, are searched for the \PName{reference layer name}. % +\fi% +The layers in the \Parameter{layer list} parameter are then inserted +before\textnote{add before/after layer} or after this reference layer% +\iffalse% Umbruchkorrekturtext +in the layers of the page style% +\fi% +. The order of the layers in the \PName{layer list} is retained. + +If the reference layer named \PName{reference layer name} is not part of the +given page style, nothing is inserted. On the other hand, if the page style is +neither a layer page style nor a page-style alias, an error will be reported.% \EndIndexGroup \begin{Declaration} \Macro{UnifyLayersAtPageStyle}\Parameter{page style name} \end{Declaration} -With the commands described before in this section you may not only add -different layers to a page style, but even add the same layer several times to -a page style. In most cases it does not make sense to have one layer several -times at the layer list of a layer page style. So you may use -\Macro{UnifyLayersAtPageStyle} to remove all dupes of layers from the layer -list of a layer page style. - -Note\textnote{Attention!}, the order of layers may change! So if -you want a special order, you should remove all layers and add the layers in -the order you want instead of using \Macro{UnifyLayersAtPageStyle}.% +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +The commands for defining page styles or adding layers to a page style do not +care how many times a layer appears in a page style, so it is quite +permissible for a layer to appear multiple times. In most cases, however, it +does not make sense to use the same layer several times in one page style. +Therefore, you can use \Macro{UnifyLayersAtPageStyle} to remove all layer +duplicates from the layer page style of the specified \Parameter{page style + name}. + +Note\textnote{Attention!} that this function can change the order of layers. +So if you need a specific order, you should remove all layers and add the +layers in the order you want instead of using \Macro{UnifyLayersAtPageStyle}.% \EndIndexGroup @@ -1221,19 +1342,25 @@ the order you want instead of using \Macro{UnifyLayersAtPageStyle}.% \Macro{AddToLayerPageStyleOptions}% \Parameter{page style name}\Parameter{option list} \end{Declaration} -Command \Macro{ModifyLayerPageStyleOptions} may be used to modify the page -style options of a layer page style. Only options at the comma separated -\PName{option list} will be set to the new values given in \PName{option list} -if the new value is not empty. Options, which are not at \PName{option list}, -will stay unchanged. If you want to set an option to \emph{do nothing} you may -use value \Macro{relax}. Note, setting an option to a new value using -\Macro{ModifyLayerPageStyleOptions} will remove the previous value including -the global default value. - -\Macro{AddToLayerPageStyleOptions} differs from -\Macro{ModifyLayerPageStyleOptions} in that point. It will not overwrite the -previous values, but adds\,---\,or more precisely: concatenates\,---\, the new -values to the previous values of the options at \PName{option list}.% +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +These two commands can be used to modify the options, and thus the +hooks\Index{hooks}, of a layer page style. With +\Macro{ModifyLayerPageStyleOptions}\textnote{change page-style options}, only +the options in the comma-separated \PName{option list} will be set to the new +values given there. The previous values are lost. All options from +\autoref{tab:scrlayer.pagestyle.hooks}, +\autopageref{tab:scrlayer.pagestyle.hooks} are allowed. Options or hooks that +are not specified in the \PName{option list} will remain unchanged. If you +want to set an option to do nothing you can set it to the value \Macro{relax}. +Setting an option to a new value using \Macro{ModifyLayerPageStyleOptions} +will remove the previous value, including the global default value. This +statement is the only way to remove the global defaults of the \KOMAScript{} +options from a page style. + +\Macro{AddToLayerPageStyleOptions}\textnote{extend page-style options}, on the +other hand, does not overwrite the previous values. Instead it adds\,---\,or, +more precisely, concatenates\,---\, the new values to old ones.% \EndIndexGroup @@ -1243,20 +1370,21 @@ values to the previous values of the options at \PName{option list}.% \Macro{IfRealLayerPageStyleExists}%^ \Parameter{page style name}\Parameter{then code}\Parameter{else code}% \end{Declaration} -Command \Macro{IfLayerPageStyleExists} tests, whether or not the real page -style of \PName{page style name} is a layer page style. If the test is true, -\PName{then code} will be executed. If \PName{page style name} is neither a -layer page style, nor an alias of a layer page style, nor an alias of an alias -of \dots\ a layer page style, \PName{else code} will be executed. Internally -this command is often used to throw an error message if you use one of the -layer page style commands with an \PName{page style name} that does not -correspond with a layer page style. - -Command \Macro{IfRealLayerPageStyleExists} is similar, but \PName{then code} -will only be executed, if \PName{page style name} itself is the name of a -layer page style. So \PName{else code} will even be executed, if \PName{page - style name} is an alias name of a layer page style or the alias name of an -alias name of \dots\ a layer page style.% +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +With these commands, you can execute code depending on whether a page style is +a layer page style or not. The \Macro{IfLayerPageStyleExists} command executes +the \PName{then code} if \PName{page style name} is the name of a layer page +style or a page-style alias that results in a layer page style. Otherwise, the +command executes the \PName{else code}. Internally, this command is often used +to throw an error message if you use one of the layer page style commands with +an \PName{page style name} that does not correspond to a layer page style. + +The \Macro{IfRealLayerPageStyleExists} command goes one step further and +executes the \PName{then code} only if the page style specified by \PName{page + style name} is itself a layer page style. So if \PName{page style name} is a +page-style alias, this command executes the \PName{else code} even if the +alias resolves to a real layer page style.% \EndIndexGroup @@ -1271,85 +1399,106 @@ alias name of \dots\ a layer page style.% \Parameter{page style name}\Parameter{layer list}% \Parameter{then code}\Parameter{else code}% \end{Declaration} -Command \Macro{IfLayerAtPageStyle} may be used to test, whether or not a layer -named \PName{layer name} is a member of the layer list of a given page -style. If the test is true, the \PName{then code} will be executed. If the -layer is not a member of the layer list of \PName{page style name}, the -\PName{else code} will be executed. - -Commands \Macro{IfSomeLayerAtPageStyle} and \Macro{IfLayersAtPageStyle} do not -only test one layer but several layers at a given, comma separated -\PName{layer list}. \Macro{IfSomeLayerAtPageStyle} will execute the -\PName{then code} if \emph{at least one} of the layers at \PName{layer list} -is a member of the layer list of \PName{page style name}. In difference -\Macro{IfLayersAtPageStyle} executes the \PName{then code} only if \emph{all} -of the layers at \PName{layer list} are members of the layer list of -\PName{page style name}.% +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +These commands can be used to test whether one or more layers are part of a +page style. The \Macro{IfLayerAtPageStyle} command expects exactly one +\PName{layer name}\textnote{exactly one layer} as the second argument. If this +layer is part of the page style specified in \PName{page style name}, the +\PName{then code} will be executed. Otherwise, the \PName{else code} will be +executed. + +The \Macro{IfSomeLayerAtPageStyle} and \Macro{IfLayersAtPageStyle} commands +allow a comma-separated \PName{layer list}. \Macro{IfSomeLayerAtPageStyle} +will execute the \PName{then code} if \emph{at least one} of the layers in the +\PName{layer list} parameter is part of the layer list of \PName{page style + name}. In contrast, \Macro{IfLayersAtPageStyle} executes the \PName{then + code} only if \emph{all} the layers in the \PName{layer list} parameter are +part of the page style. If the condition is not met, the \PName{else code} +will be executed. + +With suitable nesting of these commands, you can construct complex conditions. +If you use only one \PName{layer name} in the \PName{layer list}, all three +statements are synonymous.% \EndIndexGroup \begin{Declaration} \Macro{DestroyRealLayerPageStyle}\Parameter{page style name} \end{Declaration} -Command \Macro{DestroyRealLayerPageStyle} makes the page style named -\PName{page style name} undefined, if and only if it is a layer page -style. Nothing will be happen if it is an alias name of a layer page style, if -it is another page style, or if it is not a page style. - -If \PName{page style name} is the name of the current page style the current -page style will become a kind of empty page style. If the special page -style\,---\,this may be set using \DescRef{maincls.cmd.thispagestyle}\,---\,is -\PName{page style name}, this will be simply reset. So the previous -\DescRef{maincls.cmd.thispagestyle} will become invalid. - -Note, the layers of the page style will not be destroyed -automatically. If you want to destroy the layers too, you may use -% Umbruchkorrektur +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +\iftrue +This statement makes a layer page style undefined. If a page-style alias or +ordinary page style is specified, the command is ignored. +\else +With this command you can remove a the definition of a layer page style. +However, this only occurs if a layer page style named \PName{page style name} +exists. If, instead, it is a page-style alias, a different (non-layer) page +style, or not a page style at all, nothing happens; the command is ignored.% +\fi + +If \PName{page style name} is the name of the current page style, the current +page style will becomes a kind of empty page style. If the page style set with +\DescRef{maincls.cmd.thispagestyle} is \PName{page style name}, it will simply +be reset. The previous \DescRef{maincls.cmd.thispagestyle} command loses its +current effect. + +Note\textnote{Attention!} that the layers of the page style are not destroyed +automatically. If you want to destroy the layers too, you can do this with: \begin{lstcode} \ForEachLayerOfPageStyle{...}{\DestroyLayer{#1}} \end{lstcode} -\emph{before} destroying the layer page style. +before destroying the layer page style itself. -The command is intended to be used inside the auto-remove code of an interface -See \autoref{sec:scrlayer.enduserinterfaces} below for more information about -auto-remove code.% +The command is intended to be used within the \PName{code} argument of +\DescRef{\LabelBase.cmd.scrlayerOnAutoRemoveInterface} to remove page styles +that are defined as part of an end-user interface. See +\autoref{sec:scrlayer.enduserinterfaces} below for more information about +auto-removal code.% +\EndIndexGroup \EndIndexGroup \LoadCommonFile{headfootheight}% \section{Height of Page Head and Foot} \LoadCommonFile{pagestylemanipulation}% \section{Manipulation of Defined Page Styles} -\section{End User Interfaces} +\section{Defining and Managing Interfaces for End Users} \seclabel{enduserinterfaces} -Package \Package{scrlayer} provides an interface to define and manage -(concurrent) end user interfaces. Maybe future releases of \KOMAScript{} will -provide parts of this by package \Package{scrbase} and remove those commands -from \Package{scrlayer}. But currently this part if \Package{scrlayer} is very -experimental, so package \Package{scrlayer} provides its own interface -definition commands. Currently you should not depend on correct working of -auto-removing a concurrent end user interface. Instead you should avoid using -concurrent end user interfaces. - -This section only describes the interface commands for defining end user -interfaces. This is not interesting for end users, but only for authors of end -user interfaces. End users will find information about the end user interfaces -in the sections about the particular end user interface, e.g., -\autoref{cha:scrlayer-scrpage}, \autoref{cha:scrlayer-scrpage-experts}, and -\autoref{cha:scrlayer-notecolumn}. +The \Package{scrlayer} package provides an experimental interface to define +and manage (concurrent) interfaces for end users. \iffree{In the long run, + this interface may disappear from \Package{scrlayer} and be taken over by + \Package{scrbase} instead.}{} Currently, this interface is highly +experimental% +\iffree{ and therefore \Package{scrlayer} provides these interface commands + only for the use of subpackages of \Package{scrlayer}}{}% +. Given the current state of development, you should not depend on automatic +removal of a concurrent interface to work. Instead, you should avoid using +concurrent end-user interfaces. + +This section only describes the interface commands for defining an end-user +interface. For end users themselves, it is of little interest. Rather, this +section is intended for authors of packages and classes that build on +\Package{scrlayer}. End users will find information about specific end-user +interfaces in \autoref{cha:scrlayer-scrpage}, +\autoref{cha:scrlayer-scrpage-experts}, and \autoref{cha:scrlayer-notecolumn}. \begin{Declaration} \Macro{scrlayerInitInterface}\OParameter{interface name} \end{Declaration} -Command \Macro{scrlayerInitInterface} -registers a new interface. The \PName{interface name} must be unique. If you -try to initialise an already initialised interface an error will occur. This -command is obligatory and mandatory for interfaces. It should be the first -interface command and therefore has been described first. If the optional -argument is omitted, \PValue{\Macro{@currname}.\Macro{@currext}} will be -used instead. For classes and packages this will be the file name of the class -or package while loading the class or package. But you may use any sequence of -characters with category letter or other.% +The \Macro{scrlayerInitInterface} command registers a new interface named +\PName{interface name}. The \PName{interface name} must be unique. If an +interface with the same name has already been registered, an error will occur. + +This command should always appear as the first command when defining an +end-user interface and therefore is described here first. If the optional +argument\,---\,including the square brackets\,---\,is omitted, +\PValue{\Macro{@currname}.\Macro{@currext}} will be used instead. For classes +and packages, this is the file name of the class or package. But of course you +can use any other sequence of characters with a category of \emph{letter} or +\emph{other}. This is useful, for example, when a class or package defines +multiple end-user interfaces% \EndIndexGroup @@ -1361,39 +1510,47 @@ characters with category letter or other.% \Macro{scrlayerAddCsToInterface}% \OParameter{interface name}\Parameter{command sequence}\Parameter{code} \end{Declaration} -One of the special features of end user interfaces is that they should -register all interface dependent commands (also known as \emph{macros}). You -may do this using \Macro{scrlayerAddToInterface}% -. If your interface generates macros not only at load time but also at run -time or if the interface name should not be the class's or package's name, you -have to use the optional argument to add the command to a dedicated -interface. An error will occur, if the interface has not been initialised -before. +One of the special features of \Package{scrlayer}'s end user interfaces is +that they should register all interface-dependent commands (also known as +\emph{macros}). You can do this using \Macro{scrlayerAddToInterface}. The +optional argument \PName{interface name} must be an interface name previously +registered with \DescRef{\LabelBase.cmd.scrlayerInitInterface}. An error will +occur if the interface has not been initialised. + +If\textnote{Attention!} your interface defines macros not just when the class +or package is being loaded but also at runtime, you must provide the interface +name in the optional argument even if it corresponds to the file name of the +class or package, since the values of \Macro{@currname} and \Macro{@currext} +are only valid while the class or package is being loaded. The first mandatory argument is the \PName{command}\footnote{The - \PName{command} consists of the backslash followed by a \PName{command - sequence} consisting of characters with category code letter or one other - character, or \PName{command} consists of one active character (without - backslash).} that should be added to the interface. If the command can be -added to the interface, it will be added to the interface, will be set to -\Macro{relax} and \PName{code} will be executed. You can use, e.g., -\Macro{newcommand}\PName{command} inside of \PName{code} to define -\PName{command}. - -But when can a command be defined? If a command is undefined or \Macro{relax} -it can be defined. If a command has already been defined and registered for -another interface \emph{and} if \KOMAScript{} option -\Option{autoremoveinterfaces} has been switched on, the other interface will be -removed automatically and the new command will be set to \Macro{relax} and -will be registered for the given interface. If a command -has already been defined but is not part of another interface \emph{and} if -\KOMAScript{} option \Option{forceoverwrite} has been switched on, the command -will be set to \Macro{relax} and will be registered for the given interface. - -Command \Macro{scrlayerAddCsToInterface} is similar to -\Macro{scrlayerAddToInterface} but does not expect a command as first, -mandatory argument, but a command sequence\footnote{A command sequence may - consist of any characters with category code letter or other.}.% + \PName{command} consists of a backslash followed by a \PName{command + sequence} that consists of characters of the category code \emph{letter}, + or of exactly one character of the category \emph{other}, or of a character + of the category \emph{active} (without the backslash).} to be added to the +interface. If the command can be defined, this will be done. In addition, it +will set to \Macro{relax} and \PName{code} will be executed. Within +\PName{code}, you can then define \PName{command}, e.\,g., using +\Macro{newcommand}. + +But when can a command be defined? If a command is undefined or \Macro{relax}, +it can always be defined. If a command has already been defined \emph{and} +registered for another interface \emph{and} if the \KOMAScript{} option +\Option{autoremoveinterfaces} has been activated, the other interface will be +removed automatically, and the \PName{command} will be set to \Macro{relax} +and registered for the new interface specified. If a \PName{command} is +already defined but is \emph{not} part of another interface, \emph{and} if the +\KOMAScript{} option \Option{forceoverwrite} has been activated, the +\PName{command} is also set to \Macro{relax} and registered for the specified +interface. In all other cases, however, the command is not definable, in +particular if it is already defined and the \KOMAScript{} options +\Option{autoremoveinterfaces} and \Option{forceoverwrite} are deactivated. + +The \Macro{scrlayerAddCsToInterface} command is similar to +\Macro{scrlayerAddToInterface} but it expects the first argument to be not a +\PName{command} but a command sequence\footnote{A command sequence must be + fully expandable and its expansion must result in characters of the category + code \emph{letter}, \emph{other}, or \emph{space}.}.% \EndIndexGroup @@ -1401,13 +1558,17 @@ mandatory argument, but a command sequence\footnote{A command sequence may \Macro{scrlayerOnAutoRemoveInterface}% \OParameter{interface name}\Parameter{code} \end{Declaration} -Command \Macro{scrlayerOnAutoRemoveInterface} registers \PName{code} to be -executed, if the interface will be automatically removed (see -\DescRef{\LabelBase.option.autoremoveinterfaces} prior in this section). This -may be used, e.g., to automatically destroy layers or page styles (see +The \Macro{scrlayerOnAutoRemoveInterface} command registers \PName{code} to be +executed in the event that the end-user interface with the specified +\PName{interface name} is automatically removed (see +\DescRef{\LabelBase.option.autoremoveinterfaces} earlier in this section). +This can be used, for example, to automatically destroy layers or page styles +that rely on commands from the end-user interface (see \DescRef{\LabelBase.cmd.DestroyLayer}, \DescRef{\LabelBase.cmd.DestroyPageStyleAlias}, and -\DescRef{\LabelBase.cmd.DestroyRealLayerPageStyle}).% +\DescRef{\LabelBase.cmd.DestroyRealLayerPageStyle}). Regarding the default for +the optional argument, please refer to the explanation for +\DescRef{\LabelBase.cmd.scrlayerInitInterface}.% \EndIndexGroup % \EndIndexGroup diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex index 8279b16672d..a01a4a0035a 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrlfile.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrlfile.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,109 +46,105 @@ % ============================================================================ \KOMAProvidesFile{scrlfile.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (chapter: scrlfile)] -\translator{Gernot Hassenpflug\and Markus Kohm} +\translator{Gernot Hassenpflug\and Markus Kohm\and Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-02-15 -\chapter{Control Package Dependencies with \Package{scrlfile}} +\chapter{Controlling Package Dependencies with \Package{scrlfile}} \labelbase{scrlfile} \BeginIndexGroup \BeginIndex{Package}{scrlfile} -The introduction of {\LaTeXe} in 1994 brought many changes in the -handling of {\LaTeX} extensions. Today the package author has many -macros available to determine if another package or class is -employed and whether specific options are used. The author can load -other packages or can specify options in the the case that the -package is loaded later. This has led to the expectation that the -order in which package are loaded would not be important. Sadly -this hope has not been fulfilled. +The introduction of \LaTeXe{} in 1994 brought many changes in the handling of +\LaTeX{} extensions. The package author today has a whole series of macros +available to determine if another package or class has been loaded and whether +specific options are being used. The package author can even load other +packages or specify certain options in case the package is loaded later. This +has led to the expectation that the order in which package are loaded would +not be important. Sadly, this hope has not been fulfilled. \section{About Package Dependencies} \seclabel{dependency} +%\begin{Explain} +More and more often, different packages either newly define or redefine the +same macro. In such a case, the order in which a package is loaded becomes +very important. Sometimes, users find it very difficult to understand the +resulting behaviour. Sometimes it is necessary to react in a specific way when +another package is loaded. + +As a simple example, consider loading the \Package{longtable} package with a +\KOMAScript{} document class. The \Package{longtable} package defines its own +table captions. These are perfectly suited to the standard classes, but they +do not match the default settings for \KOMAScript{} captions, nor do they +react to the relevant configuration options. To solve this problem, the +\Package{longtable} package commands which are responsible for the table +captions need to be redefined. However, by the time the \Package{longtable} +package is loaded, the \KOMAScript{} class has already been processed. + +Previously, the only way to solve this problem was to delay the redefinition +until the beginning of the document using \Macro{AtBeginDocument}. However, if +users want to change the relevant commands themselves, they should do so in +the preamble of the document. But this is impossible because \KOMAScript{} +will overwrite the users' definitions at \Macro{begin}\PParameter{document}. +They would also need to perform the redefinition with \Macro{AtBeginDocument}. + +But \KOMAScript{} does not actually need to wait for +\Macro{begin}\PParameter{document} to redefine the macros. It would be +sufficient to postpone the redefinition until after the \Package{longtable} +package has been loaded. Unfortunately, the \LaTeX{} kernel does not define +necessary commands. The \Package{scrlfile} package provides a remedy for this +problem. + +It is also conceivable that you would like to save the definition of a macro +in a temporary macro before a package is loaded and restore it after the +package has been loaded. The \Package{scrlfile} package allows this, too. + +The use of \Package{scrlfile} is not limited to package dependencies. +Dependencies can also be considered for any other file. For example, you can +ensure that loading the not unimportant file \File{french.ldf} automatically +leads to a warning. -More and more frequently, different packages either newly define or -redefine the same macro again. In such a case the order in which a -package is loaded becomes very important. For the user it sometimes -becomes very difficult to understand the behaviour, and in some -cases the user wants only to react to the loading of a package. This -too is not really a simple matter. - -Let us take the simple example of loading the package \Package{longtable} with -a {\KOMAScript} document class. The \Package{longtable} package defines table -captions very well suited to the standard classes, but the captions are -totally unsuitable for documents using {\KOMAScript} and also do not react to -the options of the provided configuration commands. In order to solve this -problem, the \Package{longtable} package commands which are responsible for -the table captions need to be redefined. However, by the time the -\Package{longtable} package is loaded, the {\KOMAScript} class has already -been processed. - -Until the present, the only way for {\KOMAScript} to solve this problem was to -delay the redefinition until the beginning of the document with help of the -macro \Macro{AtBeginDocument}. If the user wants to change the definitions -too, it is recommended to do this in the preamble of the document. However, -this is impossible since later at \Macro{begin}\PParameter{document} -{\KOMAScript} will again overwrite the user definition with its own. -Therefore, the user too has to delay his definition with -\Macro{AtBeginDocument}. - -Actually, {\KOMAScript} should not need to delay the redefinition until -\Macro{begin}\PParameter{document}. It would be enough to delay exactly until -the package \Package{longtable} has been loaded. Unfortunately, the {\LaTeX} -kernel does not define appropriate commands. The package \Package{scrlfile} -provides redress here. - -Likewise, it might be conceivable that before a package is loaded one would -like to save the definition of a macro in a help-macro, in order to restore -its meaning after the package has been loaded. The package \Package{scrlfile} -allows this, too. - -The employment of \Package{scrlfile} is not limited to package dependencies -only. Even dependencies on any other file can be considered. For example, -the user can be warned if the not uncritical file \File{french.ldf} has been -loaded. - Although the package is particularly of interest for package authors, there -are of course applications for normal {\LaTeX} users, too. Therefore, this -chapter gives and explains examples for both groups of users. +are also applications for normal \LaTeX{} users. Therefore, this chapter +gives examples for both groups. +%\end{Explain} -\section{Actions Prior to and After Loading} +\section{Actions Before and After Loading} \seclabel{macros} -\Package{scrlfile} can execute actions both before and after the -loading of files. In the commands used to do this, distinctions are -made made between general files, classes, and packages. +The \Package{scrlfile} package can execute actions both before and after +loading files. The commands used to do so distinguish between ordinary files, +classes, and packages. \begin{Declaration} - \Macro{BeforeFile}\Parameter{file}\Parameter{instructions}% - \Macro{AfterFile}\Parameter{file}\Parameter{instructions} + \Macro{BeforeFile}\Parameter{file}\Parameter{commands}% + \Macro{AfterFile}\Parameter{file}\Parameter{commands} \end{Declaration}% -The macro \Macro{BeforeFile} ensures that \PName{instructions} are -only executed before the next time \PName{file} is loaded. -\Macro{AfterFile} works in a similar fashion, and the -\PName{instructions} will be executed only after the \PName{file} has -been loaded. If \PName{file} is never loaded then the -\PName{instructions} will never be executed. - -In order to implement those features \Package{scrlfile} redefines the well -known {\LaTeX} command \Macro{InputIfFileExists}. If this macro does not have -the expected definition then \Package{scrlfile} issues a warning. This is for -the case that in future {\LaTeX} versions the macro can have a different -definition, or that another package has already redefined it. - -The command \Macro{InputIfFileExists} is used by {\LaTeX} every time a file is -to be loaded. This is independent of whether the actual load command is +\Macro{BeforeFile} ensures that the \PName{commands} are executed before the +next time \PName{file} is loaded. \Macro{AfterFile} works in a similar +fashion, and the \PName{commands} will be executed after the \PName{file} has +been loaded. Of course, if \PName{file} is never loaded, the \PName{commands} +will never be executed. For \PName{file}, you should specify any extensions as +part of the file name, as you would with \Macro{input}. + +To implement those features, \Package{scrlfile} redefines the well-known +\LaTeX{} command \Macro{InputIfFileExists}. If this command does not have the +expected definition, \Package{scrlfile} issues a warning. This occurs in case +the command is changed in future \LaTeX{} versions or has already been +redefined by another package. + +\LaTeX{} uses the \Macro{InputIfFileExists} command every time it loads a +file. This occurs regardless of whether the file is loaded with \Macro{include}, \Macro{LoadClass}, \Macro{documentclass}, \Macro{usepackage}, -\Macro{RequirePackage}, or similar. Exceptionally, the command +\Macro{RequirePackage}, or similar commands. Only \begin{lstcode} \input foo \end{lstcode} -loads the file \texttt{foo} without utilizing -\Macro{InputIfFileExists}. Therefore, one should always use +loads the file \texttt{foo} without using +\Macro{InputIfFileExists}. You should therefore always use \begin{lstcode} \input{foo} \end{lstcode} @@ -158,70 +154,76 @@ instead. Notice the parentheses surrounding the file name!% \begin{Declaration} - \Macro{BeforeClass}\Parameter{class}\Parameter{instructions}% - \Macro{BeforePackage}\Parameter{package}\Parameter{instructions} + \Macro{BeforeClass}\Parameter{class}\Parameter{commands}% + \Macro{BeforePackage}\Parameter{package}\Parameter{commands} \end{Declaration}% -These two commands work in the same way as \DescRef{\LabelBase.cmd.BeforeFile}. The only -difference is that the document class \PName{class} and the {\LaTeX} package -\PName{package} are specified with their names and not with their file names. -That means that the file extensions \File{.cls} and \File{.sty} can be -omitted.% +These two commands work the same way as \DescRef{\LabelBase.cmd.BeforeFile}. +The only difference is that the \PName{class} or \PName{package} is specified +with its class or package name and not with its file name. That means you +should omit the file extensions \File{.cls} or \File{.sty}.% % \EndIndexGroup \begin{Declaration} - \Macro{AfterClass}\Parameter{class}\Parameter{instructions}% - \Macro{AfterClass*}\Parameter{class}\Parameter{instructions}% - \Macro{AfterClass+}\Parameter{class}\Parameter{instructions}% - \Macro{AfterClass!}\Parameter{class}\Parameter{instructions}% - \Macro{AfterAtEndOfClass}\Parameter{class}\Parameter{instructions}% - \Macro{AfterPackage}\Parameter{package}\Parameter{instructions}% - \Macro{AfterPackage*}\Parameter{package}\Parameter{instructions}% - \Macro{AfterPackage+}\Parameter{package}\Parameter{instructions}% - \Macro{AfterPackage!}\Parameter{package}\Parameter{instructions}% - \Macro{AfterAtEndOfPackage}\Parameter{package}\Parameter{instructions} + \Macro{AfterClass}\Parameter{class}\Parameter{commands}% + \Macro{AfterClass*}\Parameter{class}\Parameter{commands}% + \Macro{AfterClass+}\Parameter{class}\Parameter{commands}% + \Macro{AfterClass!}\Parameter{class}\Parameter{commands}% + \Macro{AfterAtEndOfClass}\Parameter{class}\Parameter{commands}% + \Macro{AfterPackage}\Parameter{package}\Parameter{commands}% + \Macro{AfterPackage*}\Parameter{package}\Parameter{commands}% + \Macro{AfterPackage+}\Parameter{package}\Parameter{commands}% + \Macro{AfterPackage!}\Parameter{package}\Parameter{commands}% + \Macro{AfterAtEndOfPackage}\Parameter{package}\Parameter{commands} \end{Declaration}% -The commands \Macro{AfterClass} and \Macro{AfterPackage} work in the -same way as \DescRef{\LabelBase.cmd.AfterFile}. The only difference is that the -document class \PName{class} and the {\LaTeX} package \PName{package} -are specified with their names and not with their file names. That -means that the file extensions \File{.cls} and \File{.sty} can be -omitted. +The \Macro{AfterClass} and \Macro{AfterPackage} commands work much like +\DescRef{\LabelBase.cmd.AfterFile}. The only difference is that the +\PName{class} or \PName{package} is specified with its class or package name +and not with its file name. That means you should omit the file extensions +\File{.cls} or \File{.sty}. The\important[i]{\Macro{AfterClass*}\\\Macro{AfterPackage*}} starred versions -are a little bit different. They execute the \PName{instructions} not only at -next time that the class or package is loaded, but also immediately if the -class or package has been loaded already. +function somewhat differently. If the class or package has already been +loaded, they execute the \PName{commands} immediately rather than waiting +until the next time the class or package is loaded. The\important[i]{\Macro{AfterClass+}\\\Macro{AfterPackage+}} -plussed\ChangedAt{v3.09}{\Package{scrlfile}} version executes the -\PName{instructions} after loading of the class or package has been -finished. The difference to the starred version is only valid, if loading of -the class or package already started but has not been finished -yet. Nevertheless, \PName{instructions} will be executed before the -instructions of \Macro{AtEndOfClass} or \Macro{AtEndOfPackage} when loading of -the class or package has not been finished already. +plus\ChangedAt{v3.09}{\Package{scrlfile}} version executes the +\PName{commands} after the class or package has been completely loaded. This +behaviour differs from that of the starred version only if you use the command +when the class or package has begun loading but has not yet finished. If the +class or package has not finished loading, the \PName{commands} will always be +executed before the commands in \Macro{AtEndOfClass} or +\Macro{AtEndOfPackage}. If\important[i]{\Macro{AfterClass!}\\\Macro{AfterPackage!}} a class uses \Macro{AtEndOfClass} or a package uses \Macro{AtEndOfPackage} to execute -instructions after the class of package file has been loaded completely, and -if you want to execute \PName{instructions} after the instructions of these -commands, you may use the exclamation mark version, -\Macro{AfterClass!}\ChangedAt{v3.09}{\Package{scrlfile}} respectively +commands after the class of package file has been loaded completely, and +if you want to execute \PName{commands} after these deferred +commands have been executed, you can use the exclamation-mark versions +\Macro{AfterClass!}\ChangedAt{v3.09}{\Package{scrlfile}} or \Macro{AfterPackage!}. If\important[i]{\Macro{AfterAtEndOfClass}\\\Macro{AfterAtEndOfPackage}} you -want to do this only in the case the class or package will be loaded later, -and if you want to execute \PName{instructions} outside the context of the -class or package, that will be loaded, you may use +want to execute the \PName{commands} only when the class or package is loaded +later and outside the context of that class or package, you can use \Macro{AfterAtEndOfClass}\ChangedAt{v3.09}{\Package{scrlfile}} for classes and \Macro{AfterAtEndOfPackage} for packages. \begin{Example} - In the following, an example for class and package authors shall be - given. It shows how {\KOMAScript} itself employs the new commands. - The class \Class{scrbook} contains: + The following example for class and package authors shows how \KOMAScript{} + itself makes use of the new commands. The class \Class{scrbook} contains the + following: +% CORRECTED MESSAGE: +% You are using an old version of the hyperref +% package!\MessageBreak% +% This version has a buggy hack in many +% drivers,\MessageBreak% +% causing \string\addchap\space to behave +% strangely.\MessageBreak% +% Please update hyperref to at least version +% 6.71b}% \begin{lstcode} \AfterPackage{hyperref}{% \@ifpackagelater{hyperref}{2001/02/19}{}{% @@ -236,48 +238,40 @@ class or package, that will be loaded, you may use 6.71b}}} \end{lstcode} Old versions of the \Package{hyperref} package redefine a macro of the - \Class{scrbook} class in such a way that does not work with newer - {\KOMAScript} versions. New versions of \Package{hyperref} desist - from making these changes if a new {\KOMAScript} version is detected. - For the case that \Package{hyperref} is loaded at a later stage, - therefore, the code in \Class{scrbook} verifies that a acceptable - \Package{hyperref} version is used. If not, the command issues a - warning. - - At other places in three {\KOMAScript} classes the following can be - found: + \Class{scrbook} class in a way that is incompatible with newer \KOMAScript{} + versions. Newer versions of \Package{hyperref} refrain from making this + change if a newer version of \KOMAScript{} is detected. In case + \Package{hyperref} is loaded at a later stage, \Class{scrbook} ensures that + a check for an acceptable version of \Package{hyperref} is performed + immediately after the package is loaded. If this is not the case, a warning + is issued. + + Elsewhere in three of the \KOMAScript{} classes, you can find the following: \begin{lstcode} \AfterPackage{caption2}{% \renewcommand*{\setcapindent}{% \end{lstcode} - After the package \Package{caption2} has been loaded, and only if it - has been loaded, {\KOMAScript} redefines its own command - \DescRef{maincls.cmd.setcapindent}. The exact code of the redefinition is - not important. It should only be noted that \Package{caption2} takes - control of the \DescRef{maincls.cmd.caption} macro and that therefore the - normal definition of the \DescRef{maincls.cmd.setcapindent} macro would - become ineffective. The redefinition improves the collaboration with - \Package{caption2}. - - There are however also useful examples for normal {\LaTeX} user. Suppose a - document that should be available as a PS file, using {\LaTeX} and dvips, as - well as a PDF file, using pdf{\LaTeX}. In addition, the document should - contain hyperlinks. In the list of tables there are entries longer than one - line. This is not a problem for the pdf{\LaTeX} method, since here - hyperlinks can be broken across multiple lines. However, if a - \Package{hyperref} driver for dvips or hyper{\TeX} is used then this is not - possible. In this case one desires that for the \Package{hyperref} setup - \Option{linktocpage} is used. The decision which \Package{hyperref} driver - to use happens automatically via \File{hyperref.cfg}. The file has, for - example, the following content: -\begin{lstcode} - \ProvidesFile{hyperref.cfg} - \@ifundefined{pdfoutput}{\ExecuteOptions{dvips}} - {\ExecuteOptions{pdftex}} - \endinput -\end{lstcode} - - All the rest can now be left to \DescRef{\LabelBase.cmd.AfterFile}. + After loading \Package{caption2}, and only if it has been loaded, + \KOMAScript{} redefines its own \DescRef{maincls.cmd.setcapindent} command. + The exact code of the redefinition is irrelevant. The important thing to + note is that \Package{caption2} takes control of the + \DescRef{maincls.cmd.caption} macro and that therefore the normal definition + of the \DescRef{maincls.cmd.setcapindent} command would have no effect. The + redefinition thus improves interoperability with \Package{caption2}. + + There are also, however, instances where these commands are useful to normal + \LaTeX{} users. For example, suppose you create a document from which you + want to generate both a PostScript file, using \LaTeX{} and dvips, and a PDF + file, using \mbox{pdf{\LaTeX}}. The document should also contain hyperlinks. + In the table of contents, you have entries that span several lines. This is + not a problem for the \mbox{pdf{\LaTeX}} method, since here hyperlinks can + be broken across multiple lines. However, this is not possible with the + \Package{hyperref} driver for dvips or \mbox{hyper{\TeX}}. In this case, you + would like \Package{hyperref} to use the \Option{linktocpage} option. The + decision as to which driver is loaded is made automatically by + \File{hyperref}. + + Everything else can now be left to \DescRef{\LabelBase.cmd.AfterFile}: \begin{lstcode} \documentclass{article} \usepackage{scrlfile} @@ -288,37 +282,45 @@ class or package, that will be loaded, you may use \listoffigures \clearpage \begin{figure} - \caption{This is an example for a fairly long figure caption, but - which does not employ the optional caption argument that would - allow one to write a short caption in the list of figures.} + \caption{This is an example of a fairly long figure caption, but + one that does not use the optional caption argument that would + allow you to write a short caption in the list of figures.} \end{figure} \end{document} \end{lstcode} - If now the \Package{hyperref} drivers \Option{hypertex} or - \Option{dvips} are used, then the useful \Package{hyperref} option - \Option{linktocpage} will be set. In the pdf{\LaTeX} case, the option - will not be set, since in that case another \Package{hyperref} driver, - \File{hpdftex.def}, will be used. That means neither \File{hdvips.def} + If either of the \Package{hyperref} drivers \Option{hypertex} or + \Option{dvips} is used, the useful \Package{hyperref} option + \Option{linktocpage} will be set. However, if you create a PDF file + with \mbox{pdf{\LaTeX}}, the option + will not be set because then the \Package{hyperref} driver + \File{hpdftex.def} will be used. This means that neither \File{hdvips.def} nor \File{hypertex.def} will be loaded. \end{Example} - -Furthermore\textnote{Hint!}, the loading of package \Package{scrlfile} and -the \DescRef{\LabelBase.cmd.AfterFile} statement can be written in a private -\File{hyperref.cfg}. If you do so, then instead of \Macro{usepackage} the -macro \Macro{RequirePackage} ought be used (see \cite{latex:clsguide}). The -new lines have to be inserted directly after the \Macro{ProvidesFile} line, -thus immediately prior to the execution of the options \Option{dvips} or -\Option{pdftex}.% -% +\iffalse% Umbruchkorrekturtext (der besser nicht mehr verwendet wird!) + Furthermore\textnote{Hint!}, you can also load \Package{scrlfile} and the + \DescRef{\LabelBase.cmd.AfterFile} command into a private + \File{hyperref.cfg}. In this case, however, you should use + \Macro{RequirePackage} instead of \Macro{usepackage} to load the package + (see \cite{latex:clsguide}). In the example above, the new lines have to be + inserted directly after the \Macro{ProvidesFile} line, that is, immediately + before the \Option{dvips} or \Option{pdftex} options are executed.% +\fi +Incidentally\textnote{Hint!}, you can also load \Package{scrlfile} before +\DescRef{maincls.cmd.documentclass}\IndexCmd{documentclass}. In this case, +however, you should use \Macro{RequirePackage}\IndexCmd{RequirePackage} +instead of \DescRef{maincls.cmd.usepackage} (see \cite{latex:clsguide}).% \EndIndexGroup \begin{Declaration} - \Macro{BeforeClosingMainAux}\Parameter{instructions}% - \Macro{AfterReadingMainAux}\Parameter{instructions}% + \Macro{BeforeClosingMainAux}\Parameter{commands}% + \Macro{AfterReadingMainAux}\Parameter{commands}% \end{Declaration}% -Package authors often want to write something into the \File{aux}-file after -the last document page have been shipped out. To do so, often +These commands differ in one detail from the commands explained previously. +Those commands enable actions before or after loading files. That is not the +case here. Package authors often want to write something to the \File{aux} +file after the last document page has been shipped out. To do so, ignoring the +resulting problems they create, they often use code such as the following: \begin{lstcode} \AtEndDocument{% \if@filesw @@ -328,15 +330,14 @@ the last document page have been shipped out. To do so, often \fi } \end{lstcode} -is used. Nevertheless this is not a real solution of the problem. If the last -page of the document already have been shipped out before -\Macro{end}\PParameter{document}, the code above will not result in any -writing into the \File{aux}-file. If someone would try to fix this new problem -using \Macro{immediate} just before \Macro{write}, the inverse problem would -occur: If the last page was not shipped out before -\Macro{end}\PParameter{document} the \Macro{writethistoaux} would be written -into \File{aux}-file before ship-out the last page. Another often seen -suggestion for this problem therefore is: +However, this does not really solve the problem. If the last page of the +document has already been shipped out before \Macro{end}\PParameter{document}, +the code above will not result in any output to the \File{aux} file. If you +try to fix this new problem using \Macro{immediate} just before \Macro{write}, +you would have the opposite problem: if the last page has not yet been shipped +out before \Macro{end}\PParameter{document}, \Macro{writethistoaux} would be +written to the \File{aux} file too early. Therefore you often see solutions +like: \begin{lstcode} \AtEndDocument{% \if@filesw @@ -347,23 +348,23 @@ suggestion for this problem therefore is: \fi } \end{lstcode} -This suggestion has a disadvantage again: The ship-out of the last page has -been enforced by the \DescRef{maincls.cmd.clearpage}. After that, instructions -like +However, this solution has the disadvantage that it forces the last page to be +shipped out. A command such as \begin{lstcode} \AtEndDocument{% \par\vspace*{\fill}% Note at the end of the document.\par } \end{lstcode} -would not any longer output the note at the end of the last page of the -document but at the end of one more page. Additionally \Macro{writethistoaux} -would be written one page to early into the \File{aux}-file again. - -The best solution for this problem would be, to write to the \File{aux}-file -immediately after the final \DescRef{maincls.cmd.clearpage}, that is part of -\Macro{end}\PParameter{document}, but just before closing the -\File{aux}-file. This is the purpose of \Macro{BeforeClosingMainAux}: +will no longer cause the note to appear beneath the text of the last real page +of the document but at the end of one additional page. Furthermore, +\Macro{writethistoaux} will again be written to the \File{aux} file one page +too early. + +The best solution for this problem would be if you could write directly to the +\File{aux} file immediately after the final \DescRef{maincls.cmd.clearpage} +that is part of \Macro{end}\PParameter{document} but before closing the +\File{aux} file. This is the purpose of \Macro{BeforeClosingMainAux}: \begin{lstcode} \BeforeClosingMainAux{% \if@filesw @@ -373,25 +374,24 @@ immediately after the final \DescRef{maincls.cmd.clearpage}, that is part of \fi } \end{lstcode} -This would be successful even if the final \DescRef{maincls.cmd.clearpage} -inside of \Macro{end}\PParameter{document} would not really ship-out any page -or if someone have had used \DescRef{maincls.cmd.clearpage} in the argument of -\Macro{AtEndDocument}. - -Nevertheless there one important limitation using -\Macro{BeforeClosingMainAux}: You should not use a typeset instruction inside -the \PName{instructions} of \Macro{BeforeClosingMainAux}! If you miss this -limitation the result would be as unpredictable as the results of the -problematic suggestions using \Macro{AtEndDocument} upward. - -Command \Macro{AfterReadingMainAux}\ChangedAt{v3.03}{\Package{scrlfile}} -actually executes the \PName{instructions} just after closing and input of the -\File{aux}-file inside of \Macro{end}\PParameter{document}. This will make -sense only in some cases, e.\,g., to show statistic information, that will be -valid only after input of the \File{aux}-file, or to write such information -into the \File{log}-file, or to implement additional \emph{rerun} -requests. Typeset instructions are even more critical inside these -\PName{instructions} that inside the argument of +This will be successful even if the final \DescRef{maincls.cmd.clearpage} +inside of \Macro{end}\PParameter{document} does not actually ship out any page +or if \DescRef{maincls.cmd.clearpage} is used within an \Macro{AtEndDocument} +command. + +However, there one important limitation using \Macro{BeforeClosingMainAux}: +you should not use any typesetting commands inside the \PName{commands} of +\Macro{BeforeClosingMainAux}! If you ignore this restriction, the result is +just as unpredictable as the results of the problematic suggestions above that +use \Macro{AtEndDocument}. + +The \Macro{AfterReadingMainAux}\ChangedAt{v3.03}{\Package{scrlfile}} command +actually executes the \PName{commands} after closing and reading the +\File{aux} file inside \Macro{end}\PParameter{document}. This is only useful +in a few very rare cases, for example to write statistical information to the +\File{log} file which is valid only after reading the \File{aux} file, or to +implement additional \emph{rerun} requests. Typesetting commands are even more +dangerous inside these \PName{commands} than inside the argument of \Macro{BeforeClosingMainAux}.% % \EndIndexGroup @@ -400,114 +400,107 @@ requests. Typeset instructions are even more critical inside these \section{Replacing Files at Input} \seclabel{replace} -All previous sections in this chapter describe commands to execute -instructions before or after input of a file, class, or package. Package -\Package{scrlfile} also provides commands to input another file, class, or -package instead of the one, that has been declared. +The previous sections in this chapter have explained commands to perform +actions before or after loading a particular file, package, or class. You can +also use \Package{scrlfile} to input a completely different file than the one +that was requested. \begin{Declaration} - \Macro{ReplaceInput}\Parameter{source file name}% - \Parameter{replacement file name}% + \Macro{ReplaceInput}\Parameter{original file}% + \Parameter{replacement file}% \end{Declaration}% This\ChangedAt{v2.96}{\Package{scrlfile}} command defines a replacement for -the file of the first argument: \PName{source file name}, by the file of the -second argument: \PName{replacement file name}. If \LaTeX{} will be instructed -to input the file with \PName{source file name} at any time afterward, the -file with the \PName{replacement file name} will be input instead. The -replacement definition will be valid for all files, that the user will input -with \Macro{InputIfFileExists} and for all files, that will be input with a -command, that uses \Macro{InputIfFileExists} internally. To do so, -\Package{scrlfile} redefined \Macro{InputIfFileExists}. +the file specified in the first argument, \PName{original file}. If \LaTeX{} +is instructed to load this file, the \PName{replacement file} will be loaded +instead. The replacement-file definition affects all files loaded using +\Macro{InputIfFileExists}, whether they are loaded by the user or internally +by \LaTeX{}. To do so, \Package{scrlfile} redefines \Macro{InputIfFileExists}. \begin{Example} - You want \LaTeX{} to input file \File{\Macro{jobname}.xua} instead of file - \File{\Macro{jobname.aux}}. This may be done using + You want to input the \File{\Macro{jobname}.xua} file instead of the + \File{\Macro{jobname.aux}} file. To do this, you use \begin{lstcode} \ReplaceInput{\jobname.aux}{\jobname.xua} \end{lstcode} - Additionally you may replace \File{\Macro{jobname}.xua} by - \File{\Macro{jobname}.uxa} using: + If additionally you replace \File{\Macro{jobname}.xua} by + \File{\Macro{jobname}.uxa} using \begin{lstcode} \ReplaceInput{\jobname.xua}{\jobname.uxa} \end{lstcode} - This will also replace input of \File{\Macro{jobname}.aux}, i.\,e., while - \Macro{end}\PParameter{document}, by \File{\Macro{jobname}.uxa}. As you see, - the whole replacement chain will be executed. + then \File{\Macro{jobname}.aux} will also be replaced by + \File{\Macro{jobname}.uxa}. In this way, you can process the whole + replacement chain. - Nevertheless a round robin replacement like + However, a replacement that results in a loop such as \begin{lstcode} \ReplaceInput{\jobname.aux}{\jobname.xua} \ReplaceInput{\jobname.xua}{\jobname.aux} \end{lstcode} - would result in a \emph{stack size error}. So it is not possible to define a - replacement of a file by itself directly or indirectly. + will cause a \emph{stack size error}. So it is not possible to replace + a file that has already been replaced once by itself again. \end{Example} -In theory is would also be possible to replace a package or class by another -one. But \LaTeX{} would recognize the usage of the wrong file name in this -case. A solution for this problem will be shown next.% -% +In theory, it would also be possible to use this command to replace one +package or class with another. But \LaTeX{} would recognize that the requested +file name does not match the name of the package or class. You can find a +solution for this problem below.% \EndIndexGroup \begin{Declaration} - \Macro{ReplaceClass}\Parameter{source class}% - \Parameter{replacement package}% - \Macro{ReplacePackage}\Parameter{source package}% + \Macro{ReplaceClass}\Parameter{original class}% + \Parameter{replacement class}% + \Macro{ReplacePackage}\Parameter{original package}% \Parameter{replacement package}% \end{Declaration}% -Classes\ChangedAt{v2.96}{\Package{scrlfile}}\textnote{Attention!} or packages -should never be replaced using previously described command -\DescRef{\LabelBase.cmd.ReplaceInput}. Using this command would result in a \LaTeX{} warning -because of class or package name not according the file name. +You\ChangedAt{v2.96}{\Package{scrlfile}}\textnote{Attention!} should never +replace a class or package using the \DescRef{\LabelBase.cmd.ReplaceInput} +command described above. Doing so would result in a \LaTeX{} warning about +mismatched class or package names. Real errors are also possible if a class or +package is loaded under an incorrect file name. \begin{Example} - You replace package \Package{fancyhdr} by package \Package{scrpage2} - inconsiderately using -\begin{lstcode} - \ReplaceInput{fancyhdr.sty}{scrpage2.sty} + You replace the \Package{scrpage2} package with its official successor, + \Package{scrlayer-scrpage}, by using +\begin{lstcode}[escapechar=\$] + \ReplaceInput{scrpage2.sty}{scrlayer-scrpage.sty}$\textnote{Do not try this!}$ \end{lstcode} - Loading \Package{fancyhdr}, would result in + Loading \Package{scrpage2} will then lead to the following warning: \begin{lstcode} LaTeX warning: You have requested `scrpage2', - but the package provides `fancyhdr'. + but the package provides `scrlayer-scrpage'. \end{lstcode} - after this. Users may be confused by such a warning, because they've used, - e.\,g., \Macro{usepackage}\PParameter{fancyhdr} and never requested package - \Package{scrpage2} on their own. But \Package{scrlfile} replaced the input - of \File{fancyhdr.sty} by \File{scrpage2.sty} because of your replacement - definition. + Users may be greatly confused by such a warning because they requested not + \Package{scrlayer-scrpage} but \Package{scrpage2}, which was replaced by + \Package{scrlayer-scrpage}. \end{Example} -A solution for this problem would be, to use \Macro{ReplaceClass} or -\Macro{ReplacePackage} instead of -\DescRef{\LabelBase.cmd.ReplaceInput}. Please note, that in this case you have -to use the names of the classes or packages only instead of the whole file -name. This is similar to usage of \Macro{documentclass} and -\Macro{usepackage}. - -The class replacement would perform for all classes, that will be loaded using +One solution to this problem is to use \Macro{ReplaceClass} or +\Macro{ReplacePackage} instead of \DescRef{\LabelBase.cmd.ReplaceInput}. Note +that in this case, as with \Macro{documentclass} and \Macro{usepackage}, you +should give the name of the class or package and not the complete file name. + +The replacement class works for all classes loaded with \Macro{documentclass}, \Macro{LoadClassWithOptions}, or \Macro{LoadClass}. The -package replacement would perform for all packages, that will be loaded using +replacement package works for all packages loaded with \Macro{usepackage}, \Macro{RequirePackageWithOptions}, or \Macro{RequirePackage}. -Please\textnote{Attention!} note, that the \PName{replacement class} or the -\PName{replacement package} will be loaded with the same options, the -\PName{source class} or \PName{replacement class} would until it has been -replaced. Replacement of a class or package by a class or package, that does -not support a requested option, would result in a warning or even an error -message. But you may declare such missing options using -\DescRef{\LabelBase.cmd.BeforeClass} or +Please\textnote{Attention!} note that the \PName{replacement class} or the +\PName{replacement package} will be loaded with the same options that would +have been passed to the \PName{original class} or \PName{original package}. If +you replace a class or package with one that does not support a requested +option, you will receive the usual warnings and errors. However, you can +declare such missing options using \DescRef{\LabelBase.cmd.BeforeClass} or \DescRef{\LabelBase.cmd.BeforePackage}. \begin{Example} - Assumed, package \Package{oldfoo} should be replaced by - \Package{newfoo}. This may be done using: + Suppose you want to replace the \Package{oldfoo} package with the + \Package{newfoo} package when the former package is loaded. You can do this with \begin{lstcode} \ReplacePackage{oldfoo}{newfoo} \end{lstcode} - Assumed the old package provides an option \Option{oldopt}, but the new - package does not. Using + Suppose the old package provides an \Option{oldopt} option, but the new + package does not. With \begin{lstcode} \BeforePackage{newfoo}{% \DeclareOption{oldopt}{% @@ -515,21 +508,21 @@ message. But you may declare such missing options using {option `oldopt' not supported}% }}% \end{lstcode} - additionally, would declare this missing option for package - \Package{newfoo}. This would avoid warning message about unsupported - options. + you can declare this missing option for the \Package{newfoo} package. This + avoids an error message when the \Package{oldfoo} package is loaded with the + option that is unsupported by \Package{newfoo}. - However, if package \Package{newfoo} supports an option \Option{newopt}, - that should be used instead of option \Option{oldopt} of old package - \Package{oldfoo}, this may achieved using: + If, on the other hand, the \Package{newfoo} package supports a + \Option{newopt} option that should be used instead of the \Option{oldopt} + option, you can also achieved this: \begin{lstcode} \BeforePackage{newfoo}{% \DeclareOption{oldopt}{% \ExecuteOptions{newopt}% }}% \end{lstcode} - Last but not least different default options may be selected, that should be - valid while package replacement: + You can even specify different default options that apply when loading the + new package: \begin{lstcode} \BeforePackage{newfoo}{% \DeclareOption{oldopt}{% @@ -539,7 +532,7 @@ message. But you may declare such missing options using {newfoo}% } \end{lstcode} - or somehow more directly: + or directly: \begin{lstcode} \BeforePackage{newfoo}{% \DeclareOption{oldopt}{% @@ -549,9 +542,11 @@ message. But you may declare such missing options using \PassOptionsToPackage{newdefoptA,newdefoptB}% {newfoo}% \end{lstcode} + Note that in the last example, the call to \Macro{PassOptionsToPackage} + occurs not within but after \Macro{BeforePackage} \end{Example} -To replace classes package \Package{scrlfile} has to be loaded before the +Of course, to replace classes, you must load \Package{scrlfile} before the class using \Macro{RequirePackage} instead of \Macro{usepackage}. % \EndIndexGroup @@ -562,74 +557,71 @@ class using \Macro{RequirePackage} instead of \Macro{usepackage}. \Macro{UnReplacePackage}\Parameter{package}% \Macro{UnReplaceClass}\Parameter{class}% \end{Declaration} -A\ChangedAt{v3.12}{\Package{scrlfile}} replacement definition can be removed -using one of these commands. The replacement definition of a input file should -be removed using \Macro{UnReplaceInput}, the replacement definition of a -package should be removed using \Macro{UnReplacePackage}, and the replacement -definition of a class should be removed using \Macro{UnReplaceClass}.% +You\ChangedAt{v3.12}{\Package{scrlfile}} can also remove a replacement. You +should remove the replacement definition for an input file using +\Macro{UnReplaceInput}, for a package using \Macro{UnReplacePackage}, and for +a class using \Macro{UnReplaceClass}.% \EndIndexGroup -\section{Prevent File Loading} +\section{Preventing File Loading} \seclabel{prevent} -Especially\ChangedAt{v3.08}{\Package{scrlfile}} classes or packages, that have -been made for companies or institutes, often load a lot of packages not needed -by the classes or packages itself but only because the users often use -them. Now, if such a not essential package causes any kind of problem, loading -of that package has to prevented. For this purpose \Package{scrlfile} again -provides a solution. +Classes\ChangedAt{v3.08}{\Package{scrlfile}} and packages written for use +within companies or academic institutions often load many packages only +because users need them frequently, not because they are required by the class +or package itself. If a problem occurs with one of these automatically loaded +packages, you somehow have to keep the problematic package from being loaded. +Once again, \Package{scrlfile} provides a simple solution. \begin{Declaration} - \Macro{PreventPackageFromLoading}\OParameter{instead code}% + \Macro{PreventPackageFromLoading}\OParameter{alternate code}% \Parameter{package list}% - \Macro{PreventPackageFromLoading*}\OParameter{instead code}% + \Macro{PreventPackageFromLoading*}\OParameter{alternate code}% \Parameter{package list} \end{Declaration} Calling this command\ChangedAt{v3.08}{\Package{scrlfile}} before loading a -package using \Macro{usepackage}\IndexCmd{usepackage}, +package with \Macro{usepackage}\IndexCmd{usepackage}, \Macro{RequirePackage}\IndexCmd{RequirePackage}, or -\Macro{RequirePackageWithOptions}\IndexCmd{RequirePackageWithOptions} will -prevent the package from being loaded effectively if the package is part of -the \PName{package list}. +\Macro{RequirePackageWithOptions}\IndexCmd{RequirePackageWithOptions} +effectively prevents the package from being loaded if it is found in the the +\PName{package list}. % \begin{Example} - Assumed you're working in a company, that uses font Latin-Modern for all - kind of documents. Because of this the company class, \Class{compycls} - contains the lines: + Suppose you work at a company where all documents are created using Latin + Modern. The company class, \Class{compycls}, therefore contains these lines: \begin{lstcode} \RequirePackage[T1]{fontenc} \RequirePackage{lmodern} \end{lstcode} - But now, you want to use - X\kern-.125em\lower.5ex\hbox{\reflectbox{E}}\LaTeX{} oder Lua\LaTeX{} the - first time. In this case loading of \Package{fontenc} would not be a good - suggestion and Latin-Modern would be the default font of the recommended - package \Package{fontspec}. Because of this you want to prevent both - packages from being loaded. This may be done, loading the class like this: + But now, for the first time, you want to use \XeLaTeX{} or Lua\LaTeX{}. + Since the recommended \Package{fontspec} package uses Latin Modern as the + default font anyway, and loading \Package{fontenc} would not be a good idea, + you want to prevent both packages from being loaded. Therefore, you load the + class in your own document as follows: \begin{lstcode} \RequirePackage{scrlfile} \PreventPackageFromLoading{fontenc,lmodern} \documentclass{firmenci} \end{lstcode} \end{Example} -The example above also shows, that package \Package{scrlfile} may be loaded -before the class. In this case \Macro{RequirePackage}\IndexCmd{RequirePackage} -has to be used, because \Macro{usepackage} before \Macro{documentclass} is not -permitted. - -If \PName{package list} is empty or contains a package, that already has been -loaded, \Macro{PreventPackageFromLoading} will warn. If you'd prefer an -info\ChangedAt{v3.12}{\Package{scrlfile}} at the log-file only, you may use -\Macro{PreventPackageFromLoading*} instead. - -The optional argument\ChangedAt{v3.12}{\Package{scrlfile}} may be used to -execute code instead of loading the package. But you must not load another -packages or files inside \PName{instead code}. See +The example above also shows that you can load \Package{scrlfile} before the +class. In this case, you must use +\Macro{RequirePackage}\IndexCmd{RequirePackage} because \Macro{usepackage} +before \Macro{documentclass} is not permitted. + +If you specify an empty \PName{package list} or if it contains a package that +has already been loaded, \Macro{PreventPackageFromLoading} issues a warning, +while\ChangedAt{v3.12}{\Package{scrlfile}} \Macro{PreventPackageFromLoading*} +merely writes a note to the log file only. + +You\ChangedAt{v3.12}{\Package{scrlfile}} can use the optional argument to +execute code instead of loading the package. But you cannot load any other +packages or files inside \PName{alternate code}. To load another package, see \DescRef{\LabelBase.cmd.ReplacePackage} in \autoref{sec:scrlfile.macros} on -\DescPageRef{\LabelBase.cmd.ReplacePackage} for information about replacing a -package by another one. Note also, that the \PName{instead code} will be -executed several times, if you try to load the package more than once!% +\DescPageRef{\LabelBase.cmd.ReplacePackage}. Note also that the +\PName{alternate code} will be executed several times if you try to load the +package more than once!% \EndIndexGroup @@ -638,23 +630,23 @@ executed several times, if you try to load the package more than once!% \Macro{ResetPreventPackageFromLoading} \end{Declaration} \Macro{StorePreventPackageFromLoad}\ChangedAt{v3.08}{\Package{scrlfile}} -defines \Macro{command} to be the current list of packages, that should be -prevented from being loaded. In opposite to this, +defines \Macro{command} to be the current list of packages that should not be +loaded. In contrast, \Macro{ResetPreventPackageFromLoading}\ChangedAt{v3.08}{\Package{scrlfile}} -resets the list of packages, that should be prevented from being loaded. After -\Macro{ResetPreventPackageFromLoading} all packages may be loaded again. +resets the list of packages that should not be loaded. After +\Macro{ResetPreventPackageFromLoading}, you can load all packages again. \begin{Example} - Assumed, you really need a package inside your own package and you want the - user inhibit to prevent loading of that package with + Suppose you need to load a package inside another package and you do not + want the user to be able to prevent that package from being loaded with \DescRef{\LabelBase.cmd.PreventPackageFromLoading}% - \IndexCmd{PreventPackageFromLoading}. Because of this, you reset the package - preventing list before loading the package: + \IndexCmd{PreventPackageFromLoading}. So you reset the do-not-load list + before you load this package: \begin{lstcode} \ResetPreventPackageFromLoading \RequirePackage{foo} \end{lstcode} - Unfortunately the complete prevention list of the user would be lost after - that. To avoid this, you first store the list and restore it at the end: + Unfortunately, from this point on the user's entire do-not-load list would + be lost. To avoid this, you first store the list and then restore it later: \begin{lstcode} \newcommand*{\Users@PreventList}{}% \StorePreventPackageFromLoading\Users@PreventList @@ -662,23 +654,22 @@ resets the list of packages, that should be prevented from being loaded. After \RequirePackage{foo} \PreventPackageFromLoading{\Users@PreventList} \end{lstcode} - Please\textnote{Attention!} note, that - \Macro{StorePreventPackageFromLoading} would define - \Macro{Users@PreventList} even if it already has been defined before. In other - words: \Macro{StorePreventPackageFromLoading} overwrites existing - \Macro{command} definitions without care. Because of this, - \Macro{newcommand*} has been used in the example to get an error message, if + Note\textnote{Attention!} that \Macro{StorePreventPackageFromLoading} + defines the \Macro{Users@PreventList} macro even if it has already been + defined. In other words, calling \Macro{StorePreventPackageFromLoading} + overwrites existing \Macro{command} definitions without checking. Therefore + this example uses \Macro{newcommand*} to get an error message if \Macro{Users@PreventList} has already been defined. \end{Example} -At this point please note, that everybody who manipulates the list, that has -been stored using \Macro{StorePreventPackageFromLoading} is responsible for -the correct restorability. For example the list elements must be separated by -comma, must not contain white space or group braces, and must be fully -expandable. - -Please note\textnote{Attention!}, that \Macro{ResetPreventPackageFromLoading} -does not clean the \PName{instead code} of a package. Only the execution is not -done as long as the prevention is not reactivated.% +Note that when you manipulate the list stored by +\Macro{StorePreventPackageFromLoading}, you are responsible for making sure it +can be restored. For example, the list elements must be separated by comma, +must not contain white space or group braces, and must be fully expandable. + +Also note\textnote{Attention!}, that \Macro{ResetPreventPackageFromLoading} +does not clear the \PName{alternate code} for a package. But this code +will not be executed so long as the package is not added again to the +do-not-load list.% \EndIndexGroup @@ -686,35 +677,35 @@ done as long as the prevention is not reactivated.% \Macro{UnPreventPackageFromLoading}\Parameter{package list}% \Macro{UnPreventPackageFromLoading*}\Parameter{package list} \end{Declaration} -Instead\ChangedAt{v3.12}{\Package{scrlfile}} of resetting the whole list of -packages, that should prevented from being loaded, you may also remove some -packages from that list. The star version of the command does also clean the -\PName{instead code}. So reactivation of the prevent package list, e.\,g., -from a stored one, will not reactivate the \PName{instead code} of the -packages.% +Instead\ChangedAt{v3.12}{\Package{scrlfile}} of completely resetting the list +of packages that should not be loaded, you can also specify individual +packages to remove from the list. The starred version of the command also +deletes the \PName{alternate code}. For example, restoring packages to the +do-not-load list from a stored list will not reactivate their \PName{alternate +code} in this case.% % \begin{Example} - Assuming, you want to prevent a package \Package{foo} from being loaded, but - you do not want an already stored \PName{instead code} to be - executed. Instead of that code, you're own \PName{instead code} should be - executed. You can do this: + Suppose you want to prevent a \Package{foo} package from being loaded, but + you do not want to execute any outdated \PName{alternate code} that may + exist. Instead, only your new \PName{alternate code} should be executed. You + can do this as follows: \begin{lstcode} \UnPreventPackageFromLoading*{foo} - \PreventPackageFromLoading[\typeout{Stattdessencode}]{foo} + \PreventPackageFromLoading[\typeout{alternate code}]{foo} \end{lstcode} - For \Macro{UnPreventPackageFromLoading} it does not matter whether or not - the package has been prevented from being loaded before. + For the \Macro{UnPreventPackageFromLoading} command, it does not matter + whether or not the package has been prevented from being loaded before. - Surely you can use the command also to remove only the \PName{instead code} - of all packages: + Of course you can also use the command to indirectly delete the + \PName{alternate code} of all packages: \begin{lstcode} \StorePreventPackageFromLoading\TheWholePreventList \UnPreventPackageFromLoading*{\TheWholePreventList} \PreventPackageFromLoading{\TheWholePreventList} \end{lstcode} - In this case the packages, that has been prevented from being loaded, are - still prevented from being loaded, but their \PName{instead code} has been - cleaned and will not be executed any longer.% + In this case the packages that have been prevented from being loaded are + still prevented from being loaded, but their \PName{alternate code} has been + deleted and will no longer be executed.% \end{Example}% \EndIndexGroup % @@ -729,5 +720,3 @@ packages.% %%% coding: us-ascii %%% TeX-master: "../guide" %%% End: - -% LocalWords: restorability diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2-experts.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2-experts.tex index f27ff563f2c..2e0af8b703d 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2-experts.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2-experts.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrlttr2-experts.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrlttr2-experts.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,39 +46,43 @@ % ============================================================================ \KOMAProvidesFile{scrlttr2-experts.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-21 10:37:34 +0100 (Wed, 21 Mar 2018) $ KOMA-Script guide (chapter: scrlttr2 for experts)] \translator{Harald Bongartz\and Georg Grandke\and Raimund Kohl\and Jens-Uwe - Morawski\and Stephan Hennig\and Gernot Hassenpflug\and Markus Kohm} + Morawski\and Stephan Hennig\and Gernot Hassenpflug\and Markus Kohm\and + Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-01-02 -\chapter{Additional Information about the Letter Class - \Class{scrlttr2} and the Letter Package \Package{scrletter}} +\chapter{Additional Information about the \Class{scrlttr2} Class and the + \Package{scrletter} Package} \labelbase{scrlttr2-experts} + \BeginIndexGroup \BeginIndex{Class}{scrlttr2} -\BeginIndex{Package}{scrletter} - -This chapter gives additional information about the \KOMAScript{} class -\Class{scrlttr2}. \iffree{Some parts of the chapter are subject to the - \KOMAScript{} book \cite{book:komascript} only. This should not be a - problem, because the}{The} average user, who only want to use the package, -does not need the information. Other information is addressed to users, who -want additional information about details. For example the first section will -describe pseudo-lengths in detail. These may be used to modify the note paper. -Another part of the information describes features of the class that exist -only because of compatibility to deprecated \Class{scrlettr} class. Last but -not least it will be described in detail how to change a document from the old -\Class{scrlettr} class to be used with the current \Class{scrlttr2} class. - -Since \KOMAScript~3.15\ChangedAt[2014/11]{v3.15}{\Package{scrletter}} the -additional package \Package{scrletter} exists. It can -be used with one of the \KOMAScript{} classes \Class{scrartcl}, -\Class{scrreprt}, or \Class{scrbook} and provides all the features of -\Class{scrlttr2} for those classes. There are, however, small differences -described later in this section.% +This chapter provides additional information about the \KOMAScript{} class +\Class{scrlttr2}. \iffree{Some parts of the chapter are found only in the + German \KOMAScript{} book \cite{book:komascript}. This should not be a + problem, because the}{The} average user, who only wants to use the class +or package, will not normally need this information. Part of this information +is addressed to users for whom the default options are insufficient. Thus, +for example, the first section describes in detail the pseudo-lengths that +specify the letterhead page and which can be used be used to modify the its +layout.% +\iffalse% Es wird Zeit das komplett rauszuwerfen! + In addition, this chapter also describes features that exist only to + provide compatibility with the deprecated \Class{scrlettr} class. It also + explains in detail how to convert a document from this obsolete class + to the current class. +\fi + +\BeginIndex{Package}{scrletter}% +Starting with \KOMAScript~3.15\ChangedAt[2014/11]{v3.15}{\Package{scrletter}}, +you can use the \Package{scrletter} package with one of the \KOMAScript{} +classes \Class{scrartcl}, \Class{scrreprt}, or \Class{scrbook}. It provides +nearly all the features of \Class{scrlttr2} for those classes. There are, +however, a few differences described later in this chapter.% \section{Pseudo-Lengths for Experienced Users} @@ -86,269 +90,285 @@ described later in this section.% \BeginIndexGroup \BeginIndex{}{pseudo-lengths} -{\TeX} works with a fixed number of registers. There are registers for tokens, -for boxes, for counters, for skips and for dimensions. Overall there are 256 -registers for each of these categories. For {\LaTeX} lengths, which are -addressed with \Macro{newlength}, skip registers are used. Once all these -registers are in use, you can not define any more additional lengths. The -letter class \Class{scrlttr2} would normally use up more than 20 of such -registers for the first page alone. {\LaTeX} itself already uses 40 of these -registers. The \Package{typearea} package needs some of them too; thus, -approximately a quarter of the precious registers would already be in -use. That is the reason why lengths specific to letters in \Class{scrlttr2} -are internally defined with macros instead of lengths. The drawback of this -approach is that computations with macros is somewhat more complicated than -with real lengths. - -Please note\textnote{Attention!}: Even though these pseudo-lengths are -internally implemented as macros, the commands for pseudo-length management -expect only the names of the pseudo-lengths not the macros representing the -pseudo-lengths. The names of pseudo-lengths are without backslash at the very -beginning similar to the names of \LaTeX{} counters and in opposite to macros -or \LaTeX{} lengths. - -It can be pointed out that the now recommended {\LaTeX} installation with -{\eTeX} no longer suffers from the above-mentioned limitation. However, that -improvement came too late for \Class{scrlttr2}. - -The pseudo-lengths defined and uses by \Class{scrlttr2} are listed in -\autoref{tab:scrlttr2-experts.pseudoLength}. Cross references to the detailed -descriptions of each pseudo-lengths in the following sub-sections are also -given in the table. - -A schematic display of the most important distances of the note paper is shown -in \autoref{fig:scrlttr2-experts.pseudoLength} at -\autopageref{fig:scrlttr2-experts.pseudoLength}. Beside the -pseudo-lengths for the modifiable distances, also some lengths, which may not -be modified, are shown in light gray. Some rarely needed pseudo-length of the -note paper have been omitted to get a more clear arrangement. +\TeX{} works with a fixed number of registers. There are registers for tokens, +for boxes, for counters, for skips, and for dimensions. Overall there are 256 +registers for each of these categories. For \LaTeX{} lengths, which are +defined with \Macro{newlength}, skip registers are used. Once all these +registers are in use, you can not define any more lengths. Both +\Class{scrlttr2} and \Package{scrletter} would normally use more than 20 of +these registers for the first page alone. \LaTeX{} itself already uses 40 of +these registers. The \hyperref[cha:typearea]{\Package{typearea}}% +\IndexPackage{typearea} package needs some of them too; thus, approximately a +quarter of these precious registers would already be in use. For this reason, +\KOMAScript{} stores letter-specific lengths in macros instead of lengths. The +drawback of this approach is that computations with macros are somewhat more +complicated than with real lengths. + +Note\textnote{Attention!} that even though these pseudo-lengths are internally +implemented as macros, the commands for pseudo-length management expect only +the names of the pseudo-lengths not the macros representing the +pseudo-lengths. The names of pseudo-lengths are written without the initial +backslash, like the names of \LaTeX{} counters and unlike macros or \LaTeX{} +lengths. + +Anyone who wants to argue that the recommended \LaTeX{} installation with +\eTeX{}, which is required for \KOMAScript{} anyway, no longer suffers from +the above-mentioned limitation would be right. However, that improvement came +too late for \Class{scrlttr2}. With \Package{scrletter}, the concept of +psuedo-lengths was adopted for reasons of compatibility. + +The pseudo-lengths defined and uses by \KOMAScript{} are listed in +\autoref{tab:scrlttr2-experts.pseudoLength}, which also provides cross +references to the detailed descriptions of each pseudo-lengths in the +following sub-sections. + +A schematic display of the most important distances of the letterhead page is +shown in \autoref{fig:scrlttr2-experts.pseudoLength} on +\autopageref{fig:scrlttr2-experts.pseudoLength}. In addition to the +pseudo-lengths for the configurable distances, some non-configurable lengths +are also shown in light gray. For the sake of clarity, however, some rarely +required pseudo-lengths have been omitted. % \begin{desclist} \renewcommand{\abovecaptionskipcorrection}{-\normalbaselineskip}% \desccaption{% - Pseudo-lengths provided by class \Class{scrlttr2}% + Pseudo-lengths provided by \Class{scrlttr2} and \Package{scrletter}% \label{tab:scrlttr2-experts.pseudoLength}% }{% - Pseudo-lengths provided by class \Class{scrlttr2} (\emph{continued})% + Pseudo-lengths provided by \Class{scrlttr2} and \Package{scrletter} + (\emph{continued})% }% \pentry{backaddrheight}{% - height of the return address at the upper edge of the address field % + the height of the return address at the upper edge of the address field (\autoref{sec:scrlttr2-experts.addressee}, \DescPageRef{scrlttr2-experts.plength.backaddrheight})% }% \pentry{bfoldmarklength}{% - length of the bottommost folding mark % + the length of the bottommost fold mark (\autoref{sec:scrlttr2-experts.foldmarks}, \DescPageRef{scrlttr2-experts.plength.bfoldmarkvpos})% }% \pentry{bfoldmarkvpos}{% - vertical distance of bottommost folding mark from top paper edge % - (\autoref{sec:scrlttr2-experts.foldmarks}, + the vertical distance of the bottommost fold mark from the top edge of the + paper (\autoref{sec:scrlttr2-experts.foldmarks}, \DescPageRef{scrlttr2-experts.plength.bfoldmarkvpos})% }% \pentry{firstfoothpos}{% - horizontal distance of the letter footer from the left paper edge; values - greater than the width of the paper or smaller than the negative value of - the width of the paper will activate special handling % + the horizontal distance of the letterhead page footer from the left edge + of the paper; values greater than the width of the paper or less than the + negative value of the width of the paper activate special handling % (\autoref{sec:scrlttr2-experts.firstFoot}, \DescPageRef{scrlttr2-experts.plength.firstfoothpos})% }% \pentry{firstfootvpos}{% - vertical distance of letter footer from top paper edge % - (\autoref{sec:scrlttr2-experts.firstFoot}, + the vertical distance of letterhead page footer from the top edge of the + paper (\autoref{sec:scrlttr2-experts.firstFoot}, \DescPageRef{scrlttr2-experts.plength.firstfootvpos})% }% \pentry{firstfootwidth}{% - width of letter footer % + the width of the letterhead page footer (\autoref{sec:scrlttr2-experts.firstFoot}, \DescPageRef{scrlttr2-experts.plength.firstfootwidth})% }% \pentry{firstheadhpos}{% - horizontal distance of the letterhead from the left paper edge; values - greater than the width of the paper or smaller than the negative value of - the width of the paper will activate special handling % + the horizontal distance of the letterhead from the left edge of the paper; + values greater than the width of the paper or less than the negative value + of the width of the paper activate special handling (\autoref{sec:scrlttr2-experts.firstHead}, \DescPageRef{scrlttr2-experts.plength.firstheadhpos})% }% \pentry{firstheadvpos}{% - vertical distance of letterhead from top paper edge % + the vertical distance of the letterhead from the top edge of the paper (\autoref{sec:scrlttr2-experts.firstHead}, \DescPageRef{scrlttr2-experts.plength.firstheadvpos})% }% \pentry{firstheadwidth}{% - width of the letterhead % - (\autoref{sec:scrlttr2-experts.firstHead}, + the width of the letterhead (\autoref{sec:scrlttr2-experts.firstHead}, \DescPageRef{scrlttr2-experts.plength.firstheadwidth})% }% \pentry{foldmarkhpos}{% - horizontal distance of the horizontal folding marks from left paper edge % - (\autoref{sec:scrlttr2-experts.foldmarks}, + the horizontal distance of the horizontal fold marks from the left edge of + the paper (\autoref{sec:scrlttr2-experts.foldmarks}, \DescPageRef{scrlttr2-experts.plength.foldmarkhpos})% }% \pentry{foldmarkvpos}{% - vertical distance of the vertical folding marks from the top paper edge % - (\autoref{sec:scrlttr2-experts.foldmarks}, + the vertical distance of the vertical fold marks from the top edge of the + paper (\autoref{sec:scrlttr2-experts.foldmarks}, \DescPageRef{scrlttr2-experts.plength.foldmarkvpos})% }% \pentry{fromrulethickness}{% - thickness of an optional horizontal rule in the letterhead % + the thickness of an optional horizontal rule in the letterhead (\autoref{sec:scrlttr2-experts.firstHead}, \DescPageRef{scrlttr2-experts.plength.fromrulethickness})% }% \pentry{fromrulewidth}{% - length of an optional horizontal rule in letterhead % + the length of an optional horizontal rule in the letterhead (\autoref{sec:scrlttr2-experts.firstHead}, \DescPageRef{scrlttr2-experts.plength.fromrulewidth})% }% \pentry{lfoldmarkhpos}{% - horizontal distance of the vertical folding mark from the left paper edge % - (\autoref{sec:scrlttr2-experts.foldmarks}, + the horizontal distance of the vertical fold mark from the left edge of + the paper (\autoref{sec:scrlttr2-experts.foldmarks}, \DescPageRef{scrlttr2-experts.plength.lfoldmarkhpos})% }% \pentry{lfoldmarklength}{% - length of the vertical folding mark % + the length of the vertical fold mark (\autoref{sec:scrlttr2-experts.foldmarks}, \DescPageRef{scrlttr2-experts.plength.lfoldmarklength})% }% \pentry{locheight}{% - height of the field with the extended sender's information, of the value - is not zero; \PLength{toaddrheight} will be used instead of zero value % + the height of the field containing the additional sender information if + the value is not 0; if it is 0, \PLength{toaddrheight} is used instead (\autoref{sec:scrlttr2-experts.locationField}, \DescPageRef{scrlttr2-experts.plength.locheight})% }% \pentry{lochpos}{% - horizontal distance of the field with the extended sender's information - from the right paper edge, if the value is positive; negative horizontal - distance from the left paper edge, if the value is negative; negative - value of \PLength{toaddrhpos} will be used instead of zero value % + the horizontal distance of the field containing the additional sender + information; if the value is positive, the distance is measured from the + right paper edge; if negative, from the left paper edge; if 0, the + negative value of \PLength{toaddrhpos} is used instead (\autoref{sec:scrlttr2-experts.locationField}, \DescPageRef{scrlttr2-experts.plength.lochpos})% }% \pentry{locvpos}{% - vertical distance of the field with the extended sender's information from - the top paper edge, if the value is not zero; \PLength{toaddrvpos} will be - used instead of zero value % + the vertical distance of the field containing the additional sender + information from the top edge of the paper if the value is not 0; if it is + 0, \PLength{toaddrvpos} is used instead (\autoref{sec:scrlttr2-experts.locationField}, \DescPageRef{scrlttr2-experts.plength.locvpos})% }% \pentry{locwidth}{% - width of the field with the extended sender's information; for zero value - width is calculated automatically with respect to option \DescRef{scrlttr2.option.locfield} - that is described in \autoref{sec:scrlttr2.firstpage}, - \DescPageRef{scrlttr2.option.locfield} % + the width of the field containing the additional sender information; if it + is 0, the width is calculated automatically based on the + \DescRef{scrlttr2.option.locfield} option described in + \autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.locfield} % (\autoref{sec:scrlttr2-experts.locationField}, \DescPageRef{scrlttr2-experts.plength.locwidth})% }% \pentry{mfoldmarklength}{% - length of the middle horizontal folding mark % + the length of the middle horizontal fold mark (\autoref{sec:scrlttr2-experts.foldmarks}, \DescPageRef{scrlttr2-experts.plength.mfoldmarklength})% }% \pentry{mfoldmarkvpos}{% - vertical distance of the middle horizontal folding mark from the top paper - edge % - (\autoref{sec:scrlttr2-experts.foldmarks}, + the vertical distance of the middle horizontal fold mark from the top edge + of the paper (\autoref{sec:scrlttr2-experts.foldmarks}, \DescPageRef{scrlttr2-experts.plength.mfoldmarkvpos})% }% \pentry{pfoldmarklength}{% - length of the puncher hole mark % + the length of the hole-punch mark (\autoref{sec:scrlttr2-experts.foldmarks}, \DescPageRef{scrlttr2-experts.plength.pfoldmarklength})% }% + \pentry{PPdatamatrixvskip}{% + the vertical distance between the postpaid header and the data array with + \OptionValueRef{scrlttr2}{addrfield}{PP} + (\autoref{sec:scrlttr2-experts.addressee}, + \DescPageRef{scrlttr2-experts.plength.PPdatamatrixvskip})% + }% + \pentry{PPheadheight}{% + the height of the postpaid header + (\autoref{sec:scrlttr2-experts.addressee}, + \DescPageRef{scrlttr2-experts.plength.PPheadheight})% + }% + \pentry{PPheadwidth}{% + the width of the left postpaid field with + \OptionValueRef{scrlttr2}{addrfield}{PP} + (\autoref{sec:scrlttr2-experts.addressee}, + \DescPageRef{scrlttr2-experts.plength.PPheadwidth})% + }% \pentry{refaftervskip}{% - vertical skip below reference fields or business line % + vertical skip below reference-field line % (\autoref{sec:scrlttr2-experts.refLine}, \DescPageRef{scrlttr2-experts.plength.refaftervskip})% }% \pentry{refhpos}{% - horizontal distance of reference fields or business line from left paper - edge; for zero value reference fields line is centered horizontally on - letter paper % + the horizontal distance of reference-field line from the left + edge of the paper; if the value is 0, the reference-field line is centred + horizontally on the letterhead page (\autoref{sec:scrlttr2-experts.refLine}, \DescPageRef{scrlttr2-experts.plength.refhpos})% }% \pentry{refvpos}{% - vertical distance of reference fields or business line from top paper - edge % - (\autoref{sec:scrlttr2-experts.refLine}, + the vertical distance of reference-field line from the top + edge of the paper (\autoref{sec:scrlttr2-experts.refLine}, \DescPageRef{scrlttr2-experts.plength.refvpos})% }% \pentry{refwidth}{% - width of reference fields line % + the width of the reference-field line (\autoref{sec:scrlttr2-experts.refLine}, \DescPageRef{scrlttr2-experts.plength.refwidth})% }% \pentry{sigbeforevskip}{% - vertical skip between closing and signature % + the vertical skip between the closing and the signature (\autoref{sec:scrlttr2-experts.closing}, \DescPageRef{scrlttr2-experts.plength.sigbeforevskip})% }% \pentry{sigindent}{% - indentation of signature with respect to text body % + the indentation of the signature with respect to the text body (\autoref{sec:scrlttr2-experts.closing}, \DescPageRef{scrlttr2-experts.plength.sigindent})% }% \pentry{specialmailindent}{% - left indentation of mode of dispatch within address field % + the left indentation of the delivery method within the address field (\autoref{sec:scrlttr2-experts.addressee}, \DescPageRef{scrlttr2-experts.plength.specialmailindent})% }% \pentry{specialmailrightindent}{% - right indentation of mode of dispatch within address field % + the right indentation of the delivery method within the address field (\autoref{sec:scrlttr2-experts.addressee}, \DescPageRef{scrlttr2-experts.plength.specialmailrightindent})% }% \pentry{subjectaftervskip}{% - vertical distance after the subject % + the vertical skip after the subject (\autoref{sec:scrlttr2-experts.subject}, \DescPageRef{scrlttr2-experts.plength.subjectaftervskip})% }% \pentry{subjectbeforevskip}{% - additional vertical distance before the subject % + additional vertical skip before the subject (\autoref{sec:scrlttr2-experts.subject}, \DescPageRef{scrlttr2-experts.plength.subjectbeforevskip})% }% \pentry{subjectvpos}{% - vertical distance of the subject from the top paper edge; zero value will - set the subject depending on option \DescRef{scrlttr2.option.subject} % + the vertical distance of the subject from the top edge of the paper; if it + is 0, the position is calculated based on the + \DescRef{scrlttr2.option.subject} option (\autoref{sec:scrlttr2-experts.subject}, \DescPageRef{scrlttr2-experts.plength.subjectaftervskip})% }% \pentry{tfoldmarklength}{% - length of the topmost horizontal folding mark % + the length of the topmost horizontal fold mark (\autoref{sec:scrlttr2-experts.foldmarks}, \DescPageRef{scrlttr2-experts.plength.tfoldmarklength})% }% \pentry{tfoldmarkvpos}{% - vertical distance of the topmost horizontal folding mark from the top - paper edge % - (\autoref{sec:scrlttr2-experts.foldmarks}, + the vertical distance of the topmost horizontal folding mark from the top + edge of the paper (\autoref{sec:scrlttr2-experts.foldmarks}, \DescPageRef{scrlttr2-experts.plength.tfoldmarkvpos})% }% \pentry{toaddrheight}{% - height of address field % - (\autoref{sec:scrlttr2-experts.addressee}, + the height of the address field (\autoref{sec:scrlttr2-experts.addressee}, \DescPageRef{scrlttr2-experts.plength.toaddrheight})% }% \pentry{toaddrhpos}{% - horizontal distance of the address field from left paper edge, for - positive values; negative horizontal distance of the address field from - right paper edge, for negative values % + the horizontal distance of the address field from left edge of the paper, + if the value is positive; if it is negative, the negative horizontal + distance of the address field from the right edge of the paper (\autoref{sec:scrlttr2-experts.addressee}, \DescPageRef{scrlttr2-experts.plength.toaddrhpos})% }% \pentry{toaddrindent}{% - left and right indentation of address within address field % + the left and right indentation of the address within the address field (\autoref{sec:scrlttr2-experts.addressee}, \DescPageRef{scrlttr2-experts.plength.toaddrindent})% }% \pentry{toaddrvpos}{% - vertical distance of the address field from the top paper edge % - (\autoref{sec:scrlttr2-experts.addressee}, + the vertical distance of the address field from the the top edge of the + paper (\autoref{sec:scrlttr2-experts.addressee}, \DescPageRef{scrlttr2-experts.plength.toaddrvpos})% }% \pentry{toaddrwidth}{% - width of address field % + the width of the address field % (\autoref{sec:scrlttr2-experts.addressee}, \DescPageRef{scrlttr2-experts.plength.toaddrwidth})% }% @@ -365,22 +385,26 @@ note paper have been omitted to get a more clear arrangement. \begin{Declaration} \Macro{@newplength}\Parameter{name} \end{Declaration} -This command defines an new pseudo-length. This new pseudo-length is -uniquely identified by its \PName{name}. If with this command a -redefinition of an already existing pseudo-length is attempted, the +This command defines a new pseudo-length. The new pseudo-length is +uniquely identified by its \PName{name}. Each name can therefore be +assigned only once. If you attempt to redefine an existing pseudo-length, the commands exits with an error message. -Since the user in general does not define own pseudo-lengths, this command is -not intended as a user command. Thus, it can not be used within a document, -but it can, for example, be used within an -\File{lco}-file\Index{lco-file=\File{lco}-file}.\iffree{}{ Nevertheless, if - someone likes to define a pseudo-length inside the document, i.\,e. the - document preamble, then one may avoid that constriction using +Since the ordinary user does not normally need to define pseudo-lengths, this +command is not a user instruction. It cannot be used within a document, but it +can, for example, be used within an \File{lco} +file\Index{lco file=\File{lco} file}. +% +\iftrue % Umbruchoptimierung!!! +\iffree{}{ If you want to + define a pseudo-length inside the document anyway, you can override the + restriction with the help of \Macro{makeatletter}\important[i]{\Macro{makeatletter}\\ \Macro{makeatother}}\IndexCmd{makeatletter} and \Macro{makeatother}\IndexCmd{makeatother} (see - \cite{UK:FAQ}). But\textnote{Attention!} inside an \File{lco}-file these two - commands should never be used!}% + \cite{UK:FAQ}). But\textnote{Attention!} you should never use these two + commands inside an \File{lco} file!}% +\fi % \EndIndexGroup @@ -391,90 +415,91 @@ but it can, for example, be used within an \Macro{@addtoplength}% \OParameter{factor}\Parameter{pseudo-length}\Parameter{value} \end{Declaration} -Using the command \Macro{@setplength} you can assign the multiple of a +Using \Macro{@setplength}, you can assign the multiple of a \PName{value} to a \PName{pseudo-length}. The \PName{factor} is given as an optional argument (see also \DescRef{scrlttr2.cmd.setlengthtoplength}, \autoref{sec:scrlttr2.pseudoLength}, \DescPageRef{scrlttr2.cmd.setlengthtoplength}). -The command \Macro{@addtoplength} adds the \PName{value} to a -\PName{pseudo-length}. Again a \PName{factor} may be given as an optional +With \Macro{@addtoplength} you can add the multiple of a \PName{value} to a +\PName{pseudo-length}. Again, you can pass a \PName{factor} as an optional argument. -To assign, or to add the multiple of, one \PName{pseudo-length} to another -pseudo-length, the command \Macro{useplength} (siehe -\autoref{sec:scrlttr2.pseudoLength}, -\DescPageRef{scrlttr2.cmd.useplength}) is used within \PName{value}. To -subtract the value of one pseudo-length from another \PName{pseudo-length} a -minus sign, or \PValue{-1}, is used as the \PName{factor}. - -Since the user in general does not define own pseudo-lengths, this command is -not intended as a user command. Thus, it can not be used within a document, -but can, for example, be used within an \File{lco}-file.\iffree{}{ - Nevertheless, if someone likes to change the value of a pseudo-length inside - the document, i.\,e. the document preamble, then one may avoid that - constriction using +To assign or to add the multiple of one \PName{pseudo-length} to another +pseudo-length, use the \Macro{useplength} command (see +\autoref{sec:scrlttr2.pseudoLength}, \DescPageRef{scrlttr2.cmd.useplength}) +within the \PName{value}. To subtract the value of one \PName{pseudo-length} +from another \PName{pseudo-length}, you use should use at the same time a +minus sign or \PValue{-1} as the \PName{factor}. + +Since the ordinary user does not normally need to define pseudo-lengths, this +command is not a user instruction. It cannot be used within a document, but it +can, for example, be used within an \File{lco} +file\Index{lco file=\File{lco} file}.\iffree{}{ If you want to + define a pseudo-length inside the document anyway, you can override the + restriction with the help of \Macro{makeatletter}\important[i]{\Macro{makeatletter}\\ \Macro{makeatother}}\IndexCmd{makeatletter} and \Macro{makeatother}\IndexCmd{makeatother} (see - \cite{UK:FAQ}). But\textnote{Attention!} inside an \File{lco}-file these two - commands should never be used!}% + \cite{UK:FAQ}). But\textnote{Attention!} you should never use these two + commands inside an \File{lco} file!}% % \EndIndexGroup -\subsection{Folding Marks} +\subsection{Fold Marks} \seclabel{foldmarks} \BeginIndexGroup -\index{marks>folding|see{folding marks}} -\BeginIndex{}{folding marks}% +\BeginIndex{}{fold marks}% +\index{marks>folding|see{fold marks}} -Folding mark are short horizontal lines at the left edge, and short vertical -lines at the upper edge of the paper. \KOMAScript{} at present supports three -configurable horizontal and one configurable vertical foldmarks. In addition, -there is support for a puncher hole mark or center mark which cannot be -shifted in the vertical direction. +Fold marks, or folding marks, are short horizontal lines at the left edge, and +short vertical lines at the upper edge of the paper. \KOMAScript{} currently +supports three configurable horizontal and one configurable vertical fold +marks. In addition, there is support for a hole-punch mark, or centre mark, +which cannot be shifted vertically. \begin{Declaration} \PLength{tfoldmarkvpos}% \PLength{mfoldmarkvpos}% \PLength{bfoldmarkvpos} \end{Declaration} -The letter class \Class{scrlttr2} knows a total of three vertically placed -configurable foldmarks. The position of the topmost foldmark, taken from the -upper edge of the paper, is governed by the pseudo-length -\PLength{tfoldmarkvpos}; the position of the middle foldmark by pseudo-length -\PLength{mfoldmarkvpos}\ChangedAt{v2.97e}{\Class{scrlttr2}}; the position of -the bottommost foldmark by pseudo-length \PLength{bfoldmarkvpos}. With the -addition of the puncher hole\Index{puncher hole mark} or center\Index{center - mark|see{punch hole mark}} mark, there is still a fourth horizontal -mark. This one is however always placed at the vertical center of the paper. -\iffalse% Umbruchkorrekturtext -There's no pseudo-length for this last mark, because it vertical position is -not configurable. \fi - -The\textnote{Attention!} topmost and bottommost foldmarks do not serve to -divide the paper into exactly equal thirds. Instead, with their help, the -paper should be folded such that the address field appears correctly in the -space available in the chosen window envelope format, which is determined by -choice of \File{lco}-file. Several such files are available offering -predefined formats. An anomaly is present with \Option{DINmtext}: for this -format, an envelope format of C6/5 (also known as ``C6 long'') is -assumed. Letters written with this option are not suited to envelopes of -formats C5 or C4. - -The middle foldmark is not normally required for Western letters. In Japan, -however, a larger number of envelope formats exists, requiring one more -foldmark (see the Japanese \File{lco}-files). At this point attention is drawn -to the fact that reference to ``topmost'', ``middle'', and ``bottommost'' -foldmarks is simply a convenience. In fact, it is not defined that -\PLength{tfoldmarkvpos} must be smaller than \PLength{mfoldmarkvpos}, which in -turn must be smaller than \PLength{bfoldmarkvpos}. If on the other hand one of -the pseudo-lengths is set to null, then the corresponding foldmark will not be -set even if the option -\DescRef{scrlttr2.option.foldmarks}\IndexOption{foldmarks~=\PName{Einstellung}}% -\important{\DescRef{scrlttr2.option.foldmarks}} (see \autoref{sec:scrlttr2.firstpage}, -\DescPageRef{scrlttr2.option.foldmarks}) is explicity activated. +\KOMAScript{} recognises a total of three fold marks whose vertical position +can be configured. The distance of the top fold mark from the upper edge of +the paper is determined by the \PLength{tfoldmarkvpos} pseudo-length; the +distance of the middle fold mark, by the +\PLength{mfoldmarkvpos}\ChangedAt{v2.97e}{\Class{scrlttr2}} pseudo-length; the +distance of the bottommost fold mark, by \PLength{bfoldmarkvpos} +pseudo-length. With the addition of the hole-punch\Index{hole-punch mark} or +centre\Index{centre mark|see{hole-punch mark}} mark, there is yet a fourth +horizontal mark. This one is however always placed at the vertical centre of +the paper. +\iftrue% Umbruchkorrekturtext +There is no pseudo-length for this last mark because its vertical position is +not configurable. +\fi + +The\textnote{Attention!} top and bottom fold marks do not serve to divide the +paper exactly into equal thirds. Instead, the paper should be folded with +their help such that the address field can be seen in a window envelope. The +settings are therefore different depending on the \File{lco} file chosen. +Several such files are available offering predefined formats. One format +particularly worth noting is \Option{DINmtext}. This format assumes an +envelope format of C6/5 (also known as ``C6 long''). Letters written with this +option are typically not suited for C5 or C4 envelopes. + +The middle fold mark is not normally required for Western letters. In Japan, +however, a larger number of envelope formats exists, requiring one more fold +mark (see the Japanese \File{lco} files). Note that the terms ``top'', +``middle'', and ``bottom'' fold marks only represent a naming convention. In +fact, it is not required that \PLength{tfoldmarkvpos} must be smaller than +\PLength{mfoldmarkvpos}, which in turn must be smaller than +\PLength{bfoldmarkvpos}. If, though, one of the pseudo-lengths is zero, then +the corresponding fold mark will not be set even if the +\DescRef{scrlttr2.option.foldmarks}\IndexOption{foldmarks~=\PName{setting}}% +\important{\DescRef{scrlttr2.option.foldmarks}} option (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.foldmarks}) is +explicitly activated. % \EndIndexGroup @@ -486,26 +511,26 @@ set even if the option \PLength{pfoldmarklength} \end{Declaration} These\ChangedAt{v2.97e}{\Class{scrlttr2}} four pseudo-lengths determine the -lengths of the four horizontal foldmarks. One\textnote{Attention!} -exceptional behaviour exists. If the length is given as null, then the three -vertically-configurable pseudo-lengths \PLength{tfoldmarklength}, -\PLength{mfoldmarklength} and \PLength{bfoldmarklength} are set to 2\Unit{mm} -in length. The length of the punchmark, \PLength{pfoldmarklength}, is instead -set to 4\Unit{mm}.% +lengths of the four horizontal fold marks. One\textnote{Attention!} feature is +particularly worth noting. If the length is given as zero, then the three +vertically configurable pseudo-lengths \PLength{tfoldmarklength}, +\PLength{mfoldmarklength} and \PLength{bfoldmarklength} are set to 2\Unit{mm}. +The length of the hole-punch mark, \PLength{pfoldmarklength}, however, is set +to 4\Unit{mm}.% \EndIndexGroup \begin{Declaration} \PLength{foldmarkhpos} \end{Declaration} -This pseudo-length gives the distance of all horizontal foldmarks from the -left edge of the paper. Normally, this is 3.5\Unit{mm}. This\textnote{Hint!} -value can be changed in the user's own \File{lco}-file, in case the user's -printer has a wider unprintable left margin. Whether the foldmarks are typeset -at all depends on the option \DescRef{scrlttr2.option.foldmarks}\important{\DescRef{scrlttr2.option.foldmarks}}% -\IndexOption{foldmarks~=\PName{Einstellung}} (see -\autoref{sec:scrlttr2.firstpage}, -\DescPageRef{scrlttr2.option.foldmarks}). +This pseudo-length gives the distance of all horizontal fold marks from the +left edge of the paper. Normally, this is 3.5\Unit{mm}. You\textnote{Hint!} +can change this value in your own \File{lco} file if you are using a printer +that has a wider unprintable left margin. Whether the fold marks are typeset +at all depends on the option \DescRef{scrlttr2.option.foldmarks}% +\important{\DescRef{scrlttr2.option.foldmarks}}% +\IndexOption{foldmarks~=\PName{setting}} (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.foldmarks}). % \EndIndexGroup @@ -513,39 +538,38 @@ at all depends on the option \DescRef{scrlttr2.option.foldmarks}\important{\Desc \begin{Declaration} \PLength{lfoldmarkhpos} \end{Declaration} -Apart from\ChangedAt{v2.97e}{\Class{scrlttr2}} the horizontal foldmarks there -is also a vertical foldmark, whose position from the left margin is set via -the pseudo-length \PLength{lfoldmarkhpos}. This foldmark is used, for example, -in Japanese Chou- or You-format envelopes, when one wishes to use A4 size -sheets with them. This can also be useful for envelopes in C6 format.% +In\ChangedAt{v2.97e}{\Class{scrlttr2}} addition to the horizontal fold marks, +there is also a vertical fold mark. Its distance from the left margin is set +via the \PLength{lfoldmarkhpos} pseudo-length. This fold mark is used, for +example, in Japanese Chou- or You-format envelopes if you want to use them +with A4 paper. It can also be useful for envelopes in C6 format.% \EndIndexGroup \begin{Declaration} \PLength{lfoldmarklength} \end{Declaration} -The\ChangedAt{v2.97e}{\Class{scrlttr2}} length of the vertical foldmark is set -via the pseudo-length \PLength{lfoldmarklength}. Here too there is an -exceptional behaviour. When the length is set to null, a length of 4\Unit{mm} -is actually used.% +The\ChangedAt{v2.97e}{\Class{scrlttr2}} \PLength{lfoldmarklength} +pseudo-length determines the length of the vertical fold mark. Once again, a +feature worth noting is that if the length is given as zero, a length of +4\Unit{mm} is actually used.% \EndIndexGroup \begin{Declaration} \PLength{foldmarkvpos} \end{Declaration} -This\ChangedAt{v2.97e}{\Class{scrlttr2}} pseudo-length gives the distance of -all vertical foldmarks from the upper edge of the paper. Normally this is -3.5\Unit{mm}, but\textnote{Hint!} the value can be changed in the user's -personal \File{lco}-file in case the user's printer has a wider unprintable -top margin. Whether the foldmarks are typeset at all depends on the option +This\ChangedAt{v2.97e}{\Class{scrlttr2}} pseudo-length determines the distance of +all vertical fold marks from the upper edge of the paper. Normally this is +3.5\Unit{mm}, but\textnote{Hint!} you can change the value in your own +\File{lco} file in case your printer has a wider unprintable +top margin. Whether or not the foldmarks are actually typeset depends on the \DescRef{scrlttr2.option.foldmarks}% \important{\DescRef{scrlttr2.option.foldmarks}}% -\IndexOption{foldmarks~=\PName{Einstellung}} (see -\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.foldmarks}). At -present there is only one vertical foldmark, which is designated the left -vertical foldmark. -% +\IndexOption{foldmarks~=\PName{setting}} option (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.foldmarks}). +\iffree{At present there is only one vertical fold mark, called the left + vertical fold mark.}{}% \EndIndexGroup @@ -553,9 +577,9 @@ vertical foldmark. \PLength{foldmarkthickness} \end{Declaration} This\ChangedAt{v2.97c}{\Class{scrlttr2}} pseudo-length determines the -thickness of all foldmarks. Default value is 0.2\Unit{pt}, in other words a -very thin hairline. In particular, if the color of the foldmarks is -changed, this can be too thin!% +thickness of all fold marks. The default is 0.2\Unit{pt}, in other words a +very thin hairline. In\textnote{Hint!} particular, if the colour of the fold +marks is changed, this may not be enough.% \EndIndexGroup % \EndIndexGroup @@ -564,68 +588,67 @@ changed, this can be too thin!% \subsection{Letterhead} \seclabel{firstHead} \BeginIndexGroup -\BeginIndex{}{letterhead} - -The term letterhead here refers to all of the data pertaining to the sender -and which is set above the addressee's address. It is usually expected that -this information is set via the page style settings. In fact, this was the -case in the earlier incarnation of the letter class, -\Class{scrlettr}. But\textnote{Attention!} with \Class{scrlttr2}, the -letterhead is made independent of the page style setting, and is set by the -command \DescRef{scrlttr2.cmd.opening}\IndexCmd{opening}. +\BeginIndex{}{letterhead}% + +The term letterhead refers here to all of the information concerning the +sender that appears above the recipient's address. Normally you would expect +that this information would be set through the page-style settings. In fact, +this was the case with the old letter class, \Class{scrlettr}. +But\textnote{Attention!} \Class{scrlttr2} and \Package{scrletter} output the +letterhead independently of the page style by means of the +\DescRef{scrlttr2.cmd.opening}\IndexCmd{opening} command. % Fuellmaterial \iftrue% -The position of the letterhead is absolute and independent of the type -area. In fact, the first page of a letter, the page that holds the letterhead, -is set using the page style \PValue{empty}.% + The letterhead is positioned absolutely, so that it is independent of the + type area. In fact, the first page of a letter, the page that holds the + letterhead, is set using the page style + \DescRef{scrlttr2.pagestyle.empty}\IndexPagestyle{empty}.% \fi % Ende des Fuellmaterials + \begin{Declaration} \PLength{firstheadvpos} \end{Declaration} -The pseudo-length \PLength{firstheadvpos} gives the distance between the top -edge of the paper and start of the letterhead. This value is set differently -in the various predefined -\File{lco}-files\textnote{\File{lco}-file}\Index{lco-file=\File{lco}-file}. A +The \PLength{firstheadvpos} pseudo-length gives the distance between the top +edge of the paper and the start of the letterhead. This value is set +differently in the various predefined +\File{lco} files\textnote{\File{lco} file}\Index{lco file=\File{lco} file}. A typical value is 8\Unit{mm}.% -% \EndIndexGroup \begin{Declaration} \PLength{firstheadhpos} \end{Declaration} -A positive value of pseudo-length -\PLength{firstheadhpos}\ChangedAt{v3.05}{\Class{scrlttr2}} gives the distance -between the left edge of the paper and the start of the -letterhead. If\textnote{Attention!} is actually greater than or equal to the -paper width, +A positive value of the +\PLength{firstheadhpos}\ChangedAt{v3.05}{\Class{scrlttr2}} pseudo-length gives +the distance between the left edge of the paper and the start of the +letterhead. If\textnote{Attention!} the value is actually greater than or +equal to the paper width, \Length{paperwidth}\important{\Length{paperwidth}}\IndexLength{paperwidth}, -then the letterhead will be centered to the note paper width. A negative value -gives the distance between the distance between the right paper edge and the -end of the letterhead. If the value is even less or equal to the negative -value of the width of the paper, then the letterhead will be left aligned to -the left edge of the typing area. - -Typical default\textnote{Attention!} is a value of -\Length{maxdimen}\IndexLength{maxdimen}, though the greatest allowed value of -a length. This will result in horizontal centering.% -% +the letterhead will be centred horizontally on the letterhead paper. A +negative value gives the distance between the right edge of the paper and the +right edge of the letterhead. If the value actually less than or equal to the +negative value of the width of the paper, the letterhead is placed flush with +the left edge of the type area. + +The default\textnote{Attention!} value is typically +\Length{maxdimen}\IndexLength{maxdimen}, which is the maximum allowed value of +a length. This results in horizontal centring.% \EndIndexGroup \begin{Declaration} \PLength{firstheadwidth} \end{Declaration} -The pseudo-length \PLength{firstheadwidth} gives the width of the -letterhead. This value is set differently in the various predefined -\File{lco}-files\textnote{\File{lco}-file}\Index{lco-file=\File{lco}-file}. -While this value usually depends on the paper width and the distance between -the left edge of the paper and the adressee address field, it was the type -area width in \Option{KOMAold} and has a definite value of 170\Unit{mm} in +The \PLength{firstheadwidth} pseudo-length gives the width of the letterhead. +This value is set differently in the various predefined \File{lco} +files\textnote{\File{lco} file}\Index{lco file=\File{lco} file}. While this +value usually depends on the paper width and the distance between the left +edge of the paper and the recipient's address field, it was the width of the +type area in \Option{KOMAold} and has a fixed value of 170\Unit{mm} in \Option{NF}.% -% \EndIndexGroup @@ -633,20 +656,19 @@ area width in \Option{KOMAold} and has a definite value of 170\Unit{mm} in \PLength{fromrulethickness}% \PLength{fromrulewidth} \end{Declaration} -Depending on the class option \Option{fromrule} (see -\autoref{sec:scrlttr2.firstpage}, -\DescPageRef{scrlttr2.option.fromrule}), a horizontal rule can be drawn -the predefined letterheads under or within the sender -address. If\textnote{Attention!} the pseudo-length \PLength{fromrulewidth} has -a value of 0\Unit{pt}, which is the default in the predefined \File{lco} -files, the rule length is calculated automatically taking into account, -e.\,g., letterhead width or an optional logo. Users can adjust rule length -manually in their own \File{lco}-files by setting this pseudo-length to -positive values using \Macro{\@setplength} (see -\DescPageRef{scrlttr2-experts.cmd.@setplength}). The default thickness of -the line\ChangedAt{v2.97c}{\Class{scrlttr2}}, \PLength{fromrulethickness}, is -0.4\Unit{pt}.% -% +As mentioned in the explanation of the +\DescRef{scrlttr2.option.fromrule}\IndexOption{fromrule} option in +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.fromrule}, you +can put a horizontal rule within or below the sender's address in the +predefined letterheads. If\textnote{Attention!} the \PLength{fromrulewidth} +pseudo-length has a value of 0\Unit{pt}, which is the default in the +predefined \File{lco} files, the length of this rule is calculated +automatically taking into account, for example, letterhead width or an +optional logo. You can adjust rule length manually in your own \File{lco} +files by setting this pseudo-length to positive values using +\Macro{\@setplength} (see \DescPageRef{scrlttr2-experts.cmd.@setplength}). The +default thickness of the line\ChangedAt{v2.97c}{\Class{scrlttr2}}, +\PLength{fromrulethickness}, is 0.4\Unit{pt}.% \EndIndexGroup % \EndIndexGroup @@ -656,63 +678,62 @@ the line\ChangedAt{v2.97c}{\Class{scrlttr2}}, \PLength{fromrulethickness}, is \seclabel{addressee}% \BeginIndexGroup \BeginIndex{}{addressee} -\index{address|seealso{addressee}} +\index{recipient|seealso{addressee}} -The term addressee here refers to the addressee's name and address which -are output in an address field. Additional information can be output -within this address field, such as dispatch type or a return address; -the latter is especially useful when using window envelopes. The -address directly follows the letterhead. +The term \emph{addressee} normally refers only to the recipient's name and +address, which are output in an address field. Additional information, +however, can be placed within this address field, including the delivery +method, for example registered mail or special delivery. For window envelopes, +the return address also counts as part of the address field, as it will be +displayed in the address window. The address field directly follows the +letterhead. \begin{Declaration} \PLength{toaddrvpos}% \PLength{toaddrhpos} \end{Declaration} -These pseudo-lengths define vertical and horizontal position of the address -field relative to the top-left corner of the paper. Values are set differently -in the various predefined -\File{lco}-files\textnote{\File{lco}-file}\Index{lco-file=\File{lco}-file}, -according to standard envelope window measures. A special feature of -\PLength{toaddrhpos} is that with negative values the offset is that of the -right edge of the address field relative to the right edge of the paper. This -can be found, for instance, in the case of \Option{SN} or \Option{NF}. The -smallest value of \PLength{toaddrvpos} is found with \Option{DINmtext}. Care -must be taken to avoid overlap of letterhead and address field. Whether the -address field is output or not can be controlled by class option -\Option{addrfield} (see \autoref{sec:scrlttr2.firstpage}, -\DescPageRef{scrlttr2.option.addrfield}).% -% +These pseudo-lengths define the vertical and horizontal distance of the +address field from the top-left corner of the paper. Values are set +differently in the various predefined \File{lco} files\textnote{\File{lco} +file}\Index{lco file=\File{lco} file}, according to standard envelope window +measures. For \PLength{toaddrhpos}, one property worth noting is that with +negative values, the offset is the distance from the right edge of the address +field to the right edge of the paper. You will find this, for instance, in +\Option{SN} or \Option{NF}. The smallest value of \PLength{toaddrvpos} is +found with \Option{DINmtext}. With this setting, the letterhead can easily +protrude into the address window. Whether the address field is output or not +depends on the \Option{addrfield} option (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.addrfield}).% \EndIndexGroup \begin{Declaration} \PLength{toaddrheight} \end{Declaration} -The pseudo-length \PLength{toaddrheight} defines the height of the -address field, including the dispatch type. If no dispatch type is -specified, then the address is vertically centered in the field. If a -dispatch type is specified, then the address is set below the dispatch -type, and vertically centered in the remaining field height. -% +This pseudo-length defines the height of the address field, including the +delivery method. Whether the name and address of the recipient are vertically +centred in the address field, taking into account the presence or absence of +the delivery method, depends on the \DescRef{scrlttr2.option.addrfield} +option.% \EndIndexGroup \begin{Declaration} \PLength{toaddrwidth} \end{Declaration} -This pseudo-length defines the width of the address field. Values are set -differently in the various predefined -\File{lco}-files\textnote{\File{lco}-files}\Index{lco-file=\File{lco}-files}, -according to standard envelope window measures. Typical values are between -70\Unit{mm} and 100\Unit{mm}. +This pseudo-length defines the width of the address field. The various +predefined \File{lco} files\textnote{\File{lco} files}\Index{lco +file=\File{lco} files} use different settings according to the different +standards for window envelopes. Typical values are between 70\Unit{mm} and +100\Unit{mm}. \begin{Example} - Assume that your printer has a very wide left or right margin of - 15\Unit{mm}. In this case, when using the option \Option{SN}, the - letterhead, sender's extensions and the address can not be completely - printed. Thus, you create a new \File{lco}-file with the following content: + Suppose your printer has very wide, non-printable left and right margins of 15\Unit{mm}. + This means that the letterhead, the additional sender information, and the address field cannot + be completely printed if you use the \Option{SN} option. You therefore + create a new \File{lco} file with the following content: \begin{lstcode} \ProvidesFile{SNmmarg.lco} - [2002/06/04 v0.1 my own lco] + [2002/06/04 v0.1 my lco] \LoadLetterOption{SN} \@addtoplength{toaddrwidth}{% -\useplength{toaddrhpos}} @@ -722,8 +743,8 @@ according to standard envelope window measures. Typical values are between \endinput \end{lstcode} Then, until you can obtain a printer with smaller page margins, you - simply use the option \Option{SNmmarg} instead of \Option{SN}. -\end{Example} + simply use the option \Option{SNmmarg} instead of \Option{SN}.% +\end{Example}% % \EndIndexGroup @@ -731,53 +752,48 @@ according to standard envelope window measures. Typical values are between \begin{Declaration} \PLength{toaddrindent} \end{Declaration} -Additional indentation of the address within address field can be controlled -by the pseudo-length \PLength{toaddrindent}. Its value applies to both left -and right margin. Default value is 0\Unit{pt}. +Sometimes you do not want the address field to extend the full width of the +address window but to be indented a bit. You can set the amount of this +indentation with the \PLength{toaddrindent} pseudo-length. Typically, the +default value is 0\Unit{pt}. -With\textnote{Attention!} each of the -settings\ChangedAt{v3.03}{\Class{scrlttr2}} -\OptionValueRef{scrlttr2}{addrfield}{PP}\important[i]{% +For\textnote{Attention!} the\ChangedAt{v3.03}{\Class{scrlttr2}} +\OptionValueRef{scrlttr2}{addrfield}{PP}\important{% \OptionValueRef{scrlttr2}{addrfield}{PP}\\ \OptionValueRef{scrlttr2}{addrfield}{image}\\ - \begin{tabular}{@{}l@{}} - \KOption{addrfield}\\ - \quad\PValue{backgroundimage} - \end{tabular}}\IndexOption{addrfield~=\PValue{PP}}, -\OptionValueRef{scrlttr2}{addrfield}{image}\IndexOption{addrfield~=\PValue{image}}, and + \OptionValueRef{scrlttr2}{addrfield}{backgroundimage} +}\IndexOption{addrfield~=\textKValue{PP}}, +\OptionValueRef{scrlttr2}{addrfield}{image}% +\IndexOption{addrfield~=\textKValue{image}}, and \OptionValueRef{scrlttr2}{addrfield}{backgroundimage}% -\IndexOption{addrfield~=\PValue{backgroundimage}} (see -\autoref{sec:scrlttr2.firstpage}, -\DescPageRef{scrlttr2.option.addrfield}) a value of 0\Unit{pt} will be -replaced by a value of 8\Unit{mm}. If really no indent should be used in this -case, then 1\Unit{sp} may be used to set a negligible small -indent. Additionally \PLength{toaddrindent} will be used also for the distance -to the right edge of the address window with the mentioned \Option{addrfield} -settings.% -% +\IndexOption{addrfield~=\textKValue{backgroundimage}} settings (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.addrfield}) a +value of 0\Unit{pt} will be replaced by a value of 8\Unit{mm}. If you really +do not want any indentation, you can use a value of 1\Unit{sp} to set a +negligibly small indentation. Furthermore, \PLength{toaddrindent} is also used +for the distance to the right edge of the address window with the these +\Option{addrfield} settings.% \EndIndexGroup \begin{Declaration} \PLength{backaddrheight} \end{Declaration} -For window envelopes the sender is often printed with small font at one line -above the addressee. This kind of sender's information is known as return +For window envelopes, the sender is often printed in a small font on one line +above the addressee. This sender information is called the return address\textnote{return address}\Index{return address}, because it is visible -at the address window and will be used by the post officers to return the -letter (back) to the sender. In this return address only that information -should be that is needed for this purpose. - -The height, that is reserved for the return address at the top of the address -field, is given by pseudo-length \PLength{backaddrheight}. A typical value for -this is 5\Unit{mm} in the predefined -\File{lco}-files\textnote{\File{lco}-file}\Index{}{lco-file=\File{lco}-file}. -Whether or not to print the return address depend on option \Option{addrfield} -(see \autoref{sec:scrlttr2.firstpage}, -\DescPageRef{scrlttr2.option.addrfield}) and -\DescRef{scrlttr2.option.backaddress} (see \autoref{sec:scrlttr2.firstpage}, -\DescPageRef{scrlttr2.option.backaddress}).% -% +in the address window and will be used by the post office to return an +undeliverable letter to the sender. This return address, therefore, requires +only the information necessary for that purpose. + +The height reserved for the return address within the address window is given +by the \PLength{backaddrheight} pseudo-length. This value is typically +5\Unit{mm} in the predefined \File{lco} files\textnote{\File{lco} +file}\Index{}{lco file=\File{lco} file}. Whether to print the return address +at all depends on the \Option{addrfield} (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.addrfield}) and +\DescRef{scrlttr2.option.backaddress} options (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.backaddress}).% \EndIndexGroup @@ -785,17 +801,16 @@ Whether or not to print the return address depend on option \Option{addrfield} \PLength{specialmailindent}% \PLength{specialmailrightindent} \end{Declaration} -An optional dispatch type can be output within the address field between the -return address and the addressee address, by setting the variable -\DescRef{scrlttr2.variable.specialmail}. Left and right alignment are determined by -pseudo-lengths \PLength{specialmailindent} and -\PLength{specialmailrightindent}, respectively. In the predefined -\File{lco}-files\textnote{\File{lco}-file}\Index{lco-file=\File{lco}-file} -provided by \KOMAScript, \PLength{specialmailindent} is set to rubber length -\Macro{fill}, while \PLength{specialmailrightindent} is set to -1\Unit{em}. Thus the dispatch type is set 1\Unit{em} from the address field's -right margin. -% +You can print an optional delivery method between the return address and the +recipient's address. This field is printed only if the +\DescRef{scrlttr2.variable.specialmail} variable has non-empty contents. Its +alignment is determined by the \PLength{specialmailindent} and +\PLength{specialmailrightindent} pseudo-lengths, which specify the left and +right indentation, respectively. In the predefined \File{lco} +files\textnote{\File{lco} file}\Index{lco file=\File{lco} file}, +\PLength{specialmailindent} is set to rubber length \Macro{fill}, while +\PLength{specialmailrightindent} is set to 1\Unit{em}. Thus the delivery +method is set 1\Unit{em} from the address field's right margin.% \EndIndexGroup @@ -803,27 +818,26 @@ right margin. \PLength{PPheadheight}% \PLength{PPheadwidth} \end{Declaration} -The pseudo-length \PLength{PPheadheight}\ChangedAt{v3.03}{\Class{scrlttr2}} is -the height, that will be reserved for the Port-Pay\'e head using the options -\OptionValueRef{scrlttr2}{addrfield}{PP}\important[i]{% +The \PLength{PPheadheight}\ChangedAt{v3.03}{\Class{scrlttr2}} pseudo-length +specifies the height reserved for the postpaid header at the start of the +address field for the two options +\OptionValueRef{scrlttr2}{addrfield}{PP}\important{% \OptionValueRef{scrlttr2}{addrfield}{PP}\\ - \begin{tabular}{@{}l@{}} - \KOption{addrfield}\\ - \quad\PValue{backgroundimage} - \end{tabular}}\IndexOption{addrfield~=\PValue{PP}} and + \OptionValueRef{scrlttr2}{addrfield}{backgroundimage}}% +\IndexOption{addrfield~=\textKValue{PP}} and \OptionValueRef{scrlttr2}{addrfield}{backgroundimage}% -\IndexOption{addrfield~=\PValue{backgroundimage}}. Pseudo-length -\PLength{PPheadwidth} will be used only with \OptionValueRef{scrlttr2}{addrfield}{PP} (see -\autoref{sec:scrlttr2.firstpage}, -\DescPageRef{scrlttr2.option.addrfield}) and gives the width of the left -field in the Port-Pay\'e head that contains P.\,P. logo, zip-code and -place. The width of the right field with the sender's code and the priority is -the remaining width. - -Class\textnote{Attention!} \Class{scrlttr2} automatically changes -pseudo-length \PLength{PPheadheight}'s\textnote{Attention} usual default value -from 0\Unit{mm} into 20,74\Unit{pt} and \PLength{PPheadwidth}'s default from -0\Unit{mm} into 42\Unit{mm}.% +\IndexOption{addrfield~=\textKValue{backgroundimage}}. The +\PLength{PPheadwidth} pseudo-length is used only with +\OptionValueRef{scrlttr2}{addrfield}{PP} (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.addrfield}) and +gives the width of the left-hand field within the postpaid header, which +contains the postpaid logo, the postal code, and the location. The width of +the right-hand field containing the sender's code and the priority is the +remaining width. + +\KOMAScript{}\textnote{Attention!} automatically changes the default value of +0\Unit{mm} for the \PLength{PPheadheight} pseudo-length to 20.74\Unit{pt}, and +\PLength{PPheadwidth}'s default from 0\Unit{mm} to 42\Unit{mm}.% % \EndIndexGroup @@ -831,32 +845,31 @@ from 0\Unit{mm} into 20,74\Unit{pt} and \PLength{PPheadwidth}'s default from \begin{Declaration} \PLength{PPdatamatrixvskip} \end{Declaration} -This\ChangedAt{v3.03}{\Class{scrlttr2}} pseudo-length gives the vertical -distance between the Port-Pay\'e head and the data array or data matrix of -option \OptionValueRef{scrlttr2}{addrfield}{PP}% +This\ChangedAt{v3.03}{\Class{scrlttr2}} pseudo-length specifies the vertical +distance between the postpaid header and the data array used with +\OptionValueRef{scrlttr2}{addrfield}{PP}% \important{\OptionValueRef{scrlttr2}{addrfield}{PP}}% \IndexOption{addrfield~=\PValue{PP}} (see \autoref{sec:scrlttr2.firstpage}, -\DescPageRef{scrlttr2.option.addrfield}). Class\textnote{Attention!} -\Class{scrlttr2} automatically changes the default value 0\Unit{mm} into -9\Unit{mm}. The data matrix will be set right aligned with the Port-Pay\'e -head.% -% +\DescPageRef{scrlttr2.option.addrfield}). \KOMAScript{}\textnote{Attention!} +automatically changes the default value of 0\Unit{mm} to 9\Unit{mm}. The data +matrix is flush right within the postpaid header.% \EndIndexGroup % \EndIndexGroup -\subsection{Sender's Extensions} +\subsection{Extra Sender Information} \seclabel{locationField} \BeginIndexGroup -\BeginIndex{}{sender's extension} -\index{sender>extension|see{sender's extension}} +\BeginIndex{}{extra sender information} +\index{sender>extra information|see{extra sender information}} -Often, especially with business letters, the space for the letterhead or page -footer seems to be too tight to include all you want. To give more details -about the sender, often the space right beside the addressee's field is -used. In this manual this field is called the \emph{sender's extension}. In -former manuals is has been called \emph{location field}. +Often, especially with business letters, there is not enough space in the +letterhead and footer to accommodate all the information about the sender that +you want to include. For such additional information, you can use the space +next to the addressee. In this manual, this field is called the +\emph{extra sender information}. In earlier versions of this manual, it +was called the \emph{sender's extension} or the \emph{location field}. \begin{Declaration} \PLength{locheight}% @@ -864,60 +877,52 @@ former manuals is has been called \emph{location field}. \PLength{locvpos}% \PLength{locwidth} \end{Declaration} -The pseudo-lengths \PLength{locwidth} and -\PLength{locheight}\ChangedAt{v2.97d}{\Class{scrlttr2}} set the width and -height of the sender's extension field. The pseudo-lengths \PLength{lochpos} -and \PLength{locvpos} determine the distances from the right and upper paper -edges. These value is typically set to 0\Unit{pt} in the predefined \File{lco} -files. This\textnote{Attention!} does not mean that the sender's extension has -no width; instead, it means that the actual width is set within -\DescRef{scrlttr2.cmd.opening} when the paper width, address window width, and -the distance between the left and upper edges of the paper and the address -window are known. The option \DescRef{scrlttr2.option.locfield} (see -\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.locfield}) is -also taken into account. As is the case for \PLength{toaddrhpos}, negative -values of \PLength{lochpos} take on a special meaning. In that case, instead -of referring to a distance from the right edge of the paper, \PLength{lochpos} -now means a distance from the left edge of the paper. The meaning is thus the -opposite to that of \PLength{toaddrhpos} (see -\autoref{sec:scrlttr2-experts.addressee}, +The \PLength{locwidth} and +\PLength{locheight}\ChangedAt{v2.97d}{\Class{scrlttr2}} pseudo-lengths set the +width and height of the extra-sender-information field. The \PLength{lochpos} +and \PLength{locvpos} pseudo-lengths determine the distances from the +top-right edge of the paper. These values are typically set to 0\Unit{pt} in +the predefined \File{lco} files. These\textnote{Attention!} zero-length values +have a special meaning. They result in the actual values being set within +\DescRef{scrlttr2.cmd.opening} based on the paper width, the address-window +width, the address window's distance from the top-left edge of the paper, and +the \DescRef{scrlttr2.option.locfield} option (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.locfield}). As +is the case for \PLength{toaddrhpos}, negative values of \PLength{lochpos} +also take on a special meaning. Instead of referring to the distance from the +right edge of the paper, \PLength{lochpos} then refers to the distance from +the left edge of the paper. The meaning is thus the opposite of that of +\PLength{toaddrhpos} (see \autoref{sec:scrlttr2-experts.addressee}, \DescPageRef{scrlttr2-experts.plength.toaddrhpos}).% -% \EndIndexGroup % \EndIndexGroup -\subsection{Business Line} +\subsection{Reference Line} \seclabel{refLine}% \BeginIndexGroup -\BeginIndex{}{business line} -\index{reference>field line|see{business line}} -\index{reference>line|see{business line}} - -Especially with business letters, a line can be found that gives initials, -dial code, customer number, invoice number, or a reference to a previous -letter. This line is sometimes called \emph{reference fields line} or -\emph{reference line}, sometimes \emph{business line}. The business line can -consist of more than just one line and is set only if one of those variables -mentioned above is given. Only those fields will be set that are -given. To\textnote{Hint!} set a seemingly empty field, one needs to give as -value at least a forced white space or \Macro{null}. If you want to have your -letter without a business line, then instead of it the label and contents of -the variable \DescRef{scrlttr2.variable.date} will be set. Information about adding variables -to the business line or clean up the business line may be found in -\autoref{sec:scrlttr2-experts.variables}, +\BeginIndex{}{reference line} +\index{business line|see{reference line}} + +The reference line can actually be longer than just one line. It is printed +only if at least one of variables for the reference line is not empty. Only +non-empty fields will be printed. To\textnote{Hint!} set a seemingly empty +field, you can provide content for the variable that appears empty, such as +\Macro{mbox}\Parameter{}. If the reference line is omitted, the description +and contents of the \DescRef{scrlttr2.variable.date} variable are printed in +its place. You can find information about adding variables to or removing them +from the reference line in \autoref{sec:scrlttr2-experts.variables}, \DescPageRef{scrlttr2-experts.cmd.removereffields}. + \begin{Declaration} \PLength{refvpos} \end{Declaration} -This pseudo-length gives the distance between the upper edge of the paper and -the reference fields line. Its value is set differently in the various -predefined -\File{lco}-files\textnote{\File{lco}-file}\Index{lco-file=\File{lco}-file}. -Typical values are between 80.5\Unit{mm} and 98.5\Unit{mm}. -% +This pseudo-length specifies the distance from the upper edge of the paper to +the reference line. Its value is set differently in the various predefined +\File{lco} files\textnote{\File{lco} file}\Index{lco file=\File{lco} file}. +Typical values are between 80.5\Unit{mm} and 98.5\Unit{mm}.% \EndIndexGroup @@ -925,52 +930,49 @@ Typical values are between 80.5\Unit{mm} and 98.5\Unit{mm}. \PLength{refwidth}% \PLength{refhpos} \end{Declaration} -This pseudo-length gives the width that is available for the reference fields -line. The value is set typically to 0\Unit{pt} in the predefined -\File{lco}-files\textnote{\File{lco}-file}\Index{lco-file=\File{lco}-file}. -This\textnote{Attention!} value has a special meaning: in no way does it -determine that there is no available width for the business line; instead, -this value means that the width will be calculated within the command -\DescRef{scrlttr2.cmd.opening}\IndexCmd{opening}. Thus the calculated width depends on the -determination of the options \DescRef{scrlttr2.option.refline}\important{\DescRef{scrlttr2.option.refline}}% -\IndexOption{refline~=\PName{Einstellung}} (see -\autoref{sec:scrlttr2.firstpage}, -\DescPageRef{scrlttr2.option.refline}). At the same time, -\PLength{refhpos} will be set according to this option. With -\OptionValueRef{scrlttr2}{refline}{wide}\IndexOption{refline~=\PValue{wide}}, the reference -fields line is centered, while with -\OptionValueRef{scrlttr2}{refline}{narrow}\IndexOption{refline~=\PValue{narrow}} it is -aligned on the left inside the typing area. - -If \PLength{refwidth} is not null, i.\,e., the width of the reference fields -line is therefore not determined by the option \DescRef{scrlttr2.option.refline}, then -\PLength{refhpos} gives the distance of the reference fields line from the -left edge of the paper. If\textnote{Attention!} this distance is null, then -the reference fields line is set so that the ratio between its distances from -the left and right edges of the paper equal the ratio of distance of the type +The \PLength{refwidth} pseudo-length specifies the width available for the +reference line. Its value is typically set to 0\Unit{pt} in the predefined +\File{lco} files\textnote{\File{lco} file}\Index{lco file=\File{lco} file}. +This\textnote{Attention!} value has a special meaning. In no way does it +indicate that there is no available width for the reference line. Instead, it +indicates that the width will be calculated within the +\DescRef{scrlttr2.cmd.opening}\IndexCmd{opening} command. This calculated +width then depends on the value of the \DescRef{scrlttr2.option.refline}% +\important{\DescRef{scrlttr2.option.refline}}% +\IndexOption{refline~=\PName{setting}} options (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.refline}). At +the same time, \PLength{refhpos} will also be set according to this option. +With \OptionValueRef{scrlttr2}{refline}{wide}% +\IndexOption{refline~=\textKValue{wide}}, the reference fields line is +centred, while with \OptionValueRef{scrlttr2}{refline}{narrow}% +\IndexOption{refline~=\textKValue{narrow}} it is aligned flush left with the +type area. + +If \PLength{refwidth} is not zero, the width of the reference line is not +determined by the \DescRef{scrlttr2.option.refline} option, and so +\PLength{refhpos} specifies the distance of the reference line from the left +edge of the paper. If\textnote{Attention!} this distance is zero, the the +reference line is placed so that the ratio between its distances from the left +and right edges of the paper corresponds to the ratio of distance of the type area from the left and right edges of the paper. Thus, for a type area -horizontally centered on the paper, the reference fields line too will be -centered. - -As a rule, these special cases are likely to be of little interest to the -normal user. The\textnote{Attention!} simplest rule is as follows: either -\PLength{refhpos} is left at null and so the width and alignment of the -reference fields line are left to the option -\DescRef{scrlttr2.option.refline}, or \PLength{refwidth} as well as -\PLength{refhpos} are set by the user.% -% +horizontally centred on the paper, the reference line will also be centred. + +As a rule, these special cases are likely of little interest to the normal +user. The\textnote{Attention!} simplest rule is as follows: either +\PLength{refhpos} remains zero, and so the width and alignment of the +reference line are determined with the \DescRef{scrlttr2.option.refline} +option, or the user sets both \PLength{refwidth} and \PLength{refhpos}.% \EndIndexGroup \begin{Declaration} \PLength{refaftervskip} \end{Declaration} -This pseudo-length gives the vertical space that has to be inserted beneath -the reference fields line. The value is set in the predefined -\File{lco}-files\textnote{\File{lco}-file}\Index{lco-file=\File{lco}-file}. It -directly affects the text height of the first page. A typical value lies +This pseudo-length specifies the vertical skip to be inserted beneath the +reference line. The value is set in the predefined \File{lco} +files\textnote{\File{lco} file}\Index{lco file=\File{lco} file}. It directly +affects the height of the text area on the first page. A typical value is between one and two lines.% -% \EndIndexGroup % \EndIndexGroup @@ -981,26 +983,26 @@ between one and two lines.% \BeginIndexGroup \BeginIndex{}{subject} -In different countries the letter's subject will be set different. Some like -to have the subject before the opening phrase, some prefer the subject below -the opening phrase. Some professional guilds at least want the subject before -the business line. +Different countries have different conventions for placing the subject line of +a letter. Some place it before the opening phrase; others place it after. Some +professional groups even want it before the reference line. \begin{Declaration} \PLength{subjectvpos} \end{Declaration} \ChangedAt{v3.01}{\Class{scrlttr2}}% If\textnote{Attention!} the value of this pseudo-length is 0\Unit{pt}, the -position of the subject is given by option \DescRef{scrlttr2.option.subject}\important{\DescRef{scrlttr2.option.subject}}% -\IndexOption{subject~=\PName{Einstellung}} (see -\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.subject}). -Every other value defines the distance between the top edge of the paper and -the subject. It\textnote{Hint!} is recommended to take care of the available -space to surely avoid interferences with other elements. +\IndexOption{subject~=\PName{Einstellung}} option (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.subject}) +determines the position of the subject. Any other value defines the distance +between the top edge of the paper and the subject. In this +case\textnote{Hint!}, you should ensure that there is enough space available +that overlapping with other elements is unlikely. \begin{Example} - Some professional guilds prefer to have the subject at least before the - business line. To achieve this, the position may be defined like this: + A few professionals prefer to have the subject above the reference line. For + this, you can specify the position as follows, which also changes the + position of the reference line itself: \begin{lstcode} \ProvidesFile{lawsubj.lco} [2008/11/03 lawyers lco file] @@ -1008,9 +1010,8 @@ space to surely avoid interferences with other elements. \@addtoplength{refvpos}{3\baselineskip} \endinput \end{lstcode} - which also changes the position of the business line itself. If at least one - empty line between subject and business line should stay empty, this - provides a maximum of two subject lines. + If you want to leave at least one empty line between the subject and the + reference, you have space for a maximum of two lines. \end{Example} \EndIndexGroup @@ -1020,13 +1021,12 @@ space to surely avoid interferences with other elements. \PLength{subjectaftervskip} \end{Declaration} \ChangedAt{v3.01}{\Class{scrlttr2}}% -If the subject is not positioned absolutely, but before or after the opening -phrase, additional vertical spaces may be inserted before and after the -subject. Thereby, the space before the subject may interfere with other -distances like the automatic distance of one line after the title. Because of -this the default is to use no additional space here. In contrast, the class's -default for the space after the subject is two lines.% -% +If the subject is placed not absolutely but before or after the salutation, +you can insert additional vertical space before and after the subject. The +space before the subject may interfere with other distances, such as the +automatic distance of one line after the title. Therefore the default is to +use no additional space here. The default of the class and the package for the +space after the subject is two lines.% \EndIndexGroup % \EndIndexGroup @@ -1037,87 +1037,92 @@ default for the space after the subject is two lines.% \BeginIndexGroup \BeginIndex{}{closing} -The closing consists of three parts: besides the closing phrase there -are a hand-written inscription and the signature, which acts as an -explanation for the inscription. +The closing of a letter consists of three parts: In addition to the closing +phrase, there is a hand-written signature and a printed text such as a name, +which acts as a kind of explanation of the hand-written signature. \begin{Declaration} \PLength{sigindent}% \PLength{sigbeforevskip} \end{Declaration} -Closing phrase\Index{closing>phrase}\Index{signature} and signature will be -typeset in a box. The width of the box is determined by the length of the -longest line of the closing phrase or signature. - -The box will be typeset with indentation of the length set in pseudo-length -\PLength{sigindent}. In the predefined -\File{lco}-files\textnote{\File{lco}-file}\Index{lco-file=\File{lco}-file} -this length is set to 0\Unit{mm}. - -Between closing phrase and signature a vertical space is inserted, the height -of which is defined in the pseudo-length \PLength{sigbeforevskip}. In the -predefined -\File{lco}-files\textnote{\File{lco}-file}\Index{lco-file=\File{lco}-file} -this is set to two lines. In this space you can then write your inscription.% +The closing phrase\Index{closing>phrase}\Index{signature} and signature +explanation are typeset in a box whose width is determined by the length of +the longest line of the closing phrase or explanation. + +The box will be indented by the distance specified in the \PLength{sigindent} +pseudo-length. In the predefined \File{lco} files\textnote{\File{lco} +file}\Index{lco file=\File{lco} file}, this length is set to 0\Unit{mm}. + +Between the closing phrase and the signature explanation, a vertical skip is +inserted whose height is defined in the \PLength{sigbeforevskip} +pseudo-length. In the predefined \File{lco} files\textnote{\File{lco} +file}\Index{lco file=\File{lco} file} this value is set to two lines. In this +space you can then write your signature.% +\iffalse% Umbruchkorrekturtext +\ If you decide to include a facsimile of your signature in the +\DescRef{scrlttr2.variable.signature}\IndexVariable{signature}% +\important{\DescRef{scrlttr2.variable.signature}} with the +\Package{graphicx}\IndexPackage{graphicx} package, it would be useful +to reduce the value of \PLength{sigbeforevskip} and thus the gap between +the closing phrase and the signature.% +\fi% \EndIndexGroup % \EndIndexGroup -\subsection{Letter Footer} +\subsection{Letterhead Page Footer} \seclabel{firstFoot}% \BeginIndexGroup -\BeginIndex{}{letter>footer}% -\index{note paper>footer|see{letter footer}}%| +\BeginIndex{}{letterhead page>footer}% - -As the first page of a letter, the note paper, holds a letterhead of its own, -it also holds a footer\Index{footer>of note paper}\Index{footer>of letter} of -its own. And, as with the letterhead, it will not be set by the page style -settings, but directly with the use of -\DescRef{scrlttr2.cmd.opening}\IndexCmd{opening}\important{\DescRef{scrlttr2.cmd.opening}}. +The first page of a letter, the letterhead page, contains not just its own +header, the letterhead, but also its own footer\Index{footer>letterhead +page}\Index{footer}. Just like the letterhead, it will be set not by the page +style but directly within \DescRef{scrlttr2.cmd.opening}\IndexCmd{opening}% +\important{\DescRef{scrlttr2.cmd.opening}}. \begin{Declaration} \PLength{firstfootvpos} \end{Declaration} -This pseudo-length gives the distance between the letter footer and the upper -edge of the paper. It also takes care of preventing text from jutting into the -footer area. For this the text height on the first page will be decreased -using \Macro{enlargethispage}\IndexCmd{enlargethispage}% -\important{\Macro{enlargethispage}} if needed. Likewise, and if it is wanted, -the text height can conversely be extended with the help of the option -\DescRef{scrlttr2.option.enlargefirstpage}\important{\DescRef{scrlttr2.option.enlargefirstpage}} (see +This pseudo-length gives the distance from the top of the paper to the footer +of the letterhead page. It also ensures that the text area does not protrude +into the footer. To do so, the height of the text area on the first page will +be decreased, if necessary, using +\Macro{enlargethispage}\IndexCmd{enlargethispage}% +\important{\Macro{enlargethispage}}. The +\DescRef{scrlttr2.option.enlargefirstpage}% +\important{\DescRef{scrlttr2.option.enlargefirstpage}} option (see \autoref{sec:scrlttr2.firstpage}, -\DescPageRef{scrlttr2.option.enlargefirstpage}). This way, the distance -between text area and the first letter footer can be reduced to the value -\Length{footskip}\IndexLength{footskip}\important{\Length{footskip}}. +\DescPageRef{scrlttr2.option.enlargefirstpage}) can also ensure that the +height of the text area is increased, if necessary. Thus, the distance between +text area and the letterhead page footer can be reduced to the value of the +\Length{footskip}\IndexLength{footskip}\important{\Length{footskip}} length. With\textnote{Attention!} the compatibility option -set\ChangedAt{v2.9t}{\Class{scrlttr2}} up to version +set\ChangedAt{v2.9t}{\Class{scrlttr2}} to versions up to 2.9t\IndexOption{version~=\PValue{2.9t}} (see \DescRef{scrlttr2.option.version} in \autoref{sec:scrlttr2.compatibilityOptions}, \DescPageRef{scrlttr2.option.version}) the footer is set independently of the -type area in all predefined -\File{lco}-files\textnote{\File{lco}-file}\Index{lco-file=\File{lco}-file} -(see \autoref{sec:scrlttr2.lcoFile}) except for \Option{KOMAold} and -\Option{NF}. The option \DescRef{scrlttr2.option.enlargefirstpage}% -\important{\DescRef{scrlttr2.option.enlargefirstpage}} also loses its -effect. From version 2.9u\IndexOption{version~=\PValue{2.9u}} onwards the -footer is set in a position at the bottom edge of the paper. In this -situation, the height of the type area also becomes dependent on -\DescRef{scrlttr2.option.enlargefirstpage}. - -If the letter footer be switched off using option +type area in all predefined \File{lco} files\textnote{\File{lco} +file}\Index{lco file=\File{lco} file} (see \autoref{sec:scrlttr2.lcoFile}) +except for \Option{KOMAold} and \Option{NF}. Thus the +\DescRef{scrlttr2.option.enlargefirstpage}% +\important{\DescRef{scrlttr2.option.enlargefirstpage}} option has no effect. +From version 2.9u on, the footer is placed at the bottom edge of the paper. +Thus, the height of the letterhead page's type area may also depend on the +\DescRef{scrlttr2.option.enlargefirstpage} option. + +If the letter footer is deactivated with the \OptionValueRef{scrlttr2}{firstfoot}{false}% \important{\OptionValueRef{scrlttr2}{firstfoot}{false}}% \IndexOption{firstfoot~=\PValue{false}}\ChangedAt{v2.97e}{\Class{scrlttr2}} -(see \autoref{sec:scrlttr2.firstpage}, -\DescPageRef{scrlttr2.option.firstfoot}), then the setting of +option (see \autoref{sec:scrlttr2.firstpage}, +\DescPageRef{scrlttr2.option.firstfoot}), the setting of \PLength{firstfootvpos} is ignored, and instead -\Length{paperheight}\IndexLength{paperheight} is applied. Thus, there remains -a mimimum bottom margin of length \Length{footskip}\IndexLength{footskip}.% -% +\Length{paperheight}\IndexLength{paperheight} is applied. There remains then a +minimum bottom margin of length \Length{footskip}\IndexLength{footskip}.% \EndIndexGroup @@ -1125,28 +1130,28 @@ a mimimum bottom margin of length \Length{footskip}\IndexLength{footskip}.% \PLength{firstfoothpos} \end{Declaration} \ChangedAt{v3.05}{\Class{scrlttr2}}% -A\textnote{Attention!} positive value of pseudo-length \PLength{firstfoothpos} -gives the distance between the letter footer and the left edge of the -paper. If the value is even greater than or equal to the paper width, -\Length{paperwidth}\IndexLength{paperwidth}, then the footer will be centered -horizontally to the note paper. But if the value is less than or equal to the -negative width of the paper, then the footer will be aligned left to the -typing area. - -Typical default for this value is \Length{maxdimen}\IndexLength{maxdimen}, -that is the maximum allowed value of a length. This results in horizontal -centering.% +A\textnote{Attention!} positive value of the \PLength{firstfoothpos} +pseudo-length specifies the distance from the left edge of the paper to the +letterhead page footer. If the value is greater than or equal to the paper +width, \Length{paperwidth}\IndexLength{paperwidth}, the footer is centred +horizontally on the letterhead page. But if the value is less than or equal to +the negative width of the paper, the footer is placed flush with the left edge +of the typing area. + +The typical default for this value is \Length{maxdimen}\IndexLength{maxdimen}, +which is the maximum possible value for a length. This results in horizontal +centring.% \EndIndexGroup \begin{Declaration} \PLength{firstfootwidth} \end{Declaration} -This pseudo-length gives the width of the letter's first page footer. The -value is set equal to that of the pseudo-length +This pseudo-length specifies the width of the footer of the first page of the +letter, that is the letterhead page. The value in the predefined \File{lco} +files\textnote{\File{lco} file}\Index{lco file=\File{lco} file} matches \PLength{firstheadwidth}\important{\PLength{firstheadwidth}}% -\IndexPLength{firstheadwidth} in the predefined -\File{lco}-files\textnote{\File{lco}-file}\Index{lco-file=\File{lco}-file}.% +\IndexPLength{firstheadwidth}.% % \EndIndexGroup % @@ -1160,9 +1165,9 @@ value is set equal to that of the pseudo-length \BeginIndexGroup \BeginIndex{}{variables} -\KOMAScript{} provides beside the feature of using predefined variable also -commands to define new variable or to manipulate the automatic usage of -variables in the business line\Index{business line}. +\KOMAScript{} provides commands not only to use predefined variables but also +to define new variables or to change their automatic use within the reference +line\Index{reference line}. \begin{Declaration} \Macro{newkomavar}\OParameter{description}\Parameter{name}% @@ -1171,56 +1176,56 @@ variables in the business line\Index{business line}. \Macro{defaultreffields}% \Macro{addtoreffields}\Parameter{name} \end{Declaration} -With \Macro{newkomavar} a new variable is defined. This variable is -addressed via \PName{name}. As an option you can define a -\PName{description} for the variable \PName{name}. In opposite to \PName{name} -the \PName{description} is not used to reference a variable. In fact the -\PName{description} defines an addition to the content of a variable, that may -be output similar to the variable content. - -Using the command \Macro{addtoreffields} you can add the variable \PName{name} -to the reference fields line\Index{business line} (see -\autoref{sec:scrlttr2.firstpage}, -\DescPageRef{scrlttr2.option.refline}). The \PName{description} and the -content of the variable are added at the end of the reference fields line. The -starred version \Macro{newkomavar*} is similar to the unstarred version, with -a subsequent call of the command \Macro{addtoreffields}. Thus, the starred -version automatically adds the variable to the reference fields line. +\Macro{newkomavar} defines a new variable. This variable is referenced as +\PName{name}. Optionally, you can define a \PName{description} for the +\PName{name} variable. Unlike the \PName{name}, the \PName{description} is not +used to reference a variable. Instead, the \PName{description} acts as a +supplement to the content of a variable that can be printed as a label along +with its content. + +You can use the \Macro{addtoreffields} command to add the \PName{name} +variable to the reference line\Index{reference line} (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.refline}). The +\PName{description} and the content of the variable are added to the end of +the reference line. The starred version \Macro{newkomavar*} is similar to the +unstarred version but also calls the \Macro{addtoreffields} command. Thus, the +starred version automatically adds the variable to the reference line. \begin{Example} - Suppose you need an additional field for direct dialling. You can - define this field either with + Suppose you need an additional field for a telephone extension in the + reference line. You can define this field with \begin{lstcode} - \newkomavar[Direct dialling]{myphone} + \newkomavar[Extension]{myphone} \addtoreffields{myphone} \end{lstcode} or more concisely with \begin{lstcode} - \newkomavar*[direct dialling]{myphone} + \newkomavar*[Extension]{myphone} \end{lstcode} \end{Example} -When\textnote{Attention!} you define a variable for the reference fields line -you should always give it a description. - -With the command \Macro{removereffields} all variables in the reference field -line can be removed. This also includes the predefined variables of the -class. The reference fields line is then empty. This can be useful, for -example, if you wish to change the order of the variables in the reference -fields line. - -The command \Macro{defaultreffields} acts to reset the reference -fields line to its predefined format. In doing so, all custom-defined -variables are removed from the reference fields line. - -The\textnote{Attention!} date should not be added to the reference fields line -using \Macro{addtoreffields}. Instead option \Option{date}% -\important[i]{\OptionValueRef{scrlttr2}{refline}{dateleft}\\ - \OptionValueRef{scrlttr2}{refline}{dateright}\\ - \OptionValueRef{scrlttr2}{refline}{nodate}}% -\IndexOption{refline~=\PValue{dateleft}}% -\IndexOption{refline~=\PValue{dateright}}% -\IndexOption{refline~=\PValue{nodate}} should be used to select the date left, -right or not at the business line. This option also will change the position -of the date if no reference fields will be output.% +When\textnote{Attention!} you define a variable for the reference line, you +should always give it a description. + +You can use the \Macro{removereffields} command to remove all variables from +the reference field. This includes the predefined variables of the class. The +reference line is then empty. This can be useful, for example, if you wish to +change the order of the variables in the reference fields line. + +The \Macro{defaultreffields} command resets the reference fields line to its +predefined format. In doing so, all custom-defined variables are removed from +the reference fields line. + +You\textnote{Attention!} should not add the date to the reference line with +the \Macro{addtoreffields} command. Instead you should use the +\DescRef{scrlttr2.option.refline}% +\important{\OptionValueRef{scrlttr2}{refline}{dateleft}\\ +\OptionValueRef{scrlttr2}{refline}{dateright}\\ +\OptionValueRef{scrlttr2}{refline}{nodate}}% +\IndexOption{refline~=\textKValue{dateleft}}% +\IndexOption{refline~=\textKValue{dateright}}% +\IndexOption{refline~=\textKValue{nodate}} option to select whether the date +should appear on the left or right side of the reference line, or not at all. +These settings also affect the position of the date when no reference line is +used.% % \EndIndexGroup @@ -1229,22 +1234,22 @@ of the date if no reference fields will be output.% \Macro{usekomavar}\OParameter{command}\Parameter{name}% \Macro{usekomavar*}\OParameter{command}\Parameter{name} \end{Declaration} -The commands \DescRef{scrlttr2.cmd.usekomavar} and -\DescRef{scrlttr2.cmd.usekomavar*} are, similarly to all commands where a -starred version exists or which can take an optional argument, not fully -expandable. Nevertheless, if used within -\DescRef{scrlttr2.cmd.markboth}\IndexCmd{markboth}, +The \DescRef{scrlttr2.cmd.usekomavar} and \DescRef{scrlttr2.cmd.usekomavar*} +commands are, like all commands where a starred version exists or which can +take an optional argument, not fully expandable. Nevertheless, if you use them +within \DescRef{scrlttr2.cmd.markboth}\IndexCmd{markboth}, \DescRef{scrlttr2.cmd.markright}\IndexCmd{markright} or similar commands, you -need not insert a \Macro{protect}\IndexCmd{protect} before using them. Of -course this is also true for -\DescRef{scrlayer-scrpage.cmd.markleft}\IndexCmd{markleft} if using package -\Package{scrlayer-scrpage}. However\textnote{Attention!}, these kinds of -commands can not be used within commands like -\Macro{MakeUppercase}\important{\Macro{MakeUppercase}}\IndexCmd{MakeUppercase} -which directly influence their argument. To avoid this problem you may use -commands like \Macro{MakeUppercase} as an optional argument to -\Macro{usekomavar} or \Macro{usekomavar*}. Then you will get the uppercase -content of a variable using: +need not insert \Macro{protect}\IndexCmd{protect} beforehand. Of course +this is also true for +\DescRef{scrlayer-scrpage.cmd.markleft}\IndexCmd{markleft} if you use the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage} package. These\textnote{Attention!} commands +cannot be used within commands that directly affect their argument, such as +\Macro{MakeUppercase}\important{\Macro{MakeUppercase}}% +\IndexCmd{MakeUppercase}. To avoid this problem you can use commands like +\Macro{MakeUppercase} as an optional argument to \Macro{usekomavar} or +\Macro{usekomavar*}. Then you will get the upper-case content of a variable +with \begin{lstcode}[escapeinside=`'] \usekomavar[\MakeUppercase]{`\PName{Name}'} \end{lstcode} @@ -1256,194 +1261,110 @@ content of a variable using: \Macro{ifkomavarempty}\Parameter{name}\Parameter{true}\Parameter{false}% \Macro{ifkomavarempty*}\Parameter{name}\Parameter{true}\Parameter{false} \end{Declaration} -It is important to know that the content or description of the variable will -be expanded as far as this is possible with \Macro{edef}. If this results in -spaces or unexpandable macros like \Macro{relax}, the result will be not empty -even where the use of the variable would not result in any visible output. - -Both\textnote{Attention!} variants of the command also must not be used as the -argument of \Macro{MakeUppercase}\IndexCmd{MakeUppercase} or other commands -which have similar effects to their arguments However, they are robust enough -to be used as the argument of, e.\,g., \DescRef{scrlttr2.cmd.markboth} or -\Macro{footnote}.% +It is important to know that the content of the variable will be expanded as +far as this is possible with \Macro{edef}. If this results in spaces or +unexpandable macros like \Macro{relax}, the result will be not empty even +where the use of the variable would not result in any visible output. + +Once\textnote{Attention!} again, this command cannot be used as the argument +of \Macro{MakeUppercase}\IndexCmd{MakeUppercase} or similar commands However, +it is robust enough to be used as the argument of +\DescRef{scrlttr2.cmd.markboth} or \DescRef{scrlttr2.cmd.footnote}, for +example.% % \EndIndexGroup % \EndIndexGroup -\section{Differences in the Page Styles of \Package{scrletter}} +\section{Additional Information about Page Styles} \seclabel{pagestyleatscrletter} \BeginIndexGroup \BeginIndex{}{page>style} -As described in \autoref{sec:scrlttr2.pagestyle}, the page style -\PageStyle{headings} shows the content of variables \DescRef{scrlttr2.variable.nexthead} and -\DescRef{scrlttr2.variable.nextfoot}. Page style \PageStyle{headings} has already another -meaning in the \KOMAScript{} classes \Class{scrbook}, \Class{scrreprt}, and -\Class{scrartcl}. Therefore \Package{scrletter} defines a new pair of page -styles (see \autoref{sec:scrlayer-scrpage-experts.pagestyle.pairs}, -\autopageref{sec:scrlayer-scrpage-experts.pagestyle.pairs}). The definition -is done using package -\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage}. - -Hence, you cannot use \Package{scrletter} with the outdated packages -\Package{scrpage2}\IndexPackage{scrpage2} and -\Package{scrpage}\IndexPackage{scrpage}. Same applies to -\Package{fancyhdr}\IndexPackage{fancyhdr} that is in general not recommended -for use with \KOMAScript. Additionally, internally loading package -\Package{scrlayer-scrpage} automatically activates page style -\PageStyle{scrheadings}\IndexPagestyle{scrheadings}. This activation -changes page styles \PageStyle{headings} and \PageStyle{plain} into aliases of -\PageStyle{scrheadings} and \PageStyle{plain.scrheadings}. So these page -styles are also controlled by \Package{scrlayer-scrpage}. - -\begin{Declaration} - \PageStyle{letter} - \PageStyle{plain.letter} - \DescRef{scrlttr2.variable.nexthead} - \DescRef{scrlttr2.variable.nextfoot} -\end{Declaration} -Package \Package{scrletter} defines the pair of page style \PageStyle{letter} -using \Package{scrlayer-scrpage} to become independent from the page styles of -the document class. Variables \DescRef{scrlttr2.variable.nexthead} and -\DescRef{scrlttr2.variable.nextfoot} are used by \Package{scrletter}'s -\PageStyle{letter} in the same way as for \Class{scrlttr2}'s -\PageStyle{headings}. The corresponding \PageStyle{plain} page style is also -similar to \Class{scrlttr2}'s page style \PageStyle{plain}. Notably the -position of the page number depends on option -\DescRef{scrlttr2.option.pagenumber}\IndexOption{pagenumber} (see -\DescPageRef{scrlttr2.option.pagenumber}).% -\EndIndexGroup - - -\begin{Declaration} - \Option{headsepline}% - \Option{footsepline} -\end{Declaration} -Because of the different internal approach of \Package{scrletter}, the options -\Option{headsepline}\important[i]{\Option{headsepline}\\% - \Option{footsepline}} and \Option{footsepline} differ slightly from -class \Class{scrlttr2}, because they are controlled by package -\Package{scrlayer-scrpage}. Especially the horizontal lines in page head and -foot of the \PageStyle{plain} page style depend on the options of -\Package{scrlayer-scrpage}. See -\autoref{sec:scrlayer-scrpage.pagestyle.content}, -\DescPageRef{scrlayer-scrpage.option.headsepline} and -\DescPageRef{scrlayer-scrpage.option.plainheadsepline} for information -about those options.% -\EndIndexGroup - - -\begin{Declaration} - \Macro{pagemark}% - \Macro{letterpagemark} -\end{Declaration} -The \KOMAScript{} classes already define and use \Macro{pagemark}. So when -\Package{scrletter} is loaded, it cannot simply redefine \Macro{pagemark} to -add the prefix ``Page'' using \Macro{pagename}, because this would not only -influence the pagination of the letter pages but the pagination of the whole -document. Therefore\ChangedAt{v3.17}{\Package{scrletter}} \Package{scrletter} -defines a new command \Macro{letterpagemark} with the prefix and lets -\Macro{pagemark} become \Macro{letterpagemark} in -\Macro{begin}\PParameter{letter} until the end of the letter only. If you want -to redefine \Macro{pagemark} for the whole document including the letter -pages, you have to add -\begin{lstcode} - \let\letterpagemark\pagemark -\end{lstcode} -just after the normal redefinition of \Macro{pagemark}. This add-on also will -not violate anything if you later decide to switch from package -\Package{scrletter} to class \Class{scrlttr2}. Note that the class -\Class{scrlttr2} does not provide or use \Macro{letterpagemark}.% -\EndIndexGroup -% +\LoadNonFree{scrlttr2-experts}{0}% \EndIndexGroup - -\section{Differences in the Handling of \File{lco}-Files in - \Package{scrletter}} +\iffalse% Wurde bereits in Kapitel 4.21 behandelt +\section{Differences in How \Package{scrletter} Handles \File{lco} Files} \seclabel{lcoatscrletter} \BeginIndexGroup \BeginIndex{File}{lco} -\BeginIndex{}{letter>class option}% -\BeginIndex{}{letter class option}% -\BeginIndex{}{lco-file=\File{lco}-file} +\BeginIndex{}{lco file=\File{lco} file} -As\ChangedAt{v3.15}{\Package{scrletter}} shown in -\autoref{sec:scrlttr2.lcoFile}, \Class{scrlttr2} can load \File{lco}-files via -the optional argument of \Macro{documentclass}. Package \Package{scrletter} +As\ChangedAt{v3.15}{\Package{scrletter}} explained in +\autoref{sec:scrlttr2.lcoFile}, \Class{scrlttr2} can load \File{lco} files via +the optional argument of \Macro{documentclass}. The \Package{scrletter} package does not support this. \begin{Declaration} \Macro{LoadLetterOption}\Parameter{name}% \Macro{LoadLetterOptions}\Parameter{list of names} \end{Declaration} -For \Class{scrlttr2} it is only recommended to load \File{lco}-files using +For \Class{scrlttr2}, load \File{lco} files with \DescRef{scrlttr2.cmd.LoadLetterOption} or -\DescRef{scrlttr2.cmd.LoadLetterOptions}. With \Package{scrletter} you must -use these commands to load \File{lco}-files. Of course, you can use these -commands at the earliest after loading \Package{scrletter}.% +\DescRef{scrlttr2.cmd.LoadLetterOptions} is only a recommendation. For +\Package{scrletter}, it is mandatory. Of course, you can only load the +\File{lco} files after you load \Package{scrletter}. +% \EndIndexGroup % \EndIndexGroup +\fi -\section{\File{lco}-Files for Experienced Users} +\section{\File{lco} Files for Experienced Users} \seclabel{lcoFile} \BeginIndexGroup -\BeginIndex{File}{lco}% -\BeginIndex{}{lco-file=\File{lco}-file}% - -\BeginIndex{}{paper>size>limitation}% -Even though each paper size, that may be set up using package -\Package{typearea}, may be also used with \Class{scrlttr2}, the result of the -first page may be unwanted with some of those page sizes. The conception of -the class is not the reason for this, but the fact, that there are mainly -parameter sets for ISO~A4 paper. Unfortunately their are not any universal -rules, to calculate, e.\,g., the position of the address field or similar for -every available paper sizes. But it is possible to make parameter sets for any -paper size that is needed.% -% -\EndIndex{}{paper>size>limitation}% - - -\subsection{Survey of Paper Size} -\seclabel{papersize} - -At present there exist only parameter sets and \File{lco}-files for A4-sized -or letter-sized paper. Nevertheless, class \Class{scrlttr2} supports many more -paper sizes. Because of this it's necessary to survey setting up the correct -paper size. +\BeginIndex{File}{lco} +\BeginIndex{}{lco file=\File{lco} file} + +\BeginIndexGroup% +\BeginIndex{}{paper>format}% +Although you can use any paper size that the +\hyperref[cha:typearea]{\Package{typearea}}% +\IndexPackage{typearea} package can configure, the output of the letterhead +page may produce undesirable results with some formats. Unfortunately, there +are no general rules to calculate the position of the address fields and the +like for every available paper size. Instead, different parameter sets are +needed for different paper sizes.% + +%\subsection{Verifying the Paper Size} +%\seclabel{papersize} + +At present parameter sets and \File{lco} files exist only for A4-sized and +letter-sized paper. Theoretically, however, the \Class{scrlttr2} class can +support many more paper sizes. Therefore, it's necessary to verify that the +correct paper size is used. This is even more true if you use +\Package{scrletter}, since the paper size depends on the class you use. \begin{Declaration} \Macro{LetterOptionNeedsPapersize}% \Parameter{option name}\Parameter{paper size} \end{Declaration} -In order that you will at least be warned when using another \PName{paper - size}, you will find a \Macro{LetterOptionNeedsPapersize} command in every -\File{lco}-file distributed with {\KOMAScript}. The first argument is the name -of the \File{lco}-file without the ``\File{.lco}'' suffix. The second argument -is the paper size for which the \File{lco}-file is designed. +To provide at least a warning when another \PName{paper size} is used, you can +find a \Macro{LetterOptionNeedsPapersize} command in every \File{lco} file +distributed with {\KOMAScript}. The first argument is the name of the +\File{lco} file without the ``\File{.lco}'' suffix. The second argument is the +paper size for which the \File{lco} file is designed. If several \File{lco} files are loaded in succession, a \Macro{LetterOptionNeedsPapersize} command can be contained in each of them, -but the \DescRef{scrlttr2.cmd.opening} command will only check the last given \PName{paper - size}. As shown in the following example, an experienced user can thus -easily write \File{lco}-files with parameter sets for other paper sizes. +but the \DescRef{scrlttr2.cmd.opening} command will only check the last given +\PName{paper size}. As the following example shows, an experienced user can +thus easily write \File{lco} files with parameter sets for other paper sizes. \iffalse% Umbruchoptimierung -If you do not plan to set up such \File{lco}-files yourself, you may just +If you do not plan to set up such \File{lco} files yourself, you can just forget about this option and skip the example.% \fi \begin{Example} - Suppose you use A5-sized paper in normal, i.\,e., upright or portrait, - orientation for your letters. We further assume that you want to put them - into standard C6 window envelopes. In that case, the position of the address - field would be the same as for a DIN standard letter on A4-sized paper. The - main difference is that A5 paper needs only one fold. So you want to disable - the topmost and bottommost folding marks. If their would not be options for - this, the easiest way to achieve this would be to place the marks outside of - the paper area. + Suppose you use A5-sized paper in normal, that is upright or portrait, + orientation for your letters. Let's assume that you want to put them into + standard C6 window envelopes. In that case, the position of the address + field would be the same as for a standard letter on A4-sized paper. The main + difference is that A5 paper needs only one fold. So you want to disable the + top and bottom fold marks. You can do this, for example, by placing the + marks outside the paper area. \begin{lstcode} \ProvidesFile{a5.lco} [2002/05/02 letter class option] @@ -1451,66 +1372,66 @@ forget about this option and skip the example.% \@setplength{tfoldmarkvpos}{\paperheight} \@setplength{bfoldmarkvpos}{\paperheight} \end{lstcode} - Besides this, the placement of the foot, that is, the pseudo-length - \PLength{firstfootvpos}, must be adjusted. It is left to the reader to find - an appropriate value. When using such an \File{lco} file, you must only take - care that other \File{lco} file options, like \File{SN}, are declared before - loading ``\File{a5.lco}''. -\iffalse% Umbruchoptimierung - Does this seem too complicated? Only before you have used it the first - time. Anyway, how often do you write letters not using your standard formats - for A4-size or letter-size paper? -\fi% + Of course, it would be more elegant to deactivate the marks with the + \DescRef{scrlttr2.option.foldmarks} option. In addition, you must adjust the + position of the footer, that is, the \PLength{firstfootvpos} pseudo-length. + I leave it to the reader to find an appropriate value. When using such an + \File{lco} file, you must declare other \File{lco} file options like + \File{SN} before you load ``\File{a5.lco}''. \end{Example} % -\EndIndexGroup +\EndIndexGroup% +\EndIndexGroup% +\vskip-\ht\strutbox% Wegen Beispiel am Ende der Erklaerung -\subsection{Visualization of Positions} -\seclabel{visualize} -\BeginIndexGroup -\BeginIndex{Option}{visualize} - -If someone develops a new \File{lco}-file, e.\,g., to adapt the positions of -the several fields of the note paper because of own wishes or because it's -simply necessary, then it often will be useful to make at least some elements -directly visual. This is the sense of \File{lco}-file -\File{visualize.lco}\ChangedAt{v3.04}{\Class{scrlttr2}}. This file may be -loaded like each other \File{lco}-file. But in difference to other -\File{lco}-files it has to be done in the document preamble and it's not -possible to switch off the effects of that \File{lco}-file. This -\File{lco}-file uses packages \Package{eso-pic}\IndexPackage{eso-pic}% -\important[i]{\Package{eso-pic}\\\Package{graphicx}} -and \Package{graphicx}\IndexPackage{graphicx}, that are not part of +%\subsection{Visualizing Positions} +%\seclabel{visualize} +%\BeginIndexGroup +\begin{Declaration} + \File{visualize.lco} +\end{Declaration} +\BeginIndex{Option}{visualize}% +If you develop your own \File{lco} file, for example to modify the positions +of various fields on the letterhead page because your own desires or +requirements, it is helpful if you can make at least some elements directly +visible. The \File{lco} file +\File{visualize.lco}\ChangedAt{v3.04}{\Class{scrlttr2}} exists for this +purpose. You can load this file as you would any other \File{lco} file. But +this \emph{letter class options} file must be loaded in the document preamble, +and its effects cannot be deactivated. The \File{lco} file uses the +\Package{eso-pic}\IndexPackage{eso-pic}% +\important[i]{\Package{eso-pic}\\\Package{graphicx}} and +\Package{graphicx}\IndexPackage{graphicx} packages, which are not part of \KOMAScript. \begin{Declaration} \Macro{showfields}\Parameter{field list} \end{Declaration} -This command activates the visualization of note paper fields. Argument -\PName{field list} is a comma separated list of fields that should be -visualized. Following are the supported fields: +This command makes the space occupied by the fields on the letterhead page +visible. The \PName{field list} argument is a comma-separated list of fields +to be shown. The following fields are supported: \begin{labeling}[~--]{\PValue{location}} -\item[\PValue{test}] is a test field of size 10\Unit{cm} by 15\Unit{cmd} with - position 1\Unit{cm} down and right from the topmost and leftmost edges of - the paper. This field exists for debugging purpose. It may be used as an - measure comparison in the case, that the measures will be adulterated while - printing. -\item[\PValue{head}] is the header area of the note paper. This area has an - open bottom. -\item[\PValue{foot}] is the footer area of the note paper. This area has an - open top. +\item[\PValue{test}] is a 10\Unit{cm} by 15\Unit{cm} test field, 1\Unit{cm} + from the top and left edges of the paper. This field exists for debugging. + You can use it as a benchmark to check whether the measurements have been + distorted during the creation of the document. +\item[\PValue{head}] is the header area of the letterhead page. This field + is open at the bottom. +\item[\PValue{foot}] is the footer area of the letterhead page. This field is + open at the top. \item[\PValue{address}] is the address window area used by window envelopes. -\item[\PValue{location}] is the field of the sender's extension. -\item[\PValue{refline}] is the business line. This are has an open bottom. +\item[\PValue{location}] is the field for the extra sender information. +\item[\PValue{refline}] is the reference line. This field is open at the + bottom. \end{labeling}% \BeginIndex{FontElement}{field}\LabelFontElement{field}% -The color of the visualization may be changed using -commands\DescRef{scrlttr2.cmd.setkomafont} und -\DescRef{scrlttr2.cmd.addtokomafont} (see \autoref{sec:scrlttr2.textmarkup}, -\DescPageRef{scrlttr2.cmd.setkomafont}) with the element -\FontElement{field}\important{\FontElement{field}}. Default is +You can change the colour of the visualisation with +the\DescRef{scrlttr2.cmd.setkomafont} and \DescRef{scrlttr2.cmd.addtokomafont} +(see \autoref{sec:scrlttr2.textmarkup}, +\DescPageRef{scrlttr2.cmd.setkomafont}) commands using the +\FontElement{field}\important{\FontElement{field}} element. The default is \Macro{normalcolor}.% \EndIndex{FontElement}{field}% % @@ -1518,20 +1439,21 @@ commands\DescRef{scrlttr2.cmd.setkomafont} und \begin{Declaration} - \Macro{setshowstyle}\Parameter{visualization style}% + \Macro{setshowstyle}\Parameter{style}% \Macro{edgesize} \end{Declaration} -The default for the visualization of single areas are -frames\important{\PValue{frame}} around the areas. Areas with open top or -bottom are not framed completely but have an open edge with arrows at the end -of the ending lines. Alternatively\important{\PValue{rule}} the -\PName{visualization style} \PValue{rule} may be used. In this case a -background color will be used to visualize the areas. This does not differ open -and closed areas. Instead a minimal height will be used for open areas. The -third\important{\PValue{edges}} available \PName{visualization style} is -\PValue{edges}. This will mark the corners of the areas. The corner marks at -the open edge of open areas will be omitted. The size of two edges of the -corner marks are given by the macro \Macro{edgesize} with default 1\Unit{ex}.% +By default, \File{visualize.lco} indicates the individual areas with +frames\important{\PValue{frame}}, which corresponds to the \PName{style} +\PValue{frame}. Areas open at top or bottom are not completely framed but have +an open edge with with small arrows pointing up or down. +Alternatively\important{\PValue{rule}}, you can use the \PName{style} +\PValue{rule}. In this case, the area is highlighted by a background colour. +It isnot possible to distinguish open and closed areas. Instead a minimal +height will be used for open areas. The third\important{\PValue{edges}} +available \PName{style} is \PValue{edges}, which shows the corners of the +areas. The corner marks at the open edge of open areas will be omitted. The +size of two edges of the corner marks are given by the \Macro{edgesize} macro +with a default of 1\Unit{ex}.% \EndIndexGroup @@ -1544,60 +1466,55 @@ corner marks are given by the macro \Macro{edgesize} with default 1\Unit{ex}.% \Macro{showUScheck}\OParameter{instructions}% \Macro{unitfactor} \end{Declaration} -These commands may be used to output a graphics of an envelope. The envelope -of the graphic will be rotated by 90\textdegree{} and printed in measure~1:1 -to one document page. The addressee window will be generated automatically -using the current data of the address position of the note paper: -\PLength{toaddrvpos}, \PLength{toaddrheight}, \PLength{toaddrwidth}, and -\PLength{toaddrhpos}. For this the differences \PName{h-offset} and -\PName{v-offset} of size of the folded letter sheet to the size of the -envelope, \PName{width} and \PName{height}, will be needed. If both values, -\PName{h-offset} and \PName{v-offset}, will be omitted using -\Macro{showenvelope}, then these will be calculated from the folding marks and -the paper size. - -Commands \Macro{showISOenvelope}, \Macro{showUScommercia}, and -\Macro{showUScheck} base on \Macro{showenvelope}. With \Macro{showISOenvelope} -ISO-envelopes with \PName{format} C4, C5, C5/6, DL (also known as C5/6) or C6 -may be generated. With \Macro{showUScommercial} an US-commercial envelope of -\PName{format} 9 or 10 may be generated. \Macro{showUScheck} may be used for -envelopes in format US-check. - -The \PName{instructions} may be used to print additional elements inside the -envelope. +If you have loaded \File{visualize.lco}, you can use these commands to output +a page with a drawing of an envelope. The envelope drawing is always rotated +by 90\textdegree{} on a separate page and printed in 1:1~scale. The addressee +window is generated automatically from the current data for the address +position of the letterhead page: \PLength{toaddrvpos}, \PLength{toaddrheight}, +\PLength{toaddrwidth}, and \PLength{toaddrhpos}. To do so requires knowing how +much smaller the folded letter pages are than the width and height of the +envelope. If you do not specify these two values, \PName{h-offset} and +\PName{v-offset}, when calling \Macro{showenvelope}, they are calculated from +the fold marks and the paper size itself. + +The \Macro{showISOenvelope}, \Macro{showUScommercial}, and \Macro{showUScheck} +commands are based on \Macro{showenvelope}. With \Macro{showISOenvelope}, you +can create ISO-envelopes in C4, C5, C5/6, DL (also known as C5/6) or C6 +\PName{format}. With \Macro{showUScommercial}, you can create a US commercial +envelope in the 9 or 10 \PName{format}. You can use \Macro{showUScheck} for +envelopes in US check format. \BeginIndex{FontElement}{letter}\LabelFontElement{letter}% -The position of the letter sheet will be signed with dash lines inside the -envelope. The color of this dash lines may be changed using commands -\DescRef{scrlttr2.cmd.setkomafont} und \DescRef{scrlttr2.cmd.addtokomafont} +The position of the letterhead page inside the envelope is indicated with +dashed lines. You can change the colour of these lines with the +\DescRef{scrlttr2.cmd.setkomafont} and \DescRef{scrlttr2.cmd.addtokomafont} (see \autoref{sec:scrlttr2.textmarkup}, -\DescPageRef{scrlttr2.cmd.setkomafont}) with element -\FontElement{letter}\important{\FontElement{letter}}. Default is +\DescPageRef{scrlttr2.cmd.setkomafont}) using the +\FontElement{letter}\important{\FontElement{letter}} element. The default is \Macro{normalcolor}.% -% \EndIndex{FontElement}{letter}% \BeginIndex{FontElement}{measure}\LabelFontElement{measure}% -The envelope will be dimensioned automatically. The color of the dimensioning -may be changed using commands \DescRef{scrlttr2.cmd.setkomafont} und -\DescRef{scrlttr2.cmd.addtokomafont} (see \autoref{sec:scrlttr2.textmarkup}, -\DescPageRef{scrlttr2.cmd.setkomafont}) with element -\FontElement{measure}\important{\FontElement{measure}}. Default is -\Macro{normalcolor} The dimensioning will be done in multiply of -\Length{unitlength} with accuracy of $1/\Macro{unitfactor}$. Nevertheless -accuracy of the \TeX{} arithmetic also limits the accuracy of -dimensioning. Default is 1. The \Macro{unitfactor} may be changed using -\Macro{renewcommand}.% +The envelope drawing will be provided with dimensions automatically. You can +change the colour of these dimension labels with the commands +\DescRef{scrlttr2.cmd.setkomafont} and \DescRef{scrlttr2.cmd.addtokomafont} +(see \autoref{sec:scrlttr2.textmarkup}, +\DescPageRef{scrlttr2.cmd.setkomafont}) using the +\FontElement{measure}\important{\FontElement{measure}} element. The default is +\Macro{normalcolor}. The dimensions are given in multiples of +\Length{unitlength}, with an accuracy of $1/\Macro{unitfactor}$, where the +accuracy of \TeX{} arithmetic is the actual limits. The default is 1. You can +redefine \Macro{unitfactor} using \Macro{renewcommand}.% \EndIndex{FontElement}{measure}% \begin{Example} - An example letter in format ISO-A4 will be produced. The supported fields - should be visualized with yellow frame lines. Additionally the position of - the window of an envelope with size DL should be checked with a - graphics. The measure lines of the dimensioning should be red and the - measure numbers should use a small font. The accuracy of the dimensioning - should be 1\Unit{mm}. The dashed note paper sheet in the envelope should be - colored green. + You are generating a sample letter using the ISO-A4 format. The supported + fields should be marked with yellow borders to check their position. + Furthermore, the position of the window for a DL-size envelope should be + checked with drawing. The dimension lines in this drawing should be red, and + the numbers should use a smaller font, with the dimensions printed in cm + with an accuracy of 1\Unit{mm}. The dashed letterhead page in the envelope + should be coloured green. \begin{lstcode} \documentclass[visualize]{scrlttr2} \usepackage{xcolor} @@ -1605,16 +1522,17 @@ dimensioning. Default is 1. The \Macro{unitfactor} may be changed using \setkomafont{measure}{\color{red}\small} \setkomafont{letter}{\color{green}} \showfields{head,address,location,refline,foot} - \usepackage[ngerman]{babel} + \usepackage[british]{babel} \usepackage{lipsum} \begin{document} - \setkomavar{fromname}{Peter Musterfrau} - \setkomavar{fromaddress}{Hinter dem Tal 2\\ - 54321 Musterheim} + \setkomavar{fromname}{Joe Public} + \setkomavar{fromaddress}{2 Valley\\ + SAMPLEBY\\ + ZY32 1XW} \begin{letter}{% - Joana Public\\ - Hillside 1\\ - 12345 Public City% + 1 Hillside\\ + SAMPLESTEAD\\ + WX12 3YZ% } \opening{Hello,} \lipsum[1] @@ -1625,14 +1543,14 @@ dimensioning. Default is 1. The \Macro{unitfactor} may be changed using \showISOenvelope{DL} \end{document} \end{lstcode} - This will show the note paper on the first and the envelope graphic on the - second document page. + This will show the letterhead page as the first page and the drawing of the + envelope on the second page. \end{Example} -Please note, that inauspicious combinations of \Length{unitlength} and -\Macro{unitfactor} may provoke \TeX{} errors like \emph{arithmetic overflow} -very soon. Also shown measure numbers may differ a little bit from the real -value. Both are not mistakes of \Option{visualize} but simple implementation +Note that poorly chosen combinations of \Length{unitlength} and +\Macro{unitfactor} can quickly lead to a \TeX{} \emph{arithmetic overflow} +error. The dimension numbers shown may also differ slightly from the actual +values. Neither are errors in \Option{visualize} but merely implementation limitations of \TeX. % \EndIndexGroup @@ -1645,161 +1563,87 @@ limitations of \TeX. \section{Language Support} \seclabel{languages}% \BeginIndexGroup -\BeginIndex{}{language}% - -The document class \Class{scrlttr2} supports many languages. These include -German\Index{language>German} (\PValue{german} for old German orthography, -\PValue{ngerman} for the new orthography, \PValue{austrian} for Austrian with -old German orthography, and -\PValue{naustrian}\ChangedAt{v3.09}{\Class{scrlttr2}} for Austrian with new -orthography), English\Index{language>English} (\PValue{english} without -specification as to whether American or British should be used, -\PValue{american} and \PValue{USenglish} for American, and \PValue{british} -and \PValue{UKenglish} for British), French\Index{language>French}, -Italian\Index{language>Italian}, Spanish\Index{language>Spanish}, -Dutch\Index{language>Dutch}, Croatian\Index{language>Croatian}, -Finnish\Index{language>Finnish}, -Norsk\Index{language>Norsk}\ChangedAt{v3.02}{\Class{scrlttr2}}, and -Swedish\Index{language>Swedish}\ChangedAt{v3.08}{\Class{scrlttr2}}. - -If the package \Package{babel}\IndexPackage{babel} (see -\cite{package:babel}) is used, one can switch between languages with -the command \Macro{selectlanguage}\Parameter{language}. Other -packages like \Package{german}\IndexPackage{german} (see -\cite{package:german}) and \Package{ngerman}\IndexPackage{ngerman} -(see \cite{package:ngerman}) also define this command. As a rule -though, the language selection takes place already as a direct -consequence of loading such a package. +\BeginIndex{}{languages}% + +The \Class{scrlttr2} class and the \Package{scrletter} package support many +languages. These include German\Index{language>German} (\PValue{german} for +the old German orthography, \PValue{ngerman} for the new orthography; +\PValue{austrian} for Austrian with the old German orthography, +\PValue{naustrian}\ChangedAt{v3.09}{\Class{scrlttr2}} for Austrian with the +new orthography; and \PValue{nswissgerman}\ChangedAt{v3.13}{\Class{scrlttr2}} +for Swiss German with the new orthogrphy, \PValue{swissgerman} for Swiss +German with the old orthography), English\Index{language>English} (among +others, \PValue{english} without specification as to whether American or +British should be used, \PValue{american} and \PValue{USenglish} for American +English, and \PValue{british} and \PValue{UKenglish} for British English), +French\Index{language>French}, Italian\Index{language>Italian}, +Spanish\Index{language>Spanish}, Dutch\Index{language>Dutch}, +Croatian\Index{language>Croatian}, Finnish\Index{language>Finnish}, +Norwegian\Index{language>Norwegian}\ChangedAt{v3.02}{\Class{scrlttr2}}, +Swedish\Index{language>Swedish}\ChangedAt{v3.08}{\Class{scrlttr2}}, +Polish\ChangedAt{v3.13}{\Class{scrlttr2}}, +Czech\ChangedAt{v3.13}{\Class{scrlttr2}}, and Slovak. + +You can switch languages using the \Package{babel}\IndexPackage{babel} package +(see \cite{package:babel}) with the \Macro{selectlanguage}\Parameter{language} +command. Other packages like \Package{german}\IndexPackage{german} (see +\cite{package:german}) and \Package{ngerman}\IndexPackage{ngerman} (see +\cite{package:ngerman}) also define this command. As a rule though, the +language selection occurs immediately as a direct consequence of loading such +a package. \iffalse% Umbruchkorrekturtext -Further information can be obtained in the documentation of the relevant -packages. +For details, please refer to the documentation of the relevant packages. \fi -There\textnote{Attention!} is one thing more to mention about language -packages. The package -\Package{french}\IndexPackage{french}\important{\Package{french}} (see -\cite{package:french}) redefines not only the terms of -\autoref{tab:scrlttr2-experts.languageTerms}, but also other, for instance -some versions of that package even redefine the command -\DescRef{scrlttr2.cmd.opening}, since the package assumes that the definition -of the standard \Class{letter} is used. With \Class{scrlttr2} this is not the -case, therefore the package \Package{french} destroys the definition in -\Class{scrlttr2} and does not work correctly with \KOMAScript. The author -views this is a fault in the \Package{french} package. - -If one utilizes the \Package{babel}\IndexPackage{babel} package in order to -switch to language \PValue{french} while the package -\Package{french}\IndexPackage{french} is simultaneously installed, then the -same problems may likely occur, since \Package{babel} employs definitions -from the \Package{french} package. -% -\iffalse% Umbruchergaenzungstext -If the package \Package{french} is not -installed then there are no problems. Aimilarly, there is no problem if for -\Package{babel} instead of \PValue{french} other languages like -\PValue{acadian}, \PValue{canadien}, \PValue{francais} or \PValue{frenchb} are -chosen. +There\textnote{Attention!} is one more point to note about language-switching +packages. The +\Package{french}\IndexPackage{french}\important{\Package{french}} package (see +\cite{package:french}) makes changes well beyond redefining the terms in +\autoref{tab:scrlttr2-experts.languageTerms}. For instance, it redefines the +\DescRef{scrlttr2.cmd.opening} command, since the package simply assumes that +\DescRef{scrlttr2.cmd.opening} is always defined as it is in the standard +\Class{letter} class. This, however, is not the case with \KOMAScript{}. The +\Package{french} package thus overwrites the definition and does not work +correctly with \KOMAScript. I regard this as a fault in the \Package{french} +package which, although reported decades ago, was unfortunately never +eliminated. + +If you use the \Package{babel}\IndexPackage{babel} package to switch to +\PValue{french}, problems can occasionally occur. With \Package{babel}, +however, you can usually deactivate changes to a language in a targeted +manner.% +\iffalse% This is actually outdated! +\ If the package \Package{french} is not installed, the problem with + \Package{babel} does not arise. Similarly, the problem usually does not + exist when you use \Package{babel} with other varieties of French such as + \PValue{acadian}, \PValue{canadien}, \PValue{francais} or \PValue{frenchb} + instead of \PValue{french}. \fi -From \Package{babel} version 3.7j this problem only occurs when it is -indicated explicitly by means of an option that \Package{babel} should use the -\Package{french} package. If it cannot be ascertained that a new version of -\Package{babel} is being used, it is recommended to use +\iffalse% This is also outdated! + However, with \Package{babel} version 3.7j and above, this problem only occurs + if the option explicitly indicates that \Package{babel} should use the + \Package{french} package. +% +\iftrue + If you cannot be sure you are not using an old version of \Package{babel}, I + recommend you use \begin{lstcode} \usepackage[...,frenchb,...]{babel} \end{lstcode} -in order to select french. - -Other languages can possibly cause similar problems. Currently there -are no known problems with the \Package{babel} package for the -german language and the various english language selections. - -\begin{Declaration} - \Macro{captionsenglish}% - \Macro{captionsUSenglish}% - \Macro{captionsamerican}% - \Macro{captionsbritish}% - \Macro{captionsUKenglish}% - \Macro{captionsgerman}% - \Macro{captionsngerman}% - \Macro{captionsaustrian}% - \Macro{captionsnaustrian}% - \Macro{captionsfrench}% - \Macro{captionsitalian}% - \Macro{captionsspanish}% - \Macro{captionsdutch}% - \Macro{captionscroatian}% - \Macro{captionsfinnish}% - \Macro{captionsnorsk}% - \Macro{captionsswedish} -\end{Declaration} -If one switches the language of a letter then -using these commands the language-dependent terms from -\autoref{tab:scrlttr2-experts.languageTerms}, -\autopageref{tab:scrlttr2-experts.languageTerms} are redefined. If the used -language selection scheme does not support this then the commands -above can be used directly. -% -\EndIndexGroup - - -\begin{Declaration} - \Macro{dateenglish}% - \Macro{dateUSenglish}% - \Macro{dateamerican}% - \Macro{datebritish}% - \Macro{dateUKenglish}% - \Macro{dategerman}% - \Macro{datengerman}% - \Macro{dateaustrian}% - \Macro{datenaustrian}% - \Macro{datefrench}% - \Macro{dateitalian}% - \Macro{datespanish}% - \Macro{datedutch}% - \Macro{datecroatian}% - \Macro{datefinnish}% - \Macro{datenorsk}% - \Macro{dateswedish} -\end{Declaration} -The numerical representation of the date\Index{date} (see option -\DescRef{scrlttr2.option.numericaldate} in \autoref{sec:scrlttr2.firstpage}, -\DescPageRef{scrlttr2.option.numericaldate}) will be written depending on the -selected language. Some examples can be found in \autoref{tab:date}.% -% -\begin{table} -% \centering - \KOMAoptions{captions=topbeside}% - \setcapindent{0pt}% -% \caption - \begin{captionbeside}{Language-dependent forms of the date}[l] - \begin{tabular}[t]{ll} - \toprule - Command & Date example \\ - \midrule - \Macro{dateenglish} & 24/12/1993\\ - \Macro{dateUSenglish} & 12/24/1993\\ - \Macro{dateamerican} & 12/24/1993\\ - \Macro{datebritish} & 24/12/1993\\ - \Macro{dateUKenglish} & 24/12/1993\\ - \Macro{dategerman} & 24.\,12.\,1993\\ - \Macro{datengerman} & 24.\,12.\,1993\\ - \Macro{dateaustrian} & 24.\,12.\,1993\\ - \Macro{datefrench} & 24.\,12.\,1993\\ - \Macro{dateitalian} & 24.\,12.\,1993\\ - \Macro{datespanish} & 24.\,12.\,1993\\ - \Macro{datedutch} & 24.\,12.\,1993\\ - \Macro{datecroatian} & 24.\,12.\,1993.\\ - \Macro{datefinnish } & 24.12.1993.\\ - \Macro{datenorsk} & 24.12.1993\\ - \Macro{dateswedish} & 24/12 1993\\ - \bottomrule - \end{tabular} - \end{captionbeside} - \label{tab:date} -\end{table} -% -\EndIndexGroup + to select French. + \iffalse % + If necessary, you can still switch to French with + \Macro{selectlanguage}\PParameter{french}.% + \fi% +\fi +\fi + +\iftrue + It cannot be ruled out that similar problems will not occur with other + languages or packages. For German and English, however, there are currently + no known problems with the \Package{babel} package. +\fi \begin{Declaration} @@ -1822,30 +1666,67 @@ selected language. Some examples can be found in \autoref{tab:date}.% \Macro{wwwname}% \Macro{bankname} \end{Declaration} -The commands contain the language-dependent terms. These definitions can be -modified in order to support a new language or for private customization. -How\important[i]{% +These commands contain the language-dependent terms. These\important[i]{% \DescRef{scrbase.cmd.newcaptionname}\\ \DescRef{scrbase.cmd.renewcaptionname}\\ - \DescRef{scrbase.cmd.providecaptionname}} this can be done is described in -\autoref{sec:scrbase.languageSupport}. The definitions become active only at -\Macro{begin}\PParameter{document}. Therefore they are not available in the -{\LaTeX} preamble and cannot be redefined there. In -\autoref{tab:scrlttr2-experts.languageTerms} the default settings for -\Option{english} and \Option{ngerman} can be found.% + \DescRef{scrbase.cmd.providecaptionname}} definitions can be +modified to support a new language or for your private customization, as +described in +\autoref{sec:scrbase.languageSupport}. \KOMAScript{} sets these terms only in +\Macro{begin}\PParameter{document}. Therefore they are not available in the +preamble and cannot be redefined there. The default settings for +\Option{english} and \Option{ngerman} are listed in +\autoref{tab:scrlttr2-experts.languageTerms}.% +\EndIndexGroup +%\iffree{}{\clearpage}% Siehe Kommentar zur Tabelle + +\begin{Declaration} + \Macro{captionsacadian} + \Macro{captionsamerican} + \Macro{captionsaustralien} + \Macro{captionsaustrian} + \Macro{captionsbritish} + \Macro{captionscanadian} + \Macro{captionscanadien} + \Macro{captionscroatian} + \Macro{captionsczech} + \Macro{captionsdutch} + \Macro{captionsenglish} + \Macro{captionsfinnish} + \Macro{captionsfrancais} + \Macro{captionsfrench} + \Macro{captionsgerman} + \Macro{captionsitalian} + \Macro{captionsnaustrian} + \Macro{captionsnewzealand} + \Macro{captionsngerman} + \Macro{captionsnorsk} + \Macro{captionsnswissgerman} + \Macro{captionspolish} + \Macro{captionsslovak} + \Macro{captionsspanish} + \Macro{captionsswedish} + \Macro{captionsswissgerman} + \Macro{captionsUKenglish} + \Macro{captionsUSenglish} +\end{Declaration} +If you change the language of a letter, the language-dependent terms listed in +\autoref{tab:scrlttr2-experts.languageTerms}, +\autopageref{tab:scrlttr2-experts.languageTerms} are redefined using these +commands. If your language-switching package does not support this, you can +also use the above commands directly. % \begin{table} \begin{minipage}{\textwidth} -% \centering - \KOMAoptions{captions=topbeside}% - \setcapindent{0pt}% - %\caption - \begin{captionbeside}[{% - Default settings for language-dependent terms + \centering +% \KOMAoptions{captions=topbeside}% +% \setcapindent{0pt}% + \caption[{% + Defaults for language-dependent terms }]{% - Default settings for language-dependent terms using languages - \Option{english} and \Option{ngerman}, as long as language selection - packages have not been used% + Defaults for language-dependent terms for the languages + \Option{english} and \Option{ngerman}, if they are not already defined + by the packages used for language switching% \label{tab:scrlttr2-experts.languageTerms}% }[l] \begin{tabular}[t]{lll} @@ -1874,45 +1755,127 @@ How\important[i]{% \end{tabular} \deffootnote{1em}{1em}{1\ }% brutal aber effektiv \footnotetext[1000]{Normally these terms are defined by language - packages like \Package{babel}. In this case they are not redefined by - \Class{scrlttr2} and may differ from the table above.} - \end{captionbeside} + packages like \Package{babel}. In this case, \KOMAScript{} does not + redefine them. The actual wording may therefore differ and can + be found in the documentation for the language package used.} +% \end{captionbeside} \end{minipage} \end{table} % \EndIndexGroup +\iffree{}{\clearpage}% Umbruchkorrektur + +\begin{Declaration} + \Macro{dateacadian} + \Macro{dateamerican} + \Macro{dateaustralien} + \Macro{dateaustrian} + \Macro{datebritish} + \Macro{datecanadian} + \Macro{datecanadien} + \Macro{datecroatian} + \Macro{dateczech} + \Macro{datedutch} + \Macro{dateenglish} + \Macro{datefinnish} + \Macro{datefrancais} + \Macro{datefrench} + \Macro{dategerman} + \Macro{dateitalian} + \Macro{datenaustrian} + \Macro{datenewzealand} + \Macro{datengerman} + \Macro{datenorsk} + \Macro{datenswissgerman} + \Macro{datepolish} + \Macro{dateslovak} + \Macro{datespanish} + \Macro{dateswedish} + \Macro{dateswissgerman} + \Macro{dateUKenglish} + \Macro{dateUSenglish} +\end{Declaration} +Depending on the language used, the numerical representation of the date\Index{date} (see option +\DescRef{scrlttr2.option.numericaldate} in \autoref{sec:scrlttr2.firstpage}, +\DescPageRef{scrlttr2.option.numericaldate}) is formatted in various ways. +The exact format can be found in \autoref{tab:date}.% +\EndIndexGroup % \EndIndexGroup +\iffree{}{\clearpage}% Umbruchkorrektur zwecks Ausgabe der Tabellen +\begin{table}[!tp]% Umbruchoptimierung +% \centering + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% +% \caption + \begin{captionbeside}{Language-dependent Forms of the Date}[l] + \begin{tabular}[t]{ll} + \toprule + Command & Date Example \\ + \midrule + \Macro{dateacadian} & 24.\,12.\,1993\\ + \Macro{dateamerican} & 12/24/1993\\ + \Macro{dateaustralien}& 24/12/1993\\ + \Macro{dateaustrian} & 24.\,12.\,1993\\ + \Macro{datebritish} & 24/12/1993\\ + \Macro{datecanadian} & 1993/12/24\\ + \Macro{datecanadien} & 1993/12/24\\ + \Macro{datecroatian} & 24.\,12.\,1993.\\ + \Macro{dateczech} & 24.\,12.\,1993\\ + \Macro{datedutch} & 24.\,12.\,1993\\ + \Macro{dateenglish} & 24/12/1993\\ + \Macro{datefinnish } & 24.12.1993.\\ + \Macro{datefrancais} & 24.\,12.\,1993\\ + \Macro{datefrench} & 24.\,12.\,1993\\ + \Macro{dategerman} & 24.\,12.\,1993\\ + \Macro{dateitalian} & 24.\,12.\,1993\\ + \Macro{datenaustrian} & 24.\,12.\,1993\\ + \Macro{datenewzealand}& 24/12/1993\\ + \Macro{datengerman} & 24.\,12.\,1993\\ + \Macro{datenorsk} & 24.12.1993\\ + \Macro{datenswissgerman} & 24.\,12.\,1993\\ + \Macro{datepolish} & 24.\,12.\,1993\\ + \Macro{dateslovak} & 24.\,12.\,1993\\ + \Macro{datespanish} & 24.\,12.\,1993\\ + \Macro{dateswedish} & 24/12 1993\\ + \Macro{dateswissgerman} & 24.\,12.\,1993\\ + \Macro{dateUKenglish} & 24/12/1993\\ + \Macro{dateUSenglish} & 12/24/1993\\ + \bottomrule + \end{tabular} + \end{captionbeside} + \label{tab:date} +\end{table} +% +\section{Obsolete Commands in \Class{scrlttr2}} +\seclabel{obsolete} +\BeginIndexGroup + +\LoadNonFree{scrlttr2-experts}{1} +\EndIndexGroup +% +\iffalse% Es wird Zeit das komplett rauszuwerfen! \section{From Obsolete \Class{scrlettr} to Current \Class{scrlttr2}} \seclabel{fromscrlettr} -With\textnote{Attention!} the June 2002 release of \Class{scrlttr2} (see -\autoref{cha:scrlttr2}) the old letter class \Class{scrlettr} became -obsolete. It is recommended not to use that class for new applications. There -is no more active development of the old letter class, and support is very -restricted. However, if you really need the documentation of the old letter -class, you can still find it in the file \File{scrlettr.dtx}, but only in -German. You should run it through {\LaTeX} several times, like this: -\begin{lstoutput}[morekeywords={latex,mkindex}] - latex scrlettr.dtx - mkindex scrlettr - latex scrlettr.dtx - mkindex scrlettr - latex scrlettr.dtx -\end{lstoutput} -Then you obtain the file \File{scrlettr.dvi} containing the old German -manual. If you want \File{scrlettr.pdf} instead of \File{scrlettr.dvi} you -should use \File{pdflatex} instead of \File{latex}. +With\textnote{Attention!} the 2002 release of \Class{scrlttr2} (see +\autoref{cha:scrlttr2}), the old letter class, \Class{scrlettr}, became +obsolete, and it is no longer part of \KOMAScript. If you still need the class +or information about it, you will find it in +\cite{package:koma-script-obsolete}. To facilitate the transition to the new class, there is the compatibility -option \Option{KOMAold}. In general, the complete older functionality still -remains in the new class. Without \Option{KOMAold}, the user -interface and the defaults will be different. More details on +option \Option{KOMAold}. Basically, all the older functionality still +exists in the new class. Without \Option{KOMAold}, however, the user +interface and the defaults are different. More details on this option are provided in \autoref{sec:scrlttr2.lcoFile}, \autoref{tab:lcoFiles}. -\LoadNonFree{scrlttr2-experts}{0} +\LoadNonFree{scrlttr2-experts}{2} +% +\EndIndexGroup +\fi % \EndIndexGroup diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2.tex index ef26c720cab..ff758441c91 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrlttr2.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrlttr2.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,36 +46,56 @@ % ============================================================================ \KOMAProvidesFile{scrlttr2.tex}% - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (chapter: scrlttr2)] \translator{Harald Bongartz\and Georg Grandke\and Raimund Kohl\and Jens-Uwe - Morawski\and Stephan Hennig\and Gernot Hassenpflug\and Markus Kohm} + Morawski\and Stephan Hennig\and Gernot Hassenpflug\and Markus Kohm\and + Karl Hagen} -% Date of the translated German file: 2017-01-02 +% Date of the translated German file: 2018-02-13 -\chapter{The New Letter Class \Class{scrlttr2}} +\chapter{Letters with the \Class{scrlttr2} Class or the \Package{scrletter} + Package} \labelbase{scrlttr2} -\BeginIndexGroup% -\BeginIndex{Class}{scrlttr2}% -\BeginIndex{}{letters}% -\iffalse - Since the June 2002 release {\KOMAScript} provides a completely - rewritten letter class\ChangedAt{v2.8q}{\Class{scrlttr2}}. Although - part of the code is identical to that of the main classes described - in \autoref{cha:maincls}, letters -\else - Letters -\fi -are quite different from articles, -reports, books, and suchlike. That alone justifies a separate -chapter about the letter class. But there is another reason for a -chapter on \Class{scrlttr2}. This class has been redeveloped from -scratch and provides a new user interface different from every other -class the author knows of. This new user interface may be uncommon, -but the author is convinced both experienced and new {\KOMAScript} -users will benefit from its advantages. +\BeginIndexGroup +\BeginIndex{Class}{scrlttr2}\BeginIndex{Package}{scrletter}% +\BeginIndex{}{letters}% +Letters are quite different in many ways from articles, reports, books, and +the like. That alone justifies a separate chapter on letters. But there are +other reasons for a separate chapter on \Class{scrlttr2} and +\Package{scrletter}. + +The \Class{scrlttr2}\important{\Class{scrlttr2}} class was developed from +scratch in 2002. It provides a completely new user interface, different from +every other class I know. This new user interface may be unusual, but it +offers benefits to both new and experienced {\KOMAScript} users. + +The \Package{scrletter}\important{\Package{scrletter}}% +\ChangedAt{v3.15}{\Package{scrletter}} package has supplemented \KOMAScript{} +since Version~3.15. It also provides all the letter-based functionality of +\Class{scrlttr2} to the other classes. I recommend you use one of the +\KOMAScript{} classes\,---\,\Class{scrbook}, \Class{scrreprt} or +\Class{scrartcl}\,---\, which are explained in the previous chapter. With +minor limitations, \Package{scrletter} also works well with the standard +classes. + +The starting point for developing \Package{scrletter} was, on the one hand, +requests from users who also wanted to have elements such as +section\textnote{headings, floating environments, indexes} headings, floating +environments, or a bibliography in letters. On the other hand, there were also +requests to use \Class{scrlttr2} variables in the remaining \KOMAScript{} +classes. You can achieve both by combining the desired \KOMAScript{} class +with \Package{scrletter}. + +Compared to the letter class, the letter package has a few small changes that +were necessary to avoid conflicts with other classes. These changes mainly +affect the page styles and are explicitly documented (see +\autoref{sec:\LabelBase.pagestyle}, starting at +\autopageref{sec:\LabelBase.pagestyle}). Where \Package{scrletter} is not +explicitly mentioned, everything that is documented for \Class{scrlttr2} +applies without change. \section{Variables} @@ -83,41 +103,39 @@ users will benefit from its advantages. \BeginIndexGroup \BeginIndex{}{variables} -Apart from options, commands, environments, counters and lengths, -additional elements have already been introduced in \KOMAScript. A -typical property of an element is the font style and the option to -change it (see \autoref{sec:\LabelBase.textmarkup}, -\DescPageRef{\LabelBase.cmd.setkomafont}). At this point we now -introduce variables. Variables have a name by which they are called, -and they have a content. The content of a variable can be set -independently from time and location of the actual usage in the same -way as the contents of a command can be separated from its usage. The -main difference between a command and a variable is that a command -usually triggers an action, whereas a variable only consists of plain -text which is then output by a command. Furthermore, a variable can -additionally have a description which can be set and output. - -This section specifically only gives an introduction to the concept of -variables. The following examples have no special meaning. More -detailed examples can be found in the explanation of predefined -variables of the letter class in the following sections. An overview -of all variables is given in \autoref{tab:\LabelBase.variables}. +In addition to options, commands, environments, counters, and lengths, +\autoref{cha:maincls} introduced the concept of additional elements for +\KOMAScript{}. A typical property of an element is its font style and the +ability to change it (see \autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}). In this section we introduce +variables. Variables can have a label used to identify them when they are +output in the document as well as their actual content. To avoid confusion +with labels used for cross-references, this guide refers to such labels as the +``description'' of the variable. The content of a variable can be set +independently of the time and place it is used the same way that the content +of a command can be defined separately from its use. The main difference +between a command and a variable is that a command usually triggers an action, +whereas a variable usually consists of plain text which is then output by a +command. In addition, a variable can also have a description which can be +customised and output. + +This section deliberately confines itself to introducing the concept of +variables. The examples below have no special meaning. More detailed +examples can be found in the explanation of predefined variables used in the +class and the package. An overview of all defined variables is given in +\autoref{tab:\LabelBase.variables}. % \begin{desclist} - % Umbruchkorrektur - \renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% - \desccaption{% - Alphabetical list of all supported variables in - \Class{scrlttr2}\label{tab:\LabelBase.variables}% - }{% - Alphabetical list of all supported variables in \Class{scrlttr2} - (\emph{continuation})% - }% + %\renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% + \desccaption{Supported variables in \Class{scrlttr2} and + \Package{scrletter}\label{tab:\LabelBase.variables}}% + {Supported variables in \Class{scrlttr2} and \Package{scrletter} + (\emph{continued})}% \ventry{addresseeimage}{% - instuctions, that will be used to print the Port-Pay\'e head of option - \OptionValueRef{\LabelBase}{addrfield}{backgroundimage} or the Port-Pay\'e - addressee of option \OptionValueRef{\LabelBase}{addrfield}{image} % - (\autoref{sec:\LabelBase.firstpage}, + commands used to print the postpaid postmark for the + \OptionValueRef{\LabelBase}{addrfield}{backgroundimage} option or the + postpaid address for the \OptionValueRef{\LabelBase}{addrfield}{image} + option (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.addresseeimage})}% \ventry{backaddress}{% return address for window envelopes % @@ -128,8 +146,8 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.backaddressseparator})}% \ventry{ccseparator}{% - separator between title of additional addressees, and additional - addressees % + separator between title of additional addresses (cc list) + and additional addresses % (\autoref{sec:\LabelBase.document}, \DescPageRef{\LabelBase.variable.ccseparator})}% \ventry{customer}{% @@ -141,23 +159,23 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.date})}% \ventry{emailseparator}{% - separator between e-mail name and e-mail address % + separator between email name and email address % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.emailseparator})}% \ventry{enclseparator}{% - separator between title of enclosure, and enclosures % + separator between title of enclosure and enclosures % (\autoref{sec:\LabelBase.document}, \DescPageRef{\LabelBase.variable.enclseparator})}% \ventry{faxseparator}{% - separator between title of fax, and fax number % + separator between title of fax and fax number % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.faxseparator})}% \ventry{firstfoot}{% - page\ChangedAt{v3.08}{\Class{scrlttr2}} foot of the note paper % + footer\ChangedAt{v3.08}{\Class{scrlttr2}} of the letterhead page % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.firstfoot})}% \ventry{firsthead}{% - page\ChangedAt{v3.08}{\Class{scrlttr2}} head of the note paper % + header\ChangedAt{v3.08}{\Class{scrlttr2}} of the letterhead page % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.firsthead})}% \ventry{fromaddress}{% @@ -165,7 +183,7 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.fromaddress})}% \ventry{frombank}{% - sender's bank account % + sender's bank details % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.frombank})}% \ventry{fromemail}{% @@ -194,12 +212,12 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.fromphone})}% \ventry{fromurl}{% - a URL of the sender, e.\,g., the URL of his homepage % + URL of the sender, e.\,g. of the sender's homepage % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.fromurl})}% \ventry{fromzipcode}{% - zip code or postcode of the sender used at the Port-Pay\'e head of option - \OptionValueRef{\LabelBase}{addrfield}{PP} % + ZIP code (postal code) of the sender for the postpaid postmark of the + \OptionValueRef{\LabelBase}{addrfield}{PP} option % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.fromzipcode})}% \ventry{invoice}{% @@ -207,7 +225,7 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.invoice})}% \ventry{location}{% - more details of the sender % + extra details of the sender % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.location})}% \ventry{myref}{% @@ -215,13 +233,13 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.myref})}% \ventry{nextfoot}{% - page\ChangedAt{v3.08}{\Class{scrlttr2}} foot using page style + footer\ChangedAt{v3.08}{\Class{scrlttr2}} using page style \PageStyle{headings}\IndexPagestyle{headings} or \PageStyle{myheadings}\IndexPagestyle{myheadings} % (\autoref{sec:\LabelBase.pagestyle}, \DescPageRef{\LabelBase.variable.nextfoot})}% \ventry{nexthead}{% - page\ChangedAt{v3.08}{\Class{scrlttr2}} head using page style + header\ChangedAt{v3.08}{\Class{scrlttr2}} using page style \PageStyle{headings}\IndexPagestyle{headings} or \PageStyle{myheadings}\IndexPagestyle{myheadings} % (\autoref{sec:\LabelBase.pagestyle}, @@ -231,29 +249,29 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.phoneseparator})}% \ventry{place}{% - sender's place used near date % + sender's location; used next to date % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.place})}% \ventry{placeseparator}{% - separator between place and date % + separator between location and date % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.placeseparator})}% \ventry{PPdatamatrix}{% - instruction, that print the data array of option - \OptionValueRef{\LabelBase}{addrfield}{PP} % + command to print the data array for the + \OptionValueRef{\LabelBase}{addrfield}{PP} option % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.PPdatamatrix})}% \ventry{PPcode}{% - instructions for the sender's identification code of option - \OptionValueRef{\LabelBase}{addrfield}{PP} % + commands for the sender's identification code for the + \OptionValueRef{\LabelBase}{addrfield}{PP} option % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.PPcode})}% \ventry{signature}{% - signature beneath the ending of the letter % + signature annotation beneath the closing text of the letter % (\autoref{sec:\LabelBase.closing}, \DescPageRef{\LabelBase.variable.signature})}% \ventry{specialmail}{% - mode of dispatch % + delivery method % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.specialmail})}% \ventry{subject}{% @@ -261,7 +279,7 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.subject})}% \ventry{subjectseparator}{% - separator between title of subject and subject % + separator between subject title and subject % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.subjectseparator})}% \ventry{title}{% @@ -269,23 +287,23 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.title})}% \ventry{toaddress}{% - address of addressee without addressee name % + address of recipient without recipient name % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.toaddress})}% \ventry{toname}{% - complete name of addressee % + complete name of recipient % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.toname})}% \ventry{yourmail}{% - date of addressee's referenced mail % + date of recipient's referenced mail % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.yourmail})}% \ventry{yourref}{% - addressee's reference % + recipient's reference % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.yourref})}% \ventry{zipcodeseparator}{% - separator between the zip code's or postcode's title and the code itself % + separator between the title of ZIP code (postal code) and the code itself % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.zipcodeseparator})}% \end{desclist} @@ -295,44 +313,44 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. \Parameter{name}\OParameter{description}\Parameter{content}% \Macro{setkomavar*}\Parameter{name}\Parameter{description} \end{Declaration} -With the command \Macro{setkomavar} you determine the -\PName{content} of the variable \PName{name}. Using an optional -argument you can at the same time change the \PName{description} -of the variable. In contrast, \Macro{setkomavar*} can only set the -\PName{description} of the variable \PName{name}. -% Wir haben hier ein anderes Beispiel als in der deutschen Anleitung, aber das -% passt hier sehr gut so! +The \Macro{setkomavar} command sets the \PName{content} of the \PName{name} +variable. Using the optional argument, you can change the \PName{description} +of the variable at the same time. In contrast, \Macro{setkomavar*} sets only +the \PName{description} of the \PName{name} variable. \begin{Example} - Suppose you have defined a direct dialling as mentioned above - and you now want to set the content. You write: -\begin{lstlisting} - \setkomavar{myphone}{-\,11} -\end{lstlisting} - In addition, you want to replace the term ``direct dialling'' - with ``Connection''. Thus you add the description: -\begin{lstlisting} - \setkomavar*{myphone}{Connection} -\end{lstlisting} - or you can combine both in one command: -\begin{lstlisting} - \setkomavar{myphone}[Connection]{-\,11} -\end{lstlisting} + It is customary for letters to indicate the sender in the letterhead. + First, \KOMAScript{} must know the name of the sender. For + ``Joe Public'' that would be done with: +\begin{lstcode} + \setkomavar{fromname}{Joe Public} +\end{lstcode} + The default for the description of the sender is ``From''. Assuming, + however, that Mr Public wants to have ``Sender'' in the places where + \KOMAScript{} outputs his name, he would have to add +\begin{lstcode} + \setkomavar*{fromname}{Sender} +\end{lstcode} + or combine the two commands into one: +\begin{lstcode} + \setkomavar{fromname}[Sender]{Joe Public} +\end{lstcode} + He thus kills two birds with one stone, so to speak. \end{Example} -By the way: You may delete the content of a variable using an empty -\PName{content} argument. You can also delete the description using an -empty \PName{description} argument. +By the way, you can delete the content of the variable by providing an empty +\PName{content} argument. Of course, you can delete the \PName{description} of +the variable in the same way, with an empty argument for the description. \begin{Example} - Suppose you have defined a direct dialling as mentioned above and - you now no longer want a description to be set. You write: -\begin{lstlisting} - \setkomavar*{myphone}{} -\end{lstlisting} - You can combine this with the definition of the content: -\begin{lstlisting} - \setkomavar{myphone}[]{-\,11} -\end{lstlisting} - So you may setup the content and delete the description using only - one command. + Suppose Mr Public wants to have no label for the name of the sender. He can + either delete it for himself with +\begin{lstcode} + \setkomavar*{fromname}{} +\end{lstcode} + or he could again kill two birds with one stone and use +\begin{lstcode} + \setkomavar{fromname}[]{Joe Public} +\end{lstcode} + This will simultaneously set the contents of the variable and delete its + description. \end{Example} % \EndIndexGroup @@ -342,94 +360,91 @@ empty \PName{description} argument. \Macro{usekomavar}\OParameter{command}\Parameter{name}% \Macro{usekomavar*}\OParameter{command}\Parameter{name} \end{Declaration} -In\ChangedAt{v2.9i}{\Class{scrlttr2}} some cases it is necessary for the user -to access the content or the description of a variable, and not to leave this -only up to the class. This is specially important when you have defined a -variable which is not added to the reference fields line. Using the command -\Macro{usekomavar} you have access to the content of the variable -\PName{name}, whereas the starred version \Macro{usekomavar*} allows you to -access the description or title. In \autoref{sec:scrlttr2-experts.variables}, -\DescPageRef{scrlttr2-experts.cmd.newkomavar} you may find more -information about defining variable on your own.% +In\ChangedAt{v2.9i}{\Class{scrlttr2}} some cases, it is necessary to access +the content or description of a variable and not to leave this solely to the +class. This is especially important if you have defined a variable which is +not added to the reference fields line. Using the command \Macro{usekomavar} +you have access to the content of the \PName{name} variable, whereas the +starred version \Macro{usekomavar*} allows you to access the description or +title. In \autoref{sec:scrlttr2-experts.variables}, +\DescPageRef{scrlttr2-experts.cmd.newkomavar} you can find more information +about defining your own variables.% \EndIndexGroup \begin{Declaration} - \Macro{ifkomavar}\Parameter{name}\Parameter{true-code}\Parameter{false-code} + \Macro{ifkomavar}\Parameter{name}\Parameter{then code}\Parameter{else code} \end{Declaration} -This\ChangedAt{v3.03}{\Class{scrlttr2}} command may be used to test, whether -or not a variable has already been defined. The \PName{true-code} will be -executed only, if the variable already exists. The contents of the variable -will not be examined, so it may be empty. The \PName{false-code} will be -executed if the variable does not yet exist. Such tests make sense if a -variable will be defined at one -\File{lco}-file\Index{lco-file=\File{lco}-file} (see -\autoref{sec:\LabelBase.lcoFile} from \autopageref{sec:\LabelBase.lcoFile} -onward), but used in another \File{lco}-file if it exists only.% -% +With\ChangedAt{v3.03}{\Class{scrlttr2}} this command, you can determine if a +variable has already been defined. The \PName{then code} will be executed only +if the variable already exists. The variable's contents will not be examined +and so can be empty. The \PName{else code} will be executed if the variable +does not exist. Such tests can be useful, for example, if your own variables +are defined in one \File{lco} file\Index{lco file=\File{lco} file} (see +\autoref{sec:\LabelBase.lcoFile} starting at +\autopageref{sec:\LabelBase.lcoFile}) but used in another \File{lco} file only +if they exist.% \EndIndexGroup \begin{Declaration} - \Macro{ifkomavarempty}\Parameter{name}\Parameter{true-code}% - \Parameter{false-code}% - \Macro{ifkomavarempty*}\Parameter{name}\Parameter{true-code}% - \Parameter{false-code} + \Macro{ifkomavarempty}\Parameter{name}\Parameter{then code}% + \Parameter{else code}% + \Macro{ifkomavarempty*}\Parameter{name}\Parameter{then code}% + \Parameter{else code} \end{Declaration} -With\ChangedAt{v2.9i}{\Class{scrlttr2}} these commands you may check -whether or not the expanded content or description of a variable is -empty. The \PName{true-code} will be executed if the content or -description is empty. Otherwise the \PName{false-code} will be -executed. The starred variant handles the description of a variable, -the unstarred variant handles the contents.% +With\ChangedAt{v2.9i}{\Class{scrlttr2}} these commands, you can determine +whether either the content or the description of a variable is empty. The +\PName{then code} will be executed if the expanded content or the expanded +description of the \PName{name} variable is empty. Otherwise, the \PName{else +code} will be executed. The starred variant tests the variable's description, +while the normal variant tests its contents.% \EndIndexGroup % \EndIndexGroup -\section{Pseudo-Lengths} +\section{Pseudo-lengths} \seclabel{pseudoLength} - \BeginIndexGroup \BeginIndex{}{pseudo-lengths} -\LaTeX{} processes length with commands \Macro{newlength}, \Macro{setlength}, -\Macro{addtolength}, and \Macro{the\PName{length}}. Many packages also use -macros, that are commands, to storage lengths. \KOMAScript{} extends the -method of storing length at macros by some commands similar to the commands -above, that are used to handle real lengths. \KOMAScript calls this kind of -lengths, that are stored at macros instead of real \LaTeX{} lengths, -pseudo-lengths. - -A list of all pseudo-lengths in \Class{scrlttr2} is shown in -\autoref{tab:scrlttr2-experts.pseudoLength} starting at -\autopageref{tab:scrlttr2-experts.pseudoLength}. The meaning of the various -pseudo-lengths is shown graphically in + +\LaTeX{} processes lengths with three commands: +\Macro{newlength}\IndexCmd{newlength}, \Macro{setlength}\IndexCmd{setlength} +and \Macro{addtolength}\IndexCmd{addtolength}. Many packages also use macros, +which are commands, to store lengths. \KOMAScript{} extends this method with +the ability to process such lengths stored in macros with commands similar to +those used to handle real lengths. \KOMAScript{} calls lengths that are +actually stored in macros \emph{pseudo-lengths}. + +You can find a list of all pseudo-lengths defined by \Class{scrlttr2} in +\autoref{tab:scrlttr2-experts.pseudoLength}, +\autopageref{tab:scrlttr2-experts.pseudoLength}. A graphical representation of +the main pseudo-lengths for the letterhead page is given in \autoref{fig:scrlttr2-experts.pseudoLength}. The dimensions used in the figure correspond to the default settings of \Class{scrlttr2}. More detailed -description of the individual pseudo-lengths is found in the individual +descriptions of the individual pseudo-lengths are found in the individual sections of this chapter. -Normally users would not need to define a pseudo-length on their own. Because -of this, definition of pseudo-lengths will be described in the expert part at +Since users will usually not need to define their own pseudo-lengths, the +method for defining them is described in the part for experts, in \autoref{sec:scrlttr2-experts.pseudoLengths}, -\DescPageRef{scrlttr2-experts.cmd.@newplength}. Setting pseudo-lengths to -new values is also a work for advanced users. So this will be described in the -expert part too at \DescPageRef{scrlttr2-experts.cmd.@setplength}. +\DescPageRef{scrlttr2-experts.cmd.@newplength}. Setting pseudo-lengths to new +values should also be a matter for advanced users, so this is also described +in the part for experts, on \DescPageRef{scrlttr2-experts.cmd.@setplength}. -Please note\textnote{Attention!}: Even though these pseudo-lengths are -internally implemented as macros, the commands for pseudo-length management -expect only the names of the pseudo-lengths not the macros representing the -pseudo-lengths. The names of pseudo-lengths are without backslash at the very -beginning similar to the names of \LaTeX{} counters and in opposite to macros -or \LaTeX{} lengths. +Note\textnote{Attention!} that although these pseudo-lengths are internally +implemented as macros, the commands to use pseudo-lengths expect only the the +pseudo-length names. These are written without backslashes, like the names of +\LaTeX{} counters and unlike macros or real lengths. \begin{Declaration} \Macro{useplength}\Parameter{name} \end{Declaration} -Using this command you can access the value of the pseudo-length with +Using this command you can access the value of the pseudo-length of the given \PName{name}. This is one of the few user commands in connection with pseudo-lengths. Of course this command can also be -used with an \File{lco}-file\Index{lco-file=\File{lco}-file} (see +used with an \File{lco} file\Index{lco file=\File{lco} file} (see \autoref{sec:\LabelBase.lcoFile} ab \autopageref{sec:\LabelBase.lcoFile}).% % \EndIndexGroup @@ -441,30 +456,19 @@ used with an \File{lco}-file\Index{lco-file=\File{lco}-file} (see \Macro{addtolengthplength}% \OParameter{factor}\Parameter{length}\Parameter{pseudo-length} \end{Declaration} -\begin{Explain}% - While you can simply prepend a factor to a length, this is not - possible with pseudo-lengths. Suppose you have a length \Macro{test} - with the value 2\Unit{pt}; then \texttt{3\Macro{test}} gives you the - value 6\Unit{pt}. Using pseudo-lengths instead, - \texttt{3\Macro{useplength}\PParameter{test}} would give you - 32\Unit{pt}. This is especially annoying if you want a real - \PName{length} to take the value of a \PName{pseudo-length}. -\end{Explain} -Using the command \Macro{setlengthtoplength} you can assign the -multiple of a \PName{pseudo-length} to a real \PName{length}. Here, -instead of prepending the \PName{factor} to the \PName{pseudo-length}, -it is given as an optional argument. You should also use this command -when you want to assign the negative value of a \PName{pseudo-length} -to a \PName{length}. In this case you can either use a minus sign or -\PValue{-1} as the \PName{factor}. The command -\Macro{addtolengthplength} works very similarly; it adds the multiple -of a \PName{pseudo-length} to the \PName{length}. +With the \Macro{setlengthtoplength} command, you can assign a multiple of a +\PName{pseudo-length} to a real \PName{length}. The \PName{factor} is given +as an optional argument instead of directly preceding the +\PName{pseudo-length}. You should also use this command when you want to +assign the negative of a \PName{pseudo-length} to a \PName{length}. In this +case, you can use either a minus sign or \PValue{-1} as the \PName{factor}. +The \Macro{addtolengthplength} command works very similarly. It adds the +\PName{pseudo-length} multiplied by the \PName{factor} to the \PName{length}.% % \EndIndexGroup % \EndIndexGroup - \LoadCommonFile{options} % \section{Early or Late Selection of Options} \LoadCommonFile{compatibility} % \section{Compatibility with Earlier Versions of @@ -474,13 +478,14 @@ of a \PName{pseudo-length} to the \PName{length}. \LoadCommonFile{typearea} % \section{Page Layout} -Normally it makes no sense to distinguish letters with single-side layout and -letters with double-side layout. Mostly letters are not bound like -books. Therefor each page will be viewed on its own. This is also true if both -sides of the paper sheet will be used for printing. Vertical adjustment is -unusual at letters too. Nevertheless, if you need or want it, you may read the -description of \Macro{raggedbottom} and \Macro{flushbottom} in -\autoref{sec:maincls.typearea} at \DescPageRef{maincls.cmd.flushbottom}.% +For letters, it is normally not useful to distinguish one-sided and two-sided +printing. Since letters are not usually bound, each page of a letter will be +viewed on its own. This is also true even if both the letter is printed on +both sides of the paper. Vertical adjustment usually does not matter for +letters either. If you nevertheless need it, or want to understand what it is, +please refer to the commands \Macro{raggedbottom} and \Macro{flushbottom} +explained in \autoref{sec:maincls.typearea} on +\DescPageRef{maincls.cmd.flushbottom}.% % \EndIndexGroup @@ -490,20 +495,19 @@ description of \Macro{raggedbottom} and \Macro{flushbottom} in \BeginIndexGroup \BeginIndex{}{letter>structure} -The general structure of a letter document differs somewhat from the -structure of a normal document. Whereas a book document in general -contains only one book, a letter document can contain several -letters. As illustrated in \autoref{fig:\LabelBase.document}, a letter -document consists of a preamble, the individual letters, and the -closing. +The general structure of a letter document differs somewhat from the structure +of a normal document. Whereas a book document usually contains only one book, +a letter document can contain several letters. As illustrated in +\autoref{fig:\LabelBase.document}, a letter document consists of a preamble, +the individual letters, and the closing. \begin{figure} \KOMAoptions{captions=bottombeside}% \setcapindent{0pt}% \begin{captionbeside}[{% - General structure of a letter document with several individual letters% + General structure of a letter document containing several individual letters% }]{% - General structure of a letter document with several individual letters + General structure of a letter document containing several individual letters (the structure of a single letter is shown in \autoref{fig:\LabelBase.letter})% \label{fig:\LabelBase.document}% @@ -522,7 +526,7 @@ closing. \dots\\ }}\\ \fbox{\parbox{\linewidth}{\raggedright% - \Macro{begin}\PParameter{letter}\Parameter{addressee}\\ + \Macro{begin}\PParameter{letter}\Parameter{recipient}\\ \dots\\ {\centering\emph{content of the individual letter}\\} \dots\\ @@ -536,24 +540,29 @@ closing. \end{captionbeside} \end{figure} -The preamble comprises all settings that in general concern all letters. Most -of them can also be overwritten in the settings of the individual letters. The -only setting which can not be changed within a single letter is compatibility -to prior versions of \Class{scrlttr2} (see option \DescRef{\LabelBase.option.version} in +The preamble contains all the settings that apply generally to all letters. +Most of them can also be overwritten in the settings of the individual +letters. The only setting which cannot currently be changed within a single +letter is the version of \Class{scrlttr2} for which compatibility is required +(see the \DescRef{\LabelBase.option.version} option in \autoref{sec:\LabelBase.compatibilityOptions}, \DescPageRef{\LabelBase.option.version}). -It is recommended that only general settings such as the loading of packages -and the setting of options be placed before -\Macro{begin}\PParameter{document}. All settings that comprise the setting of -variables or other text features should be done after -\Macro{begin}\PParameter{document}. This is particularly recommended when the -\Package{babel} package\IndexPackage{babel} (see \cite{package:babel}) is -used, or language-dependent variables of \Class{scrlttr2} are to be changed. +If you use \Package{scrletter}\important{scrletter}, the only difference is +that another class is loaded, with +\DescRef{\LabelBase.cmd.usepackage}\PParameter{scrletter} added before the +settings for all letters. For setting options with \Package{scrletter}, see +\autoref{sec:\LabelBase.options}, on \autopageref{sec:\LabelBase.options}. -The closing usually consists only of -\Macro{end}\PParameter{document}. Of course you can also insert -additional comments at this point. +I recommended that you place only general settings such as loading packages +and setting options before \Macro{begin}\PParameter{document}. You should +initialise all variables or other textual features after +\Macro{begin}\PParameter{document}, particularly when you use the +\Package{babel} package\IndexPackage{babel} (see \cite{package:babel}) or +change language-dependent variables of \Class{scrlttr2}. + +The closing usually consists only of \Macro{end}\PParameter{document}. Of +course you can also add additional comments at this point. \begin{figure} \KOMAoptions{captions=bottombeside}% @@ -569,11 +578,11 @@ additional comments at this point. \addtolength{\linewidth}{-\dimexpr2\fboxrule+2\fboxsep\relax}% \fbox{\parbox{\linewidth}{\raggedright% \Macro{begin}\PParameter{letter}% - \OParameter{Optionen}\Parameter{addressee}\\ + \OParameter{options}\Parameter{recipient}\\ \dots\\[\dp\strutbox] {\centering\emph{settings for this letter}\\} \dots\\ - \DescRef{\LabelBase.cmd.opening}\Parameter{opening}\\ + \DescRef{\LabelBase.cmd.opening}\Parameter{salutation}\\ }}\\[1pt] \fbox{\parbox{\linewidth}{\raggedright% \dots\\[\dp\strutbox] @@ -581,71 +590,77 @@ additional comments at this point. \dots\\ }}\\[1pt] \fbox{\parbox{\linewidth}{\raggedright% - \DescRef{\LabelBase.cmd.closing}\Parameter{closing}\\ + \DescRef{\LabelBase.cmd.closing}\Parameter{concluding text}\\ \DescRef{\LabelBase.cmd.ps}\\ \dots\\[\dp\strutbox] {\centering\emph{postscript}\\} \dots\\ \DescRef{\LabelBase.cmd.encl}\Parameter{enclosures}\\ - \DescRef{\LabelBase.cmd.cc}\Parameter{additional addressees}\\ + \DescRef{\LabelBase.cmd.cc}\Parameter{additional recipients}\\ \Macro{end}\PParameter{letter}\\ }}\\[\dimexpr\fboxsep+\fboxrule\relax] \end{minipage} \end{captionbeside} \end{figure} -As shown in \autoref{fig:\LabelBase.letter}, every single letter itself consists -of an introduction, the letter body, and the closing. In the introduction, all -settings pertaining only to the current letter are defined. It is important -that this introduction always ends with -\DescRef{\LabelBase.cmd.opening}\IndexCmd{opening}. Similarly, the closing always starts with -\DescRef{\LabelBase.cmd.closing}\IndexCmd{closing}. The two arguments \PName{opening} and -\PName{closing} can be left empty, but both commands must be used and must -have an argument. - -It should be noted that several settings can be changed between the individual -letters. Such changes then have an effect on all subsequent letters. For -reasons of maintainability of your letter documents, it is however not -recommended to use further general settings with limited scope between the -letters. +As detailed in \autoref{fig:\LabelBase.letter}, individual letters each +consist of an introduction, the body of the letter, and the closing. In the +introduction, all settings pertaining to the current letter alone are defined. +It is important that this introduction always ends with +\DescRef{\LabelBase.cmd.opening}\IndexCmd{opening}. Similarly, the closing +always starts with \DescRef{\LabelBase.cmd.closing}\IndexCmd{closing}. The +\PName{opening} and \PName{closing} arguments of the two commands can be left +empty, but both commands must be used and must have an argument. + +Note that you can change additional settings between the individual letters. +Such changes then apply to all subsequent letters. However, to keep your +letter documents clear and maintainable, you should think carefully before +actually placing further general settings of limited scope between the +letters. I cannot recommend this practice. However, if you use +\Package{scrletter2}, there is nothing wrong with inserting additional parts +of the document between or after letters that should not be in the same scope. +For example, you can combine a cover letter and a CV in one document. \begin{Declaration} - \begin{Environment}{letter}\OParameter{options}\Parameter{addressee} + \begin{Environment}{letter}\OParameter{options}\Parameter{recipient} \end{Environment} \end{Declaration} -\BeginIndex{}{addressee}% +\BeginIndex{}{address}% The \Environment{letter} environment is one of the key environments of the -letter class. A special\textnote{\KOMAScript{} vs. standard classes} -\Class{scrlttr2} feature are optional arguments to the \Environment{letter} -environment. These \PName{options} are executed internally via the +letter class. A noteworthy\textnote{\KOMAScript{} vs. standard classes} +feature of \Class{scrlttr2} and \Package{scrletter} is that they can provide +additional \PName{options} for the \Environment{letter} environment. These +\PName{options} are executed internally using the \DescRef{\LabelBase.cmd.KOMAoptions} command. -The \PName{addressee} is a mandatory argument passed to the -\Environment{letter} environment. Parts\textnote{Attention!} of the addressee -contents are separated by double backslashes. These parts are output on -individual lines in the address field. Nevertheless, the double backslash -should not be interpreted as a certain line break. Vertical material such as -paragraphs or vertical space is not permitted within \PName{addressee}, and -could lead to unexpected results and error messages, as is the case also for -the standard letter class. +The \PName{recipient}, or addressee, is a mandatory argument passed to the +\Environment{letter} environment and includes both the name and the address of +the recipient of the letter. Double\textnote{Attention!} backslashes serve to +separate the individual parts of the address. These parts are output on +individual lines in the address field. Nevertheless, you should not interpret +the double backslash as a mandatory line break. Vertical material such as new +paragraphs or vertical space is not permitted within the address. They can +lead to unexpected results and error messages. Incidentally, this is the same +for the standard letter class. \begin{Example} \phantomsection\label{desc:\LabelBase.env.letter.example}% - Assumed, someone wants to send a letter to Joana Public. A minimalistic - letter document for this may be: + Suppose you want to write a letter to Joanna Public. A minimalist + letter document would look like this: \begin{lstcode} \documentclass[version=last]{scrlttr2} - \usepackage[english]{babel} + \usepackage[british]{babel} \begin{document} - \begin{letter}{Joana Public\\ - Hillside 1\\ - 12345 Public-City} + \begin{letter}{Joanna Public\\ + 1 Hillside\\ + SAMPLESTEAD\\ + WX12 3YZ} \end{letter} \end{document} \end{lstcode} - However, this would not result in any printable output. At least there - would not be an addressee at the note paper sheet. The reason for this will - be explained at the description of command \DescRef{\LabelBase.cmd.opening} at + However, this would not result in any output. It would not even print the + recipient on the letterhead page. Why this is the case is explained in the + description of the \DescRef{\LabelBase.cmd.opening} command on \DescPageRef{\LabelBase.cmd.opening}. \end{Example} % @@ -653,31 +668,32 @@ the standard letter class. \begin{Declaration} - \Macro{AtBeginLetter}\Parameter{instruction code}% - \Macro{AtEndLetter}\Parameter{instruction code} + \Macro{AtBeginLetter}\Parameter{code}% + \Macro{AtEndLetter}\Parameter{code} \end{Declaration} -{\LaTeX} enables the user to declare \PName{instruction code} whose execution -is delayed until a determined point. Such points are called -\emph{hooks}\Index{hook}. Known macros for using hooks are +As mentioned in \cite{latex:clsguide}, \LaTeX{} lets the user declare +additional \PName{code} to be executed at certain points in a \LaTeX{} run. +For this purpose, the \LaTeX{} kernel provides, for example, \Macro{AtBeginDocument}\IndexCmd{AtBeginDocument} and -\Macro{AtEndOfClass}\IndexCmd{AtEndOfClass} at the \LaTeX{} kernel. The class -\Class{scrlttr2} provides two more hooks. The \PName{instruction code} for -these may be declared using \Macro{AtBeginLetter} and +\Macro{AtEndOfClass}\IndexCmd{AtEndOfClass}. Such points are called +\emph{hooks}\Index{hook}. The \Class{scrlttr2} class and the +\Package{scrletter} package provide two additional hooks. You can declare the +\PName{code} for these using \Macro{AtBeginLetter} and \Macro{AtEndLetter}\ChangedAt{v2.95}{\Class{scrlttr2}}. Originally, hooks were -provided for package and class authors, so they are documented in -\cite{latex:clsguide} only, and not in \cite{latex:usrguide}. However, with -letters there are useful applications of \Macro{AtBeginLetter} as the -following example may illustrate. +intended for package and class authors, so they are documented only in +\cite{latex:clsguide} and not in \cite{latex:usrguide}. However, with letters +there are useful applications at the user level for both new hooks, as the +following example illustrates. % \begin{Example} - It is given that one has to set multiple letters with questionnaires - within one document. Questions are numbered automatically within - single letters using a counter. Since, in contrast to page - numbering, that counter is not known by \Class{scrlttr2}, it would - not be reset at the start of each new letter. Given that each - questionnaire contains ten questions, question~1 would get number~11 - in the second letter. A solution is to reset this counter at the - beginning of each new letter: + Suppose you have several letters in a document that use their own commands + to insert a questionnaire in the letters. The questions are numbered + automatically using a counter. Since \KOMAScript{} is unaware of this + counter, it would not be reset at the start of each new letter, unlike the + page number. If each questionnaire contains ten questions, the first + question in the fifth letter would get the number~41. You can solve this + problem by telling \KOMAScript{} to reset this counter at the beginning of + each letter: \begin{lstlisting} \newcounter{Question} \newcommand{\Question}[1]{% @@ -689,9 +705,10 @@ following example may illustrate. \AtBeginLetter{\setcounter{Question}{0}} \end{lstlisting} This way first question remains question~1, even in the 1001st letter. Of - course the definition at this example needs package - \Package{tabularx}\IndexPackage{tabularx} (see \cite{package:tabularx}). -\end{Example} + course the definition in this example requires the + \Package{tabularx}\IndexPackage{tabularx} package (see + \cite{package:tabularx}). +\end{Example}% % \EndIndexGroup @@ -702,14 +719,15 @@ following example may illustrate. \Macro{letterlastpage} \end{Declaration} If\ChangedAt{v3.19}{\Class{scrlttr2}\and \Package{scrletter}} you have more -than one letter in one document, it is useful to have a letter number. Since -version~3.19 \KOMAScript{} provides counter \Counter{letter} and increases it -at every \Macro{begin}\PParameter{letter}. +than one letter in a document, it is useful to have a letter number. For this +purpose, \KOMAScript{} has provided the \Counter{letter} counter, which +is incremented by one at each \Macro{begin}\PParameter{letter}, since +version~3.19. \begin{Example} - Have one more look into the \DescRef{\LabelBase.cmd.AtBeginLetter} + Let's return to the \DescRef{\LabelBase.cmd.AtBeginLetter} example. Instead of resetting the counter explicitly at - \Macro{begin}\PParameter{letter}, we can do it implicitly by defining - counter \Counter{Question} depending on counter \Counter{letter}: + \Macro{begin}\PParameter{letter}, we can do so implicitly by defining + counter \Counter{Question} to depend on counter \Counter{letter}: \begin{lstlisting} \newcounter{Question}[letter] \newcommand{\Question}[1]{% @@ -719,91 +737,100 @@ at every \Macro{begin}\PParameter{letter}. \end{tabularx}% }% \end{lstlisting} - Now, the new counter will be reset at every start of a new letter and - the first question of every letter will be number one. + Now the new counter will be reset at every start of each letter so that + the first question in each letter will be number one. \end{Example} -If you want the output of current value of \Counter{letter}, you may usually -use \Macro{theletter}. Indeed the letter can also be used for +If you want to display the current value of \Counter{letter}, this is +possible, as usual, with \Macro{theletter}. The counter can also be used for cross-references. So you can use \Macro{label}\Parameter{name} to generate a label immediately after \Macro{begin}\PParameter{letter} and reference it somewhere in the document using \Macro{ref}\Parameter{name}. Inside the same -letter you can simply use \Macro{thisletter} without generating a label to get -the same result. - -\KOMAScript{} itself uses \Macro{thisletter} to put a label onto the last page -of every letter. You can use -\Macro{letterlastpage}\IndexCmd{label}\IndexCmd{pageref} to reference the last -page number of the current letter. Please note, the value of -\Macro{letterlastpage} is valid after some \LaTeX{} runs, because it uses -\Macro{label} and \Macro{pageref}. So you need at least two or three \LaTeX{} -runs, if you use \Macro{letterlastpage}. Please have a look at \emph{Rerun} -terminal or \File{log}-file messages about labels that have been changed.% +letter you can get the same result by simply using \Macro{thisletter} without +creating a label. + +For labels in form letters, it is necessary to give them a unique name across +all letters. Once again, you can use \Macro{thisletter} for this purpose. +\KOMAScript{} also uses \Macro{thisletter} internally to put a label on the +last page of each letter. This makes it possible to use +\Macro{letterlastpage}\IndexCmd{label}\IndexCmd{pageref} to reference the +number of the last page of the current letter at any point within the letter. +Since \Macro{letterlastpage} uses \Macro{label} and \Macro{pageref}, it is +only valid after several \LaTeX{} runs\,---\,usually two or three. If you use +\Macro{letterlastpage}, pay attention to the \emph{Rerun} messages in the +terminal output or \File{log} file messages about labels that have been +changed.% \EndIndexGroup \begin{Declaration} - \Macro{opening}\Parameter{opening} + \Macro{opening}\Parameter{salutation} \end{Declaration} -This is one of the most important commands in \Class{scrlttr2}. For the user -it may seem that only the \PName{opening}\Index{letter>opening}, e.\,g., -``Dear Mrs~\dots'', is typeset, but\textnote{Attention!} the command also -typesets the folding marks\Index{folding marks}, -letterhead\Index{letter>head}, address field\Index{address field}, reference -fields line\Index{reference line}, subject\Index{subject}, the page -footer\Index{page>footer} and others. In short, without \Macro{opening} there -is no letter. And if you want to print a letter without opening you have to -use an \Macro{opening} command with an empty argument. +This is one of the most important commands for letters. On the surface, it may +seem that only the \PName{salutation}\Index{letter>salutation}, for example +``Dear Mrs~\dots'', is printed. Actually\textnote{Attention!}, this command +also prints the fold marks\Index{fold marks}, the +letterhead\Index{letterhead}, the address\Index{address}, the extra sender +information, the reference line\Index{reference line}, the title\Index{title}, +the subject\Index{subject}, and the footer\Index{page>footer}. In short, +without \Macro{opening} there is no letter. If, in fact, you want to print a +letter without a salutation, you have to use an \Macro{opening} command with +an empty argument. \begin{Example} - Let's extend the example from - \DescPageRef{\LabelBase.env.letter.example} by an opening: + Let's return to the example of + \DescPageRef{\LabelBase.env.letter.example} and add a salutation: \lstinputcode[xleftmargin=1em]{letter-0.tex} - This will result in a note paper sheet shown in + This will result in the letterhead shown in \autoref{fig:\LabelBase.letter-0}. \begin{figure} \setcapindent{0pt}% - \begin{captionbeside}[{Example: letter with addressee and opening}]{% - result of a minimalistic letter with addressee and opening only - (date and folding marks are defaults of DIN-letters)}[l] + \begin{captionbeside}[{Example: letter with recipient and salutation}]{% + result of a minimalist letter with recipient and salutation only + (the date is set by default)}[l] \frame{\includegraphics[width=.4\textwidth]{letter-0}} \end{captionbeside} \label{fig:\LabelBase.letter-0} \end{figure} \end{Example} \iffalse% Umbruchkorrekturtext - -In the early days of computer-generated letters, programs did not have many -capabilities, therefore the letters seldom had an opening. Today the -capabilities have been enhanced. Thus personal openings are very common, even -in mass-production advertising letters.% +\begin{Explain} + In the early days of computer-generated letters, a salutation was normally + omitted, since individualised form letters were hardly possible. Today + personalised greetings are common in in mass mailings.% +\end{Explain} \fi % \EndIndexGroup + \begin{Declaration} - \Macro{closing}\Parameter{closing phrase} + \Macro{closing}\Parameter{concluding text} \end{Declaration} The main purpose of the command \Macro{closing} is to typeset the -\PName{closing phrase}\Index{closing}. This may even consists of multiple -lines. The lines should be separated by double backslash. Paragraph breaks -inside the \PName{closing phrase} are not allowed. +\PName{concluding text}\Index{closing}. This can even consist of multiple +lines. In that case, the individual lines should be separated by a double +backslash. Paragraph breaks inside the \PName{concluding text} are not +allowed. -Beyond that the command also typesets the content of the variable -\DescRef{\LabelBase.variable.signature}. More information about the signature and the -configuration of the signature may be found at \autoref{sec:\LabelBase.closing} -ab \DescPageRef{\LabelBase.variable.signature}. +In addition, this command also prints the content of the +\DescRef{\LabelBase.variable.signature} variable. You can find more +information about the signature and its configuration in +\autoref{sec:\LabelBase.closing} on +\DescPageRef{\LabelBase.variable.signature}. \begin{Example} - Let's extend the our example by some lines of text and a closing phrase: + Let's extend the our example with a few lines of text and a closing phrase: \lstinputcode[xleftmargin=1em]{letter-1.tex} This will result in a the letter shown in \autoref{fig:\LabelBase.letter-1}. \begin{figure} \setcapindent{0pt}% - \begin{captionbeside}[{Example: letter with addressee, opening, text, and + \begin{captionbeside}[{Example: letter with recipient, opening, text, and closing}]{% - result of a small letter with addressee, opening, text, and closing - (date and folding marks are defaults of DIN-letters)}[l] + result of a short letter with recipient, opening, text, and closing + % The refernce to DIN-letters in the German guide isn't relevant for + % English-language letters + (the date is set by default)}[l] \frame{\includegraphics[width=.4\textwidth]{letter-1}} \end{captionbeside} \label{fig:\LabelBase.letter-1} @@ -815,25 +842,24 @@ ab \DescPageRef{\LabelBase.variable.signature}. \begin{Declaration} \Macro{ps} \end{Declaration}% -This instruction merely switches to the postscript. Hence, a new -paragraph begins, and a vertical distance\,---\,usually below the -signature\,---\,is inserted. The command \Macro{ps} is followed by -normal text. If you want the postscript to be introduced with the -acronym ``PS:'' , which by the way is written without a full stop, you -have to type this yourself. The acronym is typeset neither -automatically nor optionally by the class \Class{scrlttr2}. +This instruction merely switches to the postscript. To do so, a new paragraph +begins, and a vertical gap\,---\,usually below the signature\,---\,is +inserted. The \Macro{ps} text can be followed by any text. If you want the +postscript to be introduced with the acronym ``PS:'', which in most current +usage is written without full stops, you have to type this yourself. This +abbreviation is printed neither automatically nor optionally by the +\Class{scrlttr2} class. \begin{Example} - The example letter extended by a postscript + The sample letter with the addition of a postscript \lstinputcode[xleftmargin=1em]{letter-2.tex} results in \autoref{fig:\LabelBase.letter-2}. \begin{figure} \setcapindent{0pt}% - \begin{captionbeside}[{Example: letter with addressee, opening, text, + \begin{captionbeside}[{Example: letter with recipient, opening, text, closing, and postscript}]{% - result of a small letter with addressee, opening, text, closing, and - postscript - (date and folding marks are defaults of DIN-letters)}[l] + result of a short letter with recipient, opening, text, closing, and + postscript (the date is set by default)}[l] \frame{\includegraphics[width=.4\textwidth]{letter-2}} \end{captionbeside} \label{fig:\LabelBase.letter-2} @@ -841,13 +867,12 @@ automatically nor optionally by the class \Class{scrlttr2}. \end{Example} \begin{Explain} - In the time when letters were written by hand it was quite common to use a - postscript because this was the only way to add information which one had - forgotten to mention in the main part of the letter. Of course, in letters - written with {\LaTeX} you can insert additional lines easily. Nevertheless, - it is still popular to use the postscript. It gives one a good possibility - to underline again the most important or sometimes the less important things - of the particular letter. + When letters were written still by hand, it was quite common to use a + postscript because this was the only way to add information which had been + forgotten in the main part of the letter. For letters written with \LaTeX{}, + of course, you can easily insert additional lines. Nevertheless, postscripts + remain popular. They can be useful to emphasize important points once more, + or even to mention the less important matters. \end{Explain} % \EndIndexGroup @@ -857,34 +882,32 @@ automatically nor optionally by the class \Class{scrlttr2}. \Macro{cc}\Parameter{distribution list}% \Variable{ccseparator}% \end{Declaration} -With the command \Macro{cc}% -\Index{addressee>additional}\Index{distribution list}\Index{carbon copy} it is -possible to typeset a \PName{distribution list}. The command takes the -\PName{distribution list} as its argument. If the content of the variable -\Variable{ccseparator}\Index{separator}\Index{delimiter} is not empty, then -the name and the content of this variable is inserted before -\PName{distribution list}. In this case the \PName{distribution list} will be -indented appropriately. It is a good idea\textnote{Hint!} to set the +You can print a \PName{distribution list}\Index{recipient>additional}% +\Index{distribution list}\Index{carbon copy} with the \Macro{cc} command. The +command takes the \PName{distribution list} as its argument. If the content of +the variable \Variable{ccseparator}\Index{separator}\Index{delimiter} is not +empty, the name and content of this variable are inserted before the +\PName{distribution list}. In this case, the \PName{distribution list} will be +indented appropriately. It's a good idea\textnote{Hint!} to set the \PName{distribution list} \Macro{raggedright}\IndexCmd{raggedright} and to separate the individual entries with a double backslash. \begin{Example} - This time, the example letter should be send not only to the chairman, but - also to all club members: + This time, the sample letter should go not only to the chairman but also to + all club members: \lstinputcode[xleftmargin=1em]{letter-3.tex}% The result is shown in \autoref{fig:\LabelBase.letter-3}. \begin{figure} \setcapindent{0pt}% - \begin{captionbeside}[{Example: letter with addressee, opening, text, + \begin{captionbeside}[{Example: letter with recipient, opening, text, closing, postscript, and distribution list}]{% - result of a small letter with addressee, opening, text, closing, - postscript, and distribution list - (date and folding marks are defaults of DIN-letters)}[l] + result of a short letter with recipient, opening, text, closing, + postscript, and distribution list (the date is set by default)}[l] \frame{\includegraphics[width=.4\textwidth]{letter-3}} \end{captionbeside} \label{fig:\LabelBase.letter-3} \end{figure} \end{Example} -In front of the distribution list a vertical gap is inserted automatically.% +A vertical gap is inserted automatically before the distribution list.% % \EndIndexGroup @@ -893,24 +916,23 @@ In front of the distribution list a vertical gap is inserted automatically.% \Macro{encl}\Parameter{enclosures}% \Variable{enclseparator}% \end{Declaration} -The \PName{enclosures} have the same structure as the distribution list. -The only difference is that here the enclosures starts with the name -and content of the variable -\Variable{enclseparator}\Index{separator}\Index{delimiter}. +The \PName{enclosures} have the same structure as the distribution list. The +only difference is that the list of enclosures begins with the name and +content of the \Variable{enclseparator}\Index{separator}\Index{delimiter} +variable. \begin{Example} - Now, the example letter will be extended by some paragraphs from the - constitution. These will be added as an enclosure. The description title - will be changed also, because there is only one enclosure and the default - may be prepared for several enclosures: + To the sample letter we will attach an excerpt from the club's articles of + association. These will be added as an enclosure. Because there is only one + enclosure, we change the description title accordingly: \lstinputcode[xleftmargin=1em]{letter-4.tex} This will result in \autoref{fig:\LabelBase.letter-4}. \begin{figure} \setcapindent{0pt}% - \begin{captionbeside}[{Example: letter with addressee, opening, text, + \begin{captionbeside}[{Example: letter with recipient, opening, text, closing, postscript, distribution list, and enclosure}]{% - result of a small letter with addressee, opening, text, closing, - postscript, distribution list, and enclosure - (date and folding marks are defaults of DIN-letters)}[l] + result of a short letter with recipient, opening, text, closing, + postscript, distribution list, and enclosure (the date is set by + default)}[l] \frame{\includegraphics[width=.4\textwidth]{letter-4}} \end{captionbeside} \label{fig:\LabelBase.letter-4} @@ -922,69 +944,72 @@ and content of the variable \EndIndexGroup -\LoadCommonFile{fontsize} % \section{Selection of Document Font Size} +\LoadCommonFile{fontsize} % \section{Choosing the Document Font Size} \LoadCommonFile{textmarkup} % \section{Text Markup} -\section{Note Paper} +\section{Letterhead Page} \seclabel{firstpage} \BeginIndexGroup -\BeginIndex{}{note paper}% -\BeginIndex{}{letter>first page} - -The note paper is the first page and therefore the signboard of each -letter. In business scope often preprinted forms are used, that already -contains elements like the letter head with the sender's information and -logo. \KOMAScript{} provides to position these elements independent. With this -it is not only possible to replicate the note paper directly, but also to -complete the destined fields instantaneously. The independent position is -provided by pseudo-lengths (see \autoref{sec:\LabelBase.pseudoLength} from -\autopageref{sec:\LabelBase.pseudoLength} onward). A schematic display of the -note page and the used variable is shown by -\autoref{fig:\LabelBase.variables}. Thereby the names of the variables are -printed boldly for better distinction from the commands and their arguments. - -Following pages\Index{page>following}\Index{following page} are different from -the note paper. Following pages in the meaning of this manual are all letter -pages but the first one. +\BeginIndex{}{letterhead page}% + +The letterhead page is the first page of, and therefore the signpost for, each +letter. In a business context, the paper for this page is often preprinted +stationery containing elements such as a header with the sender's information +and logo. This header itself is also known as a letterhead. \KOMAScript{} lets +you position these elements freely, and so you can not only replicate the +letterhead page directly but also fill in the required fields instantaneously. +This free positioning is achieved with pseudo-lengths (see +\autoref{sec:\LabelBase.pseudoLength} starting on +\autopageref{sec:\LabelBase.pseudoLength}). You can find a schematic +representation of the letterhead page and the variables used for it in +\autoref{fig:\LabelBase.variables}. The names of the variables are printed in +bold to better distinguish the commands from their arguments. + +Subsequent pages\Index{page>subsequent}\Index{subsequent pages} should be +distinguished from the letterhead page. For the purposes of this manual, +subsequent pages are all pages of a letter except the first one. + \begin{figure} \centering \includegraphics[scale=0.99]{varDIN} - \caption{schematic display of the note paper with the most important - commands and variables for the drafted elements} + \caption{schematic display of the letterhead page outlining the most + important commands and variables} \label{fig:\LabelBase.variables} \end{figure} + \begin{Declaration} - \OptionVName{foldmarks}{selection} + \OptionVName{foldmarks}{setting} \end{Declaration} -Foldmarks\Index{foldmark} or folding marks\Index{folding mark} are tiny -horizontal rules at the left margin or tiny vertical rules at the top -margin. \KOMAScript{} currently provides three configurable horizontal folding -marks and one configurable vertical folding mark. Additionally it provides a -horizontal hole puncher mark, also known as page middle mark. This additional -mark cannot be moved vertically. - -This option activates or deactivates folding marks for vertical -two-, three- or four-panel folding, and a single horizontal folding, of the -letter, whereby the folding need not result in equal-sized parts. The position -of the four horizontal and the single vertical marks are configurable via -pseudo-lengths (see \autoref{sec:scrlttr2-experts.foldmarks} from -\DescPageRef{scrlttr2-experts.plength.foldmarkvpos} onwards). - -The user has a choice: Either one may use the standard values for simple -switches, as described in \autoref{tab:truefalseswitch}, -\autopageref{tab:truefalseswitch}, to activate or deactivate at once all -configured folding marks on the left and upper edges of the paper; -or\ChangedAt{v2.97e}{\Class{scrlttr2}} one may specify by one or more letters, -as listed in \autoref{tab:\LabelBase.foldmark}, the use of the individual -folding marks independently. Also in the latter case the folding marks will only be -shown if they have not been switched off generally with one of \PValue{false}, -\PValue{off}, or \PValue{no}. The exact positioning of the folding marks is -specified in the user settings, that is, the \File{lco} files (see -\autoref{sec:\LabelBase.lcoFile} from \autopageref{sec:\LabelBase.lcoFile} onward) -chosen for a letter. Default values are \PValue{true} and \PValue{TBMPL}. +Fold marks\Index{fold mark}, or folding marks, are small horizontal rules in +the left margin and small vertical rules in the top margin. \KOMAScript{} +currently provides three configurable horizontal fold marks and one +configurable vertical fold mark. Additionally it provides a horizontal +hole-punch or page-centre mark. This additional mark cannot be moved +vertically. + +The \Option{foldmarks} option activates or deactivates fold marks for two, +three, or four vertical divisions and one horizontal division. The individual +parts do not have to be of equal size. The positions of three of the four +horizontal marks and the single vertical mark are configurable via +pseudo-lengths (see \autoref{sec:scrlttr2-experts.foldmarks} starting on +\DescPageRef{scrlttr2-experts.plength.foldmarkvpos}). + +With the \Option{foldmarks} option, you can either use the default values for +simple switches described in \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch} in order to activate or deactivate all +configured fold marks on the left and upper edges of the paper at once, +or\ChangedAt{v2.97e}{\Class{scrlttr2}} you can configure the individual fold +marks independently by specifying one or more letters, as listed in +\autoref{tab:\LabelBase.foldmark}. In the latter case, the fold marks are only +shown if they have not been deactivated globally with \PValue{false}, +\PValue{off}, or \PValue{no}. The exact position of the fold marks is depends +on the user settings or the \File{lco} files (see +\autoref{sec:\LabelBase.lcoFile} starting on +\autopageref{sec:\LabelBase.lcoFile}). The default values are \PValue{true} +and \PValue{TBMPL}.\textnote{default} % \begin{table} % \centering @@ -992,25 +1017,25 @@ chosen for a letter. Default values are \PValue{true} and \PValue{TBMPL}. \setcapindent{0pt}% % \caption \begin{captionbeside}{% - Combinable values for the configuration of folding marks with - option \Option{foldmarks}% + Combinable values for configuring fold marks with the + \Option{foldmarks} option% }[l] \begin{tabular}[t]{ll} \toprule - \PValue{B} & activate upper horizontal foldmark on left paper edge\\% - \PValue{b} & deactivate upper horizontal foldmark on left paper edge\\% - \PValue{H} & activate all horizontal folding marks on left paper edge\\% - \PValue{h} & deactivate all horizontal folding marks on left paper edge\\% - \PValue{L} & activate left vertical foldmark on upper paper edge\\% - \PValue{l} & deactivate left vertical foldmark on upper paper edge\\% - \PValue{M} & activate middle horizontal foldmark on left paper edge\\% - \PValue{m} & deactivate middle horizontal foldmark on left paper edge\\% - \PValue{P} & activate punch or center mark on left paper edge\\% - \PValue{p} & deactivate punch or center mark on left paper edge\\% - \PValue{T} & activate lower horizontal foldmark on left paper edge\\% - \PValue{t} & deactivate lower horizontal foldmark on left paper edge\\% - \PValue{V} & activate all vertical folding marks on upper paper edge\\% - \PValue{v} & deactivate all vertical folding marks on upper paper edge\\% + \PValue{B} & activate bottom horizontal fold mark on left paper edge\\% + \PValue{b} & deactivate bottom horizontal fold mark on left paper edge\\% + \PValue{H} & activate all horizontal fold marks on left paper edge\\% + \PValue{h} & deactivate all horizontal fold marks on left paper edge\\% + \PValue{L} & activate left vertical fold mark on upper paper edge\\% + \PValue{l} & deactivate left vertical fold mark on upper paper edge\\% + \PValue{M} & activate middle horizontal fold mark on left paper edge\\% + \PValue{m} & deactivate middle horizontal fold mark on left paper edge\\% + \PValue{P} & activate hole-punch or centre mark on left paper edge\\% + \PValue{p} & deactivate hole-punch or centre mark on left paper edge\\% + \PValue{T} & activate top horizontal fold mark on left paper edge\\% + \PValue{t} & deactivate top horizontal fold mark on left paper edge\\% + \PValue{V} & activate all vertical fold marks on upper paper edge\\% + \PValue{v} & deactivate all vertical fold marks on upper paper edge\\% \bottomrule \end{tabular} \end{captionbeside} @@ -1018,59 +1043,57 @@ chosen for a letter. Default values are \PValue{true} and \PValue{TBMPL}. \end{table} % \begin{Example} - Assume that you would like to deactivate all folding marks except the punching - mark. This you can accomplish with, for example: + Suppose you want to deactivate all fold marks except the hole-punch mark. If + the default has not already been changed, you can deactivate it as follows: \begin{lstlisting} \KOMAoptions{foldmarks=blmt} \end{lstlisting} - as long as the defaults have not been changed previously. If some changes - might have been made before, a safer method should be used. This changes our - example a little bit: + If there is a chance that the default has already been changed, you should + use a safer method. This changes our example a little bit: \lstinputcode[xleftmargin=1em]{letter-7}% The result is shown in \autoref{fig:\LabelBase.letter-7}. \begin{figure} \setcapindent{0pt}% - \begin{captionbeside}[{Example: letter with addressee, opening, text, - closing, postscript, distribution list, enclosure, and hole puncher + \begin{captionbeside}[{Example: letter with recipient, opening, text, + closing, postscript, distribution list, enclosure, and hole-punch mark}]{% - result of a small letter with addressee, opening, text, closing, - postscript, distribution list, enclosure, and hole puncher mark - (the date is a default of DIN-letters)}[l] + result of a short letter with recipient, opening, text, closing, + postscript, distribution list, enclosure, and hole-punch mark + (the date is set by default)}[l] \frame{\includegraphics[width=.4\textwidth]{letter-7}} \end{captionbeside} \label{fig:\LabelBase.letter-7} \end{figure} \end{Example} \BeginIndex{FontElement}{foldmark}\LabelFontElement{foldmark}% -The color of the folding mark may be changed -using\ChangedAt{v2.97c}{\Class{scrlttr2}} using the commands -\DescRef{\LabelBase.cmd.setkomafont} and -\DescRef{\LabelBase.cmd.addtokomafont} (see +You\ChangedAt{v2.97c}{\Class{scrlttr2}} can change the colour of the fold mark +with the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont}) -with element \FontElement{foldmark}. Default is not change.% -\EndIndex{FontElement}{foldmark}% -% +with the \FontElement{foldmark} element. The default is no change.% \EndIndexGroup \begin{Declaration} \OptionVName{enlargefirstpage}{simple switch} \end{Declaration} -The first page of a letter always uses a different page layout. The -\Class{scrlttr2} class provides a mechanism to calculate height and vertical -alignment of header and footer of the first page independently of the -following pages. If, as a result, the footer of the first page would reach -into the text area, this text area is automatically made smaller using the -\Macro{enlargethispage}\IndexCmd{enlargethispage} macro. On the other hand, if -the text area should become larger, supposing that the footer on the first -page allows that, you can use this option. At best, a little more text will -then fit on the first page. See also the description of the pseudo-length -\PLength{firstfootvpos} on -\DescPageRef{scrlttr2-experts.plength.firstfootvpos}. This option can -take the standard values for simple switches, as listed in -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. Default is -\PValue{false}. -% +\begin{Explain} + The first page of a letter always uses a different page layout because of + the many predefined elements such as the letterhead or the address. The + \Class{scrlttr2} class provides a mechanism to calculate height and vertical + alignment of header and footer of the first page independently of the + subsequent pages. If, as a result, the footer of the first page would + protrude into the text area, this text area of the first page is + automatically reduced using + \Macro{enlargethispage}\IndexCmd{enlargethispage}. +\end{Explain} +If the text area should become larger, assuming the footer on the first page +permits this, you can use this option. At best, a little more text will then +fit on the first page. See also the description of the \PLength{firstfootvpos} +pseudo-length on \DescPageRef{scrlttr2-experts.plength.firstfootvpos}. This +option takes the standard values for simple switches, as listed in +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. The default +is \PValue{false}.\textnote{default}% \EndIndexGroup @@ -1078,12 +1101,12 @@ take the standard values for simple switches, as listed in \OptionVName{firsthead}{simple switch} \end{Declaration} \BeginIndex{}{letterhead}% -\BeginIndex{}{letter>head}% +\BeginIndex{}{letter>header}% The\ChangedAt{v2.97e}{\Class{scrlttr2}} letterhead is usually the topmost -element of the note paper. This option determines whether the letterhead will -be typeset at all. The option accepts the standard values for simple keys, -given in \autoref{tab:truefalseswitch} at -\autopageref{tab:truefalseswitch}. Default is for the letterhead to be set.% +element of the letterhead page. With the \Option{firsthead} option, you can +choose whether the letterhead will be typeset at all. The option accepts the +standard values for simple switches given in \autoref{tab:truefalseswitch} on +\autopageref{tab:truefalseswitch}. The default is to typeset the letterhead.% % \EndIndexGroup @@ -1093,47 +1116,49 @@ given in \autoref{tab:truefalseswitch} at \end{Declaration} \BeginIndex{}{letterhead}% \BeginIndex{}{letter>head}% -Option\important{\Option{fromalign}} \Option{fromalign} defines the placement -of the return address in the letterhead of the first page. Apart from the -various options for positioning the return address in the letterhead, there is -also the option\ChangedAt{v2.97e}{\Class{scrlttr2}} of adding the return -address to the sender's extension\Index{sender's - extension}. Further\textnote{Attention!}, this option serves as a switch to -activate or deactivate the letterhead extensions. If these extensions are -deactivated, some other options will have no effect. This will be noted in the -explanations of the respective options. Possible values for \Option{fromalign} -are shown in \autoref{tab:\LabelBase.fromalign}. Default is \PValue{left}.% +The\important{\Option{fromalign}} \Option{fromalign} option determines where +the sender information should be placed on the first page. In addition to the +various placement options in the letterhead, you also have the +ability\ChangedAt{v2.97e}{\Class{scrlttr2}} to accommodate extra sender +information\Index{extra sender information}. At the same +time\textnote{Attention!}, this option serves as a central switch to activate +or deactivate letterhead extensions. If these extensions are deactivated, some +other options will have no effect. This will be noted in the explanations of +the respective options. Available values for \Option{fromalign} are shown in +\autoref{tab:\LabelBase.fromalign}. The default value is \PValue{left}.% % \begin{table} - \caption[{Available values for option \Option{fromalign} with - \Class{scrlttr2}}]{Available values for option \Option{fromalign} to + \caption[{Available values for the \Option{fromalign} option with + \Class{scrlttr2}}]{Available values for the \Option{fromalign} option to define the position of the from address in the letterhead with \Class{scrlttr2}} \label{tab:\LabelBase.fromalign} \begin{desctabular} \entry{\PValue{center}, \PValue{centered}, \PValue{middle}}{% - return address centered; an optional logo will be above the extended - return address; letterhead extensions will be activated}% + Sender information is centred inside the letterhead; a logo is + placed at the beginning of the extra sender information, if + applicable; letterhead extensions are activated.}% \entry{\PValue{false}, \PValue{no}, \PValue{off}}{% - standard design will be used for the return address; the letterhead - extensions are deactivated}% + The default design will be used for the sender information; the + letterhead extensions are deactivated.}% \entry{\PValue{left}}{% - left-justified return address; an optional logo will be right justified; - letterhead extensions will be activated}% + Sender information is left-aligned in the letterhead; a logo is + placed right-aligned, if applicable; letterhead extensions are + activated.}% \entry{\PValue{locationleft}, \PValue{leftlocation}}{% - return address is set left-justified in the sender's extension; a logo, - if applicable, will be placed above it; the letterhead is automatically - deactivated but can be reactivated using option - \DescRef{\LabelBase.option.firsthead}.}% + Sender information is left-justified and uses the extra sender + information; a logo is placed at the top of it, if applicable; the + letterhead is automatically deactivated but can be reactivated using the + \DescRef{\LabelBase.option.firsthead} option.}% \entry{\PValue{locationright}, \PValue{rightlocation}, \PValue{location}}{% - return address is set right-justified in the sender's extension; a logo, - if applicable, will be placed above it; the letterhead is automatically - deactivated but can be reactivated using option - \DescRef{\LabelBase.option.firsthead}.}% + Sender information is right-justified and uses the extra sender + information; a logo is placed at the top of it, if applicable; the + letterhead is automatically deactivated but can be reactivated using the + \DescRef{\LabelBase.option.firsthead} option.}% \entry{\PValue{right}}{% - right-justified return address; an optional logo will be left justified; - letterhead extensions will be activated}% + Sender information is right-justified; a logo is placed left-justified, + if applicable; letterhead extensions are activated}% \end{desctabular} \end{table} % @@ -1147,31 +1172,31 @@ are shown in \autoref{tab:\LabelBase.fromalign}. Default is \PValue{left}.% \end{Declaration} \BeginIndex{}{letterhead}% \BeginIndex{}{letter>head}% -The\important{\Variable{fromname}} sender's name will be determined by -variable \Variable{fromname}. Thereby the \PName{description} (see also -\autoref{tab:\LabelBase.fromTerm}, \autopageref{tab:\LabelBase.fromTerm}) will not -be used by the predefined letterheads. +The\important{\Variable{fromname}} sender's name is determined by the +\Variable{fromname} variable. Its \PName{description} (see also +\autoref{tab:\LabelBase.fromTerm}, \autopageref{tab:\LabelBase.fromTerm}) is +not used in the default letterheads. -At\important{\OptionValue{fromrule}{aftername}} the extended letterhead an -optional horizontal rule below the name may be selected using +In\important{\OptionValue{fromrule}{aftername}} the extended letterhead, you +can create a horizontal rule below the sender's name with \OptionValue{fromrule}{aftername}. -Alternatively\important[i]{\begin{tabular}{@{}l@{}} - \KOption{fromrule}\\\quad\PValue{afteraddress}\end{tabular}} this rule may -be placed below the while sender using \OptionValue{fromrule}{afteraddress}. A -summary of all available rule position settings shows -\autoref{tab:\LabelBase.fromrule}. The length of this rule is determined by -pseudo-length \PLength{fromrulewidth}\IndexPLength[indexmain]{fromrulewidth}. +Alternatively\important{\OptionValue{fromrule}{afteraddress}} you can place +this rule below the complete sender information with +\OptionValue{fromrule}{afteraddress}. A summary of all available settings for +the rule position is shown in \autoref{tab:\LabelBase.fromrule}. The length of +this rule is determined by the +\PLength{fromrulewidth}\IndexPLength[indexmain]{fromrulewidth} pseudo-length. \begin{table} - \caption[{Possible values of option \Option{fromrule} with - \Class{scrlttr2}}]{Possible values of option \Option{fromrule} for the - position of the rule in the from address with + \caption[{Available values of the \Option{fromrule} option with + \Class{scrlttr2}}]{Available values of the \Option{fromrule} option for the + position of the rule in the sender information with \Class{scrlttr2}} \label{tab:\LabelBase.fromrule} \begin{desctabular} \entry{\PValue{afteraddress}, \PValue{below}, \PValue{on}, \PValue{true}, \PValue{yes}}{% - rule below the return address}% + rule below the sender's address}% \entry{\PValue{aftername}}{% rule directly below the sender's name}% \entry{\PValue{false}, \PValue{no}, \PValue{off}}{% @@ -1179,100 +1204,101 @@ pseudo-length \PLength{fromrulewidth}\IndexPLength[indexmain]{fromrulewidth}. \end{desctabular} \end{table} -Default for the rule at the extended letterhead is \PValue{false}. But at the -standard letterhead the rule will always be placed below the sender's name. +The default\textnote{default} for the rule with the extended letterhead is +\PValue{false}. But in the standard letterhead, the rule will always be placed +below the sender's name. -The\important{\Variable{fromaddress}} sender's address follows below the -name. The \PName{content} of variable \Variable{fromaddress} determines this -address. The \PName{description} (see also \autoref{tab:\LabelBase.fromTerm}) -will not be used at the predefined letterheads +The\important{\Variable{fromaddress}} sender's address follows below the name. +The \PName{content} of variable \Variable{fromaddress} determines this +address. The address \PName{description} (see also +\autoref{tab:\LabelBase.fromTerm}) is not used in the default letterheads \BeginIndexGroup \BeginIndex{FontElement}{fromaddress}\LabelFontElement{fromaddress}% \BeginIndex{FontElement}{fromname}\LabelFontElement{fromname}% \BeginIndex{FontElement}{fromrule}\LabelFontElement{fromrule}% -The font of the whole address is determined by the element +You can set the font used for the complete sender information with the \FontElement{fromaddress}\IndexFontElement{fromaddress}% -\important{\FontElement{fromaddress}}. Modifications to this may be defined -with element \FontElement{fromname}\IndexFontElement{fromname}% -\important{\FontElement{fromname}} for the sender's name and with element +\important{\FontElement{fromaddress}} element. You can define modifications to +this with the \FontElement{fromname}\IndexFontElement{fromname}% +\important{\FontElement{fromname}} element for the sender's name, and with the \FontElement{fromrule}\IndexFontElement{fromrule}% -\important{\FontElement{fromrule}} for the rule, that may be activated using -option \Option{fromrule}. Nevertheless changing the font style of the rule -would make sense. But you may use the elements also to change the color, -e.\,g. color the rule gray instead of black. See \cite{package:xcolor} for -information about colors.% +\important{\FontElement{fromrule}} element for the rule created with the +\Option{fromrule} option. The default setting does not change the font. For +the rule, font switching is mainly intended to change the colour of the rule, +for example to use grey instead of black. See \cite{package:xcolor} for +information about colours.% % \EndIndexGroup \begin{Example} - Let's now define the name of the sender at our letter example: + Now let's give the sender of our sample letter a name: \lstinputcode[xleftmargin=1em]{letter-8.tex} \begin{figure} \centering \frame{\includegraphics[width=.4\textwidth]{letter-8}}\quad \frame{\includegraphics[width=.4\textwidth]{letter-9}} - \caption[{Example: letter with sender, addressee, opening, text, closing, + \caption[{Example: letter with sender, recipient, opening, text, closing, postscript, distribution list, and enclosure}] - {result of a small letter with sender, addressee, opening, text, closing, - postscript, distribution list, and enclosure (date and folding marks are - defaults of DIN-letters): at left one the standard letterhead using - \OptionValueRef{\LabelBase}{fromalign}{false}, at right one the + {result of a short letter with sender, recipient, opening, text, closing, + postscript, distribution list, and enclosure (the date is set by + default): on the left, the standard letterhead using + \OptionValueRef{\LabelBase}{fromalign}{false}; on the right, the extended letterhead using \OptionValueRef{\LabelBase}{fromalign}{center}} \label{fig:\LabelBase.letter-8-9} \end{figure} - First of all not the extended but the standard letterhead has been used. The - result is shown at the left side of \autoref{fig:\LabelBase.letter-8-9}. The - right side shows almost the same letter but with - \OptionValueRef{\LabelBase}{fromalign}{center} and therefore with the extended - letterhead. You may see, that this variation is without any rule. - - For the first time \autoref{fig:\LabelBase.letter-8-9} also shows a signature - below the closing phrase. This has been generated automatically from the - sender's name. More information about configuration of the signature may be - found in \autoref{sec:\LabelBase.closing} from - \autopageref{sec:\LabelBase.closing} onward. - - Now, the letter with extended letterhead should use option \Option{fromrule} - to print a rule below the sender's name:% + Initially, the standard rather than the extended letterhead is used. The + result can be seen in \autoref{fig:\LabelBase.letter-8-9} on the left. For + comparison, the same example is shown on the right with + \OptionValueRef{\LabelBase}{fromalign}{center} (that is, with the extended + letterhead). You can see that this variation initially has no rule. + + For the first time, \autoref{fig:\LabelBase.letter-8-9} also shows a + signature below the closing phrase. This is generated automatically from the + sender's name. You can find more information about how to configure the + signature in \autoref{sec:\LabelBase.closing}, starting on + \autopageref{sec:\LabelBase.closing}. + + Next, the letter with the extended letterhead should use the + \Option{fromrule} option to print a rule below the sender's name:% \lstinputcode[xleftmargin=1em]{letter-11.tex}% - The result may be found at the right side of - \autoref{fig:\LabelBase.letter-10-11}. + You can see the result on the right in + \autoref{fig:\LabelBase.letter-10-11}. By comparison, the same example on + the left uses the standard letterhead, which ignores the additional options. + % \begin{figure} \centering \frame{\includegraphics[width=.4\textwidth]{letter-10}}\quad \frame{\includegraphics[width=.4\textwidth]{letter-11}} - \caption[{Example: letter with sender, separation rule, addressee, + \caption[{Example: letter with sender, rule, recipient, opening, text, closing, signature, postscript, distribution list, - enclosure, and puncher hole mark}] - {result of a small letter with sender, separation rule, addressee, + enclosure, and hole-punch mark}] + {result of a short letter with sender, rule, recipient, opening, text, closing, signature, postscript, distribution list, - enclosure and puncher hole mark (the date is a default of DIN-letters): + enclosure and hole-punch mark (the date is set by default): at left one the standard letterhead using \OptionValueRef{\LabelBase}{fromalign}{false}, at right one the extended letterhead using \OptionValueRef{\LabelBase}{fromalign}{center}} \label{fig:\LabelBase.letter-10-11} \end{figure} - In difference to this, the left letter has been set once again with the - standard letter head, that does not react on the additional option. \end{Example} An\textnote{Attention!} important note concerns the sender's address: within -the sender's address, parts such as street, P.O.~Box, state, country, etc., -are separated with a double backslash. Depending on how the sender's address -is used, this double backslash will be interpreted differently and therefore -is not strictly always a line break. Paragraphs, vertical spacing and the like -are usually not allowed within the sender's address declaration. One has to -have very good knowledge of \Class{scrlttr2} to use things like those -mentioned above, intelligently. Another point to note is the one should most -certainly set the variables for return address (see variable -\DescRef{\LabelBase.variable.backaddress}, \DescPageRef{\LabelBase.variable.backaddress}) and -signature (see variable \DescRef{\LabelBase.variable.signature}, -\DescPageRef{\LabelBase.variable.signature}) oneself.% +the sender's address, individual parts such as house number and street, city +and postal code, etc., are separated with a double backslash. This double +backslash is interpreted differently depending on how the sender's address is +used and therefore is not necessarily a line break. Paragraphs, vertical +spacing, and the like are usually not allowed within the sender's information. +You have to know \KOMAScript{} very well to put such things into the sender +information, if necessary. In addition, note that if you do so, you should +definitely set the variables for return address (see +\DescRef{\LabelBase.variable.backaddress}, +\DescPageRef{\LabelBase.variable.backaddress}) and signature (see +\DescRef{\LabelBase.variable.signature}, +\DescPageRef{\LabelBase.variable.signature}) yourself.% % \EndIndexGroup - \begin{Declaration} \OptionVName{symbolicnames}{simple switch}% \OptionVName{fromphone}{simple switch}% @@ -1290,42 +1316,47 @@ signature (see variable \DescRef{\LabelBase.variable.signature}, \Variable{faxseparator}% \Variable{emailseparator}% \Variable{urlseparator}% -\end{Declaration}% +\end{Declaration} \BeginIndex{}{letterhead}% -\BeginIndex{}{letter>head}% -Whether or not a telephone number\Index{telephone}\Index{phone}, a -mobile\ChangedAt{v3.12}{\Class{scrlttr2}} telephone number\Index{mobile - phone}\Index{cell phone}\Index{cellphone}, a fax number\Index{fax}, an -e-mail address\Index{e-mail}, or a sender's URL should be set as part of the -letterhead may be configured by the options \Option{fromphone}, -\Option{fromfax}, \Option{fromemail}, and \Option{fromurl}. Any standard value -for simple switches from \autoref{tab:truefalseswitch}, -\autopageref{tab:truefalseswitch} may be assigned to these options. Default is -\PValue{false} for all of them. The \PName{contents} depends on the -corresponding variable. The default of the \PName{description} or title of -each variable may be found in \autoref{tab:\LabelBase.fromTerm}. The separators, -that will be inserted between \PName{description} and \PName{content}, may be -found in \autoref{tab:\LabelBase.fromSeparator}. - -You may\ChangedAt{v3.12}{\Class{scrlttr2}}\important{\Option{symbolicnames}} -change the defaults for the description of the separator variables at once -using option \Option{symbolicnames}. The option understands the values for -simple switches from \autoref{tab:truefalseswitch}, -\autopageref{tab:truefalseswitch}. Switching on the option replaces the -descriptions from the language depending terms \DescRef{scrlttr2-experts.cmd.emailname}, -\DescRef{scrlttr2-experts.cmd.faxname}, \DescRef{scrlttr2-experts.cmd.mobilephonename}, and \DescRef{scrlttr2-experts.cmd.phonename} into symbols -of the package \Package{marvosym}\IndexPackage{marvosym}. Also the colon will -be removed from the content of the separator variables. And in this case the -description and the content of the URL separator will be -empty. Note\textnote{Attention!}, that you have to load package -\Package{marvosym} on your own, if you switch on \Option{symbolicnames} -first time after \Macro{begin}\PParameter{document}. +\BeginIndex{}{letter>header} +\iffree{\clearpage}{} +You can use the five options \Option{fromphone}, \Option{fromfax}, +\Option{fromemail}, and \Option{fromurl} to specify whether to include the +phone number\Index{telephone}\Index{phone}, +mobile\ChangedAt{v3.12}{\Class{scrlttr2}} phone number\Index{mobile +phone}\Index{cell phone}\Index{cellphone}, fax number\Index{fax}, e-mail +address\Index{e-mail}, or sender's URL should be as part of the sender's +information. You can assign any standard value for simple switches from +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} to these +options. The default for all of them is \PValue{false}. The \PName{contents} +themselves are determined by the variables of the same name. You can find the +defaults for the \PName{description} or title of each variable in +\autoref{tab:\LabelBase.fromTerm}. You can find the separators that will be +inserted between the \PName{description} and the \PName{content} in +\autoref{tab:\LabelBase.fromSeparator}. + +You can\ChangedAt{v3.12}{\Class{scrlttr2}}\important{\Option{symbolicnames}} +change the defaults for describing the variables all at once with the +\Option{symbolicnames} option. This option understands the values for simple +switches found in \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch}. Activating the option replaces the +descriptions from the language-dependant labels of +\DescRef{scrlttr2-experts.cmd.emailname}, +\DescRef{scrlttr2-experts.cmd.faxname}, +\DescRef{scrlttr2-experts.cmd.mobilephonename}, and +\DescRef{scrlttr2-experts.cmd.phonename} with symbols from the +\Package{marvosym}\IndexPackage{marvosym} package. At the same time, the colon +is omitted when defining the separators. In this case, both the description +and the content of the URL separator will be empty. Note\textnote{Attention!} +that you have to load the \Package{marvosym} package on your own if you activate +\Option{symbolicnames} for the first time after +\Macro{begin}\PParameter{document}. \begin{table} \centering - \caption[{Predefined descriptions of the variables of the - letterhead}]{Predefined descriptions of the variables of the letterhead - (the description and contents of the separator variables may be found at + \caption[{Default descriptions of the letterhead variables}]{Default + descriptions of the letterhead variables (you can find the description and + contents of the separator variables in \autoref{tab:\LabelBase.fromSeparator}} \begin{desctabular}[1.8em] \ventry{fromemail}{\DescRef{\LabelBase.cmd.usekomavar*}\PParameter{emailseparator}% @@ -1346,13 +1377,12 @@ first time after \Macro{begin}\PParameter{document}. \end{table} \begin{table}[tp] -% \centering - \KOMAoptions{captions=topbeside}% - \setcapindent{0pt}% -% \caption - \begin{captionbeside}{Predefined description and content of the separators - at the letterhead without option \Option{symbolicnames}} - [l] + \centering +% \KOMAoptions{captions=topbeside}% +% \setcapindent{0pt}% + \caption{Default descriptions and contents of the letterhead + separators without the \Option{symbolicnames} option} +% [l] \begin{tabular}[t]{lll} \toprule variable name & description & content \\ @@ -1364,56 +1394,58 @@ first time after \Macro{begin}\PParameter{document}. \Variable{urlseparator} & \DescRef{scrlttr2-experts.cmd.wwwname} & \texttt{:\~} \\ \bottomrule \end{tabular} - \end{captionbeside} +% \end{captionbeside} \label{tab:\LabelBase.fromSeparator} \end{table} \begin{Example} - Mr Public from the example letter has telephone and e-mail. He wants to show - this also in the letterhead. Furthermore the separation rule should be - placed below the letterhead. So he uses the corresponding options and - defines the content of the needed variables:% + Mr Public from our sample letter has a telephone and an e-mail address. He + also wants to show these in the letterhead. At the same time, the separation + rule should now be placed after the letterhead. So he uses the appropriate + options and also sets the required variables:% \lstinputcode[xleftmargin=1em]{letter-12.tex}% - Nevertheless the result at the left side of - \autoref{fig:\LabelBase.letter-12-13} is not disillusioning: the options are - ignored. That's the case because the additional variables and options will - be used at the extended letterhead only. So option \DescRef{\LabelBase.option.fromalign} has to - be used, like done at the right letter of + The results on the left side of \autoref{fig:\LabelBase.letter-12-13}, + however, are confounding: the options are ignored. That's because the + additional variables and options are only used in the extended letterhead. + So the \DescRef{\LabelBase.option.fromalign} option must be used, as it is + in the right side of \autoref{fig:\LabelBase.letter-12-13}. \begin{figure} \centering \frame{\includegraphics[width=.4\textwidth]{letter-12}}\quad \frame{\includegraphics[width=.4\textwidth]{letter-13}} - \caption[{Example: letter with extended sender, separation rule, addressee, - opening, text, closing, signature, postscript, distribution list, - enclosure, and puncher hole mark; standard vs. extended letterhead}] - {result of a small letter with sender, separation rule, addressee, - opening, text, closing, signature, postscript, distribution list, - enclosure and puncher hole mark (the date is a default of DIN-letters): - at left one the standard letterhead using - \OptionValueRef{\LabelBase}{fromalign}{false}, at right one the extended letterhead - using \OptionValueRef{\LabelBase}{fromalign}{center}} + \caption[{Example: letter with extra sender information, rule, + recipient, opening, text, closing, signature, postscript, distribution + list, enclosure, and hole-punch mark; standard vs. extended letterhead}] + {result of a short letter with sender, rule, recipient, opening, text, + closing, signature, postscript, distribution list, enclosure and + hole-punch mark (the date is set by default): the left one uses the + standard letterhead with + \OptionValueRef{\LabelBase}{fromalign}{false}; the right one uses the + extended letterhead with \OptionValueRef{\LabelBase}{fromalign}{center}} \label{fig:\LabelBase.letter-12-13} \end{figure} \lstinputcode[xleftmargin=1em]{letter-13.tex} - An arrangement of alternatives with left aligned using - \OptionValueRef{\LabelBase}{fromalign}{left} and right aligned sender - using \OptionValueRef{\LabelBase}{fromalign}{right} may be found in + You can compare two other alternatives with left-aligned sender information using + \OptionValueRef{\LabelBase}{fromalign}{left} and right-aligned sender information + using \OptionValueRef{\LabelBase}{fromalign}{right} in \autoref{fig:\LabelBase.letter-14-15}. \begin{figure} \centering \frame{\includegraphics[width=.4\textwidth]{letter-14}}\quad \frame{\includegraphics[width=.4\textwidth]{letter-15}} - \caption[{Example: letter with extended sender, separation rule, addressee, - opening, text, closing, signature, postscript, distribution list, - enclosure, and puncher hole mark; left vs. right aligned letterhead}] - {result of a small letter with sender, separation rule, addressee, - opening, text, closing, signature, postscript, distribution list, - enclosure and puncher hole mark (the date is a default of DIN-letters): - at left one left aligned letterhead using - \OptionValueRef{\LabelBase}{fromalign}{left}, at right one right aligned letterhead - using \OptionValueRef{\LabelBase}{fromalign}{right}} + \caption[{Example: letter with extra sender information, rule, + recipient, opening, text, closing, signature, postscript, distribution + list, enclosure, and hole-punch mark; left- vs. right-aligned + letterhead}] + {result of a short letter with extra sender information, rule, + recipient, opening, text, closing, signature, postscript, distribution + list, enclosure and hole-punch mark (the date is set by default): + the left one uses a left-aligned letterhead with + \OptionValueRef{\LabelBase}{fromalign}{left}; the right one uses a + right-aligned letterhead using + \OptionValueRef{\LabelBase}{fromalign}{right}} \label{fig:\LabelBase.letter-14-15} \end{figure} \end{Example} @@ -1427,37 +1459,38 @@ first time after \Macro{begin}\PParameter{document}. \end{Declaration} \BeginIndex{}{letterhead}% \BeginIndex{}{letter>head}% -With option \Option{fromlogo} you may configure whether or not to use a -logo\Index{Logo} at the letterhead. The option value may be any \PName{simple - switch} from \autoref{tab:truefalseswitch}, -\autopageref{tab:truefalseswitch}. Default is \PValue{false}, that means no -logo. The logo itself is defined by the \PName{content} of variable -\Variable{fromlogo}. The \PName{description} of the logo is empty by default -and \KOMAScript{} does not use it anywhere at the predefined note papers (see -also \autoref{tab:\LabelBase.fromTerm}).% +You can use the \Option{fromlogo} to configure whether to put a +logo\Index{Logo} in the letterhead. You can use any of the default values from +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} for the +\PName{simple switch}. The default is \PValue{false}, which means no logo. The +logo itself is defined by the \PName{content} of the \Variable{fromlogo} +variable. The \PName{description} of the logo is empty by default and +\KOMAScript{} does not use it in the default letterhead pages (see also +\autoref{tab:\LabelBase.fromTerm}).% \begin{Example} - Mr Public likes to use a letterhead with logo. He generated a graphics file - with the logo and would like to include this using - \Macro{includegraphics}. Therefor he uses the additional package - \Package{graphics}\IndexPackage{graphics} (see \cite{package:graphics}).% + Mr Public finds it particularly stylish when he provides his letterhead with + a logo. He has saved his logo as a graphics file, which he would like to + load using \Macro{includegraphics}. To do this, he uses the loads the + \Package{graphics}\IndexPackage{graphics} package (see + \cite{package:graphics}).% \lstinputcode[xleftmargin=1em]{letter-16}% - The result may be seen at the left top position of - \autoref{fig:\LabelBase.letter-16-18}. The additional letter prints at this - figure shows the result with right aligned or centered sender. + You can see the result in the top left of + \autoref{fig:\LabelBase.letter-16-18}. The other two images in this figure + show the results with right-aligned and centred sender information. \begin{figure} \setcapindent{0pt}% {\hfill \frame{\includegraphics[width=.4\textwidth]{letter-16}}\quad \frame{\includegraphics[width=.4\textwidth]{letter-17}}\par\bigskip} - \begin{captionbeside}[{Example: letter with extended sender, logo, - separation rule, addressee, opening, text, closing, signature, - postscript, distribution list, enclosure, and puncher hole mark; left - vs. right aligned vs. centered sender}] - {result of a small letter with extended sender, logo, separation rule, - addressee, opening, text, closing, signature, postscript, distribution - list, enclosure and puncher hole mark (the date is a default of - DIN-letters): at top left one left aligned sender using, at right - beneath one with centered sender, and at right one right aligned + \begin{captionbeside}[{Example: letter with extra sender information, + logo, rule, recipient, opening, text, closing, signature, postscript, + distribution list, enclosure, and hole-punch mark; left-aligned vs. + right-aligned vs. centred sender information}] + {result of a short letter with extra sender information, logo, rule, + recipient, opening, text, closing, signature, postscript, distribution + list, enclosure and hole-punch mark (the date is set by default): + at top left the sender is left-aligned, at top right the sender is + centred, and at bottom right the sender is right-aligned sender}[l] \frame{\includegraphics[width=.4\textwidth]{letter-18}}\quad \end{captionbeside} @@ -1471,35 +1504,26 @@ also \autoref{tab:\LabelBase.fromTerm}).% \begin{Declaration} \Variable{firsthead}% \end{Declaration} -\BeginIndex{}{letterhead}% -\BeginIndex{}{letter>head}% -For many cases, \Class{scrlttr2} with its options and variables offers -enough possibilities to create a letterhead. In very rare situations -one may wish to have more freedom in terms of layout. In those -situations one will have to do without predefined letterheads, which -could have been chosen via options. Instead, one needs to create one's -own letterhead from scratch. To do so, one has to define the preferred -construction as content of variable \Variable{firsthead}. Within -\Macro{firsthead}, and with the help of the \Macro{parbox} command -(see \cite{latex:usrguide}), one can set several boxes side by side, -or one underneath the other. An advanced user will thus be able to -create a letterhead on his own. Of course the construct may -and should use other variables with the help of +In many cases, the capabilities that \Class{scrlttr2} offers with the +foregoing options and variables will be sufficient to design a letterhead. In +some cases, however, you may want even more flexibility. In those situations, +you will have to do without the possibilities offered by the predefined +letterhead, which you can select via the options described above. Instead, you +must create your own letterhead from scratch. To do so, you must specify the +desired structure as the \PName{contents} of the \Variable{firsthead} +variable. For example, you can set several boxes side by side or one beneath +the other using the \Macro{parbox} command (see \cite{latex:usrguide}). +Experienced users should thus be able to create their own a letterheads. Of +course you can and should use other variables with \DescRef{\LabelBase.cmd.usekomavar}. \KOMAScript{} does not use the -\PName{description} of variable \Variable{firsthead}. -\iffree{}{A detailed example for the definition of a letterhead will be shown - in \autoref{cha:modernletters}.} - -The\textnote{Attention!} command -\Macro{firsthead}\IndexCmd[indexmain]{firsthead} exists only for reason of -compatibility to former \Class{scrlttr2} versions. However it is deprecated -and you should not use it anymore.% -% +\PName{description} of variable \Variable{firsthead}. \iffree{}{You can find + a detailed example of a letterhead definition in + \autoref{cha:modernletters}.}% \EndIndexGroup \begin{Declaration} - \OptionVName{addrfield}{mode}% + \OptionVName{addrfield}{format}% \OptionVName{backaddress}{value}% \OptionVName{priority}{priority}% \Variable{toname}% @@ -1514,110 +1538,112 @@ and you should not use it anymore.% \Variable{PPdatamatrix}% \Variable{addresseeimage}% \end{Declaration}% -\BeginIndex{}{addressee}% +\BeginIndex{}{address}% +The \Option{addrfield} option determines whether or not to print an address +field. The default\textnote{default} is to include an address field. The +option recognizes the formats described in +\autoref{tab:\LabelBase.addrfield}\ChangedAt{v3.03}{\Class{scrlttr2}}. With +the values \PValue{true}, +\PValue{topaligned}\ChangedAt{v3.17}{\Class{scrlttr2}\and +\Package{scrletter}}, \PValue{PP}, and \PValue{backgroundimage}, the name and +address of the recipient are determined by the mandatory argument of the +\DescRef{\LabelBase.env.letter} environment (see +\autoref{sec:\LabelBase.document}, \DescPageRef{\LabelBase.env.letter}). This +information is also copied into the variables \Variable{toname} and +\Variable{toaddress}. + \BeginIndexGroup \BeginIndex{FontElement}{addressee}\LabelFontElement{addressee}% \BeginIndex{FontElement}{toname}\LabelFontElement{toname}% \BeginIndex{FontElement}{toaddress}\LabelFontElement{toaddress}% -Option \Option{addrfield} defines whether or not to set an address -field. Default is to use an address field. This option can take the mode -values from -\autoref{tab:\LabelBase.addrfield}\ChangedAt{v3.03}{\Class{scrlttr2}}. Default -is \PValue{true}. With values \PValue{true}, -\PValue{topaligned}\ChangedAt{v3.17}{\Class{scrlttr2}\and - \Package{scrletter}}, \PValue{PP}, and -\PValue{backgroundimage} name and address of the addressee will be defined by -the mandatory argument of the \DescRef{\LabelBase.env.letter} environment (see -\autoref{sec:\LabelBase.document}, -\DescPageRef{\LabelBase.env.letter}). These elements will additionally be -copied into the variables \Variable{toname} and \Variable{toaddress}. The -predefined font styles may be changed\ChangedAt{v2.97c}{\Class{scrlttr2}} by -execution of command \DescRef{\LabelBase.cmd.setkomafont} or \DescRef{\LabelBase.cmd.addtokomafont} (siehe +You can change the default font styles\ChangedAt{v2.97c}{\Class{scrlttr2}} +with the \DescRef{\LabelBase.cmd.setkomafont} or +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, -\DescPageRef{\LabelBase.cmd.setkomafont}). Thereby three elements -exist. First of all element -\FontElement{addressee}\important{\FontElement{addressee}}, that is -responsible for the addressee overall. The additional elements -\FontElement{toname}\important{\FontElement{toname}} and +\DescPageRef{\LabelBase.cmd.setkomafont}). There are three elements. First, +the \FontElement{addressee}\important{\FontElement{addressee}} element is +responsible for the overall style of the recipient's name and address. The +elements \FontElement{toname}\important{\FontElement{toname}} and \FontElement{toaddress}\important{\FontElement{toaddress}} are responsible -only either for the name or the address of the addressee. They may be used to -define modifications from the \FontElement{addressee} configuration.% +only for the name and the address of the recipient, respectively. You can use +\FontElement{toname} and \FontElement{toaddress} to define modifications from +the basic \FontElement{addressee} configuration.% \EndIndexGroup - +% \begin{table} - \caption[{available values for option \Option{addrfield} using - \Class{scrlttr2}}]{available values for option \Option{addrfield} to - change the addressee mode of \Class{scrlttr2}}% + \caption[{available values for the \Option{addrfield} option with + \Class{scrlttr2}}]{available values for the \Option{addrfield} option to + change the recipient format of \Class{scrlttr2}}% \label{tab:\LabelBase.addrfield}% \begin{desctabular} \entry{\PValue{backgroundimage}, \PValue{PPbackgroundimage}, \PValue{PPBackgroundImage}, \PValue{PPBackGroundImage}, \PValue{ppbackgroundimage}, \PValue{ppBackgroundImage}, \PValue{ppBackGroundImage}}{% - Prints an address field with Port-Pay\'e head, in variable - \Variable{addresseimage} defined background graphics, but without return - address or mode of dispatch.}% + Prints an address with a background image stored in the + \Variable{addresseimage} variable as the postpaid postmark, but without + a return address or delivery type.}% \entry{\PValue{false}, \PValue{off}, \PValue{no}}{% - Omits the address field.}% + Does not print an address.}% \entry{\PValue{image}, \PValue{Image}, \PValue{PPimage}, \PValue{PPImage}, \PValue{ppimage}, \PValue{ppImage}}{% - Prints variable \Variable{addresseeimage} as addressee with Port-Pay\'e, - but ignores addressee information and definitions for return address, - mode of dispatch or priority.}% + Prints an image stored in the \Variable{addresseeimage} variable as an + address with a postpaid postmark. Recipient information, return address, + and delivery type or priority are ignored.}% \entry{\PValue{PP}, \PValue{pp}, \PValue{PPexplicite}, \PValue{PPExplicite}, \PValue{ppexplicite}, \PValue{ppExplicite}}{% - Prints an address field with Port-Pay\'e head, defined by the variables - \Variable{fromzipcode}, \Variable{place}, and \Variable{PPcode} and when - indicated with priority and data array defined by - \Variable{PPdatamatrix} but without return address and mode of - dispatch.}% + Prints an address with a postage print impression (pospaid) header + filled in with the variables \Variable{fromzipcode}, \Variable{place}, + and \Variable{PPcode}, and when applicable with a priority and a data + array defined by \Variable{PPdatamatrix}, but without a return address + or delivery type.}% \entry{\PValue{topaligned}, \PValue{alignedtop}% \ChangedAt{v3.17}{\Class{scrlttr2}\and \Package{scrletter}}}{% - Prints an address field including a return address and a mode of - dispatch or priority without centring the address vertically in the - available space.}% + Prints an address including a return address and a delivery type + or priority. The address is not centred vertically beneath the delivery + type.}% \entry{\PValue{true}, \PValue{on}, \PValue{yes}}{% - Prints an address field including a return address and a mode of - dispatch or priority.}% + Prints an address field including a return address and delivery type + or priority.}% \end{desctabular} \end{table}% -With the default \OptionValue{addrfield}{true} an additional return address -will be printed. Option \Option{backaddress} defines whether a return address -for window envelopes will be set. This -option\important{\OptionValue{backaddress}{false}} can take the standard -values for simple switches, as listed in \autoref{tab:truefalseswitch}, +The default \OptionValue{addrfield}{true} also prints an underlined return +address in the address field. The \Option{backaddress} option defines if and +in what form a return address will be printed for window envelopes. On the one +hand, this option\important{\OptionValue{backaddress}{false}} accepts the +standard values for simple switches listed in \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. These values do not change style of the -return address. On the other hand, -additionally\ChangedAt{v2.96}{\Class{scrlttr2}} to switching on the return -address, the style of the return address may be selected. Option value -\PValue{underlined} selects an underlined return address. In opposite to -this value \PValue{plain}\important{\OptionValue{backaddress}{plain}} selects -a style without underline. Default is \PValue{underlined} and therefore -printing an underlined return address. - -\BeginIndex{FontElement}{backaddress}\LabelFontElement{backaddress}% -The return address itself is defined by the \PName{content} of variable -\Variable{backaddress}. Default is a combination of variable \Variable{toname} -and \Variable{toaddress} with redefinition of the double backslash to set the -\PName{content} of variable \Variable{backaddressseparator}. The predefined -separator \PName{content} is a comma followed by a non-breakable white -space. The \PName{description} of variable \Variable{backaddress} is not used -by \KOMAScript. The font style of the return address is configurable via -element -\FontElement{backaddress}\important{\FontElement{backaddress}}. Default for -this is \Macro{sffamily} (see -\autoref{tab:\LabelBase.AddresseeElements}). Before execution of the element's -font style \KOMAScript{} switches to \Macro{scriptsize}.% -\EndIndex{FontElement}{backaddress}% - -By default, \OptionValue{addrfield}{true}, the address will be vertically -centred in the available space below the mode of dispatch or -priority. In\ChangedAt{v3.17}{\Class{scrlttr2}\and \Package{scrletter}} -opposite to this, \OptionValue{addrfield}{topaligned}% +return address. On the other hand, when\ChangedAt{v2.96}{\Class{scrlttr2}} the +return address is enabled, you can select its format at the same time. For +example, the \PValue{underlined} option value enables an underlined return +address, while \PValue{plain}\important{\OptionValue{backaddress}{plain}} +selects a style without underlining. The default is \PValue{underlined} and +thus prints an underlined return address. + +The return address itself is defined by the \PName{content} of the +\Variable{backaddress} variable. The default is the name specified in +\DescRef{\LabelBase.variable.fromname} and the address specified in +\DescRef{\LabelBase.variable.fromaddress}. The double backslash is also +replaced with the \PName{content} of the \Variable{backaddressseparator} +variable. The default separator is a comma followed by a non-breaking space. +\KOMAScript{} does not use the \PName{description} of the +\Variable{backaddress} variable. +\BeginIndexGroup\BeginIndex{FontElement}{backaddress}% +\LabelFontElement{backaddress}% +You can configure the font style of the return address via the +\FontElement{backaddress}\important{\FontElement{backaddress}} element. The +default is \Macro{sffamily} (see \autoref{tab:\LabelBase.AddresseeElements}). +Before applying the element's font style \KOMAScript{} switches to +\Macro{scriptsize}.% +\EndIndexGroup + +The default \OptionValue{addrfield}{true}, centres the address vertically +within the space available for the address. +In\ChangedAt{v3.17}{\Class{scrlttr2}\and \Package{scrletter}} contrast, +\OptionValue{addrfield}{topaligned}% \important{\OptionValue{addrfield}{topaligned}} will not centre the address -but follow it aligned top at the available space. This is the only difference -to \OptionValue{addrfield}{true}.% +but place it flush with the top of the available space.% \begin{table} % \centering @@ -1625,7 +1651,7 @@ to \OptionValue{addrfield}{true}.% \setcapindent{0pt}% % \caption \begin{captionbeside}{% - Predefined font style for the elements of the address field.% + Default font styles for the elements of the address field.% }% [l] \begin{tabular}[t]{ll} @@ -1663,52 +1689,54 @@ to \OptionValue{addrfield}{true}.% \label{tab:\LabelBase.AddresseeElements}% \end{table} -\BeginIndex{FontElement}{specialmail}\LabelFontElement{specialmail}% -At the default \OptionValue{addrfield}{true} an optional dispatch -type\Index{mode of dispatch}\Index{dispatch type} can be output within the -address field between the return address and the addressee address, This will -be done only if variable \Variable{specialmail} is not empty and +\BeginIndexGroup +\BeginIndex{FontElement}{specialmail}\LabelFontElement{specialmail} +With the default \OptionValue{addrfield}{true} setting, you can output an +optional delivery type\Index{delivery type} between the return address and the +recipient address. This will be output only if the \Variable{specialmail} +variable has non-empty content and \OptionValue{priority}{manual}\ChangedAt{v3.03}{\Class{scrlttr2}} has been -selected, which is also the default. Class \Class{scrlttr2} itself does not use -the \PName{description} of variable \Variable{specialmail}. The alignment is -defined by the pseudo-lengths PLength{specialmailindent} and -\PLength{specialmailrightindent} (siehe -\DescPageRef{scrlttr2-experts.plength.specialmailindent}). The predefined -font style of element\ChangedAt{v2.97c}{\Class{scrlttr2}} -\FontElement{specialmail}\important{\FontElement{specialmail}}, that has been -listed in \autoref{tab:\LabelBase.AddresseeElements}, may be changed using -commands \DescRef{\LabelBase.cmd.setkomafont} and \DescRef{\LabelBase.cmd.addtokomafont} (see +selected, which is the default. The \Class{scrlttr2} class itself does not use +the \PName{description} of the \Variable{specialmail} variable. The alignment +is defined by the \PLength{specialmailindent} and +\PLength{specialmailrightindent} pseudo-lengths (see +\DescPageRef{scrlttr2-experts.plength.specialmailindent}). You can change the +default font style of the\ChangedAt{v2.97c}{\Class{scrlttr2}} +\FontElement{specialmail}\important{\FontElement{specialmail}} element, which +is listed in \autoref{tab:\LabelBase.AddresseeElements}, with the +\DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont}).% -\EndIndex{FontElement}{specialmail}% +\EndIndexGroup \BeginIndexGroup \BeginIndex{FontElement}{priority}\LabelFontElement{priority}% \BeginIndex{FontElement}{prioritykey}\LabelFontElement{prioritykey}% -\BeginIndex{FontElement}{PPlogo}\LabelFontElement{PPlogo}% -On\ChangedAt{v3.03}{\Class{scrlttr2}}\important[i]{\OptionValue{priority}{A}\\ - \OptionValue{priority}{B}} the other hand, using an international priority +However\ChangedAt{v3.03}{\Class{scrlttr2}}\important{\normalcolor + \OptionValue{priority}{A}\\ + \normalcolor\OptionValue{priority}{B}}, selecting an international priority with \OptionValue{priority}{A} or \OptionValue{priority}{B} (see -\autoref{tab:\LabelBase.priority}) together with \OptionValue{addrfield}{true} -will print the priority as mode of dispatch. Using it together with -\OptionValue{addrfield}{PP}\important{\OptionValue{addrfield}{PP}} will print -the priority at the corresponding position in the Port-Pay\'e head. Thereby -the element \FontElement{priority} defines the basic font style and -\FontElement{prioritykey} the modification of the basic font style for the -priority key, ``A'' or ``B''. The Port-Pay\'e logo ``P.~P.'' uses the font -style of element \FontElement{PPlogo}. The default font styles are listed in -\autoref{tab:\LabelBase.AddresseeElements} and may be changed using commands -\DescRef{\LabelBase.cmd.setkomafont} und -\DescRef{\LabelBase.cmd.addtokomafont} (siehe +\autoref{tab:\LabelBase.priority}) together with +\OptionValue{addrfield}{true}, prints the priority as the delivery type. Using +it together with +\OptionValue{addrfield}{PP}\important{\OptionValue{addrfield}{PP}} prints the +priority at the corresponding position in the postpaid postmark (also known as +the postage print impression or \emph{port pay\'e}). The \FontElement{priority} +element defines the basic font style, and \FontElement{prioritykey} defines +the modification of the basic font style for the priority keys ``A'' or ``B''. +You can find the default font styles listed in +\autoref{tab:\LabelBase.AddresseeElements} and can change then using the +\DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont}).% \EndIndexGroup - \begin{table} - \caption[{available values for option \Option{priority} in - \Class{scrlttr2}}]{available values for option \Option{priority} to select - the international priority at the address field of\Class{scrlttr2}} + \caption[{available values for the \Option{priority} option in + \Class{scrlttr2}}]{available values for the \Option{priority} option to + select the international priority in the address field of\Class{scrlttr2}} \label{tab:\LabelBase.priority} \begin{desctabular} \entry{\PValue{false}, \PValue{off}, \PValue{no}, \PValue{manual}}{% @@ -1717,99 +1745,106 @@ style of element \FontElement{PPlogo}. The default font styles are listed in \PValue{ECONOMY}, \PValue{B-ECONOMY}, \PValue{B-Economy}, \PValue{b-economy}}{% Use international priority B-Economy. With - \OptionValue{addrfield}{true} this will be printed instead of the mode - of dispatch.}% + \OptionValue{addrfield}{true}, this is printed instead of the delivery + type.}% \entry{\PValue{A}, \PValue{a}, \PValue{priority}, \PValue{Priority}, \PValue{PRIORITY}, \PValue{A-PRIORITY}, \PValue{A-Priority}, \PValue{a-priority}}{% Use international priority A-Priority. With - \OptionValue{addrfield}{true} this will be printed instead of the mode - of dispatch.}% + \OptionValue{addrfield}{true}, this is printed instead of the delivery + type.}% \end{desctabular} \end{table} With\ChangedAt{v3.03}{\Class{scrlttr2}}\important{\OptionValue{addrfield}{PP}} -\OptionValue{addrfield}{PP} also the zip-code of -variable \Variable{fromzipcode} and the place from \PName{content} of variable -\Variable{place} will be set in the Port-Pay\'e head. Thereby the -\PName{content} of variable \Variable{fromzipcode} will be preceded by the -\PName{description} of variable \Variable{fromzipcode} and the \PName{content} -of variable \Variable{zipcodeseparator}. The predefined \PName{description} -depends on the used \File{lco}-file (see \autoref{sec:\LabelBase.lcoFile} from -\autopageref{sec:\LabelBase.lcoFile} onward). On the other hand the default of -the \PName{content} of variable \Variable{zipcodeseparator} is a small -distance followed by an endash followed by one more small distance +\OptionValue{addrfield}{PP}, the postal code in the \Variable{fromzipcode} +variable and the location from the \Variable{place} pariable will be output in +the postpaid postmark. The postal code (that is, the \PName{content} of +\Variable{fromzipcode}) is preceded by the \PName{description} of the +\Variable{fromzipcode} variable and the \PName{content} of +\Variable{zipcodeseparator}. The default for the \PName{description} depends +on the \File{lco} file used (see \autoref{sec:\LabelBase.lcoFile} starting on +\autopageref{sec:\LabelBase.lcoFile}). On the other hand, the default +\PName{content} of the \Variable{zipcodeseparator} variable is a thin space +followed by an en rule followed by another thin space (\Macro{,}\texttt{-{}-}\Macro{,}). -Beyond\ChangedAt{v3.03}{\Class{scrlttr2}} that, with -\OptionValue{addrfield}{PP}\important{\OptionValue{addrfield}{PP}} and -sender's identification code will be used at the Port-Pay\'e head. This is the -\PName{content} of variable \Variable{PPcode}. Right beside the address of the -addressee an additional data array may be printed. The \PName{content} of -variable \Variable{PPdatamatrix} will be used for this. - -\BeginIndex{FontElement}{PPdata}\LabelFontElement{PPdata}% -Zip-code\ChangedAt{v3.03}{\Class{scrlttr2}}, place and code will be printed -with default font size 8\Unit{pt}. Thereby the font style of element -\FontElement{PPdata}\important{\FontElement{PPdata}} will be used. The default -of the element is listed in \autoref{tab:\LabelBase.AddresseeElements} and may -be changed using commands \DescRef{\LabelBase.cmd.setkomafont} and \DescRef{\LabelBase.cmd.addtokomafont} (see +With\ChangedAt{v3.03}{\Class{scrlttr2}} +\OptionValue{addrfield}{PP}\important{\OptionValue{addrfield}{PP}}, a code is +placed in the postpaid postmark that uniquely identifies the sender. This is +stored in the \Variable{PPcode} variable. You can also print an additional +data array to the right of the address, which is stored in the +\Variable{PPdatamatrix} variable. + +\BeginIndexGroup +\BeginIndex{FontElement}{PPdata}\LabelFontElement{PPdata} +The ZIP code\ChangedAt{v3.03}{\Class{scrlttr2}} (postal code), place, and +sender code will be printed by default in an 8\Unit{pt} font. The the font +style of the \FontElement{PPdata}\important{\FontElement{PPdata}} is used to +do so. The default is listed in \autoref{tab:\LabelBase.AddresseeElements} and +can be changed with the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont}).% -\EndIndex{FontElement}{PPdata}% +\EndIndexGroup -With\important[i]{\begin{tabular}[t]{@{}l@{}} - \KOption{addrfield}\\\quad\PValue{backgroundimage}\end{tabular}\strut\\ - \strut\OptionValue{addrfield}{image}} options +\BeginIndexGroup +\BeginIndex{FontElement}{PPlogo}\LabelFontElement{PPlogo} For the postpaid +logo ``P.P.'', however, the font style of the +\FontElement{PPlogo}\important{\FontElement{PPlogo}} element is used. Its +default can also be found in \autoref{tab:\LabelBase.AddresseeElements}.% +\EndIndexGroup + +With\important{\OptionValue{addrfield}{backgroundimage}\\ + \OptionValue{addrfield}{image}} the two settings \OptionValue{addrfield}{backgroundimage}\ChangedAt{v3.03}{\Class{scrlttr2}} -or \OptionValue{addrfield}{image} a picture will be print inside the address -field. The \PName{content} of variable \Variable{addresseeimage} will be used -for this. \KOMAScript{} does not use the \PName{description} of that -variable. Nothing else but the picture will be printed with option -\OptionValue{addrfield}{image}. But with option -\OptionValue{addrfield}{backgroundimage} the addressee's name and address from +and \OptionValue{addrfield}{image}, an image is print inside the address +window. This image is stored in the \PName{content} of variable +\Variable{addresseeimage}. \KOMAScript{} does not use the \PName{description} +of this variable. Although only the image is printed with the +\OptionValue{addrfield}{image} option, the recipient's name and address from the mandatory argument of the \DescRef{\LabelBase.env.letter} environment will -be output. +be printed with the \OptionValue{addrfield}{backgroundimage} option. -The alignment of the Port-Pay\'e head as long as the alignment of the -Port-Pay\'e address is defined by pseudo-length \PLength{toaddrindent} (see +The position of the postpaid postmark and that of the +postpaid address is defined by the \PLength{toaddrindent} pseudo-length (see \DescPageRef{scrlttr2-experts.plength.toaddrindent}) as well as -\PLength{PPheadwidth} and \PLength{PPheadheight} (siehe -\DescPageRef{scrlttr2-experts.plength.PPheadheight}). The alignment of -the data array is defined by pseudo-length \PLength{PPdatamatrixvskip} +\PLength{PPheadwidth} and \PLength{PPheadheight} (see +\DescPageRef{scrlttr2-experts.plength.PPheadheight}). The position of +the data array is defined by the \PLength{PPdatamatrixvskip} pseudo-length (see \DescPageRef{scrlttr2-experts.plength.PPdatamatrixvskip}). -Please note\textnote{Attention!} that \KOMAScript{} itself cannot set any -external graphics or pictures. So, if you want to put external picture files +Note\textnote{Attention!} that \KOMAScript{} cannot print any external +graphics or pictures by itself. So if you want to put external picture files into variables like \Variable{addresseeimage} or \Variable{PPdatamatrix}, you -have to use an additional graphics package like +must load an additional graphics package like \Package{graphics}\IndexPackage{graphics} or -\Package{graphicx}\IndexPackage{graphicx} to use, i.\,e., the command -\Macro{includegraphics} at the \PName{content} of the variables.% +\Package{graphicx}\IndexPackage{graphicx} and use, for instance, the +\Macro{includegraphics} command in the \PName{content} of the variables.% % \EndIndexGroup \begin{Declaration} - \OptionVName{locfield}{selection} + \OptionVName{locfield}{setting} \end{Declaration} -\BeginIndex{}{sender>additional information}% -\Class{scrlttr2} places a field with additional sender attributes next to the -address field. This can be used, for example, for bank account -or similar additional information. -Depending\important[i]{\OptionValueRef{\LabelBase}{fromalign}{center}\\ - \begin{tabular}[t]{@{}l@{}} - \KOption{fromalign}\\\quad\PValue{locationleft}\end{tabular}\\ - \begin{tabular}[t]{@{}l@{}} - \KOption{fromalign}\\\quad\PValue{locationright}\end{tabular}} on the +\BeginIndex{}{extra sender information}% +In addition to the address field, \Class{scrlttr2} can print a field with +extra sender attributes next to the address field. Its content can be +anything you want, for example a location, a bank-account number, or other +information. Depending\important{% + \OptionValueRef{\LabelBase}{fromalign}{locationleft}\\ + \OptionValueRef{\LabelBase}{fromalign}{center}\\ + \OptionValueRef{\LabelBase}{fromalign}{locationright}} on the \DescRef{\LabelBase.option.fromalign} option, it will also be used for the -sender logo. The width of this field may be defined within an \File{lco} file -(see \autoref{sec:\LabelBase.lcoFile}). If the width is set to 0 in that file, -then the \Option{locfield} option can toggle between two presets for -the field width. See the explanation on the \PLength{locwidth} pseudo -length in \autoref{sec:scrlttr2-experts.locationField}, -\DescPageRef{scrlttr2-experts.plength.locwidth}. Possible values for this -option are shown in \autoref{tab:\LabelBase.locfield}. Default is +sender's logo. The width of this field can be specified in an \File{lco} file +(see \autoref{sec:\LabelBase.lcoFile}). If the width is set to zero there, the +\Option{locfield} option can toggle between two defaults for the field width. +This is the case for most of the \File{lco} files that come with +\KOMAScript{}. See also the explanation on the \PLength{locwidth} +pseudo-length in \autoref{sec:scrlttr2-experts.locationField}, +\DescPageRef{scrlttr2-experts.plength.locwidth}. Available values for this +option are shown in \autoref{tab:\LabelBase.locfield}. The default is \PValue{narrow}.% % \begin{table} @@ -1818,16 +1853,16 @@ option are shown in \autoref{tab:\LabelBase.locfield}. Default is \setcapindent{0pt}% % \caption \begin{captionbeside} - [{Possible values of option \Option{locfield} with - \Class{scrlttr2}}]{Possible values of option \Option{locfield} for - setting the width of the field with additional sender attributes with + [{Available values of the \Option{locfield} option with + \Class{scrlttr2}}]{Available values of the \Option{locfield} option to + set the width of the field for extra sender information with \Class{scrlttr2}% \label{tab:\LabelBase.locfield}}% [l] \begin{minipage}[t]{.45\linewidth} \begin{desctabular}[t] - \pventry{narrow}{narrow sender supplement field}% - \pventry{wide}{wide sender supplement field}% + \pventry{narrow}{narrow extra sender information field}% + \pventry{wide}{wide extra sender information field}% \end{desctabular} \end{minipage} \end{captionbeside} @@ -1836,36 +1871,34 @@ option are shown in \autoref{tab:\LabelBase.locfield}. Default is \begin{Declaration} \Variable{location}% \end{Declaration} -\BeginIndex{}{sender>additional information}% -The contents of the sender's extension field is determined by the -variable \Variable{location}. To set this variable's \PName{content}, it is -permitted to use formatting commands like \Macro{raggedright}. \KOMAScript{} -does not use the \PName{description} of the variable. +The contents of the extra sender information field, unless it contains +the logo or the basic sender information itself, are specified by the +\Variable{location} variable. You can use formatting commands like +\Macro{raggedright} within this variable's \PName{content}. \KOMAScript{} does +not use the \PName{description} of this variable. \begin{Example} - Mr Public likes to show some additional information about his - membership. Therefor he uses the \Variable{location} variable:% + Mr Public would like to provide some additional information about his + membership. Therefore he uses the \Variable{location} variable:% \lstinputcode[xleftmargin=1em]{letter-19.tex}% - This will define the field beside the addressee's address like shown in - \autoref{fig:\LabelBase.letter-19}. + This will place the corresponding field beside the recipient's address, as + shown in \autoref{fig:\LabelBase.letter-19}. \begin{figure} \setcapindent{0pt}% \begin{captionbeside}[{Example: letter with extended sender, logo, - addressee, additional sender information, opening, - text, closing, signature, postscript, distribution list, enclosure, - and puncher hole mark}] - {result of a small letter with extended sender, logo, - addressee, additional sender information, opening, text, closing, - signature, postscript, distribution list, enclosure and puncher hole - mark (the date is a default of DIN-letters)}[l] + recipient, extra sender information, opening, text, closing, + signature, postscript, distribution list, enclosure, and hole-punch + mark}] + {result of a short letter with extended sender, logo, recipient, + extra sender information, opening, text, closing, signature, + postscript, distribution list, enclosure, and hole-punch mark (the + date is set by default)}[l] \frame{\includegraphics[width=.4\textwidth]{letter-19}} \end{captionbeside} \label{fig:\LabelBase.letter-19} \end{figure} \end{Example} -% \EndIndexGroup -% \EndIndexGroup @@ -1874,30 +1907,30 @@ does not use the \PName{description} of the variable. \end{Declaration} This option toggles between the standard, language-dependent date\Index{date}\Index{reference line} presentation, and a short, numerical -one. {\KOMAScript} does not provide the standard presentation. It should be -defined by packages such as \Package{ngerman}\IndexPackage{ngerman}, +one. \KOMAScript{} does not provide the standard date format. It should be +defined by a package such as \Package{ngerman}\IndexPackage{ngerman}, \Package{babel}\IndexPackage{babel}, or \Package{isodate}\IndexPackage{isodate}. The\important{\OptionValue{numericaldate}{true}} short, numerical -presentation, on the other hand, is produced by \Class{scrlttr2} itself. This -option can take the standard values for simple switches, as listed in -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. Default is -\PValue{false}, which results in standard date presentation. +representation, however, is produced by \Class{scrlttr2} itself. The option +recognizes the standard values for simple switches as listed in +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. The default +is \PValue{false}, which results in standard date format. \begin{Declaration} \Variable{date}% \end{Declaration} -The date in the selected presentation will become the \PName{content} of -variable \Variable{date}. The selection of option -\DescRef{\LabelBase.option.numericaldate} does not influence the date any -longer, if the \PName{content} of this variable will be changed by the -user. Normally the date will be part of the reference line. If all other -elements of the reference line will be empty and therefore unused a date line -instead of a reference line will be printed. See the description of variable +The date in the selected format is stored as \PName{content} of the +\Variable{date} variable. Setting the +\DescRef{\LabelBase.option.numericaldate} option has no effect if this +variable is overridden. The date is usually output as part of the reference +line. If all other elements of the reference line are empty, a date line +consisting of the location and the date is printed instead. However in this +case, the settings of the \DescRef{\LabelBase.option.refline} option described +below also affect the date line. See the description of variable \DescRef{\LabelBase.variable.place} on \DescPageRef{\LabelBase.variable.placeseparator} for more information about -the date line. You should note, that you can change the automatic printing of -the date using option \DescRef{\LabelBase.option.refline}, that will be described next. +the location. % \EndIndexGroup \EndIndexGroup @@ -1907,37 +1940,39 @@ the date using option \DescRef{\LabelBase.option.refline}, that will be describe \OptionVName{refline}{selection} \end{Declaration} \BeginIndex{}{reference line}% -\index{business line|see{reference line}}% | -Especially in business letters a line with information like identification -code\Index{identification>code}, direct dial, customer's number, invoice's -number, or references to previous letters may be found usually. This line will -be named \emph{reference line}\textnote{reference line} in this manual. - -With the \Class{scrlttr2} class, the header, footer, address, and sender -attributes may extend beyond the normal type area to the left and to the -right. Option \OptionValue{refline}{wide} defines that this should also apply to -the reference fields line. Normally, the reference fields line contains at -least the date, but it can hold additional data. Possible values for this -option are shown in \autoref{tab:\LabelBase.refline}. Default is \PValue{narrow} -and \PValue{dateright}\ChangedAt{v3.09}{\Class{scrlttr2}}.% +\index{business line|see{reference line}}% +Business letters in particular often contain an area with information such as +an identification code\Index{identification code}, phone +extension\Index{phone>extension}, customer number\Index{customer number}, +invoice number\Index{invoice number}, or references to previous letters. This +guide calls this area the \emph{reference-field line}\textnote{reference-field + line}, or simply the \emph{reference line}. + +With \Class{scrlttr2} and \Package{scrletter}, the header, footer, address, +and extra sender information can extend left and right beyond the normal +type area. The +\OptionValue{refline}{wide}\important{\OptionValue{refline}{wide}} option +specifies that this should also apply to the reference-field line. Normally, +the reference-field line contains at least the date, but it can hold +additional data. Available values for this option are shown in +\autoref{tab:\LabelBase.refline}. The default is \PValue{narrow} and +\PValue{dateright}\ChangedAt{v3.09}{\Class{scrlttr2}}.% % \begin{table} - \caption[{Possible value of option \Option{refline} with - \Class{scrlttr2}}]{Possible value of option \Option{refline} for setting - the width of the reference fields line with - \Class{scrlttr2}} + \caption[{Available values of the \Option{refline} option with + \Class{scrlttr2}}]{Available value of the \Option{refline} option to set + the width of the reference line with \Class{scrlttr2}} \label{tab:\LabelBase.refline} \begin{desctabular} \pventry{dateleft}{\ChangedAt{v3.09}{\Class{scrlttr2}}% - The date will be placed leftmost at the reference line.}% + The date is placed leftmost in the reference line.}% \pventry{dateright}{\ChangedAt{v3.09}{\Class{scrlttr2}}% - The date will be placed rightmost at the reference line.}% - \pventry{narrow}{The reference line will be restricted to type - area.}% + The date is placed rightmost in the reference line.}% + \pventry{narrow}{The reference line is restricted to the type area.}% \pventry{nodate}{\ChangedAt{v3.09}{\Class{scrlttr2}}% The date is not placed automatically into the reference line.}% - \pventry{wide}{The with of the reference line corresponds to address and - sender's additional information.}% + \pventry{wide}{The width of the reference line depends on the positions of + the address and extra sender information.}% \end{desctabular} \end{table} @@ -1948,58 +1983,60 @@ and \PValue{dateright}\ChangedAt{v3.09}{\Class{scrlttr2}}.% \Variable{customer}% \Variable{invoice}% \end{Declaration} -These five variables represent typical fields of the reference line. Their -meanings are given in \autoref{tab:\LabelBase.variables} on -\autopageref{tab:\LabelBase.variables}. Each variable has also a predefined -\PName{description}, shown in \autoref{tab:\LabelBase.reflineTerm}. Additional -information about adding other variables to the reference line may be found -in \autoref{sec:scrlttr2-experts.variables} from -\DescPageRef{scrlttr2-experts.cmd.newkomavar} onward.% +You can manage the typical contents of the reference-field line with five +variables: \Variable{yourref}, \Variable{yourmail}, \Variable{myref}, +\Variable{customer} and \Variable{invoice}. Their meanings are listed in +\autoref{tab:\LabelBase.variables} on \autopageref{tab:\LabelBase.variables}. +Each variable has also a predefined \PName{description}, shown in +\autoref{tab:\LabelBase.reflineTerm}. How to add more variables to the +reference-field line is explained in \autoref{sec:scrlttr2-experts.variables} +starting on \DescPageRef{scrlttr2-experts.cmd.newkomavar}.% % \begin{table} % \centering \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% % \caption - \begin{captionbeside}[{predefined descriptions of variables of the reference - line}]{predefined descriptions of typical variables of the reference - fields line using macros depending on the current language}% + \begin{captionbeside}[{default descriptions of variables in the + reference line}]{default descriptions of typical variables in the + reference line using language-dependent commands}% [l] \begin{tabular}[t]{lll} \toprule - variable name & description & e.\,g., in english \\ + name & description & English default text\\ \midrule \Variable{yourref} & \DescRef{scrlttr2-experts.cmd.yourrefname} & Your reference \\ \Variable{yourmail} & \DescRef{scrlttr2-experts.cmd.yourmailname} & Your letter from \\ \Variable{myref} & \DescRef{scrlttr2-experts.cmd.myrefname} & Our reference \\ \Variable{customer} & \DescRef{scrlttr2-experts.cmd.customername} & Customer No.: \\ \Variable{invoice} & \DescRef{scrlttr2-experts.cmd.invoicename} & Invoice No.: \\ - \DescRef{\LabelBase.variable.date} & \DescRef{scrlttr2-experts.cmd.datename} & date \\ + \DescRef{\LabelBase.variable.date} & \DescRef{scrlttr2-experts.cmd.datename} & date \\ \bottomrule \end{tabular} \end{captionbeside} \label{tab:\LabelBase.reflineTerm} \end{table} +\BeginIndexGroup \BeginIndex{FontElement}{refname}\LabelFontElement{refname}% \BeginIndex{FontElement}{refvalue}\LabelFontElement{refvalue}% -Font style and color\ChangedAt{v2.97c}{\Class{scrlttr2}} of the -\PName{description} and \PName{content} of the fields of the reference line -may be changed with elements \FontElement{refname}% +You\ChangedAt{v2.97c}{\Class{scrlttr2}} can change the font style and colour +of the \PName{description} and \PName{content} of the fields in the reference +line with the \FontElement{refname}% \important[i]{\FontElement{refname}\\\FontElement{refvalue}} and -\FontElement{refvalue}. Therefor the commands \DescRef{\LabelBase.cmd.setkomafont} and \DescRef{\LabelBase.cmd.addtokomafont} (see +\FontElement{refvalue} elements using the \DescRef{\LabelBase.cmd.setkomafont} +and \DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, -\DescPageRef{\LabelBase.cmd.setkomafont}) should be used. The default -configuration of both elements is listed in -\autoref{tab:\LabelBase.refnamerefvalue}.% +\DescPageRef{\LabelBase.cmd.setkomafont}). The defaults for both elements are +listed in \autoref{tab:\LabelBase.refnamerefvalue}.% \begin{table}[tp] % \centering \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% % \caption \begin{captionbeside} - [{font style default of elements of the reference line}]{default font - style configuration of the elements of the reference line% + [{default font styles for elements in the reference line}]{default font + style settings for the elements in the reference line% \label{tab:\LabelBase.refnamerefvalue}} [l] \begin{tabular}[t]{ll} @@ -2013,8 +2050,6 @@ configuration of both elements is listed in \end{captionbeside} \end{table}% % -\EndIndex{FontElement}{refvalue}% -\EndIndex{FontElement}{refname}% \EndIndexGroup @@ -2022,48 +2057,56 @@ configuration of both elements is listed in \Variable{placeseparator}% \end{Declaration}% \BeginIndex{Variable}{place}% -If all variables of the reference line are empty, the line will be omitted. -In this case, the \PName{content} of \DescRef{\LabelBase.variable.place} and -\Variable{placeseparator} will be set, followed by the \PName{content} of -\DescRef{\LabelBase.variable.date}. The predefined \PName{content} of the -\Variable{placeseparator} is a comma followed by a non-breaking space. If the -variable \DescRef{\LabelBase.variable.place} has no \PName{content} value then -the hyphen remains unset also. The predefined \PName{content} of -\DescRef{\LabelBase.variable.date} is \Macro{today}\IndexCmd{today} and -depends on the setting of the option \DescRef{\LabelBase.option.numericaldate} -(see \DescPageRef{\LabelBase.option.numericaldate}). - -Since version~3.09\ChangedAt{v3.09}{\Class{scrlttr2}} place and date the -alignment of place and date is given by option \DescRef{\LabelBase.option.refline}. The available -alignment values for this option are listed in \autoref{tab:\LabelBase.refline}. +If all variables in the reference-field line, with the exception of +\DescRef{\LabelBase.variable.date}% +\important{\DescRef{\LabelBase.variable.date}}\IndexVariable{date}, are empty, +no actual reference line is output. Instead, a date line consisting only of a +location\Index{location} and a date\Index{date} is output. The \PName{content} +of the \DescRef{\LabelBase.variable.place} variable contains the location. The +delimiter, which in this case is placed after the location, is specified by +the \PName{content} of the \Variable{placeseparator} variable. The +default\textnote{default} \PName{content} of the delimiter is a comma followed +by a non-breaking space. If the location is empty, the delimiter is not +output. The default \PName{content} of \DescRef{\LabelBase.variable.date} is +\Macro{today}\IndexCmd{today} and depends on the setting of the +\DescRef{\LabelBase.option.numericaldate} option (see +\DescPageRef{\LabelBase.option.numericaldate}). + +Starting with version~3.09\ChangedAt{v3.09}{\Class{scrlttr2}}, the location +and date are no longer required to be right-aligned. Instead, when a date +line is used, its alignment is specified by the date setting of the +\DescRef{\LabelBase.option.refline} option, as listed in +\autoref{tab:\LabelBase.refline}. +\BeginIndexGroup \BeginIndex{FontElement}{placeanddate}\LabelFontElement{placeanddate}% -The\ChangedAt{v3.12}{\Class{scrlttr2}} font setting of place and date in the -date line are given by font -element\FontElement{placeanddate}\important[i]{\FontElement{placeanddate}} -instead of element \DescRef{\LabelBase.fontelement.refvalue}, which would be used for general -reference lines. You can change the empty default of the font element using -commands \DescRef{\LabelBase.cmd.setkomafont} and \DescRef{\LabelBase.cmd.addtokomafont} (see +If\ChangedAt{v3.12}{\Class{scrlttr2}} such a date line is output with a +location rather than a reference-field line, the font setting of the +\DescRef{\LabelBase.fontelement.refvalue} element does not apply. In this +case, the \FontElement{placeanddate}\important{\FontElement{placeanddate}} +element is used. You can change the empty default of this font element as +usual with the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont}).% -\EndIndex{FontElement}{placeanddate}% +\EndIndexGroup \begin{Example} - Now Mr Public also sets the place:% + Now Mr Public also sets the variable for the location:% \lstinputcode[xleftmargin=1em]{letter-20.tex}% - In this case \autoref{fig:\LabelBase.letter-20} shows the place and the - automatic separator in front of the date. The date has been defined - explicitly to make the printed date independent from the date of the - \LaTeX{} run. + As seen in \autoref{fig:\LabelBase.letter-20}, the location appears + in front of the date, followed by the automatic delimiter. This date has + been defined explicitly so that the original date is maintained in any later + \LaTeX{} run rather than using the date of the \LaTeX{} run. \begin{figure} \setcapindent{0pt}% \begin{captionbeside}[{Example: letter with extended sender, logo, - addressee, additional sender information, place, date, opening, + recipient, extra sender information, location, date, opening, text, closing, signature, postscript, distribution list, enclosure, - and puncher hole mark}] - {result of a small letter with extended sender, logo, addressee, - additional sender information, place, date, opening, text, closing, - signature, postscript, distribution list, enclosure and puncher hole + and hole-punch mark}] + {result of a short letter with extended sender, logo, recipient, + extra sender information, location, date, opening, text, closing, + signature, postscript, distribution list, enclosure and hole-punch mark}[l] \frame{\includegraphics[width=.4\textwidth]{letter-20}} \end{captionbeside} @@ -2072,41 +2115,44 @@ commands \DescRef{\LabelBase.cmd.setkomafont} and \DescRef{\LabelBase.cmd.addtok \end{Example} % \EndIndexGroup -% +\EndIndexGroup \EndIndexGroup \begin{Declaration} \Variable{title}% \end{Declaration} -\BeginIndex{}{title}% +With \KOMAScript{}, you can also give a letter a title\Index{title}. The title +is centred, using the \Macro{LARGE} font size, and placed directly beneath the +reference-field line. + \BeginIndex{FontElement}{lettertitle}\LabelFontElement{lettertitle}% \BeginIndex{FontElement}{title}\LabelFontElement{title}% -With \Class{scrlttr2} a letter can carry an additional title. The title is -centered and set with font size \Macro{LARGE} directly after and beneath the -reference fields line. The predefined font setup for the element -\FontElement{lettertitle}\important{\FontElement{lettertitle}} can be changed -with commands \DescRef{\LabelBase.cmd.setkomafont} und \DescRef{\LabelBase.cmd.addtokomafont} (see +You can change the font style for the +\FontElement{lettertitle}\important{\FontElement{lettertitle}} element with +the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont}). Font size declarations are -allowed. Font size \Macro{LARGE} is not part of the predefined default -\Macro{normalcolor}\Macro{sffamily}\Macro{bfseries} but nevertheless will be -used before the font style of the element. With \Class{scrlttr2} you can also -use \FontElement{title}\important{\FontElement{title}} as an alias of -\FontElement{lettertitle}. This is not provided using \Package{scrletter} with -a \KOMAScript{} class, because these classes already define an element -\FontElement{title} with different meaning for the document title.% +allowed. The \Macro{LARGE} font size always precedes the font selection in +\KOMAScript{}, and is therefore not part of the default setting +\Macro{normalcolor}\Macro{sffamily}\Macro{bfseries}. With \Class{scrlttr2}, +you can also use \FontElement{title}\important{\FontElement{title}} as an +alias for \FontElement{lettertitle}. This is not possible when using +\Package{scrletter} with a \KOMAScript{} class because these classes already +define a \FontElement{title} element for the document title with different +setting.% \EndIndex{FontElement}{title}% \EndIndex{FontElement}{lettertitle}% \begin{Example} - Assume that you are to write a reminder. Thus you put as title: + Suppose you are writing a reminder letter. You set a corresponding title: \begin{lstlisting} \setkomavar{title}{Reminder} \end{lstlisting} - This way the addressee will recognize a reminder as such. + This way the recipient should recognize the reminder as such. \end{Example} -Like shown in the example, the \PName{content} of the variable defines the -title. \KOMAScript{} will not use the \PName{description}.% +As shown in the example, the \PName{content} of the variable defines the +title. \KOMAScript{} does not use the \PName{description}.% % \EndIndexGroup @@ -2117,23 +2163,22 @@ title. \KOMAScript{} will not use the \PName{description}.% \Variable{subjectseparator}% \end{Declaration} \BeginIndex{}{subject}% -In case a subject should be set, the \PName{content} of the variable -\Variable{subject} need to be defined. First of all with option -\OptionValue{subject}{true}\important{\OptionValue{subject}{titled}} the usage -of the \PName{description} before the output of the subject may be -configured. See \autoref{tab:\LabelBase.subjectTerm} for the predefined -\PName{description}. In case of using the \PName{description} the -\PName{content} of variable \Variable{subjectseparator}\Index{separator} will -be set between the \PName{description} and \PName{content} of the -\Variable{subject}. The predefined \PName{content} of \PName{subjectseparator} -is a colon followed by a white space. +To include a subject, define the \PName{content} of the \Variable{subject} +variable accordingly. First of all, you can use the +\OptionValue{subject}{true}\important{\OptionValue{subject}{titled}} option, +to choose whether the subject should be preceded with a \PName{description} or +not. If you use the \PName{description} the \PName{content} of the +\Variable{subjectseparator}\Index{separator} variable is output between the +\PName{description} and the \PName{content} of the \Variable{subject} +variable. The default \PName{content} of \PName{subjectseparator} consists of +a colon followed by a space. \begin{table} % \centering \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% % \caption - \begin{captionbeside}{predefined descriptions of subject-related variables} + \begin{captionbeside}{default descriptions of variables for the subject} [l] \begin{tabular}[t]{lll} \toprule @@ -2150,17 +2195,18 @@ is a colon followed by a white space. \label{tab:\LabelBase.subjectTerm} \end{table} -On the other hand, \OptionValue{subject}{afteropening}% -\important{\OptionValue{subject}{afteropening}} may be used to place the -subject below instead of before the letter opening. Furthermore, the -formatting\important[i]{\OptionValue{subject}{underlined}\\ +Additionally, you can use \OptionValue{subject}{afteropening}% +\important{\OptionValue{subject}{afteropening}\\ + \OptionValue{subject}{beforeopening}} to place the subject after the letter +opening instead of the default \OptionValue{subject}{beforeopening}. You can +also specify other formatting\important{\OptionValue{subject}{underlined}\\ \OptionValue{subject}{centered}\\ - \OptionValue{subject}{right}} of the subject may be changed using either + \OptionValue{subject}{right}} for the subject with \OptionValue{subject}{underlined}, \OptionValue{subject}{centered}, or -\OptionValue{subject}{right}\ChangedAt{v2.97c}{\Class{scrlttr2}}. All -available values are listed in \autoref{tab:\LabelBase.subject}. Please -note\textnote{Attention!}, that with option \OptionValue{subject}{underlined} -the while subject must fit at one line! Defaults are +\OptionValue{subject}{right}\ChangedAt{v2.97c}{\Class{scrlttr2}}. The +available values are listed in \autoref{tab:\LabelBase.subject}. +Note\textnote{Attention!} that with the \OptionValue{subject}{underlined} +option, the whole subject must fit onto one line. The defaults are \OptionValue{subject}{left}, \OptionValue{subject}{beforeopening}, and \OptionValue{subject}{untitled}.% % @@ -2170,8 +2216,8 @@ the while subject must fit at one line! Defaults are \setcapindent{0pt}% % \caption \begin{captionbeside} - [{available values of option \Option{subject} with \Class{scrlttr2}}] - {available values of option \Option{subject} for the position and + [{Available values of the \Option{subject} option with \Class{scrlttr2}}] + {Available values of the \Option{subject} option for the position and formatting of the subject with \Class{scrlttr2}\label{tab:\LabelBase.subject}}% [l] @@ -2179,49 +2225,51 @@ the while subject must fit at one line! Defaults are \begin{desctabular}[t] \pventry{afteropening}{subject after opening}% \pventry{beforeopening}{subject before opening}% - \pventry{centered}{subject centered}% + \pventry{centered}{subject centred}% \pventry{left}{subject left-justified}% \pventry{right}{subject right-justified}% \pventry{titled}{add title/description to subject}% - \pventry{underlined}{set subject underlined (see note in text please)}% + \pventry{underlined}{set subject underlined (see note in text)}% \pventry{untitled}{do not add title/description to subject}% \end{desctabular} \end{minipage} \end{captionbeside} \end{table} +\BeginIndexGroup \BeginIndex{FontElement}{lettersubject}\LabelFontElement{lettersubject}% \BeginIndex{FontElement}{subject}\LabelFontElement{subject}% -The subject line is set in a separate font\Index{font>style}. To change this -use the commands \DescRef{\LabelBase.cmd.setkomafont} and -\DescRef{\LabelBase.cmd.addtokomafont} (siehe +The subject line is set in a separate font\Index{font>style}. To change this, +use the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, -\DescPageRef{\LabelBase.cmd.setkomafont}). For element -\FontElement{lettersubject}\important{\FontElement{lettersubject}} the -predetermined font is \Macro{normalcolor}\Macro{bfseries}. With -\Class{scrlttr2} you can also use +\DescPageRef{\LabelBase.cmd.setkomafont}). For the +\FontElement{lettersubject}\important{\FontElement{lettersubject}} element, +the default font is \Macro{normalcolor}\Macro{bfseries}. With the +\Class{scrlttr2} class, you can also use \FontElement{subject}\important{\FontElement{subject}} as an alias of -\FontElement{lettersubject}. This is not provided using \Package{scrletter} -with a \KOMAScript{} class, because these classes already define an element -\FontElement{subject} with different meaning for the document title.% -\EndIndex{FontElement}{subject}% -\EndIndex{FontElement}{lettersubject}% +\FontElement{lettersubject}. This is not possible with the \Package{scrletter} +package when using a \KOMAScript{} class, because these classes already define +a \FontElement{subject} element for the document title with different +settings.% +\EndIndexGroup + \begin{Example} - Now, Mr Public sets a subject. He's a more traditional person, so he likes - to have a kind of heading to the subject and therefor sets the corresponding + Mr Public now includes a subject. As a traditionalist, he also wants the + subject to be labelled accordingly and therefore sets the corresponding option:% \lstinputcode[xleftmargin=1em]{letter-21.tex}% - The result is shown by \autoref{fig:\LabelBase.letter-21}. + The result is shown in \autoref{fig:\LabelBase.letter-21}. \begin{figure} \setcapindent{0pt}% \begin{captionbeside}[{Example: letter with extended sender, logo, - addressee, additional sender information, place, date, subject, + recipient, extra sender information, place, date, subject, opening, text, closing, signature, postscript, distribution list, - enclosure, and puncher hole mark}] - {result of a small letter with extended sender, logo, addressee, - additional sender information, place, date, subject opening, text, + enclosure, and hole-punch mark}] + {result of a short letter with extended sender, logo, recipient, + extra sender information, place, date, subject, opening, text, closing, signature, postscript, distribution list, enclosure and - puncher hole mark}[l] + hole-punch mark}[l] \frame{\includegraphics[width=.4\textwidth]{letter-21}} \end{captionbeside} \label{fig:\LabelBase.letter-21} @@ -2234,51 +2282,36 @@ with a \KOMAScript{} class, because these classes already define an element \begin{Declaration} \OptionVName{firstfoot}{simple switch} \end{Declaration} -\BeginIndex{}{letter>foot}% -\BeginIndex{}{letterfoot}% -This\ChangedAt{v2.97e}{\Class{scrlttr2}} option determines whether the -letterfoot is set or not. Switching off the letterfoot, e.\,g., using -\OptionValue{firstfoot}{false}\important{\OptionValue{firstfoot}{false}}, has -an effect when the option \DescRef{\LabelBase.option.enlargefirstpage} (see -\DescPageRef{\LabelBase.option.enlargefirstpage}) is used concurrently. In -this case the text area of the page will be enlarged down to the bottom. Then -the normal distance between typing area and the letter foot will become the -only distance remaining between the end of the typing area and the end of the -page. - -The option understands the standard values for simple switches, as given in -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. Default is -the setting of the letter foot. +\BeginIndex{}{letterhead page>footer}% +This\ChangedAt{v2.97e}{\Class{scrlttr2}} option determines whether the footer +for the letterhead page is output. Switching off the letterhead page footer +with \OptionValue{firstfoot}{false}\important{\OptionValue{firstfoot}{false}}, +has an effect when the \DescRef{\LabelBase.option.enlargefirstpage} option +(see \DescPageRef{\LabelBase.option.enlargefirstpage}) is used at the same +time, as this will logically extend the page downwards. In this case, the +distance that is ordinarily between type area and the footer becomes the +distance between the end of the type area and the bottom of the page. + +The option recognizes the standard values for simple switches listed in +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. The default +is to include the letterhead page footer. \EndIndexGroup \begin{Declaration} \Variable{firstfoot}% \end{Declaration}% -\BeginIndex{}{letter>foot}% -\BeginIndex{}{letterfoot}% -The first page's footer is preset to -empty. However\ChangedAt{v3.08}{\Class{scrlttr2}}, a new construction may be -made at the \PName{content} of variable \Variable{firstfoot}. \KOMAScript{} -does not use the \PName{description} of the variable. For more information see -the example following the next description. Only for compatibility reason the -deprecated command \Macro{firstfoot}\IndexCmd[indexmain]{firstfoot} of -\Class{scrlttr2} before release~3.08 still exists. Nevertheless it should not -be used any longer. +\BeginIndex{}{letterhead page>footer}% +The footer of the first page is empty by default. +However\ChangedAt{v3.08}{\Class{scrlttr2}}, you can specify a new footer +in the \PName{content} of the \Variable{firstfoot} variable. \KOMAScript{} +does not use the \PName{description} of the variable. -\begin{Declaration} - \Variable{frombank}% -\end{Declaration}% -This variable at the moment takes on a special meaning: it is not used -internally at this point, and the user can make use of it to set, for example, -his bank account\Index{bank account} within the sender's additional -information (see variable \DescRef{\LabelBase.variable.location}, -\DescPageRef{\LabelBase.variable.location}) or the footer.% -% +\BeginIndex{Variable}{frombank}% \begin{Example} - In the first page's footer, you may want to set the \PName{content} of the - variable \Variable{frombank} (the bank account). The double - backslash should be exchanged with a comma at the same time: + You want to put the \PName{content} of the \Variable{frombank} variable + (i.\,e. the bank account details) in the footer of the first page. The + double backslash should be replaced with a comma: \begin{lstcode} \setkomavar{firstfoot}{% \parbox[b]{\linewidth}{% @@ -2286,12 +2319,11 @@ information (see variable \DescRef{\LabelBase.variable.location}, }% } \end{lstcode} - For the hyphen you might define a variable of your own if you like. - This is left as an exercise for the reader. + You can also define your own variable for the separator. I leave + this as an exercise for the reader. - Nowadays it has become very common to create a proper footer in - order to obtain some balance with respect to the letterhead. This - can be done as follows: + If you want to create a footer in order to counterbalance the letterhead, you + can do so, for example, as follows: \begin{lstcode} \setkomavar{firstfoot}{% \parbox[t]{\textwidth}{\footnotesize @@ -2302,9 +2334,9 @@ information (see variable \DescRef{\LabelBase.variable.location}, \end{tabular}% \hfill \begin{tabular}[t]{l@{}}% - \multicolumn{1}{@{}l@{}}{Manager:}\\ - Jane Fonda\\[1ex] - \multicolumn{1}{@{}l@{}}{Court Of Jurisdiction:}\\ + \multicolumn{1}{@{}l@{}}{Managing Director:}\\ + Lisa Mayer\\[1ex] + \multicolumn{1}{@{}l@{}}{Court Jurisdiction:}\\ Great Plains \end{tabular}% \ifkomavarempty{frombank}{}{% @@ -2317,90 +2349,105 @@ information (see variable \DescRef{\LabelBase.variable.location}, }% } \end{lstcode} - This example, by the way, came from Torsten Kr\"uger. With + This example originally came from Torsten Kr\"uger. You should + consider placing a definition intended for multiple use in different + documents in a separate \File{lco} file\Index{lco file=\File{lco} file}. \begin{lstcode} - \setkomavar{frombank}{Account No. 12\,345\,678\\ - at Citibank\\ - bank code no: 876\,543\,21} + \setkomavar{frombank}{Account No. 12345678\\ + Buffoon Bank\\ + Bank Code: 65-43-21} \end{lstcode} - the bank account can be set accordingly. -% If the footer will have such a large height then it might happen that you -% have to shift its position. You can do this with the pseudo-length -% \PLength{firstfootvpos}\IndexPLength{firstfootvpos}, which is -% described above in this section. + can then be used to set the bank details in the document. +% However depending on your settings, there may not be sufficient space +% for such a large footer, and it may therefore be placed too low on the +% page. In such a case, you can adjust its vertical position with the +% pseudo-length \PLength{firstfootvpos}\IndexPLength{firstfootvpos}. \end{Example} -In the previous example a multi-line footer was set. With a compatibility -setting to version 2.9u (see \DescRef{\LabelBase.option.version} in + +The previous example uses a multi-line footer. With a compatibility setting +of version 2.9u (see \DescRef{\LabelBase.option.version} in \autoref{sec:\LabelBase.compatibilityOptions}, -\DescPageRef{\LabelBase.option.version}) the space will in general not -suffice. In that case, you may need to reduce \PLength{firstfootvpos} (see +\DescPageRef{\LabelBase.option.version}) the space is generally insufficient. +In this case, you should reduce \PLength{firstfootvpos} (see \DescPageRef{scrlttr2-experts.plength.firstfootvpos}) appropriately.% -% \EndIndexGroup + +\begin{Declaration} + \Variable{frombank} +\end{Declaration}% +\BeginIndex{}{letterhead page>footer}% +The \Variable{frombank} variable used in the previous example +occupies a special position. It is not currently used internally. However, you +can use it to put the bank information\Index{bank information} in the +extra sender information field or in the footer, as in the example (see +the variable \DescRef{\LabelBase.variable.location}, +\DescPageRef{\LabelBase.variable.location}).% % \EndIndexGroup % \EndIndexGroup - \LoadCommonFile{parmarkup} % \section{Paragraph Markup} \LoadCommonFile{oddorevenpage} % \section{Detection of Odd and Even Pages} -\section{Head and Foot Using Predefined Page Style} +\section{Headers and Footers with the Default Page Style} \seclabel{pagestyle} \BeginIndexGroup \BeginIndex{}{page>style}% -\BeginIndex{}{page>head}% -\BeginIndex{}{page>foot}% +\BeginIndex{}{page>header}% +\BeginIndex{}{page>footer}% -One of the general properties of a document is the page style. In {\LaTeX} -this means mostly the contents of headers and -footers. Like\textnote{Attention!} already mentioned in -\autoref{sec:\LabelBase.firstpage}, the head and foot of the note paper are -treated as elements of the note paper. Therefore they do not depend on the -settings of the page style. So this section describes the page styles of the -consecutive pages of letter after the note paper. At single-side letters this is -the page style of the secondary letter sheet. At double-side letters this is -also the page style of all backsides. +One of the general properties of a document is its page style. In \LaTeX{} +this mostly consists of the contents of headers and footers. +As\textnote{Attention!} already mentioned in +\autoref{sec:\LabelBase.firstpage}, the header and footer of the letterhead +page are treated as elements of the letterhead page. Therefore they do not +depend on the settings of the page style. So this section describes the page +styles of the subsequent pages of a letter after the letterhead page. For +one-sided letters, this is the page style of the second sheet. For two-sided +letters, this is also the page style of all verso pages. \begin{Declaration} \Macro{letterpagestyle} \end{Declaration} The\ChangedAt{v3.19}{\Class{scrlttr2}\and \Package{scrletter}} default page -style used for letters is specified by the contents of command -\Macro{letterpagestyle}. With \Class{scrlttr2} an empty value has been -predefined that does not change the -page style of the letter from the page style of the document. This has been -done, because \Class{scrlttr2} has been made for letter-only-documents. So it -is much easier to define the page style of all letters with the page style of -the document using \DescRef{\LabelBase.cmd.pagestyle} inside the preamble or before starting -the first letter. - -The \PageStyle{plain} page style of letters differs from the \PageStyle{plain} -page style of most classes. Therefore package \Package{scrletter} defines -\Macro{letterpagestyle} with the contents -\PageStyle{plain.letter}\IndexPagestyle{plain.letter}. So all letters will use -the \PageStyle{plain} style of page style pair -\PageStyle{letter}\IndexPagestyle{letter} by default and independent from the -page style of the rest of the document. See +style for letters is specified by the contents of the \Macro{letterpagestyle} +command. By default\textnote{default}, +\Class{scrlttr2}\OnlyAt{\Class{scrlttr2}} leaves this command empty. This +means that the page style of letters is the same as in the rest of the +document. This is useful because \Class{scrlttr2} is intended for letter-only +documents, and it is easier to define the page style for all letters globally, +using \DescRef{\LabelBase.cmd.pagestyle} as usual. + +Since both the \DescRef{\LabelBase.pagestyle.plain} and the +\DescRef{\LabelBase.pagestyle.headings} page styles of other classes differs +from the page style necessary for letters, the +\Package{scrletter}\OnlyAt{\Package{scrletter}}\textnote{default} package +defines \Macro{letterpagestyle} with to be +\DescRef{\LabelBase.pagestyle.plain.letter}\IndexPagestyle{plain.letter}% +\important{\DescRef{\LabelBase.pagestyle.plain.letter}}. This causes all +letters to use the +\hyperref[desc:\LabelBase.pagestyle.plain.letter]{\PageStyle{plain}} style of +the \DescRef{\LabelBase.pagestyle.letter}\IndexPagestyle{letter} page style +pair, regardless of the page style of the rest of the document. See \autoref{sec:scrlttr2-experts.pagestyleatscrletter} for more information about -the characteristics of the page style of package \Package{scrletter}. +the characteristics of the page style of the \Package{scrletter} package. \begin{Example} - You are using package \Package{scrletter} and want to have the same page - style inside letters as for the rest of the document. So you are using + You are using the \Package{scrletter} package and want letters to use the + same page style that was set for the rest of the document with + \DescRef{\LabelBase.cmd.pagestyle}. To do this, put the command \begin{lstcode} \renewcommand*{\letterpagestyle}{} \end{lstcode} - in your document preamble. Take care about the star of - \Macro{renewcommand*}! + in your document preamble. Notice the star in \Macro{renewcommand*}. \end{Example} -Nevertheless, if you use \DescRef{\LabelBase.cmd.pagestyle} or \DescRef{\LabelBase.cmd.thispagestyle} inside a -letter, this will overwrite the setting of \Macro{letterpagestyle} that is -only the default for the initialisation inside -\Macro{begin}\PParameter{document}.% +Of course, if you use \DescRef{\LabelBase.cmd.pagestyle} or +\DescRef{\LabelBase.cmd.thispagestyle} inside a letter, this will take +precedence over the page style set in \Macro{begin}\PParameter{letter} with +\Macro{letterpagestyle}.% \EndIndexGroup @@ -2408,39 +2455,67 @@ only the default for the initialisation inside \OptionVName{headsepline}{simple switch}% \OptionVName{footsepline}{simple switch} \end{Declaration} -These two options select whether or not to insert a separator -line\Index{line>separator}\Index{rule>separator} below the header or above the -footer, respectively, on consecutive pages. This option can take the standard -values for simple switches, as listed in \autoref{tab:truefalseswitch}, -\autopageref{tab:truefalseswitch}. -Activation\important{\OptionValue{headsepline}{true}} of option -\Option{headsepline} switches on a rule below the page -head. Activation\important{\OptionValue{footsepline}{true}} of option -\Option{footsepline} switches on a rule above the page foot. Deactivation of -the options switches of the corresponding rules. - -Obviously option \Option{headsepline} does not influence page style -\PValue{empty}\important[i]{\PageStyle{empty}} (see afterwards at this -section). This page style explicitly does not use any page head. - -Typographically\important[i]{\PageStyle{headings}\\ - \PageStyle{myheadings}\\\PageStyle{plain}} such a rule make a hard optical -connection of head or foot and the text area. This would not mean, that the -distance between head and text or text and foot should be increased. Instead -of this the head or foot should be seen as parts of the typing area, while -calculation of margins and typing area. To achieve this \KOMAScript{} will -pass option \DescRef{typearea.option.headinclude}% -\important[i]{\DescRef{typearea.option.headinclude}\\ - \DescRef{typearea.option.footinclude}} or -\DescRef{typearea.option.footinclude}, respectively, to the \Package{typearea} -package, if option \Option{headsepline} or \Option{footsepline}, respectively, -are used as a class option. In\important{\PageStyle{plain}} opposite to -\Option{headsepline} option \Option{footsepline} does influence page style -\PValue{plain} also, because \PValue{plain} uses a page number at the -foot. Package \Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage}% -\important{\Package{scrlayer-scrpage}} (see \autoref{cha:scrlayer-scrpage}) -provides additional features for rules at head and foot and may be combined -with \Class{scrlttr2}.% +With these options \Class{scrlttr2}\OnlyAt{scrlttr2} can select whether to put +a separator rule\Index{line>separator}\Index{rule>separator} below the header +or above the footer, respectively, on subsequent pages. This option acccepts +the standard values for simple switches listed in +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. +Activating\important{\OptionValue{headsepline}{true}} the \Option{headsepline} +option enables a rule below the header. +Activating\important{\OptionValue{footsepline}{true}} the \Option{footsepline} +option enables a rule above the footer. Deactivating the options disables the +corresponding rules. + +Of course, the \Option{headsepline} and \Option{footsepline} options have no +effect on the \DescRef{\LabelBase.pagestyle.empty}% +\important{\DescRef{\LabelBase.pagestyle.empty}} page style (see later in this +section). This page style explicitly does not use headers or footers. + +Typographically\important{\DescRef{\LabelBase.pagestyle.headings}\\ + \DescRef{\LabelBase.pagestyle.myheadings}\\ + \DescRef{\LabelBase.pagestyle.plain}} speaking, such a rule creates an +optical effect of making the header or footer appear to be closer to the text +area. This does not mean that the distance between the header or footer and +the text should be increased. Instead, they should be seen as part of the text +body\Index{text>body} when calculating the type area. To achieve this +\Class{scrlttr2} uses the \Option{headsepline} class option to automatically +pass the \DescRef{typearea.option.headinclude}% +\important{\DescRef{typearea.option.headinclude}} package option to the +\hyperref[cha:typearea]{\Package{typearea}} package. The same applies to +\DescRef{\LabelBase.option.footsepline} for +\DescRef{typearea.option.footinclude}% +\important{\DescRef{typearea.option.footinclude}}. + +The options themselves do not automatically recalculate the type area. To +recalculate the type area, see the \DescRef{typearea.option.DIV} option with +the \PValue{last} or \PValue{current} values (see +\DescPageRef{typearea.option.DIV.last}), or the +\DescRef{typearea.cmd.recalctypearea} command (see +\DescPageRef{typearea.cmd.recalctypearea}) in \autoref{cha:typearea}. + +The \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} +package (see \autoref{cha:scrlayer-scrpage}) provides further control over +header and footer rules and you can also combine it with \Class{scrlttr2}. The +\Package{scrletter} package automatically uses +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} to +define the \DescRef{\LabelBase.pagestyle.letter} and +\DescRef{\LabelBase.pagestyle.plain.letter} page styles. + +The\OnlyAt{\Package{scrletter}} \DescRef{\LabelBase.pagestyle.letter} and +\DescRef{\LabelBase.pagestyle.plain.letter} page styles defined by +\Package{scrletter} follow the rules of +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}. This particularly +applies to setting the header and footer rules of the \PageStyle{plain} page +style \DescRef{\LabelBase.pagestyle.plain.letter}. See in +\autoref{sec:scrlayer-scrpage.pagestyle.content}, +\DescPageRef{scrlayer-scrpage.option.headsepline} and +\DescPageRef{scrlayer-scrpage.option.plainheadsepline} the options +\DescRef{scrlayer-scrpage.option.headsepline} and +\DescRef{scrlayer-scrpage.option.plainheadsepline}. Also, settings like +\DescRef{scrlayer-scrpage.option.automark} are of some importance for the +\DescRef{\LabelBase.pagestyle.letter} page style.% % \EndIndexGroup @@ -2448,51 +2523,59 @@ with \Class{scrlttr2}.% \begin{Declaration} \OptionVName{pagenumber}{position} \end{Declaration} -This option defines if and where a page number will be placed on consecutive -pages. This option affects the page -styles\important[i]{\PageStyle{headings}\\ - \PageStyle{myheadings}\\ - \PageStyle{plain}} \PageStyle{headings}, \PageStyle{myheadings}, and -\PageStyle{plain}. It also affects the default page styles of the -\Package{scrlayer-scrpage}\important{\Package{scrlayer-scrpage}} package, if -set before loading the package (see \autoref{cha:scrlayer-scrpage}). It can -take values only influencing horizontal, only vertical, or both -positions. Available value are shown in -\autoref{tab:\LabelBase.pagenumber}. Default is \PValue{botcenter}. +With this option you can select if and where a page number should be placed on +subsequent pages. In \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}} this option +affects the page styles\important{\DescRef{\LabelBase.pagestyle.headings}\\ + \DescRef{\LabelBase.pagestyle.myheadings}\\ + \DescRef{\LabelBase.pagestyle.plain}} +\DescRef{\LabelBase.pagestyle.headings}, +\DescRef{\LabelBase.pagestyle.myheadings} and +\DescRef{\LabelBase.pagestyle.plain}; in +\Package{scrletter}\OnlyAt{\Package{scrletter}}, it affects the +\DescRef{\LabelBase.pagestyle.letter} and +\DescRef{\LabelBase.pagestyle.plain.letter} page styles. It also affects the +default page styles of the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}}% +\IndexPackage{scrlayer-scrpage} package, as long as it is set before that +package is loaded (see \autoref{cha:scrlayer-scrpage}). It accepts values that +influence only the horizontal position, only the vertical position, or both +positions simultaneously. Available values are listed in +\autoref{tab:\LabelBase.pagenumber}. The default is \PValue{botcenter}. \begin{table} - \caption[{available values of option \Option{pagenumber} with - \Class{scrlttr2}}]{available values of option \Option{pagenumber} for the - position of the page number in page styles \PageStyle{headings}, + \caption[{Available values for the \Option{pagenumber} option with + \Class{scrlttr2}}]{Available values of the \Option{pagenumber} option to + position the page number in page styles \PageStyle{headings}, \PageStyle{myheadings}, and \PValue{plain} with \Class{scrlttr2}} \label{tab:\LabelBase.pagenumber} \begin{desctabular} \entry{\PValue{bot}, \PValue{foot}}{% - page number in footer, horizontal position not changed}% + page number in footer, horizontal position unchanged}% \entry{\PValue{botcenter}, \PValue{botcentered}, \PValue{botmittle}, \PValue{footcenter}, \PValue{footcentered}, \PValue{footmiddle}}{% - page number in footer, centered}% + page number in footer, centred}% \entry{\PValue{botleft}, \PValue{footleft}}{% - page number in footer, left justified}% + page number in footer, left-justified}% \entry{\PValue{botright}, \PValue{footright}}{% - page number in footer, right justified}% + page number in footer, right-justified}% \entry{\PValue{center}, \PValue{centered}, \PValue{middle}}{% - page number centered horizontally, vertical position not changed}% + page number centred horizontally, vertical position unchanged}% \entry{\PValue{false}, \PValue{no}, \PValue{off}}{% no page number}% \entry{\PValue{head}, \PValue{top}}{% - page number in header, horizontal position not changed}% + page number in header, horizontal position unchanged}% \entry{\PValue{headcenter}, \PValue{headcentered}, \PValue{headmiddle}, \PValue{topcenter}, \PValue{topcentered}, \PValue{topmiddle}}{% - page number in header, centered}% + page number in header, centred}% \entry{\PValue{headleft}, \PValue{topleft}}{% - page number in header, left justified}% + page number in header, left-justified}% \entry{\PValue{headright}, \PValue{topright}}{% - page number in header, right justified}% + page number in header, right-justified}% \entry{\PValue{left}}{% - page number left, vertical position not changed}% + page number left, vertical position unchanged}% \entry{\PValue{right}}{% - page number right, vertical position not changed}% + page number right, vertical position unchanged}% \end{desctabular} \end{table} % @@ -2503,59 +2586,124 @@ positions. Available value are shown in \Macro{pagestyle}\Parameter{page style}% \Macro{thispagestyle}\Parameter{local page style} \end{Declaration}% -In letters written with \Class{scrlttr2} there are four different +\BeginIndex{Pagestyle}{empty}% +\BeginIndex{Pagestyle}{plain}% +\BeginIndex{Pagestyle}{headings}% +\BeginIndex{Pagestyle}{myheadings}% +Letters written with \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}} have four +different page styles available. In contrast, +\Package{scrletter}\OnlyAt{\Package{scrletter}} defines only two of its own page styles. -\begin{description} -\item[{\PageStyle{empty}% - \IndexPagestyle[indexmain]{empty}\LabelPageStyle{empty}}] is the page - style, in which the header and footer of consecutive pages are completely - empty. This page style is also used for the first page, because header and - footer of this page are set by other means using the macro +\begin{description}\setkomafont{descriptionlabel}{} +\item[{\PageStyle{empty}}] + \LabelPageStyle{empty} is the page style where the headers and footers of + subsequent pages are completely empty. This page style is also automatically + used for the first page of the letter because the header and footer of this + page are set by other means, using \DescRef{\LabelBase.cmd.opening}\IndexCmd{opening} (see \autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.cmd.opening}). -\item[{\PageStyle{headings}% - \IndexPagestyle[indexmain]{headings}\LabelPageStyle{heading}}] is the page - style for running (automatic) headings on consecutive pages. The inserted - marks are the sender's name from the variable - \DescRef{\LabelBase.variable.fromname}\IndexVariable{fromname} and the - subject from the variable \DescRef{\LabelBase.variable.subject}\IndexVariable{subject} (see - \autoref{sec:\LabelBase.firstpage}, +\item[{\PageStyle{headings}}] + \LabelPageStyle{headings} is, for \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}}, + the page style for automatic running heads on subsequent pages. The sender's + name from the \DescRef{\LabelBase.variable.fromname}\IndexVariable{fromname} + variable and the subject from the + \DescRef{\LabelBase.variable.subject}\IndexVariable{subject} variable are + used to set the marks (see \autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.fromname} and - \DescPageRef{\LabelBase.variable.subject}). At which position these marks - and the page numbers are placed, depends on the previously described option - \DescRef{\LabelBase.option.pagenumber} and the \PName{content} of the variables + \DescPageRef{\LabelBase.variable.subject}). Where exactly these marks and + page numbers are placed depends on the + \DescRef{\LabelBase.option.pagenumber} described above and the + \PName{content} of the \DescRef{\LabelBase.variable.nexthead}\IndexVariable{nexthead} and - \DescRef{\LabelBase.variable.nextfoot}\IndexVariable{nextfoot}. The author can also change - these marks manually after the \DescRef{\LabelBase.cmd.opening} command. To - this end, the commands \DescRef{\LabelBase.cmd.markboth} and - \DescRef{\LabelBase.cmd.markright} are available as usual, and with the use - of package \Package{scrlayer-scrpage} also - \DescRef{scrlayer-scrpage.cmd.markleft} (see - \autoref{sec:scrlayer-scrpage.pagestyle.content}, - \DescPageRef{scrlayer-scrpage.cmd.automark}) is available. -\item[{\PageStyle{myheadings}% - \IndexPagestyle[indexmain]{myheadings}\LabelPageStyle{myheadings}}] is the - page style for manual page headings on consecutive pages. This is very - similar to \PValue{headings}, but here the marks must be set by the author - using the commands \DescRef{\LabelBase.cmd.markboth}\IndexCmd{markboth} and - \DescRef{\LabelBase.cmd.markright}\Index{markright}. With the use of package - \Package{scrlayer-scrpage} also \DescRef{scrlayer-scrpage.cmd.markleft} can be utilized. -\item[{\PageStyle{plain}% - \IndexPagestyle[indexmain]{plain}\LabelPageStyle{plain}}] is the page - style with only page numbers in the header or footer on consecutive - pages. The placement of these page numbers is influenced by the previously - described option \DescRef{\LabelBase.option.pagenumber}. + \DescRef{\LabelBase.variable.nextfoot}\IndexVariable{nextfoot} variables. An + author can also change these marks manually after the + \DescRef{\LabelBase.cmd.opening} command. As usual, the + \DescRef{\LabelBase.cmd.markboth} and \DescRef{\LabelBase.cmd.markright} + commands are available, as is \DescRef{scrlayer-scrpage.cmd.markleft} if you + use \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + \IndexPackage{scrlayer-scrpage}% + \important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} + (see \autoref{sec:scrlayer-scrpage.pagestyle.content}, + \DescPageRef{scrlayer-scrpage.cmd.automark}). + + Since \Package{scrletter}\OnlyAt{scrletter} uses + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} internally, any + page style \DescRef{maincls.pagestyle.headings} provided by the class are + redefined as an alias of \DescRef{scrlayer-scrpage.pagestyle.scrheadings}. + You can find more about this page style in \autoref{cha:scrlayer-scrpage} on + \DescPageRef{scrlayer-scrpage.pagestyle.scrheadings}. +\item[{\PageStyle{letter}}] + \LabelPageStyle{letter}% + Since the \PageStyle{headings} page style is generally already in use by + the classes, the \Package{scrletter}\OnlyAt{scrletter} package instead + defines the \PageStyle{letter} page style. This is accomplished with the + help of \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} in + \autoref{cha:scrlayer-scrpage}, \autopageref{cha:scrlayer-scrpage}. With the + \OptionValueRef{scrlayer-scrpage}{automark}{true}% + \important{\OptionValueRef{scrlayer-scrpage}{automark}{true}}% + \IndexOption{automark} setting enabled, \PageStyle{letter} then assumes the + role played by \PageStyle{headings} in \Class{scrlttr2}. With + \OptionValueRef{scrlayer-scrpage}{automark}{false}% + \important{\OptionValueRef{scrlayer-scrpage}{automark}{false}}% + \IndexOption{automark} set, \PageStyle{letter} assumes the role of + \PageStyle{myheadings}. + + When\textnote{Attention!} you use + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} with + \Package{scrletter}, you cannot use the obsolete + \Package{scrpage2}\IndexPackage{scrpage2} package or the + \Package{fancyhdr}\IndexPackage{fancyhdr} package, which is incompatible + with \KOMAScript{}. +\item[{\PageStyle{myheadings}}] + \LabelPageStyle{myheadings}% + in \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}} is the page style for manual + running heads on subsequent pages. Unlike \PValue{headings}, you must set + the marks yourself with the + \DescRef{\LabelBase.cmd.markboth}\IndexCmd{markboth} and + \DescRef{\LabelBase.cmd.markright}\IndexCmd{markright} commands. When you + use \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}, + \DescRef{scrlayer-scrpage.cmd.markleft}\IndexCmd{markleft} is also + available. + + With the \Package{scrletter}\OnlyAt{\Package{scrletter}} package, the + \PageStyle{letter} page style also assumes the role of + \PageStyle{myheadings}. +\item[{\PageStyle{plain}}] + \LabelPageStyle{plain}% + is the default page style for \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}}, + which does not use any headers on subsequent pages and only outputs + a single page number. Where this is placed depends on the + \DescRef{\LabelBase.option.pagenumber} option explained above. + + Since \Package{scrletter}\OnlyAt{scrletter} uses + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} internally, the + \DescRef{maincls.pagestyle.plain} page style is redefined as an alias of + \DescRef{scrlayer-scrpage.pagestyle.plain.scrheadings}. You can find more + about this page style in \autoref{cha:scrlayer-scrpage} on + \DescPageRef{scrlayer-scrpage.pagestyle.scrheadings}. +\item[{\PageStyle{plain.letter}}] + \LabelPageStyle{plain.letter}% + Since the \PageStyle{plain} page style is generally already in use by the + classes, the \Package{scrletter}\OnlyAt{scrletter} defines a + \PageStyle{plain.letter} page style instead. This is accomplished with the + help of \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}. + When\textnote{Attention!} you use + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} with + \Package{scrletter}, you cannot use the obsolete + \Package{scrpage2}\IndexPackage{scrpage2} package or the + \Package{fancyhdr}\IndexPackage{fancyhdr} package, which is incompatible + with \KOMAScript{}. \end{description} -Page styles are also influenced by the previously described -options\important[i]{\DescRef{\LabelBase.option.headsepline}\\ +The appearance of the page styles is also influenced by +the\important{\DescRef{\LabelBase.option.headsepline}\\ \DescRef{\LabelBase.option.footsepline}} \DescRef{\LabelBase.option.headsepline}\IndexOption{headsepline} and -\DescRef{\LabelBase.option.footsepline}\IndexOption{footsepline}. The page -style beginning with the current page is switched using \Macro{pagestyle}. In -contrast, \Macro{thispagestyle} changes only the page style of the current -page. The\textnote{Attention!} letter class itself uses -\Macro{thispagestyle}\PParameter{empty} within +\DescRef{\LabelBase.option.footsepline}\IndexOption{footsepline} options +described above. The page style beginning with the current page is changed +using \Macro{pagestyle}. In contrast, \Macro{thispagestyle} changes only the +page style of the current page. The\textnote{Attention!} letter class itself +uses \Macro{thispagestyle}\PParameter{empty} within \DescRef{\LabelBase.cmd.opening}\IndexCmd{opening} for the first page of the letter. @@ -2564,24 +2712,23 @@ letter. \BeginIndex{FontElement}{pageheadfoot}\LabelFontElement{pageheadfoot}% \BeginIndex{FontElement}{pagefoot}\LabelFontElement{pagefoot}% \BeginIndex{FontElement}{pagenumber}\LabelFontElement{pagenumber}% -For changing the font style of headers or footers you should use the user -interface described in \autoref{sec:maincls.textmarkup}. For header and -footer the same element is used, which you can name either +To changing the font style of headers or footers, you should use the user +interface described in \autoref{sec:maincls.textmarkup}. The header and footer +use the same element, which you can refer to by either \FontElement{pageheadfoot}\important{\FontElement{pagehead}} or -\FontElement{pagehead}. There\ChangedAt{v3.00}{\Class{scrlttr2}} is an -additional element \FontElement{pagefoot}\important{\FontElement{pagefoot}} -for the page foot. This will be used after \FontElement{pageheadfoot} at page -foots, that has been defined either with variable -\DescRef{\LabelBase.variable.nextfoot}\IndexVariable{nextfoot} or Package -\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} (see -\autoref{cha:scrlayer-scrpage}, -\DescPageRef{scrlayer-scrpage.fontelement.pagefoot}). The element for the -page number within the header or footer is named -\FontElement{pagenumber}\important{\FontElement{pagenumber}}. Default settings -are listed in \autoref{tab:maincls.defaultFontsHeadFoot}, -\autopageref{tab:maincls.defaultFontsHeadFoot}. Please have also a look at -the example in \autoref{sec:maincls.pagestyle}, -\PageRefxmpl{maincls.cmd.pagestyle}. +\FontElement{pagehead}. The\ChangedAt{v3.00}{\Class{scrlttr2}} +\FontElement{pagefoot}\important{\FontElement{pagefoot}} element +additionally controls the formatting of the footer. This element is applied +after \FontElement{pageheadfoot} in the +\DescRef{\LabelBase.variable.nextfoot}\IndexVariable{nextfoot} variable or +when \Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} page styles are +used (see \autoref{cha:scrlayer-scrpage}, +\DescPageRef{scrlayer-scrpage.fontelement.pagefoot}). The element for the page +number within the header or footer is called +\FontElement{pagenumber}\important{\FontElement{pagenumber}}. The default +settings are listed in \autoref{tab:maincls.defaultFontsHeadFoot}, +\autopageref{tab:maincls.defaultFontsHeadFoot}. Please also note the example +from \autoref{sec:maincls.pagestyle}, \PageRefxmpl{maincls.cmd.pagestyle}. % \EndIndexGroup % @@ -2592,55 +2739,56 @@ the example in \autoref{sec:maincls.pagestyle}, \Macro{markboth}\Parameter{left mark}\Parameter{right mark}% \Macro{markright}\Parameter{right mark} \end{Declaration} -The possibilities that are offered with variables and options in -\Class{scrlttr2} should be good enough in most cases to create letterheads and -footers for the consecutive pages that follow the first letter page. Even more -so since you can additionally change with \Macro{markboth} and -\Macro{markright} the sender's statements that \Class{scrlttr2} uses to create -the letterhead. The commands \Macro{markboth}\IndexCmd{markboth} and -\Macro{markright}\IndexCmd{markright} can in particular be used together with -pagestyle \PageStyle{myheadings}\IndexPagestyle{myheadings}% -\important{\PageStyle{myheadings}}. If the package -\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} is used then this, -of course, is valid also for pagestyle -\PValue{scrheadings}\IndexPagestyle{scrheadings}. There the command -\DescRef{scrlayer-scrpage.cmd.markleft}\IndexCmd{markleft} is furthermore +In most cases, \KOMAScript{}'s options and variables should be quite adequate +for creating headers\Index{header} and footers\Index{footer} for the +subsequent pages, all the more so because, in addition to \Macro{markboth} and +\Macro{markright}, you can change the sender information that \Class{scrlttr2} +or \Package{scrletter} puts in the header. You can, in particular, use the +\Macro{markboth}\IndexCmd{markboth} and \Macro{markright}\IndexCmd{markright} +commands with the \PageStyle{myheadings}\IndexPagestyle{myheadings}% +\important{\PageStyle{myheadings}} pagestyle. Of course, if you use the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} +package, this is also valid for the +\PValue{scrheadings}\IndexPagestyle{scrheadings} page style. In that case, the +\DescRef{scrlayer-scrpage.cmd.markleft}\IndexCmd{markleft} command is also available. \begin{Declaration} \Variable{nexthead}% \Variable{nextfoot}% \end{Declaration} -At times one wants to have more freedom with creating the letterhead or footer -of subsequent pages. Then one has to give up the previously described -possibilities of predefined letterheads or footers that could have been chosen -via the option -\DescRef{\LabelBase.option.pagenumber}\IndexOption{pagenumber}. Instead one is -free to create the letterhead and footer of consecutive pages just the way one -wants to have them set with page style -\PageStyle{headings}\IndexPagestyle{headings}\important{\PageStyle{headings}, - \PageStyle{myheadings}} or -\PageStyle{myheadings}\IndexPagestyle{myheadings}. For that, one creates the -desired letterhead or footer construction using the \PName{content} of -variable\ChangedAt{v3.08}{\Class{scrlttr2}} \Variable{nexthead} or -\Variable{nextfoot}, respectively. Within the \PName{content} of -\Variable{nexthead} and \Variable{nextfoot} you can, for example, have several -boxes side by side or one beneath the other by use of the \Macro{parbox} -command (see \cite{latex:usrguide}). A more advanced user should have no -problems creating letterheads of footers of his own. Within \PName{content} -you can and should of course also make use of other variables by using +At times, however, you may want to the header or the footer of subsequent pages +to more closely resemble the letterhead page. In these cases, you must dispense +with the predefined options that can be selected with the +\DescRef{\LabelBase.option.pagenumber}\IndexOption{pagenumber} option described above. +Instead, you can customise the header and footer of subsequent pages using the +\DescRef{\LabelBase.pagestyle.headings}\IndexPagestyle{headings}% +\important{\DescRef{\LabelBase.pagestyle.headings}, + \DescRef{\LabelBase.pagestyle.myheadings}} or +\DescRef{\LabelBase.pagestyle.myheadings}\IndexPagestyle{myheadings} page styles with \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}}, +and the \DescRef{\LabelBase.pagestyle.letter}% +\IndexPagestyle{letter}\important{\DescRef{\LabelBase.pagestyle.letter}} page style +with \Package{scrletter}\OnlyAt{\Package{scrletter}}. To do so, you create the +structure you want in the \PName{content} of +the\ChangedAt{v3.08}{\Class{scrlttr2}} \Variable{nexthead} or +\Variable{nextfoot} variables. Within the \PName{content} of +\Variable{nexthead} and \Variable{nextfoot} you can, for example, use the \Macro{parbox} +command to place several boxes next to or beneath each other (see \cite{latex:usrguide}). More advanced users should +be able to create their own headers and footers. Of course, you can +and should also make use of additional variables using \DescRef{\LabelBase.cmd.usekomavar}. \KOMAScript{} does not use the -\PName{description} of both variables. - -Only\textnote{Attention!} for compatibility reason the deprecated commands -\Macro{nexthead}\IndexCmd[indexmain]{nexthead} and -\Macro{nextfoot}\IndexCmd[indexmain]{nextfoot} of former \Class{scrlttr2} -releases before 3.08 are also implemented. Nevertheless, you should not use -those.% +\PName{description} for either variable. % -\EndIndexGroup +%Only\textnote{Attention!} for compatibility reason the deprecated commands +%\Macro{nexthead}\IndexCmd[indexmain]{nexthead} and +%\Macro{nextfoot}\IndexCmd[indexmain]{nextfoot} of former \Class{scrlttr2} +%releases before 3.08 are also implemented. Nevertheless, you should not use +%those.% % \EndIndexGroup +\EndIndexGroup % \EndIndexGroup @@ -2652,46 +2800,45 @@ those.% \LoadCommonFile{lists}% \section{Lists} -\section{Math} +\section{Mathematics} \seclabel{math}% \BeginIndexGroup \BeginIndex{}{equations}% \BeginIndex{}{formulas}% \BeginIndex{}{mathematics}% -There are not math environments implemented at the \KOMAScript{} -classes. Instead of this, the math features of the \LaTeX{} kernel have been -supported. Furthermore\textnote{Attention!} regular math with numbered -equations or formulas is very unusual at letters. Because of this -\Class{scrlttr2} does not actively support numbered equations. Therefore -options \DescRef{maincls.option.leqno} and \DescRef{maincls.option.fleqn}, -that has been described for \Class{scrbook}, \Class{scrreprt}, and -\Class{scrartcl} at \autoref{sec:maincls.math} are not available from -\Class{scrlttr2}. - -You will not find a description of the math environments of the \LaTeX{} kernel -here. If you want to use \Environment{displaymath}\IndexEnv{displaymath}, -\Environment{equation}\IndexEnv{equation} and -\Environment{eqnarray}\IndexEnv{eqnarray} you should read a short introduction -into \LaTeX{} like \cite{lshort}. But\textnote{Hint!} if you want more than -very simple mathematics, usage of package \Package{amsmath} would be -recommended (see \cite{package:amsmath}).% +The \KOMAScript{} classes do not provide their own maths environments. +Instead, \KOMAScript{} relies completely on the maths features of the \LaTeX{} +kernel. However\textnote{Attention!}, since numbered equations and formulas +are very unusual in letters, \KOMAScript{} does not actively support them. +Therefore, the \DescRef{maincls.option.leqno} and +\DescRef{maincls.option.fleqn} options for \Class{scrbook}, \Class{scrreprt}, +and \Class{scrartcl}, documented in \autoref{sec:maincls.math}, are not +available with \Class{scrlttr2}. + +You will not find a description here of the maths environments of the \LaTeX{} +kernel, that is \Environment{displaymath}\IndexEnv{displaymath}, +\Environment{equation}\IndexEnv{equation}, and +\Environment{eqnarray}\IndexEnv{eqnarray}. If you want to use them, consult an +introduction to \LaTeX{} like \cite{lshort}. But\textnote{Hint!} if you want +more than very simple mathematics, you should use the \Package{amsmath} +package (see \cite{package:amsmath}).% % \EndIndexGroup -\section{Floating Environments of Tables and Figures} +\section{Floating Environments for Tables and Figures} \seclabel{floats} -Floating environments for tables or figures are very unusual in -letters. Therefore\textnote{Attention!} \Class{scrlttr2} does not provide -them. If someone nevertheless needs floating environments, then this is often -points out a malpractice of the letter class. In such cases you may try to -define the floating environments with help of packages like \Package{tocbasic}\important{\Package{tocbasic}} (siehe -\autoref{cha:tocbasic}). Nevertheless, tabulars and pictures or graphics -without floating environment may still be done with the letter class -\Class{scrlttr2}. - +Floating environments for tables or figures are very unusual in letters. +Therefore\textnote{Attention!} \Class{scrlttr2} does not provide them. If you +still believe you need them, this often indicates a misuse of the letter +class. In such cases, it is advisable to combine one of the \KOMAScript{} +classes from \autoref{cha:maincls} with the +\Package{scrletter}\important{\Package{scrletter}} package instead. In this +case you, the floating environments documented for the class can also be used +in letters. You could also define your own floating environments with help of +\Package{tocbasic}\important{\Package{tocbasic}} (see \autoref{cha:tocbasic}). \LoadCommonFile{marginpar} % \section{Margin Notes} @@ -2704,68 +2851,73 @@ without floating environment may still be done with the letter class \BeginIndex{}{signature}% \BeginIndex{}{letter>signature}% -That the letter closing will be set by -\DescRef{\LabelBase.cmd.closing}\IndexCmd{closing} has been explained already -in \autoref{sec:\LabelBase.document}, \DescPageRef{\LabelBase.cmd.closing}. A kind -of annotation to the signature is often placed below the signature of the -letter. The signing or hand-written inscription itself is placed between this -signature annotation and the closing phrase. +It has already been mentioned in \autoref{sec:\LabelBase.document}, +\DescPageRef{\LabelBase.cmd.closing} that the letter's closing text is +provided by \DescRef{\LabelBase.cmd.closing}\IndexCmd{closing}. Beneath the +closing text, there is often a space for a handwritten signature, beneath +which there can be a printed name, which serves as a kind of annotation to the +actual signature. \begin{Declaration} \Variable{signature}% \end{Declaration} -The variable \Variable{signature} holds an explanation or annotation for the -inscription, the signing of the letter. The \PName{content} is predefined as -\DescRef{\LabelBase.cmd.usekomavar}\PParameter{fromname}. The annotation may -consist of multiple lines. The lines should then be separated by a double -backslash. Paragraph\textnote{Attention!} breaks in the annotation are however -not permitted.% +The \Variable{signature} variable contains the printed name or annotation for +the handwritten signature. Its default \PName{content} is the +\DescRef{\LabelBase.cmd.usekomavar}\PParameter{fromname}. This annotation can +consist of multiple lines. In that case, you should separate the individual +lines with double backslashes. Paragraph\textnote{Attention!} breaks in the +signature annotation, however, are not permitted.% \EndIndexGroup \begin{Declaration} \Macro{raggedsignature} \end{Declaration} -Closing phrase and signature will be typeset in a box. The width of -the box is determined by the length of the longest line of the closing -phrase or signature's \PName{content}. - -Where to place this box is determined by the pseudo-lengths -\PLength{sigindent}\IndexPLength{sigindent} and -\PLength{sigbeforevskip}\IndexPLength{sigbeforevskip} (see -\autoref{sec:scrlttr2-experts.closing}, -\DescPageRef{scrlttr2-experts.plength.sigindent}). The command -\Macro{raggedsignature} defines the alignment inside the box. In the -predefined \File{lco} files the command is either defined as \Macro{centering} -(all besides \Option{KOMAold}) or \Macro{raggedright} (\Option{KOMAold}). In -order to obtain flush-right or flush-left alignment inside the box, the -command can be redefined in the same way as -\DescRef{maincls.cmd.raggedsection} (see \autoref{sec:maincls.structure}, +The closing phrase and the signature will be typeset in a box. The width of +the box is determined by the length of the longest line in the closing +phrase or signature. + +The \PLength{sigindent}\IndexPLength{sigindent} and +\PLength{sigbeforevskip}\IndexPLength{sigbeforevskip} pseudo-lengths determine +exactly where this box is placed (see \autoref{sec:scrlttr2-experts.closing}, +\DescPageRef{scrlttr2-experts.plength.sigindent}). The \Macro{raggedsignature} +command defines the alignment inside the box. In the default \File{lco} files, +the command is either defined as \Macro{centering} (all besides +\Option{KOMAold}) or \Macro{raggedright} (\Option{KOMAold}). In order to +obtain flush-right or flush-left alignment inside the box, you can redefine +the command in the same way as \DescRef{maincls.cmd.raggedsection} (see the +example in \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.raggedsection}). \begin{Example} - Now, Mr Public really wants to aggrandize himself. Therefor he uses the - signature to show again, that he himself was formerly chairman. Because of - this he changes \PName{contents} of variable - \DescRef{\LabelBase.variable.signature}. Additionally he wants the signature - be flush-left aligned and so he also redefines \Macro{raggedsignature}:% + Now Mr Public wants to make himself seem really important, and therefore he uses the + signature to show once again that he was formerly a chairman himself. So + he changes \PName{contents} of the + \DescRef{\LabelBase.variable.signature} variable. He also wants the signature + be aligned flush-left and so he also redefines \Macro{raggedsignature}:% \lstinputcode[xleftmargin=1em]{letter-22}% See \autoref{fig:\LabelBase.letter-22} for the result. \begin{figure} \setcapindent{0pt}% \begin{captionbeside}[{Example: letter with extended sender, logo, - addressee, additional sender information, place, date, subject, + recipient, extra sender information, place, date, subject, opening, text, closing, modified signature, postscript, distribution - list, enclosure, and puncher hole mark}] - {result of a small letter with extended sender, logo, addressee, - additional sender information, place, date, subject opening, text, + list, enclosure, and hole-punch mark}] + {result of a short letter with extended sender, logo, recipient, + extra sender information, place, date, subject opening, text, closing, modified signature, postscript, distribution list, enclosure - and puncher hole mark}[l] + and hole-punch mark}[l] \frame{\includegraphics[width=.4\textwidth]{letter-22}} \end{captionbeside} \label{fig:\LabelBase.letter-22} \end{figure} \end{Example} + +\iftrue% Umbruchkorrekturtext + The preceding example shows the most important, although not all possible, + elements of a letter. It can, however, serve quite well as a general + template.% +\fi % \EndIndexGroup % @@ -2775,244 +2927,283 @@ command can be redefined in the same way as \section{Letter Class Option Files} \seclabel{lcoFile}% \BeginIndexGroup -\BeginIndex{}{lco-file=\File{lco}-file}% +\BeginIndex{}{lco file=\File{lco} file}% \BeginIndex{}{letter class option}% -\BeginIndex{}{letter>class option}% Normally, you would not redefine selections like the sender's information every time you write a letter. Instead, you would reuse a whole set of -parameters for certain occasions. It will be much the same for the letterhead -and footer used on the first page. Therefore, it is reasonable to save these -settings in a separate file. For this purpose, the \Class{scrlttr2} class -offers the \File{lco}-files. The \File{lco} suffix is an abbreviation for +parameters for certain occasions. The same applies to the letterhead +and footer used on the first page. Therefore it makes sense to save these +settings in a separate file. For this purpose, \KOMAScript{} offers +\File{lco} files. The \File{lco} suffix is an abbreviation for \emph{\emph{l}etter \emph{c}lass \emph{o}ption}. -In an \File{lco} file you can use all commands available to the document at -the time the \File{lco} file is loaded. Additionally, it can contain internal -commands available to package writers. For \Class{scrlttr2}, these are in -particular the commands +In an \File{lco} file, you can use all commands available to the document at +the time the \File{lco} file is loaded. You can also use internal commands +available to package writers. For \Class{scrlttr2} and \Package{scrletter}, +these are, in particular, the commands \DescRef{scrlttr2-experts.cmd.@newplength}\IndexCmd{@newplength}, \DescRef{scrlttr2-experts.cmd.@setplength}\IndexCmd{@setplength}, and \DescRef{scrlttr2-experts.cmd.@setplength}\IndexCmd{@addtoplength} (see \autoref{sec:scrlttr2-experts.pseudoLengths}). -There are already some \File{lco} files included in the {\KOMAScript} -distribution. The \File{DIN.lco}, \File{DINmtext.lco}, \File{SNleft.lco}, -\File{SN.lco}, \File{UScommercial9}, \File{UScommercial9DW}, -\File{NF.lco}\ChangedAt{v3.04}{\Class{scrlttr2}} files serve to adjust -{\KOMAScript} to different layout standards. They are well suited as templates -for your own parameter sets, while you become a \KOMAScript{} expert. The -\File{KOMAold.lco} file, on the other hand, serves to improve compatibility -with the old letter class \Class{scrlettr}. Since it contains internal -commands not open to package writers, you should not use this as a template -for your own \File{lco} files. You can find a list of predefined \File{lco} -files in \autoref{tab:lcoFiles}, \autopageref{tab:lcoFiles}. - -If you have defined a parameter set for a letter standard not yet supported by -\KOMAScript, you are explicitly invited to send this parameter set to the -{\KOMAScript} support address. Please do not forget to include the permission -for distribution under the {\KOMAScript} license (see the \File{lppl.txt} -file). If you know the necessary metrics for an unsupported letter standard, -but are not able to write a corresponding \File{lco} file yourself, you can -also contact the {\KOMAScript} author, Markus Kohm, directly. More -particular complex examples of \File{lco}-files are shown at \cite{homepage} -or in \cite{DANTE:TK0203:MJK}. Both locations are mainly in German. +\KOMAScript{} comes provided with some \File{lco} files. The \File{DIN.lco}, +\File{DINmtext.lco}, \File{SNleft.lco}, \File{SN.lco}, \File{UScommercial9}, +\File{UScommercial9DW}, and \File{NF.lco}\ChangedAt{v3.04}{\Class{scrlttr2}} +files serve to adapt \Class{scrlttr2} and \Package{scrletter} to different +standards. They are well suited as templates for your own parameter sets as +you become a \KOMAScript{} expert. The \File{KOMAold.lco} file, on the other +hand, serves to improve compatibility with the old letter class +\Class{scrlettr}. This class was removed from \KOMAScript{} over fifteen years +ago. It is therefore not discussed in any detail. Since this file also +contains internal commands that are not released for package writers, you +should not use this as a template for your own \File{lco} files. You can find +a list of predefined \File{lco} files in \autoref{tab:lcoFiles}, +\autopageref{tab:lcoFiles}. + +If you have defined a parameter set for a letter standard that is not yet +supported by \KOMAScript{}, you are explicitly requested to send this +parameter set to the \KOMAScript{} support address. Please also provide +permission for distribution under the \KOMAScript{} license (see the +\File{lppl.txt} file). If you have the necessary measurements for an +unsupported letter standard but are unable to write a corresponding \File{lco} +file yourself, you can also contact the \KOMAScript{} author, Markus Kohm, +directly. you can find further examples of \File{lco} files, some very +complex, at \cite{homepage} or in \cite{DANTE:TK0203:MJK}. Both sites are +mainly in German. + \begin{Declaration} \Macro{LoadLetterOption}\Parameter{name}% \Macro{LoadLetterOptions}\Parameter{list of names} \end{Declaration} -With \Class{scrlttr2} \File{lco}-files can be loaded by the -\Macro{documentclass} command. You enter the name of the \File{lco}-file -without suffix as an option\Index{option}. In this case, the \File{lco}-file -will be loaded right after the class file. - -However, it is recommended to load an \File{lco}-file using -\Macro{LoadLetterOption} or -\Macro{LoadLetterOptions}\ChangedAt{v3.14}{\Class{scrlttr2}}. You can do this -even from within another \File{lco}-file. Both commands take the \PName{name} -of the \File{lco}-file without suffix, \Macro{LoadLetterOption} as a single -parameter, \Macro{LoadLetterOptions} as one member of a comma-separated -\PName{list of names}. The corresponding \File{lco}-files will be loaded in -the order given by the list. +With \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}} you can load \File{lco} files +with the \Macro{documentclass} command. To do so, give the name of the +\File{lco} file without the extension as an option\Index{option}. The +\File{lco} file is then loaded directly after the class. The +\Package{scrletter}\textnote{Attention!} package does not offer this option. +To load \File{lco} files, you must use \Macro{LoadLetterOption} or +\Macro{LoadLetterOptions}\ChangedAt{v3.14}{\Class{scrlttr2}}. +This\textnote{Recommendation!} is also recommended for \Class{scrlttr2}. + +You can also use \Macro{LoadLetterOption} and \Macro{LoadLetterOptions} after +\Macro{begin}\PParameter{document}, or even from within another \File{lco} +file. Both commands take the \PName{name} of the \File{lco} file without the +extension. While the argument of \Macro{LoadLetterOption} should be exactly +one \File{lco} file, \Macro{LoadLetterOptions} accepts a comma-separated +\PName{list of names}. The corresponding \File{lco} files with those names are +loaded in the order given by the list. \begin{Example} - Mr Public also writes a document containing several letters. Most of them - should comply with the German DIN standard. So he starts with: + Joe Public also writes a document containing several letters. For most of + them, the default format, which follows the format of the German Institute + for Standardisation, or \emph{Deutsches Institut f\"{u}r Normung} (DIN), is + sufficient. So he starts with: \begin{lstcode} \documentclass{scrlttr2} \end{lstcode} - However, one letter should use the \File{DINmtext} variant, with the - address field placed more toward the top, which results in more text - fitting on the first page. The folding will be modified so that the - address field still matches the address window in a DIN~C6/5 envelope. - You can achieve this as follows: + However, he wants to send one letter in a C6/5 envelope, and so he + uses the \File{DINmtext} variant, in which the + address field appears higher on the page, so that more text + fits on the first page. The fold marks are adjusted so that the + address field still fits the address window in a C6/5 envelope. + He achieves this as follows: \begin{lstcode} \begin{letter}{% - Joana Public\\ - Hillside 1\\ - 12345 Public-City} + Joanna Public\\ + 1 Hillside\\ + SAMPLESTEAD\\ + WX12 3YZ} \LoadLetterOption{DINmtext} \opening{Hello,} \end{lstcode} - Since construction of the page does not start before the - \DescRef{\LabelBase.cmd.opening}\IndexCmd{opening} command, it is sufficient - to load the \File{lco}-file before this. In particular, the loading need not - be done before \Macro{begin}\PParameter{letter}. Therefore the changes made - by loading the \File{lco}-file are local to the corresponding letter. + Since construction of the first page only really begins with the + \DescRef{\LabelBase.cmd.opening}\IndexCmd{opening} command, you only need to + load the \File{lco} file before this point. In particular, you do not need + to load it before \Macro{begin}\PParameter{letter}. That way the changes + made by loading the \File{lco} file are local to the corresponding letter. \end{Example} -If\ChangedAt{v2.97}{\Class{scrlttr2}} an \File{lco}-file is loaded via -\Macro{documentclass}, then it may no longer have the same name as an option. +If\ChangedAt{v2.97}{\Class{scrlttr2}} an \File{lco} file is loaded via +\Macro{documentclass}, then it must not have the same name as an option. \begin{Example} - Since Mr~Public often writes letters with the same options and parameters, - he does not like to copy all these to each new letter. To simplify the effort - of writing a new letter, he therefore makes a \File{lco}-file:% + Since Mr Public often writes letters with the same options and parameters, + he finds it quite annoying to copy this information to each new letter. To + simplify the effort of writing a new letter, he therefore creates an + \File{lco} file:% \lstinputcode[xleftmargin=1em]{ich.lco}% - With this the size of the previous letter decreases to: - \lstinputcode[xleftmargin=1em]{letter-23.tex}% - Nevertheless, as shown in \autoref{fig:\LabelBase.letter-23}, the result - does not change. + With this, the size of his letter from the previous example shrinks + considerably: \lstinputcode[xleftmargin=1em]{letter-23.tex}% + Nevertheless, the result does not change, as shown in + \autoref{fig:\LabelBase.letter-23}. \begin{figure} \setcapindent{0pt}% \begin{captionbeside}[{Example: letter with extended sender, logo, - addressee, additional sender information, place, date, subject, + recipient, extra sender information, place, date, subject, opening, text, closing, modified signature, postscript, distribution - list, enclosure, and puncher hole mark using a \File{lco}-file}] - {result of a small letter with extended sender, logo, addressee, - additional sender information, place, date, subject opening, text, + list, enclosure, and hole-punch mark using an \File{lco} file}] + {result of a short letter with extended sender, logo, recipient, + extra sender information, place, date, subject opening, text, closing, modified signature, postscript, distribution list, enclosure - and puncher hole mark using a \File{lco}-file}[l] + and hole-punch mark using an \File{lco} file}[l] \frame{\includegraphics[width=.4\textwidth]{letter-23}} \end{captionbeside} \label{fig:\LabelBase.letter-23} \end{figure} \end{Example} -Please note\textnote{Attention!} that immediately after loading the -document class normally neither a package for the input encoding nor a -language package has been loaded. Because of this, you should use \TeX's 7-bit -encoding for all characters, e.\,g., use ``\Macro{ss}'' to produce a German +Note\textnote{Attention!} that immediately after loading the document class, +normally neither a package for the input encoding nor a language package has +been loaded. Because of this, you should use \TeX's 7-bit encoding for all +non-ASCII characters. For example, use ``\Macro{ss}'' to produce a German ``\ss''. In \autoref{tab:lcoFiles}, \autopageref{tab:lcoFiles} you can find a list of all predefined \File{lco} files. If\textnote{Attention!} you use a printer that has large unprintable areas on the left or right side, you might have problems with the \Option{SN}\IndexOption{SN} option. Since the Swiss standard -SN~101\,130 defines the address field to be placed 8\Unit{mm} from the right -paper edge, the headline and the sender attributes too will be set with the -same small distance from the paper edge. This also applies to the reference -line when using the \DescRef{\LabelBase.option.refline}\PValue{=wide} option -(see \autoref{sec:\LabelBase.firstpage}, -\DescPageRef{\LabelBase.option.refline}). If\textnote{Hint!} you have this -kind of problem, create your own \File{lco} file that loads \Option{SN} first -and then changes \PLength{toaddrhpos}\IndexPLength{toaddrhpos} (see +SN~101\,130 stipulates that the address field should be placed 8\Unit{mm} from +the right edge of the paper, the headline and the sender attributes are also +placed at a correspondingly small distance from the paper edge. This also +applies to the reference line when using the +\DescRef{\LabelBase.option.refline}\PValue{=wide} option (see +\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.option.refline}). +If\textnote{Hint!} you have this kind of problem, create your own \File{lco} +file that loads \Option{SN} first and then changes +\PLength{toaddrhpos}\IndexPLength{toaddrhpos} (see \autoref{sec:scrlttr2-experts.addressee}, -\DescPageRef{scrlttr2-experts.plength.toaddrvpos}) to a smaller -value. Additionally, also reduce \PLength{toaddrwidth} accordingly.% +\DescPageRef{scrlttr2-experts.plength.toaddrvpos}) to a smaller value. In +addition, you should also reduce \PLength{toaddrwidth} accordingly.% -By\textnote{Hint!} the way, the \File{DIN} \File{lco}-file will always be -loaded as the first \File{lco} file. This ensures that all pseudo-lengths will -have more or less reasonable default values. Because of this, it is not -necessary to load this default file on your own. +By\textnote{Hint!} the way, the \File{DIN} \File{lco} file is always loaded +automatically as the first \File{lco} file. This ensures that all +pseudo-lengths will have more or less reasonable default values. Therefore you +do not need to load this default file on your own. -Please\textnote{Attention!} note that it is not possible to use -\Macro{PassOptionsToPackage} to pass options to packages from within an -\File{lco}-file that have already been loaded by the class. Normally, this -only applies to the \Package{typearea}, \Package{scrlfile}, \Package{scrbase}, -and \Package{keyval} packages.% +%Please\textnote{Attention!} note that it is not possible to use +%\Macro{PassOptionsToPackage} to pass options to packages from within an +%\File{lco} file that have already been loaded by the class. Normally, this +%only applies to the \Package{typearea}, \Package{scrlfile}, \Package{scrbase}, +%and \Package{keyval} packages.% \begin{desclist} \renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% \desccaption{% - predefined \File{lco}-files\label{tab:lcoFiles}% + Predefined \File{lco} files\label{tab:lcoFiles}% }{% - predefined \File{lco}-files (\emph{continuation})% + Predefined \File{lco} files (\emph{continued})% }% \oentry{DIN}{% - parameter set for letters on A4-size paper, complying with German standard + \leavevmode% + \IndexOption[indexmain]{DIN}\IndexFile[indexmain]{DIN.lco}% + parameters for letters on A4 paper, complying with German standard DIN~676; suitable for window envelopes in the sizes C4, C5, C6, and C6/5 (C6 long).}% \oentry{DINmtext}{% - parameter set for letters on A4-size paper, complying with DIN~676, but - using an alternate layout with more text on the first page; only suitable - for window envelopes in the sizes C6 and C6/5 (C6 long).}% + \leavevmode% + \IndexOption[indexmain]{DINmtext}\IndexFile[indexmain]{DINmtext.lco}% + parameters for letters on A4 paper, complying with DIN~676 but using an + alternate layout with more text on the first page; only suitable for + window envelopes in the sizes C6 and C6/5 (C6 long).}% \oentry{KakuLL}{% - parameter set for Japanese letters in A4 format; suitable for Japanese - window envelopes of type Kaku A4, in which the windows is approximately - 90\Unit{mm} wide, 45\Unit{mm} high, and positioned 25\Unit{mm} from the + \leavevmode% + \IndexOption[indexmain]{KakuLL}\IndexFile[indexmain]{KakuLL.lco}% + parameters for Japanese letters on A4 paper; suitable for Japanese + window envelopes of type Kaku A4, in which the window is approximately + 90\Unit{mm} wide by 45\Unit{mm} high, and positioned 25\Unit{mm} from the left and 24\Unit{mm} from the top edge (see \autoref{cha:japanlco}).}% \oentry{KOMAold}{% - parameter set for letters on A4-size paper using a layout close to the now + \leavevmode% + \IndexOption[indexmain]{KOMAold}\IndexFile[indexmain]{KOMAold.lco}% + parameters for letters on A4 paper using a layout close to that of the obsolete \Class{scrlettr} letter class; suitable for window envelopes in the sizes C4, C5, C6, and C6/5 (C6 long); some additional commands to improve compatibility with obsolete \Class{scrlettr} commands are defined; - \Class{scrlttr2} may behave slightly different when used with this - \File{lco}-file than with the other \File{lco}-files.}% + \Class{scrlttr2} may behave slightly differently with this \File{lco} file + than with the other \File{lco} files.}% \oentry{NF}{% - parameter set for French letters, according to NF~Z~11-001; suitable for - window envelopes of type DL (110\Unit{mm} to 220\Unit{mm}) with a window - of about 20\Unit{mm} from right and bottom with width 45\Unit{mm} and - height 100\Unit{mm}; this file was originally developed by Jean-Marie - Pacquet, who provides an extended version and additional information on + \leavevmode% + \IndexOption[indexmain]{NF}\IndexFile[indexmain]{NF.lco}% + parameters for French letters, complying with NF~Z~11-001; suitable for + window envelopes of type DL (110\Unit{mm} by 220\Unit{mm}) with a window + 45\Unit{mm} wide by 100\Unit{mm} high placed about 20\Unit{mm} from the + lower right edge; this file was originally developed by Jean-Marie + Pacquet, who also provides LyX integration in addition to extensions at \cite{www:NF.lco}.}% \oentry{NipponEH}{% - parameter set for Japanese letters in A4 format; suitable for Japanese - window envelopes of types Chou or You 3 or 4, in which the windows is - approximately 90\Unit{mm} wide, 55\Unit{mm} high, and positioned + \leavevmode% + \IndexOption[indexmain]{NipponEH}\IndexFile[indexmain]{NipponEH.lco}% + parameters for Japanese letters on A4 paper; suitable for Japanese + window envelopes of types Chou or You 3 or 4, in which the window is + approximately 90\Unit{mm} wide by 55\Unit{mm} high, and positioned 22\Unit{mm} from the left and 12\Unit{mm} from the top edge (see \autoref{cha:japanlco}).}% \oentry{NipponEL}{% - parameter set for Japanese letters in A4 format; suitable for Japanese - window envelopes of types Chou or You 3 or 4, in which the windows is - approximately 90\Unit{mm} wide, 45\Unit{mm} high, and positioned + \leavevmode% + \IndexOption[indexmain]{NipponEL}\IndexFile[indexmain]{NipponEL.lco}% + parameters for Japanese letters on A4 paper; suitable for Japanese + window envelopes of types Chou or You 3 or 4, in which the window is + approximately 90\Unit{mm} wide by 45\Unit{mm} high, and positioned 22\Unit{mm} from the left and 12\Unit{mm} from the top edge (see \autoref{cha:japanlco}).}% \oentry{NipponLH}{% - parameter set for Japanese letters in A4 format; suitable for Japanese - window envelopes of types Chou or You 3 or 4, in which the windows is - approximately 90\Unit{mm} wide, 55\Unit{mm} high, and positioned + \leavevmode% + \IndexOption[indexmain]{NipponLH}\IndexFile[indexmain]{NipponLH.lco}% + parameters for Japanese letters on A4 paper; suitable for Japanese + window envelopes of types Chou or You 3 or 4, in which the window is + approximately 90\Unit{mm} wide by 55\Unit{mm} high, and positioned 25\Unit{mm} from the left and 12\Unit{mm} from the top edge (see \autoref{cha:japanlco}).}% \oentry{NipponLL}{% - parameter set for Japanese letters in A4 format; suitable for Japanese - window envelopes of types Chou or You 3 or 4, in which the windows is - approximately 90\Unit{mm} wide, 45\Unit{mm} high, and positioned + \leavevmode% + \IndexOption[indexmain]{NipponLL}\IndexFile[indexmain]{NipponLL.lco}% + parameters for Japanese letters on A4 paper; suitable for Japanese + window envelopes of types Chou or You 3 or 4, in which the window is + approximately 90\Unit{mm} wide by 45\Unit{mm} high, and positioned 25\Unit{mm} from the left and 12\Unit{mm} from the top edge (see \autoref{cha:japanlco}).}% \oentry{NipponRL}{% - parameter set for Japanese letters in A4 format; suitable for Japanese - window envelopes of types Chou or You 3 or 4, in which the windows is - approximately 90\Unit{mm} wide, 45\Unit{mm} high, and positioned + \leavevmode% + \IndexOption[indexmain]{NipponRL}\IndexFile[indexmain]{NipponRL.lco}% + parameters for Japanese letters on A4 paper; suitable for Japanese + window envelopes of types Chou or You 3 or 4, in which the window is + approximately 90\Unit{mm} wide by 45\Unit{mm} high, and positioned 25\Unit{mm} from the left and 24\Unit{mm} from the top edge (see \autoref{cha:japanlco}).}% \oentry{SN}{% - parameter set for Swiss letters with address field on the right side, + \leavevmode% + \IndexOption[indexmain]{SN}\IndexFile[indexmain]{SN.lco}% + parameters for Swiss letters with the address field on the right side, according to SN~010\,130; suitable for Swiss window envelopes in the sizes C4, C5, C6, and C6/5 (C6 long).}% \oentry{SNleft}{% - parameter set for Swiss letters with address field on the left side; - suitable for Swiss window envelopes with window on the left side in the - sizes C4, C5, C6, and C6/5 (C6 long).}% + \leavevmode% + \IndexOption[indexmain]{SNleft}\IndexFile[indexmain]{SNleft.lco}% + parameters for Swiss letters with the address field on the left side; + suitable for Swiss window envelopes with the window on the left side in + the sizes C4, C5, C6, and C6/5 (C6 long).}% \oentry{UScommercial9}{% - parameter set for US-American letters with paper size letter; suitable for - US-American window envelopes of size \emph{commercial~No.\,9} with window - width of 4\,1/2\Unit{in}, height of 1\,1/8\Unit{in}, and position of - 7/8\Unit{in} from the left and 1/2\Unit{in} from the bottom, without - sender's return address inside of the window; with folding it first at the - puncher mark then at the top folder mark also legal paper may be used but - would result in a page size warning}% + \leavevmode% + \IndexOption[indexmain]{UScommercial9}% + \IndexFile[indexmain]{UScommercial9.lco}% + parameters for US letters on American letter paper; suitable for + \emph{commercial~No.\,9} US window envelopes with a window 4\,1/2\Unit{in} + wide by 1\,1/8\Unit{in} high, positioned 7/8\Unit{in} from the left and + 1/2\Unit{in} from the bottom, without the return address inside the + window; when folded first at the middle mark then at the top fold mark, + legal paper can also be used but results in a paper-size warning}% \oentry{UScommercial9DW}{% - parameter set for US-American letters with paper size letter; suitable for - US-American window envelopes of size \emph{commercial~No.\,9} with - addressee's window width of 3\,5/8\Unit{in}, height of 1\,1/8\Unit{in}, - and position of 3/4\Unit{in} from the left and 1/2\Unit{in} from the - bottom, and with a sender's window width of 3\,1/2\Unit{in}, height of - 7/8\Unit{in}, and position of 5/16\Unit{in} from the left and - 2\,1/2\Unit{in} from the bottom, but without a sender's return address at - any of the windows; with folding it first at the puncher mark then at the - top folder mark also legal paper may be used but would result in a page - size warning}% + \leavevmode% + \IndexOption[indexmain]{UScommercial9DW}% + \IndexFile[indexmain]{UScommercial9DW.lco}% + parameters for US letters on American letter paper; suitable for + \emph{commercial~No.\,9} US window envelopes with an recipient-address + window 3\,5/8\Unit{in} wide by 1\,1/8\Unit{in} high, positioned + 3/4\Unit{in} from the left and 1/2\Unit{in} from the bottom, and with a + return-address window 3\,1/2\Unit{in} wide by 7/8\Unit{in} high, + positioned 5/16\Unit{in} from the left and 2\,1/2\Unit{in} from the + bottom; when folded first at the middle mark and then at the top fold + mark, legal paper can also be used but results in a paper-size warning}% \end{desclist} % \EndIndexGroup @@ -3020,182 +3211,183 @@ and \Package{keyval} packages.% \EndIndexGroup -\section{Address Files and Circular Letters} +\section{Address Files and Form Letters} \seclabel{addressFile}% \BeginIndexGroup \BeginIndex{}{address>file}% -\BeginIndex{}{circular letters}% -\index{serial letters|see circular letters}% +\BeginIndex{}{form letters}% +\index{serial letters|see form letters}% +\index{circular letters|see form letters}% -When people write circular letters one of the more odious tasks is the typing -of many different addresses. The class \Class{scrlttr2}% +One of the most annoying things about creating form letters is typing up +the different addresses. \KOMAScript{} provides basic support for this task% \iffalse% Umbruchkorrekturtext -, as did its predecessor \Class{scrlettr} as well,% +, as did its predecessor \Class{scrlettr}% \fi% -\ provides basic support for this task.% +.% \iffalse% Umbruchkorrekturtext -\ Currently there are plans for much enhanced support.% +\ Currently there are plans for greatly enhanced support.% \fi \begin{Declaration} - \Macro{adrentry}\Parameter{last-name}\Parameter{first-name}% + \Macro{adrentry}\Parameter{last~name}\Parameter{first~name}% \Parameter{address}\Parameter{phone}\Parameter{F1}\Parameter{F2}% \Parameter{comment}\Parameter{key} \end{Declaration}% -The class \Class{scrlttr2} supports the use of address files which -contain address entries, very useful for circular letters. The file -extension of the address file has to be \File{.adr}. Each entry is an -\Macro{adrentry} command with eight parameters, for example: +\Class{scrlttr2} and \Package{scrletter} can evaluate address files. +This can be very useful for form letters. An address file must have the +extension \File{.adr} and consists of a number \Macro{adrentry} entries. +An individual entry consists of eight parameters and may look, for example, +like this: \begin{lstcode} \adrentry{McEnvy} {Flann} - {Main Street 1\\ Glasgow} - {123 4567} - {male} + {1 High Street\\ Glasgow} + {0141 123 4567} + {builder} {} - {niggard} + {buys everything} {FLANN} \end{lstcode} -The 5\textsuperscript{th} and 6\textsuperscript{th} elements, \PValue{F1} and -\PValue{F2}, can be used freely: for example, for the gender, the academic -grade, the birthday, or the date on which the person joined a society. The -last parameter \PName{key} should only consist of more than one uppercase -letters in order to not interfere with existing {\TeX} or {\LaTeX} commands. +You can use the fifth and sixth elements, \PValue{F1} and \PValue{F2}, for +anything you want. Gender, academic grade, birth date, or the date the person +joined a society are all possibilities. The last parameter, \PName{key}, +should consist of more than one letter and be upper-case only so as not to +interfere with existing \TeX{} or \LaTeX{} commands. \begin{Example} - Mr McEnvy is one of your most important business partners, but - every day you receive correspondence from him. Before long you do - not want to bother typing his boring address again and again. Here - \Class{scrlttr2} can help. Assume that all your business partners - have an entry in your \File{partners.adr} address file. If you now - have to reply to Mr~McEnvy again, then you can save typing as - follows: + Mr McEnvy is one of your most important business partners. Since you + maintain a frequent correspondence with him, it is too tedious to + enter all his data again and again. \KOMAScript{} will do this work for you. + For example, if you have saved your customer contacts in the + \File{partners.adr} address file and you would like to write a letter to + Mr~McEnvy, you can save a great deal of effort by typing: \begin{lstcode} \input{partners.adr} \begin{letter}{\FLANN} Your correspondence of today \dots \end{letter} \end{lstcode} - Your {\TeX} system must be configured to have access to your address - file. Without access, the \Macro{input} command results in an - error. You can either put your address file in the same directory - where you are running {\LaTeX}, or configure your system to find the - file in a special directory. + Please make sure that your {\TeX} system can access your address file. + Otherwise the \Macro{input} command results in an error message. You can + either put your address file in the same directory as your letter or + configure your \TeX{} system to look for a dedicated address directory. \end{Example} % \EndIndexGroup + \begin{Declaration} \Macro{addrentry}\Parameter{last-name}\Parameter{first-name}% \Parameter{address}\Parameter{phone}\Parameter{F1}\Parameter{F2}% \Parameter{F3}\Parameter{F4}\Parameter{key} \end{Declaration}% -Over the years people have objected that the \DescRef{\LabelBase.cmd.adrentry} has only two -free parameters. To cater to this demand, there now exists a new command -called \Macro{addrentry}\,---\,note the additional ``d''\,---\,which supports -four freely-definable parameters. Since {\TeX} supports maximally nine -parameters per command, the comment parameter has fallen away. Other than this -difference, the use is the same as that of \DescRef{\LabelBase.cmd.adrentry}. - -Both \DescRef{\LabelBase.cmd.adrentry} and \Macro{addrentry} commands can be freely mixed in -the \File{adr} files. However, it should be noted that there are some packages -which are not suited to the use of \Macro{addrentry}. For example, the -\Package{adrconv} by Axel Kielhorn can be used to create address lists from -\File{adr} files, but it has currently no support for command -\Macro{addrentry}. In this case, the only choice is to extend the package -yourself.% +Before you object that a total of two free parameters is too few, +\KOMAScript{} alternatively offers the \Macro{addrentry} command\,---\,note +the additional ``d''\,---\,which adds two more freely definable parameters but +omits the comment parameter. Otherwise, you can use this command in exactly +the same way as \DescRef{\LabelBase.cmd.adrentry}. + +Both \DescRef{\LabelBase.cmd.adrentry} and \Macro{addrentry} commands can be +freely mixed in the \File{adr} files. I should note, however, that other +packages, such as \Package{adrconv}\IndexPackage{adrconv} by Axel Kielhorn, +may not be designed to use \Macro{addrentry}. If necessary, you have to create +the appropriate extensions yourself.% % \EndIndexGroup -Besides the simple access to addresses, the address files can be -easily used in order to write circular letters. Thus, there is no -requirement to access a complicated database system via {\TeX}. +In addition to simplifying access to addresses, you can also use the +\File{adr} files to create circulars or form letters. Thus you can create such +mass mailings without a complicated connection to a database system. % \begin{Example} - Suppose you are member of a society and want write an invitation for - the next general meeting to all members. + You want to sent a form letter to all members of your fishing club to invite + them to the next general meeting. \begin{lstcode} \documentclass{scrlttr2} \begin{document} \renewcommand*{\adrentry}[8]{ \begin{letter}{#2 #1\\#3} - \opening{Dear members,} Our next general meeting will be on - Monday, August 12, 2002. The following topics are \dots + \opening{Dear members,} + Our next general meeting will be on + Monday, 12 August 2002. + + The following topics are \dots \closing{Regards,} \end{letter} } \input{members.adr} \end{document} \end{lstcode} - If the address file contains \DescRef{\LabelBase.cmd.addrentry} commands too, than an - additional definition for \DescRef{\LabelBase.cmd.addrentry} is required before loading - the address file: + If the address file also contains \DescRef{\LabelBase.cmd.addrentry} + commands, you must add a corresponding definition before loading the address + file: \begin{lstcode} \renewcommand*{\addrentry}[9]{% \adrentry{#1}{#2}{#3}{#4}{#5}{#6}{#7}{#9}% } \end{lstcode} - In this simple example the extra freely-definable parameter is not - used, and therefore \DescRef{\LabelBase.cmd.addrentry} is defined with the help of + In this example, the extra freely-definable parameter is not used, and + therefore \DescRef{\LabelBase.cmd.addrentry} is defined using \DescRef{\LabelBase.cmd.adrentry}. \end{Example} -With some additional programming one can let the content of the -letters depend on the address data. For this the free parameters of -the \DescRef{\LabelBase.cmd.adrentry} and and \DescRef{\LabelBase.cmd.addrentry} commands can be used. - +Of course, the letter's contents can also be adapted to the characteristics of +the address data. You can use the free parameters of the +\DescRef{\LabelBase.cmd.adrentry} and \DescRef{\LabelBase.cmd.addrentry} +commands for this. \begin{Example} - Suppose the 5\textsuperscript{th} parameter of the \DescRef{\LabelBase.cmd.adrentry} - command contains the gender of a member (\PValue{m/f}), and the - 6\textsuperscript{th} parameter contains what amount of subscription - has not yet been paid by the member. If you would like to write a - more personal reminder to each such member, then the next example - can help you: + Suppose you use the fifth parameter of the \DescRef{\LabelBase.cmd.adrentry} + command to indicate the gender of a club member (\PValue{m/f}), and the + sixth parameter to indicate the amount of membership dues that is unpaid. + If you would like to write a reminder to each such member and address them + personally, the next example will help you: \begin{lstcode} \renewcommand*{\adrentry}[8]{ \ifdim #6pt>0pt\relax - % #6 is an amount greater than 0. - % Thus, this selects all members with due subscription. + % #6 is an amount (floating-point number) greater than 0. + % Thus, this selects all members owing dues. \begin{letter}{#2 #1\\#3} - \if #5m \opening{Dear Mr.\,#2,} \fi - \if #5f \opening{Dear Mrs.\,#2,} \fi + \if #5m \opening{Dear Mr #2,} \fi + \if #5f \opening{Dear Ms #2,} \fi - Unfortunately we have to remind you that you have - still not paid the member subscription for this - year. + Unfortunately, we have noticed that you are in arrears + with the payment of your membership fees. - Please remit EUR #6 to the account of the society. + Please remit the outstanding balance of \pounds #6 to the club + account. \closing{Regards,} \end{letter} \fi } \end{lstcode} \end{Example} -As you can see, the letter text can be made more personal by depending on -attributes of the letter's addressee. The number of attributes is only -restricted by number of two free parameters of the \DescRef{\LabelBase.cmd.adrentry} command, -or four free parameters of the \DescRef{\LabelBase.cmd.addrentry} command. +It is therefore possible to tailor the text of the letter to the specific +characteristics of the recipient and create the impression of a personal +letter. The extent of the customisation is only limited by the maximum number +of two free \DescRef{\LabelBase.cmd.adrentry} parameters and four free +\DescRef{\LabelBase.cmd.addrentry} parameters. \begin{Declaration} \Macro{adrchar}\Parameter{initial letter}% \Macro{addrchar}\Parameter{initial letter} \end{Declaration} -\Index[indexmain]{address>list}\Index[indexmain]{telephone list}% -As already mentioned above, it is possible to create address and telephone -lists using \File{adr} files. For that, the additional package -\Package{adrconv} by Axel Kielhorn (see \cite{package:adrconv}) is needed. -This package contains interactive {\LaTeX} documents which help to create -those lists. - -The address files have to be sorted already in order to obtain sorted -lists. It is recommended to separate the sorted entries at each different -initial letter of \PName{last name}. As a separator, the commands -\Macro{adrchar} and \Macro{addrchar} can be used. These commands will be -ignored if the address files are utilized in \Class{scrlettr2}. +\Index[indexmain]{address>list}\Index[indexmain]{telephone directory}% +It is possible to create address lists and telephone directories using +\File{adr} files. You also need the \Package{adrconv}\IndexPackage{adrconv} +package by Axel Kielhorn (see \cite{package:adrconv}). This package contains +interactive \LaTeX{} documents which make it easy to create such lists. + +The address files have to be sorted already in order to obtain sorted lists. +It is advisable to insert an \Macro{adrchar} or \Macro{addrchar} command +containing the initial letter of the \PName{last name} before the point in the +list where this letter changes. \Class{scrlettr2} and \Package{scrletter} will +ignore these commands. % \begin{Example} - Suppose you have the following short address file: + Suppose you have the following, rather tiny address file from which you + want to create an address book: \begin{lstlisting} \adrchar{A} \adrentry{Angel}{Gabriel} @@ -3210,9 +3402,16 @@ ignored if the address files are utilized in \Class{scrlettr2}. {+49~62\,03~1\,??\,??}{}{}{no angel at all} {KOMA} \end{lstlisting} - This address file can be treated with \File{adrdir.tex} of the - \Package{adrconv} package~\cite{package:adrconv}. - The result should look like this: + You can now process these entries using the \File{adrdir.tex} document from + \cite{package:adrconv}. One potential problem with this is that + \File{adrdir.tex} up to and including Version~1.3 uses both the obsolete + \Package{scrpage} package and obsolete font commands which \KOMAScript{} has + not supported for some time. If you receive an error message and cannot + install a newer version, you can find a listing of \File{adrdir.tex} which + indicates the changes necessary to avoid these errors at + \cite{https://komascript.de/node/2154} (in German). + + The result looks something like this: \begin{center} \setlength{\unitlength}{1mm} \begin{picture}(80,57) @@ -3237,15 +3436,15 @@ ignored if the address files are utilized in \Class{scrlettr2}. \qbezier(0,3)(10,6)(40,3)\qbezier(40,3)(60,0)(80,3) \end{picture} \end{center} - The letter in the page header is created by the \Macro{adrchar} - command. The definition can be found in \File{adrdir.tex}. + The letter in the header is generated by answering ``no'' to the + question ``Names in the header?'' See explanation in \File{adrdir.tex}. \end{Example} -More about the \Package{adrconv} package can be found in its -documentation. There you should also find information about whether the +You can find more about the \Package{adrconv}\IndexPackage{adrconv} package in +its documentation. There you should also find information about whether the current version of \Package{adrconv} supports the -\DescRef{\LabelBase.cmd.addrentry} and \Macro{addrchar} commands. Former -versions only know the commands \DescRef{\LabelBase.cmd.adrentry} and -\Macro{adrchar}.% +\DescRef{\LabelBase.cmd.addrentry} and \Macro{addrchar} commands. Previous +versions only recognised the \DescRef{\LabelBase.cmd.adrentry} and +\Macro{adrchar} commands.% % \EndIndexGroup % @@ -3253,6 +3452,7 @@ versions only know the commands \DescRef{\LabelBase.cmd.adrentry} and % \EndIndexGroup +\endinput %%% Local Variables: %%% mode: latex @@ -3261,6 +3461,3 @@ versions only know the commands \DescRef{\LabelBase.cmd.adrentry} and %%% ispell-local-dictionary: "en_GB" %%% TeX-master: "../guide" %%% End: - -% LocalWords: scrlttr simpleSwitchValues afteropening beforeopening Combinable -% LocalWords: locfield Hennig Kohm Foldmarks diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2examples.dtx b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2examples.dtx index acfbde56775..18286886b38 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2examples.dtx +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2examples.dtx @@ -2,7 +2,7 @@ % \iffalse % ====================================================================== % scrlttr2examples.dtx -% Copyright (c) Markus Kohm, 2008-2013 +% Copyright (c) Markus Kohm, 2008-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -20,7 +20,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrlttr2examples.dtx -% Copyright (c) Markus Kohm, 2008-2013 +% Copyright (c) Markus Kohm, 2008-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -101,13 +101,13 @@ % \begin{macrocode} %<*lco&23> \ProvidesFile{ich.lco}[2008/06/11 lco -% (John Public)] +% (Joe Public)] % (Peter Musterfrau)] \KOMAoptions{foldmarks=true,foldmarks=blmtP, fromphone,fromemail,fromlogo,subject=titled} %<*english> -\setkomavar{fromname}{John Public} -\setkomavar{signature}{John Public\\ +\setkomavar{fromname}{Joe Public} +\setkomavar{signature}{Joe Public\\ (former chairman)} % %<*ngerman> @@ -117,15 +117,16 @@ % \renewcommand*{\raggedsignature}{\raggedright} %<*english> -\setkomavar{fromaddress}{Valley 2\\ - 54321 Public-Village} +\setkomavar{fromaddress}{2 Valley\\ + SAMPLEBY\\ + ZY32 1XW} % %<*ngerman> \setkomavar{fromaddress}{Hinter dem Tal 2\\ 54321 Musterheim} % \setkomavar{fromphone}{0\,12\,34~56\,78} -%\setkomavar{fromemail}{Peter@Public.invalid} +%\setkomavar{fromemail}{joe@public.invalid} %\setkomavar{fromemail}{Peter@Musterfrau.invalid} \setkomavar{fromlogo}{% \includegraphics{musterlogo}} @@ -134,7 +135,7 @@ Club member no.~4711\\ since 11.09.2001\\ chairman 2003--2005} -\setkomavar{place}{Public-Village} +\setkomavar{place}{Sampleby} \setkomavar{frombank}{Bank of Friendly Greetings} % %<*ngerman> @@ -192,15 +193,15 @@ %\LoadLetterOption{NipponEL} % +%<*ngerman> \setkomavar{fromaddress}{Hinter dem Tal 2\\ 54321 Musterheim} +% %<*!9&!10&!11> \setkomavar{fromphone}{0\,12\,34~56\,78} -\setkomavar{fromemail}{Peter@Musterfrau.invalid} +%\setkomavar{fromemail}{joe@public.invalid} +%\setkomavar{fromemail}{Peter@Musterfrau.invalid} %<*!12&!13&!14&!15> \setkomavar{fromlogo}{\includegraphics{musterlogo}} % @@ -191,20 +231,38 @@ %<*19|20|21|22|23|label> %<*!23&!label&!nipponA&!nipponB> \setkomavar{location}{\raggedright +%<*english> + Club member no.~4711\\ + since 11.09.2001\\ + chairman 2003--2005} +% +%<*ngerman> Mitglied Nr.~4711\\ seit dem 11.09.2001\\ Vorsitzender in den Jahren 2003--2005} +% % %<*20|21|22|23|label> -\setkomavar{date}{29. Februar 2011} -%\setkomavar{place}{Musterheim} +%\setkomavar{date}{29th February 2011} +%\setkomavar{date}{29. Februar 2011} +%<*!23&!label> +%\setkomavar{place}{Sampleby} +%\setkomavar{place}{Musterheim} +% %<*21|22|23|label> -\setkomavar{subject}{Mitgliederversammlung vermisst} +%\setkomavar{subject}{Missing general meeting} +%\setkomavar{subject}{Mitgliederversammlung vermisst} % % % %\begin{letter}{% %<5>\begin{letter}[fontsize=14pt]{% +%<*english> + Joanna Public\\ + 1 Hillside\\ + SAMPLESTEAD\\ + WX12 3YZ% +% %<*ngerman> Petra Mustermann\\ Vor dem Berg 1\\ @@ -212,28 +270,48 @@ % } % %<*!1> +%<*english> +\ps PS: I hope you do not take this request amiss. +% %<*ngerman> \ps PS: Ich hoffe, Du nimmst mir das nicht krumm. % %<*!2> %<*!3> +%<*english> +\setkomavar*{enclseparator}{Enclosure} +\encl{Excerpt from the articles governing general + meetings} +% %<*ngerman> \setkomavar*{enclseparator}{Anlage} \encl{Auszug aus der Satzung, in dem die Mitgliederversammlungen geregelt sind} % % +%<*english> +\cc{executive board\\all members} +% %<*ngerman> \cc{Die Vereinsvorsitzende\\Alle Mitglieder} % diff --git a/Master/texmf-dist/source/latex/koma-script/doc/ngerman/scrwfile.tex b/Master/texmf-dist/source/latex/koma-script/doc/ngerman/scrwfile.tex index cec15276397..4e27aa22eb4 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/ngerman/scrwfile.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/ngerman/scrwfile.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrwfile.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrwfile.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,7 +46,7 @@ % ============================================================================ \KOMAProvidesFile{scrwfile.tex} - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-02-16 04:42:17 +0100 (Fri, 16 Feb 2018) $ KOMA-Script guide (chapter: scrwfile)] \chapter{Dateien mit \Package{scrwfile} sparen und ersetzen} @@ -69,7 +69,12 @@ Im Endeffekt kann es daher geschehen, dass irgendwann die Meldung \ch@ck ...\else \errmessage {No room for a new #3} \fi \end{lstcode} -erscheint. +erscheint. Seit einiger Zeit ist die einfachste Lösung dieses Problems die +Verwendung von Lua\LaTeX{} anstelle von PDF\LaTeX{} oder \XeLaTeX. Damit +entfällt die Beschränkung und die maximale Anzahl der gleichzeitig zum +Schreiben geöffneten Dateien wird nur noch durch das Betriebssystem +bestimmt. In der Realität braucht man sich darüber dann normalerweise keine +Gedanken mehr zu machen. Dass \LaTeX{} bei Verzeichnissen wie dem Inhaltsverzeichnis, dem Tabellenverzeichnis und dem Abbildungsverzeichnis immer sofort eine neue Datei @@ -79,7 +84,8 @@ auch kein weiteres Mal gesetzt werden, da die zugeh jeweiligen Befehl bis zum Ende des Dokuments leer ist. Das Paket \Package{scrwfile} bietet hier eine grundsätzliche Änderung im -\LaTeX-Kern, durch die beide Probleme gelöst werden können. +\LaTeX-Kern, durch die beide Probleme nicht nur für Lua\LaTeX{} sondern auch bei +Verwendung von PDF\LaTeX{} oder \XeLaTeX{} gelöst werden können. \section{Grundsätzliche Änderungen am \LaTeX-Kern} @@ -109,11 +115,7 @@ Nat Potential, dass es zu Unverträglichkeiten mit anderen Paketen kommen kann. Betroffen können in erster Linie Pakete sein, die ebenfalls \Macro{@starttoc} oder \Macro{@writefile} umdefinieren. In einigen Fällen kann -es helfen, die Reihenfolge der Pakete zu ändern. - -Tatsächlich sind bisher keine solchen Probleme im Zusammenhang mit -\Package{scrwfile} bekannt, obwohl das Paket vor der Veröffentlichung von -verschiedenen Anwendern über ein Jahr lang getestet wurde. Wenn Sie jedoch auf +es helfen, die Reihenfolge der Pakete zu ändern. Wenn Sie auf ein solches Problem stoßen, sollten Sie sich an den \KOMAScript-Autor wenden. @@ -131,15 +133,15 @@ ge \Macro{end}\PParameter{document} wird dann \Macro{@writefile} so umdefiniert, dass diese Anweisung statt in die eigentlichen Hilfsdateien in eine neue Hilfsdatei mit der Endung \File{wrt} schreibt. Nach dem Einlesen der -\File{aux}-Dateien wird dann noch die \File{wrt}-Datei abgearbeitet und zwar +\File{aux}-Dateien wird schließlich die \File{wrt}-Datei abgearbeitet und zwar ein Mal für jede der Hilfsdateien, in die mit \Macro{@writefile} geschrieben -wird. Dabei muss dann aber nicht jede dieser Hilfsdateien gleichzeitig +wird. Dabei muss aber nicht jede dieser Hilfsdateien gleichzeitig geöffnet sein. Stattdessen ist immer nur eine zum Schreiben geöffnet und wird auch wieder explizit geschlossen. Da dabei eine interne Schreibdatei von \LaTeX{} wiederverwendet wird, benötigt \Package{scrwfile} keine einzige eigene Schreibdatei für diese Art von Verzeichnissen. -Selbst, wenn bisher nur mit einem Inhaltsverzeichnis gearbeitet wird, steht +Selbst wenn bisher nur mit einem Inhaltsverzeichnis gearbeitet wird, steht nach dem Laden des Pakets bereits eine Schreibdatei mehr für Literaturverzeichnisse, Stichwortverzeichnisse, Glossare und ähnliche Verzeichnisse, die nicht mit \Macro{@starttoc} arbeiten, zur @@ -169,23 +171,26 @@ kann man in dieses geklonte Verzeichnis auch zus schreiben. Die \PName{Zielendung} der Zieldatei wird mit Hilfe von -\Package{tocbasic}\important{\Package{tocbasic}} (siehe +\hyperref[cha:tocbasic]{\Package{tocbasic}}% +\important{\hyperref[cha:tocbasic]{\Package{tocbasic}}} (siehe \autoref{cha:tocbasic}) verwaltet. Steht eine solche Datei bereits unter -Kontrolle von \Package{tocbasic} wird eine Warnung ausgegeben. Anderenfalls -wird mit Hilfe von \Package{tocbasic} ein neues Verzeichnis für diese Endung -angelegt. Die Überschrift dieses Verzeichnisses kann man über das optionale -Argument \PName{Verzeichnisüberschrift} bestimmen. +Kontrolle von \hyperref[cha:tocbasic]{\Package{tocbasic}} wird eine Warnung +ausgegeben. Anderenfalls wird mit Hilfe von +\hyperref[cha:tocbasic]{\Package{tocbasic}} ein neues Verzeichnis für diese +Endung angelegt. Die Überschrift dieses Verzeichnisses kann man über das +optionale Argument \PName{Verzeichnisüberschrift} bestimmen. Ausgeben kann man dieses neue Verzeichnis dann beispielsweise über die Anweisung \Macro{listof\PName{Zielendung}}. Die -Verzeichniseigenschaften\important{\Package{tocbasic}} \PValue{leveldown}, -\PValue{numbered}, \PValue{onecolumn} und \PValue{totoc} (siehe Anweisung -\DescRef{tocbasic.cmd.setuptoc} in \autoref{sec:tocbasic.toc}, -\DescPageRef{tocbasic.cmd.setuptoc}) werden automatisch in das -Zielverzeichnis übernommen, falls sie für das Quellverzeichnis bereits gesetzt -waren. Die Eigenschaft \PValue{nobabel} wird für geklonte Verzeichnisse immer -gesetzt, da die entsprechenden \Package{babel}-Einträge in das -Quellverzeichnis ohnehin bereits kopiert werden. +Verzeichniseigenschaften\important{\hyperref[cha:tocbasic]{\Package{tocbasic}}} +\PValue{leveldown}, \PValue{numbered}, \PValue{onecolumn} und \PValue{totoc} +(siehe Anweisung \DescRef{tocbasic.cmd.setuptoc} in +\autoref{sec:tocbasic.toc}, \DescPageRef{tocbasic.cmd.setuptoc}) werden +automatisch in das Zielverzeichnis übernommen, falls sie für das +Quellverzeichnis bereits gesetzt waren. Die Eigenschaft \PValue{nobabel} wird +für geklonte Verzeichnisse immer gesetzt, da die entsprechenden +\Package{babel}-Einträge in das Quellverzeichnis ohnehin bereits kopiert +werden. \begin{Example} Angenommen, Sie wollen zusätzlich zum normalen Inhaltsverzeichnis eine @@ -222,29 +227,34 @@ Quellverzeichnis ohnehin bereits kopiert werden. Gliederungsübersicht angezeigt werden soll. Dies wäre zwar mit \begin{lstcode} \addtocontents{toc}{% - \protect\addcontentsline + \protect\addxcontentsline {stoc}{chapter}{\protect\contentsname}% } \end{lstcode} möglich. Da jedoch alle Einträge in \File{toc} auch nach \File{stoc} kopiert werden, würde so von der Gliederungsübersicht dieser Eintrag ebenfalls übernommen. Also darf der Eintrag nicht aus der Verzeichnisdatei heraus - erzeugt werden. Da das Paket \Package{tocbasic}\important{\Package{tocbasic}} - zum Einsatz kommt, kann aber - \phantomsection\xmpllabel{cmd.BeforeStartingTOC} + erzeugt werden. Da das Paket \hyperref[cha:tocbasic]{\Package{tocbasic}}% + \important{\hyperref[cha:tocbasic]{\Package{tocbasic}}} zum Einsatz kommt, + kann aber% + \phantomsection\xmpllabel{cmd.BeforeStartingTOC}% \begin{lstcode} \BeforeStartingTOC[toc]{% - \addcontentsline{stoc}{chapter} - {\protect\contentsname}} + \addxcontentsline{stoc}{chapter} + {\protect\contentsname}} \end{lstcode} verwendet werden. Natürlich\textnote{Achtung!} setzt dies voraus, dass die - Datei mit Endung \File{toc} auch unter der Kontrolle von \Package{tocbasic} - steht. Dies ist bei allen \KOMAScript-Klassen der Fall. Näheres zur - Anweisung \DescPageRef{tocbasic.cmd.BeforeStartingTOC} ist in - \autoref{sec:tocbasic.toc} auf \DescPageRef{tocbasic.cmd.BeforeStartingTOC} - zu finden. -\end{Example} + Datei mit Endung \File{toc} auch unter der Kontrolle von + \hyperref[cha:tocbasic]{\Package{tocbasic}} steht. Dies ist bei allen + \KOMAScript-Klassen der Fall. Näheres zur Anweisung + \DescRef{tocbasic.cmd.BeforeStartingTOC} ist in \autoref{sec:tocbasic.toc} + auf \DescPageRef{tocbasic.cmd.BeforeStartingTOC} zu finden.% +\end{Example}% % +Die in den Beispielen verwendete Anweisung +\DescRef{tocbasic.cmd.addxcontentsline} ist übrigens ebenfalls in +\autoref{cha:tocbasic}, \DescPageRef{tocbasic.cmd.addxcontentsline} +dokumentiert.% \EndIndexGroup @@ -293,5 +303,5 @@ in \Package{titletoc} noch in \Package{scrwfile}.% % LocalWords: Eindateiensystem Schreibdatei Zieldatei Zielendung Quellendung % LocalWords: Verzeichnisüberschrift Dateiendung Zielendungen Verzeichnisdatei % LocalWords: Benutzeranweisungen Dokumentpräambel Kapitelebene -% LocalWords: Paketunverträglichkeiten +% LocalWords: Paketunverträglichkeiten Verzeichniseigenschaften diff --git a/Master/texmf-dist/source/latex/koma-script/doc/ngerman/tocbasic.tex b/Master/texmf-dist/source/latex/koma-script/doc/ngerman/tocbasic.tex index 61c285c4754..e8532e621a9 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/ngerman/tocbasic.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/ngerman/tocbasic.tex @@ -1,6 +1,6 @@ % ====================================================================== % tocbasic.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % tocbasic.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,7 +46,7 @@ % ====================================================================== \KOMAProvidesFile{tocbasic.tex} - [$Date: 2017-08-08 11:57:30 +0200 (Tue, 08 Aug 2017) $ + [$Date: 2018-03-27 11:46:14 +0200 (Tue, 27 Mar 2018) $ KOMA-Script guide (package tocbasic)] \chapter{Verzeichnisse verwalten mit Hilfe von \Package{tocbasic}} @@ -71,9 +71,9 @@ vornehmen zu m Als kleiner Nebeneffekt kann das Paket auch verwendet werden, um neue Gleitumgebungen oder den Gleitumgebungen ähnliche nicht gleitende Umgebungen für Konsultationsobjekte zu definieren. Näheres dazu wird nach der Erklärung -der grundlegenden Anweisungen in \autoref{sec:tocbasic.toc} durch ein Beispiel -in \autoref{sec:tocbasic.example} verdeutlicht, das in kompakter Form noch -einmal in \autoref{sec:tocbasic.declarenewtoc} aufgegriffen wird. +der grundlegenden Anweisungen in den folgenden vier Abschnitten durch ein +Beispiel in \autoref{sec:tocbasic.example} verdeutlicht, das in kompakter Form +noch einmal in \autoref{sec:tocbasic.declarenewtoc} aufgegriffen wird. \KOMAScript{} verwendet \Package{tocbasic} sowohl für das Inhaltsverzeichnis als auch für die bereits erwähnten Verzeichnisse für Abbildungen und Tabellen. @@ -87,18 +87,19 @@ bekannten Dateierweiterungen\textnote{Dateierweiterung, Verzeichnis}, die f Verzeichnisse stehen, zu verwalten. Einträge in Dateien mit solchen Dateierweiterungen werden typischerweise mit \Macro{addtocontents}\important{\Macro{addtocontents}, - \DescRef{\LabelBase.cmd.addxcontentsline}} oder \DescRef{\LabelBase.cmd.addxcontentsline} vorgenommen. Darüber -hinaus gibt es Anweisungen, mit denen Aktionen für all diese -Dateierweiterungen durchgeführt werden können. Außerdem gibt es Anweisungen, -um Einstellungen für die Datei vorzunehmen, die zu einer gegebenen -Dateierweiterung gehört. Typischerweise hat so eine Dateierweiterung auch -einen Besitzer\textnote{Dateibesitzer}. Dieser Besitzer kann eine Klasse oder -ein Paket oder ein Bezeichner sein, den der Autor der Klasse oder des Pakets, -das \Package{tocbasic} verwendet, frei gewählt hat. \KOMAScript{} selbst -verwendet beispielsweise den Besitzer \PValue{float} für die -Dateierweiterungen \File{lof} und \File{lot}, die für das Abbildungs- und das -Tabellenverzeichnis stehen. Für das Inhaltsverzeichnis verwendet \KOMAScript{} -als Besitzer den Dateiname der Klasse. + \DescRef{\LabelBase.cmd.addxcontentsline}} oder +\DescRef{\LabelBase.cmd.addxcontentsline} vorgenommen. Darüber hinaus gibt es +Anweisungen, mit denen Aktionen für all diese Dateierweiterungen durchgeführt +werden können. Außerdem gibt es Anweisungen, um Einstellungen für die Datei +vorzunehmen, die zu einer gegebenen Dateierweiterung gehört. Typischerweise +hat so eine Dateierweiterung auch einen +Besitzer\textnote{Dateibesitzer}. Dieser Besitzer kann eine Klasse oder ein +Paket oder ein Bezeichner sein, den der Autor der Klasse oder des Pakets, das +\Package{tocbasic} verwendet, frei gewählt hat. \KOMAScript{} selbst verwendet +beispielsweise den Besitzer \PValue{float} für die Dateierweiterungen +\File{lof} und \File{lot}, die für das Abbildungs- und das Tabellenverzeichnis +stehen. Für das Inhaltsverzeichnis verwendet \KOMAScript{} als Besitzer den +Dateinamen der Klasse. \begin{Declaration} \Macro{ifattoclist}\Parameter{Dateierweiterung} @@ -111,7 +112,7 @@ die \PName{Dateierweiterung} bereits ausgeführt. \begin{Example} Angenommen, Sie wollen wissen, ob die Dateierweiterung »\File{foo}« bereits - verwendet wird, um in diesem Fall einen Fehlermeldung auszugeben, weil diese + verwendet wird, um in diesem Fall eine Fehlermeldung auszugeben, weil diese damit nicht mehr verwendet werden kann: \begin{lstcode} \ifattoclist{foo}{% @@ -151,7 +152,7 @@ aufgrund der Verwendung einer Anweisung durch den Benutzer aufgerufen wird. In diesem Fall wird als \PName{Besitzer} »\PValue{.}« eingetragen. Beachten\textnote{Achtung!} Sie, dass ein leeres Argument \PName{Besitzer} -nicht das gleiche ist, wie das Weglassen des kompletten optionalen Arguments +nicht das Gleiche ist wie das Weglassen des kompletten optionalen Arguments einschließlich der eckigen Klammern. Ein leeres Argument würde auch einen leeren \PName{Besitzer} ergeben. \begin{Example} @@ -172,7 +173,7 @@ leeren \PName{Besitzer} ergeben. See the tocbasic package documentation for explanation. Type H for immediate help. \end{lstoutput} - Wenn Sie dann tatsächlich die Taste »\texttt{H}« gefolgt von der + Wenn Sie dann tatsächlich die Taste »\texttt{H}«, gefolgt von der Return-Taste drücken, erhalten Sie als Hilfe: \begin{lstoutput} File extension `foo' is already used by a toc-file, while bar.sty @@ -201,33 +202,45 @@ leeren \PName{Besitzer} ergeben. oder aber ein Fehler gemeldet, wenn diese Dateierweiterung bereits verwendet wird. \end{Example} + Sie können als \PName{Besitzer} angeben, was immer Sie wollen, aber es sollte eindeutig sein! Wenn Sie beispielsweise der Autor des Pakets \Package{float} -wären, könnten Sie als \PName{Besitzer} auch »\PValue{float}« an Stelle von -»\PValue{float.sty}« angeben. In diesem Fall würden die \KOMAScript-Optionen -für das Verzeichnis der Abbildungen und das Verzeichnis der Tabellen auch Ihre -Verzeichnisse betreffen, die zum Zeitpunkt der Verwendung der jeweiligen -Option bereits zur Liste der bekannten Dateierweiterungen hinzugefügt -sind. Das liegt daran, dass \KOMAScript{} die Dateierweiterungen -»\PValue{lof}« für das Abbildungsverzeichnis und »\PValue{lot}« für das -Tabellenverzeichnis mit dem Besitzer »\PName{float}« anmeldet und die Optionen -für diese Besitzer setzt.% -% +wären, könnten Sie als \PName{Besitzer} auch »\PValue{float}« anstelle von +»\PValue{float.sty}« angeben. In diesem Fall würden die +\KOMAScript-Optionen\important{\DescRef{maincls.option.listof}}% +\IndexOption{listof~=\PName{Einstellung}} für das Verzeichnis der Abbildungen +und das Verzeichnis der Tabellen auch Ihre Verzeichnisse betreffen, die zum +Zeitpunkt der Verwendung der jeweiligen Option bereits zur Liste der bekannten +Dateierweiterungen hinzugefügt sind. Das liegt daran, dass \KOMAScript{} die +Dateierweiterungen »\PValue{lof}« für das Abbildungsverzeichnis und +»\PValue{lot}« für das Tabellenverzeichnis mit dem Besitzer »\PValue{float}« +anmeldet und die Optionen für diese Besitzer setzt. + +Das Paket \hyperref[cha:scrhack]{\Package{scrhack}}\IndexPackage{scrhack}% +\important{ \hyperref[cha:scrhack]{\Package{scrhack}}} enthält übrigens +Patches für mehrere Pakete wie \Package{float} oder \Package{listings}, die +eigene Verzeichnisse bereitstellen. Bei Verwendung von +\hyperref[cha:scrhack]{\Package{scrhack}} wird dann unter anderem die +jeweilige Dateierweiterung der Liste der bekannten Dateierweiterungen +hinzugefügt. Dabei wird als \PName{Besitzer} ebenfalls »\PValue{float}« +verwendet. Dies ist sozusagen der grundlegende Baustein, um die Möglichkeiten +von \Package{tocbasic} und der \KOMAScript-Klassen auch für diese +Verzeichnisse nutzen zu können.% \EndIndexGroup \begin{Declaration} \Macro{AtAddToTocList}\OParameter{Besitzer}\Parameter{Anweisungen} \end{Declaration} -Auf diese Weise können die \Parameter{Anweisungen} zu einer internen Liste von +Auf diese Weise können die \PName{Anweisungen} zu einer internen Liste von Anweisungen hinzugefügt werden, die immer dann auszuführen sind, wenn eine Dateierweiterung mit dem angegebenen \PName{Besitzer} zur Liste der bekannten Dateierweiterungen hinzugefügt wird. Bezüglich des optionalen Arguments wird -wie in der Erklärung von \DescRef{\LabelBase.cmd.addtotoclist} beschrieben verfahren. Wird das -optionale Argument leer gelassen, werden in diesem Fall die Aktionen -unabhängig vom Besitzer immer ausgeführt, wenn die Dateierweiterung zu der -Liste der bekannten Dateierweiterungen hinzugefügt wird. Während der -Ausführung der \PName{Anweisungen} ist außerdem +wie in der Erklärung von \DescRef{\LabelBase.cmd.addtotoclist} beschrieben +verfahren. Wird das optionale Argument leer gelassen, werden in diesem Fall +die Aktionen unabhängig vom Besitzer immer ausgeführt, wenn die +Dateierweiterung zu der Liste der bekannten Dateierweiterungen hinzugefügt +wird. Während der Ausführung der \PName{Anweisungen} ist außerdem \Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} die Dateierweiterung, die gerade hinzugefügt wird. \begin{Example} @@ -243,9 +256,11 @@ Dateierweiterung, die gerade hinzugef \end{Example} Die\textnote{Achtung!} zweimalige Verwendung von \Macro{expandafter} ist im -Beispiel erforderlich, weil das Argument von \DescRef{\LabelBase.cmd.tocbasic@extend@babel} -zwingend bereits expandiert sein muss. Siehe dazu auch die Erklärung zu -\DescRef{\LabelBase.cmd.tocbasic@extend@babel} in \autoref{sec:tocbasic.internals}, +Beispiel erforderlich, weil das Argument von +\DescRef{\LabelBase.cmd.tocbasic@extend@babel} zwingend bereits expandiert +sein muss. Siehe dazu auch die Erklärung zu +\DescRef{\LabelBase.cmd.tocbasic@extend@babel} in +\autoref{sec:tocbasic.internals}, \DescPageRef{\LabelBase.cmd.tocbasic@extend@babel}. % \EndIndexGroup @@ -259,23 +274,24 @@ Dateierweiterungen entfernen. Ist das optionale Argument \OParameter{Besitzer} angegeben, so wird die Dateierweiterung nur entfernt, wenn sie für den angegebenen \PName{Besitzer} angemeldet wurde. Wie der Besitzer beim Weglassen des optionalen Argument bestimmt wird, ist der Erklärung zu -\DescRef{\LabelBase.cmd.addtotoclist} zu entnehmen. Wird ein leerer \PName{Besitzer} angegeben, -findet kein Besitzertest statt, sondern die \PName{Dateierweiterung} wird -unabhängig vom Besitzer entfernt.% +\DescRef{\LabelBase.cmd.addtotoclist} zu entnehmen. Wird ein leerer +\PName{Besitzer} angegeben, findet kein Besitzertest statt, sondern die +\PName{Dateierweiterung} wird unabhängig vom Besitzer entfernt.% \EndIndexGroup \begin{Declaration} \Macro{doforeachtocfile}\OParameter{Besitzer}\Parameter{Anweisungen} \end{Declaration} -Bisher haben Sie nur Anweisungen kennen gelernt, die für Klassen- und +Bisher haben Sie nur Anweisungen kennengelernt, die für Klassen- und Paketautoren zwar zusätzliche Sicherheit, aber auch eher zusätzlichen Aufwand bedeuten. Mit \Macro{doforeachtocfile} kann man die erste Ernte dafür einfahren. Diese Anweisung erlaubt es die angegebenen \PName{Anweisungen} für jede von dem \PName{Besitzer} angemeldete Dateierweiterung auszuführen. Während der Ausführung der \PName{Anweisungen} ist -\Macro{@currext} die aktuell verarbeitete Dateierweiterung. Wird das optionale -Argument \OParameter{Besitzer} weggelassen, so werden alle Dateierweiterungen +\Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} die aktuell +verarbeitete Dateierweiterung. Wird das optionale Argument +\OParameter{Besitzer} weggelassen, so werden alle Dateierweiterungen unabhängig vom Besitzer abgearbeitet. Ein leeres optionales Argument würde hingegen nur die Dateierweiterungen mit leerem Besitzer verarbeiten. \begin{Example} @@ -284,42 +300,44 @@ hingegen nur die Dateierweiterungen mit leerem Besitzer verarbeiten. \begin{lstcode} \doforeachtocfile{\typeout{\@currext}} \end{lstcode} - möglich. Wollen Sie hingegen nur die Dateierweiterungen des Besitzer - »\PValue{foo}«, dann geht das einfach mit: + möglich. Sollen hingegen nur die Dateierweiterungen des Besitzer + »\PValue{foo}« ausgegeben werden, geht das einfach mit: \begin{lstcode} \doforeachtocfile[foo]{\typeout{\@currext}} \end{lstcode} \end{Example} -Die \KOMAScript-Klassen \Class{scrbook} und \Class{scrreprt} verwenden diese -Anweisung übrigens, um für jedes Verzeichnis, für das die Eigenschaft -\PValue{chapteratlist} gesetzt ist, optional einen vertikalen Abstand oder die -Kapitelüberschrift in dieses Verzeichnis einzutragen. Wie Sie diese -Eigenschaft setzen können, ist in \autoref{sec:tocbasic.toc}, -\DescPageRef{\LabelBase.cmd.setuptoc} zu finden.% +Die \KOMAScript-Klassen \Class{scrbook} und \Class{scrreprt} verwenden die +Anweisung, um für Verzeichnisse, für die Eigenschaft \PValue{chapteratlist} +gesetzt ist, optional einen vertikalen Abstand oder die Kapitelüberschrift in +das Verzeichnis einzutragen. Wie Sie diese Eigenschaft setzen können, ist +in \autoref{sec:tocbasic.toc} ab \DescPageRef{\LabelBase.cmd.setuptoc} zu +finden.% \EndIndexGroup \begin{Declaration} \Macro{tocbasicautomode} \end{Declaration} -Diese Anweisung definiert die Anweisung \Macro{@starttoc}, die der \LaTeX-Kern -bereit stellt, so um, dass bei jedem Aufruf von \Macro{@starttoc} die dabei -angegebene Dateierweiterung in die Liste der bekannten Dateierweiterungen -eingefügt wird, soweit sie dort noch nicht vorhanden ist. Außerdem wird dann -\DescRef{\LabelBase.cmd.tocbasic@starttoc} an Stelle von \Macro{@starttoc} verwendet. Näheres -zu \DescRef{\LabelBase.cmd.tocbasic@starttoc} und \Macro{@starttoc} ist -\autoref{sec:tocbasic.internals}, +Diese Anweisung definiert das vom \LaTeX-Kern für Klassen- und Paketautoren +bereitgestellte +\Macro{@starttoc}\IndexCmd{@starttoc}\important{\Macro{\@starttoc}} so um, +dass bei jedem Aufruf von \Macro{@starttoc} die dabei angegebene +Dateierweiterung in die Liste der bekannten Dateierweiterungen eingefügt wird, +soweit sie dort noch nicht vorhanden ist. Außerdem wird dann +\DescRef{\LabelBase.cmd.tocbasic@starttoc} anstelle von \Macro{@starttoc} +verwendet. Näheres zu \DescRef{\LabelBase.cmd.tocbasic@starttoc} und +\Macro{@starttoc} ist \autoref{sec:tocbasic.internals}, \DescPageRef{\LabelBase.cmd.tocbasic@starttoc} zu entnehmen. -Mit Hilfe von \Macro{tocbasicautomode} wird also sozusagen jedes Verzeichnis, -das mit Hilfe von \Macro{@starttoc} erstellt wird, automatisch zumindest -teilweise unter die Kontrolle von \Package{tocbasic} gestellt. Ob das zum -gewünschten Ergebnis führt, hängt jedoch sehr von den jeweiligen -Verzeichnissen ab. Immerhin funktioniert damit schon einmal die Erweiterung -für das \Package{babel}-Paket für alle Verzeichnisse. Es ist jedoch -vorzuziehen, wenn der Paketautor selbst \Package{tocbasic} explizit -verwendet. Er kann dann auch die weiteren Vorteile nutzen, die ihm das Paket -bietet und die in den nachfolgenden Abschnitten beschrieben werden.% +Mit Hilfe von \Macro{tocbasicautomode} wird also jedes Verzeichnis, das mit +Hilfe von \Macro{@starttoc} erstellt wird, automatisch unter die Kontrolle von +\Package{tocbasic} gestellt. Ob das zum gewünschten Ergebnis führt, hängt +jedoch sehr von den jeweiligen Verzeichnissen ab. Immerhin funktioniert damit +schon einmal die Erweiterung für das \Package{babel}-Paket für alle +Verzeichnisse. Es ist jedoch vorzuziehen, wenn der Paketautor selbst +\Package{tocbasic} explizit verwendet. Er kann dann auch die weiteren Vorteile +nutzen, die ihm das Paket bietet und die in den nachfolgenden Abschnitten +beschrieben werden.% \EndIndexGroup @@ -327,12 +345,12 @@ bietet und die in den nachfolgenden Abschnitten beschrieben werden.% \seclabel{toc} Im vorherigen Abschnitt haben Sie erfahren, wie eine Liste bekannter -Dateierweiterungen geführt werden kann und wie automatisch Anweisungen beim -Hinzufügen von Dateierweiterungen zu dieser Liste ausgeführt werden -können. Des Weiteren haben Sie eine Anweisung kennen gelernt, mit der man für -jede einzelne bekannte Dateierweiterung oder einen spezifischen Teil davon -Anweisungen ausführen kann. In diesem Abschnitt werden Sie Anweisungen kennen -lernen, die sich auf die Datei beziehen, die mit dieser Dateierweiterung +Dateierweiterungen verwaltet werden kann\iffree{ und wie automatisch Anweisungen + beim Hinzufügen von Dateierweiterungen zu dieser Liste ausgeführt werden + können}{}. Des Weiteren haben Sie eine Anweisung kennengelernt, mit der man +für jede einzelne bekannte Dateierweiterung oder einen spezifischen Teil davon +Anweisungen ausführen kann. In diesem Abschnitt werden Sie Anweisungen +kennenlernen, die sich auf die Datei beziehen, die mit dieser Dateierweiterung verbunden ist. @@ -340,12 +358,13 @@ verbunden ist. \Macro{addtoeachtocfile}\OParameter{Besitzer}\Parameter{Inhalt} \end{Declaration} Die Anweisung \Macro{addtoeachtocfile} schreibt \PName{Inhalt} mit Hilfe von -\Macro{addtocontents} aus dem \LaTeX-Kern in jede Datei, die für den -angegebenen \PName{Besitzer} in der Liste der bekannten Dateierweiterungen zu -finden ist. Wird das optionale Argument weggelassen, wird in jede Datei aus -der Liste der bekannten Dateierweiterungen geschrieben. Der konkrete Dateiname -setzt sich dabei übrigens aus \Macro{jobname} und der Dateierweiterung -zusammen. Während des Schreibens von \PName{Inhalt} ist +\Macro{addtocontents}\IndexCmd{addtocontents}\important{\Macro{addtocontents}}% +\iffree{ aus dem \LaTeX-Kern}{} in jede Datei, die mit dem angegebenen +\PName{Besitzer} in der Liste der bekannten Dateierweiterungen \iffree{zu + finden ist}{steht}. Wird das optionale Argument weggelassen, wird in jede +Datei aus der Liste der bekannten Dateierweiterungen geschrieben.\iffree{ Der + konkrete Dateiname setzt sich dabei übrigens aus \Macro{jobname} und der + Dateierweiterung zusammen.}{} Während des Schreibens von \PName{Inhalt} ist \Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} die Dateierweiterung der Datei, in die aktuell geschrieben wird. \begin{Example} @@ -362,10 +381,11 @@ Dateierweiterung der Datei, in die aktuell geschrieben wird. \addtoeachtocfile[foo]{% \protect\addvspace{\protect\baselineskip}% } -\end{lstcode} -\end{Example} -Anweisungen, die nicht bereits beim Schreiben expandiert werden sollen, sind -wie bei \Macro{addtocontents} mit \Macro{protect} zu schützen. +\end{lstcode}% +\end{Example}% +\iffree{Anweisungen, die nicht bereits beim Schreiben expandiert werden + sollen, sind wie bei \Macro{addtocontents} mit \Macro{protect} zu + schützen.}{}% \EndIndexGroup @@ -373,18 +393,15 @@ wie bei \Macro{addtocontents} mit \Macro{protect} zu sch \Macro{addxcontentsline}\Parameter{Dateierweiterung}\Parameter{Ebene} \OParameter{Gliederungsnummer}\Parameter{Inhalt} \end{Declaration} -Diese\ChangedAt{v3.12}{\Package{tocbasic}} -Anweisung ähnelt sehr der Anweisung +Diese\ChangedAt{v3.12}{\Package{tocbasic}} Anweisung ähnelt sehr der Anweisung \Macro{addcontentsline}\IndexCmd{addcontentsline} aus dem \LaTeX-Kern. Allerdings besitzt sie ein zusätzliches optionales Argument für die \PName{Gliederungsnummer} des Eintrags, während diese bei -\Macro{addcontentsline} im Argument \PName{Inhalt} mit angegeben wird. - -Die Anweisung wird verwendet, um nummerierte oder nicht nummerierte Einträge -in das über die \PName{Dateierweiterung} spezifierte Verzeichnis -aufzunehmen. Dabei ist \PName{Ebene} der symbolische Name der Gliederungsebene -und \PName{Inhalt} der entsprechende Eintrag. Die Seitenzahl wird automatisch -bestimmt. +\Macro{addcontentsline} im Argument \PName{Inhalt} mit angegeben wird. Sie +wird verwendet, um nummerierte oder nicht nummerierte Einträge in das über die +\PName{Dateierweiterung} spezifizierte Verzeichnis aufzunehmen. Dabei ist +\PName{Ebene} der symbolische Name der Gliederungsebene und \PName{Inhalt} der +entsprechende Eintrag. Die Seitenzahl wird automatisch bestimmt. Im Unterschied zu \Macro{addcontentsline} testet \Macro{addxcontentsline} zunächst, ob Anweisung \Macro{add\PName{Ebene}\PName{Dateierweiterung}entry} @@ -394,7 +411,7 @@ obligatorisches Argument Anweisung, die von den \KOMAScript-Klassen bereitgestellt wird, wäre \DescRef{maincls-experts.cmd.addparttocentry} (siehe \autoref{sec:maincls-experts.experts}, -\DescPageRef{maincls-experts.cmd.addparttocentry}). Ist die entsprechend +\DescPageRef{maincls-experts.cmd.addparttocentry}). Ist die entsprechende Anweisung nicht definiert, wird stattdessen die interne Anweisung \DescRef{\LabelBase.cmd.tocbasic@addxcontentsline} verwendet. Diese erhält alle vier Argumente als obligatorische Argumente und verwendet dann @@ -431,7 +448,7 @@ Dateien aus der Liste der bekannten Dateierweiterungen schreibt. \begin{Example} Angenommen, Sie sind Klassen-Autor und wollen den Kapiteleintrag nicht nur in das Inhaltsverzeichnis, sondern in alle Verzeichnisdateien schreiben. Nehmen - wir weiter an, dass aktuell \PName{\#1} den Titel enthält, der geschrieben + wir weiter an, dass aktuell \PValue{\#1} den Titel enthält, der geschrieben werden soll. \begin{lstcode} \addxcontentslinetoeachtocfile{chapter}% @@ -449,8 +466,8 @@ Dateierweiterung der Datei, in die aktuell geschrieben wird.% Die Anweisung\ChangedAt{v3.12}{\Package{tocbasic}} \Macro{addxcontentslinetoeachtocfile} ist wann immer möglich gegenüber \Macro{addcontentslinetoeachtocfile} vorzuziehen, da die Erweiterungen von -\DescRef{\LabelBase.cmd.addxcontentsline} nur damit Anwendung finden. Näheres zu diesen -Erweiterungen und Vorteilen ist in der vorausgehenden Erklärung von +\DescRef{\LabelBase.cmd.addxcontentsline} nur damit Anwendung finden. Näheres +zu diesen Erweiterungen und Vorteilen ist in der vorausgehenden Erklärung von \DescRef{\LabelBase.cmd.addxcontentsline} zu finden.% % \EndIndexGroup @@ -509,8 +526,9 @@ passend zu definieren. \end{lstcode} Im zweiten Fall würde natürlich auch ein optional aktivierter Eintrag in das Inhaltsverzeichnis nicht gesetzt. Näheres zur Eigenschaft des Eintrags in - das Inhaltsverzeichnis ist bei der Anweisung \DescRef{\LabelBase.cmd.setuptoc}, - \DescPageRef{\LabelBase.cmd.setuptoc} zu finden. + das Inhaltsverzeichnis ist bei der Anweisung + \DescRef{\LabelBase.cmd.setuptoc}, \DescPageRef{\LabelBase.cmd.setuptoc} zu + finden. Wenn Sie zuvor \begin{lstcode} @@ -540,8 +558,15 @@ dieser Anweisungen zu einer Fehlermeldung der Art \end{lstoutput} führen, wenn keine Schreibdateien mehr zur Verfügung stehen. Abhilfe kann in diesem Fall das Laden des in \autoref{cha:scrwfile} beschriebenen Pakets -\Package{scrwfile}\important{\Package{scrwfile}}\IndexPackage{scrwfile} bieten. -% +\Package{scrwfile}\important{\Package{scrwfile}}\IndexPackage{scrwfile} +bieten. + +Das Paket \hyperref[cha:scrhack]{\Package{scrhack}}\IndexPackage{scrhack}% +\important{ \hyperref[cha:scrhack]{\Package{scrhack}}} enthält übrigens +Patches für mehrere Pakete wie \Package{float} oder \Package{listings}, damit +deren Verzeichnisbefehle \Macro{listoftoc} verwenden. Dadurch stehen viele +Möglichkeiten von \Package{tocbasic} und den \KOMAScript-Klassen auch für +deren Verzeichnisse zur Verfügung.% \EndIndexGroup @@ -552,15 +577,15 @@ diesem Fall das Laden des in \autoref{cha:scrwfile} beschriebenen Pakets \end{Declaration} Manchmal ist es nützlich, wenn unmittelbar vor dem Einlesen der Datei mit den Verzeichnisdaten \PName{Anweisungen} ausgeführt werden können. Mit Hilfe von -\Macro{BeforeStartingTOC} können Sie genau solche \PName{Anweisungen} +\Macro{BeforeStartingTOC} können Sie eine solche Ausführung wahlweise für eine einzelne \PName{Dateierweiterung} oder alle Dateien, die -mit Hilfe von \DescRef{\LabelBase.cmd.listoftoc*}, \DescRef{\LabelBase.cmd.listoftoc} oder \DescRef{\LabelBase.cmd.listofeachtoc} +mit Hilfe von \DescRef{\LabelBase.cmd.listoftoc*}, +\DescRef{\LabelBase.cmd.listoftoc} oder \DescRef{\LabelBase.cmd.listofeachtoc} eingelesen werden, erreichen. Ebenso können Sie \PName{Anweisungen} nach dem Einlesen der Datei ausführen, wenn Sie diese mit \Macro{AfterStartingTOC} definieren. Während der Ausführung der \PName{Anweisungen} ist \Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} die -Dateierweiterung der Datei, die eingelesen wird bzw. gerade eingelesen -wurde. +Dateierweiterung der Datei, die eingelesen wird bzw. gerade eingelesen wurde. Ein Beispiel\textnote{Beispiel} zur Verwendung von \Macro{BeforeStartingTOC} ist in \autoref{sec:scrwfile.clonefilefeature} auf @@ -611,7 +636,7 @@ sondern verwendet wie vorgefunden. Erlauben\textnote{Tipp!} Sie mir einen Hinweis zu \Macro{MakeUppercase}. Diese Anweisung ist zum einen nicht voll expandierbar. Das bedeutet, dass sie im -Zusammenspiel mit anderen Anweisungen zu Problemen führen kann. Darüber hinaus +Zusammenspiel mit anderen Anweisungen zu Problemen führen kann. Zum anderen sind sich alle Typografen einig, dass beim Versalsatz, also beim Satz kompletter Wörter oder Passagen in Großbuchstaben, Sperrung unbedingt notwendig ist. Dabei darf jedoch kein fester Abstand zwischen den Buchstaben @@ -624,11 +649,10 @@ ebenso wenig leisten wie der Befehl \Macro{MakeUppercase} selbst. Auch die automatische Sperrung mit Hilfe des \Package{microtype}-Pakets ist diesbezüglich nur eine näherungsweise Notlösung, da die von der konkreten Schrift abhängige Form der Buchstaben auch hier nicht näher betrachtet -wird. Da\textnote{Empfehlung} Versalsatz also eher etwas für die absoluten +wird. Da\textnote{Empfehlung} Versalsatz also eher etwas für absolute Experten ist und fast immer Handarbeit bedeutet, wird Laien empfohlen, darauf -eher zu verzichten oder ihn nur vorsichtig und nicht an so exponierter Stelle -wie im Kolumnentitel zu verwenden. -% +zu verzichten oder ihn nur vorsichtig und nicht an so exponierter Stelle +wie dem Kolumnentitel zu verwenden.% \EndIndexGroup @@ -637,15 +661,15 @@ wie im Kolumnentitel zu verwenden. \end{Declaration} Das Paket \Package{tocbasic} enthält eine Standarddefinition für das Setzen von Überschriften von Verzeichnissen. Diese Standarddefinition ist durch -verschiedene Eigenschaften, die bei der Anweisung \DescRef{\LabelBase.cmd.setuptoc} erläutert -werden, konfigurierbar. Sollte diese Möglichkeit einmal nicht ausreichen, so -besteht die Möglichkeit, mit \Macro{deftocheading} eine alternative -Überschriftenanweisung für ein Verzeichnis mit einer bestimmten -\PName{Dateierweiterung} zu definieren. Die Definition kann als einzigen -Parameter \PName{\#1} enthalten. Beim Aufruf der Anweisung innerhalb von -\DescRef{\LabelBase.cmd.listoftoc} oder \DescRef{\LabelBase.cmd.listofeachtoc} wird als dieses Argument dann der -Titel für das Verzeichnis übergeben. -% +verschiedene Eigenschaften, die bei der Anweisung +\DescRef{\LabelBase.cmd.setuptoc} erläutert werden, konfigurierbar. Sollte +diese Möglichkeit einmal nicht ausreichen, so besteht die Möglichkeit, mit +\Macro{deftocheading} eine alternative Überschriftenanweisung für ein +Verzeichnis mit einer bestimmten \PName{Dateierweiterung} zu definieren. Die +Definition kann als einzigen Parameter \PValue{\#1} enthalten. Beim Aufruf der +Anweisung innerhalb von \DescRef{\LabelBase.cmd.listoftoc} oder +\DescRef{\LabelBase.cmd.listofeachtoc} wird für dieses Argument dann der Titel +für das Verzeichnis übergeben.% \EndIndexGroup @@ -656,23 +680,25 @@ Titel f \Parameter{Liste von Eigenschaften} \end{Declaration} Mit diesen beiden Anweisungen können \PName{Eigenschaften} für eine -\PName{Dateierweiterung} bzw. das Verzeichnis, das dazu gehört, gesetzt -werden. Die \PName{Liste von Eigenschaften} ist dabei eine durch Komma -getrennte Aneinanderreihung von \PName{Eigenschaften}. Das Paket +\PName{Dateierweiterung} bzw. das Verzeichnis, das dazu gehört, gesetzt und +gelöscht werden. Die \PName{Liste von Eigenschaften} ist dabei eine durch +Komma getrennte Folge von \PName{Eigenschaften}. Das Paket \Package{tocbasic} wertet folgende Eigenschaften aus: -\begin{description} +\begin{description}\setkomafont{descriptionlabel}{}% \item[\PValue{leveldown}] bedeutet, dass das Verzeichnis nicht mit der - obersten Gliederungsebene unterhalb von \DescRef{maincls.cmd.part} -- wenn vorhanden - \DescRef{maincls.cmd.chapter}, sonst \DescRef{maincls.cmd.section} -- erstellt wird, sondern mit einer - Überschrift der nächst tieferen Gliederungsebene. Diese Eigenschaft wird von - der internen Überschriftenanweisung ausgewertet. Wird\textnote{Achtung!} - hingegen eine eigene Überschriftenanweisung mit \DescRef{\LabelBase.cmd.deftocheading} + obersten Gliederungsebene unterhalb von \DescRef{maincls.cmd.part} -- wenn + vorhanden \DescRef{maincls.cmd.chapter}, sonst \DescRef{maincls.cmd.section} + -- erstellt wird, sondern mit einer Überschrift der nächst tieferen + Gliederungsebene. Diese Eigenschaft wird von der internen + Überschriftenanweisung ausgewertet. Wird\textnote{Achtung!} hingegen eine + eigene Überschriftenanweisung mit \DescRef{\LabelBase.cmd.deftocheading} definiert, liegt die Auswertung der Eigenschaft in der Verantwortung dessen, der die Definition vornimmt. Die \KOMAScript-Klassen setzen diese Eigenschaft bei Verwendung der Option - \OptionValueRef{maincls}{listof}{leveldown}\important{\OptionValueRef{maincls}{listof}{leveldown}}% - \IndexOption{listof~=\PValue{leveldown}} - für alle Dateierweiterungen des Besitzers \PValue{float}. + \OptionValueRef{maincls}{listof}{leveldown}% + \important{\OptionValueRef{maincls}{listof}{leveldown}}% + \IndexOption{listof~=\textKValue{leveldown}} für alle Dateierweiterungen des + Besitzers \PValue{float}. \item[\PValue{nobabel}] bedeutet, dass die normalerweise automatisch verwendete Erweiterung für die Sprachumschaltung mit \Package{babel}\IndexPackage{babel} für diese Dateierweiterung nicht @@ -698,7 +724,7 @@ getrennte Aneinanderreihung von \PName{Eigenschaften}. Das Paket das Abschalten des optischen Randausgleichs in den Verzeichnissen. Optischer Randausgleich wird standardmäßig abgeschaltet, wenn das Paket \Package{microtype}\IndexPackage{microtype} oder ein anderes Paket, das die - Anweisung \Macro{microtypesetup}\IndexCmd{microtypesetup} bereit stellt, + Anweisung \Macro{microtypesetup}\IndexCmd{microtypesetup} bereitstellt, geladen ist. Wenn also optischer Randausgleich in den Verzeichnissen gewünscht wird, dann muss diese Eigenschaft aktiviert werden. Es\textnote{Achtung!} ist jedoch zu beachten, dass der optische @@ -713,14 +739,13 @@ getrennte Aneinanderreihung von \PName{Eigenschaften}. Das Paket \KOMAScript-Klassen setzen diese Eigenschaft bei Verwendung der Option \OptionValueRef{maincls}{listof}{numbered}% \important{\OptionValueRef{maincls}{listof}{numbered}}% - \IndexOption{listof~=\PValue{numbered}} für alle Dateierweiterungen des + \IndexOption{listof~=\textKValue{numbered}} für alle Dateierweiterungen des Besitzers \Package{float}. \item[\PValue{numberline}] \ChangedAt{v3.12}{\Package{tocbasic}}% - bedeutet, dass auch all diejenigen Einträge, die mit Hilfe der Anweisung + bedeutet, dass all diejenigen Einträge, die mit Hilfe der Anweisung \DescRef{\LabelBase.cmd.addxcontentsline} oder der Anweisung - \DescRef{\LabelBase.cmd.addxcontentslinetoeachtocfile} in das Verzeichnis - geschrieben werden und bei denen das optionale Argument für die Nummer fehlt - oder leer ist, mit einer (leeren) + \DescRef{\LabelBase.cmd.addxcontentslinetoeachtocfile} vorgenommen werden, wobei das optionale Argument für die Nummer fehlt + oder leer ist, mit einer leeren \DescRef{\LabelBase.cmd.numberline}-Anweisung versehen werden. Das führt in der Regel dazu, dass diese Einträge nicht linksbündig mit der Nummer, sondern mit dem Text der nummerierten Einträge gleicher Ebene gesetzt @@ -734,18 +759,18 @@ getrennte Aneinanderreihung von \PName{Eigenschaften}. Das Paket Die \KOMAScript-Klassen setzen diese Eigenschaft bei Verwendung der Option \OptionValueRef{maincls}{listof}{numberline}% \important{\OptionValueRef{maincls}{listof}{numberline}}% - \IndexOption{listof~=\PValue{numberline}} für die Dateierweiterungen des + \IndexOption{listof~=\textKValue{numberline}} für die Dateierweiterungen des Besitzers \PValue{float} und bei Verwendung der Option \OptionValueRef{maincls}{toc}{numberline}% \important{\OptionValueRef{maincls}{toc}{numberline}}% - \IndexOption{toc~=\PValue{numberline}} für die Dateierweiterung + \IndexOption{toc~=\textKValue{numberline}} für die Dateierweiterung \PValue{toc}. Entsprechend wird die Eigenschaft bei Verwendung von Option \OptionValueRef{maincls}{listof}{nonumberline}% \important{\OptionValueRef{maincls}{listof}{nonumberline}}% - \IndexOption{listof~=\PValue{nonumberline}} oder + \IndexOption{listof~=\textKValue{nonumberline}} oder \OptionValueRef{maincls}{toc}{nonumberline}% \important{\OptionValueRef{maincls}{toc}{nonumberline}}% - \IndexOption{toc~=\PValue{nonumberline}} wieder zurückgesetzt. + \IndexOption{toc~=\textKValue{nonumberline}} wieder zurückgesetzt. \item[\PValue{onecolumn}] \leavevmode\ChangedAt{v3.01}{\Package{tocbasic}}% bedeutet, dass für dieses Verzeichnis automatisch der \LaTeX-interne Einspaltenmodus mit \Macro{onecolumn}\IndexCmd{onecolumn} verwendet @@ -772,17 +797,18 @@ getrennte Aneinanderreihung von \PName{Eigenschaften}. Das Paket Eigenschaft bei Verwendung der Option \OptionValueRef{maincls}{listof}{totoc}% \important{\OptionValueRef{maincls}{listof}{totoc}}% - \IndexOption{listof~=\PValue{totoc}} für alle Dateierweiterungen des + \IndexOption{listof~=\textKValue{totoc}} für alle Dateierweiterungen des Besitzers \Package{float}. \end{description} Die \KOMAScript-Klassen kennen eine weitere Eigenschaft: -\begin{description} +\begin{description}\setkomafont{descriptionlabel}{} \item[\PValue{chapteratlist}] sorgt dafür, dass in dieses Verzeichnis bei jedem neuen Kapitel eine optionale Gliederung eingefügt wird. In der Voreinstellung ist diese Untergliederung dann ein vertikaler Abstand. Näheres zu den Möglichkeiten ist Option \DescRef{maincls.option.listof}% - \IndexOption{listof}\important{\DescRef{maincls.option.listof}} in + \IndexOption{listof~=\PName{Einstellung}}% + \important{\DescRef{maincls.option.listof}} in \autoref{sec:maincls.floats}, \DescPageRef{maincls.option.listof} zu entnehmen. \end{description} @@ -801,9 +827,9 @@ Die \KOMAScript-Klassen kennen eine weitere Eigenschaft: \begin{lstcode} \setuptoc{loa}{chapteratlist} \end{lstcode} - Wollen Sie außerdem, dass bei Klassen, die \DescRef{maincls.cmd.chapter} als oberste - Gliederungsebene verwenden, das Verzeichnis automatisch einspaltig gesetzt - wird, so verwenden Sie zusätzlich +Wollen Sie außerdem, dass bei Klassen, die \DescRef{maincls.cmd.chapter} als +oberste Gliederungsebene verwenden, das Verzeichnis automatisch einspaltig +gesetzt wird, so verwenden Sie zusätzlich \begin{lstcode} \ifundefinedorrelax{chapter}{}{% \setuptoc{loa}{onecolumn}% @@ -822,7 +848,7 @@ Die \KOMAScript-Klassen kennen eine weitere Eigenschaft: Wie Sie hier sehen, unterstützt ein Paket, das \Package{tocbasic} verwendet, bereits ohne nennenswerten Aufwand diverse Möglichkeiten für die dadurch realisierten Verzeichnisse, die sonst einigen Implementierungsaufwand -bedeuteten und deshalb in vielen Paketen leider fehlen.% +bedeuten würden und deshalb in vielen Paketen leider fehlen.% \EndIndexGroup @@ -847,7 +873,7 @@ unterst \BeginIndex{}{Verzeichnis>Eintrag} Neben\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} den eigentlichen -Verzeichnissen und den zugehörigen Hilfsdateien kann man mit Paket +Verzeichnissen und den zugehörigen Hilfsdateien kann man mit dem Paket \Package{tocbasic} ab Version~3.20 auch Einfluss auf die Verzeichniseinträge nehmen. Dazu können neue Stile definiert werden. Es stehen aber auch mehrere vordefinierte Stile zur Verfügung. Mittelfristig wird \Package{tocbasic} das @@ -868,15 +894,14 @@ Ebene Eintr Bei \Class{book} ist \Counter{tocdepth} beispielsweise mit 2 voreingestellt, es werden also die Einträge der Ebenen \PValue{part}, \PValue{chapter}, \PValue{section} und \PValue{subsection} ausgeben. Tiefere Ebenen wie -\PValue{subsubsection}, deren numerischer Wert 3 ist, werden nicht +\PValue{subsubsection}, deren nummerischer Wert 3 ist, werden nicht ausgegeben. Trotzdem sind die Einträge in der Hilfsdatei für das Inhaltsverzeichnis vorhanden. -Die von \Package{tocbasic} definierten Eintragsstile beachten abgesehen von +Die von \Package{tocbasic} definierten Eintragsstile beachten, abgesehen von \PValue{gobble} (siehe \DescRef{\LabelBase.cmd.DeclareTOCStyleEntry}\iffree{}{, weiter unten in - diesem Abschnitt}) ebenfalls \Counter{tocdepth}. -% + diesem Abschnitt}), ebenfalls \Counter{tocdepth}.% \EndIndexGroup @@ -886,25 +911,25 @@ Die von \Package{tocbasic} definierten Eintragsstile beachten abgesehen von \end{Declaration} Zwar\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} definiert bereits der \LaTeX-Kern eine Anweisung \Macro{numberline}, diese ist allerdings für die -Anforderungen von \Package{tocbasic} nicht ausreichend. Deshalb definiert es -eigene Anweisungen und setzt \Macro{numberline} bei Bedarf mit Hilfe von -\Macro{usetocbasicnumberline} für die einzelnen Verzeichniseinträge -entsprechend. Eine Umdefinierung von \Macro{numberline} ist daher bei -Verwendung von \Package{tocbasic} oftmals wirkungslos und führt teilweise auch -zu Warnungen. +Anforderungen von \Package{tocbasic} nicht ausreichend. Deshalb definiert +\Package{tocbasic} eigene Anweisungen und setzt \Macro{numberline} bei Bedarf +mit Hilfe von \Macro{usetocbasicnumberline} für die einzelnen +Verzeichniseinträge entsprechend. Eine Umdefinierung von \Macro{numberline} +ist daher bei Verwendung von \Package{tocbasic} oftmals wirkungslos und führt +teilweise auch zu Warnungen. Man kann auch die Definition von \Package{tocbasic} generell nutzen, indem man bereits in der Dokumentpräambel \Macro{usetocbasicnumberline} aufruft. Die Anweisung versucht zunächst zu ermitteln, ob in der aktuellen Definition wichtige interne Anweisungen von \Package{tocbasic} verwendet werden. Ist dies -nicht der Fall wird \Macro{numberline} entsprechend umdefiniert und zusätzlich +nicht der Fall, wird \Macro{numberline} entsprechend umdefiniert und zusätzlich \PName{Code} ausgeführt. Ist kein optionales Arguments angegeben, wird stattdessen via \Macro{PackageInfo} eine Meldung über die erfolgte Umdefinierung ausgegeben. Diese Meldung kann man einfach unterdrücken, indem ein leeres optionales Argument angegeben wird. Es\textnote{Achtung!} ist zu beachten, dass \Macro{usetocbasicnumberline} den -internen Schalter \Macro{@tempswa} global verändern kann!% +internen Schalter \Macro{if@tempswa} global verändern kann!% \EndIndexGroup @@ -924,10 +949,11 @@ sein muss. \PName{Stil} abhängenden Eigenschaften des Eintrags festgelegt werden. Derzeit werden von \Package{tocbasic} die folgenden Eintragsstile definiert: -\begin{description} +\begin{description}\setkomafont{descriptionlabel}{} \item[\PValue{default}] ist in der Voreinstellung ein Klon von Stil \PValue{dottedtocline}. Klassenautoren, die \Package{tocbasic} verwenden, - wird empfohlen, diesen Stil mit Hilfe von \Macro{CloneTOCStyle} auf den + wird empfohlen, diesen Stil mit Hilfe von + \DescRef{\LabelBase.cmd.CloneTOCEntryStyle} auf den Standardverzeichniseintragsstil der Klasse zu ändern. Bei den \KOMAScript-Klassen wird \PValue{default} beispielsweise zu einem Klon von Stil \PValue{tocline}. @@ -935,8 +961,8 @@ Derzeit werden von \Package{tocbasic} die folgenden Eintragsstile definiert: \Class{book} und \Class{report} für die Inhaltsverzeichniseinträge der Ebenen \PValue{section} bis \PValue{subparagraph} und bei allen Standardklassen für die Einträge in das Abbildungs- und das - Tabellenverzeichnis bekannt ist. Er kennt nur die Eigenschaften - \PValue{level}, \PValue{indent} und \PValue{numwidth}. Die Einträge werden + Tabellenverzeichnis bekannt ist. Er kennt nur drei\important{\PValue{level}, + \PValue{indent}, \PValue{numwidth}} Eigenschaften. Die Einträge werden um \PValue{indent} von links eingezogen in der aktuellen Schrift ausgegeben. \DescRef{\LabelBase.cmd.numberline} wird nicht umdefiniert. Die Breite der Nummer wird von \PValue{numwidth} bestimmt. Bei mehrzeiligen @@ -999,27 +1025,30 @@ Derzeit werden von \Package{tocbasic} die folgenden Eintragsstile definiert: nicht ausgegeben sondern sozusagen verschluckt. Dennoch verfügt er über die Standardeigenschaft \PValue{level}, die jedoch nie ausgewertet wird. \item[\PValue{largetocline}] entspricht dem Stil, der von den Standardklassen - für die Ebene \PValue{part} bekannt ist. Er kennt nur die Eigenschaften + für die Ebene \PValue{part} bekannt ist. Er kennt + nur\important{\PValue{level}, \PValue{indent}} die Eigenschaften \PName{level} und \PName{indent}. Letzteres ist gleichsam eine Abweichung von den Standardklassen, die selbst keinen Einzug der \PValue{part}-Einträge unterstützen. Vor dem Eintrag wird ein Seitenumbruch erleichtert. Die Einträge werden um - \PValue{indent} von links eingezogen in \Macro{large}\Macro{bfseries} - ausgegeben. Sollte \DescRef{\LabelBase.cmd.numberline} verwendet werden, so - ist die Nummernbreite fest auf 3\Unit{em} + \PValue{indent} von links eingezogen und mit den Schrifteinstellungen + \Macro{large}\Macro{bfseries} ausgegeben. Sollte + \DescRef{\LabelBase.cmd.numberline} verwendet werden, so ist die + Nummernbreite fest auf 3\Unit{em} eingestellt. \DescRef{\LabelBase.cmd.numberline} wird nicht umdefiniert. Die Standardklassen verwenden für \PName{part}-Einträge kein \DescRef{\LabelBase.cmd.numberline}. Der Wert hat bei mehrzeiligen Einträgen auch keine Auswirkung auf den Einzug ab der zweiten Zeile. - \autoref{fig:tocbasic.largetocline} illustriert die Eigenschaften des - Stils. Dabei wird auch auffällig, dass der Stil einige Ungereimtheiten der - Standardklassen übernommen hat, beispielsweise der fehlende Einzug ab der - zweiten Zeile bei mehrzeiligen Einträgen und zwei unterschiedliche Werte für - \Macro{@pnumwidth}, die aus einer Abhängigkeit von der Schriftgröße + \autoref{fig:tocbasic.largetocline} illustriert die + Eigenschaften + des Stils. Dabei wird auch auf"|fällig, dass der Stil einige Ungereimtheiten + der Standardklassen übernommen hat, beispielsweise der fehlende Einzug ab + der zweiten Zeile bei mehrzeiligen Einträgen und zwei unterschiedliche Werte + für \Macro{@pnumwidth}, die aus einer Abhängigkeit von der Schriftgröße resultieren. Daraus resultiert auch der Umstand, dass im Extremfall der Text - der Überschrift der Seitenzahl zu nah kommen kann. Es ist zu beachten, dass + der Überschrift der Seitenzahl zu nahe kommen kann. Es ist zu beachten, dass die in der Abbildung gezeigte Breite der Gliederungsnummer nur dann Verwendung findet, wenn auch tatsächlich \DescRef{\LabelBase.cmd.numberline} verwendet wird. Die Standardklassen setzen hingegen einen festen Abstand von @@ -1066,21 +1095,23 @@ Derzeit werden von \Package{tocbasic} die folgenden Eintragsstile definiert: mit Hilfe dieses Stils, ändern dann jedoch den \PName{Initialisierungscode} der Klone so ab, dass sie unterschiedliche Voreinstellungen besitzen. - Der Stil kennt die Eigenschaften \PValue{level}, \PValue{beforeskip}, - \PValue{dynnumwidth}, \PValue{entryformat}, \PValue{entrynumberformat}, - \PValue{breakafternumber}, \PValue{indent}, \PValue{linefill}, - \PValue{numsep}, \PValue{numwidth}, \PValue{onstarthigherlevel}, - \PValue{onstartlowerlevel}, \PValue{onstartsamelevel}, - \PValue{pagenumberbox}, \PValue{pagenumberformat}, \PValue{raggedentrytext} - und \PValue{raggedpagenumber}. Die Voreinstellungen all dieser Eigenschaften - werden abhängig vom Namen der \PName{Eintragsebene} bestimmt und orientieren - sich dann an den Ergebnissen der Standardklassen. Es ist daher möglich, nach - Laden von \Package{tocbasic} den Stil der Inhaltsverzeichniseinträge der - Standardklassen mit \DescRef{\LabelBase.cmd.DeclareTOCEntryStyle} in \PValue{tocline} zu - ändern, ohne dass dies unmittelbar zu größeren Veränderungen im Aussehen der + Der Stil kennt neben der Standardeigenschaft \PValue{level} noch + 16\important{\PValue{level}, \PValue{beforeskip}, \PValue{breakafternumber}, + \PValue{dynnumwidth}, \PValue{entryformat}, \PValue{entrynumberformat}, + \PValue{indent}, \PValue{linefill}, \PValue{numsep}, \PValue{numwidth}, + \PValue{onstarthigherlevel}, \PValue{onstartlowerlevel}, + \PValue{onstartsamelevel}, \PValue{pagenumberbox}, + \PValue{pagenumberformat}, \PValue{raggedentrytext}, + \PValue{raggedpagenumber}} weitere Eigenschaften. Die Voreinstellungen all + dieser Eigenschaften werden abhängig vom Namen der \PName{Eintragsebene} + bestimmt und orientieren sich dann an den Ergebnissen der + Standardklassen. Es ist daher möglich, nach Laden von \Package{tocbasic} den + Stil der Inhaltsverzeichniseinträge der Standardklassen mit + \DescRef{\LabelBase.cmd.DeclareTOCEntryStyle} in \PValue{tocline} zu ändern, + ohne dass dies unmittelbar zu größeren Veränderungen im Aussehen der Inhaltsverzeichniseinträge führt. So kann man gezielt nur die Eigenschaften ändern, die für erwünschte Änderungen notwendig sind. Dasselbe gilt für - Abbildungs- und Tabellenverzeichnis der Standardklassen. + Abbildungs- und Tabellenverzeichnis der Standardklassen.% Aufgrund der hohen Flexibilität kann dieser Stil prinzipiell die Stile \PValue{dottedtocline}, \PValue{undottedtocline} und \PValue{largetocline} @@ -1237,19 +1268,17 @@ Derzeit werden von \Package{tocbasic} die folgenden Eintragsstile definiert: \item[\PValue{undottedtocline}] entspricht dem Stil, der von den Standardklassen \Class{book} und \Class{report} für die Ebene \PValue{chapter} und von \Class{article} für die Ebene \PValue{section} - bekannt ist. Er kennt nur die Eigenschaften \PValue{level}, \PValue{indent} - und \PValue{numwidth}. Letztere ist gleichsam eine Abweichung von den - Standardklassen, die selbst keinen Einzug für die genannten Ebenen - unterstützen. - + bekannt ist. Er kennt\important{\PValue{level}, \PValue{indent}, + \PValue{numwidth}} nur drei Eigenschaften. Vor dem Eintrag wird ein Seitenumbruch erleichtert und ein vertikaler Abstand eingefügt. Die Einträge werden um \PValue{indent} von links - eingezogen in \Macro{bfseries} - ausgegeben. \DescRef{\LabelBase.cmd.numberline} wird nicht umdefiniert. Die - Breite der Nummer wird von \PValue{numwidth} bestimmt. Bei mehrzeiligen - Einträgen wird der Einzug ab der zweiten Zeile um \PValue{numwidth} - erhöht. \autoref{fig:tocbasic.undottedtocline} illustriert die Eigenschaften - des Stils. + eingezogen in \Macro{bfseries} ausgegeben. Dies ist gleichsam eine + Abweichung von den Standardklassen, die selbst keinen Einzug für Einträge + der genannten Ebenen bieten. \DescRef{\LabelBase.cmd.numberline} wird nicht + umdefiniert. Die Breite der Nummer wird von \PValue{numwidth} bestimmt. Bei + mehrzeiligen Einträgen wird der Einzug ab der zweiten Zeile um + \PValue{numwidth} erhöht. \autoref{fig:tocbasic.undottedtocline} illustriert + die Eigenschaften des Stils. \begin{figure} \centering \resizebox{.8\linewidth}{!}{% @@ -1292,16 +1321,19 @@ Derzeit werden von \Package{tocbasic} die folgenden Eintragsstile definiert: Eine Erklärung zu den Eigenschaften der von \Package{tocbasic} definierten Stile findet sich in \autoref{tab:tocbasic.tocstyle.attributes}. Bei\ChangedAt[2016/06]{v3.21}{\Package{tocbasic}} Verwendung der Eigenschaften -als Optionen für \DescRef{\LabelBase.cmd.DeclareNewTOC} (siehe +als Optionen für +\DescRef{\LabelBase.cmd.DeclareNewTOC}\IndexCmd{DeclareNewTOC} (siehe \DescPageRef{\LabelBase.cmd.DeclareNewTOC}) sind die Namen der Eigenschaften mit dem Präfix \PValue{tocentry}, also beispielsweise \Option{tocentrylevel} -an Stelle von \PValue{level} zu +anstelle von \PValue{level}, zu verwenden. Bei\ChangedAt[2015/12]{v3.20}{\Package{tocbasic}} Verwendung als -Optionen für \DescRef{maincls-experts.cmd.DeclareSectionCommand} (siehe +Optionen für \DescRef{maincls-experts.cmd.DeclareSectionCommand}% +\IndexCmd{DeclareSectionCommand}\IndexCmd{DeclareNewSectionCommand}% +\IndexCmd{RedeclareSectionCommand}\IndexCmd{ProvideSectionCommand} (siehe \DescPageRef{maincls-experts.cmd.DeclareSectionCommand}) und verwandten Anweisungen sind die Namen der Eigenschaften mit dem Präfix \PValue{toc} zu -versehen, also beispielsweise \Option{toclevel} an Stelle von \PValue{level} -zu verwenden. +versehen, also beispielsweise \Option{toclevel} anstelle von \PValue{level} zu +verwenden. Letztlich führt der Aufruf von \Macro{DeclareTOCStyleEntry} zur Definition der Anweisung \Macro{l@\PName{Eintragsebene}}. @@ -1324,9 +1356,9 @@ Anweisung \Macro{l@\PName{Eintragsebene}}. Bei der \PName{Eintragsebene} \PValue{part} wird das Attribut mit \texttt{2.25em plus 1pt} initialisiert, bei \PValue{chapter} mit \texttt{1em plus 1pt}. Ist noch keine \PName{Eintragsebene} - \PValue{chapter} bekannt wird für \PValue{section} ebenfalls \texttt{1em - plus 1pt} verwendet. Alle anderen Ebenen werden mit \texttt{0pt plus - .2pt} initialisiert.% + \PValue{chapter} bekannt, wird stattdessen für \PValue{section} + \texttt{1em plus 1pt} verwendet. Ansonsten wird \PValue{section} wie alle + anderen Ebenen mit \texttt{0pt plus .2pt} initialisiert.% }% \entry{\OptionVName{breakafternumber}{Schalter}}{% \PName{Schalter} ist einer der Werte für einfache Schalter aus @@ -1338,14 +1370,14 @@ Anweisung \Macro{l@\PName{Eintragsebene}}. In der Voreinstellung ist die Eigenschaft im Stil \PValue{tocline} nicht gesetzt. - Ist\textnote{Achtung!} für ein Verzeichnis mit - \DescRef{\LabelBase.cmd.setuptoc} die Eigenschaft \Option{numberline} - gesetzt (siehe \autoref{sec:tocbasic.toc}, + Ist %\textnote{Achtung!} + für ein Verzeichnis mit \DescRef{\LabelBase.cmd.setuptoc} die Eigenschaft + \Option{numberline} gesetzt (siehe \autoref{sec:tocbasic.toc}, \DescPageRef{\LabelBase.cmd.setuptoc}), wie dies bei den \KOMAScript-Klassen und Verwendung deren Option \OptionValueRef{maincls}{toc}{numberline}% - \IndexOption{toc~=\PValue{numberline}} der Fall ist, führt dies auch dazu, - dass bei nicht nummerierten Einträgen dennoch die Zeile mit der dann + \IndexOption{toc~=\textKValue{numberline}} der Fall ist, führt dies auch + dazu, dass bei nicht nummerierten Einträgen dennoch die Zeile mit der dann leeren Nummer in der Formatierung von \Option{entrynumberformat} gesetzt wird.% }% @@ -1355,8 +1387,8 @@ Anweisung \Macro{l@\PName{Eintragsebene}}. Schalter beim Stil \PValue{tocline} aktiviert, gibt die Eigenschaft \PValue{numwidth} nur noch einen Minimalwert an. Übertrifft die beim letzten \LaTeX-Lauf ermittelte maximale Breite der Eintragsnummern - gleicher Ebene zuzüglich des Werts von \PValue{numsep} diesen Minimalwert, - so wird stattdessen der ermittelte Wert verwendet.% + gleicher Ebene zuzüglich des Wertes von \PValue{numsep} diesen + Minimalwert, so wird stattdessen der ermittelte Wert verwendet.% }% \entry{\OptionVName{entryformat}{Befehl}}{% Über diese Eigenschaft kann die Formatierung des gesamten Eintrags @@ -1388,14 +1420,15 @@ Anweisung \Macro{l@\PName{Eintragsebene}}. Initialisiert wird die Eigenschaft mit Ausgabe des übergebenen Arguments. Die Eintragsnummer wird also unverändert ausgegeben. - Ist\textnote{Achtung!} für ein Verzeichnis mit - \DescRef{\LabelBase.cmd.setuptoc} die Eigenschaft \Option{numberline} - gesetzt (siehe \autoref{sec:tocbasic.toc}, - \DescPageRef{\LabelBase.cmd.setuptoc}), wie dies bei den \KOMAScript-Klassen - und Verwendung deren Option \OptionValueRef{maincls}{toc}{numberline}% - \IndexOption{toc~=\PValue{numberline}} der Fall ist, führt dies auch dazu, - dass bei nicht nummerierten Einträgen \PName{Befehl} dennoch ausgeführt - wird.% + Ist %\textnote{Achtung!} + für ein Verzeichnis mit \DescRef{\LabelBase.cmd.setuptoc} die Eigenschaft + \Option{numberline} gesetzt (siehe \autoref{sec:tocbasic.toc}, + \DescPageRef{\LabelBase.cmd.setuptoc}), wie dies bei den + \KOMAScript-Klassen und Verwendung deren Option + \OptionValueRef{maincls}{toc}{numberline}% + \IndexOption{toc~=\textKValue{numberline}} der Fall ist, führt dies auch + dazu, dass bei nicht nummerierten Einträgen \PName{Befehl} dennoch + ausgeführt wird.% }% \entry{\OptionVName{indent}{Länge}}{% Horizontaler Abstand des Eintrags vom linken Rand (siehe @@ -1417,7 +1450,8 @@ Anweisung \Macro{l@\PName{Eintragsebene}}. Nummerischer Wert der \PName{Eintragsebene}. Tatsächlich angezeigt werden nur Einträge, deren nummerische Ebene nicht größer als Zähler \DescRef{\LabelBase.counter.tocdepth}% - \important{\DescRef{\LabelBase.counter.tocdepth}}\IndexCounter{tocdepth} + %\important{\DescRef{\LabelBase.counter.tocdepth}} + \IndexCounter{tocdepth} ist. Diese Eigenschaft ist für alle Stile zwingend und wird bei der @@ -1495,46 +1529,48 @@ Anweisung \Macro{l@\PName{Eintragsebene}}. Die Erkennung funktioniert übrigens nur, solange sich \Macro{lastpenalty} seit dem letzten Eintrag nicht geändert hat. - Initialisiert wird die Eigenschaft mit \DescRef{\LabelBase.cmd.LastTOCLevelWasLower} (siehe + Initialisiert wird die Eigenschaft mit + \DescRef{\LabelBase.cmd.LastTOCLevelWasLower} (siehe \DescPageRef{\LabelBase.cmd.LastTOCLevelWasLower}).% }% \entry{\OptionVName{onstartlowerlevel}{Code}}{% Der Stil \PValue{tocline} kann zu Beginn eines Eintrags eine Aktion in Abhängigkeit davon ausführen, ob der zuletzt gesetzte Eintrag einen - höheren, denselben oder einen niedrigeren \PName{level}-Wert - hatte. Der im Falle, dass der aktuelle Eintrag einen kleineren - \PName{level}-Wert besitzt, in der Hierarchie der Einträge also höher - steht, wird der über diese Eigenschaft angegebene \PName{Code} ausgeführt. + höheren, denselben oder einen niedrigeren \PName{level}-Wert hatte. Im + Falle, dass der aktuelle Eintrag einen kleineren \PName{level}-Wert + besitzt, in der Hierarchie der Einträge also höher steht, wird der über + diese Eigenschaft angegebene \PName{Code} ausgeführt. Die Erkennung funktioniert übrigens nur, solange sich \Macro{lastpenalty} seit dem letzten Eintrag nicht geändert hat. - Initialisiert wird die Eigenschaft mit \DescRef{\LabelBase.cmd.LastTOCLevelWasHigher} (siehe + Initialisiert wird die Eigenschaft mit + \DescRef{\LabelBase.cmd.LastTOCLevelWasHigher} (siehe \DescPageRef{\LabelBase.cmd.LastTOCLevelWasHigher}), was normalerweise dazu führt, dass ein Umbruch vor dem Eintrag begünstigt wird.% }% \entry{\OptionVName{onstartsamelevel}{Code}}{% Der Stil \PValue{tocline} kann zu Beginn eines Eintrags eine Aktion in Abhängigkeit davon ausführen, ob der zuletzt gesetzte Eintrag einen - höheren, denselben oder einen niedrigeren \PName{level}-Wert - hatte. Der im Falle, dass der aktuelle Eintrag denselben - \PName{level}-Wert besitzt, in der Hierarchie der Einträge also gleich - gestellt ist, wird der über diese Eigenschaft angegebene \PName{Code} - ausgeführt. + höheren, denselben oder einen niedrigeren \PName{level}-Wert hatte. Im + Falle, dass der aktuelle Eintrag denselben \PName{level}-Wert besitzt, in + der Hierarchie der Einträge also gleich gestellt ist, wird der über diese + Eigenschaft angegebene \PName{Code} ausgeführt. Die Erkennung funktioniert übrigens nur, solange sich \Macro{lastpenalty} seit dem letzten Eintrag nicht geändert hat. - Initialisiert wird die Eigenschaft mit \DescRef{\LabelBase.cmd.LastTOCLevelWasSame} (siehe - \DescPageRef{\LabelBase.cmd.LastTOCLevelWasSame}), was normalerweise - dazu führt, dass ein Umbruch vor dem Eintrag begünstigt wird.% + Initialisiert wird die Eigenschaft mit + \DescRef{\LabelBase.cmd.LastTOCLevelWasSame} (siehe + \DescPageRef{\LabelBase.cmd.LastTOCLevelWasSame}), was normalerweise dazu + führt, dass ein Umbruch vor dem Eintrag begünstigt wird.% }% \entry{\OptionVName{pagenumberbox}{Befehl}}{% Normalerweise wird die zu einem Eintrag gehörende Seitenzahl rechtsbündig in eine Box der Breite \Macro{@pnumwidth} gesetzt. Beim Stil \PValue{tocline} kann der Befehl, der dazu verwendet wird, über diese - Eigenschaft konfiguriert werden. Der dabei anzugebende \PName{Befehl} - hat genau ein Argument zu erwarten. + Eigenschaft konfiguriert werden. Der dabei anzugebende \PName{Befehl} hat + genau ein Argument zu erwarten. Initialisiert wird die Eigenschaft mit der bereits erwähnten Box.% }% @@ -1542,7 +1578,7 @@ Anweisung \Macro{l@\PName{Eintragsebene}}. Über diese Eigenschaft kann die Formatierung der Seitenzahl des Eintrags verändert werden. Der dabei als Wert angegebene \PName{Befehl} hat genau ein Argument zu erwarten. Font-Änderungen über \Option{entryformat} - erfolgen ausgehend von \Option{entryformat} gefolgt von + erfolgen ausgehend von \Option{entryformat}, gefolgt von \Macro{normalfont}\Macro{normalsize}. Initialisiert wird die Eigenschaft für die \PName{Eintragsebene} @@ -1632,19 +1668,19 @@ Einlesen dieser Hilfsdatei f eine Anweisung \Macro{l@\PName{Eintragsebene}} aus. Wird später einer \PName{Eintragsebene} über -\DescRef{\LabelBase.cmd.DeclareTOCStyleEntry} der \PName{Stil} zugewiesen, so -wird zunächst der optionale \PName{Initialisierungscode} ausgeführt und dann -\Macro{l@\PName{Eintragsebene}} als \PName{Befehlscode} -definiert. \PName{Befehlscode} ist also letztlich der Code, der bei +\DescRef{\LabelBase.cmd.DeclareTOCStyleEntry} ein \PName{Stil} zugewiesen, so +wird zunächst \PName{Initialisierungscode} ausgeführt falls angegeben und dann +\PName{Befehlscode} für die Definition von \Macro{l@\PName{Eintragsebene}} +verwendet. \PName{Befehlscode} ist also letztlich der Code, der bei \Macro{l@\PName{Eintragsebene}} ausgeführt wird. Dabei ist \texttt{\#1} der Name der Eintragsebene, während \texttt{\#\#1} und \texttt{\#\#2} Platzhalter für die beiden Argumente von \Macro{l@\PName{Eintragsebene}} sind. -Der \PName{Initialisierungscode} dient einerseits dazu, alle Einstellungen zu -initialisieren. Entwickler sollten darauf achten, dass wirklich alle -Einstellungen hier bereits einen Wert erhalten, damit -\DescRef{\LabelBase.cmd.DeclareTOCStyleEntry} auch ohne Angabe einer -\PName{Optionenliste} fehlerfrei funktioniert. Darüber hinaus hat der +Der \PName{Initialisierungscode} dient einerseits dazu, die Einstellungen +eines Stils zu initialisieren. Entwickler\textnote{Empfehlung!} sollten darauf +achten, dass wirklich alle Einstellungen hier bereits einen Wert erhalten. Nur +dann funktioniert \DescRef{\LabelBase.cmd.DeclareTOCStyleEntry} auch ohne +Angabe einer \PName{Optionenliste} fehlerfrei. Darüber hinaus hat der \PName{Initialisierungscode} auch alle Optionen, die der jeweilige Stil versteht, zu definieren. Zwingend vordefiniert wird lediglich \Option{level}. Der eingestellte Wert für \Option{level} kann in @@ -1653,12 +1689,13 @@ versteht, zu definieren. Zwingend vordefiniert wird lediglich beispielsweise mit dem Wert des Zählers \DescRef{\LabelBase.counter.tocdepth}\IndexCounter{tocdepth} zu vergleichen. -Zur Definition neuer Optionen zur Einstellung von Eigenschaften einer -Eintragsebene stehen nur innerhalb von \PName{Initialisierungscode} die -Anweisungen \Macro{DefineTOCEntryBooleanOption}, +Zur Definition neuer Optionen für die Eigenschaften einer +Eintragsebene existieren nur innerhalb von \PName{Initialisierungscode} die +Anweisungen \iffree{\Macro{DefineTOCEntryBooleanOption}, \Macro{DefineTOCEntryCommandOption}, \Macro{DefineTOCEntryIfOption}, -\Macro{DefineTOCEntryLengthOption} und \Macro{DefineTOCEntryNumberOption}. -All diese Anweisungen definieren jeweils eine \PName{Option}, die bei ihrem +\Macro{DefineTOCEntryLengthOption} und +\Macro{DefineTOCEntryNumberOption}}{\Macro{DefineTOCEntry\dots Option}}. +Diese Anweisungen definieren jeweils eine \PName{Option}, die bei ihrem Aufruf eine Anweisung \Macro{\PName{Präfix}\PName{Eintragsebene}\PName{Postfix}} mit dem übergebenen Wert oder bei Fehlen einer Wertzuweisung mit dem \PName{Säumniswert} @@ -1693,29 +1730,32 @@ entsprechen. Innerhalb von Stil \PValue{tocline} wird beispielsweise \begin{lstcode} - \DefineTOCEntryCommandOption{linefill}[\TOCLineLeaderFill]% - {scr@tso@}{@linefill}{filling between text and page number}% + \DefineTOCEntryCommandOption{linefill}% + [\TOCLineLeaderFill]{scr@tso@}{@linefill}% + {filling between text and page number}% \end{lstcode} -verwendet, um Option \Option{linefill} mit dem \PName{Säumniswert} -\DescRef{\LabelBase.cmd.TOCLineLeaderFill} zu definieren. Ein Aufruf wie +verwendet, um Option \Option{linefill} zu definieren. Durch die Angabe von +\DescRef{\LabelBase.cmd.TOCLineLeaderFill} als \PName{Säumniswert} würde ein +Aufruf wie \begin{lstcode} \RedeclareTOCStyleEntry[linefill]{tocline}{part} \end{lstcode} -würde daher unter anderem die Definition +unter anderem die Definition \begin{lstcode} \def\scr@tso@part@linefill{\TOCLineLeaderFill} \end{lstcode} vornehmen. -Wer sich selbst einen Stil definieren möchte, dem sei empfohlen, zunächst die -Definition des Stils \PValue{dottedtocline} zu studieren. Nachdem dessen -Definition verstanden wurde, gibt dann die deutlich komplexere Definition von -Stil \PValue{tocline} viele Hinweise darauf, wie die Anweisungen sinnvoll zu -verwenden sind. +Wer\textnote{Tipp!} sich selbst einen Stil definieren möchte, dem sei +empfohlen, zunächst die Definition des Stils \PValue{dottedtocline} zu +studieren. Nachdem dessen Definition verstanden wurde, gibt dann die deutlich +komplexere Definition von Stil \PValue{tocline} viele Hinweise darauf, wie die +Anweisungen sinnvoll zu verwenden sind. -In vielen Fällen wird es jedoch auch ausreichen, einen der vorhandenen Stile -mit \DescRef{\LabelBase.cmd.CloneTOCEntryStyle} zu klonen und dann dessen -Initialisierungscode mit \DescRef{\LabelBase.cmd.TOCEntryStyleInitCode} oder +In\textnote{Tipp!} vielen Fällen wird es jedoch auch ausreichen, einen der +vorhandenen Stile mit \DescRef{\LabelBase.cmd.CloneTOCEntryStyle} zu klonen +und dann dessen Initialisierungscode mit Anweisung +\DescRef{\LabelBase.cmd.TOCEntryStyleInitCode} oder \DescRef{\LabelBase.cmd.TOCEntryStyleStartInitCode} abzuändern. \Macro{DefineTOCEntryOption} dient eher der Definition der übrigen @@ -1735,9 +1775,12 @@ mit denselben Eigenschaften und Voreinstellungen wie der existierende \Macro{CloneTOCEntryStyle}, um den Stil \PValue{default} als Klon von \PValue{dottedtocline} zu deklarieren. Die \KOMAScript-Klassen verwenden die Anweisung um die Stile \PValue{part}, \PValue{section} und \PValue{chapter} -oder \PValue{subsection} als Klon von \PValue{tocline} zu deklarieren und den -Stil \PValue{default} neu als Klon von \PValue{section} beziehungsweise -\PValue{subsection} zu deklarieren.% +oder \PValue{subsection} als Klon von \PValue{tocline} zu deklarieren und dann +mit \DescRef{\LabelBase.cmd.TOCEntryStyleInitCode} und +\DescRef{\LabelBase.cmd.TOCEntryStyleStartInitCode} abzuändern. Der Stil +\PValue{default} wird von \Class{scrbook} und \Class{scrreprt} neu als Klon +von \PValue{section} und von \Class{scrartcl} als Klon von \PValue{subsection} +deklariert.% \EndIndexGroup @@ -1751,14 +1794,15 @@ Jeder\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} Verzeichniseintragsstil verfügt über einen Initialisierungscode. Dieser wird immer dann aufgerufen, wenn einer Verzeichnisebene der entsprechende \PName{Stil} mit \DescRef{\LabelBase.cmd.DeclareTOCEntryStyle}\IndexCmd{DeclareTOCEntryStyle} -zugewiesen wird. Dieser \PName{Initialisierungscode} sollte keine globalen -Seiteneffekte aufweisen, da er auch für lokale Initialisierungen innerhalb -anderer Anweisungen wie \DescRef{\LabelBase.cmd.DeclareNewTOC}\IndexCmd{DeclareNewTOC} -verwendet wird. Der \PName{Initialisierungscode} dient einerseits dazu, -Eigenschaften für den jeweiligen \PName{Stil} zu definieren. Er setzt aber -auch die Standardeinstellungen für diese Eigenschaften. - -Mit Hilfe von \Macro{TOCEntryStyleStartInitCode} und +zugewiesen wird. Dieser\textnote{Achtung!} \PName{Initialisierungscode} sollte +keine globalen Seiteneffekte aufweisen, da er auch für lokale +Initialisierungen innerhalb anderer Anweisungen wie +\DescRef{\LabelBase.cmd.DeclareNewTOC}\IndexCmd{DeclareNewTOC} verwendet +wird. Der \PName{Initialisierungscode} dient einerseits dazu, Eigenschaften +für den jeweiligen \PName{Stil} zu definieren. Er setzt aber auch die +Standardeinstellungen für diese Eigenschaften. + +Mit Hilfe der Anweisungen \Macro{TOCEntryStyleStartInitCode} und \Macro{TOCEntryStyleInitCode} kann der für einen \PName{Stil} bereits definierte Initialisierungscode um weiteren \PName{Initialisierungscode} erweitert werden. Dabei fügt \Macro{TOCEntryStyleStartInitCode} den neuen @@ -1787,8 +1831,9 @@ definieren.% \Macro{LastTOCLevelWasLower} \end{Declaration} Bei\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} Einträgen im Stil -\PValue{tocline} wird am Anfang abhängig von \Macro{lastpenalty} eine dieser -drei Anweisungen ausgeführt. Dabei fügen \Macro{LastTOCLevelWasHigher} und +\PValue{tocline} wird am Anfang abhängig vom Wert von +\Macro{lastpenalty}\IndexCmd{lastpenalty} eine dieser drei Anweisungen +ausgeführt. Dabei fügen \Macro{LastTOCLevelWasHigher} und \Macro{LastTOCLevelWasSame} im vertikalen Modus \Macro{addpenalty}\PParameter{\Macro{@lowpenalty}} ein und ermöglichen so einen Umbruch vor Einträgen gleicher oder übergeordneter @@ -1797,8 +1842,8 @@ dass zwischen einem Eintrag und seinem ersten Untereintrag normalerweise ein Umbruch untersagt ist. Anwender sollten diese Anweisungen nicht umdefinieren. Stattdessen können und -sollten Änderungen für die jeweiligen Eintragsebenen gezielt über die -Eigenschaften \PValue{onstartlowerlevel}, \PValue{onstartsamelevel} und +sollten Änderungen bei Zuweisung des Stils an eine Eintragsebene gezielt über +die Eigenschaften \PValue{onstartlowerlevel}, \PValue{onstartsamelevel} und \PValue{onstarthigherlevel} vorgenommen werden.% \EndIndexGroup @@ -1811,11 +1856,12 @@ als Wert f \PName{tocline} verwendet zu werden. Sie erzeugt dann eine Verbindung zwischen dem Ende des Textes eines Eintrags und der zugehörigen Seitenzahl. Das \PName{Füllzeichen}, das dazu in regelmäßigem Abstand wiederholt wird, kann -als optionales Argument angegeben werden. Voreinstellung ist ein Punkt. +als optionales Argument angegeben werden. Voreinstellung ist ein +Punkt.\textnote{Voreinstellung} Wie der Name schon vermuten lässt, werden die Füllzeichen mit Hilfe von -\Macro{leaders} gesetzt. Als Abstand wird wie bei \Macro{@dottedtocline} aus -dem \LaTeX-Kern vor und nach dem Füllzeichen +\Macro{leaders} gesetzt. Als Abstand wird wie bei der \LaTeX-Kern-Anweisung +\Macro{@dottedtocline} vor und nach dem Füllzeichen \Macro{mkern}\Macro{@dotsep}\Unit{\texttt{mu}} verwendet.% \EndIndexGroup % @@ -1830,7 +1876,7 @@ Benutzung durch Klassen- und Paketautoren freigegeben ist. Diese Anweisungen beginnen alle mit \Macro{tocbasic@}. Aber\textnote{Achtung!} auch Klassen- und Paketautoren sollten diese Anweisungen nur verwenden und nicht etwa umdefinieren! Ihre interne Funktion kann jederzeit geändert oder erweitert -werden, so dass Umdefinierung der Anweisungen die Funktion von +werden, so dass jede Umdefinierung der Anweisungen die Funktion von \Package{tocbasic} erheblich beschädigen könnte! @@ -1856,39 +1902,43 @@ die Eigenschaft \PValue{nobabel}\important{\PValue{nobabel}} (siehe \DescRef{\LabelBase.cmd.setuptoc}, \autoref{sec:tocbasic.toc}, \DescPageRef{\LabelBase.cmd.setuptoc}) kann dies unterdrückt werden. Für die Dateinamenerweiterungen \File{toc}, \File{lof} und \File{lot} unterdrückt -\Package{tocbasic} dies bereits selbst, damit die Umschaltung nicht mehrfach -in die zugehörigen Dateien eingetragen wird. +\Package{tocbasic} dies bereits selbst, % +\iftrue% Umbruchvarianten +da \Package{babel} sie von sich aus vornimmt.% +\else% +damit die Umschaltung nicht mehrfach in die zugehörigen Dateien +eingetragen wird.% +\fi Normalerweise gibt es keinen Grund, diese Anweisung selbst aufzurufen. Es sind allerdings Verzeichnisse denkbar, die nicht unter der Kontrolle von \Package{tocbasic} stehen, also nicht in der Liste der bekannten Dateierweiterungen geführt werden, aber trotzdem die Spracherweiterung für -\Package{babel} nutzen sollen. Für diese ist die Anweisung explizit -aufzurufen. Bitte achten Sie jedoch darauf, dass dies für jede Dateierweiterung -nur einmal geschieht! -% +\Package{babel} nutzen sollen. Für derartige Verzeichnisse wäre die Anweisung +explizit aufzurufen. Bitte\textnote{Achtung!} achten Sie jedoch darauf, dass +dies für jede Dateierweiterung nur einmal geschieht!% \EndIndexGroup \begin{Declaration} \Macro{tocbasic@starttoc}\Parameter{Dateierweiterung} \end{Declaration} -Diese Anweisung ist der eigentlich Ersatz der Anweisung +Diese Anweisung ist der eigentliche Ersatz der Anweisung \Macro{@starttoc}\IndexCmd{@starttoc}\important{\Macro{@starttoc}} aus dem -\LaTeX-Kern. Es ist die Anweisung, die sich hinter \DescRef{\LabelBase.cmd.listoftoc*} (siehe -\autoref{sec:tocbasic.toc}, \DescPageRef{\LabelBase.cmd.listoftoc*}) -verbirgt. Klassen- oder Paketautoren, die Vorteile von \Package{tocbasic} -nutzen wollen, sollten zumindest diese Anweisung, besser jedoch -\DescRef{\LabelBase.cmd.listoftoc} verwenden. Die Anweisung baut selbst auf \Macro{@starttoc} -auf, setzt allerdings zuvor -\Length{parskip}\IndexLength{parskip}\important[i]{\Length{parskip}\\ - \Length{parindent}\\ - \Length{parfillskip}} und \Length{parindent}\IndexLength{parindent} auf 0 -und \Length{parfillskip}\IndexLength{parfillskip} auf 0 bis -unendlich. Außerdem wird -\Macro{@currext}\important{\Macro{@currext}}\IndexCmd{@currext} auf die +\LaTeX-Kern. Es ist die Anweisung, die sich hinter +\DescRef{\LabelBase.cmd.listoftoc*} (siehe \autoref{sec:tocbasic.toc}, +\DescPageRef{\LabelBase.cmd.listoftoc*}) verbirgt. Klassen- oder Paketautoren, +die Vorteile von \Package{tocbasic} nutzen wollen, sollten zumindest diese +Anweisung, besser jedoch \DescRef{\LabelBase.cmd.listoftoc} verwenden. Die +Anweisung baut selbst auf \Macro{@starttoc} auf, setzt allerdings zuvor +\Length{parskip}\IndexLength{parskip}\important[i]{\Length{parskip}, + \Length{parindent}, \Length{parfillskip}} und +\Length{parindent}\IndexLength{parindent} auf 0 und +\Length{parfillskip}\IndexLength{parfillskip} auf 0 bis unendlich. Außerdem +wird \Macro{@currext}\important{\Macro{@currext}}\IndexCmd{@currext} auf die aktuelle Dateierweiterung gesetzt, damit diese in den nachfolgend ausgeführten -Haken ausgewertet werden kann. +Haken\Index{Haken} ausgewertet werden kann. Die Erklärungen der Haken finden +Sie im Anschluss. Da\textnote{Achtung!} \LaTeX{} bei der Ausgabe eines Verzeichnisses auch gleich eine neue Verzeichnisdatei zum Schreiben öffnet, kann der Aufruf dieser @@ -1901,8 +1951,7 @@ Anweisung zu einer Fehlermeldung der Art führen, wenn keine Schreibdateien mehr zur Verfügung stehen. Abhilfe kann in diesem Fall das Laden des in \autoref{cha:scrwfile} beschriebenen Pakets \Package{scrwfile}\important{\Package{scrwfile}}\IndexPackage{scrwfile} -bieten. -% +oder die Verwendung von Lua\LaTeX{} bieten.% \EndIndexGroup @@ -1910,16 +1959,17 @@ bieten. \Macro{tocbasic@@before@hook} \Macro{tocbasic@@after@hook} \end{Declaration} -Der Haken \Macro{tocbasic@@before@hook} wird unmittelbar vor dem Einlesen der -Verzeichnisdatei, noch vor den mit \DescRef{\LabelBase.cmd.BeforeStartingTOC} -definierten Anweisungen ausgeführt. Es ist erlaubt, diesen Haken mit Hilfe von +Der Haken\Index{Haken} \Macro{tocbasic@@before@hook} wird unmittelbar vor dem +Einlesen der Verzeichnisdatei, noch vor den mit +\DescRef{\LabelBase.cmd.BeforeStartingTOC} definierten Anweisungen +ausgeführt. Es ist erlaubt, diesen Haken mit Hilfe von \Macro{g@addto@macro}\IndexCmd{g@addto@macro} zu erweitern. Ebenso wird \Macro{tocbasic@@after@hook} unmittelbar nach der Verzeichnisdatei, aber noch vor den mit \DescRef{\LabelBase.cmd.AfterStartingTOC} definierten Anweisungen -ausgeführt. Es ist erlaubt, diesen Haken mit Hilfe von \Macro{g@addto@macro} -zu erweitern. +ausgeführt. Es ist erlaubt, diesen Haken mit Hilfe von +\Macro{g@addto@macro}\IndexCmd{g@addto@macro} zu erweitern. \KOMAScript{} nutzt diese Haken, um Verzeichnisse mit dynamischer Anpassung an die Breite der Gliederungsnummern zu ermöglichen. Ihre Verwendung ist Klassen @@ -1932,9 +1982,8 @@ innerhalb der beiden Haken sind nicht gestattet! Wird keine\textnote{Achtung!} der Anweisungen \DescRef{\LabelBase.cmd.listofeachtoc}, \DescRef{\LabelBase.cmd.listoftoc} und \DescRef{\LabelBase.cmd.listoftoc*} für die Ausgabe der Verzeichnisse -verwendet, sollten die beiden Anweisungen für die Haken trotzdem aufgerufen -werden. -% +verwendet, sollten die Anweisungen für die Haken\Index{Haken} trotzdem +aufgerufen werden.% \EndIndexGroup @@ -1942,19 +1991,20 @@ werden. \Macro{tb@\PName{Dateierweiterung}@before@hook} \Macro{tb@\PName{Dateierweiterung}@after@hook} \end{Declaration} -Diese Anweisungen werden direkt nach \DescRef{\LabelBase.cmd.tocbasic@@before@hook} bzw. vor -\DescRef{\LabelBase.cmd.tocbasic@@after@hook} für das jeweilige Verzeichnis mit der -entsprechenden \PName{Dateierweiterung} ausgeführt. Sie\textnote{Achtung!} -dürfen keinesfalls von Klassen- und Paketautoren verändert werden. Werden für -die Ausgabe der Verzeichnisse die Anweisungen -\DescRef{\LabelBase.cmd.listoftoc}, \DescRef{\LabelBase.cmd.listoftoc*} und -\DescRef{\LabelBase.cmd.listofeachtoc} nicht verwendet, sollten die beiden -Anweisungen für die Haken trotzdem aufgerufen werden, soweit sie definiert -sind. Die Anweisungen können auch undefiniert sein. Für einen entsprechenden -Test siehe +Diese Anweisungen werden direkt nach +\DescRef{\LabelBase.cmd.tocbasic@@before@hook} bzw. vor +\DescRef{\LabelBase.cmd.tocbasic@@after@hook} für das jeweilige Verzeichnis +mit der entsprechenden \PName{Dateierweiterung} +ausgeführt. Sie\textnote{Achtung!} dürfen keinesfalls von Klassen- und +Paketautoren verändert werden. Werden für die Ausgabe der Verzeichnisse die +Anweisungen \DescRef{\LabelBase.cmd.listoftoc}, +\DescRef{\LabelBase.cmd.listoftoc*} und \DescRef{\LabelBase.cmd.listofeachtoc} +nicht verwendet, sollten die beiden Anweisungen für die Haken\Index{Haken} +trotzdem aufgerufen werden, soweit sie definiert sind. Die Anweisungen können +auch undefiniert sein. Für einen entsprechenden Test siehe \DescRef{scrbase.cmd.scr@ifundefinedorrelax}\IndexCmd{scr@ifundefinedorrelax} -in \autoref{sec:scrbase.if}, \DescPageRef{scrbase.cmd.scr@ifundefinedorrelax}. -% +in \autoref{sec:scrbase.if}, +\DescPageRef{scrbase.cmd.scr@ifundefinedorrelax}.% \EndIndexGroup @@ -1969,8 +2019,7 @@ Anweisung sein. Wenn Sie Ihre eigene Anweisung f können Sie ebenfalls \Macro{tocbasic@listhead} verwenden. In diesem Fall sollte vor dem Aufruf von \Macro{tocbasic@listhead} die Anweisung \Macro{@currext}\important{\Macro{@currext}}\IndexCmd{@currext} auf die -Dateinamenerweiterung, die zu diesem Verzeichnis gehört, gesetzt werden. -% +Dateinamenerweiterung, die zu diesem Verzeichnis gehört, gesetzt werden.% \EndIndexGroup @@ -1978,9 +2027,9 @@ Dateinamenerweiterung, die zu diesem Verzeichnis geh \Macro{tocbasic@listhead@\PName{Dateierweiterung}}\Parameter{Titel} \end{Declaration} Ist diese individuelle Anweisung für das Setzen einer Verzeichnisüberschrift -definiert, so verwendet \DescRef{\LabelBase.cmd.tocbasic@listhead} diese. Anderenfalls -definiert \DescRef{\LabelBase.cmd.tocbasic@listhead} diese und ruft sie dann auf. -% +definiert, so verwendet \DescRef{\LabelBase.cmd.tocbasic@listhead} +sie. Anderenfalls definiert \DescRef{\LabelBase.cmd.tocbasic@listhead} diese +vor der Verwendung.% \EndIndexGroup @@ -1994,19 +2043,22 @@ definiert \DescRef{\LabelBase.cmd.tocbasic@listhead} diese und ruft sie dann auf Anweisung\ChangedAt{v3.12}{\Package{tocbasic}} \Macro{tocbasic@addxcontentsline} nimmt einen \PName{Eintrag} der angegebenen \PName{Ebene} in das über die \PName{Dateierweiterung} spezifizierte -Verzeichnis vor. Ob der Eintrag nummeriert wird oder nicht, hängt davon ab, ob -das Argument \PName{Gliederungsnummer} leer ist oder nicht. Im Falle eines -leeren Argument wird dem \PName{Eintrag} ein \Macro{nonumberline} ohne -Argument vorangestellt. Anderenfalls wird wie gewohnt -\DescRef{\LabelBase.cmd.numberline} mit \PName{Gliederungsnummer} als Argument -verwendet. +Verzeichnis vor. Ob der Eintrag nummeriert wird\iffree{ oder + nicht}{}% Umbruchvarianten +, hängt davon ab, ob das Argument \PName{Gliederungsnummer} leer ist oder +nicht. Im Falle eines leeren Argument wird dem \PName{Eintrag} ein +\Macro{nonumberline} ohne Argument vorangestellt. Anderenfalls wird wie +gewohnt \DescRef{\LabelBase.cmd.numberline} mit \PName{Gliederungsnummer} als +Argument verwendet. Die Anweisung \Macro{nonumberline} wird innerhalb \DescRef{\LabelBase.cmd.listoftoc} (siehe \autoref{sec:tocbasic.toc}, \DescPageRef{\LabelBase.cmd.listoftoc}) entsprechend der Eigenschaft \PValue{numberline} (siehe \autoref{sec:tocbasic.toc}, \DescPageRef{\LabelBase.cmd.setuptoc}) umdefiniert. Dadurch wirkt sich das -Setzen oder Löschen dieser Eigenschaft bereits beim nächsten \LaTeX-Lauf aus.% +Setzen oder Löschen dieser Eigenschaft \iffree{bereits beim nächsten + \LaTeX-Lauf}{unmittelbar} % Umbruchvarianten +aus.% % \EndIndexGroup @@ -2017,21 +2069,30 @@ Setzen oder L \end{Declaration} Der\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} Verzeichniseintragsstil \PValue{tocline} (siehe \autoref{sec:tocbasic.tocstyle}) setzt am Ende jedes -Eintrags \Macro{penalty} so, dass nach einem Eintrag kein Seitenumbruch -erfolgen darf. Dabei wird der genaue Wert abhängig von der -\PName{Eintragsebene} gewählt. Dies erledigt -\Macro{tocbasic@SetPenaltyByTOCLevel}. Am Anfang eines Eintrags wird dann über -\Macro{tocbasic@DependOnPenaltyAndTOCLevel} abhängig von \Macro{lastpenalty} -und der aktuellen \PName{Eintragsebene} die über die Eigenschaften -\Option{onstartlowerlevel}, \Option{onstartsamelevel} oder -\Option{onstarthigherlevel} festgelegte Aktion eines der internen Makros -\Macro{scr@tso@\PName{Eintragsebene}@LastTOCLevelWasHigher}, -\Macro{scr@tso@\PName{Eintragsebene}@LastTOCLevelWasSame} oder -\Macro{scr@tso@\PName{Eintragsebene}@LastTOCLevelWasLower} ausgeführt. In der -Voreinstellung erlauben die ersten beiden einen Umbruch, wenn sie im -vertikalen Modus ausgeführt werden. - -Entwickler, die eigene Stile kompatibel mit Stil \PValue{tocline} erstellen +Eintrags über \Macro{tocbasic@SetPenaltyByTOCLevel} \Macro{penalty} so, dass +nach einem Eintrag kein Seitenumbruch erfolgen darf. Der genaue Wert wird +dabei abhängig von der \PName{Eintragsebene} gewählt. + +% \begin{sloppypar} +\begingroup +\emergencystretch=2em +Über \Macro{tocbasic@DependOnPenaltyAndTOCLevel} wird am Anfang eines +Eintrags, abhängig von \Macro{lastpenalty} und der \PName{Eintragsebene} die +über die Eigenschaft \Option{onstartlowerlevel} im internen Makro +\Macro{scr@tso@\PName{Eintragsebene}@LastTOCLevelWasHigher}, über die +\iffree{Eigenschaft}{Ei\-genschaft} +\Option{onstartsamelevel} im zugehörigen, internen +Makro\iffree{ +}{\linebreak}\Macro{scr@tso@\PName{Eintragsebene}@LastTOCLevelWasSame} oder +über die Eigenschaft \Option{onstarthigherlevel} im zugehörigen, internen +Makro \Macro{scr@tso@\PName{Eintragsebene}@LastTOCLevelWasLower} gespeicherte +Aktion ausgeführt. In der Voreinstellung\textnote{Voreinstellung} erlauben die +ersten beiden einen Umbruch, wenn sie im vertikalen Modus ausgeführt +werden.\par +\endgroup +%\end{sloppypar} + +Entwicklern, die eigene Stile kompatibel mit \PValue{tocline} erstellen wollen, sei empfohlen, dieses Verhalten zu kopieren. Zu diesem Zweck dürfen sie auf diese eigentlich internen Makros zurückgreifen.% \EndIndexGroup @@ -2052,30 +2113,27 @@ verwendet werden m Als\textnote{Umgebung} erstes wird eine Umgebung benötigt, die diese neue Gleitumgebung bereitstellt. Das geht ganz einfach mit: -% Umbruchkorrektur: listings korrigiert! \begin{lstcode} - \newenvironment{remarkbox}{% - \@float{remarkbox}% - }{% - \end@float - } + \newenvironment{remarkbox}% + {\@float{remarkbox}}% + {\end@float} \end{lstcode} Die neue Umgebung heißt also \Environment{remarkbox}. Jede\textnote{Platzierung} Gleitumgebung hat eine Standardplatzierung. Diese -setzt sich aus den bekannten Platzierungsoptionen zusammen: -% Umbruchkorrektur: listings korrigiert! +setzt sich aus einer oder mehreren der bekannten Platzierungsoptionen +\PValue{b}, \PValue{h}, \PValue{p} und \PValue{t} zusammen: \begin{lstcode} \newcommand*{\fps@remarkbox}{tbp} \end{lstcode} Die neue Gleitumgebung soll also in der Voreinstellung nur oben, unten oder auf einer eigenen Seite platziert werden dürfen. -Gleitumgebungen\textnote{Gleittyp} haben außerdem einen nummerischen -Gleittyp. Umgebungen, bei denen das gleiche Bit im Gleittyp gesetzt ist, -dürfen sich nicht gegenseitig überholen. Abbildungen und Tabellen haben -normalerweise den Typ~1 und 2. Sie dürfen sich also gegenseitig überholen. -% Umbruchkorrektur: listings korrigiert! +Gleitumgebungen\textnote{Gleittyp} haben außerdem einen nummerischen Gleittyp +zwischen 1 und 31. Umgebungen, bei denen das gleiche Bit +im Gleittyp gesetzt ist, dürfen sich nicht gegenseitig überholen. Abbildungen +und Tabellen haben normalerweise den Typ~1 und 2. Abbildungen dürfen also +Tabellen überholen und umgekehrt. \begin{lstcode} \newcommand*{\ftype@remarkbox}{4} \end{lstcode} @@ -2083,11 +2141,11 @@ Die neue Umgebung hat den Typ~4, darf also Tabellen und Abbildungen und von diesen überholt werden. Gleitumgebungen\textnote{Nummer} haben außerdem eine Nummer. -% Umbruchkorrektur: listings korrigiert! \begin{lstcode} \newcounter{remarkbox} \newcommand*{\remarkboxformat}{% - Merksatz~\theremarkbox\csname autodot\endcsname} + Merksatz~\theremarkbox\csname autodot\endcsname + } \newcommand*{\fnum@remarkbox}{\remarkboxformat} \end{lstcode} Hier wird zunächst ein neuer Zähler definiert, der unabhängig von Kapiteln @@ -2099,7 +2157,6 @@ Ausgabe wird wiederum als Gleitumgebungsnummer f Gleitumgebungen\textnote{Dateierweiterung} haben Verzeichnisse und diese haben eine Datei mit dem Namen \Macro{jobname} und einer Dateierweiterung. -% Umbruchkorrektur: listings korrigiert! \begin{lstcode} \newcommand*{\ext@remarkbox}{lor} \end{lstcode} @@ -2109,12 +2166,10 @@ Die\important{\Package{tocbasic}} Umgebung selbst steht damit. Es fehlt allerdings das Verzeichnis. Damit wir dabei möglichst wenig selbst machen müssen, verwenden wir das Paket \Package{tocbasic}. Dieses wird in Dokumenten mit -% Umbruchkorrektur: listings korrigiert! \begin{lstcode} \usepackage{tocbasic} \end{lstcode} geladen. Ein Klassen- oder Paketautor würde hingegen -% Umbruchkorrektur: listings korrigiert! \begin{lstcode} \RequirePackage{tocbasic} \end{lstcode} @@ -2122,7 +2177,6 @@ verwenden. Nun\textnote{Dateierweiterung} machen wir die neue Dateierweiterung dem Paket \Package{tocbasic} bekannt. -% Umbruchkorrektur: listings korrigiert! \begin{lstcode} \addtotoclist[float]{lor} \end{lstcode} @@ -2132,7 +2186,6 @@ von Gleitumgebungen beziehen, auch auf das neue Verzeichnis beziehen. Jetzt\textnote{Verzeichnistitel} definieren wir noch einen Titel für dieses Verzeichnis: -% Umbruchkorrektur: listings korrigiert! \begin{lstcode} \newcommand*{\listoflorname}{Verzeichnis der Merksätze} \end{lstcode} @@ -2144,22 +2197,20 @@ will. Siehe dazu \autoref{sec:scrbase.languageSupport}, ab Jetzt\textnote{Verzeichniseintrag}\index{Verzeichnis>Eintrag} müssen wir nur noch definieren, wie ein einzelner Eintrag in dem Verzeichnis aussehen soll: -% Umbruchkorrektur: listings korrigiert! \begin{lstcode} \newcommand*{\l@remarkbox}{\l@figure} \end{lstcode} Weil das die einfachste Lösung ist, wurde hier festgelegt, dass Einträge in das Verzeichnis der Merksätze genau wie Einträge in das Abbildungsverzeichnis aussehen sollen. Man hätte auch eine explizite Festlegung wie -% Umbruchkorrektur: listings korrigiert! \begin{lstcode} - \newcommand*{\l@remarkbox}{\@dottedtocline{1}{1em}{1.5em}} + \DeclareTOCStyleEntry[level=1,indent=1em,numwidth=1.5em]% + {tocline}{remarkbox} \end{lstcode} verwenden können. -Außerdem\textnote{Kapiteleintrag} wollen Sie, das Kapiteleinträge sich auf das +Außerdem\textnote{Kapiteleintrag} wollen Sie, dass sich Kapiteleinträge auf das Verzeichnis auswirken. -% Umbruchkorrektur: listings korrigiert! \begin{lstcode} \setuptoc{lor}{chapteratlist} \end{lstcode} @@ -2174,7 +2225,6 @@ Inhaltsverzeichniseintrag, mit Inhaltsverzeichniseintrag, mit Nummerierung) wählen und das Verzeichnis mit \DescRef{\LabelBase.cmd.listoftoc}\PParameter{lor} ausgeben. Mit einem schlichten -% Umbruchkorrektur: listings korrigiert! \begin{lstcode} \newcommand*{\listofremarkboxes}{\listoftoc{lor}} \end{lstcode} @@ -2200,12 +2250,16 @@ dass der Anwender automatisch von etwaigen zuk \Package{tocbasic} profitiert. Soll der Anwender aber nicht mit der Tatsache belastet werden, dass für die Merksätze die Dateierweiterung \File{lor} verwendet wird, so genügt -% Umbruchkorrektur: listings korrigiert! \begin{lstcode} \newcommand*{\setupremarkboxes}{\setuptoc{lor}} \end{lstcode} +\iffalse% um eine als Argument an \Macro{setupremarkboxes} übergebene Liste von -Eigenschaften direkt als Liste von Eigenschaften für \File{lor} zu setzen. +Eigenschaften direkt als Liste von % +\else% +um über \Macro{setupremarkboxes} +\fi +Eigenschaften für \File{lor} zu setzen. \section{Alles mit einer Anweisung} @@ -2213,7 +2267,7 @@ Eigenschaften direkt als Liste von Eigenschaften f Das Beispiel aus dem vorherigen Abschnitt hat gezeigt, dass es mit mit \Package{tocbasic} recht einfach ist, eigene Gleitumgebungen mit eigenen -Verzeichnissen zu definieren. In diesem Beispiel wird gezeigt, dass es sogar +Verzeichnissen zu definieren. In diesem Abschnitt wird gezeigt, dass es sogar noch einfacher gehen kann. \begin{Declaration} @@ -2236,8 +2290,9 @@ k \PName{Dateierweiterung} definiert dabei die Dateiendung der Hilfsdatei, die das Verzeichnis repräsentiert, wie dies in \autoref{sec:tocbasic.basics}, ab -\autopageref{sec:tocbasic.basics} bereits erläutert wurde. Dieser Parameter -muss angegeben werden und darf nicht leer sein! +\autopageref{sec:tocbasic.basics} bereits erläutert +wurde. Dieser\textnote{Achtung!} Parameter muss angegeben werden und darf +nicht leer sein! \PName{Optionenliste} ist eine durch Komma getrennte Liste, wie dies auch von \DescRef{maincls.cmd.KOMAoptions} (siehe \autoref{sec:typearea.options}, @@ -2245,145 +2300,30 @@ muss angegeben werden und darf nicht leer sein! Optionen\textnote{Achtung!} können jedoch \emph{nicht} mit \DescRef{maincls.cmd.KOMAoptions}\IndexCmd{KOMAoptions} gesetzt werden! Eine Übersicht über die möglichen Optionen bietet -\autoref{tab:tocbasic.DeclareNewTOC-options} ab -\autopageref{tab:tocbasic.DeclareNewTOC-options}. +\autoref{tab:tocbasic.DeclareNewTOC-options}\iffalse ab +\autopageref{tab:tocbasic.DeclareNewTOC-options}\fi. Wird\ChangedAt[2015/12]{v3.20}{\Package{tocbasic}} Option \Option{tocentrystyle} nicht gesetzt, so wird bei Bedarf der Stil \PValue{default} verwendet. Näheres zu diesem Stil ist \autoref{sec:tocbasic.tocstyle} zu entnehmen. Soll kein Befehl für Verzeichniseinträge definiert werden, so kann ein leeres Argument, also -wahlweise \OptionValue{tocentrystyle}{} oder -\OptionValue{tocentrystyle}{\PParameter{}} verwendet werden. Dies birgt -allerdings das Risiko, dass bei Ausgabe des entsprechenden Verzeichnisses -diverse Fehler gemeldet werden. +wahlweise \OptionValue{tocentrystyle}{}\iffree{}{\unskip} oder +\OptionValue{tocentrystyle}{\PParameter{}} verwendet werden. Abhängig\ChangedAt[2016/06]{v3.21}{\Package{tocbasic}} vom Stil der Verzeichniseinträge können auch alle für diesen Stil gültigen Eigenschaften gesetzt werden, indem die entsprechenden in \autoref{tab:tocbasic.tocstyle.attributes} ab -\autopageref{tab:tocbasic.tocstyle.attributes} aufgeführten Namen mit dem -Präfix \PValue{tocentry} versehen in der \PName{Optionenliste} angegeben +\autopageref{tab:tocbasic.tocstyle.attributes} aufgeführten Namen, mit dem +Präfix \PValue{tocentry} versehen, in der \PName{Optionenliste} angegeben werden. Nachträgliche Änderungen am Stil sind mit \DescRef{\LabelBase.cmd.DeclareTOCStyleEntry}% \IndexCmd{DeclareTOCStyleEntry}% \important{\DescRef{\LabelBase.cmd.DeclareTOCStyleEntry}} jederzeit möglich. Siehe dazu \autoref{sec:tocbasic.tocstyle}, \DescPageRef{\LabelBase.cmd.DeclareTOCStyleEntry}. -% -\begin{Example} - Das Beispiel aus \autoref{sec:tocbasic.example} kann mit Hilfe der neuen - Anweisung deutlich verkürzt werden: -\begin{lstcode} - \DeclareNewTOC[% - type=remarkbox,% - types=remarkboxes,% - float,% Gleitumgebungen sollen definiert werden. - floattype=4,% - name=Merksatz,% - listname={Verzeichnis der Merks\"atze}% - ]{lor} - \setuptoc{lor}{chapteratlist} -\end{lstcode} - Neben den Umgebungen \Environment{remarkbox} und \Environment{remarkbox*} - sind damit auch der Zähler \Counter{remarkbox}, die zur Ausgabe gehörenden - Anweisungen \Macro{theremarkbox}, \Macro{remarkboxname} und - \Macro{remarkboxformat}, die für das Verzeichnis benötigten - \Macro{listremarkboxname} und \Macro{listofremarkboxes} sowie einige intern - verwendete Anweisungen mit Bezug auf die Dateiendung \File{lor} - definiert. Soll der Gleitumgebungstyp dem Paket überlassen werden, so kann - Option \Option{floattype} im Beispiel entfallen. Wird zusätzlich - die Option \Option{nonfloat} angegeben, wird außerdem eine nicht gleitende - Umgebung \Environment{remarkbox-} definiert, in der ebenfalls - \DescRef{maincls.cmd.caption}\IndexCmd{caption} verwendet werden kann. - Zum besseren Verständnis zeigt \autoref{tab:tocbasic.comparison} eine - Gegenüberstellung der Anweisungen und Umgebungen für die neu erstellte - Beispielumgebung \Environment{remarkbox} mit den entsprechenden Befehlen und - Umgebungen für Abbildungen.% - \begin{table} - \centering - \caption{Gegenüberstellung von Beispielumgebung \Environment{remarkbox} - und Umgebung \Environment{figure}} - \label{tab:tocbasic.comparison} - \begin{tabularx}{\textwidth}{l@{\hskip\tabcolsep}l@{\hskip\tabcolsep}>{\raggedright}p{7em}@{\hskip\tabcolsep}X} - \toprule - \begin{tabular}[t]{@{}l@{}} - Umgebung\\ - \Environment{remarkbox} - \end{tabular} - & \begin{tabular}[t]{@{}l@{}} - Umgebung\\ - \Environment{figure} - \end{tabular} - & Optionen von \Macro{DeclareNewTOC} & Kurzbeschreibung \\[1ex] - \midrule - \Environment{remarkbox} & \Environment{figure} - & \Option{type}, \Option{float} - & Gleitumgebung des jeweiligen Typs.\\[1ex] - \Environment{remarkbox*} & \Environment{figure*} - & \Option{type}, \Option{float} - & spaltenübergreifende Gleitumgebung des jeweiligen Typs \\[1ex] - \Counter{remarkbox} & \Counter{figure} - & \Option{type}, \Option{float} - & Zähler, der von \DescRef{maincls.cmd.caption} verwendet wird \\[1ex] - \Macro{theremarkbox} & \Macro{thefigure} - & \Option{type}, \Option{float} - & Anweisung zur Ausgabe des jeweiligen Zählers \\[1ex] - \Macro{remarkboxformat} & \DescRef{maincls.cmd.figureformat} - & \Option{type}, \Option{float} - & Anweisung zur Formatierung des jeweiligen Zählers in der Ausgabe von - \DescRef{maincls.cmd.caption}\\[1ex] - \Macro{remarkboxname} & \Macro{figurename} - & \Option{type}, \Option{float}, \Option{name} - & Name, der im Label von \DescRef{maincls.cmd.caption} verwendet - wird\\[1ex] - \Macro{listofremarkboxes} & \DescRef{maincls.cmd.listoffigures} - & \Option{types}, \Option{float} - & Anweisung zur Ausgabe des jeweiligen Verzeichnisses \\[1ex] - \Macro{listremarkboxname} & \Macro{listfigurename} - & \Option{type}, \Option{float}, \Option{listname} - & Überschrift des jeweiligen Verzeichnisses \\[1ex] - \Macro{fps@remarkbox} & \Macro{fps@figure} - & \Option{type}, \Option{float}, \Option{floattype} - & nummerischer Gleitumge\-bungstyp zwecks - Reihen\-fol\-gen\-erhalts\\[1ex] - \File{lor} & \File{lof} - & - & Dateiendung der Hilfsdatei für das jeweilige Verzeichnis \\ - \bottomrule - \end{tabularx} - \end{table} - - Und hier nun eine mögliche Verwendung der Umgebung: -\begin{lstcode} - \begin{remarkbox} - \centering - Gleiches sollte immer auf gleiche Weise und - mit gleichem Aussehen gesetzt werden. - \caption{Erster Hauptsatz der Typografie} - \label{rem:typo1} - \end{remarkbox} -\end{lstcode} - Ein Ausschnitt aus einer Beispielseite mit dieser Umgebung könnte dann so - aussehen: - \begin{center}\footnotesize - \begin{tabular} - {|!{\hspace{.1\linewidth}}p{.55\linewidth}!{\hspace{.1\linewidth}}|} - \\ - \centering - Gleiches sollte immer auf gleiche Weise und - mit gleichem Aussehen gesetzt werden.\\[\abovecaptionskip] - {% - \usekomafont{caption}\footnotesize - \begin{tabularx}{\hsize}[t]{@{}l@{ }X@{}} - \usekomafont{captionlabel}{Merksatz 1:} & - Erster Hauptsatz der Typografie \\ - \end{tabularx} - }\\ - \end{tabular}% - \end{center}% -\end{Example}% % Umbruchoptimierung: Tabelle verschoben. \begin{desclist} \renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% @@ -2410,7 +2350,7 @@ m \Counter{\PName{Eintragstyp}} (siehe Option \Option{type}) angelegt. Dieser Zähler kann in gleicher Weise wie beispielsweise der Zähler \Counter{figure} bei \Class{book}-Klassen von Zähler - \Counter{chapter} abhängt von einem \LaTeX-Zähler ahängig gemacht + \Counter{chapter} abhängt, von einem \LaTeX-Zähler ahängig gemacht werden.}% \entry{\Option{float}}{% Es wird nicht nur ein neuer Verzeichnistyp definiert, sondern auch @@ -2481,7 +2421,7 @@ m Jedes Verzeichnis hat eine Überschrift, die durch diese Option bestimmt werden kann. Ist die Option nicht angegeben, so wird als Verzeichnistitel »\texttt{List of \PName{Mehrzahl des Eintragstyps}}« (siehe Option - \PName{types}) verwendet, wobei das erste Zeichen der \PName{Mehrzahl des + \Option{types}) verwendet, wobei das erste Zeichen der \PName{Mehrzahl des Eintragstyps} in einen Großbuchstaben gewandelt wird. Es wird auch ein Makro \Macro{list\PName{Eintragstyp}name} mit diesem Wert definiert, der jederzeit geändert werden kann. Dieses Makro wird jedoch nur definiert, @@ -2503,16 +2443,24 @@ m Es wird nicht nur ein neuer Verzeichnistyp definiert, sondern auch eine nicht gleitende Umgebungen \Environment{\PName{Eintragstyp}-} (siehe Option \Option{type}), die ähnlich wie eine Gleitumgebung verwendet werden - kann, jedoch nicht gleitet und auch nicht die Grenzen der aktuell gültigen - Umgebung durchbricht.}% + kann, jedoch nicht gleitet und auch nicht die Grenzen der Umgebung, in der + sie verwendet wird, durchbricht.}% \entry{\OptionVName{owner}{Besitzer}}{% Jedes neue Verzeichnis hat bei \Package{tocbasic} einen Besitzer (siehe \autoref{sec:tocbasic.basics}). Dieser kann hier angegeben werden. Ist kein Besitzer angegeben, so wird der Besitzer »\PValue{float}« verwendet, den auch die \KOMAScript-Klassen für das Abbildungs- und das Tabellenverzeichnis verwenden.}% + \entry{\OptionVName{setup}{Liste von Eigenschaften}}{% + \ChangedAt{v3.25}{\Package{tocbasic}}% + Die \PName{Liste von Eigenschaften} wird via + \DescRef{\LabelBase.cmd.setuptoc} gesetzt. Es wird darauf hingewiesen, + dass für die Angabe mehrerer durch Komma getrennter Eigenschaften die + \PName{Liste von Eigenschaften} in geschweifte Klammern gesetzt werden + muss.% + }% \entry{\OptionVName{tocentrystyle}{Eintragsstil}}{% - \ChangedAt[2015/12]{v3.20}{\Package{tocbasic}}% + \ChangedAt{v3.20}{\Package{tocbasic}}% \PName{Eintragsstil} gibt den Stil an, den Einträge in das entsprechende Verzeichnis haben sollen. Der Name der Eintragsebene wird dabei über Option \Option{type} bestimmt. Zusätzlich zu den Optionen dieser Tabelle @@ -2543,16 +2491,140 @@ m An verschiedenen Stellen wird auch die Mehrzahlform des Eintragstyps verwendet, beispielsweise um eine Anweisung \Macro{listof\PName{Mehrzahl des Eintragstyps}} zu definieren. Wird diese Option nicht verwendet, - so wird als \PName{Mehrzahl des Eintragstyps} einfach - »\PName{Eintragstyp}s« verwendet.}% + so wird als \PName{Mehrzahl des Eintragstyps} der Wert von + \Option{type} mit angehängtem »s« verwendet.}% + \entry{\OptionVName{unset}{Liste von Eigenschaften}}{% + \ChangedAt{v3.25}{\Package{tocbasic}}% + Die \PName{Liste von Eigenschaften} wird via + \DescRef{\LabelBase.cmd.unsettoc} aufgehoben. Es wird darauf hingewiesen, + dass für die Angabe mehrerer durch Komma getrennter Eigenschaften die + \PName{Liste von Eigenschaften} in geschweifte Klammern gesetzt werden + muss.% + }% \end{desclist} -Benutzer von \Package{hyperref}\IndexPackage{hyperref} sollten Option -\Option{listname} übrigens immer angeben. Anderenfalls kommt es in der Regel -zu einer Fehlermeldung, weil \Package{hyperref} nicht mit dem -\Macro{MakeUppercase} im Namen des Verzeichnisses zurecht kommt, das benötigt -wird, um den ersten Buchstaben des Wert von \Option{types} in Großbuchstaben -zu wandeln.% +\begin{Example} + Das Beispiel aus \autoref{sec:tocbasic.example} kann mit Hilfe der neuen + Anweisung deutlich verkürzt werden: +\begin{lstcode} + \DeclareNewTOC[% + type=remarkbox,% + types=remarkboxes,% + float,% Gleitumgebungen sollen definiert werden. + floattype=4,% + name=Merksatz,% + listname={Verzeichnis der Merks\"atze}% + ]{lor} + \setuptoc{lor}{chapteratlist} +\end{lstcode} + Neben den Umgebungen \Environment{remarkbox} und \Environment{remarkbox*} + sind damit auch der Zähler \Counter{remarkbox}, die zur Ausgabe gehörenden + Anweisungen \Macro{theremarkbox}, \Macro{remarkboxname} und + \Macro{remarkboxformat}, die für das Verzeichnis benötigten + \Macro{listremarkboxname} und \Macro{listofremarkboxes} sowie einige intern + verwendete Anweisungen mit Bezug auf die Dateiendung \File{lor} + definiert. Soll der Gleitumgebungstyp dem Paket überlassen werden, so kann + Option \Option{floattype} im Beispiel entfallen. Wird zusätzlich + die Option \Option{nonfloat} angegeben, wird außerdem eine nicht gleitende + Umgebung \Environment{remarkbox-} definiert, in der ebenfalls + \DescRef{maincls.cmd.caption}\IndexCmd{caption} verwendet werden kann. + + Zum besseren Verständnis zeigt \autoref{tab:tocbasic.comparison} eine + Gegenüberstellung der Anweisungen und Umgebungen für die neu erstellte + Beispielumgebung \Environment{remarkbox} mit den entsprechenden Befehlen und + Umgebungen für Abbildungen.% + \begin{table} + \centering + \caption{Gegenüberstellung von Beispielumgebung \Environment{remarkbox} + und Umgebung \Environment{figure}} + \label{tab:tocbasic.comparison} + \begin{tabularx}{\textwidth}{l@{\hskip\tabcolsep}l@{\hskip\tabcolsep}>{\raggedright}p{7em}@{\hskip\tabcolsep}X} + \toprule + \begin{tabular}[t]{@{}l@{}} + Umgebung\\ + \Environment{remarkbox} + \end{tabular} + & \begin{tabular}[t]{@{}l@{}} + Umgebung\\ + \Environment{figure} + \end{tabular} + & Optionen von \Macro{DeclareNewTOC} & Kurzbeschreibung \\[1ex] + \midrule + \Environment{remarkbox} & \Environment{figure} + & \Option{type}, \Option{float} + & Gleitumgebung des jeweiligen Typs.\\[1ex] + \Environment{remarkbox*} & \Environment{figure*} + & \Option{type}, \Option{float} + & spaltenübergreifende Gleitumgebung des jeweiligen Typs \\[1ex] + \Counter{remarkbox} & \Counter{figure} + & \Option{type}, \Option{float} + & Zähler, der von \DescRef{maincls.cmd.caption} verwendet wird \\[1ex] + \Macro{theremarkbox} & \Macro{thefigure} + & \Option{type}, \Option{float} + & Anweisung zur Ausgabe des jeweiligen Zählers \\[1ex] + \Macro{remarkboxformat} & \DescRef{maincls.cmd.figureformat} + & \Option{type}, \Option{float} + & Anweisung zur Formatierung des jeweiligen Zählers in der Ausgabe von + \DescRef{maincls.cmd.caption}\\[1ex] + \Macro{remarkboxname} & \Macro{figurename} + & \Option{type}, \Option{float}, \Option{name} + & Name, der im Label von \DescRef{maincls.cmd.caption} verwendet + wird\\[1ex] + \Macro{listofremarkboxes} & \DescRef{maincls.cmd.listoffigures} + & \Option{types}, \Option{float} + & Anweisung zur Ausgabe des jeweiligen Verzeichnisses \\[1ex] + \Macro{listremarkboxname} & \Macro{listfigurename} + & \Option{type}, \Option{float}, \Option{listname} + & Überschrift des jeweiligen Verzeichnisses \\[1ex] + \Macro{fps@remarkbox} & \Macro{fps@figure} + & \Option{type}, \Option{float}, \Option{floattype} + & nummerischer Gleitumge\-bungstyp zwecks + Reihen\-fol\-gen\-erhalts\\[1ex] + \File{lor} & \File{lof} + & + & Dateiendung der Hilfsdatei für das jeweilige Verzeichnis \\ + \bottomrule + \end{tabularx} + \end{table} + + Und hier nun eine mögliche Verwendung der Umgebung: +\begin{lstcode} + \begin{remarkbox} + \centering + Gleiches sollte immer auf gleiche Weise und + mit gleichem Aussehen gesetzt werden. + \caption{Erster Hauptsatz der Typografie} + \label{rem:typo1} + \end{remarkbox} +\end{lstcode} + Ein Ausschnitt aus einer Beispielseite mit dieser Umgebung könnte dann so + aussehen: + \begin{center}\footnotesize + \begin{tabular} + {|!{\hspace{.1\linewidth}}p{.55\linewidth}!{\hspace{.1\linewidth}}|} + \\ + \centering + Gleiches sollte immer auf gleiche Weise und + mit gleichem Aussehen gesetzt werden.\\[\abovecaptionskip] + {% + \usekomafont{caption}\footnotesize + \begin{tabularx}{\hsize}[t]{@{}l@{ }X@{}} + \usekomafont{captionlabel}{Merksatz 1:} & + Erster Hauptsatz der Typografie%\\ + \end{tabularx}% + }% + \\ + \end{tabular}% + \end{center}% +\end{Example}% + +Benutzer von +\Package{hyperref}\IndexPackage{hyperref}\important{\Package{hyperref}} +sollten Option \Option{listname} übrigens immer angeben. Anderenfalls kommt es +in der Regel zu einer Fehlermeldung, weil \Package{hyperref} nicht mit dem +\Macro{MakeUppercase}\IndexCmd{MakeUppercase} im Namen des Verzeichnisses +zurecht kommt, das benötigt wird, um den ersten Buchstaben des Wertes von +\Option{types} in Großbuchstaben zu wandeln.% \EndIndexGroup % \EndIndexGroup @@ -2568,7 +2640,6 @@ zu wandeln.% %%% End: % LocalWords: Verzeichnisdatei Klonquelle Absatzabstandes Absatzabstand - % LocalWords: Verzeichniseinträge Verzeichniseintrag Eintragsstile % LocalWords: Inhaltsverzeichniseinträge Standardklassen Nummernbreite % LocalWords: Standardeigenschaft Eintragsebene Optionenliste expandierbar @@ -2578,4 +2649,6 @@ zu wandeln.% % LocalWords: Eintragsnummer Initialisierungscode Aktivierungswerte % LocalWords: Deaktivierungswert Verzeichnistitel Eintragstyp Eintragstyps % LocalWords: Verzeichniseintrags Säumniswert Überschriftenanweisung -% LocalWords: Eintragstext +% LocalWords: Eintragstext Dateierweiterung Dateierweiterungen Paketautoren +% LocalWords: Verzeichnisbefehle Verzeichnisdaten Schrifteinstellungen +% LocalWords: Eintragsebenen Platzierungsoptionen Kapiteleinträge diff --git a/Master/texmf-dist/source/latex/koma-script/doc/ngerman/typearea-experts.tex b/Master/texmf-dist/source/latex/koma-script/doc/ngerman/typearea-experts.tex index 933d3d458ad..9b071f0edd3 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/ngerman/typearea-experts.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/ngerman/typearea-experts.tex @@ -1,6 +1,6 @@ % ====================================================================== % typearea-experts.tex -% Copyright (c) Markus Kohm, 2008-2017 +% Copyright (c) Markus Kohm, 2008-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % typearea-experts.tex -% Copyright (c) Markus Kohm, 2008-2017 +% Copyright (c) Markus Kohm, 2008-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,26 +46,26 @@ % ====================================================================== \KOMAProvidesFile{typearea-experts.tex} - [$Date: 2017-04-13 09:47:38 +0200 (Thu, 13 Apr 2017) $ + [$Date: 2018-01-31 09:49:41 +0100 (Wed, 31 Jan 2018) $ KOMA-Script guide (chapter: typearea for experts)] \chapter{Zusätzliche Informationen zum Paket \Package{typearea.sty}} \labelbase{typearea-experts} -\BeginIndexGroup -\BeginIndex{Package}{typearea} -In diesem Kapitel finden Sie zusätzliche Informationen zum Paket -\Package{typearea}. \iffree{Einige Teile des Kapitels sind dabei dem - \KOMAScript-Buch \cite{book:komascript} vorbehalten. Dies sollte kein - Problem sein, denn der}{Der} normale Anwender, der das Paket einfach nur -verwenden will, wird diese Informationen normalerweise nicht benötigen. Ein -Teil der Informationen richtet sich an Anwender, die ausgefallene Aufgaben -lösen oder eigene Pakete schreiben wollen, die auf \Package{typearea} -basieren. Ein weiterer Teil der Informationen behandelt Möglichkeiten von -\Package{typearea}, die aus Gründen der Kompatibilität zu den Standardklassen -oder früheren Versionen von \KOMAScript{} existieren. Die Teile, die nur aus -Gründen der Kompatibilität zu früheren Versionen von \KOMAScript{} existieren, -sind in serifenloser Schrift gesetzt und sollten nicht mehr verwendet werden. +\BeginIndexGroup \BeginIndex{Package}{typearea} In diesem Kapitel finden Sie +zusätzliche Informationen zum Paket +\hyperref[cha:typearea]{\Package{typearea}}. \iffree{Einige Teile des Kapitels + sind dabei dem \KOMAScript-Buch \cite{book:komascript} vorbehalten. Dies + sollte kein Problem sein, denn der}{Der} normale Anwender, der das Paket +einfach nur verwenden will, wird diese Informationen eher selten +benötigen. Ein Teil der Informationen richtet sich an Anwender, die +ausgefallene Aufgaben lösen oder eigene Pakete schreiben wollen, die auf +\Package{typearea} basieren. Ein weiterer Teil der Informationen behandelt +Möglichkeiten von \Package{typearea}, die aus Gründen der Kompatibilität zu +den Standardklassen oder früheren Versionen von \KOMAScript{} existieren. Die +Teile, die nur aus Gründen der Kompatibilität zu früheren Versionen von +\KOMAScript{} existieren, sind in serifenloser Schrift gesetzt und sollten +nicht mehr verwendet werden. \section{Experimentelle Möglichkeiten} @@ -86,19 +86,19 @@ Normalerweise k einer Konstellation zusammen mit dem Paket \Package{geometry}\IndexPackage{geometry} (siehe \cite{package:geometry}) verwendet wird. Das bedeutet insbesondere, dass \Package{geometry} nach wie -vor nichts davon mit bekommt, wenn man mit \Package{typearea} beispielsweise +vor nichts davon mitbekommt, wenn man mit \Package{typearea} beispielsweise die Papiergröße ändert -- etwas, das \Package{geometry} selbst gar nicht bietet. Sobald\ChangedAt{v3.17}{\Package{typearea}} Option \Option{usegeometry} -gesetzt wird versucht \Package{typearea} alle eigenen Optionen auch in -Optionen für \Package{geometry} zu übersetzen und innerhalb des Dokuments wird -sogar \Macro{newgeometry} aufgerufen, wenn neue Parameter aktiviert werden -(siehe \DescRef{\LabelBase.cmd.activateareas} im nachfolgenden Abschnitt). Da -\Package{geometry} keine Änderung der Papiergröße oder Papierausrichtung via -\Macro{newgeometry} bietet, wird diese bei Bedarf über interne Anweisungen und -Längen von \Package{geometry} umgesetzt. Getestet ist dies für -\Package{geometry}~5.3 bis 5.6. +gesetzt wird, versucht \Package{typearea}, alle eigenen Optionen für +\Package{geometry} in dessen Optionen zu übersetzen. Innerhalb des Dokuments +wird sogar \Macro{newgeometry} aufgerufen, wenn neue Parameter aktiviert +werden (siehe \DescRef{\LabelBase.cmd.activateareas} im nachfolgenden +Abschnitt). Da \Package{geometry} keine Änderung der Papiergröße oder +Papierausrichtung via \Macro{newgeometry} bietet, wird diese bei Bedarf über +interne Anweisungen und Längen von \Package{geometry} umgesetzt. Getestet ist +dies für \Package{geometry}~5.3 bis 5.6. Die Option bedeutet übrigens nicht, dass bei Verwendung von \Package{geometry} nach einer Papiergrößen- oder Papierausrichtungsänderung mit @@ -108,11 +108,21 @@ Papiereinstellung bietet, als f Kopf, Fuß etc. benötigt werden -- man spricht von \emph{Überbestimmung} -- und gleichzeitig bei neuen Aufrufen von \Macro{newgeometry} fehlende Angaben aus bereits bekannten ableitet -- man spricht von \emph{Werterhalt} --, -muss man gegebenenfalls durch explizite vollständige Bestimmung neuer Werte +muss man gegebenenfalls durch vollständige Bestimmung neuer Werte bei einem eigenen Aufruf von \Macro{newgeometry} alle gewünschten Einstellungen explizit vornehmen. Nichts desto Trotz kann die Berücksichtigung von \Package{geometry} durch \Package{typearea} zusätzliche Möglichkeiten -eröffnen.% +eröffnen. + +{\setlength{\emergencystretch}{1em}% +Von \Package{typearea} werden mit \Option{usegeometry} für \Package{geometry} +derzeit die Optionen +\Option{bindingoffset}, \Option{footskip}, \Option{headheight}, +\Option{headsep}, \Option{includefoot}, \Option{includehead}, +\Option{includemp}, \Option{lmargin}, \Option{marginparsep}, +\Option{marginparwidth}, \Option{textheight}, \Option{textwidth}, \Option{top} +und in der Dokumentpräambel zusätzlich \Option{paperheight} und +\Option{paperwidth} gesetzt.\par}% \EndIndexGroup @@ -142,8 +152,8 @@ verschoben sein.% In diesem Abschnitt werden Anweisungen beschrieben, die für den normalen Anwender kaum oder gar nicht von Interesse sind. Experten bieten diese -Anweisungen zusätzliche Möglichkeiten. Da die Beschreibungen für Experten -gedacht sind, sind sie kürzer gefasst. +Anweisungen zusätzliche Möglichkeiten.\iffree{ Da die Beschreibungen für + Experten gedacht sind, sind sie kürzer gefasst.}{} \begin{Declaration} \Macro{activateareas} @@ -183,7 +193,7 @@ Einstellungen wieder zu reaktivieren. Sie wollen in einem Dokument im Hochformat eine Seite im Querformat unterbringen. Mit \Macro{storeareas} kein Problem: \begin{lstcode} - \documentclass[pagesize]{scrartcl} + \documentclass{scrartcl} \begin{document} \noindent\rule{\textwidth}{\textheight} @@ -205,11 +215,11 @@ Einstellungen wieder zu reaktivieren. \DescRef{maincls.cmd.cleardoubleoddpage}\IndexCmd{cleardoubleoddpage} oder -- wenn keine \KOMAScript-Klasse zum Einsatz kommt -- \DescRef{maincls.cmd.cleardoublepage}\IndexCmd{cleardoublepage} verwendet - werden. + werden.% + \iffree{\par Außerdem wird \Macro{noindent} verwendet, um den normalen + Absatzeinzug vor den schwarzen Kästen zu verhindern. Sie würden sonst kein + korrektes Bild des Seitenlayouts wiedergeben.}{}% \end{Example} -Im Beispiel wird \Macro{noindent} verwendet, um den normalen Absatzeinzug vor -den schwarzen Kästen zu verhindern. Sie würden sonst kein korrektes Bilde des -Seitenlayouts wiedergeben. Bei\textnote{Achtung!} der Verwendung von \Macro{storeareas} ist zu beachten, dass sowohl \Macro{storeareas} als auch die damit definierte \PName{Anweisung} @@ -219,7 +229,7 @@ nicht innerhalb einer Gruppe aufgerufen werden sollten. Die Definition der erneuter Verwendung einer bereits definierten \PName{Anweisung} wird eine entsprechende Fehlermeldung ausgegeben. -Oftmals\ChangedAt{v3.18}{\Package{typearea}} ist es auch erwünscht, vor der +Oftmals\ChangedAt{v3.18}{\Package{typearea}} ist auch erwünscht, vor der Wiederherstellung der Einstelllungen per \PName{Anweisung} grundsätzlich bestimmte Aktionen wie beispielsweise ein \DescRef{maincls.cmd.cleardoubleoddpage} auszuführen. Dies kann man mit Hilfe @@ -244,7 +254,7 @@ auswirkt.% Diese Anweisungen dienen der Verwaltung zweier Haken\Index{Haken} (engl. \emph{hooks}\Index{hook=\emph{hook}}). Die ersten beiden, \Macro{AfterCalculatingTypearea} und deren Sternform, ermöglichen es dem -Experten jedes Mal, nachdem \Package{typearea} eine neue Aufteilung in +Experten jedes Mal, nachdem \Package{typearea} eine neue Auf"|teilung in Satzspiegel und Ränder berechnet hat, also nach jeder impliziten oder expliziten Ausführung von \DescRef{typearea.cmd.typearea}, \PName{Anweisungen} ausführen zu lassen. Entsprechendes leisten diff --git a/Master/texmf-dist/source/latex/koma-script/doc/ngerman/typearea.tex b/Master/texmf-dist/source/latex/koma-script/doc/ngerman/typearea.tex index 2d0e3d5eb15..0ff9dd4573a 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/ngerman/typearea.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/ngerman/typearea.tex @@ -1,6 +1,6 @@ % ====================================================================== % typearea.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % typearea.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -47,11 +47,13 @@ \KOMAProvidesFile{typearea.tex} - [$Date: 2017-08-08 11:47:52 +0200 (Tue, 08 Aug 2017) $ + [$Date: 2018-01-31 13:01:01 +0100 (Wed, 31 Jan 2018) $ KOMA-Script guide (chapter: typearea)] \chapter{Satzspiegelberechnung mit \Package{typearea.sty}} \labelbase{typearea} +\BeginIndexGroup% +\BeginIndex{Package}{typearea}% Viele \LaTeX-Klassen\iffree{, darunter auch die Standardklassen,}{} bieten dem Anwender eine weitgehend feste Auf"|teilung von Rändern und Textbereich. Bei den Standardklassen ist die konkrete Auf"|teilung in engen Grenzen von der @@ -88,10 +90,10 @@ Anwender erleichtern, eine gute Wahl zu treffen. Rändern« die Rede.}% \fi% , einem Kopfbereich, einem Textkörper und einem Fußbereich. Genauer - betrachtet kommt noch ein Abstand zwischen Kopfbereich und Textkörper sowie + betrachtet, kommt noch ein Abstand zwischen Kopfbereich und Textkörper sowie zwischen Textkörper und Fußbereich hinzu. Der Textkörper heißt in der Fachsprache der Typografen und Setzer \emph{Satzspiegel}. Die Auf"|teilung - dieser Bereiche, sowie ihre Anordnung zueinander und auf dem Papier nennen + dieser Bereiche sowie ihre Anordnung zueinander und auf dem Papier nennen wir \emph{Satzspiegeldefinition} oder \emph{Satzspiegelkonstruktion}.\Index[indexmain]{Satzspiegel} @@ -100,8 +102,8 @@ Anwender erleichtern, eine gute Wahl zu treffen. \iffree{ \cite{DANTE:TK0402:MJK}}{. Einen Überblick über einige Möglichkeiten und der dabei angenommenen Grundsätze gibt \autoref{cha:typeareaconstruction}}% - . Häufig findet man dabei ein Verfahren, das mit verschiedenen Diagonalen - und Schnittpunkten arbeitet. Das gewünschte Ergebnis dabei ist, dass das + . Häufig findet man ein Verfahren, das mit verschiedenen Diagonalen + und deren Schnittpunkten arbeitet. Das gewünschte Ergebnis ist, dass das Seitenverhältnis des Satzspiegels dem Seitenverhältnis \emph{der Seite} entspricht. Bei einem einseitigen\Index{einseitig} Dokument sollen außerdem der linke und der rechte Rand gleich breit sein, während der obere zum @@ -170,26 +172,28 @@ Anwender erleichtern, eine gute Wahl zu treffen. \Var{Bundsteg}\index{Bundsteg} \end{align*} }{% + % Umbruchkorrektur: Abstände verändert! \begin{prepareformargin} - \vskip-\baselineskip + \vskip -.5\baselineskip plus .25\baselineskip \begin{align*} \Var{Satzspiegelhöhe}\Index{Satzspiegel} : \Var{Satzspiegelbreite} &= \Var{Seitenhöhe}\Index{Seite} : \Var{Seitenbreite} \\ \Var{oberer~Rand}\Index{Rand} : \Var{unterer~Rand} &= - \text{1} : \text{2} \\ + \text{1} : \text{2} \\ \Var{linker~Rand} : \Var{rechter~Rand} &= \text{1} : \text{1} \\ - \Var{innerer~Randanteil} : \Var{äußerer~Rand} &= \text{1} : \text{2}\\ + \Var{innerer~Randanteil} : \Var{äußerer~Rand} &= + \text{1} : \text{2}\\ \Var{Seitenbreite} &= - \Var{Papierbreite}\Index{Papier} - - \Var{Bindekorrektur}\Index{Bindekorrektur} \\ + \Var{Papierbreite}\Index{Papier} - + \Var{Bindekorrektur}\Index{Bindekorrektur} \\ \Var{oberer~Rand} + \Var{unterer~Rand} &= - \Var{Seitenhöhe} - \Var{Satzspiegelhöhe} \\ + \Var{Seitenhöhe} - \Var{Satzspiegelhöhe} \\ % \Var{linker~Rand} + \Var{rechter Rand} &= - \Var{Seitenbreite} - \Var{Satzspiegelbreite} \\ + \Var{Seitenbreite} - \Var{Satzspiegelbreite} \\ % \Var{innerer Randanteil} + \Var{äußerer Rand} &= - \Var{Seitenbreite} - \Var{Satzspiegelbreite} \\ + \Var{Seitenbreite} - \Var{Satzspiegelbreite} \\ % % \end{align*} % \end{prepareformargin}\pagebreak @@ -199,6 +203,7 @@ Anwender erleichtern, eine gute Wahl zu treffen. \Var{Bundsteg}\index{Bundsteg} \end{align*} \end{prepareformargin} + \vskip .5\baselineskip minus .25\baselineskip }% \Index[indexmain]{Rand}% Dabei gibt es \Var{linker~Rand} und \Var{rechter~Rand} nur im einseitigen @@ -213,11 +218,16 @@ Anwender erleichtern, eine gute Wahl zu treffen. Die Frage nach der Breite des Satzspiegels wird in der Literatur ebenfalls diskutiert. Die optimale Satzspiegelbreite ist von verschiedenen Faktoren abhängig: - \begin{itemize} - \item Größe, Laufweite und Art der verwendeten Schrift - \item Verwendeter Durchschuss - \item Länge der Worte - \item Verfügbarer Platz + \iffree{\begin{itemize}}{\begin{itemize}[% Umbuchkorrektur + topsep=.5\baselineskip plus .25\baselineskip minus .33\baselineskip, + partopsep=.5\baselineskip plus .25\baselineskip minus .33\baselineskip, + itemsep=.33\baselineskip plus .25\baselineskip minus .25\baselineskip, + parsep=0pt + ]} + \item Größe, Laufweite und Art der verwendeten Schrift, + \item verwendeter Durchschuss, + \item Länge der Worte, + \item verfügbarer Platz. \end{itemize} Der Einfluss der Schrift wird deutlich, wenn man sich bewusst macht, wozu Serifen dienen. Serifen\Index[indexmain]{Serifen} sind kleine @@ -249,10 +259,10 @@ Anwender erleichtern, eine gute Wahl zu treffen. Zeilenlängen\Index[indexmain]{Zeilenlaenge=Zeilenlänge} findet man in der Literatur je nach Autor unterschiedliche Angaben. Teilweise ist dies auch in der Muttersprache des Autors begründet. Das Auge springt nämlich - üblicherweise von Wort zu Wort, wobei kurze Worte diese Aufgabe + üblicherweise von Wort zu Wort, wobei kurze Wörter diese Aufgabe erleichtern. Über alle Sprachen und Schriftarten hinweg kann man sagen, dass eine Zeilenlänge von 60 bis 70 Zeichen, einschließlich Leer- und - Satzzeichen, einen brauchbaren Kompromiss darstellen. Ein gut gewählter + Satzzeichen, einen brauchbaren Kompromiss darstellt. Ein gut gewählter Durchschuss wird dabei vorausgesetzt. Bei den Voreinstellungen von \LaTeX{} braucht man sich über Letzteres normalerweise keine Sorgen zu machen. Größere Zeilenlängen darf man nur Gewohnheitslesern zumuten, die @@ -292,14 +302,14 @@ Anwender erleichtern, eine gute Wahl zu treffen. \else Soweit die Grundlagen. \fi -\iftrue% Umbruchkorrektur +\iffalse% Umbruchkorrektur Es folgen die beiden von \KOMAScript{} angebotenen Konstruktionen. \else -\iftrue% Umbruchkorrektur +\iffalse% Umbruchkorrektur Wir können also mit den konkreten Konstruktionen beginnen. \else In den folgenden beiden Abschnitten werden die von {\KOMAScript} angebotenen - Konstruktionen vorgestellt. + Konstruktionen im Detail vorgestellt. \fi \fi \end{Explain} @@ -448,8 +458,8 @@ Anwender erleichtern, eine gute Wahl zu treffen. Im \Package{typearea}-Paket wird diese Konstruktion dahingehend abgewandelt, dass durch Auswahl eines ausgezeichneten -- normalerweise unsinnigen -- - \Var{DIV}-Wertes oder eine spezielle Paket-Option derjenige \Var{DIV}-Wert - ermittelt wird, bei dem der resultierende Satzspiegel dem + \Var{DIV}-Wertes oder einer speziellen, symbolischen Angabe derjenige + \Var{DIV}-Wert ermittelt wird, bei dem der resultierende Satzspiegel dem spätmittelalterlichen Buchseitenkanon am nächsten kommt. Es wird also wiederum auf die Satzspiegelkonstruktion durch Teilung zurückgegriffen. % @@ -475,10 +485,11 @@ nehmen. Die wichtigste M im vorherigen Abschnitt erwähnt, können die Optionen dabei auf unterschiedlichen Wegen gesetzt werden. -In diesem Abschnitt wird die Klasse \Class{protokol} verwendet werden. Es -handelt sich dabei nicht um eine \KOMAScript-Klasse, sondern um eine -hypothetische Klasse. Diese\iffree{ Anleitung}{s Buch} geht von dem Idealfall -aus, dass für jede Aufgabe eine dafür passende Klasse zur Verfügung steht. +In\textnote{Hinweis!} diesem Abschnitt wird die Klasse \Class{protokol} +verwendet werden. Es handelt sich dabei nicht um eine \KOMAScript-Klasse, +sondern um eine hypothetische Klasse. Diese\iffree{ Anleitung}{s Buch} geht +von dem Idealfall aus, dass für jede Aufgabe eine dafür passende Klasse zur +Verfügung steht. \begin{Declaration} @@ -486,7 +497,8 @@ aus, dass f \end{Declaration}% Mit Hilfe der Option \OptionVName{BCOR}{Korrektur}\ChangedAt{v3.00}{\Package{typearea}} geben Sie -den absoluten Wert der Bindekorrektur\Index{Bindekorrektur} an, also die +den absoluten Wert der +Bindekorrektur\Index{Bindekorrektur}\textnote{Bindekorrektur} an, also die Breite des Bereichs, der durch die Bindung von der Papierbreite verloren geht. Dieser Wert wird in der Satzspiegelkonstruktion automatisch berücksichtigt und bei der Ausgabe wieder dem inneren beziehungsweise linken @@ -504,12 +516,12 @@ verstandene Ma \documentclass[a4paper]{report} \usepackage[BCOR=8.25mm]{typearea} \end{lstcode} - oder + mit \OptionValue{BCOR}{8.25mm} als Option für \Package{typearea} oder \begin{lstcode} \documentclass[a4paper,BCOR=8.25mm]{report} \usepackage{typearea} \end{lstcode} - bei Angabe von \Option{BCOR} als globale Option. + zur Angabe von \OptionValue{BCOR}{8.25mm} als globale Option. Bei Verwendung einer \KOMAScript-Klasse kann das explizite Laden von \Package{typearea} entfallen: @@ -578,7 +590,7 @@ Schriftgr % \caption [{Satzspiegelma"se in Abh"angigkeit von \Var{DIV} bei A4}] {\label{tab:typearea.typearea}Satzspiegelma"se in Abh"angigkeit von \Var{DIV} - bei A4 ohne Berücksichtigung von \Length{topskip}} + bei A4 ohne Berücksichtigung von \Length{topskip} oder \Var{BCOR}} [l] \begin{tabular}[t]{ccccc} \toprule @@ -615,7 +627,7 @@ Schriftgr Höhe relativ breit. Deshalb ist Ihnen die Voreinstellung für den \Var{DIV}-Wert in \Package{typearea} zu gering. Statt einem Wert von 12 sind Sie nach gründlichem Studium dieses Kapitels einschließlich der - weiterführenden Abschnitte überzeugt, dass ein Wert 15 angebracht ist. Das + weiterführenden Abschnitte überzeugt, dass der Wert 15 angebracht ist. Das Protokoll wird nicht gebunden, sondern gelocht und in einen Ordner abgeheftet. Eine Bindekorrektur ist deshalb nicht notwendig. Sie schreiben also: @@ -662,7 +674,7 @@ muss. Weder sollte das Paket \Package{typearea} bei Verwendung einer noch die Option dabei als optionales Argument angegeben werden. Wird\textnote{automatische Neuberechnung} die Option per \DescRef{\LabelBase.cmd.KOMAoptions} oder \DescRef{\LabelBase.cmd.KOMAoption} -nach dem Laden des Pakets geändert, so werden Satzspiegel und Rändern +nach dem Laden des Pakets geändert, so werden Satzspiegel und Ränder automatisch neu berechnet. \begin{Declaration} @@ -679,13 +691,13 @@ sehr rasch zu unangenehm hoher Zeichenzahl je Zeile f Überlegungen in \autoref{sec:typearea.basics}. Wird ein anderes Papierformat gewählt, so berechnet \Package{typearea} selbst einen guten \Var{DIV}-Wert. Natürlich können Sie diese Berechnung auch für A4 wählen. Hierzu verwenden Sie -\OptionValue{DIV}{calc}\important{\OptionValue{DIV}{calc}} an Stelle von -\OptionVName{\DescRef{\LabelBase.option.DIV}}{Faktor}. Selbstverständlich können Sie diese Option auch -explizit bei allen anderen Papierformaten angeben. Wenn Sie die automatische -Berechnung wünschen, ist diese Angabe sogar sinnvoll, da die Möglichkeit -besteht, in einer Konfigurationsdatei andere Voreinstellungen zu setzen (siehe -\autoref{sec:typearea-experts.cfg}). Eine explizit angegebene Option -\OptionValue{DIV}{calc} überschreibt diese Vorkonfiguration aber. +\OptionValue{DIV}{calc}\important{\OptionValue{DIV}{calc}} anstelle von +\OptionVNameRef{\LabelBase}{DIV}{Faktor}. Selbstverständlich können Sie +diese Option auch explizit bei allen anderen Papierformaten angeben. Wenn Sie +die automatische Berechnung wünschen, ist diese Angabe sogar sinnvoll, da die +Möglichkeit besteht, in einer Konfigurationsdatei andere Voreinstellungen zu +setzen (siehe \autoref{sec:typearea-experts.cfg}). Eine explizit angegebene +Option \OptionValue{DIV}{calc} überschreibt diese Vorkonfiguration aber. \begin{table} % \centering @@ -694,8 +706,7 @@ besteht, in einer Konfigurationsdatei andere Voreinstellungen zu setzen (siehe \begin{captionbeside} %\caption [{\PName{DIV}-Voreinstellungen f"ur A4}] - {\label{tab:typearea.div}\PName{DIV}-Voreinstellungen f"ur A4 bei Verzicht - auf \Var{BCOR}} + {\label{tab:typearea.div}\PName{DIV}-Voreinstellungen f"ur A4} [l] \begin{tabular}[t]{lccc} \toprule @@ -708,26 +719,26 @@ besteht, in einer Konfigurationsdatei andere Voreinstellungen zu setzen (siehe Die in \autoref{sec:typearea.circleConstruction} erwähnte klassische Konstruktion, der mittelalterliche Buchseitenkanon, ist ebenfalls auswählbar. -Verwenden Sie in diesem Fall an Stelle von \OptionVName{\DescRef{\LabelBase.option.DIV}}{Faktor} oder -\OptionValue{DIV}{calc} einfach +Verwenden Sie in diesem Fall anstelle von +\OptionVNameRef{\LabelBase}{DIV}{Faktor} oder \OptionValue{DIV}{calc} einfach \OptionValue{DIV}{classic}\important{\OptionValue{DIV}{classic}}. Es wird dann ein \Var{DIV}-Wert ermittelt, der eine möglichst gute Näherung an den mittelalterlichen Buchseitenkanon darstellt. \begin{Example} - In dem bei der Option \OptionVName{\DescRef{\LabelBase.option.DIV}}{Faktor} aufgeführten - Beispiel mit der Schriftart Bookman gab es ja genau das Problem, - dass man einen zur Schriftart besser passenden \Var{DIV}-Wert haben - wollte. Man könnte also in Abwandlung des ersten Beispiels auch - einfach die Ermittlung dieses Wertes \Package{typearea} überlassen: + In dem bei der Option \OptionVNameRef{\LabelBase}{DIV}{Faktor} aufgeführten + Beispiel mit der Schriftart Bookman gab es ja genau das Problem, dass man + einen zur Schriftart besser passenden \Var{DIV}-Wert haben wollte. Man + könnte also in Abwandlung des ersten Beispiels auch einfach die Ermittlung + dieses Wertes \Package{typearea} überlassen: \begin{lstcode} \documentclass[a4paper,twoside]{protokol} \usepackage{bookman} \usepackage[DIV=calc]{typearea} \end{lstcode} \end{Example} - -\iffree{Bitte beachten Sie unbedingt\textnote{Achtung!}, dass diese Option bei +\iffree{\par% + Bitte beachten Sie unbedingt\textnote{Achtung!}, dass diese Option bei Verwendung einer der \KOMAScript-Klassen % \iftrue wie im Beispiel \fi% als Klassenoption oder per \DescRef{\LabelBase.cmd.KOMAoptions} @@ -738,7 +749,10 @@ mittelalterlichen Buchseitenkanon darstellt. optionales Argument angegeben werden. Wird die Option per \DescRef{\LabelBase.cmd.KOMAoptions} oder \DescRef{\LabelBase.cmd.KOMAoption} nach dem Laden des Pakets geändert, so - werden Satzspiegel und Rändern automatisch neu berechnet.}{}% + werden Satzspiegel und Ränder automatisch neu berechnet.% +}{% + \vskip-\dp\strutbox% Wegen Code im Beispiel am Ende +}% % \EndIndexGroup @@ -794,14 +808,14 @@ Berechnung verwendet wird. Gehen wir wieder davon aus, dass für die Schriftart Bookman ein Satzspiegel mit guter Zeilenlänge berechnet werden soll. Gleichzeitig wird eine \KOMAScript-Klasse verwendet. Dies ist mit dem symbolischen Wert - \PValue{last} und der Anweisung \DescRef{\LabelBase.cmd.KOMAoptions} sehr einfach möglich: + \PValue{last} und der Anweisung \DescRef{\LabelBase.cmd.KOMAoptions} sehr + einfach möglich: \begin{lstcode} \documentclass[BCOR=12mm,DIV=calc,twoside] {scrartcl} \usepackage{bookman} \KOMAoptions{DIV=last} \end{lstcode} - \iffree{}{\clearpage}% Umbruchoptimierung Wird später entschieden, dass ein anderer \Var{DIV}-Wert verwendet werden soll, so muss nur die Einstellung im optionalen Argument von \DescRef{\LabelBase.cmd.documentclass} geändert werden. @@ -814,27 +828,34 @@ darauf hingewiesen, dass auch die Verwendung des Pakets andere Schrift lädt. \begin{table} - \caption[{Symbolische Werte für Option \Option{DIV} und das - \PName{DIV}-Argument von \DescRef{typearea.cmd.typearea}}]{Mögliche symbolische Werte - für die Option \Option{DIV} oder das \PName{DIV}-Argument der Anweisung - \DescRef{typearea.cmd.typearea}\OParameter{BCOR}\Parameter{DIV}} + \caption[{% + Symbolische Werte für Option \DescRef{typearea.option.DIV} und das + \PName{DIV}-Argument von \DescRef{typearea.cmd.typearea}% + }]{% + Mögliche symbolische Werte für die Option \DescRef{typearea.option.DIV} + oder das \PName{DIV}-Argument der Anweisung + \DescRef{typearea.cmd.typearea}\OParameter{BCOR}\Parameter{DIV}% + } \label{tab:symbolicDIV} \begin{desctabular} - \pventry{areaset}{Satzspiegel neu anordnen.\IndexOption{DIV~=\PValue{areaset}}}% + \pventry{areaset}{Satzspiegel neu + anordnen.\IndexOption{DIV~=\textKValue{areaset}}}% \pventry{calc}{Satzspiegelberechnung einschließlich Ermittlung eines guten - \Var{DIV}-Wertes erneut durchführen.\IndexOption{DIV~=\PValue{calc}}}% + \Var{DIV}-Wertes erneut + durchführen.\IndexOption{DIV~=\textKValue{calc}}}% \pventry{classic}{Satzspiegelberechnung nach dem mittelalterlichen Buchseitenkanon (Kreisberechnung) erneut - durchführen.\IndexOption{DIV~=\PValue{classic}}}% + durchführen.\IndexOption{DIV~=\textKValue{classic}}}% \pventry{current}{Satzspiegelberechnung mit dem aktuell gültigen - \Var{DIV}-Wert erneut durchführen.\IndexOption{DIV~=\PValue{current}}}% + \Var{DIV}-Wert erneut + durchführen.\IndexOption{DIV~=\textKValue{current}}}% \pventry{default}{Satzspiegelberechnung mit dem Standardwert für das aktuelle Seitenformat und die aktuelle Schriftgröße erneut durchführen. Falls kein Standardwert existiert, \PValue{calc} - anwenden.\IndexOption{DIV~=\PValue{default}}}% + anwenden.\IndexOption{DIV~=\textKValue{default}}}% \pventry{last}{Satzspiegelberechnung mit demselben \PName{DIV}-Argument, das beim letzten Aufruf angegeben wurde, erneut - durchführen.\IndexOption{DIV~=\PValue{last}}}% + durchführen.\IndexOption{DIV~=\textKValue{last}}}% \end{desctabular} \end{table} @@ -863,14 +884,15 @@ normalen der Satzspiegel f Berechnung eines neuen Satzspiegels ausführt, ist es nicht zwingend notwendig, nach \Macro{linespread} den gewählten Durchschuss mit \Macro{selectfont} zu aktivieren, damit dieser % -\iffalse % Umbruchkorrektur +\iftrue % Umbruchkorrektur auch tatsächlich \fi % für die Neuberechnung verwendet wird. Das gleiche Beispiel sähe unter Verwendung des - \Package{setspace}-Pakets\IndexPackage{setspace} (siehe - \cite{package:setspace}) wie folgt aus: + \Package{setspace}-Pakets\IndexPackage{setspace}% + \important{\Package{setspace}} + (siehe \cite{package:setspace}) wie folgt aus: \begin{lstcode} \documentclass[10pt,twoside,BCOR=12mm,DIV=calc] {scrreprt} @@ -884,7 +906,7 @@ Wie\textnote{Tipp!} man an dem Beispiel sieht, spart man sich mit dem allerdings nur für die Standardschriftgrößen 10\Unit{pt}, 11\Unit{pt} und 12\Unit{pt}. Für alle anderen Schriftgrößen verwendet das Paket % -\iffalse % Umbruchkorrektur +\iftrue % Umbruchkorrektur einen näherungsweise passenden Dehnungswert. % \else % @@ -923,7 +945,9 @@ Auswirkungen auf Kopf und Fu beispielsweise bei Verwendung von \Package{scrlayer-scrpage} auswirken und man muss dann selbst entscheiden, ob man dort lieber den normalen Durchschuss oder den veränderten haben will. Siehe dazu auch Option -\DescRef{scrlayer.option.singlespacing} in \autoref{cha:scrlayer} auf +\DescRef{scrlayer.option.singlespacing} in \autoref{cha:scrlayer}% +\important{\hyperref[cha:scrlayer]{\Package{scrlayer}}}% +\IndexPackage{scrlayer}\IndexOption{singlespacing} auf \DescPageRef{scrlayer.option.singlespacing}. Bitte beachten Sie unbedingt\textnote{Achtung!}, dass diese Optionen auch zur @@ -944,35 +968,40 @@ von Satzspiegel und R Wird die Option \DescRef{\LabelBase.option.DIV} oder die Option \DescRef{\LabelBase.option.BCOR} nach dem Laden des Pakets \Package{typearea} gesetzt, so wird intern die Anweisung \Macro{typearea} - aufgerufen. Dabei wird beim Setzen der Option \DescRef{\LabelBase.option.DIV} für \PName{BCOR} - intern der symbolische Wert \PValue{current} verwendet, der aus Gründen der - Vollständigkeit auch in \autoref{tab:symbolicBCOR} zu finden ist. Beim - Setzen der Option \DescRef{\LabelBase.option.BCOR} wird für \PName{DIV} - hingegen der symbolische Wert \PValue{last} verwendet. Wollen Sie, dass - Satzspiegel und Rändern stattdessen mit dem symbolischen Wert - \PValue{current} für \PName{DIV} neu berechnet werden, so können Sie direkt + aufgerufen. Dabei wird beim Setzen der Option + \DescRef{\LabelBase.option.DIV} für \PName{BCOR} intern der symbolische Wert + \PValue{current} verwendet, der aus Gründen der Vollständigkeit auch in + \autoref{tab:symbolicBCOR} zu finden ist. Beim Setzen der Option + \DescRef{\LabelBase.option.BCOR} wird für \PName{DIV} hingegen der + symbolische Wert \PValue{last} verwendet. Wollen Sie, dass Satzspiegel und + Ränder stattdessen mit dem symbolischen Wert \PValue{current} für + \PName{DIV} neu berechnet werden, so können Sie direkt \Macro{typearea}\POParameter{current}\PParameter{current} verwenden. \end{Explain} \begin{table} - \caption[{Symbolische \PName{BCOR}-Argumente für - \Macro{typearea}}]{Mögliche symbolische \PName{BCOR}-Argumente für - \Macro{typearea}\OParameter{BCOR}\Parameter{DIV}} + \caption[{% + Symbolische \PName{BCOR}-Argumente für \DescRef{typearea.cmd.typearea}% + }]{% + Mögliche symbolische \PName{BCOR}-Argumente für + \Macro{typearea}\OParameter{BCOR}\Parameter{DIV}% + } \label{tab:symbolicBCOR} \begin{desctabular} \pventry{current}{Satzspiegelberechnung mit dem aktuell gültigen - \Var{BCOR}-Wert erneut durchführen.\IndexOption{BCOR~=\PValue{current}}} + \Var{BCOR}-Wert erneut + durchführen.\IndexOption{BCOR~=\textKValue{current}}} \end{desctabular} \end{table} Sollen die Werte sowohl von \PName{BCOR} als auch \PName{DIV} geändert werden, so ist die Verwendung von \Macro{typearea} zu empfehlen, da hierbei die Ränder -und der Satzspiegel nur einmal neu berechnet werden. Hingegen werden bei +und der Satzspiegel nur einmal neu berechnet werden. Bei \DescRef{\LabelBase.cmd.KOMAoptions}% -\PParameter{\OptionVName{\DescRef{\LabelBase.option.DIV}}{DIV},% - \OptionVName{\DescRef{\LabelBase.option.BCOR}}{BCOR}} Ränder und Satzspiegel -zunächst bei der Änderung für \PName{DIV} und dann zusätzlich bei der Änderung -für \PName{BCOR} neu berechnet. +\PParameter{\OptionVNameRef{\LabelBase}{DIV}{Faktor},% + \OptionVNameRef{\LabelBase}{BCOR}{Korrektur}} werden hingegen Ränder und +Satzspiegel zunächst in Folge von Option \DescRef{\LabelBase.option.DIV} und +dann zusätzlich durch Option \DescRef{\LabelBase.option.BCOR} neu berechnet. \begin{Explain} Der Befehl \Macro{typearea} ist derzeit so definiert, dass es auch möglich @@ -986,9 +1015,11 @@ f Seitenumbruch. \end{Explain} -Da\important{\Macro{recalctypearea}} -\DescRef{\LabelBase.cmd.KOMAoption}\PParameter{DIV}\PParameter{last} oder -\DescRef{\LabelBase.cmd.KOMAoptions}\PParameter{DIV=last} beziehungsweise +Da\important{\Macro{recalctypearea}} \DescRef{\LabelBase.cmd.KOMAoption}% +\PParameter{\hyperref[desc:\LabelBase.option.DIV.last]{\Option{DIV}}}% +\PParameter{\hyperref[desc:\LabelBase.option.DIV.last]{last}} oder +\DescRef{\LabelBase.cmd.KOMAoptions}% +\PParameter{\OptionValueRef{\LabelBase}{DIV}{last}} beziehungsweise \Macro{typearea}\POParameter{current}\PParameter{last} für die Neuberechnung des Satzspiegels und der Ränder recht häufig benötigt werden, gibt es dafür die abkürzende Anweisung @@ -1061,23 +1092,24 @@ Wert \PValue{semi}\ChangedAt{v3.00}{\Package{typearea}}% einseitigen, also nicht alternierenden Marginalien. Eine\ChangedAt{v3.12}{\Package{typearea}} eventuelle Bindekorrektur (siehe Option \DescRef{\LabelBase.option.BCOR}, -\DescPageRef{typearea.option.BCOR}) wird jedoch ab \KOMAScript~Version -3.12 wie beim doppelseitigen Satz auf Seiten mit ungerader Nummer dem linken -Rand und auf Seiten mit gerader Nummer dem rechten Rand zugeschlagen. Wird auf -Kompatibilität zu einer Version früheren Version zurückgeschaltet (siehe -\autoref{sec:typearea.compatibilityOptions}, +\DescPageRef{typearea.option.BCOR}) wird jedoch ab \KOMAScript~Version 3.12 +wie beim doppelseitigen Satz auf Seiten mit ungerader Nummer dem linken Rand +und auf Seiten mit gerader Nummer dem rechten Rand zugeschlagen. Wird auf +Kompatibilität zu einer früheren +Version\important{\OptionValueRef{\LabelBase}{version}{3.12}} zurückgeschaltet +(siehe \autoref{sec:typearea.compatibilityOptions}, \autopageref{sec:typearea.compatibilityOptions}), so ist die Bindekorrektur jedoch auch bei \OptionValue{twoside}{semi} immer Teil des linken Randes. Die Option kann % -\iffalse % Umbruchkorrektur +\iftrue % Umbruchkorrektur wahlweise \fi % als Klassenoption bei \DescRef{\LabelBase.cmd.documentclass}, als Paketoption bei \DescRef{\LabelBase.cmd.usepackage} oder auch nach dem Laden von \Package{typearea} per \DescRef{\LabelBase.cmd.KOMAoptions} oder \DescRef{\LabelBase.cmd.KOMAoption} gesetzt werden. Eine Verwendung dieser Option nach dem Laden von \Package{typearea} führt\textnote{automatische - Neuberechnung} automatisch zur Neuberechnung des Satzspiegels mittels + Neuberechnung} automatisch zur Neuberechnung des Satzspiegels mit \DescRef{\LabelBase.cmd.recalctypearea} (siehe \DescPageRef{typearea.cmd.recalctypearea}). War vor der Option doppelseitiger Satz aktiv, wird noch vor der Neuberechnung auf die nächste @@ -1090,11 +1122,11 @@ ungerade Seite umbrochen.% \OptionVName{twocolumn}{Ein-Aus-Wert} \end{Declaration}% Für die Berechnung eines guten Satzspiegels mit Hilfe von -\OptionValueRef{\LabelBase}{DIV}{calc} ist es erforderlich zu wissen, ob das Dokument ein- -oder zweispaltig gesetzt wird. Da die Betrachtungen zur Zeilenlänge aus -\autoref{sec:typearea.basics} dann für jede einzelne Spalte gelten, darf der -Satzspiegel in doppelspaltigen Dokumenten bis zu doppelt so breit sein wie in -einspaltigen Dokumenten. +\OptionValueRef{\LabelBase}{DIV}{calc} ist es erforderlich zu wissen, ob das +Dokument ein- oder zweispaltig gesetzt wird. Da die Betrachtungen zur +Zeilenlänge aus \autoref{sec:typearea.basics} dann für jede einzelne Spalte +gelten, darf der Satzspiegel in doppelspaltigen Dokumenten bis zu doppelt so +breit sein wie in einspaltigen Dokumenten. Um diese Unterscheidung vornehmen zu können, muss \Package{typearea} mit Option \Option{twocolumn} mitgeteilt werden, ob das Dokument doppelspaltig @@ -1103,7 +1135,7 @@ einfache Schalter aus \autoref{tab:truefalseswitch} verwendet werden. Wird die Option ohne Wert-Angabe verwendet, so wird der Wert \PValue{true}\important{\OptionValue{twocolumn}{true}} angenommen, also doppelspaltiger Satz verwendet. Ein -Deaktivieren der Option führt wieder zum voreingestellten, +Deaktivieren der Option führt wieder zum voreingestellten einspaltigen Satz. Die Option kann als Klassenoption bei \DescRef{\LabelBase.cmd.documentclass}, @@ -1157,7 +1189,7 @@ Option nach dem Laden von \Package{typearea} f Ermangelung erreichbarer Großeltern kann man sich auch damit behelfen, dass man die eigenen Augen auf Fernsicht stellt, die Seite aber nur mit ausgestreckten Armen hält. Brillenträger sind hier deutlich im Vorteil. Hat - man eine Fußzeile, die neben der Paginierung weitere, weitschweifige Angaben + man eine Fußzeile, die neben der Paginierung weitere weitschweifige Angaben enthält, beispielsweise einen Copyright-Hinweis, so wirkt die Fußzeile eher wie ein etwas abgesetzter Teil des Textkörpers. Bei der Berechnung des Satzspiegels sollte das berücksichtigt werden. @@ -1177,7 +1209,7 @@ Option nach dem Laden von \Package{typearea} f erfolgt. Dadurch erhält man einen links und rechts abgeschlossenen Bereich, der kaum noch als leerer Rand wirkt. Schwieriger ist es bei Paginierung im Fuß und Überschriften, deren Länge sehr stark schwankt. Hier kann der Kopf - der einen Seite wie Textkörper wirken, der Kopf der anderen Seite jedoch + der einen Seite wie Textkörper wirken, der Kopf der anderen Seite aber eher wie Rand. Keinesfalls sollte man die Seiten jedoch unterschiedlich behandeln. Das würde zu vertikal springenden Köpfen führen und ist nicht einmal für ein Daumenkino geeignet. Ich rate in diesem Fall dazu, den Kopf @@ -1215,13 +1247,16 @@ obige Erl Bitte beachten Sie unbedingt\textnote{Achtung!}, dass diese Optionen bei Verwendung einer der \KOMAScript-Klassen als Klassenoptionen oder per -\DescRef{\LabelBase.cmd.KOMAoptions} beziehungsweise \DescRef{\LabelBase.cmd.KOMAoption} nach dem Laden der -Klasse übergeben werden müssen. Eine Änderung dieser Optionen nach dem Laden -von \Package{typearea} führt dabei nicht\textnote{keine automatische - Neuberechnung} zu einer automatischen Neuberechnung des -Satzspiegels. Vielmehr wirkt sich die Änderung erst bei der nächsten -Neuberechnung des Satzspiegels aus. Zur Neuberechnung des Satzspiegels siehe -Option \DescRef{\LabelBase.option.DIV} mit den Werten \PValue{last} oder \PValue{current} (siehe +\DescRef{\LabelBase.cmd.KOMAoptions} beziehungsweise +\DescRef{\LabelBase.cmd.KOMAoption} nach dem Laden der Klasse übergeben werden +müssen. Eine Änderung dieser Optionen nach dem Laden von \Package{typearea} +führt dabei nicht\textnote{keine automatische Neuberechnung} zu einer +automatischen Neuberechnung des Satzspiegels. Vielmehr wirkt sich die Änderung +erst bei der nächsten Neuberechnung des Satzspiegels aus. Zur Neuberechnung +des Satzspiegels siehe Option +\hyperref[desc:\LabelBase.option.DIV.last]{\Option{DIV}} mit den Werten +\hyperref[desc:\LabelBase.option.DIV.last]{\PValue{last}} oder +\hyperref[desc:\LabelBase.option.DIV.current]{\PValue{current}} (siehe \DescPageRef{typearea.option.DIV.last}) oder die Anweisung \DescRef{\LabelBase.cmd.recalctypearea} (siehe \DescPageRef{typearea.cmd.recalctypearea}).% @@ -1304,13 +1339,16 @@ bleiben. Bitte beachten Sie unbedingt\textnote{Achtung!}, dass diese Option bei Verwendung einer der \KOMAScript-Klassen als Klassenoption oder per -\DescRef{\LabelBase.cmd.KOMAoptions} beziehungsweise oder \DescRef{\LabelBase.cmd.KOMAoption} nach dem Laden der -Klasse übergeben werden muss. Eine Änderung dieser Option nach dem Laden von -\Package{typearea} führt nicht\textnote{keine automatische Neuberechnung} zu -einer automatischen Neuberechnung des Satzspiegels. Vielmehr wirkt sich die -Änderung erst bei der nächsten Neuberechnung des Satzspiegels aus. Zur -Neuberechnung des Satzspiegels siehe Option \DescRef{\LabelBase.option.DIV} mit den Werten -\PValue{last} oder \PValue{current} (siehe +\DescRef{\LabelBase.cmd.KOMAoptions} beziehungsweise oder +\DescRef{\LabelBase.cmd.KOMAoption} nach dem Laden der Klasse übergeben werden +muss. Eine Änderung dieser Option nach dem Laden von \Package{typearea} führt +nicht\textnote{keine automatische Neuberechnung} zu einer automatischen +Neuberechnung des Satzspiegels. Vielmehr wirkt sich die Änderung erst bei der +nächsten Neuberechnung des Satzspiegels aus. Zur Neuberechnung des +Satzspiegels siehe Option +\hyperref[desc:\LabelBase.option.DIV.last]{\Option{DIV}} mit den Werten +\hyperref[desc:\LabelBase.option.DIV.last]{\PValue{last}} oder +\hyperref[desc:\LabelBase.option.DIV.current]{\PValue{current}} (siehe \DescPageRef{typearea.option.DIV.last}) oder die Anweisung \DescRef{\LabelBase.cmd.recalctypearea} (siehe \DescPageRef{typearea.cmd.recalctypearea}).% @@ -1334,7 +1372,7 @@ Die Option \Option{headlines}\important{\Option{headlines}} setzt man dabei auf die Anzahl der Kopfzeilen. Normalerweise arbeitet das \Package{typearea}-Paket mit 1,25 Kopfzeilen. Dieser Wert stellt einen Kompromiss dar. Zum einen ist er groß genug, um auch für eine unterstrichene -Kopfzeile (siehe \autoref{sec:maincls.options}) Platz zu bieten, zum anderen +Kopfzeile (siehe \autoref{sec:maincls.pagestyle}) Platz zu bieten, zum anderen ist er klein genug, um das Randgewicht nicht zu stark zu verändern, wenn mit einer einfachen, nicht unterstrichenen Kopfzeile gearbeitet wird. Damit ist der voreingestellte Wert in den meisten Standardfällen ein guter Wert. In @@ -1368,18 +1406,23 @@ m kennt. Es ist jedoch zu beachten, dass bei Verwendung einer \LaTeX-Länge wie \Length{baselineskip} nicht deren Größe zum Zeitpunkt des Setzens der Option, sondern zum Zeitpunkt der Berechnung des Satzspiegels und der Ränder -entscheidend ist. +entscheidend ist. Außerdem\textnote{Achtung!} sollten \LaTeX-Längen wie +\Length{baselineskip} keinesfalls im optionalen Argument von +\DescRef{\LabelBase.cmd.documentclass} oder +\DescRef{\LabelBase.cmd.usepackage} verwendet werden. -\iffree{}{\pagebreak}% Umbruchoptimierung!!! Bitte beachten Sie unbedingt\textnote{Achtung!}, dass diese Optionen bei Verwendung einer der \KOMAScript-Klassen als Klassenoptionen oder per -\DescRef{\LabelBase.cmd.KOMAoptions} beziehungsweise \DescRef{\LabelBase.cmd.KOMAoption} nach dem Laden der -Klasse übergeben werden müssen. Eine Änderung dieser Optionen nach dem Laden -von \Package{typearea} führt nicht\textnote{keine automatische - Neuberechnung} zu einer automatischen Neuberechnung des -Satzspiegels. Vielmehr wirkt sich die Änderung erst bei der nächsten -Neuberechnung des Satzspiegels aus. Zur Neuberechnung des Satzspiegels siehe -Option \DescRef{\LabelBase.option.DIV} mit den Werten \PValue{last} oder \PValue{current} (siehe +\DescRef{\LabelBase.cmd.KOMAoptions} beziehungsweise +\DescRef{\LabelBase.cmd.KOMAoption} nach dem Laden der Klasse übergeben werden +müssen. Eine Änderung dieser Optionen nach dem Laden von \Package{typearea} +führt nicht\textnote{keine automatische Neuberechnung} zu einer automatischen +Neuberechnung des Satzspiegels. Vielmehr wirkt sich die Änderung erst bei der +nächsten Neuberechnung des Satzspiegels aus. Zur Neuberechnung des +Satzspiegels siehe Option +\hyperref[desc:\LabelBase.option.DIV.last]{\Option{DIV}} mit den Werten +\hyperref[desc:\LabelBase.option.DIV.last]{\PValue{last}} oder +\hyperref[desc:\LabelBase.option.DIV.current]{\PValue{current}} (siehe \DescPageRef{typearea.option.DIV.last}) oder die Anweisung \DescRef{\LabelBase.cmd.recalctypearea} (siehe \DescPageRef{typearea.cmd.recalctypearea}).% @@ -1398,14 +1441,15 @@ soll. Hierzu dienen die Optionen \Option{footlines} und \Option{footheight}\ChangedAt{v3.12}{\Package{typearea}}. Allerdings ist die Höhe des Fußes im Gegensatz zur Höhe des Kopfes keine Länge des \LaTeX-Kerns selbst. Daher definiert \Package{typearea} zur Einführung eine neue Länge -\Length{footheight}\IndexLength[indexmain]{footheight}, -falls diese noch nicht existiert. Ob diese dann auch beispielsweise von -Klassen und Paketen für die Gestaltung von Kopf und Fuß verwendet wird, hängt -von den verwendeten Klassen und Paketen ab. Das \KOMAScript-Paket -\Package{scrlayer-scrpage} berücksichtigt -\Length{footheight} und arbeitet somit aktiv mit -\Package{typearea} zusammen. Die \KOMAScript-Klassen berücksichtigen -\Length{footheight} hingegen nicht, da sie ohne +\Length{footheight}\IndexLength[indexmain]{footheight}, falls diese noch nicht +existiert. Ob diese dann auch beispielsweise von Klassen und Paketen für die +Gestaltung von Kopf und Fuß verwendet wird, hängt von den verwendeten Klassen +und Paketen ab. Das \KOMAScript-Paket +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}}% +\IndexPackage{scrlayer-scrpage} berücksichtigt \Length{footheight} und +arbeitet somit aktiv mit \Package{typearea} zusammen. Die \KOMAScript-Klassen +berücksichtigen \Length{footheight} hingegen nicht, da sie ohne Paketunterstützung nur Seitenstile mit einzeiligen Seitenfüßen anbieten. Die Option \Option{footlines}\important{\Option{footlines}} setzt man @@ -1413,7 +1457,7 @@ vergleichbar zu \DescRef{\LabelBase.option.headlines} auf die Anzahl der Fußzeilen. Normalerweise arbeitet das \Package{typearea}-Paket mit 1,25 Fußzeilen. Dieser Wert stellt einen Kompromiss dar. Zum einen ist er groß genug, um auch für eine über- und unterstrichene Fußzeile (siehe -\autoref{sec:maincls.options}) Platz zu bieten, zum anderen ist er klein +\autoref{sec:maincls.pagestyle}) Platz zu bieten, zum anderen ist er klein genug, um das Randgewicht nicht zu stark zu verändern, wenn mit einer einfachen Fußzeile ohne Trennlinien gearbeitet wird. Damit ist der voreingestellte Wert in den meisten Standardfällen ein guter Wert. In einigen @@ -1426,7 +1470,9 @@ Erfordernissen anpassen. vorgesehene Platz dafür genügend Raum bietet, die Überschreitung der vorgesehenen Höhe resultiert aber wahrscheinlich in einer unausgeglichenen Verteilung von Satzspiegeln und Rändern. Außerdem führt beispielsweise das - Paket \Package{scrlayer-scrpage}, mit dem ein solcher Fuß\-in\-halt gesetzt + Paket \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + \important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}}% + \IndexPackage{scrlayer-scrpage}, mit dem ein solcher Fuß\-in\-halt gesetzt werden könnte, durchaus eine entsprechende Überprüfung durch und meldet gegebenenfalls auch Überschreitungen. Daher ist es sinnvoll, die benötigte größere Fußhöhe bereits bei der Berechnung des Satzspiegels anzugeben: @@ -1450,21 +1496,26 @@ m kennt. Es ist jedoch zu beachten, dass bei Verwendung einer \LaTeX-Länge wie \Length{baselineskip} nicht deren Größe zum Zeitpunkt des Setzens der Option, sondern zum Zeitpunkt der Berechnung des Satzspiegels und der Ränder -entscheidend ist. +entscheidend ist. Außerdem\textnote{Achtung!} sollten \LaTeX-Längen wie +\Length{baselineskip} keinesfalls im optionalen Argument von +\DescRef{\LabelBase.cmd.documentclass} oder +\DescRef{\LabelBase.cmd.usepackage} verwendet werden. Bitte beachten Sie unbedingt\textnote{Achtung!}, dass diese Optionen bei Verwendung einer der \KOMAScript-Klassen als Klassenoptionen oder per -\DescRef{\LabelBase.cmd.KOMAoptions} beziehungsweise \DescRef{\LabelBase.cmd.KOMAoption} nach dem Laden der -Klasse übergeben werden müssen. Eine Änderung dieser Optionen nach dem Laden -von \Package{typearea} führt nicht\textnote{keine automatische - Neuberechnung} zu einer automatischen Neuberechnung des -Satzspiegels. Vielmehr wirkt sich die Änderung erst bei der nächsten -Neuberechnung des Satzspiegels aus. Zur Neuberechnung des Satzspiegels siehe -Option \DescRef{\LabelBase.option.DIV} mit den Werten \PValue{last} oder \PValue{current} (siehe +\DescRef{\LabelBase.cmd.KOMAoptions} beziehungsweise +\DescRef{\LabelBase.cmd.KOMAoption} nach dem Laden der Klasse übergeben werden +müssen. Eine Änderung dieser Optionen nach dem Laden von \Package{typearea} +führt nicht\textnote{keine automatische Neuberechnung} zu einer automatischen +Neuberechnung des Satzspiegels. Vielmehr wirkt sich die Änderung erst bei der +nächsten Neuberechnung des Satzspiegels aus. Zur Neuberechnung des +Satzspiegels siehe Option +\hyperref[desc:\LabelBase.option.DIV.last]{\Option{DIV}} mit den Werten +\hyperref[desc:\LabelBase.option.DIV.last]{\PValue{last}} oder +\hyperref[desc:\LabelBase.option.DIV.current]{\PValue{current}} (siehe \DescPageRef{typearea.option.DIV.last}) oder die Anweisung \DescRef{\LabelBase.cmd.recalctypearea} (siehe \DescPageRef{typearea.cmd.recalctypearea}).% -% \EndIndexGroup @@ -1494,7 +1545,7 @@ Informationen zu \DescRef{typearea-experts.cmd.areaset} auf \DescPageRef{typearea-experts.cmd.areaset} in \autoref{sec:typearea-experts.experimental}. -Die Voreinstellung für \PName{BCOR} ist 0\Unit{pt}. Soll hingegen die aktuell, +Die Voreinstellung für \PName{BCOR} ist 0\Unit{pt}. Soll hingegen die aktuelle, beispielsweise per Option \DescRef{\LabelBase.option.BCOR}\IndexOption{BCOR} eingestellte Bindekorrektur erhalten bleiben, sollte man den symbolischen Wert \PValue{current} als optionales Argument verwenden. @@ -1530,7 +1581,7 @@ eingestellte Bindekorrektur erhalten bleiben, sollte man den symbolischen Wert \else % Soll stattdessen ein Gedichtband mit quadratischem Textbereich der Seitenlänge 15\Unit{cm} und einem Binderand von 1\Unit{cm} gesetzt - werden, so ist folgendes möglich: + werden, so ist Folgendes möglich: % \fi \begin{lstcode} @@ -1563,7 +1614,7 @@ zuletzt per \DescRef{\LabelBase.cmd.areaset} eingestellt wurde.% \iftrue% Umbruchkorrekturtext: Alternativen Wenn Sie konkrete Vorgaben bezüglich der Ränder zu erfüllen haben, ist \Package{typearea} nicht geeignet. In diesem Fall ist die Verwendung des -Paketes +Pakets \Package{geometry}\IndexPackage{geometry}\important{\Package{geometry}} (siehe \cite{package:geometry}) empfehlenswert. % @@ -1631,16 +1682,16 @@ deaktiviert sein. Zusätzlich kann das \PName{Format} auch in der Form \PName{Breite}\texttt{:}\PName{Höhe}\ChangedAt{v3.01b}{\Package{typearea}}% -\important{\OptionVName{paper}\PName{Breite}\texttt{:}{Höhe}} -beziehungsweise +\important{\OptionVName{paper}{Breite\textup{:}Höhe}} beziehungsweise \PName{Höhe}\texttt{:}\PName{Breite}\ChangedAt{v3.22}{\Package{typearea}}% -\important{\OptionVName{paper}{Höhe}\texttt{:}\PName{Breite}} angegeben +\important{\OptionVName{paper}{Höhe\textup{:}Breite}} angegeben werden. Welcher Wert die \PName{Höhe} und welcher die \PName{Breite} ist, richtet sich nach der Ausrichtung des Papiers. Mit \OptionValue{paper}{landscape} oder \OptionValue{paper}{seascape} ist der kleinere Wert die \PName{Höhe} und der größere Wert die \PName{Breite}. Mit -\OptionValue{paper}{portrait} ist dagegen der kleinere Wert die \PName{Breite} -und der größere Wert die \PName{Höhe}. +\OptionValue{paper}{portrait}\important{\OptionValue{paper}{portrait}} ist +dagegen der kleinere Wert die \PName{Breite} und der größere Wert die +\PName{Höhe}. Es\textnote{Achtung!} wird darauf hingewiesen, dass bis Version~3.01a der erste Wert immer die \PName{Höhe} und der zweite Wert die \PName{Breite} @@ -1686,8 +1737,9 @@ Kompatibilit \end{Example} In der Voreinstellung wird bei \KOMAScript{} mit A4-Papier in der Ausrichtung -portrait gearbeitet. Dies ist ein Unterschied zu den Standardklassen, bei denen -in der Voreinstellung das amerikanische Format letter verwendet wird. +portrait gearbeitet. Dies ist ein Unterschied\textnote{\KOMAScript{} + vs. Standardklassen} zu den Standardklassen, bei denen in der Voreinstellung +das amerikanische Format letter verwendet wird. Bitte beachten Sie unbedingt\textnote{Achtung!}, dass diese Option bei Verwendung einer der \KOMAScript-Klassen als Klassenoption oder per @@ -1699,11 +1751,12 @@ der Anweisung \DescRef{\LabelBase.cmd.KOMAoptions}\textnote{keine automatische \Package{typearea} führt nicht zu einer automatischen Neuberechnung des Satzspiegels. Vielmehr wirkt sich die Änderung erst bei der nächsten Neuberechnung des Satzspiegels aus. Zur Neuberechnung des Satzspiegels siehe -Option \DescRef{\LabelBase.option.DIV} mit den Werten \PValue{last} oder -\PValue{current} (siehe \DescPageRef{typearea.option.DIV.last}) oder die -Anweisung \DescRef{\LabelBase.cmd.recalctypearea} (siehe +Option \hyperref[desc:\LabelBase.option.DIV.last]{\Option{DIV}} mit den Werten +\hyperref[desc:\LabelBase.option.DIV.last]{\PValue{last}} oder +\hyperref[desc:\LabelBase.option.DIV.current]{\PValue{current}} (siehe +\DescPageRef{typearea.option.DIV.last}) oder die Anweisung +\DescRef{\LabelBase.cmd.recalctypearea} (siehe \DescPageRef{typearea.cmd.recalctypearea}).% -% \EndIndexGroup @@ -1713,29 +1766,39 @@ Anweisung \DescRef{\LabelBase.cmd.recalctypearea} (siehe \begin{Explain}% Die oben genannten Mechanismen zur Auswahl des Papierformats haben nur insofern einen Einfluss auf die Ausgabe, als interne {\LaTeX}-Maße gesetzt - werden. Das \Package{typearea} verwendet diese dann bei der Auf"|teilung der - Seite in Ränder und Textbereich. Die Spezifikation des + werden. Das Paket \Package{typearea} verwendet diese dann bei der + Auf"|teilung der Seite in Ränder und Textbereich. Die Spezifikation des DVI-Formats\Index{DVI} sieht aber an keiner Stelle Angaben zum Papierformat - vor. Wird direkt aus dem DVI-Format in eine Low-Level-Druckersprache wie - PCL% - \iftrue% Umbruchkorrektur - \footnote{PCL ist die Druckersprache, die HP für seine Tinten- und - Laserdrucker verwendet.}% - \fi \ oder ESC/P2% - \iftrue% Umbruchkorrektur - \footnote{ESC/P2 ist die Druckersprache, die EPSON für seine Nadel-, Tinten- - und Laserdrucker benutzt.}% - \fi \ ausgegeben, spielt dies normalerweise keine Rolle, da auch bei diesen - Ausgaben der 0-Bezugspunkt wie bei DVI links oben liegt. Wird aber in - Sprachen wie PostScript\Index{PostScript} oder PDF\Index{PDF} übersetzt, bei - denen der 0-Bezugspunkt an anderer Stelle liegt und außerdem das - Papierformat in der Ausgabedatei angegeben werden sollte, so fehlt diese + vor. % + \iffree{% + Wird direkt aus dem DVI-Format in eine Low-Level-Druckersprache wie PCL% + \iftrue% Umbruchkorrektur + \footnote{PCL ist eine Familie von Druckersprachen, die HP für seine + Tinten- und Laserdrucker verwendet.}% + \fi \ oder ESC/P2% + \iftrue% Umbruchkorrektur + \footnote{ESC/P2 ist die Druckersprache, die EPSON für seine 24-Nadel- und + ältere Tinten- oder Laserdrucker benutzt.}% + \fi \ beziehungsweise ESC/P-R% + \iftrue% Umbruchkorrektur + \footnote{ESC/P-R ist die Druckersprache, die EPSON aktuell für Tinten- + und Laserdrucker benutzt.}% + \fi \ ausgegeben, spielt dies normalerweise keine Rolle% + }{% + In früheren Zeiten, als DVI zum Ausruck noch direkt in + Low-Level-Druckersprachen übertragen wurde, spielte dies keine Rolle% + }, da auch bei diesen Ausgaben der 0-Bezugspunkt wie bei DVI links oben + liegt. \iffree{Wird aber}{Heutzutage wird aber meist} in Sprachen wie + PostScript\Index{PostScript} oder PDF\Index{PDF} übersetzt, bei denen der + 0-Bezugspunkt an anderer Stelle liegt und außerdem das Papierformat in der + Ausgabedatei angegeben werden sollte\iffree{, so}{. Dabei} fehlt diese Information. Als Lösung des Problems verwendet der entsprechende Treiber eine voreingestellte Papiergröße, die der Anwender entweder per Option oder durch entsprechende Angabe in der {\TeX}-Quelldatei verändern kann. Bei Verwendung des DVI-Treibers \File{dvips} oder \File{dvipdfm} kann diese - Angabe in Form einer \Macro{special}-Anweisung erfolgen. Bei {pdf\TeX} oder - {V\TeX} werden stattdessen zwei Längen entsprechend gesetzt. + Angabe in Form einer \Macro{special}-Anweisung erfolgen. Bei Verwendung von + {pdf\TeX}, {lua\TeX}, {\XeTeX} oder {V\TeX} werden deren + Papierformat-Längen entsprechend gesetzt.% \end{Explain} Mit der Option \Option{pagesize} kann eingestellt werden, für welchen Ausgabetreiber die Papiergröße in das Ausgabedokument geschrieben wird. Die @@ -1750,25 +1813,32 @@ entspricht \OptionValue{pagesize}{auto}. \begin{desctabular} \pventry{auto}{Falls die pdf\TeX-spezifischen Register \Macro{pdfpagewidth}\IndexLength{pdfpagewidth} und - \Macro{pdfpageheight}\IndexLength{pdfpageheight} vorhanden sind, wird + \Macro{pdfpageheight}\IndexLength{pdfpageheight} oder die + lua\TeX-spezifischen Register \Macro{pagewidth}\IndexLength{pagewidth} + und \Macro{pageheight}\IndexLength{pageheight} vorhanden sind, wird der Ausgabetreiber \PValue{pdftex} aktiviert. Zusätzlich wird auch der - Ausgabetreiber \PValue{dvips} verwendet.\IndexOption{pagesize~=\PValue{auto}}}% + Ausgabetreiber \PValue{dvips} + verwendet. Diese Einstellung ist grundsätzlich auch für \XeTeX{} + geeignet.% + \IndexOption{pagesize~=\textKValue{auto}}}% \pventry{automedia}{Dies entspricht dem Ausgabetreiber \PValue{auto}. Allerdings werden zusätzlich auch noch die \mbox{V\TeX}-spezifischen Register \Macro{mediawidth}\IndexLength{mediawidth} und \Macro{mediaheight}\IndexLength{mediaheight} gesetzt, falls diese - definiert sind.\IndexOption{pagesize~=\PValue{automedia}}}% + definiert sind.% + \IndexOption{pagesize~=\textKValue{automedia}}}% \entry{\PValue{false}, \PValue{no}, \PValue{off}}{% Die Papiergröße wird nicht an den Ausgabetreiber - gemeldet.\IndexOption{pagesize~=\PValue{false}}}% + gemeldet.% + \IndexOption{pagesize~=\textKValue{false}}}% \pventry{dvipdfmx}{\ChangedAt{v3.05a}{\Package{typearea}}Die Papiergröße wird als \Macro{special}\PParameter{pagesize=\PName{Breite},\PName{Höhe}} in die DVI-Datei geschrieben. Der Name des Ausgabetreibers kommt daher, dass das Programm \File{dvipdfmx} eine Pa\-pier\-for\-mat\-um\-schal\-tung - über diese Anweisung auch innerhalb des Dokuments - erlaubt.\IndexOption{pagesize~=\PValue{dvipdfmx}}}% + über diese Anweisung auch innerhalb des Dokuments erlaubt.% + \IndexOption{pagesize~=\textKValue{dvipdfmx}}}% \pventry{dvips}{Bei Verwendung innerhalb der Dokumentpräambel wird die Papiergröße über \Macro{special}\PParameter{pagesize=\PName{Breite},\PName{Höhe}} in das @@ -1778,12 +1848,19 @@ entspricht \OptionValue{pagesize}{auto}. Umschaltung nach Möglichkeit dennoch zu erreichen. Pa\-pier\-for\-mat\-um\-schal\-tung nach der Dokumentprämbel bei gleichzeitiger Verwendung des Ausgabetreibers \PValue{dvips} - erfolgen daher auf eigene Gefahr!\IndexOption{pagesize~=\PValue{dvips}}}% - \pventry{pdftex}{Die Papiergröße wird über die pdf\TeX-spezifischen - Register \Macro{pdfpagewidth}\IndexLength{pdfpagewidth} und - \Macro{pdfpageheight}\IndexLength{pdfpageheight} gesetzt. Dies ist + erfolgen daher auf eigene Gefahr!% + \IndexOption{pagesize~=\textKValue{dvips}}}% + \entry{\PValue{pdftex}, \PValue{luatex}}{% + \ChangedAt{v3.20}{\Package{typearea}}Die Papiergröße + wird über die pdf\TeX-spezifischen Register + \Macro{pdfpagewidth}\IndexLength{pdfpagewidth} und + \Macro{pdfpageheight}\IndexLength{pdfpageheight} oder die + lua\TeX-spezifischen Register \Macro{pagewidth}\IndexLength{pagewidth} + und \Macro{pageheight}\IndexLength{pageheight} gesetzt. Dies ist auch jederzeit innerhalb des Dokuments problemlos - möglich.\IndexOption{pagesize~=\PValue{pdftex}}}% + möglich.% + \IndexOption{pagesize~=\textKValue{pdftex}}% + \IndexOption{pagesize~=\textKValue{luatex}}}% \end{desctabular} \label{tab:typearea.outputdriver} \end{table} @@ -1792,7 +1869,9 @@ entspricht \OptionValue{pagesize}{auto}. Angenommen, es soll ein Dokument sowohl als DVI-Datei verwendet werden, als auch eine Online-Version im PDF-Format erstellt werden. Dann könnte die Präambel beispielsweise so beginnen: -\begin{lstcode} + \begin{lstcode}[% + aboveskip=.5\baselineskip plus .1\baselineskip minus .1\baselineskip,% + belowskip=.4\baselineskip plus .1\baselineskip minus .1\baselineskip] \documentclass{article} \usepackage[paper=A4,pagesize]{typearea} \end{lstcode} @@ -1803,48 +1882,56 @@ entspricht \OptionValue{pagesize}{auto}. {pdf\LaTeX} --, so wird ein \Macro{special} an den Anfang dieser Datei geschrieben. \end{Example}% +\iffree{% Die Empfehlung ist eigentlich überholt. Wer derart alte Versionen + % von typearea verwendet, ist selbst schuld. Es wird empfohlen\textnote{Achtung!}, die Option \Option{pagesize} immer anzugeben, weil frühere Versionen von \Package{typearea} sie noch nicht als Voreinstellung gesetzt haben. In der Regel ist dabei die Methode ohne \PName{Ausgabetreiber} oder mit \PValue{auto} oder \PValue{automedia} günstig.% +}{% + \vskip-1\ht\strutbox plus .75\ht\strutbox% Wegen Beispiel am Ende der Erklärung +} \EndIndexGroup % \EndIndexGroup - +% Umbruchverbesserung: +%\iffree{}{\clearpage} \section{Tipps} \seclabel{tips} Insbesondere für die Erstellung von schriftlichen Arbeiten während des -Studiums findet man häufig Vorschriften, die einer typografischen Begutachtung -nicht nur in keiner Weise standhalten, sondern massiv gegen alle Regeln der -Typografie verstoßen. Ursache für solche Regeln ist oft typografische -Inkompetenz derjenigen, die sie herausgeben. Manchmal ist die Ursache auch im +Studiums findet man häufig Vorschriften\textnote{Satzvorschriften + vs. gute~Typografie}, die einer typografischen Begutachtung nicht nur in +keiner Weise standhalten, sondern massiv gegen alle Regeln der Typografie +verstoßen. Ursache für solche Regeln ist oft typografische Inkompetenz +derjenigen, die sie herausgeben. Manchmal ist die Ursache auch im Ausgangspunkt begründet, nämlich der Schreibmaschine. Mit einer -Schreibmaschine oder einer Textverarbeitung von 1980 ist es ohne erheblichen -Aufwand kaum möglich, typografisch perfekte Ergebnisse zu erzielen. Also -wurden einst Vorschriften erlassen, die leicht erfüllbar schienen und dem -Korrektor trotzdem entgegenkommen. Dazu zählen dann Randeinstellungen, die -für einseitigen Druck mit einer Schreibmaschine zu brauchbaren Zeilenlängen -führen. Um nicht extrem kurze Zeilen zu erhalten, die durch Flattersatz zudem -verschlimmert werden, werden die Ränder schmal gehalten und für Korrekturen -stattdessen ein großer Durchschuss in Form von eineinhalbzeiligem Satz -vorgeschrieben. Bevor moderne Textverarbeitungssysteme verfügbar wurden, wäre --- außer mit {\TeX} -- einzeiliger Satz die einzige Alternative gewesen. Dabei -wäre dann selbst das Anbringen von Korrekturzeichen schwierig geworden. Als -die Verwendung von Computern für die Erstellung schriftlicher Arbeiten -üblicher wurde, hat sich manches Mal auch der Spieltrieb des einen oder -anderen Studenten gezeigt, der durch Verwendung einer Schmuckschrift seine -Arbeit aufpeppen und so eine bessere Note mit weniger Einsatz herausschinden -wollte. Nicht bedacht hat er dabei, dass solche Schriften schlechter zu lesen -und deshalb für den Zweck ungeeignet sind. Damit hielten zwei Brotschriften -Einzug in die Vorschriften, die weder zusammenpassen noch im Falle von Times -wirklich gut geeignet sind. Times ist eine relativ enge Schrift, die Anfang -des 20.~Jahrhunderts speziell für schmale Spalten im englischen Zeitungssatz -entworfen wurde. In modernen Schnitten ist dies etwas entschärft. Dennoch -passt die häufig vorgeschriebene Times meist nicht zu den gleichzeitig -gegebenen Randvorgaben. +Schreibmaschine oder einer Textverarbeitung von 1980 ist es +ohne +erheblichen Aufwand kaum möglich, typografisch perfekte Ergebnisse zu +erzielen. Also wurden einst Vorschriften erlassen, die leicht erfüllbar +schienen und dem Korrektor trotzdem entgegenkommen. Dazu zählen dann +Randeinstellungen, die für einseitigen Druck mit einer Schreibmaschine zu +brauchbaren Zeilenlängen führen. Um nicht extrem kurze Zeilen zu erhalten, die +durch Flattersatz zudem verschlimmert werden, werden die Ränder schmal +gehalten und für Korrekturen stattdessen ein großer Durchschuss in Form von +eineinhalbzeiligem Satz vorgeschrieben. Bevor moderne +Textverarbeitungssysteme verfügbar wurden, wäre -- außer mit {\TeX} -- +einzeiliger Satz die einzige Alternative gewesen. Dabei wäre dann selbst das +Anbringen von Korrekturzeichen schwierig geworden. Als die Verwendung von +Computern für die Erstellung schriftlicher Arbeiten üblicher wurde, hat sich +manches Mal auch der Spieltrieb des einen oder anderen Studenten gezeigt, der +durch Verwendung einer Schmuckschrift seine Arbeit aufpeppen und so eine +bessere Note mit weniger Einsatz herausschinden wollte. Nicht bedacht hat er +dabei, dass solche Schriften schlechter zu lesen und deshalb für den Zweck +ungeeignet sind. Damit hielten zwei Brotschriften Einzug in die Vorschriften, +die weder zusammenpassen noch im Falle von Times wirklich gut geeignet +sind. Times ist eine relativ enge Schrift, die Anfang des 20.~Jahrhunderts +speziell für schmale Spalten im englischen Zeitungssatz entworfen wurde. In +modernen Schnitten ist dies etwas entschärft. Dennoch passt die häufig +vorgeschriebene Times meist nicht zu den gleichzeitig gegebenen Randvorgaben. {\LaTeX} setzt bereits von sich aus mit ausreichendem Durchschuss. Gleichzeitig sind die Ränder bei sinnvollen Zeilenlängen groß genug, um Platz @@ -1879,46 +1966,54 @@ gerecht. Wenn Sie also mit Vorschriften konfrontiert sind, die offensichtlich erheblich davon abweichen, so empfehle ich, dem Betreuer einen Textauszug vorzulegen und nachzufragen, ob es gestattet ist, die Arbeit trotz der Abweichungen in dieser Form zu liefern. Gegebenenfalls kann durch Veränderung -der Option \DescRef{\LabelBase.option.DIV} der Satzspiegel moderat angepasst -werden. Von der Verwendung von \DescRef{\LabelBase.cmd.areaset} zu diesem -Zweck rate ich jedoch ab. Schlimmstenfalls verwenden Sie das nicht zu -{\KOMAScript} gehörende \Package{geometry}-Paket (siehe -\cite{package:geometry}) oder verändern Sie die Satzspiegelparameter von -{\LaTeX} selbst. Die von \Package{typearea} ermittelten Werte finden Sie in -der \File{log}-Datei Ihres Dokuments. Damit sollten moderate Anpassungen -möglich sein. Achten Sie jedoch unbedingt darauf, dass die Proportionen des -Textbereichs mit denen der Seite unter Berücksichtigung der Bindekorrektur -annähernd übereinstimmen. +der Option +\DescRef{\LabelBase.option.DIV}\important{\DescRef{\LabelBase.option.DIV}} der +Satzspiegel moderat angepasst werden. Von der Verwendung von +\DescRef{\LabelBase.cmd.areaset} zu diesem Zweck rate ich jedoch +ab. Schlimmstenfalls verwenden Sie das nicht zu {\KOMAScript} gehörende +\Package{geometry}-Paket\important{\Package{geometry}}\IndexPackage{geometry} +(siehe \cite{package:geometry}) oder verändern Sie die Satzspiegelparameter +von {\LaTeX} selbst. Die von \Package{typearea} ermittelten Werte finden Sie +in der \File{log}-Datei Ihres Dokuments. Mit Hilfe von Option +\DescRef{typearea-experts.option.usegeometry}% +\important{\DescRef{typearea-experts.option.usegeometry}}, die Sie in +\autoref{part:forExperts} finden, kann außerdem die Zusammenarbeit von +\Package{typearea} und \Package{geometry} verbessert werden. Damit sollten +moderate Anpassungen möglich sein. Achten Sie jedoch unbedingt darauf, dass +die Proportionen des Textbereichs mit denen der Seite unter Berücksichtigung +der Bindekorrektur annähernd übereinstimmen. Sollte es unbedingt erforderlich sein, den Text eineinhalbzeilig zu setzen, so definieren Sie keinesfalls \Macro{baselinestretch} um. Dieses Vorgehen wird zwar allzu häufig empfohlen, ist aber seit der Einführung von {\LaTeXe} im Jahre 1994 obsolet. Verwenden Sie schlimmstenfalls den Befehl \Macro{linespread}. Ich empfehle das Paket -\Package{setspace},\IndexPackage{setspace} das nicht zu {\KOMAScript} gehört -(siehe \cite{package:setspace}). Auch sollten Sie \Package{typearea} nach der -Umstellung des Zeilenabstandes den Satzspiegel für diesen Abstand berechnen -lassen, jedoch für den Titel, besser auch für die Verzeichnisse -- sowie das -Literaturverzeichnis und den Index -- wieder auf normalen Satz umschalten. Das -\Package{setspace}-Paket bietet dafür eine spezielle Umgebung und eigene -Befehle. +\Package{setspace}\important{\Package{setspace}}\IndexPackage{setspace}, das +nicht zu {\KOMAScript} gehört (siehe \cite{package:setspace}). Auch sollten +Sie \Package{typearea} nach der Umstellung des Zeilenabstandes den Satzspiegel +für diesen Abstand berechnen lassen, jedoch für den Titel, besser auch für die +Verzeichnisse -- sowie das Literaturverzeichnis und den Index -- wieder auf +normalen Satz umschalten. Näheres dazu finden Sie bei der Erklärung zu +\OptionValueRef{\LabelBase}{DIV}{current}% +\important{\OptionValueRef{\LabelBase}{DIV}{current}}. Das \Package{typearea}-Paket berechnet auch bei der Option -\OptionValueRef{\LabelBase}{DIV}{calc} einen sehr großzügigen +\OptionValueRef{\LabelBase}{DIV}{calc}% +\important{\OptionValueRef{\LabelBase}{DIV}{calc}} einen sehr großzügigen Textbereich. Viele konservative Typografen werden feststellen, dass die resultierende Zeilenlänge noch zu groß ist. Der berechnete \Var{DIV}-Wert ist ebenfalls in der \File{log}-Datei zum jeweiligen Dokument zu finden. Sie können also leicht nach dem ersten \LaTeX-Lauf einen kleineren Wert wählen. -Nicht selten wird mir die Frage gestellt, warum ich eigentlich kapitelweise -auf einer Satzspiegelberechnung herumreite, während es sehr viel einfacher -wäre, nur ein Paket zur Verfügung zu stellen, mit dem man die Ränder wie bei -einer Textverarbeitung einstellen kann. Oft wird auch behauptet, ein solches -Paket wäre ohnehin die bessere Lösung, da jeder selbst wisse, wie gute Ränder -zu wählen seien, und die Ränder von {\KOMAScript} wären ohnehin nicht gut. Ich -erlaube mir zum Abschluss dieses Kapitels ein passendes Zitat von Hans Peter -Willberg und Friedrich Forssmann, zwei der angesehensten Typografen der -Gegenwart (siehe \cite{TYPO:ErsteHilfe}): +Nicht\textnote{Was ist besser?} selten wird mir die Frage gestellt, warum ich +eigentlich kapitelweise auf einer Satzspiegelberechnung herumreite, während es +sehr viel einfacher wäre, nur ein Paket zur Verfügung zu stellen, mit dem man +die Ränder wie bei einer Textverarbeitung einstellen kann. Oft wird auch +behauptet, ein solches Paket wäre ohnehin die bessere Lösung, da jeder selbst +wisse, wie gute Ränder zu wählen seien, und die Ränder von {\KOMAScript} wären +ohnehin nicht gut. Ich erlaube mir zum Abschluss dieses Kapitels ein passendes +Zitat von Hans Peter Willberg und Friedrich Forssmann, zwei der angesehensten +Typografen der Gegenwart (siehe \cite{TYPO:ErsteHilfe}): \begin{quote} \phantomsection\label{sec:typearea.tips.cite}% \textit{Das\textnote{Zitat!} Selbermachen ist längst üblich, die Ergebnisse @@ -1930,6 +2025,8 @@ Gegenwart (siehe \cite{TYPO:ErsteHilfe}): erster Linie um Information geht, können Fehler nicht nur stören, sondern sogar Schaden anrichten.} \end{quote} +% +\EndIndexGroup %%% Local Variables: %%% mode: latex diff --git a/Master/texmf-dist/source/latex/koma-script/doc/scrguide.cls b/Master/texmf-dist/source/latex/koma-script/doc/scrguide.cls index 5abd1e630aa..1929f7493db 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/scrguide.cls +++ b/Master/texmf-dist/source/latex/koma-script/doc/scrguide.cls @@ -1,6 +1,6 @@ % ====================================================================== % scrguide.cls -% Copyright (c) Markus Kohm, 2005-2017 +% Copyright (c) Markus Kohm, 2005-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrguide.cls -% Copyright (c) Markus Kohm, 2005-2017 +% Copyright (c) Markus Kohm, 2005-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -145,14 +145,8 @@ \RequirePackage{multicol} \RequirePackage{marginnote} \RequirePackage{tabularx} -\RequirePackage[svgnames]{xcolor} -\RequirePackage{tocstyle}% hyperref needs xcolor with tocstyle -\RequirePackage{tikz} -\usetikzlibrary{calc} -\RequirePackage[\uselanguage]{hyperref} -\RequirePackage[open,openlevel=0]{bookmark}% improved pdf bookmarks -\RequirePackage{scrhack} -\RequirePackage{mparhack} +\RequirePackage{scrhack}% +\RequirePackage{mparhack}% % \end{macrocode} % % \section{Dependence from \KOMAScript{} Version} @@ -169,84 +163,88 @@ % % \begin{macrocode} \newif\ifshortversion\shortversionfalse -\AtEndOfClass{% - \InputIfFileExists{scrnonfree.tex}{}{% - \typeout{^^J - ----------------------------------------------------------------------^^J - FREE VERSION OF THE KOMA-SCRIPT GUIDE.^^J - NOTE THAT THIS VERSION MAY BE FULL OF UGLY PARAGRAPH AND PAGE BREAKS.^^J - THIS IS BECAUSE THIS VERSION OF THE KOMA-SCRIPT GUIDE IS UNDER^^J - CONSTRUCTION FOREVER.^^J - ----------------------------------------------------------------------^^J - ^^J% - }% - \newcommand*{\iffree}{\@firstoftwo}% - \newcommand*{\important}[2][]{}% - \newcommand*{\textnote}[2][]{}% - \shortversiontrue - \newcommand*{\LoadNonFree}[2]{\par\GuideLoadNonFree\par}% - \AtBeginDocument{\InputIfFileExists{linkalias.tex}{}{}}% - \usepackage{lmodern}% - \@twosidefalse\@openrightfalse\@mparswitchfalse - \RequirePackage{geometry}% - \geometry{papersize={180mm,210mm},% - includehead,includemp,reversemp,marginparwidth=4em,% - vmargin={1.5mm,3mm},hmargin=1.75mm}% - \RequirePackage{scrlayer-scrpage}% - \clearpairofpagestyles - \ihead{% - \smash{% - \hspace*{.5em}\rule[-\dp\strutbox]{0pt}{\headheight}\headmark - }% - }% - \ohead*{\smash{\pagemark\hspace{2mm}}}% - \colorlet{headbackground}{DarkBlue}% - \colorlet{headline}{white}% - \setkomafont{pageheadfoot}{\small\sffamily\bfseries\color{headline}}% - \setkomafont{pagenumber}{}% - \DeclareNewLayer[head,background, - hoffset=0pt, - width=\paperwidth, - addheight=\dimexpr \topmargin+1in+\dp\strutbox\relax, - addvoffset=2\dp\strutbox, - contents={% - \color{headbackground}\rule{\layerwidth}{\layerheight}}] - {headbackground}% - \AddLayersAtBeginOfPageStyle{scrheadings}{headbackground}% - \renewcommand*{\chaptermark}[1]{% - \@mkdouble{\ifnumbered{chapter}{\chaptermarkformat}{}##1}% +\InputIfFileExists{scrnonfree.tex}{}{% + \RequirePackage[svgnames]{xcolor}% + \RequirePackage{tocstyle}% hyperref needs xcolor with tocstyle + \RequirePackage{tikz}% + \usetikzlibrary{calc}% + \RequirePackage[\uselanguage]{hyperref}% + \RequirePackage[open,openlevel=0]{bookmark}% improved pdf bookmarks + \typeout{^^J + ----------------------------------------------------------------------^^J + FREE VERSION OF THE KOMA-SCRIPT GUIDE.^^J + NOTE THAT THIS VERSION MAY BE FULL OF UGLY PARAGRAPH AND PAGE BREAKS.^^J + THIS IS BECAUSE THIS VERSION OF THE KOMA-SCRIPT GUIDE IS UNDER^^J + CONSTRUCTION FOREVER.^^J + ----------------------------------------------------------------------^^J + ^^J% + }% + \newcommand*{\iffree}{\@firstoftwo}% + \newcommand*{\important}[2][]{}% + \newcommand*{\textnote}[2][]{}% + \shortversiontrue + \newcommand*{\LoadNonFree}[2]{\par\GuideLoadNonFree\par}% + \AtBeginDocument{\InputIfFileExists{linkalias.tex}{}{}}% + \usepackage{lmodern}% + \@twosidefalse\@openrightfalse\@mparswitchfalse + \RequirePackage{geometry}% + \geometry{papersize={180mm,210mm},% + includehead,includemp,reversemp,marginparwidth=4em,% + vmargin={1.5mm,3mm},hmargin=1.75mm}% + \RequirePackage{scrlayer-scrpage}% + \clearpairofpagestyles + \ihead{% + \smash{% + \hspace*{.5em}\rule[-\dp\strutbox]{0pt}{\headheight}\headmark }% - \renewcommand*{\chaptermarkformat}{% - \makebox[\dimexpr \oddsidemargin+1in-.5em][r]{% - \chapapp~\thechapter:~% - }% + }% + \ohead*{\smash{\pagemark\hspace{2mm}}}% + \colorlet{headbackground}{DarkBlue}% + \colorlet{headline}{white}% + \setkomafont{pageheadfoot}{\small\sffamily\bfseries\color{headline}}% + \setkomafont{pagenumber}{}% + \DeclareNewLayer[head,background, + hoffset=0pt, + width=\paperwidth, + addheight=\dimexpr \topmargin+1in+\dp\strutbox\relax, + addvoffset=2\dp\strutbox, + contents={% + \color{headbackground}\rule{\layerwidth}{\layerheight}}] + {headbackground}% + \AddLayersAtBeginOfPageStyle{scrheadings}{headbackground}% + \renewcommand*{\chaptermark}[1]{% + \@mkdouble{\ifnumbered{chapter}{\chaptermarkformat}{}##1}% + }% + \renewcommand*{\chaptermarkformat}{% + \makebox[\dimexpr \oddsidemargin+1in-.5em][r]{% + \chapapp~\thechapter:~% }% - \renewcommand*{\chapterformat}{}% - \renewcommand*{\chapterpagestyle}{scrheadings}% - \setlength{\@tempdimc}{\oddsidemargin}% - \addtolength{\@tempdimc}{1in}% - \setheadwidth[-\@tempdimc]{paper}% - % Entweder: - \hypersetup{colorlinks}% - % oder: + }% + \renewcommand*{\chapterformat}{}% + \renewcommand*{\chapterpagestyle}{scrheadings}% + \setlength{\@tempdimc}{\oddsidemargin}% + \addtolength{\@tempdimc}{1in}% + \setheadwidth[-\@tempdimc]{paper}% + % Entweder: + \hypersetup{colorlinks,citecolor=Green,linkcolor=Crimson,urlcolor=Blue}% + % oder: % \hypersetup{pdfborderstyle={/S/U/W 1}}% - \let\orig@maketitle\maketitle - \def\maketitle{% - \begingroup - \@twosidetrue - \let\cleardoublepage\clearpage - \addtolength{\oddsidemargin}{\evensidemargin}% - \setlength{\evensidemargin}{.5\oddsidemargin}% - \setlength{\oddsidemargin}{\evensidemargin}% - \orig@maketitle\relax - \endgroup - }% - \renewcommand*{\chapterheadstartvskip}{}% - \raggedbottom - \sloppy - \lstset{breaklines,prebreak=\mbox{$\hookleftarrow$}}% + \let\orig@maketitle\maketitle + \def\maketitle{% + \begingroup + \@twosidetrue + \let\cleardoublepage\clearpage + \addtolength{\oddsidemargin}{\evensidemargin}% + \setlength{\evensidemargin}{.5\oddsidemargin}% + \setlength{\oddsidemargin}{\evensidemargin}% + \orig@maketitle\relax + \endgroup }% -} + \renewcommand*{\chapterheadstartvskip}{}% + \raggedbottom + \sloppy + \lstset{breaklines,prebreak=\mbox{$\hookleftarrow$}}% +}% % \end{macrocode} % % Now loading the last package (better do it late than never): @@ -576,6 +574,14 @@ % The \KOMAScript{} guide uses a lot of emphasizations. Most of them are % declared robustly to avoid problems at index, change log etc. % +% We need some colors for emphasizing in images: +% \begin{macrocode} +\colorlet{ImageRed}{Crimson}% +\colorlet{ImageBlue}{Blue}% +\colorlet{ImageGreen}{Green}% +\colorlet{ImageYellow}{Yellow}% +% \end{macrocode} +% % \begin{macro}{\textsfrm} % Something like |\emph| using |\textsf| and |\textrm| instead of |\textit| % and |\textup|. @@ -725,7 +731,9 @@ \LabelOption{#1}% \textOption{#1}% } -\DeclareSpecialMarkup{\KOption}{\mbox{\textOption{#1=}}\linebreak[0]}{% +\DeclareSpecialMarkup{\KOption}{% + \mbox{\textOption{#1=}}\linebreak[0]% +}{% \ClassWarning{scrguide}{You should replace \string\KOption{#1}\string\PName{...}\MessageBreak by \string\OptionVName{#1}{...}}% @@ -845,6 +853,35 @@ \label{\label@desc@prefix\label@base.option.#2=#3#1}% \endgroup } +% \end{macrocode} +% \begin{macro}{\OptionVNameRef} +% \cs{OptionVName} by reference. Use it like +% |\OptionVNameRef[suffix]{maincls}{version}{value}|. +% \begin{macrocode} +\newcommand*{\OptionVNameRef}{% + \kernel@ifstar {\@RefOptionVName0}{\@RefOptionVName1}% +} +\newcommand*{\@RefOptionVName}[1]{% + \kernel@ifnextchar [%] + {\@@RefOptionVName#1}{\@@RefOptionVName#1[]}% +} +\newcommand*{\@@RefOptionVName}{} +\def\@@RefOptionVName#1[#2]#3#4#5{% + \scr@ifundefinedorrelax{r@\label@desc@prefix#3.option.#4=#5#2}{% + \ifcase #1 + \expandafter\scr@no@hyperref + \else + \expandafter\hyperref + \fi + [\label@desc@prefix#3.option.#4#2]% + {\OptionVName{\ref*{\label@desc@prefix#3.option.#4#2}}{#5}}% + }{% + \expandafter\ref\ifcase #1 *\fi{\label@desc@prefix#3.option.#4=#5#2}% + }% +} +% \end{macrocode} +% \end{macro} +% \begin{macrocode} \newcommand*{\DescOptionVName}[2]{% \par \leftskip\z@ @@ -872,7 +909,7 @@ } \newcommand*{\LabelPageStyle}[2][\label@suffix]{% \begingroup - \protected@edef\@currentlabel{\FloatStyle{#2}}% + \protected@edef\@currentlabel{\PageStyle{#2}}% \label@sanitize \Hy@MakeCurrentHref{\label@desc@prefix\label@base.pagestyle.#2#1}% \ClassInfo{scrguide}{Anchor: `\@currentHref'}% @@ -1848,16 +1885,22 @@ \lstdefinestyle{code}{% language=[LaTeX]TeX,% moretexcs={% - @auxout, @currext, @dottedtocline, @empty, @float, @ifpackagelater, + @auxout,@currext,@dottedtocline,@empty,@float,@hangfrom,@ifpackagelater, @ifundefined, - @rightmark, @secondoftwo, @tempswafalse,@tempswatrue, @undefined, + @rightmark,@secondoftwo, + @tempskipa,@tempdima,@tempswafalse,@tempswatrue, + @undefined, AtBeginDocument,AtEndDocument, appendix, ClassWarningNoLine,CurrentOption, color,colorbox, - DeclareOption,DeclareRobustCommand,dimexpr, end@float, ExecuteOptions, - if@filesw,if@tempswa,if@twoside, includegraphics, MessageBreak, + DeclareOption,DeclareRobustCommand,dimexpr,end@float,ExecuteOptions, + gluexpr, + if@filesw,if@tempswa,if@twoside,includegraphics, + MessageBreak, + numexpr, onehalfspacing, PackageError,PackageInfo,PackageWarning,PassOptionsToPackage, - ProcessOptions,protected@write,ProvidesFile,ProvidesPackage, + ProcessOptions,protected@edef,protected@write, + ProvidesFile,ProvidesPackage, providecommand, RequirePackage,RequirePackageWithOptions,setkey,setlength, SelectInputMappings,setkeys, @@ -1885,11 +1928,15 @@ blinddocument,blindtext,Blinddocument,Blindtext, cc,captionabove,captionaboveof,captionbelow,captionbelowof,captionformat, captionof,cefoot,cfoot,chapapp, chapappifchapterprefix, + chapterheadstartvskip,chapterheadmidvskip,chapterheadendvskip, chapter,chapterlinesformat,chapterlineswithprefixformat, - chapterformat,chaptermarkformat,chapterpagestyle,chead, + chapterformat,chaptermarkformat,chapternumdepth,chaptertocdepth, + chapterpagestyle,chead, Clause, - cleardoubleevenemptypage,clearscrheadfoot,closing,cofoot,Comment, + cleardoubleevenemptypage,cleardoubleoddpage, + clearscrheadfoot,closing,cofoot,Comment, CloneTOCEntryStyle, + DeclareNewJuraEnvironment, DeclareLayer,DeclareNewLayer,DeclareNewPageStyleByLayers, DeclarePageStyleByLayers, DeclareTOCStyleEntry,DeclareTOCEntryStyle, @@ -1897,8 +1944,11 @@ DeclareNewTOC,DeclareSectionCommand,DeclareNewSectionCommand, RedeclareSectionCommand,ProvideSectionCommand, dedication,defcaptionname,deffootnote,deffootnotemark, - DefineFamily,DefineFamilyKey, - DefineFamilyMember,DestroyLayer,defpagestyle,deftripstyle, + DefineFamily,DefineFamilyKey,DefineFamilyMember, + DefineTOCEntryOption,DefineTOCEntryBooleanOption, + DefineTOCEntryCommandOption,DefintTOCEntryIfOption, + DefineTOCEntryLengthOption,DefineTOCEntryNumberOption, + DestroyLayer,defpagestyle,deftripstyle, dictum,dictumauthorformat,dictumrule,dictumwidth,doforeachtocfile, ellipsispar, encl,extratitle,FamilyBoolKey,FamilyExecuteOptions, @@ -1906,7 +1956,7 @@ FamilyKeyStateUnknownValue,FamilyKeyStateNeedValue, FamilyNumericalKey,% FamilyOption,FamilyOptions,FamilyProcessOptions,FamilySetBool, - FamilyStringKey, + FamilyStringKey,FamilyUnknownKeyValue, figureformat,figurename,firstfoot,firsthead,FirstName,footfont,footref, ForEachLayerOfPageStyle, FreeI,FreeII,FreeIII,FreeIV, @@ -1915,7 +1965,8 @@ ifundefinedorrelax, ifattoclist,ifoot,ihead,ifkomavarempty,ifstr,ifthispageodd,InputAddressFile, KOMAoption,KOMAoptions,KOMAScript, l@addto@macro, - LastName,layerwidth,layerheight,lefoot,lehead,LetterOptionNeedsPapersize, + LastName,layerwidth,layerheight,lefoot,lefttopmark,leftbotmark, + leftfirstmark,lehead,LetterOptionNeedsPapersize, LenToUnit, lipsum,listoffigures, listoftables,listoftoc,LoadLetterOption,lofoot,lohead,lowertitleback, @@ -1924,23 +1975,34 @@ Name,nameday,newbibstyle,newcaptionname,newkomavar,nexthead, ofoot,ohead,opening,othersectionlevelsformat, p@section,pagemark,paragraphformat,subparagraphformat, + paragraphnumdepth,paragraphtocdepth, + subparagraphnumdepth,subparagraphtocdepth, parellipsis,parformat,parname,parshortname, - part,partformat,partname,partpagestyle,pnumfont, + part,partformat,partlineswithprefixformat, + partname,partnumdepth,partpagestyle,partnumdepth, + partheadstartvskip,partheadmidvskip,partheadendvskip, + pnumfont, PreventPackageFromLoading,providecaptionname,publishers,ps, putLL,putLR,putUL,putUR,putC, - raggedsection,raggedpart,raggedsignature,recalctypearea, + raggedcaption,raggedchapter,raggedfootnote,raggedsection,raggedpart, + raggedsignature, + recalctypearea, refL,refS,refN,refoot, refParagraph,refParagraphN,refPar,refParL,refParS,refParN, refSentence,refSentenceL,refSentenceS,refSentenceN,rehead, RelaxFamilyKey, removereffields,renewcaptionname, - RedeclarePageStyleAlias, + RedeclarePageStyleAlias,RedeclareTOCStyleEntry, ReplaceInput,ReplacePackage,ResetPreventPackageFromLoading, + rightbotmark,righttopmark,rightfirstmark, rohead, sectionformat,subsectionformat,subsubsectionformat, + sectionnumdepth,sectiontocdepth, + subsectionnumdepth,subsectiontocdepth, + subsubsectionnumdepth,subsubsectiontocdepth, sectionmarkformat,sectioncatchphraseformat,sectionlinesformat, Sentence,sentencename,sentenceshortname, - setbibpreamble,setcapindent,setcapwidth, + setbibpreamble,setcapindent,setcapwidth,setcaptionalignment, setchapterpreamble,setfootbotline,setfootsepline,setfootwidth, setheadsepline,setheadtopline,setheadwidth,setindexpreamble,setkomafont, setkomavar,setlengthtoplength,setparsizes,setpartpreamble,setuptoc, @@ -2004,16 +2066,18 @@ KOMAScript \endcsname % We have to setup \textsf{hyperref}: % \begin{macrocode} \AtBeginDocument{% - \hypersetup{% - plainpages=false, - pdftitle={\GuideTitle}, - pdfauthor={Markus Kohm, Jens-Uwe Morawski}, - pdfsubject={\GuideSubject}, - pdfkeywords={\KOMAScript, scrbook, scrreprt, scrartcl, - typearea, scrlfile, - scrpage, scrpage2, scrlettr, scrlttr2, scraddr, scrtime, scrdate}, - pdfcreator={\KOMAScript, hyperref} - }% + \iffree{% + \hypersetup{% + plainpages=false, + pdftitle={\GuideTitle}, + pdfauthor={Markus Kohm}, + pdfsubject={\GuideSubject}, + pdfkeywords={\KOMAScript, scrbook, scrreprt, scrartcl, + typearea, scrlfile, scrlayer, scrlayer-scrpage, scrlayer-notecolumn, + scrletter, scrlttr2, scraddr, scrtime, scrdate, scrwfile}, + pdfcreator={\KOMAScript, hyperref} + }% + }{}% } % \end{macrocode} % @@ -2092,6 +2156,18 @@ KOMAScript \endcsname % \end{macrocode} % % +% \section{Logos} +% +% I don't want to use package \textsf{hologo} for only one logo: +% \begin{macrocode} +\DeclareRobustCommand{\XeTeX}{% + X\kern-.125em\lower.5ex\hbox{\reflectbox{E}}\kern-.10em\TeX% +}% +\DeclareRobustCommand{\XeLaTeX}{% + X\kern-.125em\lower.5ex\hbox{\reflectbox{E}}\kern-.10em\LaTeX% +}% +% \end{macrocode} +% % \section{Appendix} % % \begin{macro}{\appendix} diff --git a/Master/texmf-dist/source/latex/koma-script/doc/scrguide.html b/Master/texmf-dist/source/latex/koma-script/doc/scrguide.html index 91c68657257..68ad75018df 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/scrguide.html +++ b/Master/texmf-dist/source/latex/koma-script/doc/scrguide.html @@ -10,967 +10,975 @@

  • Optionen
  • Anweisungen
  • Umgebungen
  • Längen
  • Pseudolängen
  • Variablen
  • Seitenstile
  • Zähler
  • Stile für das float-Paket
  • Optionen

    Anweisungen

    Umgebungen

    Längen

    Pseudolängen

    Variablen

    Seitenstile

    Zähler

    Stile für das float-Paket

    Options

  • Commands
  • Environments
  • Lengths
  • Pseudolengths
  • Variables
  • Page Styles
  • Counter
  • Styles for the float Package
  • Options

    Commands

    Environments

    Lengths

    Pseudolengths

    Variables

    Page Styles

    Counter

    Styles for the float Package

    %%% using: package,identify %%%% using: package,option %%%% using: package,body @@ -71,7 +71,7 @@ \ifx\ProvidesFile\undefined\def\ProvidesFile#1[#2]{}\fi \begingroup \def\filedate$#1: #2-#3-#4 #5${\gdef\filedate{#2/#3/#4}} - \filedate$Date: 2017-07-24 21:31:57 +0200 (Mon, 24 Jul 2017) $ + \filedate$Date: 2018-03-16 09:39:32 +0100 (Fri, 16 Mar 2018) $ \def\filerevision$#1: #2 ${\gdef\filerevision{r#2}} \filerevision$Revision: 1962 $ \endgroup @@ -837,7 +837,19 @@ Note: If you want to use \Package{setspace} with package option \@ifundefined{ext@#1}{\float@error{#1}}{% \@ifundefined{l@#1}{\expandafter\let\csname l@#1\endcsname\l@figure \@ifundefined{l@#1}{% - \@namedef{l@#1}{\@dottedtocline{1}{1.5em}{2.3em}}}{}% +% \end{macrocode} +% \changes{v3.25}{2018/03/16}{Verwendung von \cs{DeclareTOCStyleEntry}}^^A +% Bis Version 3.24 wurde hier nun wie üblich |\l@#1| unter Verwendung von +% \cs{@dottedtocline} definiert: +% \begin{verbatim} +% \@namedef{l@#1}{\@dottedtocline{1}{1.5em}{2.3em}}% +% \end{verbatim} +% Da aber \Package{tocbasic} inzwischen diese schöne Schnittstelle für die +% Verzeichniseinträge bietet, verwenden wir die hier nun auch: +% \begin{macrocode} + \DeclareTOCStyleEntry[level=1,numwidth=2.3em,indent=1.5em] + {default}{#1}% + }{}% }{}% \listoftoc[{#2}]{\csname ext@#1\endcsname}% }% @@ -961,7 +973,17 @@ Note: If you want to use \Package{setspace} with package option {\expandafter\noexpand\csname #1name\endcsname\nobreakspace \expandafter\noexpand\csname the#1\endcsname}% \@namedef{the#1}{\arabic{#1}}\flnew@ext{lo#1}\@namedef{fps@#1}{tbp}% - \@namedef{l@#1}{\@dottedtocline{1}{1.5em}{2.3em}}% +% \end{macrocode} +% \changes{v3.25}{2018/03/16}{Verwendung von \cs{DeclareTOCStyleEntry}}^^A +% Bis Version 3.24 wurde hier nun wie üblich |\l@#1| unter Verwendung von +% \cs{@dottedtocline} definiert: +% \begin{verbatim} +% \@namedef{l@#1}{\@dottedtocline{1}{1.5em}{2.3em}}% +% \end{verbatim} +% Da aber \Package{tocbasic} inzwischen diese schöne Schnittstelle für die +% Verzeichniseinträge bietet, verwenden wir die hier nun auch: +% \begin{macrocode} + \DeclareTOCStyleEntry[level=1,numwidth=2.3em,indent=1.5em]{default}{#1}% \caption@setkeys[floatrow]{newfloat}{#2}\let\FR@tmp=\relax \xdef\@tempa{\noexpand\flrow@types{\the\flrow@types \FR@tmp{#1}}}% \@tempa @@ -975,7 +997,12 @@ Note: If you want to use \Package{setspace} with package option \@ifundefined{ext@#1}{\flrow@error{Unknown float style `#1'}}{% \@ifundefined{l@#1}{\expandafter\let\csname l@#1\endcsname\l@figure \@ifundefined{l@#1}{% - \@namedef{l@#1}{\@dottedtocline{1}{1.5em}{2.3em}}}{}% +% \end{macrocode} +% Siehe die Anmerkung zur Verwendung von \cs{DeclareTOCStyleEntry} oben. +% \begin{macrocode} + \DeclareTOCStyleEntry[level=1,numwidth=2.3em,indent=1.5em] + {default}{#1}% + }{}% }{}% \listoftoc[{#2}]{\csname ext@#1\endcsname}% }% diff --git a/Master/texmf-dist/source/latex/koma-script/scrjura.dtx b/Master/texmf-dist/source/latex/koma-script/scrjura.dtx index 77ab25d5914..b906cb9559d 100644 --- a/Master/texmf-dist/source/latex/koma-script/scrjura.dtx +++ b/Master/texmf-dist/source/latex/koma-script/scrjura.dtx @@ -1,4 +1,4 @@ -% \CheckSum{1934} +% \CheckSum{1938} % \iffalse meta-comment % ====================================================================== % scrjura.dtx @@ -60,11 +60,11 @@ % Right brace \} Tilde \~} % % \iffalse -%%% From File: $Id: scrjura.dtx 2649 2017-05-29 09:39:43Z kohm $ +%%% From File: $Id: scrjura.dtx 2847 2017-12-19 09:38:00Z kohm $ %<*dtx> \begingroup \def\filedate$#1: #2-#3-#4 #5${\gdef\filedate{#2/#3/#4}} - \filedate$Date: 2017-05-29 11:39:43 +0200 (Mon, 29 May 2017) $ + \filedate$Date: 2017-12-19 10:38:00 +0100 (Tue, 19 Dec 2017) $ \def\filerevision$#1: #2 ${\gdef\filerevision{r#2}} \filerevision$Revision: 1962 $ \endgroup @@ -741,43 +741,52 @@ \@onlypreamble\DeclareNewJuraEnvironment % \end{macrocode} % \begin{macro}{\@defjuraenvironment} -% \changes{v0.9}{2014/11/04}{Neue (interne) Anweisung} -% Diese Anweisunge soll irgendwann einmal dazu dienen, weitere -% Umgebungen einfach definieren zu können. Allerdings wird das vor Version 1.0 -% offiziell nichts werden. Bis dahin funktioniert die Anweisung bzw. die damit -% definierten Umgebungen nicht korrekt und sollten nicht verwendet werden! +% \changes{v0.9}{2014/11/04}{Neue (interne) Anweisung}^^A +% \changes{v3.25}{2017/12/08}{neue Option \texttt{ClauseFont}}^^A +% \changes{v3.25}{2017/12/08}{\cs{reserved@defjuraenvironment} wird wieder +% \cs{relax}}^^A +% \changes{v3.25}{2017/12/08}{Umstellung von globalen auf lokale Optionen}^^A +% Diese Anweisung dient dazu, weitere Umgebungen einfach definieren zu können. +% Dabei werden optional diverse Optionen unterstützt. Näheres ist der +% Anleitung zu entnehmen. % \begin{macrocode} \DefineFamily{KOMAarg} \DefineFamilyMember{KOMAarg} -\DefineFamilyKey{KOMAarg}{Clause}{% - \expandafter\gdef\csname \scrjura@env@type @Clause\endcsname{#1}% -} -\DefineFamilyKey{KOMAarg}{SubClause}{% - \expandafter\gdef\csname \scrjura@env@type @SubClause\endcsname{#1}% -} -\DefineFamilyKey{KOMAarg}{Sentence}{% - \expandafter\gdef\csname \scrjura@env@type @Sentence\endcsname{#1}% -} -\DefineFamilyKey{KOMAarg}{ClauseNumberFormat}{% - \expandafter\gdef\csname \scrjura@env@type @Clauseformat \endcsname - ##1{#1{##1}} - \expandafter\xdef\csname \scrjura@env@type @Clauseformat\endcsname{% - \noexpand\protect\expandafter\noexpand - \csname \scrjura@env@type @Clauseformat \endcsname - }% -} \newcommand{\@defjuraenvironment}{} \long\def\@defjuraenvironment#1[#2]#3#4{% + \let\reserved@defjuraenvironment\relax % \end{macrocode} % Die Zähler definieren: % \begin{macrocode} \newcounter{#1Clause}% \newcounter{#1AbsoluteClause}% \newcounter{#1SubClause}% - \begingroup - \edef\scrjura@env@type{#1}% - \FamilyExecuteOptions[.scrjura.sty]{KOMAarg}{#2}% - \endgroup + \FamilyCSKey[.scrjura.sty]{KOMAarg}{Clause}{#1@Clause}% + \FamilyCSKey[.scrjura.sty]{KOMAarg}{SubClause}{#1@SubClause}% + \FamilyCSKey[.scrjura.sty]{KOMAarg}{Sentence}{#1@Sentence}% + \DefineFamilyKey[.scrjura.sty]{KOMAarg}{ClauseNumberFormat}{% + \expandafter\def\csname #1@Clauseformat \endcsname####1{##1{####1}}% + \expandafter\edef\csname #1@Clauseformat\endcsname{% + \noexpand\protect\expandafter\noexpand\csname #1@Clauseformat \endcsname + }% + \FamilyKeyStateProcessed + } + \DefineFamilyKey[.scrjura.sty]{KOMAarg}{ClauseFont}{% + \IfExistskomafont{#1.Clause}{% + \IfIsAliaskomafont{#1.Clause}{% + \expandafter\let\csname scr@fnt@instead@#1.Clause\endcsname\relax + \newkomafont{#1.Clause}{##1}% + }{\setkomafont{#1.Clause}{##1}}% + }{% + \newkomafont{#1.Clause}{##1}% + }% + } + \FamilyExecuteOptions[.scrjura.sty]{KOMAarg}{#2}% + \RelaxFamilyKey[.scrjura.sty]{KOMAarg}{ClauseFont}% + \RelaxFamilyKey[.scrjura.sty]{KOMAarg}{ClauseNumberFormat}% + \RelaxFamilyKey[.scrjura.sty]{KOMAarg}{Sentence}% + \RelaxFamilyKey[.scrjura.sty]{KOMAarg}{SubClause}% + \RelaxFamilyKey[.scrjura.sty]{KOMAarg}{Clause}% \@ifundefined{#1@Clauseformat}{% \expandafter\DeclareRobustCommand\expandafter*% \csname #1@Clauseformat\endcsname[1]{\Clauseformat{##1}}% @@ -825,11 +834,17 @@ \csname \scrjura@env@type @everypar\endcsname \contract@everypar }{}% - \@ifundefined{scr@fnt@#1}{% - \@ifundefined{scr@fnt@instead@#1}{% - \aliaskomafont{Clause}{contract.Clause}% +% \end{macrocode} +% Jetzt wird noch ein Font-Alias für \texttt{Clause} gesetzt. Ist kein Font +% und kein Alias-Font für die neue Umgebung definiert, so wird +% \texttt{contract.Clause} verwendet. +% \changes{v3.25}{2017/12/08}{Fontalias korrigiert}^^A +% \begin{macrocode} + \IfExistskomafont{#1.Clause}{% + \IfIsAliaskomafont{#1.Clause}{% + \aliaskomafont{Clause}{\csname scr@fnt@instead@#1.Clause\endcsname}% }{% - \aliaskomafont{Clause}{\csname scr@fnt@instead@#1\endcsname}% + \aliaskomafont{Clause}{#1.Clause}% }% }{% \aliaskomafont{Clause}{contract.Clause}% @@ -941,11 +956,15 @@ % \end{macro} % \end{option} % \begin{macro}{\contract@paragraph@font} -% Das muss noch auf die Element-Schnittstelle von \KOMAScript{} umgestellt -% werden! +% \changes{v3.25}{2017/12/08}{Es wird Element \texttt{Clause} statt +% \texttt{contract.Clause} verwendet}^^A +% Eigentlich müsste die Anweisung \cs{contract@paragraph@format} heißen. Da +% sie jedoch für irgendwelche Tricks verwendet wurde. will ich das ungern +% ändern. Ebenso müsste die Anweisung eigentlich je nach Vertragsumgebung +% neu definiert und dann jene Defintion verwendet werden. % \begin{macrocode} \newkomafont{contract.Clause}{\sffamily\bfseries\large} -\newcommand*{\contract@paragraph@font}{\usekomafont{contract.Clause}% +\newcommand*{\contract@paragraph@font}{\usekomafont{Clause}% \@hangfrom} % \end{macrocode} % \end{macro} @@ -1318,18 +1337,20 @@ % \begin{macro}{\contract@everypar} % |\scrjura@everpar| für Verträge. % \begin{macro}{\ifparnumber} -% \changes{v0.6}{2011/09/29}{Definition des Schalters in die Definition der -% Option verschoben} +% \changes{v0.6}{2011/09/29}{Definition des Schalters in die Definition der +% Option verschoben}^^A % \begin{Counter}{par} % \begin{macro}{\thepar} % \begin{macro}{\theHpar} % \begin{macro}{\parformat} -% \changes{v0.7}{2013/06/07}{neues Font-Element \texttt{parnumber}} +% \changes{v0.7}{2013/06/07}{neues Font-Element \texttt{parnumber}}^^A % \begin{macro}{\parformatseparation} -% \changes{v0.9f}{2016/02/06}{neue Anweisung} +% \changes{v0.9f}{2016/02/06}{neue Anweisung}^^A % \begin{macro}{\p@par} -% \changes{v0.5d}{2010/04/28}{\cs{jura@usetype} mit Argument -% \cs{jura@env@type} eingefügt} +% \changes{v0.5d}{2010/04/28}{\cs{jura@usetype} mit Argument +% \cs{jura@env@type} eingefügt}^^A +% \begin{macro}{\withoutparnumber} +% \changes{v3.25}{2017/12/19}{neu}^^A % Der Schalter gibt an, ob überhaupt mit Absatznummern gearbeitet werden % soll. Sind Absatznummern deaktiviert, werden auch keine manuellen % Absatznummern gesetzt. Die Absätze werden dann auch nicht gezählt. Ansonsten @@ -1347,12 +1368,14 @@ \renewcommand*\p@par{{\scrjura@usetype{\scrjura@env@type}\theSubClause\scrjura@separator{\nobreakspace}}} \@addtoreset{par}{Clause} \@addtoreset{par}{SubClause} +\newcommand*{\withoutparnumber}{} % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \end{macro} +% \end{macro} % \end{Counter} % \end{macro} % \changes{v0.5c}{2010/04/26}{erstes Argument von \cs{newmaxpar} und zweites @@ -1414,12 +1437,14 @@ \else \def\reserved@a{\relax}% \ifx\@tempa\reserved@a + \withoutparnumber \else {\usekomafont{parnumber}{\parformat\parformatseparation}}% \fi \fi \endgroup \else + \begingroup\withoutparnumber\endgroup \setcounter{sentence}{-1}\refstepcounter{sentence}% \fi } diff --git a/Master/texmf-dist/source/latex/koma-script/scrkernel-basics.dtx b/Master/texmf-dist/source/latex/koma-script/scrkernel-basics.dtx index 9eb08be0387..38b12a8f180 100644 --- a/Master/texmf-dist/source/latex/koma-script/scrkernel-basics.dtx +++ b/Master/texmf-dist/source/latex/koma-script/scrkernel-basics.dtx @@ -1,4 +1,4 @@ -% \CheckSum{3675} +% \CheckSum{3730} % \iffalse meta-comment % ====================================================================== % scrkernel-basics.dtx @@ -55,7 +55,7 @@ % Right brace \} Tilde \~} % % \iffalse -%%% From File: $Id: scrkernel-basics.dtx 2640 2017-05-08 09:36:55Z kohm $ +%%% From File: $Id: scrkernel-basics.dtx 2818 2017-12-08 08:31:53Z kohm $ %%%% (run: prepare) %

    \bibliography@heading{\refname}% +% \bibliography@heading{\bibname}% +} +\newcommand*{\bibliography@heading}[1]{% \ifbib@leveldown - \subsection*{\refname}% - \scr@ifundefinedorrelax{@mkright}{% - \ifx\@mkboth\@gobbletwo\else\markright{\MakeMarkcase{\refname}}\fi - }{% - \@mkright{\MakeMarkcase{\refname}}% - }% +%
    \subsection*{#1}% +% \section*{#1}% + \@mkright{\MakeMarkcase{#1}}% \else - \section*{\refname}% - \scr@ifundefinedorrelax{@mkdouble}{% - \@mkboth{\MakeMarkcase{\refname}}{\MakeMarkcase{\refname}}% - }{% - \@mkdouble{\MakeMarkcase{\refname}}% - }% +%
    \section*{#1}% +% \chapter*{#1}% + \@mkdouble{\MakeMarkcase{#1}}% \fi -%
    -%<*book|report> - \ifbib@leveldown - \section*{\bibname}% - \scr@ifundefinedorrelax{@mkright}{% - \ifx\@mkboth\@gobbletwo\else\markright{\MakeMarkcase{\bibname}}\fi - }{% - \@mkright{\MakeMarkcase{\bibname}}% - }% - \else - \chapter*{\bibname}% - \scr@ifundefinedorrelax{@mkdouble}{% - \@mkboth{\MakeMarkcase{\bibname}}{\MakeMarkcase{\bibname}}% - }{% - \@mkdouble{\MakeMarkcase{\bibname}}% - }% - \fi -%
    }% % \end{macrocode} % \end{macro} -% +% \end{macro}% % % % \subsection{Optionen für das Literaturverzeichnis} @@ -327,6 +310,10 @@ % \changes{v3.12}{2013/09/28}{Es werden keine Kapiteleinträge in andere % Verzeichnisse geschrieben.}^^A % \changes{v3.17}{2015/03/12}{interne Speicherung der Werte}^^A +% \changes{v3.25}{2017/10/13}{use always \cs{@mkright} and +% \cs{@mkdouble}}^^A +% \changes{v3.25}{2017/10/13}{redefines \cs{bibliography@heading} instead of +% \cs{bib@heading}}^^A % Dies ist der Generalschlüssel für alle Optionen, die das % Literaturverzeichnis betreffen. Neu ist, dass verschiedene Stile definiert % werden können. Desweiteren kann man \texttt{totoc} und @@ -356,25 +343,16 @@ \KOMA@kav@remove{.\KOMAClassFileName}{bibliography}{totoc}% \KOMA@kav@remove{.\KOMAClassFileName}{bibliography}{numbered}% \KOMA@kav@add{.\KOMAClassFileName}{bibliography}{notoc}% - \renewcommand*\bib@heading{% -%<*article> + \renewcommand*{\bibliography@heading}[1]{% \ifbib@leveldown - \subsection*{\refname}% - \ifx\@mkboth\@gobble\else\markright{\MakeMarkcase{\refname}}\fi +%
    \subsection*{##1}% +% \section*{##1}% + \@mkright{\MakeMarkcase{##1}}% \else - \section*{\refname}% - \@mkboth{\MakeMarkcase{\refname}}{\MakeMarkcase{\refname}}% +%
    \section*{##1}% +% \chapter*{##1}% + \@mkdouble{\MakeMarkcase{##1}}% \fi -%
    -%<*book|report> - \ifbib@leveldown - \section*{\bibname}% - \ifx\@mkboth\@gobble\else\markright{\MakeMarkcase{\bibname}}\fi - \else - \chapter*{\bibname}% - \@mkboth{\MakeMarkcase{\bibname}}{\MakeMarkcase{\bibname}}% - \fi -%
    }% \or% totoc \KOMA@kav@remove{.\KOMAClassFileName}{toc}{nobibliography}% @@ -385,35 +363,36 @@ \KOMA@kav@remove{.\KOMAClassFileName}{bibliography}{totoc}% \KOMA@kav@remove{.\KOMAClassFileName}{bibliography}{numbered}% \KOMA@kav@add{.\KOMAClassFileName}{bibliography}{totoc}% - \renewcommand*\bib@heading{% + \renewcommand*{\bibliography@heading}[1]{% %<*article> \ifbib@leveldown % \end{macrocode} -% \changes{v3.23}{2017/02/23}{Verwendung von \cs{ext@toc}}^^A -% Ab Version 3.23 wird das von \textsf{tocbasic} bereitgestellte -% \cs{ext@toc} statt dem hart codierten \texttt{toc} verwendet. +% \changes{v3.23}{2017/02/23}{Verwendung von \cs{ext@toc}}^^A +% \changes{v3.25}{2017/10/13}{Verwendung von \cs{addsubsectiontocentry} statt +% \cs{addxcontentsline}}^^A +% Ab Version 3.23 wird das von \textsf{tocbasic} bereitgestellte +% \cs{ext@toc} statt dem hart codierten \texttt{toc} verwendet. % \begin{macrocode} \subsection*{% - \expandafter\addxcontentsline\expandafter{\ext@toc}% - {subsection}{\refname}% - \refname + \addsubsectiontocentry{}{##1}% + ##1% }% - \ifx\@mkboth\@gobble\else\markright{\MakeMarkcase{\refname}}\fi + \@mkright{\MakeMarkcase{##1}}% \else - \addsec{\refname} - \@mkboth{\MakeMarkcase{\refname}}{\MakeMarkcase{\refname}}% + \addsec{##1}% + \@mkdouble{\MakeMarkcase{##1}}% \fi %
    %<*book|report> \ifbib@leveldown - \addsec{\bibname} + \addsec{##1}% \else \if@chaptertolists - \@chaptertolistsfalse\addchap{\bibname}\@chaptertoliststrue + \@chaptertolistsfalse\addchap{##1}\@chaptertoliststrue \else - \addchap{\bibname} + \addchap{##1}% \fi - \@mkboth{\MakeMarkcase{\bibname}}{\MakeMarkcase{\bibname}}% + \@mkdouble{\MakeMarkcase{##1}}% \fi % }% @@ -426,27 +405,25 @@ \KOMA@kav@remove{.\KOMAClassFileName}{bibliography}{totoc}% \KOMA@kav@remove{.\KOMAClassFileName}{bibliography}{numbered}% \KOMA@kav@add{.\KOMAClassFileName}{bibliography}{numbered}% - \renewcommand*\bib@heading{% + \renewcommand*{\bibliography@heading}[1]{% %<*article> \ifbib@leveldown - \subsection{\refname}% + \subsection{##1}% \else - \section{\refname}% - \@mkboth{\MakeMarkcase{\sectionmarkformat \refname}}% - {\MakeMarkcase{\sectionmarkformat \refname}}% + \section{##1}% + \@mkdouble{\MakeMarkcase{\sectionmarkformat ##1}}% \fi %
    %<*book|report> \ifbib@leveldown - \section{\bibname}% + \section{##1}% \else \if@chaptertolists - \@chaptertolistsfalse\chapter{\bibname}\@chaptertoliststrue + \@chaptertolistsfalse\chapter{##1}\@chaptertoliststrue \else - \chapter{\bibname} + \chapter{##1} \fi - \@mkboth{\MakeMarkcase{\chaptermarkformat \bibname}}% - {\MakeMarkcase{\chaptermarkformat \bibname}}% + \@mkdouble{\MakeMarkcase{\chaptermarkformat ##1}}% \fi %
    } diff --git a/Master/texmf-dist/source/latex/koma-script/scrkernel-compatibility.dtx b/Master/texmf-dist/source/latex/koma-script/scrkernel-compatibility.dtx index c350585bd15..9d37bc4dab9 100644 --- a/Master/texmf-dist/source/latex/koma-script/scrkernel-compatibility.dtx +++ b/Master/texmf-dist/source/latex/koma-script/scrkernel-compatibility.dtx @@ -1,8 +1,8 @@ -% \CheckSum{214} +% \CheckSum{215} % \iffalse meta-comment % ====================================================================== % scrkernel-compatibility.dtx -% Copyright (c) Markus Kohm, 2006-2017 +% Copyright (c) Markus Kohm, 2006-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -20,7 +20,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrkernel-compatibility.dtx -% Copyright (c) Markus Kohm, 2006-2017 +% Copyright (c) Markus Kohm, 2006-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -55,7 +55,7 @@ % Right brace \} Tilde \~} % % \iffalse -%%% From File: $Id: scrkernel-compatibility.dtx 2640 2017-05-08 09:36:55Z kohm $ +%%% From File: $Id: scrkernel-compatibility.dtx 2950 2018-03-05 07:54:19Z kohm $ %%%% (run: identify) %%%% (run: init) % % \end{macrocode} % +% \begin{macrocode} +%<*init> +% \end{macrocode} % \begin{macro}{\scr@v@first} % \changes{v2.9u}{2005/03/05}{Neues Macro}^^A % \begin{macro}{\scr@v@2.9} @@ -410,12 +413,13 @@ % \changes{v3.23}{2017/02/04}{Neues Macro} % \begin{macro}{\scr@v@3.23} % \changes{v3.24}{2017/04/22}{Neues Macro} +% \begin{macro}{\scr@v@3.25} +% \changes{v3.25}{2017/09/07}{Neues Macro} % \begin{macro}{\scr@v@last} % \changes{v2.9u}{2005/03/05}{Neues Macro}^^A % Nun die unterschiedlichen möglichen Werte (|\scr@v@last| ist jeweils die % höchste vorhandene Nummer): % \begin{macrocode} -%<*init> \@namedef{scr@v@first}{0} \@namedef{scr@v@2.9}{0} \@namedef{scr@v@2.9t}{0} @@ -481,8 +485,8 @@ \@namedef{scr@v@3.22}{16} \@namedef{scr@v@3.23}{16} \@namedef{scr@v@3.24}{16} -\@namedef{scr@v@last}{16} -% +\@namedef{scr@v@3.25}{17} +\@namedef{scr@v@last}{17} % \end{macrocode} % \end{macro} % \end{macro} @@ -536,6 +540,7 @@ % \end{macro} % \end{macro} % \end{macro} +% \end{macro} % \end{macro} % \end{macro} % \end{macro} @@ -552,6 +557,9 @@ % \end{macro} % \end{macro} % \end{option} +% \begin{macrocode} +% +% \end{macrocode} % % \begin{macro}{\scr@v@is@lt} % \changes{v3.17}{2015/03/10}{Neu (intern)}^^A diff --git a/Master/texmf-dist/source/latex/koma-script/scrkernel-floats.dtx b/Master/texmf-dist/source/latex/koma-script/scrkernel-floats.dtx index 27db5a73a76..ab752b1b0cc 100644 --- a/Master/texmf-dist/source/latex/koma-script/scrkernel-floats.dtx +++ b/Master/texmf-dist/source/latex/koma-script/scrkernel-floats.dtx @@ -1,4 +1,4 @@ -% \CheckSum{1515} +% \CheckSum{1692} % \iffalse meta-comment % ====================================================================== % scrkernel-floats.dtx @@ -55,7 +55,7 @@ % Right brace \} Tilde \~} % % \iffalse -%%% From File: $Id: scrkernel-floats.dtx 2640 2017-05-08 09:36:55Z kohm $ +%%% From File: $Id: scrkernel-floats.dtx 2701 2017-11-15 14:02:01Z kohm $ %