diff options
| author | Karl Berry <karl@freefriends.org> | 2017-09-22 22:55:20 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2017-09-22 22:55:20 +0000 |
| commit | a3caad5b4b4880fc51f9d2be58dcaa0958b536c6 (patch) | |
| tree | b8951e0abbec878218b57a3862c6ca6b8cd03e82 | |
| parent | 2fac25871588760688adca2de7ed1132c96e99c9 (diff) | |
novel (22sep17)
git-svn-id: svn://tug.org/texlive/trunk@45383 c570f23f-e606-0410-a88d-b1316a301751
21 files changed, 430 insertions, 378 deletions
diff --git a/Master/texmf-dist/doc/lualatex/novel/extras/novel-cover-template.tex b/Master/texmf-dist/doc/lualatex/novel/extras/novel-cover-template.tex index 200517ce1b4..d9a6734d9af 100644 --- a/Master/texmf-dist/doc/lualatex/novel/extras/novel-cover-template.tex +++ b/Master/texmf-dist/doc/lualatex/novel/extras/novel-cover-template.tex @@ -1,6 +1,6 @@ % !TeX program = LuaLaTeX % !TeX encoding = UTF-8 -\documentclass[coverart]{novel} % v. 1.40.1 or later +\documentclass[coverart]{novel} % v. 1.40.2 or later \SetMediaSize{width}{height} % includes bleed \SetTrimSize{width}{height} % without bleed \SetTitle{example} % title required, might not be book title diff --git a/Master/texmf-dist/doc/lualatex/novel/extras/novel-example.tex b/Master/texmf-dist/doc/lualatex/novel/extras/novel-example.tex index 7c60332d8d4..8c35257226f 100644 --- a/Master/texmf-dist/doc/lualatex/novel/extras/novel-example.tex +++ b/Master/texmf-dist/doc/lualatex/novel/extras/novel-example.tex @@ -3,7 +3,7 @@ % % EXAMPLE OF NOVEL DOCUMENT CLASS % Uses mostly default layout. -\documentclass{novel} % v. 1.40.1 or later +\documentclass{novel} % v. 1.40.2 or later \SetTitle{Dark and Stormy} \SetSubtitle{A Tale of Nights} \SetAuthor{Dirk Hardcase} diff --git a/Master/texmf-dist/doc/lualatex/novel/novel-documentation.html b/Master/texmf-dist/doc/lualatex/novel/novel-documentation.html index 3ed48889bf8..c38b0915a36 100644 --- a/Master/texmf-dist/doc/lualatex/novel/novel-documentation.html +++ b/Master/texmf-dist/doc/lualatex/novel/novel-documentation.html @@ -5,7 +5,7 @@ <title>Document class "novel" - documentation</title> <style type="text/css"> -body {font-family:sans-serif; line-height:150%; font-size:14pt; background:#cccccc none;} +body {font-family:sans-serif; line-height:150%; font-size:14pt; color:#203310; background:#cccccc none;} p {font-family:sans-serif,sans-serif; font-size:1em; margin:0px 16px 0px 16px; text-indent:16px;} ol, ul {list-style-type:none; margin:0px; padding:0px;} li {margin:3px 8px 3px 16px; padding:0px;} @@ -30,7 +30,7 @@ div.d6 {margin:0px 0px 16px 16px; padding-bottom:0.5em; border-top:0; border-rig div.page {padding:16px 0px 16px 0px; border-top:4px solid #505050;} div.codeblock {overflow:auto; margin:16px; padding: 8px; border: 1px solid #000000;} div.codeblock p {text-indent:0px; white-space:nowrap;} -code {font-family:sans-serif,sans-serif; font-size:1em; background:#dddddd none; padding:0px 3px 0px 3px;} +code {font-family:monospace,monospace; font-size:0.92em; color:#200050; background:transparent none; padding:0px 3px 0px 3px;} *.noindent {text-indent:0px;} *.noindent1 {text-indent:0px; margin-top:8px;} *.noindent2 {text-indent:0px; margin-bottom:8px;} @@ -235,7 +235,7 @@ function showul(thisul){ <li><p class="noimg"><a href="#h5.4.3">5.4.3 Open Type Features</a></p></li> <li><p class="noimg"><a href="#h5.4.4">5.4.4 Scale Pseudo-Feature</a></p></li> <li><p class="noimg"><a href="#h5.4.5">5.4.5 Color and Opacity</a></p></li> - <li><p class="noimg"><a href="#h5.4.6">5.4.6 \CreateFeature{}{}</a></p></li> + <li><p class="noimg"><a href="#h5.4.6">5.4.6 \CreateFontFeature{}{}</a></p></li> <li><p class="noimg"><a href="#h5.4.7">5.4.7 Local Feature Changes</a></p></li> </ul> </li><!-- end 5.4 --> @@ -350,6 +350,7 @@ function showul(thisul){ <li><p class="noimg"><a href="#h9.3.7">9.3.7 Sample Preface</a></p></li> <li><p class="noimg"><a href="#h9.3.8">9.3.8 Sample Acknowledgements</a></p></li> <li><p class="noimg"><a href="#h9.3.9">9.3.9 Sample Map</a></p></li> + <li><p class="noimg"><a href="#h9.3.10">9.3.10 Characters, Synopsis</a></p></li> </ul> </li><!-- end 9.3 --> </ul> @@ -409,6 +410,7 @@ function showul(thisul){ </ul> </li><!-- end 12.2 --> <li><p class="noimg"><a href="#h12.3">12.3. Regarding Back Matter</a></p></li> + <li><p class="noimg"><a href="#h12.4">12.4. \cleartoend</a></p></li> </ul> </li><!-- end 12 --> @@ -506,8 +508,9 @@ function showul(thisul){ <!-- **************************************************************************************** --> <h1 id="h0">Document class <i>novel</i> - documentation</h1> -<p class="noindent">Version: 1.40, 2017/09/14. This is a complete re-write of the documentation, with the HTML in a single file, and many improvements. Version 1.40.1: Minor doc changes, especially correction to code for converting cover image to CMYK.</p> -<p>A complete example novel, text and cover, can be found at the <a class="external" rel="external" target="new" href="https://github.com/RobtAll/novel/">GitHub project page</a>, in the "other" folder.</p> +<p class="noindent">Version: 1.40, 2017/09/14. This is a complete re-write of the documentation, with the HTML in a single file, and many improvements. Version 1.40.1: Minor doc changes, especially correction to code for converting cover image to CMYK. Version 1.40.2: More minor doc changes.</p> +<p class="noindent" style="position:relative"><span style="position:absolute; top:-.1em; font-size:150%; color:#008000">☺</span> An example novel, text and cover, can be found at the <a class="external" rel="external" target="new" href="https://github.com/RobtAll/novel/">GitHub project page</a>, in the "other" folder. You will find its TeX source and the resulting PDF. The PDF text and cover meet submission standards for major American print-on-demand services.</p> +<p>A smaller example document is <i>novel-example.tex</i>, which can be found in the <i>extras</i> folder within this documentation.</p> <p> </p> @@ -531,10 +534,10 @@ function showul(thisul){ <h4 id="h1.1.1">1.1.1. Installation</h4> <div class="d4" id="d1.1.1"> -<p class="noindent">Your TeX installation must be based on TeXLive 2016 or later (including any recent MiKTeX). If you are on Linux and your distro is something such as Ubuntu 16.04 LTS (Xenial), then the distro version of TeXLive is too old. However, you can sill install a more recent version of TeXLive manually, to your home directory, from <a class="external" rel="external" target="new" href="https://www.tug.org/texlive/"></a>.</p> +<p class="noindent">Your TeX installation must be based on TeXLive 2016 or later (including any recent MiKTeX). If you are on Linux and your distro is something such as Ubuntu 16.04 LTS (Xenial), then the distro version of TeXLive is too old. However, you can still install a more recent version of TeXLive manually, to your home directory, from <a class="external" rel="external" target="new" href="https://www.tug.org/texlive/">tug.org</a>.</p> <p>The <i>novel</i> package is not (yet) included with default TeX distribution. Once you have TeX working, use its package manager to install <i>novel</i>. The TeX package will be placed in <i>(texroot)/tex/lualatex/novel/</i>, the documentation will be placed in <i>(texroot)/doc/lualatex/novel/</i>, and the included font will be placed in <i>(texroot)/fonts/opentype/novel/</i>.</p> <p>Fonts from the <i>libertinus</i> package are required, and may be installed via your TeX package manager. Note that a <i>novel</i> document does not request the package, so you will not see an error if the fonts are not installed! Instead, if you have not manually specified which fonts to use, it will automatically look for pre-installed Libertinus fonts (or Linux Libertine O) as defaults.</p> -<p>Since you will be using LuaTeX, the font cache will be updated to include the newly-installed fonts, the next time you run this software. However, I recommend that you force a full cache refresh, by locating the <i>luatex-cache</i> directory, and discard its contents. The cache may be anywhere (sadly), so you will have to hunt for it. If you have never used LuaTeX before, it may not exist. If there are any updates to the fonts, then a manual cache refresh is necessary.</p> +<p>Since you will be using LuaLaTeX, the font cache will be updated to include the newly-installed fonts, the next time you run this software. However, I recommend that you force a full cache refresh, by locating the <i>luatex-cache</i> directory, and discard its contents. The cache may be anywhere (sadly), so you will have to hunt for it. If you have never used LuaLaTeX before, it may not exist. If there are any updates to the fonts, then a manual cache refresh is necessary.</p> </div> <h4 id="h1.1.2">1.1.2. Licensing</h4> @@ -548,8 +551,8 @@ function showul(thisul){ <p class="noindent">My method of "programming" largely involves using or modifying code provided by others under allowable license terms. Thus, within the TeX code files, you will find places where small or large pieces of code are the work of someone else. Names or organizations are credited in-place within the TeX code, according to license.</p> <p>Various clipart graphics were obtained from <a class="external" rel="external" target="new" href="https://openclipart.org">openclipart.org</a>. The <i>NovelDeco.otf</i> font is partly derived from <i>Linux Libertine O</i>, using <a class="external" rel="external" target="new" href="https://fontforge.github.io/en-US/">FontForge.</a></p> <p>I read popular fiction a lot, usually books from my local public library. Even if I do not read a particular book, I often look a how it is designed. Throughout this documentation, where I recommend a design or style, it is most often based on the preponderance of designs/styles as I have seen in softcover or hardcover popular fiction, from major publishers in the U.S.A. That does not include "mass-market paperback" versions (the kind seen at supermarkets, rather than at bookstores). I may mention several common alternatives.</p> -<p>I have also consulted the authoritative Chicago Manual of Style (CMoS) hardcover 16th Edition. In the case of fiction, CMoS occasionally notes that publishers sometimes don't do things the official way.</p> -<p>Although I have looked at a variety of web sites concerning book design, I give these the least credence, because (a) often they merely duplicate each other's opinions, right or wrong, and (b) they may simply echo CMoS.</p> +<p>I have also consulted the authoritative <i>Chicago Manual of Style (CMoS)</i> hardcover 16th Edition. In the case of fiction, <i>CMoS</i> notes that publishers sometimes don't do things the official way.</p> +<p>Although I have looked at a variety of web sites concerning book design, I give these the least credence, because (a) often they merely duplicate each other's opinions, right or wrong, and (b) they may simply echo <i>CMoS</i>.</p> </div> <h4 id="h1.1.4">1.1.4. Success Story</h4> @@ -561,8 +564,8 @@ function showul(thisul){ <h4 id="h1.1.5">1.1.5. Help Wanted</h4> <div class="d4" id="d1.1.5"> -<p class="noindent">Although this package works for me, and there are no known issues, bugs are always possible. You may file an issue at the <a class="external" rel="external" target="new" href="https://github.com/RobtAll/novel">GitHub project page</a>, or contact the author by e-mail if you do not have a GitHub account. My e-mail address is towards the top of the <i>novel.cls</i> file.</p> -<p>I, the original author of this package, am a retiree who prefers to move on to other things. If you are of a mind to take up long-term maintenance, then contact me by e-mail. If you already are a package developer with a <a class="external" rel="external" target="new" href="https://ctan.org/contact">CTAN</a> login, also contact them. You will need to understand elementary LuaLaTeX, fontspec, Unicode, Open Type fonts, PDF/X, and the general needs of ficion writers in the printed (not e-book) market. However, Lua, XeTeX, TiKz, math, and physics are not required (possibly counterproductive).</p> +<p class="noindent">Although this package works for me, and there are no <i>known</i> issues, bugs are always possible. You may file an issue at the <a class="external" rel="external" target="new" href="https://github.com/RobtAll/novel">GitHub project page</a>, or contact me by e-mail if you do not have a GitHub account. My e-mail address is towards the top of the <i>novel.cls</i> file.</p> +<p>I, the original author of this package, am a retiree who prefers to move on to other things. If you are of a mind to take up long-term maintenance, then contact me by e-mail. If you already are a package developer with a <a class="external" rel="external" target="new" href="https://ctan.org/contact">CTAN</a> login, also contact them. You will need to understand elementary LuaLaTeX, fontspec, Unicode, Open Type fonts, PDF/X, and the general needs of fiction writers in the printed (not e-book) market. However, Lua, XeTeX, TiKz, math, and physics are not required (possibly counterproductive).</p> </div> </div><!-- end class="d3" --> @@ -573,32 +576,32 @@ function showul(thisul){ <h4 id="h1.2.1">1.2.1. Always Use UTF-8, Without fontenc</h4> <div class="d4" id="d1.2.1"> <p class="noindent">You must create your document in utf-8 encoding. No OT1, no T1, no LY1, or other TeX font encoding that pre-dates cell phones.</p> -<p>Instead of typing TeX codes such as \`{e} you can simply paste è from a Unicode character map. Other alphabets such as Greek and Cyrillic are directly supported, as long as you choose fonts that support those character sets.</p> +<p>Instead of typing TeX codes such as <code>\`{e}</code> you can simply paste <code>è</code> from a Unicode character map. Other alphabets such as Greek and Cyrillic are directly supported, as long as you choose fonts that support those character sets.</p> <p>Do not call for <i>fontenc</i> in your Preamble. The <i>novel</i> class is pre-configured for utf-8.</p> <p>If you use a plain text editor, or TeXWorks, or export plain text from a word processor, be sure that your text is encoded as utf-8, without byte order mark (BOM).</p> -<p>If you are on Windows, do not use Notepad! The free <a class="external" rel="external" target="new" href="https://notepad-plus-plus.org">Notepad++</a> (also <a class="external" rel="external" target="new" href="https://portableapps.com/apps/development/notepadpp_portable">Portable</a> version) is a suitable plain text editor. Configure it as specified.</p> +<p>If you are on Windows, do not use Notepad! The free <a class="external" rel="external" target="new" href="https://notepad-plus-plus.org">Notepad++</a> (also <a class="external" rel="external" target="new" href="https://portableapps.com/apps/development/notepadpp_portable">Portable</a> version) is a suitable plain text editor. Configure it as specified, with utf-8 and without BOM. Does not matter whether UNIX or DOS line endings, as long as you are consistent.</p> </div> -<h4 id="h1.2.2">1.2.2. Do Not Load Fonts via \usepackage or \RequirePackage</h4> +<h4 id="h1.2.2">1.2.2. Do Not Load Fonts via <code>\usepackage</code> or <code>\RequirePackage</code></h4> <div class="d4" id="d1.2.2"> -<p class="noindent">The method for loading fonts is described elsewhere on this page. Be sure you read that! For example, you cannot load a font with \usepackage{fontname} in this document class.</p> +<p class="noindent">The method for loading fonts is described elsewhere on this page. Be sure you read that! For example, you cannot load a font with <code>\usepackage{<em>fontname</em>}</code> in this document class.</p> </div> <h4 id="h1.2.3">1.2.3. Use LuaLaTeX and Open Type fonts</h4> <div class="d4" id="d1.2.3"> -<p class="noindent"><img class="floatright" src="html-resources/doordie.png" width="279" height="300" alt="Thou Shalt"/> With <i>novel</i>, you will be using the <i>LuaLaTeX</i> engine, whether you like it or not. No <i>pdfTeX</i>, no <i>XeTeX</i>, no <i>dvips</i>. You do not have to understand <i>Lua</i> code, since the heavy lifting is already done for you.</p> +<p class="noindent"><img class="floatright" src="html-resources/doordie.png" width="279" height="300" alt="Thou Shalt"/> With <i>novel</i>, you will be using the <i>LuaLaTeX</i> engine, whether you like it or not. No <i>pdfTeX</i>, no <i>XeTeX</i>, no <i>dvips</i>. You do not have to understand <i>Lua</i> code, since the heavy lifting is already done for you. Just follow the instructions in this documentation.</p> <p>The built-in <i>fontspec</i> package handles modern Open Type fonts, and is able to access their internal features. The syntax is easy to learn, and very powerful. And, you can directly include text with diacritical marks, Greek, Cyrillic, and most other utf-8 encoded characters in your document. All you need are the fonts, and you probably have them. You will wonder why you never did this before.</p> </div> <h4 id="h1.2.4">1.2.4. Disabled standard text size commands</h4> <div class="d4" id="d1.2.4"> -<p class="noindent">Would you like to size text, using command such as \small or \LARGE ? Bah! They will be ignored. Write these commands, and the text will appear at its usual size, just as if the commands did not exist.</p> +<p class="noindent">Would you like to size text, using command such as <code>\small</code> or<code> \LARGE</code> ? Bah! They will be ignored. Write these commands, and the text will appear at its usual size, just as if the commands did not exist.</p> <p>There is a reason for this behavior, related to the need for constant line spacing. Thus, <i>novel</i> provides its own capability to size text, using different commands.</p> </div> <h4 id="h1.2.5">1.2.5. Disabled academic-purpose commands</h4> <div class="d4" id="d1.2.5"> -<p class="noindent"><img class="floatright" src="html-resources/fpaper.png" width="134" height="215" alt="flunked math"/> Commands such as \section, \chapter, \abstract, \index, \tableofcontents, \maketitle, and many other structural commands will not work with <i>novel</i>. Those are for academic papers. The results they would produce (if enabled) would be inappropriate for fiction. If you attempt to use them, you will either get an error message, or they will simply be ignored.</p> +<p class="noindent"><img class="floatright" src="html-resources/fpaper.png" width="134" height="215" alt="flunked math"/> Commands such as <code>\section</code>, <code>\chapter</code>, <code>\abstract</code>, <code>\index</code>, <code>\tableofcontents</code>, <code>\maketitle</code>, and many other structural commands will not work with <i>novel</i>. Those are for academic papers. The results they would produce (if enabled) would be inappropriate for fiction. If you attempt to use them, you will either get an error message, or they will simply be ignored.</p> <p>Novelists do not need many ways to distinguish chapters. With <i>novel</i> there are commands specifically created for the needs of fictional works. They are described below.</p> <p>Also, the <i>float</i> and <i>table</i> environments are ineffective. In <i>novel</i> there are specific ways to place images or construct a table of contents.</p> </div> @@ -615,7 +618,7 @@ function showul(thisul){ <p><img class="floatright" src="html-resources/trdol.png" width="238" height="67" alt="dollar is math mode"/> TeX has a number of special characters. If you type them in a document, they will not appear as an ordinary printed character, but will do something else. These are:</p> <p class="code"><code>$ % # _ ^ & ~ \ { }</code> and sometimes <code>[ ]</code></p> <p>In most cases, an incorrect usage will provide an error message that can be easily deciphered. However, the dollar sign and percent symbol are tricky. Incorrect use of the dollar sign may either place your text in math mode (not your intent) or produce a baffling error message that points to an innocent package. The percent symbol normally produces no error, since it is a comment character. But then, whatever text follows on that line will be missing from your PDF.</p> -<p>Special characters, other than the backslash, are escaped by placing a backslash in front, thus: \$ for the dollar sign, \% for percent. If you must print a backslash, \string\ does it.</p> +<p>Special characters, other than the backslash, are escaped by placing a backslash in front, thus: <code>\$</code> for the dollar sign, <code>\%</code> for percent. If you must print a backslash, <code>\string\</code> does it.</p> <p class="noindent"><b>• Tip:</b> To avoid unforeseen problems, you should review your document in a text editor, prior to compiling. Search for any instances of special characters, particularly dollar and percent. Backslash them as needed.</p> </div> @@ -629,9 +632,10 @@ function showul(thisul){ <div class="d4" id="d1.2.9"> <p class="noindent">I suggest that you write your novel in a word processor rather than in a text editor. <i>MS Word</i> and similar programs work. I use <a class="external" rel="external" target="new" href="https://www.libreoffice.org">LibreOffice</a> (also <a class="external" rel="external" target="new" href="https://portableapps.com/apps/office/libreoffice_portable">Portable</a> version). If you use <i>LibreOffice</i>, version 5.3 or later is much better than earlier versions.</p> <p>Why begin with a word processor? These programs can automatically substitute curly quotes and other characters. Remember than since you are using utf-8 encoding, you don't need to use TeX code for that, since you can simply insert the character directly. And, word processors have much better support for spell checking (and sometimes grammar). Just be sure that the word processor does not <i>automatically</i> correct your spelling, because any TeX code won't be in its dictionary.</p> -<p>Remember that TeX closes paragraphs by skipping lines, or by \par. Also remember that in most word processors, the emdash is <i>two</i> hyphens, not the three used in TeX. You can always insert an emdash (or endash) directly. You can write TeX code into the word processor, where it will be treated like ordinary text, so use \textit{italicized} or similar command, rather than the word processor's italics menu.</p> +<p>Remember that TeX closes paragraphs by skipping lines, or by <code>\par</code>. Also remember that in most word processors, the emdash is <i>two</i> hyphens, not the three used in TeX. You can always insert an emdash (or endash) directly. You can write TeX code into the word processor, where it will be treated like ordinary text, so use <code>\textit{<em>text</em>}</code> or similar command, rather than the word processor's italics menu.</p> <p>In any case, be sure to export plain text as utf-8, then compile it with <i>lualatex</i>.</p> <p class="noindent"><b>• Tip:</b> For the editing and proofreading phase, where spelling and grammar are carefully reviewed, I use a special font <i>CPmodified.otf</i>. This is my custom derivative of the <a class="external" rel="external" target="new" href="https://quoteunquoteapps.com/courierprime/">Courier Prime</a> regular font. <i>Cpmodified</i> can be found in the documentation <i>extras</i> folder. It is released under the SIL Open Font License v.1.1. To use this font for editing, install it in your <i>operating system</i>, not TeX. Then, call it from your word processor. The font includes Latin-1 and ANSI characters, and a few others. It is not quite monospaced (the em dash and ellipsis are longer). Punctuation is highly exaggerated, so you can see it more easily. My own experience is that most errors in the nearly-finished document involve punctuation.</p> +<p class="noindent"><b>• Tip:</b> Word processors usually make an incorrect substitution for certain English elisions (possibly in other languages also). When you type "Give 'em hell," the substitution may provide <i>Give ‘em hell</i>, but the correct rendition is <i>Give ’em hell</i>. Can you see the tiny difference in the direction of the single quote? Probably not on your computer screen, but it will be noticeable in print. The <i>CPmodified.otf</i> font makes the difference obvious.</p> </div> <h4 id="h1.2.10">1.2.10. Think for yourself</h4> @@ -675,13 +679,15 @@ function showul(thisul){ <p>Your book will not be printed with "gray ink." Instead, anything other than pure black will be emulated by a pattern of black dots. This is known as "halftone." It causes a reduction in resolution, so your gray text will appear somewhat fuzzy. Therefore, do not use very small text, or characters with fine lines.</p> <p>Sometimes the halftone operation extends to nearby text that is not gray. So: Unlike the example shown above, it is a bad idea to mingle gray with the ordinary flow of black text. The most appropriate use of gray text is for special items such as chapter titles.</p> <p>You may place darker text over a lighter background. But even though the resulting PDF meets standards, lighter text over darker background is unlikely to print as intended.</p> +<p>See also <a href="#h7.2.8">section 7.2.8</a>.</p> </div> <h3 id="h2.3">2.3. shademargins</h3> <div class="d3" id="d2.3"> <p class="noindent">This option is ignored unless using draft mode. It is not necessary to use the <i>graytext</i> option.</p> -<p><img class="floatright" style="margin-top:6px" src="html-resources/shademargins.png" width="132" height="205" title="shademargins" alt="shademargins"/> The <i>shademargins</i> option is simple: The margins will have a light gray background. Note that <em>margins</em> refers to the area between the live text area (including head/foot, if any) and the TrimBox, which is the finished size of your book. If you are using \SetMediaSize to request paper larger than your book's Trim Size, the excess area is <em>not</em> considered to be margins; it is discarded paper, so it is not gray.</p> -<p>Some commands (in particular, images) allow their content to overflow the textblock area. With <code>shademargins</code> you can see where such object intrude into the margins.</p> +<p><img class="floatright" style="margin-top:6px" src="html-resources/shademargins.png" width="132" height="205" title="shademargins" alt="shademargins"/> The <i>shademargins</i> option is simple: The margins will have a light gray background.</p> +<p>Note that <em>margins</em> refers to the area between the live text area (including head/foot, if any) and the TrimBox, which is the finished size of your book. If you are using <code>\SetMediaSize</code> to request paper larger than your book's Trim Size, the excess area is <em>not</em> considered to be margins; it is discarded paper, so it is not gray.</p> +<p>Some commands (in particular, images) allow their content to overflow the textblock area. With <i>shademargins</i> you can see where such object intrude into the margins.</p> <p>Sometimes it is hard to see whether a centered object is really centered, because the left-right margins are not the same width. With <i>shademargins</i> you can more easily see centering.</p> <p>Note that headers and footers are not part of the margins.</p> </div> @@ -706,7 +712,7 @@ function showul(thisul){ <h3 id="h2.6">2.6. closecrop</h3> <div class="d3" id="d2.6"> -<p class="noindent"><img class="floatright" style="margin-top:6px" src="html-resources/closecrop.png" width="110" height="186" title="closecrop" alt="closecrop"/> This option is only effective in draft mode. When used, the layout of your text is unchanged, but the surrounding margins are shrunk so that they just clear the live text area (which includes header and footer, if present). Also, the TrimSize is shrunk accordingly. Left and right margins are the same. The resulting PDF will be easier to read on a handheld device.</p> +<p class="noindent"><img class="floatright" style="margin-top:6px" src="html-resources/closecrop.png" width="110" height="186" title="closecrop" alt="closecrop"/> This option is only effective in draft mode. When used, the layout of your text is unchanged, but the surrounding margins are shrunk so that they just clear the live text area (which includes header and footer, if present). Also, the TrimSize is shrunk accordingly. The resulting PDF will be easier to read on a handheld device.</p> <p>This does <em>not</em> produce an E-book, since the file will be missing some things that an E-book ought to have. The sole purpose of this option is to create a conveniently-sized file that you can carry around while you are thinking about edits and revisions.</p> </div> @@ -725,7 +731,7 @@ function showul(thisul){ <h3 id="h2.9">2.9. unblock (primarily for developer use)</h3> <div class="d3" id="d2.9"> <p class="noindent">A number of LaTeX packages are known to be incompatible with <i>novel</i>, because "the way those packages do things" conflicts with "the way <i>novel</i> does things." If you attempt to load one of those packages, then the results you get may not be in agreement with the formats and styles described in this documentation, because the other package over-rides some of <i>novel's</i> own macros.</p> -<p>Therefore, at the end of your Preamble, <i>novel</i> reviews the loaded packages, and throws an error message if you included any of them via <i>\usepackage</i> or <i>\RequirePackage</i>. That also applies if you call some other package that chain-loads one of the forbidden packages.</p> +<p>Therefore, at the end of your Preamble, <i>novel</i> reviews the loaded packages, and throws an error message if you included any of them via <code>\usepackage</code> or <code>\RequirePackage</code>. That also applies if you call some other package that chain-loads one of the forbidden packages.</p> <p>The odds that you will need a forbidden package are small, because they generally pertain to layout for mathematical and academic papers (tables, floats, equations, diagrams, etc.).</p> <p>If you specify document class option <i>unblock</i> then the list of forbidden packages will be disregarded by <i>novel</i>. Use at your own risk! This option is really intended for the convenience of developers, rather than ordinary users.</p> </div> @@ -783,9 +789,9 @@ function showul(thisul){ <div class="d4" id="d3.2.2"> <p class="noindent">At least in the USA, your print service may require that File Data be limited to characters in the Latin-1 set. This is because their production and distribution software uses Latin-1 for the database. Note that Latin-1 does not include curly quotes or em dash. You will still be using utf-8 encoding in your document files, but your choice of characters is restricted.</p> <p>If it were not for the database limitation to Latin-1, you could give your book a Greek or Cyrillic title, because <i>novel</i> can do it, and so can the PDF.</p> -<p>If your book has File Data using quotes, then use the special commands \straightquote{} and \straightdblquote{}. Be sure to use the braces, so that you don't have to worry about gobbled space. When you use these commands instead of typing ' or " you eliminate the risk that your software will automatically convert them to the forbidden curly quotes. Example title:</p> +<p>If your book has File Data using quotes, then use the special commands <code>\straightquote{}</code> and <code>\straightdblquote{}</code>. Be sure to use the braces, so that you don't have to worry about gobbled space. When you use these commands instead of typing ' or " you eliminate the risk that your software will automatically convert them to the forbidden curly quotes. Example title:</p> <p class="code"><code>\SetTitle{That\straightquote{}s Amore} % That's Amore</code></p> -<p>If you are limited to Latin-1 in File Data, you can still use curly quotes and em dash on the cover and title page, and in headings. In <i>novel</i> there is no \maketitle command, so you may (and should) apply styling to the printed title, even though the File Data title cannot be styled.</p> +<p>If you are limited to Latin-1 in File Data, you can still use curly quotes and em dash on the cover and title page, and in headings. In <i>novel</i> there is no <code>\maketitle</code> command, so you may (and should) apply styling to the printed title, even though the File Data title cannot be styled.</p> </div> <h4 id="h3.2.3">3.2.3. TeX escapes</h4> @@ -801,10 +807,10 @@ function showul(thisul){ <div class="d4" id="d3.2.4"> <p class="noindent">• Do not use the backslash <code>\</code> except as described above.</p> <p class="noindent">• Do not use the tilde <code>~</code> or the circumflex <code>^</code>.</p> -<p class="noindent">• Do not use TeX code, such as <code>\`e</code> for e with grave; instead paste è directly from a character map.</p> -<p class="noindent">• Do not use styling, such as {\small text} or \textit{text}.</p> -<p class="noindent">• Use only \straightquote{} and \straightdblquote{} if necessary, not TeX code for apostrphe or quote.</p> -<p class="noindent">• Do not use multiple hyphens to create longer dahses. Do not use em dash or en dash.</p> +<p class="noindent">• Do not use TeX code, such as <code>\`e</code> for e with grave; instead paste <code>è</code> directly from a character map.</p> +<p class="noindent">• Do not use styling, such as <code>{\small text}</code> or <code>\textit{text}</code>.</p> +<p class="noindent">• Use only <code>\straightquote{}</code> and <code>\straightdblquote{}</code> if necessary, not TeX code for apostrophe or quote.</p> +<p class="noindent">• Do not use multiple hyphens to create longer dashes. Do not use em dash or en dash.</p> </div> </div><!-- end class="d3" --> @@ -812,24 +818,25 @@ function showul(thisul){ <div class="d3" id="d3.3"> <p class="noindent">Now that you understand what File Data means, and how it may be written, you can use commands to write it.</p> -<h4 id="h3.3.1">3.3.1. \SetTitle{}</h4> +<h4 id="h3.3.1">3.3.1. <code>\SetTitle{<em>text</em>}</code></h4> <div class="d4" id="d3.3.1"> -<p class="noindent">If you do not use the \SetTitle{} command, or leave it empty or blank, then the resulting PDF cannot comply with PDF/X standards. In very rare cases, that is desirable. Note that this information is not automatically transferred to your book's title page. It will be used as default in certain page heading styles, but you can over-ride it. The information can be retrieved as \theTitle anywhere in your document.</p> +<p class="noindent">If you do not use the <code>\SetTitle{}</code> command, or leave it empty or blank, then the resulting PDF cannot comply with PDF/X standards. In <i>very rare</i> cases, that is desirable.</p> +<p>This information is not automatically transferred to your book's title page. It will be used as default in certain page heading styles, but you can over-ride it. The information can be retrieved as \theTitle anywhere in your document.</p> </div> -<h4 id="h3.3.2">3.3.2. \SetAuthor{}</h4> +<h4 id="h3.3.2">3.3.2. <code>\SetAuthor{<em>text</em>}</code></h4> <div class="d4" id="d3.3.2"> -<p class="noindent">This information is not automatically transferred to your book's title page. It will be used as default in certain page heading styles, but you can over-ride it. The information can be retrieved as \theAuthor anywhere in your document.</p> +<p class="noindent">This information is not automatically transferred to your book's title page. It will be used as default in certain page heading styles, but you can over-ride it. The information can be retrieved as <code>\theAuthor</code> anywhere in your document.</p> </div> -<h4 id="h3.3.3">3.3.3. \SetSubtitle{}</h4> +<h4 id="h3.3.3">3.3.3. <code>\SetSubtitle{<em>text</em>}</code></h4> <div class="d4" id="d3.3.3"> -<p class="noindent">There is no file data for subtitle! The only reason for using this command is if you wish to later retrieve the information as \theSubtitle in your document.</p> +<p class="noindent">There is no file data for subtitle! The only reason for using this command is if you wish to later retrieve the information as <code>\theSubtitle</code> in your document.</p> </div> -<h4 id="h3.3.4">3.3.4 Advanced: \SetApplication{} and \SetProducer{}</h4> +<h4 id="h3.3.4">3.3.4 Advanced: <code>\SetApplication{<em>text</em>}</code> and <code>\SetProducer{<em>text</em>}</code></h4> <div class="d4" id="d3.3.4"> -<p class="noindent">The <i>Application</i>, also known as <i>CreatorTool</i>, is the program used to create your source document. Text editors, word processors, and page layout programs are the most common Applications (not particular to TeX). The PDF <i>Producer</i> is the program that converts the source document to PDF. In many cases, the Producer is a back-end, directly linked to the Application.</p> +<p class="noindent">The <i>Application</i>, also known as <i>CreatorTool</i>, is the program used to create your source document. Text editors, word processors, and page layout programs are the most common Applications (not specific to TeX). The PDF <i>Producer</i> is the program that converts the source document to PDF. In many cases, the Producer is a back-end, directly linked to the Application.</p> <p>These details are automatically created when you compile your document, without any input from you. However, if you have the need to provide a custom text string for the Application or Producer, these commands will do it.</p> </div> </div><!-- end class="d3" --> @@ -838,7 +845,7 @@ function showul(thisul){ <div class="d3" id="d3.4"> <p class="noindent">Commercial printers are very likely to require PDF/X compliance. This ensures that your PDF meets a variety of criteria, by containing those things it must contain, and omitting those things it must not contain. Most perfectly valid PDF files are <em>not</em> PDF/X compliant, simply because they are not intended for commercial printing.</p> <p class="code"><code>\SetPDFX[<em>output intent</em>]{<em>compliance standard</em>}</code> and starred version</p> -<p>If the \SetPDFX command is not used, it is <i>off</i> by default. Note that a non-compliant file is not a defective file! It complies with PDF standards, but not PDF/X standards. Some print services insist on PDF/X, and others don't care as long as the fonts are embedded (which they always are).</p> +<p>If the <code>\SetPDFX</code> command is not used, it is <i>off</i> by default. Note that a non-compliant file is not a defective file! It complies with PDF standards, but not PDF/X standards. Some print services insist on PDF/X, and others don't care as long as the fonts are embedded (which they always are).</p> <h4 id="h3.4.1">3.4.1. Compliance Standards</h4> <div class="d4" id="3.4.1"> @@ -854,7 +861,7 @@ function showul(thisul){ <h4 id="h3.4.2">3.4.2. Output Intent</h4> <div class="d4" id="d3.4.2"> <p class="noindent">Unless compliance is <i>off</i>, an Output Intent is always required. However, <i>novel</i> treats this as an optional argument, because it will automatically use CGATSTR001 as default Output Intent.</p> -<p>Output Intent informs the printer that you "intend" your PDF to be printed according to certain printer capabilities. If you took the trouble to soft-proof your PDF on a color-controlled monitor using color managed software, and if the printer's capabilities actually correspond to the intent, then the printed result will closely match what you expected. This is very important in commercial color printing (such as for cover artwork), but nearly irrelevant for a black and white book block. Nevertheless, an Output Intent is required to meet PDF/X compliance.</p> +<p>Output Intent informs the printer that you "intend" your PDF to be printed according to certain printer capabilities. If you took the trouble to soft-proof your PDF on a color-calibrated monitor using color-managed software, and if the printer's capabilities actually correspond to the intent, then the printed result will closely match what you expected. This is very important in commercial color printing (such as for cover artwork), but nearly irrelevant for a black and white book block. Nevertheless, an Output Intent is required to meet PDF/X compliance.</p> </div> <h4 id="h3.4.3">3.4.3. Built-in Output Intent Codes</h4> @@ -875,15 +882,16 @@ function showul(thisul){ <h4 id="h3.4.5">3.4.5. Whether or Not to Embed *.icc</h4> <div class="d4" id="d3.4.5"> <p class="noindent">Each Output Intent has a corresponding color profile, in the form of a file with extension <i>*.icc</i>.</p> -<p>You usually do not need it. In fact, unless your print service specifically asks you to embed the file, <i>don't do it</i>. When you use \SetPDFX in its un-starred form, the *.icc file will not be embedded.</p> -<p>If your print service demands that you embed the *.icc color profile, then use \SetPDFX* (with the asterisk).</p> +<p>You usually do not need it. In fact, unless your print service specifically asks you to embed the file, <i>don't do it</i>. When you use <code>\SetPDFX</code> in its un-starred form, the *.icc file will not be embedded.</p> +<p>If your print service demands that you embed the *.icc color profile, then use <code>\SetPDFX*</code> (with the asterisk).</p> <p>Repeat: Do not embed the *.icc color profile unless specifically requested by your print service.</p> -<p>If your printer requests "US Web Coated SWOP v2" and, as usual, requests that you <em>not</em> embed the corresponding *.icc color profile, then some software will read the Output Intent as "CGATS TR 001" instead of "US Web Coated SWOP v2". They are identical. But not everyone knows that.</p> +<p>• If your printer requests "US Web Coated SWOP v2" and, as usual, requests that you <em>not</em> embed the corresponding *.icc color profile, then some software will read the Output Intent as "CGATS TR 001" instead of "US Web Coated SWOP v2". They are identical. But not everyone knows that.</p> </div> <h4 id="h3.4.6">3.4.6. Where to Find *.icc Files</h4> <div class="d4" id="d3.4.6"> -<p class="noindent">Although many *.icc files are freely available, they usually cannot be distributed within an open-source project. You might already have them in your system, wherever such files are stored. Note that TeX uses forward slash in file paths, not backslash, even if the platform is Windows:</p> +<p class="noindent">You do not need an *.icc color profile unless you choose to embed it.</p> +<p>Although many *.icc files are freely available, they usually cannot be distributed within an open-source project. You might already have them in your system, wherever such files are stored. Note that TeX uses forward slash in file paths, not backslash, even if the platform is Windows:</p> <p class="isolate"> Windows: <code>C:/Windows/System32/spool/drivers/color/</code> [older Windows: system32 instead of System32]<br/> Linux: <code>/usr/share/color</code> or hidden <code>~/.local/share/icc/</code> or other places<br/> @@ -913,12 +921,13 @@ OSX: <code>/Library/Colorsync/Profiles/</code> or hidden <code>(username)/Librar <h4 id="h4.1.1">4.1.1. Trim Size</h4> <div class="d4" id="d4.1.1"> -<p class="noindent"><b>Trim Size</b> is the finished size of your book, width and height (but not thickness). In the case of hardcover books, where the cover is larger than the contents, it is (usually) the cover size that is measured, with the internal trim size being slightly smaller than nominal</p> +<p class="noindent"><b>Trim Size</b> is the finished size of your book, width and height (but not thickness). In the case of softcover books, it is the exact size. In the case of hardcover books, where the cover is larger than the contents, it is (usually) the cover size that is measured, with the internal trim size being slightly smaller than nominal (some of the margins shaved away).</p> +<p>Your print service has a list of standard trim sizes. For fiction, you probably want creme (off-white) paper, which eliminates a few of the choices. Choice of size may also be limited by the distribution channels you choose.</p> </div> <h4 id="h4.1.2">4.1.2. Media Size, TrimBox</h4> <div class="d4" id="d4.1.2"> -<p class="noindent"><img class="floatright" src="html-resources/mbcrectomar.png" width="202" height="264" alt="media size recto"/> In a few cases, the commercial printer will request that the PDF page size be something larger than the Trim Size of your book. In PDF terminology, the larger dimensions are the <b>Media Size</b>. Typically, the Media Size will be U.S. Letter, or A4, and the Trim Size must be floated in the center, horizontally and vertically. As an alternative, the Trim Size will be at the edge. Something of the sort happens when you print a copy of your PDF at home, where your printer's paper tray has letter or A4, not the Trim Size.</p> +<p class="noindent"><img class="floatright" src="html-resources/mbcrectomar.png" width="202" height="264" alt="media size recto"/> In a few cases, the commercial printer will request that the PDF page size be something larger than the Trim Size of your book. In PDF terminology, the larger dimensions are the <b>Media Size</b>. Typically, the Media Size will be U.S. Letter, or A4, and the Trim Size must be floated in the center, horizontally and vertically. As an alternative, the Trim Size will be at the edge. Something of the sort happens when you print a copy of your PDF at home, where your printer's paper tray has Letter or A4, not the Trim Size.</p> <p>Unless you explicitly set it to a different value, Media Size will automatically be set at Trim Size. <i>Do not specify the Media Size, unless the commercial printer requests it.</i></p> <p>Since your PDF is being prepared for commercial print production, it will have an invisible <code>TrimBox</code> automatically encoded. This information tells the printer where the Trim Size is located. If (as usual) the Trim Size and Media Size are identical, then the TrimBox is the full size of the PDF page. But when the Trim Size is smaller than the Media Size, the TrimBox defines where the paper will be trimmed. Although it is not normally marked on the PDF page and never appears in print, some PDF viewers allow you make the TrimBox visible.</p> <p>In the accompanying diagram, the TrimBox is shown as a faint green line. The margins, shaded gray, are measured relative to the Trim Size, not relative to the Media Size. The excess area beyond the Trim Size is "wasted paper" that will not become part of the book.</p> @@ -927,7 +936,7 @@ OSX: <code>/Library/Colorsync/Profiles/</code> or hidden <code>(username)/Librar <h4 id="h4.1.3">4.1.3. Margins</h4> <div class="d4" id="d4.1.3"> <p class="noindent"><b>Margins</b> are required on all four edges of the page. They do not have to be the same width. Generally the margin at the spine edge (inside margin) is wider.</p> -<p>The accompanying illustration shows a typical recto page, on a layout with header and footer. The margins have been shaded gray in the picture (but, not in the book). The inside (spine) margin is at the left of this page. In the case of fiction, where there are no marginal notes, it is typically the case that the inside margin is the widest. But this is not a rule for all books. All that is required is that each margin be "wide enough" for the printing process.</p> +<p>In the case of fiction, where there are no marginal notes, it is typically the case that the inside margin is the widest. But this is not a rule for all books. All that is required is that each margin be "wide enough" for the printing process.</p> <p>Keep in mind that the print services are not used to seeing books with exotic margins (such as bottom margin twice the size of top margin). They may think that there is a mistake in your PDF, or in the print job, if you do that.</p> <p>The <i>novel</i> document class does not provide for marginal notes.</p> <p>Normally, your TeX document will be compiled to a PDF that is electronically at the exact Trim Size. And normally, print services want it to be that way. When you view your PDF, the text will shift from side to side as you move through the pages, due to the slightly increased margin at the inside edge.</p> @@ -939,26 +948,26 @@ OSX: <code>/Library/Colorsync/Profiles/</code> or hidden <code>(username)/Librar <p class="noindent">Now that you understand how the terms are used, you are ready to use <i>novel</i> layout commands.</p> <p>Remember that everything is pre-configured, specifically for the purpose of fiction. You only need to write a layout command if you don't like the defaults.</p> -<h4 id="h4.2.1">4.2.1. \SetTrimSize{<em>width</em>}{<em>height</em>}</h4> +<h4 id="h4.2.1">4.2.1. <code>\SetTrimSize{<em>width</em>}{<em>height</em>}</code></h4> <div class="d4" id="d4.2.1"> -<p class="noindent">Command \SetTrimSize{}{} sets the size of your book. Both values must be written, using units such as <i>in</i> or <i>mm</i>. If you do not use this command, the default Trim Size will be the widely-used 5.5in wide x 8.5in high.</p> +<p class="noindent">Command <code>\SetTrimSize</code> sets the size of your book. Both values must be written, using units such as <i>in</i> or <i>mm</i>. If you do not use this command, the default Trim Size will be the widely-used 5.5in wide x 8.5in high.</p> <p>This setting is most crucial. Unless your book is very exceptional, its Trim Size will be one of several standard sizes available from the print service. Among those sizes, only one or two will be "standard" for your genre.</p> <p>In the USA, 5.5in x 8.5in is often used for softcover fiction. Some fiction, and most nonfiction, prefers the slightly larger 6in x 9in trim size. Both of these are known as "trade" sizes.</p> -<p>If you ever need to retroactively change Trim Size, see Appendix F.</p> +<p>If you ever need to <i>retroactively</i> change Trim Size, see Appendix F.</p> <p>Do not request a <em>mass-market paperback</em> size unless you really, truly, know what you are doing. Since you are not a major writer for a major publishing house, you don't know; so, don't do it.</p> </div> -<h4 id="h4.2.2">4.2.2. \SetMargins{<em>top</em>}{<em>outside</em>}{<em>bottom</em>}{<em>inside</em>}</h4> +<h4 id="h4.2.2">4.2.2. <code>\SetMargins{<em>top</em>}{<em>outside</em>}{<em>bottom</em>}{<em>inside</em>}</code></h4> <div class="d4" id="d4.2.2"> <p class="noindent"><img class="floatright" src="html-resources/margins.png" width="303" height="234" alt="margins"/> Mnemonic: "TOBI, or not TOBI, that is the question."</p> <p>When you choose your book's Trim Size, margins are pre-configured. In most cases, the top, outside, and bottom margins are 0.5", and the inside (spine) margin is 0.75" to allow 0.25" binding clearance. These values are acceptable to most American printers, unless your book is very thick. The largest Trim Sizes have slightly larger margins.</p> -<p>Command \SetMargins lets you choose your own margins. If you use it, all four must be written, using units such as <i>in</i> or <i>mm</i>.</p> +<p>Command <code>\SetMargins</code> lets you choose your own margins. If you use it, all four must be written, using units such as <i>in</i> or <i>mm</i>.</p> <p><img class="floatright" src="html-resources/whichgutter.png" width="276" height="219" alt="Which gutter?"/> If your book has headers and/or footers, they sit inside the rectangle bounded by the margins. That is, they do not sit inside the peripheral areas cleared by the margins.</p> <p>Be aware that there is a lot of confusion regarding the word "gutter." In the accompanying diagram, it might mean any of A, B, C, or D, depending on who is doing the talking and which software is in use. The <i>novel</i> class uses <em>inside margin</em>, also known as <em>spine margin</em>, to mean C.</p> -<p>If you ever need to retroactively change margins, see Appendix F.</p> +<p>If you ever need to <i>retroactively</i> change margins, see Appendix F.</p> </div> -<h4 id="h4.2.3">4.2.3. \SetFontSize{<em>length</em>}</h4> +<h4 id="h4.2.3">4.2.3. <code>\SetFontSize{<em>length</em>}</code></h4> <div class="d4" id="d4.2.3"> <p class="noindent">In the <i>novel</i> document class, you do not set point size as a class option. Instead you use \SetFontSize in the Preamble.</p> <p>The size may be any units TeX understands, including decimal values. So, <i>12.8bp</i> and <i>13.1pt</i> are acceptable. This is because you will be using scalable, Open Type and TrueType fonts throughout your document. They do not need TeX metrics.<p> @@ -966,20 +975,20 @@ OSX: <code>/Library/Colorsync/Profiles/</code> or hidden <code>(username)/Librar <p>The minimum normal font size is 8pt, and the maximum is 18bp. On a local basis, text may be larger or smaller than this.</p> </div> -<h4 id="h4.2.4">4.2.4. \SetLinesPerPage{<em>integer</em>}</h4> +<h4 id="h4.2.4">4.2.4. <code>\SetLinesPerPage{<em>integer</em>}</code></h4> <div class="d4" id="d4.2.4"> <p class="noindent">Lines per page refers only to the textblock, and does <em>not</em> include header/footer. Lines are not stretched to fill short pages.</p> -<p>By default, a suitable number of lines per page are set, based on other dimemsions. You can change the default with this command. Any non-integer will be rounded. There is no direct command to set the <em>leading</em>, also known as line-to-line spacing or <em>baselineskip</em>. Instead, is is calculated from the textblock height and number of lines.</p> +<p>By default, a suitable number of lines per page are set, based on other dimemsions. You can change the default with this command. Any non-integer will be rounded. There is no direct command to set the <em>leading</em>, also known as line-to-line spacing or <em>baselineskip</em>. Instead, it is calculated from the textblock height and number of lines.</p> <p>If the calculated leading is less than 1.2x the font size, an error will result. It is difficult for TeX to honor all layout settings with such a small leading, which would normally be unacceptable for fiction in any case. If the calculated leading is at least 1.2x the font size, but less than 1.25x the font size, then the log file will have an Alert message, suggesting that you should consider using fewer lines per page. If the leading exceeds 1.4x the font size, then the log will have an Alert, suggesting more lines per page. The Alert messages are friendly; you do not necessarily have to do anything.</p> </div> -<h4 id="h4.2.5">4.2.5. \SetHeadFootStyle{<em>number</em>}</h4> +<h4 id="h4.2.5">4.2.5. <code>\SetHeadFootStyle{<em>number</em>}</code></h4> <div class="d4" id="d4.2.5"> -<p class="noindent"><img class="floatright" src="html-resources/headfoot.png" width="276" height="219" title="head foot style 1" alt="head foot style 1"/> The use of this command is described on <a href="noveldocs-06-header-footer.html#a6.1.2">Page 6</a>. It is mentioned here, because whether or not your book has headers and/or footers will affect the overall layout. The default is style 1, which has header but no footer (shown here).</p> -<p>The pre-defined styles are comprehensive, for use in fiction. It is hard to imagine a header/footer style that is not identical to, or a variation from, one of those styles. But if you do wish to create your own style, you must use \SetHeadFootStyle to choose the closest available style, then use <i>fancyhdr</i> commands for your custom style. The reason is that \SetHeadFootStyle tells the layout engine how much space it needs to reserve.</p> +<p class="noindent"><img class="floatright" src="html-resources/headfoot.png" width="276" height="219" title="head foot style 1" alt="head foot style 1"/> The use of this command is described in <a href="#h6.1.2">section 6.1.2</a>. It is mentioned here, because whether or not your book has headers and/or footers will affect the overall layout. The default is style 1, which has header but no footer (shown here).</p> +<p>The pre-defined styles are comprehensive, for use in fiction. It is hard to imagine a header/footer style that is not identical to, or a variation from, one of those styles. But if you do wish to create your own style, you must use <code>\SetHeadFootStyle</code> to choose the closest available style, then use <i>fancyhdr</i> commands for your custom style. The reason is that <code>\SetHeadFootStyle</code> tells the layout engine how much space it needs to reserve.</p> </div> -<h4 id="h4.2.6">4.2.6. \SetHeadJump{<em>number</em>} and \SetFootJump{<em>number</em>}</h4> +<h4 id="h4.2.6">4.2.6. <code>\SetHeadJump{<em>number</em>}</code> and <code>\SetFootJump{<em>number</em>}</code></h4> <div class="d4" id="d4.2.6"> <p class="noindent">Puzzled by TeX terms such as <em>headsep</em> and <em>footskip</em>? Me too! That's why I rewrote the way that the positions of headers and footers are calculated. Now, you can use easy-to-understand commands that do what you think they ought to be doing.</p> <p class="floatright" style="text-indent:0px"><img src="html-resources/headjump1.png" width="158" height="125" alt="headjump 1"/><br/><img src="html-resources/footjump2.png" width="130" height="116" alt="footjump 2"/></p> @@ -989,10 +998,10 @@ OSX: <code>/Library/Colorsync/Profiles/</code> or hidden <code>(username)/Librar <p>Don't worry about <em>headheight</em>. Whether you like it or not, headers (if used) will have only one line, and footers (if used) will have only one line. The necessary heights are calculated automatically.</p> </div> -<h4 id="h4.2.7">4.2.7. Advanced: \SetMediaSize[<em>alignment</em>]{<em>width</em>}{<em>height</em>}</h4> +<h4 id="h4.2.7">4.2.7. Advanced: <code>\SetMediaSize[<em>alignment</em>]{<em>width</em>}{<em>height</em>}</code></h4> <div class="d4" id="d4.2.7"> <p class="noindent">Normally, the book Trim Size will also set the same size for the PDF pages. What you see is what you get.</p> -<p>Some print services prefer that the Trim Size be floated in a standard paper size, such as US Letter or A4. That's not a technical necessity, but "the way things are done around here." If you must do that, use the \SetMediaSize command.</p> +<p>Some print services prefer that the Trim Size be floated in a standard paper size, such as US Letter or A4. That's not a technical necessity, but "the way things are done around here." See <a href="#h4.1.2">section 4.1.2</a> for details. If you must do that, use the <code>\SetMediaSize</code> command.</p> <p>The width and height must be specified with units, such as <i>in</i> or <i>mm</i>. If the optional <em>alignment</em> is not specified, then The Trim Size will be centered horizontally and vertically in the Media Size. That is the preferred method.</p> <p>If you write <i>edge</i> for the optional alignment, then the Trim Size will be off-center in the Media Size. Do not do this unless your print service specifically wants it that way. If you are making a hand-made book with a home printer, then this option might be convenient.</p> <p>Note that margins are measured relative to the Trim Size, not the Media Size. The extra white space between Trim Size and Media Size is just that: extra white space, unrelated to the margins of your book.</p> @@ -1005,9 +1014,9 @@ OSX: <code>/Library/Colorsync/Profiles/</code> or hidden <code>(username)/Librar <p>Trim Size 5.5"x8.5" is centered in Media Size 8.5"x11". The <i>shademargins</i> option was used, so that the page margins can be seen. Whether verso or recto, the Trim is centered in the Media. This image is a recto page, which has its slightly-larger inside margin at left of the text. For purposes of illustration, I have drawn the invisible TrimBox with a green line.</p> </div> -<h4 id="h4.2.8">4.2.8. Advanced: \SetCropmarkGap{<em>length</em>}</h4> +<h4 id="h4.2.8">4.2.8. Advanced: <code>\SetCropmarkGap{<em>length</em>}</code></h4> <div class="d4" id="d4.2.8"> -<p class="noindent"><img class="floatright" src="html-resources/cropmarkgap.png" width="140" height="141" alt="media size larger than trim size"/> This command is only effective if you use the <i>cropmarks</i> class option. Note that user-provided cropmarks are <em>very unusual</em> in the print-on demand market. Do not use them unless your print service specifically requests them. The built-in cropmark capability is very elementary, and cannot be easily enhanced by adding other LaTeX packages.</p> +<p class="noindent"><img class="floatright" src="html-resources/cropmarkgap.png" width="140" height="141" alt="media size larger than trim size"/> This command is only effective if you use the <i>cropmarks</i> class option, as described in <a href="#h2.4">section 2.4</a>. Note that user-provided cropmarks are <em>very unusual</em> in the print-on demand market. Do not use them unless your print service specifically requests them. The built-in cropmark capability is very elementary, and cannot be easily enhanced by adding other LaTeX packages.</p> <p>In the accompanying image with cropmarks, a corner of the Trim Size is at lower right. The invisible TrimBox has been drawn with a green line. The cropmark gap is G.</p> </div> </div><!-- end class="d3" --> @@ -1020,8 +1029,8 @@ OSX: <code>/Library/Colorsync/Profiles/</code> or hidden <code>(username)/Librar <h2 id="h5">5. Fonts</h2> <div class="d2" id="d5"> -<p class="noindent">This section describes how to choose fonts and font features, and how to apply fonts within your document. Local styling (such as italics) is described farther down this page.</p> -<p><b>EEEK!</b> If you are like me, you <em>first</em> try to do something the way you did it before, then when it fails, you <em>finally</em> read the instructions. So, before you came to this page, you tried these things, and none of them worked:</p> +<p class="noindent">This section describes how to choose fonts and font features, and how to apply fonts within your document. Local styling (such as italics) is described <a href="#h7">farther down</a> this page.</p> +<p><b>EEEK!</b> If you are like me, you <em>first</em> try to do something the way you did it before, then when it fails, you <em>finally</em> read the instructions. So, before you came to this part, you tried these things, and none of them worked:</p> <p class="code"><code> \usepackage{somefont} % FAILS!<br/> \renewcommand\rmdefault{smf} \normalfont % FAILS!<br/> @@ -1030,7 +1039,7 @@ OSX: <code>/Library/Colorsync/Profiles/</code> or hidden <code>(username)/Librar <p><b>DON'T PANIC.</b> In <i>novel</i>, the essential fonts are specified with different code. Fortunately, they are all pre-configured. If you accept the carefully-chosen defaults, then you do not need to worry about fonts. You do not even need to specify the font families. Sit back and relax.</p> <p>You can do something like this, if you have the font license. Then let <i>novel</i> do the rest:</p> <p class="code"><code>\SetParentFont{Adobe Garamond Pro} % WORKS!</code></p> -<p><b>It's that simple.</b> But TeX being what it is, there are complicated ways to customize things. The rest of this page shows you how to do it. You will be using Open Type fonts, or perhaps TrueType fonts. Forget the old Type 1 fonts.</p> +<p><b>It's that simple.</b> But TeX being what it is, there are complicated ways to customize things. The rest of this part shows you how to do it. You will be using Open Type fonts, or perhaps TrueType fonts. Forget the old Type 1 fonts.</p> <h3 id="h5.1">5.1. The Parent Font and Descendants</h3> <div class="d3" id="d5.1"> @@ -1041,8 +1050,8 @@ OSX: <code>/Library/Colorsync/Profiles/</code> or hidden <code>(username)/Librar <p>The <em>parentfont</em> has TeX ligatures and kerning, applied by default. All of the descendant fonts will also have TeX ligatures and kerning. (Note: TeX ligatures allow you to type `` to get “ and so forth.)</p> <p>If you specify any optional features for the <em>parentfont</em>, they will automatically be applied to descendants: <em>textfont</em>, <em>chapterfont</em>, <em>subchfont</em>, and <em>headfont</em>.</p> <p>If you do not set the <em>parentfont</em> yourself, then the following will be used as default, in order of priority: <em>Libertinus Serif</em>, <em>Linux Libertine O</em>, <em>Latin Modern Roman</em>. -<p>The <em>Libertinus Serif</em> fonts are well-suited to fiction. If in doubt, use them. They can be downloaded as TeX <i>libertinus</i> package, but do not write \usepackage{libertinus} in your Preamble. Those fonts are a more up-to-date fork of the <em>Linux Libertine O</em> fonts, which are in the <i>libertine</i> package. Alas, even though <em>Latin Modern Roman</em> is a fine font, its style and weight are not well-suited to fiction; the only reason they are a last-choice default, is because just about every TeX system has them.</p> -<p style="font-size:small">Note: In class version 1.0.10 and earlier, the <em>parentfont</em> was known as the <em>masterfont</em>, and the <em>textfont</em> was known as the <em>mainfont</em>. For backwards compatibility, both will work.</p> +<p>The <em>Libertinus Serif</em> fonts are well-suited to fiction. If in doubt, use them. They can be downloaded as TeX <i>libertinus</i> package, but do not write <code>\usepackage{libertinus}</code> in your Preamble. Those fonts are a more up-to-date fork of the <em>Linux Libertine O</em> fonts, which are in the <i>libertine</i> package.</p> +<p>Alas, even though <em>Latin Modern Roman</em> is a fine font, its style and weight are not well-suited to fiction; the only reason they are a last-choice default, is because just about every TeX system has them.</p> <h4 id="h5.1.1">5.1.1. Where Fonts Are Used</h4> <div class="d4" id="d5.1.1"> @@ -1053,42 +1062,46 @@ OSX: <code>/Library/Colorsync/Profiles/</code> or hidden <code>(username)/Librar <h4 id="h5.1.2">5.1.2. The Text Font</h4> <div class="d4" id="d5.1.2"> -<p class="noindent">The text font, or <em>textfont</em>, is the default main font used used for ordinary, flowing text. It uses the <em>parentfont</em>, with added features: common ligatures, and oldstyle numbers.</p> -<p>Common ligatures (the Open Type <em>liga</em> feature) are such things as replacing f<span style="position:relative; left:2px">f</span> with the single character ff. Oldstyle numbers are designed to blend with surrounding text. Not every font has these features; if they are missing, then whatever the font actually has, is used instead.</p> +<p class="noindent"><p>The text font, or <em>textfont</em>, is the default main font used used for ordinary, flowing text. It uses the <em>parentfont</em>, with added features: common ligatures, and oldstyle numbers. Thus, you do not set or customize the <i>textfont</i> by itself.</p> +<p>Common ligatures (the Open Type <em>liga</em> feature) are such things as replacing f<span style="position:relative; left:2px">f</span> with the single character ff. Oldstyle numbers (<i>onum</i>) are designed to blend with surrounding text. Not every font has these features; if they are missing, then whatever the font actually has, is used instead.</p> <p>Normally, you do not need to call the <em>textfont</em> explicity, because it is the default for ordinary text. But in the event that you have a small passage in <em>textfont</em>, within a passage in some other font, you can do this:</p> <p class="code"><code>{\textfont <em>text</em>}</code></p> -<p>Note that {\textfont <em>text</em>} and {\rmfamily <em>text</em>} mean the same thing.</p> -<p>You do not set the <em>textfont</em> itself. It inherits from the <em>parentfont</em>.</p> +<p>Note that <code>{\textfont <em>text</em>}</code> and <code>{\rmfamily <em>text</em>}</code> mean the same thing.</p> +<p>Local font changes are described in sections <a href="#h7.2.6">7.2.6</a> and <a href="#h7.2.7">7.2.7</a>.</p> </div> <h4 id="h5.1.3">5.1.3. The Chapter Title Font</h4> <div class="d4" id="d5.1.3"> -<p class="noindent">The <i>novel</i> command \ChapterTitle{<em>text</em>} automatically styles its text in the <em>chapterfont</em>.</p> -<p>If you write custom code for chapter titles, then whether or not you use this font is your choice. It is not automatic. If you wish to use it:</p> -<p class="code"><code>{\chapterfont <em>text</em>}</code></p> +<p class="noindent">The <i>novel</i> command <code>\ChapterTitle{<em>text</em>}</code> automatically styles its text in the <em>chapterfont</em> by default.</p> +<p>The <i>chapterfont</i> inherits from the <i>parentfont</i>. Then, by default it is set to a larger font size (Scale=1.6), and uses Lining numbers if available (Open Type feature <i>lnum</i>).</p> <p>You may customize the <em>chapterfont</em>:</p> <p class="code"><code>\SetChapterFont[optional,features]{Font Family} % Note command case!</code></p> -<p>If you do not use the above command to customize the <em>chapterfont</em>, then by default it will be the <em>parentfont</em> with added features: Lining numbers, and 1.6 scale.</p> +<p>If you write chapter titles by means other than the <code>\ChapterTitle</code> command, then whether or not you use <i>chapterfont</i> is your choice.</p> +<p>Outside of <code>\ChapterTitle</code> (where <i>chapterfont</i> is automatic), you may use this font anywhere in your document:</p> +<p class="code"><code>{\chapterfont <em>text</em>}</code></p> </div> <h4 id="h5.1.4">5.1.4. The Chapter Subtitle Font</h4> <div class="d4" id="d5.1.4"> -<p class="noindent">The <i>novel</i> commands \ChapterSubtitle{<em>text</em>} and \QuickChapter{<em>text</em>} automatically style their text in the <em>subchfont</em>.</p> -<p>If you write custom code for chapter subtitles or quick chapters, then whether or not you use this font is your choice. It is not automatic. If you wish to use it:</p> -<p class="code"><code>{\subchfont <em>text</em>}</code></p> -<p>You may customize the subchfont:</p> +<p class="noindent">The <i>novel</i> commands <code>\ChapterSubtitle{<em>text</em>}</code> and <code>\QuickChapter{<em>text</em>}</code> automatically style their text in the <em>subchfont</em> by default.</p> +<p>The <i>subchfont</i> inherits from the <i>parentfont</i>. Then, by default it is set to a slightly larger font size (Scale=1.2), and uses Lining numbers if available (Open Type feature <i>lnum</i>).</p> +<p>You may customize the <em>subchfont</em>:</p> <p class="code"><code>\SetSubchFont[optional,features]{Font Family} % Note command case!</code></p> -<p>If you do not use the above command to customize the <em>subchfont</em>, then by default it will be the <em>parentfont</em> with added features: Lining numbers, and 1.2 scale.</p> +<p>If you write chapter subtitles by means other than the <code>\ChapterSubtitle</code> command, then whether or not you use <i>subchfont</i> is your choice. Same applies regarding <code>\QuickChapter</code>.</p> +<p>Outside of <code>\ChapterSubtitle</code> and <code>\QuickChapter</code> (where <i>subchfont</i> is automatic), you may use this font anywhere in your document:</p> +<p class="code"><code>{\subchfont <em>text</em>}</code></p> </div> <h4 id="h5.1.5">5.1.5. The Header/Footer Font</h4> <div class="d4" id="d5.1.5"> -<p class="noindent">The <i>novel</i> pre-configured header/footer layouts automatically style their text in the <em>headfont</em>. -<p>If you write a customer header/footer layout (using <code>fancyhdr</code> syntax), then whether or not you use this font is your choice. It is not automatic. If you wish to use it:</p> -<p class="code"><code>{\headfont <em>text</em>}</code></p> -<p>You may customize the headfont:</p> +<p class="noindent">The <i>novel</i> pre-configured header/footer layouts automatically style their text in the <em>headfont</em> by default. +<p>The <i>headfont</i> inherits from the <i>parentfont</i>. Then, by default it is set to a slightly smaller font size (Scale=0.92), and uses Lining numbers if available (Open Type feature <i>lnum</i>).</p> +<p>You may customize the <em>headfont</em>:</p> <p class="code"><code>\SetHeadFont[optional,features]{Font Family} % Note command case!</code></p> -<p>If you do not use the above command to customize the <em>headfont</em>, then by default it will be the <em>parentfont</em> with added features: Lining numbers, and 0.92 scale.</p> +<p>If you use <i>fancyhdr</i> syntax to write your own header/footer content, then whether or not you use <i>headfont</i> is your choice.</p> +<p>If you write chapter titles by means other than the <code>\ChapterTitle</code> command, then whether or not you use <i>chapterfont</i> is your choice.</p> +<p>Outside of headers and footers (where <i>headfont</i> is automatic), you may use this font anywhere in your document:</p> +<p class="code"><code>{\headfont <em>text</em>}</code></p> </div> </div><!-- end class="d3" --> @@ -1098,7 +1111,7 @@ OSX: <code>/Library/Colorsync/Profiles/</code> or hidden <code>(username)/Librar <h4 id="h5.2.1">5.2.1. Sans and Mono Fonts</h4> <div class="d4" id="d5.2.1"> -<p class="noindent">You probably do not need a sans-serif or monospaced font in a work of fiction. The most prominent exception might be headers/footers, where the use of a light sans-serif font is fashionable. But in that case, set the <em>headfont</em> to the desired sans-serif font, instead of inheriting from <em>parentfont</em>.</p> +<p class="noindent">You probably do not need a sans-serif or monospaced font in a work of fiction. The most prominent exception might be headers/footers, where the use of a light sans-serif font is fashionable. But in that case, <a href="#h5.1.5">set</a> the <em>headfont</em> to the desired sans-serif font, instead of inheriting from <em>parentfont</em>.</p> <p>The <i>novel</i> class does not have its own commands for setting or using sans-serif or monospaced fonts. If you wish, you may use ordinary <i>fontspec</i> syntax to set them:</p> <p class="code"><code> \setsansfont[optional,features]{Font Family}<br/> @@ -1124,21 +1137,25 @@ OSX: <code>/Library/Colorsync/Profiles/</code> or hidden <code>(username)/Librar <p class="noindent">The <i>novel</i> class ships with its own custom font, <em>NovelDeco.otf</em>. This Open Type font is specifically designed to provide a number of decorative glyphs, and some other characters. It is <em>not</em> a general-purpose font, and can <em>not</em> be replaced by any other font, except by a modified version of <em>NovelDeco</em>.</p> <p>The <em>decofont</em> is automatically configured. You do not need to set it. However, if you use a font editor to create a modified version, then your modification must have a different font name (to avoid confusion with the original). In such a rare case, you may point to your modified font like this:</p> <p class="code"><code>\SetDecoFont[optional,features]{YourDecoFont}</code></p> -<p>The <em>decofont</em> is automatically called by other commands, such as \decoglyph{} and \acronym{}. Normally you do not request <em>decofont</em> directly. But if you wish to do so:</p> +<p>The <em>decofont</em> is automatically called by other commands, such as <code>\decoglyph</code> and <code>\acronym</code>. Normally you do not request <em>decofont</em> directly. But if you wish to do so:</p> <p class="code"><code>{\decofont <em>text</em>}</code></p> -<p>The decorative glyphs in this font (not including its ordinary characters) are shown in file <i>NovelDeco-glyphs.pdf</i>, which can be found in these docs in the documentation <i>extras</i> folder.</p> +<p>The decorative glyphs in this font (not including its ordinary characters) are shown in file <i>NovelDeco-glyphs.pdf</i>, which can be found in the documentation <i>extras</i> folder.</p> </div> </div><!-- end class="d3" --> <h3 id="h5.3">5.3. Defining New Fonts</h3> <div class="d3" id="d5.3"> -<p class="noindent">You can define new font commands. The syntax depends on whether the new font is part of a family (where you might have bold and italic variants), or just a single file (no variants). If part of a family, use \NewFontFamily. If alone, use \NewFontFace.</p> +<p class="noindent">You can define new font commands. The syntax depends on whether the new font is part of a family (where you might have bold and italic variants), or just a single file (no variants). If part of a family, use <code>\NewFontFamily</code>. If alone, use <code>\NewFontFace</code>.</p> +<p>The <code>\NewFontFamily</code> command (or <code>\NewFontFace</code>) takes three arguments: First, the name you assign to the new font command is required. Second, font features are optional. Third, the font name is required (this is tricky; see <a href="#h5.4">section 5.4</a>).</p> +<p class="code"><code> +\NewFontFamily<em>\pickaname</em>[<em>optional,features</em>]{<em>Font Family</em>}<br/> +\NewFontFace<em>\pickaname</em>[<em>optional,features</em>]{<em>Individual Font File</em>} +</code></p> <p>Note that if you define a font <em>family</em> when you should have just defined a font <em>face</em>, there will be complaints in the log file, because the font loaded cannot find the (nonexistent) other members of the family. But the document will compile. On the other hand, if you define a font <em>face</em> when you should have defined a font <em>family</em>, then commands for bold or italic will have no effect, since the other family members were not loaded. Again, the document will compile.</p> -<p>The \NewFontFamily command (or \NewFontFace) takes three arguments: First, the name of the new font command is required. Second, font features are optional. Third, the font name is required.</p> -<p style="margin-top:16px"><b>Example:</b> Suppose your work is science fiction, and one if its characters is a talking robot. You wish to depict its utterances in a robotic-looking font, which will be called using a new \robovoice command. You shop around, and find that the <em>Orbitron</em> font suits your purpose, except that it is too large compared to your <em>textfont</em>. So, you scale it.</p> +<p style="margin-top:16px"><b>Example:</b> Suppose your work is science fiction, and one if its characters is a talking robot. You wish to depict its utterances in a robotic-looking font, which will be called using a new <code>\robovoice</code> command. You shop around, and find that the <em>Orbitron</em> font suits your purpose, except that it is too large compared to your <em>textfont</em>. So, you scale it.</p> <p>In the Preamble, you define the new font command:</p> <p class="code"><code>\NewFontFace\robovoice[Scale=0.8]{Orbitron} % not part of a family</code></p> -<p>After some experimentation, you realize that the \robovoice letters need to be spread apart a bit. Do not use the standard LaTeX \textls command. Instead, go back and change the font definition like this: +<p>After some experimentation, you realize that the \robovoice letters need to be spread apart a bit. Do not use the standard LaTeX <code>\textls</code> command. Instead, go back and change the font definition like this: <p class="code"><code>\NewFontFace\robovoice[Scale=0.8,LetterSpace=<em>number</em>]{Orbitron} % pick a number</code></p> <p>In the document body:</p> <p class="code"><code> @@ -1165,17 +1182,17 @@ OSX: <code>/Library/Colorsync/Profiles/</code> or hidden <code>(username)/Librar Nonexistent Publications • Portland, Oregon\par<br/> \end{center} </code></p> -<p style="clear:both; margin-top:16px; font-size:small">Note: Command \NewFontFamily is identical to \newfontfamily, and command \NewFontFace is identical to \newfontface.</p> </div><!-- end class="d3" --> <h3 id="h5.4">5.4. Font Customization Syntax</h3> <div class="d3" id="d5.4"> -<p class="noindent">You will be using <code>fontspec</code> syntax to select your own fonts. Much of what follows is a digested portion of the full <code>fontspec</code> documentation. There are many more features, and ways to use them, than will be described below.</p> +<p class="noindent">You will be using <i>fontspec</i> syntax to select your own fonts. Much of what follows is a digested portion of the full <i>fontspec</i> package documentation. There are many more features, and ways to use them, than will be described below.</p> <h4 id="h5.4.1">5.4.1. Font (Family) Name vs. Font File Name</h4> <div class="d4" id="d5.4.1"> <p class="noindent">A <em>font file</em> is an individual file, with its own <em>file name</em>, including file extension. For example, libertinusserif-regular.otf and libertinusserif-italic.otf are two different font files. This much is obvious.</p> -<p>A <em>font family name</em>, often merely called <em>font name</em>, refers to one or more font files that are variations of the same basic font. Some fonts are so unique that the family consists of just one file. For example, the NovelDeco font family consists of the one file NovelDeco.otf. Typically, a font family has four files, consisting of Regular, Italic, Bold, and BoldItalic variants. Even though there are four font files, there is a single font family name. Many font families have more than four files, including Semibold and Light weights, and Condensed tracking. It is up to the font designer to decide whether a Condensed variation of the "Bubble Turble" font should be treated as a member of the "Burble Turble" family, or as a separate "Burble Turble Condensed" family.</p> +<p>A <em>font family name</em>, often merely called <em>font name</em>, refers to one or more font files that are variations of the same basic font. Some fonts are so unique that the family consists of just one file. For example, the <i>NovelDeco</i> font family consists of the one file <i>NovelDeco.otf</i>. Typically, a font family has four files, consisting of Regular, Italic, Bold, and BoldItalic variants. Even though there are four font files, there is a single font family name.</p> +<p>Many font families have more than four files, including Semibold and Light weights, and Condensed tracking. It is up to the font designer to decide whether a Condensed variation of the "Bubble Turble" font should be treated as a member of the "Burble Turble" family, or as a separate "Burble Turble Condensed" family.</p> <p>The font (family) name can be learned by opening font files in your system font viewer. Currently, the Windows 10 font viewer uses "Font name" and the Ubuntu font viewer puts the font name in more prominent type. A font (family) name may contain more than one word, with or without spaces, and may contain a general classification such as <em>serif</em>, <em>sans</em>, or <em>mono</em>, because those are actually different families. But it will not contain words such as <em>regular</em>, <em>medium</em>, <em>semibold</em>, <em>bold</em>, or <em>italic</em>; those are for individual members of the same family. Within TeX, some of the older PostScript fonts have been re-worked as newer TrueType and Open Type fonts. The family names are slightly different, so pay attention.</p> <p class="centerimg"> <img src="html-resources/win10libser.png" width="268" height="184" alt="Windows 10 font viewer"/> @@ -1192,8 +1209,8 @@ Nonexistent Publications • Portland, Oregon\par<br/> <p class="code" style="clear:both"><code>\NewFontFamily\rway{Raleway}</code></p> <p>Document Body:</p> <p class="code"><code>{\rway I came, \textbf{I saw}, \emph{I conquered}, \textsc{I left}.}</code></p> -<p style="margin-top:10px"><b>By file names:</b></p> -<p><img class="floatright" style="padding-top:12px" src="html-resources/fontbyfilenamei.png" width="335" height="44" alt="font file defined"/> However, if you specify the <em>font file name</em>, then <em>only</em> that font file will be used, regardless of requests for bold or italic. Small caps will be honored, if the specific file has them:</p> +<p style="margin-top:10px"><b>By file name:</b></p> +<p><img class="floatright" style="padding-top:12px" src="html-resources/fontbyfilenamei.png" width="335" height="44" alt="font file defined"/> However, if you specify a single <em>font file name</em>, then <em>only</em> that font file will be used, regardless of requests for bold or italic. Small caps will be honored, if the specific file has them:</p> <p>Preamble:</p> <p class="code" style="clear:both"><code>\NewFontFamily\rwayi{Raleway-Regular-Italic.otf}</code></p> <p>Document Body:</p> @@ -1219,7 +1236,7 @@ Nonexistent Publications • Portland, Oregon\par<br/> <h4 id="h5.4.3">5.4.3 Open Type Features</h4> <div class="d4" id="d5.4.3"> -<p class="noindent">Features are variations, contained within a single font file. In the bad old days, when you wanted true small caps, you had to load a separate font file that had them (and did not have ordinary lowercase letters). Now, if an Open Type font file has the "smcp" feature, you obtain the small caps from within the same file, by asking for them. Requests for the feature may be made on-the-fly, or pre-loaded for global use.</p> +<p class="noindent">Features are variations, contained within a single font file. In the bad old days, when you wanted true small caps, you had to load a separate font file that had them (and did not have ordinary lowercase letters). Now, if an Open Type font file has the <i>smcp</i> feature (most do), you obtain the small caps from within the same file, by asking for them. Requests for the feature may be made on-the-fly, or pre-loaded for global use.</p> <p>Here are several of the most frequently-used features, relevant to fiction writing. There are many more, and most fonts have only a few of them. Even when a font has a feature, it may be limited to some portion of the characters. For example, it is common for small caps to be available only for Latin-1 letters, even though the font also contains Greek and Cyrillic. To put this another way: The availability of a feature does not tell you its breadth of coverage. Unless the font has documentation showing coverage of its features, the only way to find out is to create and print a test page.</p> <table class="preconf"> <caption> @@ -1270,16 +1287,17 @@ Some Frequently-Used Open Type Features </tr> </tbody> </table> -<p>• Kerning is the automatic adjustment of spacing between letters, so that they fit together nicely. Common ligatures are substitutions, such as a combined <i>ff</i> character for two consecutive <i>f</i> characters. It is up to the font designer to determine which ligatures, if any, are common.</p> +<p>• Kerning is the automatic adjustment of spacing between letters, so that they fit together nicely. The values are read from tables within the font.</p> +<p>• Common ligatures are substitutions, such as a combined <i>ff</i> character for two consecutive <i>f</i> characters. It is up to the font designer to determine which ligatures, if any, are common.</p> <p>• TeX ligatures (such as replacing `` with “ and --- with —) are not actually an Open Type feature, but they are treated that way by the software. All of these are enabled by default. The <i>fontspec</i> manual explains how to disable them, if necessary.</p> <p>• The SmallCaps feature applies only to lowercase letters; ordinary capitals remain ordinary capitals. UppercaseSmallCaps deals only with converting ordinary capitals to small caps. If you want both, use both. In most fonts that have them, small caps are slightly taller than lowercase, and slightly more widely spaced. What distinguishes real small caps from fake ones (obtained by scaling ordinary capitals) is that the weight and spacing are more compatible with surrounding text.</p> <p class="centerimg"><img src="html-resources/smallcapsrealfake.png" width="478" height="43" alt="real vs fake small caps"/></p> -<p>• Lining numerals are the ones most familiar to you, from math or accounting. They sit on the baseline and have the height of capital letters. That's just right for doing calculations, and doesn't look bad for things such as page numbers and chapter numbers.</p> +<p>• Lining numerals are the ones most familiar to you, from math or accounting. They sit on the baseline and have the height of capital letters. That's just right for doing calculations, and is acceptable for things such as page numbers and chapter numbers.</p> <p>• When lining numerals are mingled with flowing text, they may stand out too much. OldStyle numerals are more like flowing text: Most of the numerals are at lowercase height, with ascenders and descenders. Compare the first number as OldStyle, the second as Lining:</p> <p class="centerimg"><img src="html-resources/jollybeers.png" width="499" height="52" alt="oldstyle vs lining numerals"/></p> <p>Most fonts use Lining numerals as their default. A few default to OldStyle numerals. Thus, you should explicitly call for the kind of numerals you wish to use.</p> -<p>• True OldStyle numerals have a flat top on <em>one</em>, and a very round <em>zero</em>: <img src="html-resources/10trueold.png" width="37" height="13" alt="true oldstyle 10"/> This may be a bit distracting. Some fonts use a transitional form, where the one has a tilted top (like big 1) and the zero is not so round: <img src="html-resources/10transold.png" width="37" height="13" alt="transitional oldstyle 10"/> Others offer you a choice, via an Open Type "style set." See the <code>fontspec</code> manual for how to code style sets.</p> -<p>• There are many more Open Type features, most of which are not useful in ordinary fiction writing. Fonts rarely have more than a few features. Some features (such as the ones shown above) have a specific meaning. Other features, such as "style sets", have whatever meaning the font designer assigns them; Thus the "ss03" feature of one font may do something very different from "ss03" in a different font.</p> +<p>• True OldStyle numerals have a flat top on <em>one</em>, and a very round <em>zero</em>: <img src="html-resources/10trueold.png" width="37" height="13" alt="true oldstyle 10"/> This may be a bit distracting. Some fonts use a transitional form, where the one has a tilted top (like big 1) and the zero is not so round: <img src="html-resources/10transold.png" width="37" height="13" alt="transitional oldstyle 10"/> Others offer you a choice, via an Open Type "style set." See the <i>fontspec</i> manual for how to code style sets.</p> +<p>• There are many more Open Type features, most of which are not useful in ordinary fiction writing. Fonts rarely have more than a few features. Some features (such as the ones shown above) have a specific meaning. Other features, such as "style sets", have whatever meaning the font designer assigns them; Thus the <i>ss03</i> feature of one font may do something very different from <i>ss03</i> in a different font.</p> </div> <h4 id="h5.4.4">5.4.4. Scale as Pseudo-Feature</h4> @@ -1296,30 +1314,31 @@ Some Frequently-Used Open Type Features <h4 id="h5.4.5">5.4.5 Color and Opacity</h4> <div class="d4" id="d5.4.5"> -<p class="noindent">Even though the <i>fontspec</i> syntax allows you to set <i>Color</i> and <i>Opacity</i> as pseudo-features when you define a font, <em>the novel class blocks these features.</em> If you attempt to set them as features in a font definition, an error will result. The same applies if you attempt to add them, using \addfontfeature. However, you can still make use of grayscale using ordinary, local color commands.</p> +<p class="noindent">Even though the <i>fontspec</i> syntax allows you to set <i>Color</i> and <i>Opacity</i> as pseudo-features when you define a font, <em>the novel class blocks these features.</em> If you attempt to set them as features in a font definition, an error will result. The same applies if you attempt to add them, using <code>\addfontfeature</code>. However, you can still make use of grayscale using ordinary, local color commands.</p> <p>When you use the <i>graytext</i> class option, you may write text in grayscale, using commands from the included <i>xcolor</i> package. You should only do this for text that is in special locations. For example, if you begin each chapter with a number that is very large, you might wish to make that number gray, so that it does not overpower the main text.</p> <p>To avoid possible conflicts, the color specification should be chosen from a limited list of names. In order from dark to light: black, blue, violet, darkgray, purple, red, teal, olive, magenta, gray, brown, green, orange, cyan, lightgray, lime, pink, yellow, white. They will all be rendered in <em>shades of gray</em> (of course, black and white will be themselves). You may also choose from this more convenient list: black, gray1, gray2, gray3, gray4, gray5, gray6, gray7, gray8, gray9, white.</p> <p>If <i>graytext</i> is not chosen as class option, then any color (even white) will be rendered as black.</p> +<p>• Placing light text over a dark background may produce unexpected results in print, even if it looks good in PDF. If you need this effect, it is better to build the text into the background, as a single image.</p> </div> -<h4 id="h5.4.6">5.4.6. \CreateFeature{<em>code</em>}{<em>substitutions</em>}</h4> +<h4 id="h5.4.6">5.4.6. <code>\CreateFontFeature{<em>code</em>}{<em>substitutions</em>}</code></h4> <div class="d4" id="d5.4.6"> <p class="noindent">Once in a while, a font has a glyph that you would like to use, but it is not included in any of the font's Open Type feature sets. So, how to you grab that particular glyph? For example: One well-known font has a glyph named <em>emdash.alt</em>, which is not as long as the font's ordinary <em>emdash</em> glyph, and looks better in text. Unfortunately, <em>emdash.alt</em> is not in any of the font's style sets. Without some trickery, only a program such as InDesign can grab that glyph.</p> -<p>Thanks to <i>fontspec</i>, <i>novel</i> has the necessary trickery. Command \CreateFeature creates a fake Open Type feature code, and assigns your list of substitutions to that code. Use comma-separated entries if there are multiple substitutions. For the case in question:</p> -<p class="code"><code>\CreateFeature{myem}{emdash=emdash.alt}</code></p> +<p>Thanks to <i>fontspec</i>, <i>novel</i> has the necessary trickery. Command <code>\CreateFontFeature</code> creates a fake Open Type feature code, and assigns your list of substitutions to that code. Use comma-separated entries if there are multiple substitutions. For the case in question:</p> +<p class="code"><code>\CreateFontFeature{myem}{emdash=emdash.alt}</code></p> <p>The code <i>myem</i> was randomly chosen as something that is not already defined among Open Type feature codes. Once specified, the fake feature may be used in any font definition, such as this:</p> -<p class="code"><code>\SetMasterFont[RawFeature=+myem]{Adobe Garamond Pro}</code></p> +<p class="code"><code>\SetParentFont[RawFeature=+myem]{Adobe Garamond Pro}</code></p> <p>Of course, the fake feature has no effect if the font does not have the substitution character.</p> <p>This technique may be used for more complicated features, but that is beyond the scope of this documentation. See the <i>fontspec</i> manual if you need to do more.</p> </div> <h4 id="h5.4.7">5.4.7. Local Modifications to Open Type Features</h4> <div class="d4" id="d5.4.7"> -<p class="noindent">If you specify a particular Open Type feature, it will be generally used for that font command. So if you define a new font command with <i>Letters=SmallCaps</i> as a feature (and if the font actually has them), then small caps will be used for that font, whether or not you locally request them with a command such as \textsc.</p> -<p>Often, you can add (or sometimes remove) features on a local basis. For example, suppose that you defined the font without using is <i>ss03</i> style set. You can locally add that feature to some text, using a command that looks like this:</p> +<p class="noindent">If you specify a particular Open Type feature, it will be generally used for that font command. So if you define a new font command with <i>Letters=SmallCaps</i> as a feature (and if the font actually has them), then small caps will be used for that font, whether or not you locally request them with a command such as <code>\textsc</code>.</p> +<p>Often, you can add (or sometimes remove) features on a local basis. For example, suppose that you defined the font without using its <i>ss03</i> style set. You can locally add that feature to some text, using a command that looks like this:</p> <p class="code"><code>{\addfontfeature{<em>which feature</em>} <em>applied to this text</em>}</code></p> <p>The above code assumes that you are already using the font in that location. You cannot apply <i>ss03</i> from one font to an entirely different font!</p> -<p>See the <i>fontspec</i> documentation for details of \addfontfeature.</p> +<p>See the <i>fontspec</i> documentation for details of <code>\addfontfeature</code>.</p> <p>As an alternative to changing features locally, you can define different font commands to call the same underlying font, but with different features.</p> <p>Two ways to accomplish the same thing:</p> <p class="code"><code> @@ -1336,22 +1355,22 @@ Some text {\baskf\addfontfeature{Numbers=Monospaced} hello 123} is here. <div class="d3" id="d5.5"> <p class="noindent">In <i>novel</i>, superscripts and subscripts are called "markers." Most book-quality Open Type fonts have markers in style sets (<i>sups</i>, <i>sinf</i>, <i>subs</i>).</p> <p>In professional fonts, marker glyph weights are adjusted for consistent appearance compared to ordinary glyphs. However, many free fonts do not adjust marker glyph weights, so the markers may appear too small, or too light. You may choose whether to use a font's own markers, or allow <i>novel</i> to generate markers, depending on whichever you think looks better.</p> +<p>• <i>real</i> markers attempt to use the Open Type feature <i>sups</i> for superscripts, and the feature <i>sinf</i> (preferred) or <i>subs</i> (alternate) for subscripts. If the requested feature is not available for the font, then it will be automatically faked, by scaling/raising/lowering ordinary characters from the basefont (lining numerals will be used).</p> +<p>• <i>fake</i> markers ignore whether the Open Type features are available, and simply fakes them.</p> -<h4 id="h5.5.1">5.5.1 \SetMarkers[<em>real,fake</em>]{<em>asterisk, dagger, number</em>}</h4> +<h4 id="h5.5.1">5.5.1 <code>\SetMarkers[<em>real,fake</em>]{<em>asterisk, dagger, number</em>}</code></h4> <div class="d4" id="d5.5.1"> -<p>This command is used only in the Preamble. Default is <i>real</i> and <i>asterisk</i>.</p> -<p>• The option <i>real</i> (default) attempts to use the Open Type feature <i>sups</i> for superscripts, and the feature <i>sinf</i> (preferred) or <i>subs</i> (alternate) for subscripts. If the requested feature is not available, then it will be automatically faked, by scaling/raising/lowering ordinary characters from the basefont (lining numerals will be used).</p> -<p>• Option <i>fake</i> ignores whether the Open Type features are available, and simply fakes them.</p> -<p>Thus, you may choose whether real or fake markers look better, depending on the font you are using. What looks better in one font may not look better in another.</p> -<p>• The required argument applies only to markers created by the \footnote command. It does not apply to endnotes, or to manually placed superscripts and subscripts.</p> -<p><i>asterisk</i> (default) uses symbolic footnote markers. The symbols rotate in order * † ‡ § ** †† ‡‡ §§ until reset.</p> -<p><i>dagger</i> uses symbolic footnote markers, but without asterisks. The symbols rotate in order † ‡ § †† ‡‡ §§ until reset.</p> -<p><i>number</i> uses numerical markers. Due to possible conflict, the log file will have a "Big Bad Warning" if you use a numerical footnote marker in a document that also has endnotes, since endnotes alays have numerical markers.</p> +<p>This command may only be used in the Preamble. It globally sets the kind of marker to be used. Default is <i>real</i> and <i>asterisk</i>.</p> +<p>The optional argument applies real or fake markers, as described above.</p> +<p>The required argument applies only to markers created by the <code>\footnote</code> command. It does not apply to endnotes, or to manually placed superscripts and subscripts.</p> +<p>• <i>asterisk</i> (default) uses symbolic footnote markers. The symbols rotate in order * † ‡ § ** †† ‡‡ §§ until reset.</p> +<p>• <i>dagger</i> uses symbolic footnote markers, but without asterisks. The symbols rotate in order † ‡ § †† ‡‡ §§ until reset.</p> +<p>• <i>number</i> uses numerical footnote markers. Due to possible conflict, the log file will have a "Big Bad Warning" if you use a numerical footnote marker in a document that also has endnotes, since endnotes always have numerical markers.</p> </div> -<h4 id="h5.5.2">5.5.2 \realmarker, \fakemarker</h4> +<h4 id="h5.5.2">5.5.2 <code>\realmarker</code>, <code>\fakemarker</code></h4> <div class="d4" id="d5.5.2"> -<p class="noindent">Within the body of the document, you may use \realmarker and \fakemarker to change your preference. The choice remains in effect until you change it again.</p> +<p class="noindent">Within the body of the document, you may use <code>\realmarker</code> and <code>\fakemarker</code> to change your preference. The choice remains in effect until you change it again.</p> <p>The option real/fake applies wherever superscripts or subscripts are used, not just for footnotes or endnotes.</p> </div> </div><!-- end class="d3" --> @@ -1375,18 +1394,18 @@ Some text {\baskf\addfontfeature{Numbers=Monospaced} hello 123} is here. <h4 id="h6.1.1">6.1.1. <code>\SetHeadJump{<em>number</em>}</code>, <code>\SetFootJump{<em>number</em>}</code></h4> <div class="d4" id="d6.1.1"> -<p class="noindent">These two commands control the separation between the header/footer and the main text. Since they pertain to page layout, rather than style, their usage is described above, in the layout section.</p> +<p class="noindent">These two commands control the separation between the header/footer and the main text. Since they pertain to page layout, rather than style, their usage is described above, in layout <a href="#h4.2.6">section 4.2.6</a>.</p> </div> <h4 id="h6.1.2">6.1.2. <code>\SetHeadFootStyle{<em>number</em>}</code></h4> <div class="d4" id="d6.1.2"> -<p class="noindent">Command \SetHeadFootStyle{<em>number</em>} chooses among several pre-configured header/footer styles, numbered 1 through 6. The default is style 1. The internals of the configuration can then be changed using a variety of commands.</p> +<p class="noindent">Command <code>\SetHeadFootStyle{<em>number</em>}</code> chooses among several pre-configured header/footer styles, numbered 1 through 6. The default is style 1. The internals of the configuration can then be changed using a variety of commands.</p> <p>Some styles support an optional "emblem", which applies a decoration near the page number.</p> <p>Style 0 means neither header nor footer. Not practical for fiction, but it exists.</p> <p> </p> <img class="floatright" src="html-resources/headfoot1.png" width="276" height="219" alt="style 1" title="style 1"/> <p style="padding-left:16px"> -<b>\SetHeadFootStyle{1}</b></p> +<b><code>\SetHeadFootStyle{1}</code></b></p> <p>Only Header.<br/> Page number at outside (left verso, right recto).<br/> Optional emblem adjacent to page number.<br/> @@ -1395,21 +1414,21 @@ Text centered. Default author verso, title recto.<br/> <div style="clear:both"></div> <img class="floatright" src="html-resources/headfoot2.png" width="276" height="219" alt="style 2" title="style 2"/> <p style="padding-left:16px"> -<b>\SetHeadFootStyle{2}</b></p> +<b><code>\SetHeadFootStyle{2}</code></b></p> <p>Only Footer.<br/> Page number at outside (left verso, right recto).<br/> Optional emblem adjacent to page number.</p> <div style="clear:both"></div> <img class="floatright" src="html-resources/headfoot3.png" width="276" height="219" alt="style 3" title="style 3"/> <p style="padding-left:16px"> -<b>\SetHeadFootStyle{3}</b></p> +<b><code>\SetHeadFootStyle{3}</code></b></p> <p>Only Footer.<br/> Page number centered.<br/> Disregards emblem, if coded.</p> <div style="clear:both"></div> <img class="floatright" src="html-resources/headfoot4.png" width="276" height="219" alt="style 4" title="style 4"/> <p style="padding-left:16px"> -<b>\SetHeadFootStyle{4}</b></p> +<b><code>\SetHeadFootStyle{4}</code></b></p> <p>Only Header.<br/> Page number at outside (left verso, right recto).<br/> Optional emblem adjacent to page number.<br/> @@ -1419,7 +1438,7 @@ Default author verso, title recto.</p> <div style="clear:both"></div> <img class="floatright" src="html-resources/headfoot5.png" width="276" height="219" alt="style 5" title="style 5"/> <p style="padding-left:16px"> -<b>\SetHeadFootStyle{5}</b></p> +<b><code>\SetHeadFootStyle{5}</code></b></p> <p>Header and Footer.<br/> Page number centered in footer.<br/> Disregards emblem, if coded.<br/> @@ -1428,7 +1447,7 @@ Default author verso, title recto.</p> <div style="clear:both"></div> <img class="floatright" src="html-resources/headfoot6.png" width="276" height="219" alt="style 6" title="style 6"/> <p style="padding-left:16px"> -<b>\SetHeadFootStyle{6}</b></p> +<b><code>\SetHeadFootStyle{6}</code></b></p> <p>Only Header.<br/> Page number at outside (left verso, right recto).<br/> Optional emblem adjacent to page number.<br/> @@ -1440,17 +1459,17 @@ Default author verso, title recto.</p> <div class="d5" id="d6.1.2.1"> <p class="noindent">Before you think about writing custom header/footer styles, be sure to try the pre-configured choices. I have looked through a lot of fiction of all kinds. The pre-configured choices include every style I have seen, with the exception of the most highly decorative.</p> <p>If none of the above are satisfactory, then you can write your own headers and footers using the syntax of the <code>fancyhdr</code> package.</p> -<p>• In the Preamble, use one of the above \SetHeadFootStyle{<em>integer</em>} to pick a starting point, in terms of whether or not there is a header and/or footer. <em>This is required, so that the layout engine knows how to calculate space.</em> After that, write the <i>fancyhdr</i> code for your custom header/footer in the Preamble. It will over-ride the numerical style in terms of appearance, but occupy the same space.</p> +<p>• In the Preamble, use one of the above <code>\SetHeadFootStyle{<em>integer</em>}</code> to pick a starting point, in terms of whether or not there is a header and/or footer. <em>This is required, so that the layout engine knows how to calculate space.</em> After that, write the <i>fancyhdr</i> code for your custom header/footer in the Preamble. It will over-ride the numerical style in terms of appearance, but occupy the same space.</p> <p>• You cannot use a header or footer with more than one line. No exceptions.</p> <p>• See the file <i>novel-HeadFootStyles.sty</i> for how it is done in the pre-configured styles. In the file, the relevant portion follows <em>Look here for the pre-defined styles, for use as models.</em></p> -<p>• Particularly note that your own style will not automatically use the headfont, or loose tracking, unless you include the necessary code in your own definition. Do not use the \textls command.</p> +<p>• Particularly note that your own style will not automatically use the <i>headfont</i>, or add extra space between letters, unless you include the necessary code in your own definition. Do not use the <code>\textls</code> command.</p> <p>• No cheating! If you choose a numerical style that does not have a header, then do not attempt to write a custom style that includes a header. Same with footer. Also, if you you choose a numerical style with both header and footer, then you cannot only customize one of them; you must customize both.</p> </div></div><!-- end class="d4" --> <h4 id="h6.1.3">6.1.3. <code>\SetEmblems{<em>verso</em>}{<em>recto</em>}</code></h4> <div class="d4" id="d6.1.3"> <p class="noindent">If the style supports it, you may place an "emblem" that appears at a fixed distance (2.5em} from the outer margin. Thus, it will appear to the right of the page number on verso pages, and to the left of the page number on recto pages. In the case of style 4, there will be a clearance of 1em between the emblem and the header text.</p> -<p>The font used for emblems will be the same as the headfont, unless you code the emblem to use a different font (perhaps one you specified with the \NewFontFace command), or unless you use one of the built-in \decoglyph codes.</p> +<p>The font used for emblems will be the same as the headfont, unless you code the emblem to use a different font (perhaps one you specified with the <code>\NewFontFace</code> command), or unless you use one of the built-in <code>\decoglyph</code> codes.</p> <p>An emblem is a minor decoration that should not distract the eye from the main text.</p> <p><img class="floatright" src="html-resources/emblembar.png" width="380" height="104" alt="simple emblems using vertical bar"/>• Most books do not use emblems. When they do, it is typically a vertical bar, or a bullet, like this:</p> <p class="code"><code>\SetHeadFootStyle{4}</code></p> @@ -1460,20 +1479,20 @@ Default author verso, title recto.</p> <p>The header emblems shown at right were produced using the code below. Dingbats from the NovelDeco font were specified, adjusted for size and position.</p> <p style="clear:both" class="code"><code>\SetEmblems{\charscale{1.1}{\raisebox{-0.05em}{\decoglyph{l9825}}}}%</code></p> <p class="code"><code>{\charscale{1.1}{\raisebox{-0.05em}{\decoglyph{l9826}}}}</code></p> -<p>• You may also use images, or combined images and text. If you use images, they must be at the exact resolution required by your print service (usually 300dpi for gray, 600dpi for b/w), and at exact size without scaling. The \InlineImage command must be used. See <i>novel's</i> image documentation details. You may find that a vertical offset of \nfs (normal font size) is useful, as this will place the top of the emblem image at the top margin.</p> +<p>• You may also use images, or combined images and text. If you use images, they must be at the exact resolution required by your print service (usually 300dpi for gray, 600dpi for b/w), and at exact size without scaling. The <code>\InlineImage</code> command must be used. See <i>novel's</i> image documentation details. You may find that a vertical offset of <code>\nfs</code> (normal font size) is useful, as this will place the top of the emblem image at the top margin.</p> <p class="code" style="text-indent:0px"><img class="floatright" src="html-resources/emblemimg.png" width="295" height="77" alt="emblem image"/> <code>\SetHeadFootStyle{4}<br/> \SetEmblems{\InlineImage[0pt,b]{spy.png}}%<br/> {\InlineImage[0pt,b]{spy.png}} </code></p> -<p>• At the small size of an emblem, it is difficult to use detailed artwork. A black/white image at 600dpi will print similarly to a font dingbat. Grayscale at 300dpi will probably not be satisfactory unless the emblem is a single shade of gray. For the above example, a character from the "Fontawesome" font was converted to a png image at mid-gray. It is less distracting than a black character from the font, but hard to discern. Note that there is no "gray ink" for directly writing text in gray.</p> +<p>• At the small size of an emblem, it is difficult to use detailed artwork. A black/white image at 600dpi will print similarly to a font dingbat. Grayscale at 300dpi will probably not be satisfactory unless the emblem is a single shade of gray. For the above example, a character from the <i>Fontawesome</i> font was converted to a png image at mid-gray. It is less distracting than a black character from the font, but hard to discern. Note that there is no "gray ink" for directly writing text in gray.</p> <p>• Ask your print service whether the presence of a small image in each page header will affect production costs. Probably not, but if there is a different per-page charge when pages have an image... Oops!</p> -<p>• The layout calculation does not care whether emblems intrude into the margins. You will have to inspect your PDF to determine whether a header emblem is too tall, or a footer emblem too deep, for the allowed top and bottm margin clearance. Class option <i>shademargins</i> (in draft mode only) is helpful.</p> +<p>• The layout calculation does not care whether emblems intrude into the margins. You will have to inspect your PDF to determine whether a header emblem is too tall, or a footer emblem too deep, for the allowed top and bottom margin clearance. Class option <i>shademargins</i> (in draft mode only) is helpful.</p> </div> <h4 id="h6.1.4">6.1.4. <code>\SetPageNumberStyle{<em>code using \thepage</em>}</code></h4> <div class="d4" id="d6.1.4"> -<p class="noindent">By default, the page number is simply \thepage. In most cases, leave it that way. But if you wish to change how the page number is displayed, you can use this command to style how \thepage is displayed. Examples:</p> +<p class="noindent">By default, the page number is simply <code>\thepage</code>. In most cases, leave it that way. But if you wish to change how the page number is displayed, you can use this command to style how <code>\thepage</code> is displayed. Examples:</p> <p class="code" style="text-indent:0px"><code>\SetPageNumberStyle{\emph{thepage}} % Page number in italics.<br/> \SetPageNumberStyle{-- \thepage --} % En-dash on each side of number, for head/foot style 3 or 5.</code></p> <p>The <i>headfont</i> is applied automatically, unless you over-ride it in your code.</p> @@ -1482,27 +1501,27 @@ Default author verso, title recto.</p> <h4 id="h6.1.5">6.1.5. <code>\SetHeadFont[<em>features</em>]{<em>font</em>}</code></h4> <div class="d4" id="d6.1.5"> -<p class="noindent">This setting is described earlier on this page.</p> +<p class="noindent">This setting is described in <a href="#h5.1.5">section 5.1.5</a>.</p> </div> <h4 id="h6.1.6">6.1.6. <code>\SetLooseHead{<em>number</em>}</code></h4> <div class="d4" id="d6.1.6"> <p class="noindent">This command applies to both headers and footers.</p> <p>If you are using a style that has header text, then for best appearance the characters should appear with a little extra space between them, so that they are more easily distinguished from the main text. This is especially true if you are using small caps. The name for such adjustment is "tracking."</p> -<p>Note: Do not use the \textls command. It is disabled in this class.</p> +<p>Note: Do not use the <code>\textls</code> command. It is disabled in this class.</p> <p class="centerimg"><img src="html-resources/looseheads.png" width="400" height="76" alt="loosehead 50 and 100"/></p> -<p>The argument of \SetLooseHead is a number from 0 to 1000. At 0 there is no extra space between the letters. Values from 50 (default) to 200 are most useful. Higher values are unusual.</p> +<p>The argument of <code>\SetLooseHead</code> is a number from 0 to 1000. At 0 there is no extra space between the letters. Values from 50 (default) to 200 are most useful. Higher values are unusual.</p> <p>Page number tracking will be clamped at a maximum of 50, even when a larger (looser) tracking is applied to text.</p> -<p>The looseness applies to inter-letter spacing, but not to inter-word spacing. To increase inter-word spacing, use extra code such as \, (which is a LaTeX thin space) as needed.</p> +<p>The looseness applies to inter-letter spacing, but not to inter-word spacing. To increase inter-word spacing, use extra code such as <code>\,</code> (backslash comma, which is a LaTeX thin space) as needed.</p> </div> <h4 id="h6.1.7">6.1.7. <code>\SetChapterStart{<em>choice</em>}</code></h4> <div class="d4" id="d6.1.7"> -<p class="noindent">This command is only applied if you begin new chapters with the ChapterStart environment. You may pick one of the \thispagestyle choices, described in the next section. For example:</p> +<p class="noindent">This command is only applied if you begin new chapters with the <a href="#h11.1">ChapterStart</a> environment. You may pick one of the <code>\thispagestyle</code> choices, described in the <a href="#h6.2.2">section 6.2.2</a>. For example:</p> <p class="code"><code>\SetChapterStart{dropfolioinside}</code></p> -<p>Then, that choice will be applied to each page that uses ChapterStart, without you having to write \thispagestyle each time.</p> +<p>Then, that choice will be applied to each page that uses ChapterStart, without you having to write <code>\thispagestyle</code> each time.</p> <p>The default is <i>footer</i>. This allows a ChapterStart page to show its footer (only if it has one), but not header.</p> -<p>If you use this command, you may still over-ride it on a particular page, by using \thispagestyle{<em>choice</em>} <em>before</em> \begin{ChapterStart}.</p> +<p>If you use this command, you may still over-ride it on a particular page, by using <code>\thispagestyle{<em>choice</em>}</code> <em>before</em> <code>\begin{ChapterStart}</code>.</p> </div> </div><!-- end class="d3" --> @@ -1512,11 +1531,11 @@ Default author verso, title recto.</p> <h4 id="h6.2.1">6.2.1. <code>\SetVersoHeadText{<em>text</em>}</code><code>\SetRectoHeadText{<em>text</em>}</code></h4> <div class="d4" id="d6.2.1"> -<p class="noindent">If you are using style 1, 4, 5, or 6, the header text can be dynamically changed from page to page. This feature is useful if your wish to include chapter titles in the header. It is also useful if your work is a collection of stories with different titles, perhaps by different authors. But before you use this feature, speak with your print service! Many print-on-demand services will insist that the content of headers must not vary from place to place, because different headers may be confused with portions of different books, during the assembly process.</p> +<p class="noindent">If you are using <a href="#h6.1.2">head/foot style</a> 1, 4, 5, or 6, the header text can be dynamically changed from page to page. This feature is useful if you wish to include chapter titles in the header, since they change throughout the book. It is also useful if your work is a collection of stories with different titles, perhaps by different authors. But before you use this feature, speak with your print service! Many print-on-demand services will insist that the content of headers must not vary from place to place, because different headers may be confused with portions of different books, during the assembly process.</p> <p class="code"><code>\SetVersoHeadText{New Verso Head}</code><br/><code>\SetRectoHeadText{New Recto Head}</code></p> -<p>These two commands may be used at any time, in the Preamble or document body. When a command is used, it stores its argument in \versoheadtext or \rectoheadtext. In turn, the current value of \versoheadtext or \rectoheadtext is immediately used for the header, and will remain in effect until changed again by \SetVersoHeadText or \SetRectoHeadText.<p> +<p>These two commands may be used at any time, in the Preamble or document body. When a command is used, it stores its argument in <code>\versoheadtext</code> or <code>\rectoheadtext</code>. In turn, the current value of <code>\versoheadtext</code> or <code>\rectoheadtext</code> is immediately used for the header, and will remain in effect until changed again by <code>\SetVersoHeadText</code> or <code>\SetRectoHeadText</code>.<p> <p>If you do not use these commands in the Preamble, then at the beginning of the document body they will be automatically set to the author (verso) and the title (recto). However, you may find that the inter-word space is closer than you would like.<p> -<p>For improved inter-word space, use \, (the LaTeX thin space) in addition to ordinary space. You may use as many as you need.</p> +<p>For improved inter-word space, use <code>\,</code> (backslash comma, the LaTeX thin space) in addition to ordinary space. You may use as many as you need.</p> <p>You may use ordinary LaTeX styling commands for the text:</p> <p class="code"><code>\SetRectoHeadText{The \,\emph{Bad \,Boy} \,Chronicles}</code></p> <p>The most popular styling uses lowercase to small caps:</p> @@ -1527,30 +1546,30 @@ Default author verso, title recto.</p> <h4 id="h6.2.2">6.2.2. <code>\thispagestyle{<em>choice</em>}</code></h4> <div class="d4" id="d6.2.2"> -<p class="noindent">When you choose a style with header, then space is allocated above the text block, where the header will be placed. That space will be allocated whether or not the header is full or empty. The same applies to the footer. This allocation is global, and cannot be changed in your document body. All standard books work this way, not just with TeX.</p> +<p class="noindent">When you choose a <a href="#h6.1.2">head/foot style</a> with header, then space is allocated above the text block, where the header will be placed. That space will be allocated whether or not the header is full or empty. The same applies to the footer. This allocation is global, and cannot be changed in your document body. All standard books work this way, not just with TeX.</p> <p>However, on a per-page basis you can change whether or not a header or footer has visible content. This is routinely done for blank pages, title page, copyright page, and some others. It is also the norm for pages that begin a new chapter.</p> <p>• The word "folio" has several meanings: It may refer to a particular paper size, or to a folded piece of paper at any size, or simply to a page number. Below, "folio" means page number.</p> -<p>• When you use the \thispagestyle command, your choice is applied only to the one page on which the command is written. It is best to use this command at or towards the top of the affected page. If the page uses the ChapterStart environment, and you use \thispagestyle, then you <em>must</em> place \thispagestyle before \begin{ChapterStart}.</p> +<p>• When you use the <code>\thispagestyle</code> command, your choice is applied only to the one page on which the command is written (usally does not have to be at the top of the page). But if the page uses the <a href="#h11.1">ChapterStart</a> environment, and you use <code>\thispagestyle</code>, then you <em>must</em> place <code>\thispagestyle</code> <em>before</em> <code>\begin{ChapterStart}</code>.</p> <p>• The following choices are allowed: <i>fancy</i>, <i>empty</i>, <i>footer</i>, <i>forcenumber</i>, <i>dropfoliobeneath</i>, and <i>dropfolioinside</i>.</p> <p>For compatibility reasons, <i>plain</i> and <i>fancyplain</i> are also allowed, and have the same effect as <i>footer</i>.</p> -<p> <b>\thispagestyle{fancy}</b></p> -<p>This applies the default (fancy) page style, so it is not normally needed. Only use this command to over-ride some other \thispagestyle command, or to over-ride the \SetChapterStart setting.</p> -<p> <b>\thispagestyle{empty}</b></p> +<p> <b><code>\thispagestyle{fancy}</code></b></p> +<p>This applies the default (fancy) page style, so it is not normally needed. Only use this command to over-ride some other \thispagestyle command, or to over-ride the <code>\SetChapterStart</code> setting.</p> +<p> <b><code>\thispagestyle{empty}</code></b></p> <p>Header and footer are both blank.</p> -<p> <b>\thispagestyle{footer}</b></p> +<p> <b><code>\thispagestyle{footer}</code></b></p> <p>Ignored if the style has no footer. If it does, then the usual footer appears. Header, if any, is blank.</p> <p>This command is an alias for <i>fancyplain</i>. It is like the <i>plain</i> style, except that the footer (which is presumed to contain the page number) is fully styled. But unlike <i>plain</i>, the <i>footer</i> style does <em>not</em> cause a page number to appear when no footer exists. If that is what you need, then use either style <i>dropfoliobeneath</i> or <i>dropfolioinside</i>, depending on whether you have extra room in the bottom margin.</p> -<p> <b>\thispagestyle{forcenumber}</b></p> +<p> <b><code>\thispagestyle{forcenumber}</code></b></p> <p>If the style has a footer, then it appears as usual, and the header (if any) is blank. If the style has a header but no footer, then the outside portion of the header (which is presumed to contain the page number and emblem) appears, but the text portion of the header is blank.</p> <p>The <i>forcenumber</i> choice is non-standard. Use it only if you must have a page number, and no other choice is suitable.</p> -<p> <b>\thispagestyle{dropfoliobeneath}</b></p> +<p> <b><code>\thispagestyle{dropfoliobeneath}</code></b></p> <p>The header (if any) is blank. If there is a footer, then it appears as usual. But if there is no footer, this command creates a one-page fake footer, which contains the centered page number. The fake footer is located where the next line of text would be, if the textblock were one line longer than its actual value.</p> <p>• For the fake footer to be acceptable in print, the bottom margin must be wider than the minimum amount required by your print service. For example, suppose that the minimum bottom margin is 0.5in, but you set the bottom margin to 0.75in. That gives you 0.25in wiggle room, into which the fake footer will probably fit, because typical baselineskip is 0.2in to 0.25in.</p> <p>• The document class does not know whether or not you have extra space available in the bottom margin. It is your responsibility to know.</p> -<p> <b>\thispagestyle{dropfolioinside}</b></p> +<p> <b><code>\thispagestyle{dropfolioinside}</code></b></p> <p>The header (if any) is blank. If there is a footer, then it appears as usual. But if there is no footer, this commands temporarily reduces the number of lines per page by one line. At the bottom, where the last line of text would normally be, the page number is centered. Thus, there is no intrusion into the bottom margin.</p> -<p>This command may only be used following the \clearpage command. Thus, it may be used at the start of new chapters, or on pages (such as copyright page) that do not flow from a previous page. If you use it elsewhere, the print will have incorrect layout, but there will be no error or warning, since the compiler is not sure what you are trying to do.</p> -<p>If used on a page with ChapterStart environment, you must place \thispagestyle{dropfolioinside} <em>before</em> \begin{ChapterStart}. The ChapterStart block has a disposable blank line at its top, which is removed when <i>dropfolioinside</i> is used (instead of removing a line from the following text block).</p> +<p>This command may only be used following the <code>\clearpage</code> command. Thus, it may be used at the start of new chapters, or on pages (such as copyright page) that do not flow from a previous page. If you use it elsewhere, the print will have incorrect layout, but there will be no error or warning, since the compiler is not sure what you are trying to do.</p> +<p>If used on a page with ChapterStart environment, you must place <code>\thispagestyle{dropfolioinside}</code> <em>before</em> <code>\begin{ChapterStart}</code>. The <i>ChapterStart</i> block has a disposable blank line at its top, which is removed when <i>dropfolioinside</i> is used (instead of removing a line from the following text block).</p> </div> </div><!-- end class="d3" --> @@ -1564,7 +1583,7 @@ Default author verso, title recto.</p> <h2 id="h7">7. Text Sizes and Styling</h2> <div class="d2" id="d7"> <p class="noindent">This section describes how to change the size of text, how to style text (such as italics), and how to move it around. It also describes some miscellaneous commands that are intended to modify text.</p> -<p>Information about how to choose the main text point size is described earlier on this page. Information about choosing fonts and font features is also described earlier on this page.</p> +<p>Information about how to choose the main text point size is described in <a href="#h4.2.3">section 4.2.3</a>. Information about choosing fonts and font features was <a href="#h5">previously described</a> on this page.</p> <p>There is no direct setting for normal baselineskip; it is automatically calculated from the size of the textblock and lines per page.</p> <h3 id="h7.1">7.1. Text Sizes</h3> @@ -1573,17 +1592,16 @@ Default author verso, title recto.</p> <h4 id="h7.1.1">7.1.1. Surprise! Traditional TeX Font Size Commands Are Disabled.</h4> <div class="d4" id="d7.1.1"> -<p class="noindent">Ah, the simplicity of TeX font size commands, such as \small and \LARGE. But in <i>novel</i>, they don't work. If you write {\LARGE text}, then the incuded text appear at normal size. This is by design.</p> +<p class="noindent">Ah, the simplicity of TeX font size commands, such as <code>\small</code> and <code>\LARGE</code>. But in <i>novel</i>, they don't work. If you write <code>{\LARGE text}</code>, then the included text appears at normal size. This is by design.</p> <p>Why? In <i>novel</i>, the focus is on maintaining a constant baselineskip, so that facing pages have text aligned. This is impossible with the standard TeX commands. In particular, commands to increase font size will change the baselineskip, whether you like it or not, even if you try to code for a constant baselineskip. That's just the way TeX works.</p> -<p>The one exception is that footnotes will appear with smaller than normal size and skip. But this is done automatically. You cannot manipulate it with a size command.</p> +<p>The one exception is that <a href="#h12.1">footnotes</a> will appear with smaller than normal size and skip. But this is done automatically. You cannot manipulate it with a size command.</p> <p>Fortunately, there are not a lot of occasions where fiction needs to change font size. In <i>novel</i>, there are new commands to address each situation.</p> </div> -<h4 id="h7.1.2">7.1.2. \charscale[<em>scale,hoffset,voffset</em>]{<em>text</em>}, \charscale*[<em>scale,hoffset,voffset</em>]{<em>text</em>}</h4> +<h4 id="h7.1.2">7.1.2. <code>\charscale[<em>scale,hoffset,voffset</em>]{<em>text</em>}</code>, <code>\charscale*[<em>scale,hoffset,voffset</em>]{<em>text</em>}</code></h4> <div class="d4" id="d7.1.2"> -<p class="noindent">The \charscale command may be used for a short amount of text, where there is no line break. The command will throw an error if the included text has \\ or \par or any other command that breaks the line. You may not place an image in \charscale.</p> -<p>This command is built into some other <i>novel</i> commands, such as \ChapterTitle.</p> -<p>When used without the option, \charscale echoes the included text. However, the text gains the magical ability to extend above or below the normal line of text, without pushing apart the baselines. This is useful if the text has some unusual character that is extraordinarily tall or deep.</p> +<p class="noindent">The <code>\charscale</code> command may be used for a short amount of text, where there is no line break. The command will throw an error if the included text has <code>\\</code> or <code>\par</code> or any other command that breaks the line. Text within <code>\charscale</code> does not wrap. You may not place an image in <code>\charscale</code>.</p> +<p>When used without the option, <code>\charscale</code> echoes the included text. However, the text gains the magical ability to extend above or below the normal line of text, without pushing apart the baselines. This is useful if the text has some unusual character that is extraordinarily tall or deep.</p> <p>Using the option, you may uniformly scale the text by any amount, and displace it horizontally and vertically. The text can overlie other text, or any previously-placed image.</p> <p>With the unstarred command, the scaled width of the text will occupy horizontal space, even if the text is displaced far away. But with the starred command, the text does not occupy any horizontal space.</p> <p>The single optional argument may include up to three comma-separated values. The first value is a number, indicating the scale. If a second argument is used, it is the length of horizontal offset (positive is right). If a third number is used, it is the length of the vertical offset (positive is up). Remember that if all you want to do is scale the text, without positioning it, then you only need to provide the scale.</p> @@ -1595,7 +1613,7 @@ Bada\charscale[1.25,5em,1.3\nbs]{Bang} Bam\par<br/> Bada \charscale[1.25]{Bang} Bam\par </code></p> <p>In the result (above right), notice how the starred command leaves no gap where the word Boom would have been. The unstarred command leaves a gap where the word Bang would have been located. In each case, the baseline grid is maintained.</p> -<p>The most practical application of \charscale is styling the first character of chapter text. Drop capitals are out of fashion, but enlarged capitals (rising above the baseline) are in fashion. Example, also using the \FirstLine command (from package <i>magaz</i>, included with <i>novel</i>:</p> +<p>The most practical application of <code>\charscale</code> is styling the first character of chapter text. Drop capitals are out of fashion, but enlarged capitals (rising above the baseline) are in fashion. Example, also using the <code>\FirstLine</code> command (from package <i>magaz</i>, included with <i>novel</i>:</p> <p class="code"><code>\FirstLine{\noindent\charscale[1.5]{I}t was a dark and stormy night. Lord Withens mounted his horse and rode through the gloom to Castle McDingle, where Baron von Feathering awaited. The pair had dirty deeds to do, but being members of the nobility, they commanded a high price.}</code></p> <p class="centerimg"><img src="html-resources/mcdingle.png" width="559" height="121" alt="larger first letter"/></p> <p>In the above example, the initial I is 1.5x its normal size. It appears larger than that, by comparison to the adjacent small caps letters.</p> @@ -1606,7 +1624,7 @@ Bada \charscale[1.25]{Bang} Bam\par <p class="noindent">The parascale environment is used on a paragraph basis. More than one paragraph may be included. The scale is applied to the font size and to the baselineskip within.</p> <p>Since the text within parascale generally will not occupy an integral number of normal baselineskips, the following text will be off-grid. This may not be a problem, if parascale is used in places where maintaining the grid does not matter (such as on a title page or copyright page).</p> <p>• If parascale is used within body text, then it will be necessary to restore the line grid for the following text. This cannot be done automatically; you will have to make a preliminary run, look at the results, and adjust accordingly.</p> -<p>For example, suppose you use \begin{parascale}[0.92]...text...\end{parascale}. The preliminary run shows that the included text occupies 7 lines. The following baseline will then be 7x(1–0.92)=0.56 normal baselineskip too high. This can be fixed by adding \vspace{0.56\nbs}. For best appearance, the \vspace should be split above and below the parascale environment, but not nessarily in half.</p> +<p>For example, suppose you use <code>\begin{parascale}[0.92]...text...\end{parascale}</code>. The preliminary run shows that the included text occupies 7 lines. The following baseline will then be 7x(1–0.92)=0.56 normal baselineskip too high. This can be fixed by adding <code>\vspace{0.56\nbs}</code>. For best appearance, the <code>\vspace</code> should be split above and below the parascale environment, but not nessarily in half.</p> <p>• If parascale crosses to the next page, then you will need to make vertical adjustment for each page independently. For example, if a 7-line parascale has 3 lines at the bottom of a page, followed by 4 lines on the following page, then you need to restore only a 4 line deficit on the following page.</p> <p>• Within parascale you may need to manually indent paragraphs, or remove indents if necessary.</p> </div> @@ -1624,17 +1642,17 @@ Bada \charscale[1.25]{Bang} Bam\par <h4 id="h7.2.1">7.2.1. Italics and Emphasis</h4> <div class="d4" id="d7.2.1"> -<p class="noindent"><b>\textit{<em>text</em>}</b> puts the text in italics, provided that the font family has an Italic font. If it does not have an Italic font, then the letters will remain normal, <em>not</em> fake slanted.</p> -<p>If the italicized text leans too far into the following space, try adding \/ (back and forward slashes) just before closing the braces.</p> -<p><b>\emph{<em>text</em>}</b> changes regular text to italics, and italic text to regular. You may nest \emph commands. Many writers opine that this is the preferred way to specify Italics.</p> +<p class="noindent"><b><code>\textit{<em>text</em>}</code></b> puts the text in italics, provided that the font family has an Italic font. If it does not have an Italic font, then the letters will remain normal, <em>not</em> fake slanted.</p> +<p>If the italicized text leans too far into the following space, try adding <code>\/</code> (back and forward slashes) just before closing the braces.</p> +<p><b><code>\emph{<em>text</em>}</code></b> changes regular text to italics, and italic text to regular. You may nest <code>\emph</code> commands. Many writers opine that this is the preferred way to specify Italics.</p> </div> <h4 id="h7.2.2">7.2.2. Bold, Semibold, etc.</h4> <div class="d4" id="d7.2.2"> -<p class="noindent"><b>\textbf{<em>text</em>}</b> puts the text in whatever font you specified as the Bold font, when you defined the currently-used font family.</p> +<p class="noindent"><b><code>\textbf{<em>text</em>}</code></b> puts the text in whatever font you specified as the Bold font, when you defined the currently-used font family.</p> <p>If the font family has no Bold font, then it will <em>not</em> be faked.</p> <p>The default main font used by <i>novel</i>, namely <i>Libertinus Serif</i>, has both Bold and Semibold weights. Given this choice, <i>novel</i> explicitly calls for the Semibold weight. If you intend to use a font such as Adobe Garamond Pro, which also has a Semibold weight, then you can request it instead of Bold when you define the font family.</p> -<p>What if you want both Bold and Semibold, or maybe even a Light weight? Only one can be assigned to \textbf when you define the font. For the others, use \NewFontFace to assign the desired weight to its own font command, which you will use (but inside the braces) instead of \textbf.</p> +<p>What if you want both Bold and Semibold, or maybe even a Light weight? Only one can be assigned to <code>\textbf</code> when you define the font. For the others, use <code>\NewFontFace</code> to assign the desired weight to its own font command, which you will use (but inside the braces) instead of <code>\textbf</code>.</p> <p>Actually, you should not be using Bold in fiction. It <em>might</em> be the case that this weight is useful for titles, but you ought to consider a fancy-looking font for that purpose, rather than mere Bold. Or, make the letters big and bold, but balance the effect by using gray.</p> </div> @@ -1645,16 +1663,16 @@ Bada \charscale[1.25]{Bang} Bam\par <h4 id="h7.2.4">7.2.4. Small Caps and Acronyms</h4> <div class="d4" id="d7.2.4"> -<p class="noindent"><code><b>\textsc{<em>text</em>}</b></code> converts lowercase letters to small caps, leaving uppercase unchanged. The font's <code>smcp</code> Open Type feature will be used. But if the font does not have <code>smcp</code>, it will <em>not</em> be faked.</p> -<p><code><b>\smcp{<em>text</em>}</b></code> is an alias for <code>\textsc{<em>text</em>}</code>.</p> -<p><code><b>\allsmcp{<em>text</em>}</b></code> places both uppercase and lowercase letters in small caps. If the font has the <code>c2sc</code> feature, it will be used; if not, the letters will be converted to lowercase first. Then, <code>smcp</code> is applied.</p> +<p class="noindent"><b><code>\textsc{<em>text</em>}</code></b> converts lowercase letters to small caps, leaving uppercase unchanged. The font's <code>smcp</code> Open Type feature will be used. But if the font does not have <code>smcp</code>, it will <em>not</em> be faked.</p> +<p><b><code>\smcp{<em>text</em>}</code></b> is an alias for <code>\textsc{<em>text</em>}</code>.</p> +<p><b><code>\allsmcp{<em>text</em>}</code></b> places both uppercase and lowercase letters in small caps. If the font has the <code>c2sc</code> feature, it will be used; if not, the letters will be converted to lowercase first. Then, <code>smcp</code> is applied.</p> <p>• If you require small caps, but your font does not have them, you can fake them by scaling uppercase. But this is usually unattractive. A better method is described in the <i>fontspec</i> package documentation: You may appoint a different font that will provide small caps.</p> <p>• If you insist on using old-fashioned TeX fonts, which do not have the <i>smcp</i> Open Type feature, then you may need to write this code in the Preamble:</p> <p class="code"><code>\let\smcp\oldscshape\relax<br/> \let\textsc\oldscshape\relax<br/> \let\scshape\oldscshape\relax</code></p> <p>The above code sends you in a time machine back to the Twentieth Century.</p> -<p><b>\acronym{<em>text</em>}</b> is special to <i>novel</i>. If the <i>NovelDeco</i> font is installed, uppercase letters in the text will be converted to "mid-size capitals," and lowercase will remain lowercase, but with ascenders slightly reduced. The purpose of this command is so that acronyms such as NASA and NATO blend well with surrounding text. I have found that whereas ordinary uppercase is too conspicuous, small caps also looks wrong. Example:</p> +<p><b><code>\acronym{<em>text</em>}</code></b> is special to <i>novel</i>. If the <i>NovelDeco</i> font is installed, uppercase letters in the text will be converted to "mid-size capitals," and lowercase will remain lowercase, but with ascenders slightly reduced. The purpose of this command is so that acronyms such as NASA and NATO blend well with surrounding text. I have found that whereas ordinary uppercase is too conspicuous, small caps also looks wrong. Example:</p> <p class="code"><img class="floatright" src="html-resources/acronym2.png" width="192" height="89" alt="acronym"/> <code> The NATO alliance...\par<br/> @@ -1666,37 +1684,37 @@ The \allsmcp{NATO} alliance...\par <h4 id="h7.2.5">7.2.5. Local Tracking Adjustment</h4> <div class="d4" id="d7.2.5"> -<p class="noindent"><b>\squeeze{<em>text</em>}</b> narrows the text by one percent.</p> -<p><b>\crush{<em>text</em>}</b> narrows the text by two percent.</p> +<p class="noindent"><b><code>\squeeze{<em>text</em>}</code></b> narrows the text by one percent.</p> +<p class="noindent"><b><code>\crush{<em>text</em>}</code></b> narrows the text by two percent.</p> <p>These commands are for emergency use only. They temporarily apply a horizontal scale to the letters, so that they are very slightly narrower than usual. Inter-word spacing is not necessarily changed (it can even grow larger), because spacing is calculated during paragraph layout. The enclosed text may span paragraphs.</p> <p>The commands do not compound. That is, placing one crush inside another will not narrow the text by four percent. But any adjustments made by <i>microtype</i> will still apply, and may compound with these commands.</p> -<p>The only application for these commands is when a paragraph does not quite fit where you would like it to be. For example: Perhaps one short word, or part of a word, dangles to an extra line. Try \squeeze first, then \crush, for all or most of the paragraph. These do not always produce a useful effect, since the actual paragraph layout depends on other factors. But <em>if you are lucky,</em> then the paragraph re-flows to a better layout.</p> -<p>• If the commands do not help, then be sure to remove them, or the typography will be worse.</p> +<p>The only application for these commands is when a paragraph does not quite fit where you would like it to be. For example: Perhaps one short word, or part of a word, dangles to an extra line. Try <code>\squeeze</code> first, then <code>\crush</code>, for all or most of the paragraph. These do not always produce a useful effect, since the actual paragraph layout depends on other factors. But <em>if you are lucky,</em> then the paragraph re-flows to a better layout.</p> +<p>• If the commands do not help, then <em>be sure to remove them</em>, or the typography will be worse than it was before!</p> </div> <h4 id="h7.2.6">7.2.6. Local Font Selection</h4> <div class="d4" id="d7.2.6"> -<p class="noindent"><b>{\<em>fontcode</em> <em>text</em>}</b> where <i>fontcode</i> is a previously-defined font command.</p> -<p>You locally change the font in use, by calling its font command. For example, \subchfont is a built-in command, automatically used in certain macros. You can use it yourself:</p> +<p class="noindent"><b><code>{\<em>fontcode</em> <em>text</em>}</code></b> where <i>fontcode</i> is a previously-defined <a href="#h5.1">built-in</a> or <a href="#h5.3">user-defined</a> font command.</p> +<p>You locally change the font in use, by calling its font command. For example, <code>\subchfont</code> is a built-in command, automatically used in certain macros. You can use it yourself:</p> <p class="code"><code>{\subchfont <em>text</em>} % Note that the braces go on the outside.</code></p> -<p>Likewise, if you used \NewFontFamily or \NewFontFace to define your own font, giving it the command name \mynewfont, then you would use it like this:</p> +<p>Likewise, if you used <code>\NewFontFamily</code> or <code>\NewFontFace</code> to define your own font, giving it the command name <code>\mynewfont</code>, then you would use it like this:</p> <p class="code"><code>{\mynewfont <em>text</em>} % Again, the braces go on the outside.</code></p> </div> <h4 id="h7.2.7">7.2.7. Local Feature Changes</h4> <div class="d4" id="d7.2.7"> -<p class="noindent"><b>{\addfontfeature{<em>feature</em>} <em>text</em>}</b> for changing Open Type features.</p> -<p>If a font is already defined, you can locally add one or more features. For example, suppose that you defined \mynewfont without using its Open Type feature <i>ss03</i> (we will assume that the font actually has this feature). In a particular place, you wish to activate <i>ss03</i>. The code looks like this:</p> +<p class="noindent"><b><code>{\addfontfeature{<em>feature</em>} <em>text</em>}</code></b> for changing Open Type features.</p> +<p>If a font is already defined, you can locally add one or more <a href="#h5.4.3">features</a>. For example, suppose that you defined <code>\mynewfont</code> without using its Open Type feature <i>ss03</i> (we will assume that the font actually has this feature). In a particular place, you wish to activate <i>ss03</i>. The code looks like this:</p> <p class="code"><code>{\mynewfont\addfontfeature{RawFeature=+ss03} <em>text</em>}</code> % Note + sign. Braces outside.</p> <p>That limits the scope of the feature to the included group, in TeX terminology.</p> <p>You can modify features used by any defined font, whether you defined it yourself or it is one of the <i>novel</i> built-in font commands. You can add more than one feature. If the requested feature does not exist in the font, then your request will be ignored.</p> -<p>What about removing a feature that is already present in the font definition? Suppose you defined \mynewfont so that <i>Numbers=OldStyle</i> is used. On a local basis, can you change the style of numbers? Usually, yes. You could use <i>Numbers=Lining</i> to over-ride the feature. Sometimes it depends on how you chose the features, as a matter of syntax. See the <i>fontspec</i> documentation.</p> +<p>What about removing a feature that is already present in the font definition? Suppose you defined <code>\mynewfont</code> so that <i>Numbers=OldStyle</i> is used. On a local basis, can you change the style of numbers? Usually, yes. You could use <i>Numbers=Lining</i> to over-ride the feature. Sometimes it depends on how you chose the features, as a matter of syntax. See the <i>fontspec</i> documentation.</p> </div> <h4 id="h7.2.8">7.2.8. Color Text (actually, grayscale)</h4> <div class="d4" id="d7.2.8"> -<p class="noindent"><b>graytext</b> class option must be used, or any color command will be ignored, and its included text will be rendered in black (even if the requested color is white). Images are unaffected.</p> -<p><b>\color{<em>name</em>}</b> or <b>\color[gray]{<em>scale</em>}</b> is used within a group. All text will be in grayscale, from where the command is placed, until the group ends. If the command is not at the beginning of the group, it does not affect prior text. Example:</p> +<p class="noindent">For this effect, the <a href="#h2.2"><i>graytext</i></a> class option must be used, or any color command will be ignored, and its included text will be rendered in black (even if the requested color is white). Images are unaffected.</p> +<p><b><code>\color{<em>name</em>}</code></b> or <b><code>\color[gray]{<em>scale</em>}</code></b> is used within a group. All text will be in grayscale, from where the command is placed, until the group ends. If the command is not at the beginning of the group, it does not affect prior text. Example:</p> <p class="code"><code> \begingroup<br/> This text is unaffected by the following command.<br/> @@ -1704,14 +1722,14 @@ This text is unaffected by the following command.<br/> This text is in lightgray, until the group ends.<br/> \endgroup </code></p> -<p style="margin-top:10px"><b>\textcolor{<em>text</em>}</b> or <b>\textcolor[gray]{<em>scale</em>}{<em>text</em>}</b> affects only the included text.</p> +<p style="margin-top:10px"><b><code>\textcolor{<em>text</em>}</code></b> or <b><code>\textcolor[gray]{<em>scale</em>}{<em>text</em>}</code></b> affects only the included text.</p> <p class="code"><code>\textcolor{gray7}{This text is in color gray7, a medium-light gray.}<br/> \textcolor[gray]{0.32}{This text is in 32 percent gray.}</code></p> -<p style="margin-top:10px">Whether you use \color or \textcolor, there are two ways to specify the color: by name, or by scale, using package <i>xcolor</i> syntax.</p> +<p style="margin-top:10px">Whether you use <code>\color</code> or <code>\textcolor</code>, there are two ways to specify the color: by name, or by scale, using package <i>xcolor</i> syntax.</p> <p>• The following color names are accepted, and will be converted to some shade of gray (from dark to light): black, blue, violet, darkgray, purple, red, teal, olive, magenta, gray, brown, green, orange, cyan, lightgray, lime, pink, yellow, white.</p> <p>The above names are often not helpful, so <i>novel</i> also allows you to use these: black, gray1, gray2, gray3, gray4, gray5, gray6, gray7, gray8, gray9, white. The scale is not uniform (gray5 is not 50 percent gray), but the values are usefully spaced.</p> <p>Other names "known to dvips," such as <i>Apricot</i>, do not work. An error will result.</p> -<p>• To specify color by scale, follow the color command with <i>[gray]{<em>scale</em>}</i>, where the scale is a number between 0 (black) and 1 (white). Example: \color[gray]{0.63}.</p> +<p>• To specify color by scale, follow the color command with <i>[gray]{<em>scale</em>}</i>, where the scale is a number between 0 (black) and 1 (white). Example:<code> \color[gray]{0.63}</code>.</p> <p>• If you use <i>xcolor</i> syntax to request an rgb color, it will be converted to 1-channel grayscale.</p> <p>• Absolutely no transparency!</p> </div> @@ -1723,49 +1741,51 @@ This text is in lightgray, until the group ends.<br/> <h4 id="h7.3.1">7.3.1. What to Avoid</h4> <div class="d4" id="d7.3.1"> -<p class="noindent">• The \raisebox command does not play well with novel. It can be used, but there is the great risk of disturbing the line grid. Use \charscale instead.</p> -<p>• If you must use the \vspace command (or its relative, \vskip) be sure to measure the space in units of \nbs (normal baseline skip).</p> -<p>• Avoid the minipage and parbox environments. These are likely to disrupt the line grid. When that happens, restoring the grid is your own responsibility. You may find the adjustwidth environment to be a useful alternative.</p> -<p>• In most cases, do not use the center environment. You may use {\centering ... \par} instead, for a single paragraph. The center environment may cause the text to go off-grid. That's not a problem on some stand-alone pages where you don't care about the grid, but it is ugly in the middle of running text.</p> -<p>• Avoid positioning via the textblock or textblock* environments (package <i>textpos</i>). Actually, novel uses that code internally. But if not handled with more care than usual, positioned text can disrupt the baseline and position of surrounding text. You may use \charscale to position small amounts of text safely, but not on a paragraph basis. Images have built-in positioning arguments, which may also be useful for positioned text.</p> +<p class="noindent">• The <code>\raisebox</code> command does not play well with novel. It can be used, but there is the great risk of disturbing the line grid. Use <code><a href="#h7.1.2">\charscale</a></code> instead.</p> +<p>• If you must use the <code>\vspace</code> command (or its relative, <code>\vskip</code>) be sure to measure the space in units of <code>\nbs</code> (normal baseline skip).</p> +<p>• Avoid the <i>minipage</i> and <i>parbox</i> environments. These are likely to disrupt the line grid. When that happens, restoring the grid is your own responsibility. You may find the <i>adjustwidth</i> environment to be a useful alternative.</p> +<p>• In most cases, do not use the center environment. You may use <code>{\centering ... \par}</code> instead, for a single paragraph. The center environment may cause the text to go off-grid. That's not a problem on some stand-alone pages where you don't care about the grid, but it is ugly in the middle of running text.</p> +<p>• Avoid positioning via the <i>textblock</i> or <i>textblock*</i> environments (package <i>textpos</i>). Actually, <i>novel</i> uses that code internally. But if not handled with more care than usual, positioned text can disrupt the baseline and position of surrounding text. You may use <code><a href="#h7.1.2">\charscale</a></code> to position small amounts of text safely, but not on a paragraph basis. Images have built-in positioning arguments, which may also be useful for positioned text.</p> <p>• Do not use floats. If you try, then <i>novel</i> may intercept them with a nasty message.</p> -<p>• Do not use tables. Nasty message will result. But <i>novel</i> has its own provision for a Table of Contents, and the code may be used for other purposes as well.</p> -<p>• If you use images, then use only the image commands provided by novel: \InlineImage and \BlockImage.<p> -<p>• There is no built-in provision for a two-column environment. However, you can place text alongside an image.</p> +<p>• Do not use tables. Nasty message will result. But <i>novel</i> has its <a href="#h9.3.5">own provision</a> for a Table of Contents, and the code may be used for other purposes as well.</p> +<p>• If you use images, then use only the image commands provided by novel: <code><a href="#h8.4.2">\InlineImage</a></code> and <code><a href="#h8.4.4">\BlockImage</a></code>.<p> +<p>• There is no built-in provision for a two-column environment. However, you can place text <a href="#h8.4.5">alongside</a> an image.</p> </div> <h4 id="h7.3.2">7.3.2. Some Useful Commands</h4> <div class="d4" id="d7.3.2"> <p class="noindent">This is not a complete list. It merely addresses a few situations that you are likely to encounter, without the need for elaborate code, and without loading additional packages.</p> -<p style="margin-top:10pt"><b>\begin{adjustwidth}{<em>left</em>}{<em>right</em>}</b> ... <b>\end{adjustwidth}</b></p> +<p style="margin-top:10pt"><b><code>\begin{adjustwidth}{<em>left</em>}{<em>right</em>}</b> ... <b>\end{adjustwidth}</code></b></p> <p>This environment, from the included <i>changepage</i> package, is the most useful way to create block indents. The included text may have multiple paragraphs and span pages. The left and right arguments are lengths, being the amount to <em>increase</em> the respective margins from their normal values.</p> -<p style="margin-top:10pt"><b>\phantom{<em>text</em>}</b></p> +<p style="margin-top:10pt"><b><code>\phantom{<em>text</em>}</code></b></p> <p>Does not print the text, but leaves a horizontal gap as if the text were there.</p> -<p style="margin-top:10pt"><b>\mbox{<em>text</em>}</b></p> +<p style="margin-top:10pt"><b><code>\mbox{<em>text</em>}</code></b></p> <p>Prevents a specific word from being hyphenated, or to ensure that two consecitive words always appear on the same line. The box will not be broken across lines. However, it may overhang the margin, which is undesirable.</p> -<p style="margin-top:10pt"><b>\makebox[<em>width</em>][<em>alignment</em>]{<em>text</em>}</b></p> -<p>Puts the text in a box of fixed width (usually much larger than the text's own width) and aligns it left, center, or right in the box. If using this across the full textwidth, be sure to precede it with \noindent to prevent offset.</p> -<p style="margin-top:10pt"><b>\hspace{<em>length</em>}</b></p> +<p style="margin-top:10pt"><b><code>\makebox[<em>width</em>][<em>alignment</em>]{<em>text</em>}</code></b></p> +<p>Puts the text in a box of fixed width (usually much larger than the text's own width) and aligns it left, center, or right in the box. If using this across the full textwidth, be sure to precede it with <code>\noindent</code> to prevent offset.</p> +<p style="margin-top:10pt"><b><code>\hspace{<em>length</em>}</code></b></p> <p>Creates a horizontal space.</p> -<p style="margin-top:10pt"><b>\strut</b></p> +<p style="margin-top:10pt"><b><code>\strut</code></b></p> <p>Places an invisible box with no width, which has the height and depth of the font. Sometimes used as a placeholder.</p> -<p style="margin-top:10pt"><b>\indent, \noindent, \forceindent, \backindent</b></p> -<p>Commands \indent and \noindent have their ordinary TeX meaning. Sometimes, the action of other macros will remove an indent that should be there, or add an indent that should not be there. If writing \indent and \noindent do not fix the problems, use \forceindent and \backindent as more forceful solutions.</p> -<p style="margin-top:10pt"><b>\hfill</b></p> +<p style="margin-top:10pt"><b><code>\stake</code></b></p> +<p>Placeholder like <code>\strut</code>, but does not occupy the height or depth of the font.</p> +<p style="margin-top:10pt"><b><code>\indent</code>, <code>\noindent</code>, <code>\forceindent</code>, <code>\backindent</code></b></p> +<p>Commands <code>\indent</code> and <code>\noindent</code> have their ordinary TeX meaning. Sometimes, the action of other macros will remove an indent that should be there, or add an indent that should not be there. If writing <code>\indent</code> and <code>\noindent</code> do not fix the problems, use <code>\forceindent</code> and <code>\backindent</code> as more forceful solutions.</p> +<p style="margin-top:10pt"><b><code>\hfill</code></b></p> <p>Pushes the following text to the right end of the line. Actual effect depends on what precedes and follows. Sometimes a \strut is needed at the beginning of a line.</p> -<p style="margin-top:10pt"><b>\vfill. \vfill*</b></p> +<p style="margin-top:10pt"><b><code>\vfill</code>, <code>\vfill*</code></b></p> <p>Pushes the following text to the bottom of the page. Actual effect depends on paragraph organization. Use the asterisk if there is nothing printed above this command, on the same page.</p> -<p style="margin-top:10pt"><b>\kern</b></p> -<p>Tweaks the spacing between consecutive letters. A tricky command, as it is always used without braces, and makes the surrounding text illegible in your source code. If you use it, the units of length should always be em, rather than pt. Example:</p> +<p style="margin-top:10pt"><b><code>\kern</code></b></p> +<p>Tweaks the spacing between consecutive letters. A tricky command, as it is always used without braces, and makes the surrounding text illegible in your source code. If you use it, the units of length should always be <i>em</i>, rather than <i>pt</i>. Example:</p> <p class="code"><code>It wa\kern-.02ems a da\kern.03emrk and stormy ni\kern-.004emght.</code></p> <p>The <code>\kern</code> command is not useful for globally changing kern values.</p> -<p style="margin-top:10pt"><b>\bigemdash[<em>yoffset,thickness</em>]</b></p> -<p>Simulates a "big emdash" of variable length. Horizontal width is from command to end of line marked by \par, or limited by a fixed width such as created by \makebox. If placed in other situations, the line may be missing or too long.</p> +<p style="margin-top:10pt"><b><code>\bigemdash[<em>yoffset,thickness</em>]</code></b></p> +<p>Simulates a "big emdash" of variable length. Horizontal width is from command to end of line marked by <code>\par</code>, or limited by a fixed width such as created by <code>\makebox</code>. If placed in other situations, the line may be missing or too long.</p> <p>The line's normal position is at the typical height of an emdash, which is slightly above half the height of lowercase x. Its normal width is typical of an emdash width. Thus, the line is like an extended emdash.</p> <p>You can tweak the line using its optional argument. The first value tweaks the vertical position by a scale factor, where 1 equals its normal position (so that 0.9 places it a little lower). The second argument, if used, is separated from the first by a comma. It tweaks the line thickness by a scale factor (so that 0.9 makes it a little thinner).</p> -<p>Since \bigemdash allows an optional argument, but no mandatory argument, you may not immediately follow it with text. If it is boxed, then first close the box; otherwise, end the paragraph.</p> -<p style="margin-top:10pt"><b>\straightquote \straightdblquote</b></p> -<p>These insert the single quote (apostrophe), and double quote, as ASCII straight characters, without TeX (or your software) automatically substituting the curly characters.</p> +<p>Since <code>\bigemdash</code> allows an optional argument, but no mandatory argument, you may not immediately follow it with text. If it is boxed, then first close the box; otherwise, end the paragraph.</p> +<p style="margin-top:10pt"><b><code>\straightquote</code>, <code>\straightdblquote</code></b></p> +<p>These insert the single quote (apostrophe), and double quote, as ASCII straight characters. Prevents TeX (or your software) from automatically substituting the curly characters.</p> </div> </div><!-- end class="d3" --> @@ -1880,58 +1900,58 @@ This text is in lightgray, until the group ends.<br/> <p>You may ask: If the image was not really grayscale, can it be converted to grayscale using a simple command line, with ImageMagick or GraphicsMagick? The answer is yes, but don't do it that way. The reason is that there are many ways to map colors (even "gray colors") to true grayscale, and an automated conversion may produce unexpectedly light or dark results. It is better to do the conversion in a graphics program, where you can see what you are doing.</p> </div> -<h4 id="h8.3.3">8.3.3. Scaling Images after \Rework.</h4> +<h4 id="h8.3.3">8.3.3. Scaling Images after <code>\Rework</code>.</h4> <div class="d4" id="d8.3.3"> -<p class="noindent">When you use one or both of the \Rework commands (Appendix F), the font size and/or the baselineskip will change. However, it does not scale images. In many cases, there is no problem. But in some cases, an un-scaled image will disrupt the previous flow of text or pagination. See Appendix F.5 for how to re-work images.</p> +<p class="noindent">When you use one or both of the <code>\Rework</code> commands (<a href="#hF">Appendix F</a>), the font size and/or the baselineskip will change. However, it does not scale images. In many cases, there is no problem. But in some cases, an un-scaled image will disrupt the previous flow of text or pagination. See <a href="#hF.5">Appendix F.5</a> for how to re-work images.</p> </div> <!-- end class="d3" --> <h3 id="h8.4">8.4. Placing Images In Your Document</h3> <div class="d3" id="d8.4"> -<p class="noindent">An image may be placed as an inline element, using the \InlineImage or \InlineImage* command. This allows the image to mingle with text, and even have text as an overlay.</p> -<p>\BlockImage places the image so that <em>subsequent</em> text will clear the bottom of the image, and be on the baseline grid. You may also <em>accompany</em> the image with text in its own block space, if you wish.</p> +<p class="noindent">An image may be placed as an inline element, using the <code>\InlineImage</code> or <code>\InlineImage*</code> command. This allows the image to mingle with text, and even have text as an overlay.</p> +<p><code>\BlockImage</code> places the image so that <em>subsequent</em> text will clear the bottom of the image, and be on the baseline grid. You may also <em>accompany</em> the image with text in its own block space, if you wish.</p> <p>If your book has a lot of images, then you should consider using a page layout program (such as Scribus) instead of TeX. That's because the best strategies for an image-intensive picture book are very different from the strategies adoped by <i>novel</i>.</p> <p>Beware of overlap. If images overlap each other, or overlap with text, no error will result. If text lies atop an image, the result may be desirable. All other situations are undesirable. Since TeX cannot detect such errors, you need to carefully review the result.</p> <p>Do not use the ordinary TeX commands, or environments, for floats or figures.</p> -<h4 id="h8.4.1">8.4.1. \charscale[<em>scale,hoffset,voffset</em>]{<em>text</em>}, \charscale*[<em>scale,hoffset,voffset</em>]{<em>text</em>}</h4> +<h4 id="h8.4.1">8.4.1. <code>\charscale[<em>scale,hoffset,voffset</em>]{<em>text</em>}</code> and starred version</h4> <div class="d4" id="d8.4.1"> -<p class="noindent">The \charscale command pertains to text, not images. It is mentioned here because it can place text almost anywhere on a page, even overlapping other text or previously-placed images. Thus, it provides an image-like effect.</p> -<p>The command is documented earlier on this page.</p> +<p class="noindent">The <code>\charscale</code> command pertains to text, not images. It is mentioned here because it can place text almost anywhere on a page, even overlapping other text or previously-placed images. Thus, it provides an image-like effect.</p> +<p>The command is documented <a href="#h7.1.2">earlier</a> on this page.</p> </div> -<h4 id="h8.4.2">8.4.2 \InlineImage[<em>hoffset,voffset</em>]{<em>imageFile.png or .jpg</em>} and starred version</h4> +<h4 id="h8.4.2">8.4.2 <code>\InlineImage[<em>hoffset,voffset</em>]{<em>imageFile.png or .jpg</em>}</code> and starred version</h4> <div class="d4" id="d8.4.2"> <p class="noindent">This command places the image as an inline element, at 100% scale. The use of <i>png</i> or <i>jpg</i> images, with file extension, is required.<p> -<p>You may offset the image horizontally or vertically. Positive direction is to the right and up. If you use one offset, then you must use both (if necessary, <i>0em</i>). Any units of length may be used, but the preferred units are <i>em</i> or <i>\textwidth</i> for horizontal, and <i>em</i> or <i>\nbs</i> for vertical, because these are most compatible with the \Rework commands.</p> +<p>You may offset the image horizontally or vertically. Positive direction is to the right and up. If you use one offset, then you must use both (if necessary, <i>0em</i>). Any units of length may be used, but the preferred units are <i>em</i> or <code>\textwidth</code> for horizontal, and <i>em</i> or <code>\nbs</code> for vertical, because these are most compatible with the <code><a href="#hF">\Rework</a></code> commands.</p> <p>By default, the <em>top</em> of the image is at the text baseline. If you prefer that the <em>bottom</em> of the image be at the text baseline, use voffset <i>b</i>. Example:</p> <p class="code"><code>\InlineImage[0em,b]{imageFile.png}</code></p> -<p>Thanks to the included <i>calc</i> package, offsets may use \widthof{<em>text</em>} and/or \heightof{<em>text</em>} as lengths. The most useful of these is when you wish to align the top of an image at the X-height of surrounding text:</p> +<p>Thanks to the included <i>calc</i> package, offsets may use <code>\widthof{<em>text</em>}</code> and/or <code>\heightof{<em>text</em>}</code> as lengths. The most useful of these is when you wish to align the top of an image at the X-height of surrounding text:</p> <p class="code"><code>\InlineImage[0em,\heightof{X}]{imageFile.png}</code></p> -<p>You may also use \heightof{\Aring} for the tallest accented letter normally found in Latin-1.</p> -<p>Lengths <i>\imagewidth</i> and <i>\imageheight</i> may also be used for offsets. These lengths remain set, and can be used for other purposes (such as displacing text) until another image is placed.</p> -<p>Offsets may be written as combinations of lengths. If you use the baseline <i>b</i> as above, it must be the first character of voffset. If you use <i>\widthof</i> or <i>\heightof</i>, then its backslash must be the first character <em>unless</em> it is preceded by another length. Thus, an offset of <i>-\heightof{X}</i> is prohibited, but you can use <i>0pt-\heightof{X}</i>. +<p>You may also use <code>\heightof{\Aring}</code> for the tallest accented letter normally found in Latin-1.</p> +<p>Lengths <code>\imagewidth</code> and <code>\imageheight</code> may also be used for offsets. These lengths remain set, and can be used for other purposes (such as displacing text) until another image is placed.</p> +<p>Offsets may be written as combinations of lengths. If you use the baseline <i>b</i> as above, it must be the first character of voffset. If you use <code>\widthof</code> or <code>\heightof</code>, then its backslash must be the first character <em>unless</em> it is preceded by another length. Thus, an offset of <code>-\heightof{X}</code> is prohibited, but you can use <code>0pt-\heightof{X}</code>. <p>Here are some examples of allowable code:</p> <p class="code"><code> \InlineImage[2.3em, -0.4em]{imageFile.png}<br/> \InlineImage[0pt-\widthof{eee}, b+\heightof{X}-0.2em]{imageFile.jpg} </code></p> -<p>The image occupies zero vertical space. So, it will not push apart baselines. The next line(s) of text may overlie the image. In some cases, this is desirable. If you do not want that effect, then you can either insert a suitable number of <i>\null</i> lines after the image, or use the \BlockImage command instead.</p> -<p>With the un-starred \InlineImage command, the image occupies its natural horizontal width. That is, text following the image will (if it fits) continue from the right edge of the image. But with the starred \InlineImage* command, the image occupies zero width. In this case, text following the image will continue from the left of the image, and overlie the image.</p> +<p>The image occupies zero vertical space. So, it will not push apart baselines. The next line(s) of text may overlie the image. In some cases, this is desirable. If you do not want that effect, then you can either insert a suitable number of <code>\null</code> lines after the image, or use the <code>\BlockImage</code> command instead.</p> +<p>With the un-starred <code>\InlineImage</code> command, the image occupies its natural horizontal width. That is, text following the image will (if it fits) continue from the right edge of the image. But with the starred <code>\InlineImage*</code> command, the image occupies zero width. In this case, text following the image will continue from the left of the image, and overlie the image.</p> <p>Having text overlie the image is allowable, and can create some interesting special effects. But when your print service sees what you have done, they may think that it is a mistake. Be sure that you discuss this with them.</p> <p>If you do allow text to overlie an image, be sure that the image is very light. Repeat: <em>very light</em>. Depending on the printing technology, an image may print darker than you see on your computer screen, and that would make text hard to read. At low print volume, your print service will probably use a technology that is like an industrial-strength home inkjet printer, which can make very sharp text over images. However, if your book goes to volume production, then the technology will be different. Volume printing will use halftoned images, and the text overlay may also become halftoned, which will reduce its sharpness considerably.</p> -<p>Note that an image may be placed in a way that prints some of the image in the margin. That's allowable if your margin is wider than the minimum required for printing clearance. But even if it is not allowable, there will be no complaint or warning from TeX.</p> +<p>Note that an image may be placed in a way that prints some of the image in the margin. That's allowable if your margin is wider than the minimum required for printing clearance. But even if it is not allowable, there will be no complaint or warning from TeX. Use the <a href="#h2.3">shademargins</a> class option to ascertain position.</p> <p>Do not place an image so that it approaches or goes beyond the page edge. That requires a "bleed box" which is not part of <i>novel</i> capabilities. If your book needs that kind of image handling, use a page layout program instead.</p> <p>Do not place images so that they overlap. Although that is allowed in the PDF, it is likely to be flagged as an error by your print service.</p> </div> -<h4 id="h8.4.3">8.4.3. Text Over \InlineImage</h4> +<h4 id="h8.4.3">8.4.3. Text Over <code>\InlineImage</code></h4> <div class="d4" id="d8.4.3"> -<p class="noindent">As noted above, an \InlineImage (or its starred version) can be used as the background to any subsequent text. Just as with any other text, whatever sits atop an image must be pure black. If you need text in gray, then you must integrate the rasterized text with the image in an external graphics program, instead of typing the text in your document.</p> +<p class="noindent">As noted above, an <code>\InlineImage</code> (or its starred version) can be used as the background to any subsequent text. Just as with any other text, whatever sits atop an image must be pure black. If you need text in gray, then you must integrate the rasterized text with the image in an external graphics program, instead of typing the text in your document.</p> <p>When text overlies an image, it retains its identity as vector paths, as far as the PDF is concerned. In some printing processes, particularly those for very low volume production, the result will be as sharp and dark as ordinary text. However, if your book sells well (or is being prepared to sell well), the image will be converted to halftone, and the text that lies above it may also be converted to halftone. This will reduce the sharpness of the text. It is not necessarily a problem, unless your text is very small or has fine details.</p> <p>If the text-over-image is part of a title, then the text is naturally large and dark, and will easily withstand halftoning.</p> <p>Be aware that not all print services will accept text over images. It's not that they <em>cannot</em> do it; after all, your home and office printers can easily do it. The reason they object is because the pages of your book will be handled in small volume by persons who are unfamiliar with the book. Text over an image may be flagged as a printing error or a bug in the PDF. In the advertising world, text over image is routine. But in the world of fictional novels, it is unusual. Don't imagine that they will decide what you meant to do, by reading your book. Also, very sharp image/text, at low printing volume, will not appear as sharp when the technology changes for higher volume production. They know that, but are not sure if <em>you</em> know that.</p> -<p>An inline image occupies zero vertical space. If you place its top near the bottom of the textblock, then the image will happily flow into the lower margin and perhaps off the bottom of the page, without an error (but the print service will reject it). The reason that TeX does not provide an error message is quite simple: Technically, it is not an error! It is just not what you meant to do. The software cannot read your mind.</p> +<p>An inline image occupies zero vertical space. If you place its top near the bottom of the textblock, then the image will happily flow into the lower margin and perhaps off the bottom of the page, without an error (but the print service will reject it). The reason that TeX does not provide an error message is quite simple: Technically, it is not an error! It is just not what you meant to do. The software cannot read your mind. This is where the <a href="#h2.3">shademargins</a> class option helps.</p> <p>Example:</p> <p class="code"><code> \noindent\InlineImage*[0pt,1.2\nbs]{gavel.png} Lord Withens took a seat at the rear of the courtroom, attempting to be inconspicuous. Yet his effort was in vain, as he was the only person there with a riding crop and spurs.\par<br/> @@ -1940,16 +1960,16 @@ He would have taken the car, had it not been stolen. But that was why he was her <p class="centerimg"><img src="html-resources/inlineimagest.png" width="651" height="249" alt="example of InlineImage*"/></p> </div> -<h4 id="h8.4.4">8.4.4. \BlockImage[<em>alignment,hoffset,voffset</em>]{<em>imageFile.png or .jpg</em>}[<em>text</em>]</h4> +<h4 id="h8.4.4">8.4.4. <code>\BlockImage[<em>alignment,hoffset,voffset</em>]{<em>imageFile.png or .jpg</em>}[<em>text</em>]</code></h4> <div class="d4" id="d8.4.4"> -<p class="noindent">Note that \BlockImage has an optional argument that <i>precedes</i> the mandatory image file name. It has another optional argument that <i>follows</i> the file name. If this second option is used, there must be no space between <code>}[</code>.</p> -<p>The first optional argument has up to three comma-separated values. The first is alignment: <i>l</i>, <i>c</i>, or <i>r</i> for left, center, or right. The second and third values are hoffset and voffset. Unlike the \InlineImage command, do not use <i>b</i> to indicate vertical position relative to the image bottom; it is always at the top with this command. The default alignment is centered, without offsets.</p> +<p class="noindent">Note that <code>\BlockImage</code> has an optional argument that <i>precedes</i> the mandatory image file name. It has another optional argument that <i>follows</i> the file name. If this second option is used, there must be no space between <code>}[</code>.</p> +<p>The first optional argument has up to three comma-separated values. The first is alignment: <i>l</i>, <i>c</i>, or <i>r</i> for left, center, or right. The second and third values are hoffset and voffset. Unlike the <code>\InlineImage</code> command, do not use <i>b</i> to indicate vertical position relative to the image bottom; it is always at the top with this command. The default alignment is centered, without offsets.</p> <p>An automatic calculation clears the height of the image. Subsequent text will be on grid. This is the right thing to do when the image and included text fit on a single page. But if they cannot both fit on a single page, an unusual layout will result.</p> </div> -<h4 id="h8.4.5">8.4.5. \BlockImage with Accompanying Text</h4> +<h4 id="h8.4.5">8.4.5. <code>\BlockImage</code> with Accompanying Text</h4> <div class="d4" id="d8.4.5"> -<p class="noindent">The second optional argument of \BlockImage, following the image file name, may contain text that will accompany the image in the same block of space. The text is left-aligned like ordinary text, no matter which alignment you use for the image. The text may be in more than one paragraph, and may use {\centering ...\par} or \begin{adjustwidth} ... \end{adjustwidth} for positioning relative to the image. The text may overlie the image, using \charscale. You may need to use \forceindent or \backindent to control how the text appears. Note that you cannot automatically "flow" text around an image in <i>novel</i> class.</p> +<p class="noindent">The second optional argument of <code>\BlockImage</code>, following the image file name, may contain text that will accompany the image in the same block of space. The text is left-aligned like ordinary text, no matter which alignment you use for the image. The text may be in more than one paragraph, and may use <code>{\centering ...\par}</code> or <code>\begin{adjustwidth} ... \end{adjustwidth}</code> for positioning relative to the image. The text may overlie the image, using <code>\charscale</code>. You may need to use <code>\forceindent</code> or <code>\backindent</code> to control how the text appears. Note that you cannot automatically "flow" text around an image in <i>novel</i> class.</p> <p>Example:</p> <p class="code"> <code> @@ -1975,30 +1995,29 @@ Lord Withens was taken aback. How dare this mere gnome speak to him in such a to <h2 id="h9">9. Front Matter</h2> <div class="d2" id="d9"> -<p class="noindent">The <b>\frontmatter</b> command must be written immediately after \begin{document}. This sets page numbering to lowercase roman, and performs some other actions.</p> -<p>A book's front matter is <em>about the book</em>. It is not part of the story. The only mandatory front matter is the Title Page and its verso, the Copyright Page. On a practical basis, six pages of front matter are the minimum, and this minimum is often used, even by major publshers. See Appendix B for how to construct basic six-page front matter.</p> +<p class="noindent">The <b><code>\frontmatter</code></b> command must be written immediately after <code>\begin{document}</code>. This sets page numbering to lowercase roman, and performs some other actions.</p> +<p>A book's front matter is <em>about the book</em>. It is not part of the story. The only mandatory front matter is the Title Page and its verso, the Copyright Page. On a practical basis, six pages of front matter are the minimum, and this minimum is often used, even by major publishers. See <a href="#hB">Appendix B</a> for how to construct basic six-page front matter.</p> <h3 id="h9.1">9.1. Useful Commands in Front Matter</h3> <div class="d3" id="d9.1"> <p class="noindent">Among the numerous commands available to you, here are some that are particularly useful in front matter, for styling and positioning:</p> <p class="code"><code>\thispagestyle{empty}</code> prevents header or footer from printing on that page. In most cases, this command should be the first to appear on each page of front matter. The only exceptions are lengthy Foreword, Preface, and Introduction. Those should be treated with the same styling as chapters, and may contain headers (except at their start) or footers.</p> -<p class="code"><code>\strut</code> and <code>\stake</code> are invisible, zero-width placeholders. \strut occupies the vertical text height, but \stake does not. Once in a while, these are used to establish a reference point, where positioning is relative to prior code.</p> +<p class="code"><code>\strut</code> and <code>\stake</code> are invisible, zero-width placeholders. <code>\strut</code> occupies the vertical text height, but <code>\stake</code> does not. Once in a while, these are used to establish a reference point, where positioning is relative to prior code.</p> <p class="code"><code>\charscale</code> changes text size, and can also tweak position.</p> -<p class="code"><code>\vspace*</code> (note the asterisk) placed at the top of the page, sets a blank area above the first line of text. Useful for moving things down on the page. Can also be used for vertical spacing between elements.</p> -<p class="code"><code>\null\vfill</code> placed at the top of the page, pushes the remaining text down, so that its last line is at the bottom of the text block. Sometimes a copyright page is styled this way.</p> -<p class="code"><code>\vfill</code> (without the \null) may be used between paragraphs of text. The subsequent text will be pushed to the bottom of the text block. This is useful for forcing a publisher's imprint downward, on the title page.</p> +<p class="code"><code>\vspace</code> inserts a specified vertical space between block elements (such as paragraphs). Without an asterisk, the command does nothing if it is at the top of the page. With an asterisk, the command is equally effective anywhere on the page.</p> +<p class="code"><code>\vfill</code> between block elements (such as paragraphs) pushes the following material downward on the page. Typically used on a title page, where the publisher's imprint is forced down to the final line.</p> <p class="code"><code>center</code> environment. Although the center environment may sometimes cause vertical misalignment when used within flowing text (chapters), it is OK for front matter, where that is not a problem.</p> <p class="code"><code>adjustwidth</code> environment. Very useful for creating text areas do not occupy the full page text width. Often used for a Dedication or Epigraph. Also useful in conjunction with the center environment, for certain copyright page designs. In other cases, a non-centered copyright page may have its text limited to less than full width, so that it is visually different from an ordinary page.</p> <p class="code"><code>legalese</code> environment. Sets text ragged-right, and disables hyphenation. Useful for some copyright page designs.</p> -<p class="code"><code>\smcp</code> and <code>\allsmcp</code> for small caps. \smcp is the same as \textsc, which converts lowercase letters to small caps, leaving uppercase letters unchanged. \allsmcp changes both uppercase and lowercase letters to small caps. These commands are useful for such expressions as FIRST EDITION, which are customarily set in small caps.</p> -<p class="code"><code>\lnum</code> sets Lining numbers, which all have the height of a capital letter. Without using \lnum, numbers will probably be set Old Style, since that is the text default.</p> -<p class="code"><code>\indent, \forceindent, \noindent, \backindent</code> control indentation. \forceindent and \backindent usually work when the others don't, and can also be used cumulatively. If your copyright page has CIP data, you will need to pay attention to how the data is indented, since that is part of the specification.</p> -<p class="code"><code>\decoglyph</code> selects a decorative element from the deco font (normally NovelDeco.otf). The decoration will usually have to be magnified, using \charscale. This is a handy way to add something to a title page, if you do not otherwise have artwork there.</p> -<p class="code"><code>\clearpage</code> or <code>\cleartorecto</code> terminates a page. With \clearpage, the following material will be placed recto or verso, in normal flow. With \cleartorecto, if the following page would normally be verso, then a blank verso is inserted, so that the following material is forced to recto. The blank page has no header/footer.</p> -<p class="code"><code>\itshape</code> or <code>\textit</code> for italics. The \itshape command is used when the text includes multiple paragraphs. Sometimes a copyright page is styled in all italics. The \textit command cannot cross paragraphs.</p> +<p class="code"><code>\smcp</code> and <code>\allsmcp</code> for small caps. <code>\smcp</code> is the same as <code>\textsc</code>, which converts lowercase letters to small caps, leaving uppercase letters unchanged. <code>\allsmcp</code> changes both uppercase and lowercase letters to small caps. These commands are useful for such expressions as FIRST EDITION, which are customarily set in small caps.</p> +<p class="code"><code>\lnum</code> sets Lining numbers, which all have the height of a capital letter. Without using <code>\lnum</code>, numbers will probably be set Old Style, since that is the text default.</p> +<p class="code"><code>\indent</code>, <code>\forceindent</code>, <code>\noindent</code>, <code>\backindent</code> control indentation. <code>\forceindent</code> and <code>\backindent</code> usually work when the others don't, and can also be used cumulatively. If your copyright page has CIP data, you will need to pay attention to how the data is indented, since that is part of the specification.</p> +<p class="code"><code>\decoglyph</code> selects a decorative element from the deco font (normally <i>NovelDeco.otf</i>). The decoration may usually have to be magnified, using <code>\charscale</code>. This is a handy way to add something to a title page, if you do not otherwise have artwork there.</p> +<p class="code"><code>\clearpage</code> or <code>\cleartorecto</code> terminates a page. With <code>\clearpage</code>, the following material will be placed recto or verso, in normal flow. With <code>\cleartorecto</code>, if the following page would normally be verso, then a blank verso is inserted, so that the following material is forced to recto. The blank page has no header/footer.</p> +<p class="code"><code>\itshape</code> or <code>\textit</code> for italics. The <code>\itshape</code> command is used when the text includes multiple paragraphs. Sometimes a copyright page is styled in all italics. The <code>\textit</code> command cannot cross paragraphs.</p> <p class="code"><code>\straightquote</code> and <code>\straightdblquote</code> insert a character. A following space is gobbled, in usual TeX fashion. This commands may be helpful if (for some technical reason) you must place a straight quote, and cannot allow the typesetter to convert it to a curly quote.</p> -<p class="code"><code>parascale</code> environment. Unlike \charscale, this command works with line breaks and multiple paragraphs. The scaled text also has its line spacing scaled, which is not a problem in most front matter. Possibly useful if your copyright information does not quite fit on one page, at normal text size.</p> -<p class="code"><code>\strut\hfill</code> right-aligns the following text. Be sure to finish with \par. Useful for attributing an Epigraph, or for things such as a signed Foreword.</p> +<p class="code"><code>parascale</code> environment. Unlike <code>\charscale</code>, this command works with line breaks and multiple paragraphs. The scaled text also has its line spacing scaled, which is not a problem in most front matter. Possibly useful if your copyright information does not quite fit on one page, at normal text size.</p> +<p class="code"><code>\strut\hfill</code> right-aligns the following text n a single line. Be sure to finish with <code>\par</code>. Useful for attributing an Epigraph, or for things such as a signed Foreword.</p> <p class="code"><code>toc</code> environment. Specifically designed for a Table of Contents.</p> <p class="code"><code>\tocitem</code> is an entry in a Table of Contents.</p> <p>You may also use image commands, as needed. In fiction, the title page often has graphical elements.</p> @@ -2007,13 +2026,13 @@ Lord Withens was taken aback. How dare this mere gnome speak to him in such a to <h3 id="h9.2">9.2. Chapter-Like Sections in Front Matter</h3> <div class="d3" id="d9.2"> <p class="noindent">By "chapter-like section" I mean something such as a Foreword, Preface, or Introduction that may be styled in the same manner as a chapter. Most fiction does not have them. Before you place such sections in front matter, ask yourself: Do your readers really want to hear about your travails in writing the book? Maybe they'd rather get directly to the sex and violence in your main story.</p> -<p>You may begin a chapter-like section with the \ChapterStart environment, and use \ChapterTitle. These commands may be used anywhere.</p> -<p>Such a section always begins recto. If it does not extend for more than two pages, then you should use \thispagestyle{empty} to ensure that headers and footers do not appear. Since you don't know where a two-page section will break, the second \thispagestyle{empty} may be placed at the end of the second page, before \clearpage.</p> +<p>You may begin a chapter-like section with the <i>ChapterStart</i> environment, and use <code>\ChapterTitle</code>. These commands may be used anywhere.</p> +<p>Such a section always begins recto. If it does not extend for more than two pages, then you should use <code>\thispagestyle{empty}</code> to ensure that headers and footers do not appear. Since you don't know where a two-page section will break, the second <code>\thispagestyle{empty}</code> may be placed at the end of the second page, before <code>\clearpage</code>.</p> <p>However, if the section is longer than two pages, it may have headers and footers. For example, suppose you have a lengthy Preface, in a book that ordinarily has page headings. At the start of the Preface:</p> <p class="code"><code>\SetVersoHeadText{\allsmcp{Preface}}<br/> \SetRectoHeadText{\allsmcp{Preface}}</code></p> -<p>In the above case, small caps were chosen as style. Then, instead of the author and title of your book, the word <small>PREFACE</small> will appear in headings. Page numbers will be lowercase roman, because those were set by the \frontmatter command.</p> -<p>Note: If your book is of the genre that pretends to be a "lost manuscript," with the main story being a transcription or translation of the manuscript, then your own explanation of its finding should go in main matter, not front matter. That's because your explanation is fictional, and is part of the total story. Something like that might be titled "Author's Note" or "About the Manuscript," or maybe "Prologue," and be designed like a chapter.</p> +<p>In the above case, small caps were chosen as style. Then, instead of the author and title of your book, the word <small>PREFACE</small> will appear in headings. Page numbers will be lowercase roman, because those were set by the <code>\frontmatter</code> command.</p> +<p>Note: If your book is of the genre that pretends to be a "lost manuscript," with the main story being a transcription or translation of the manuscript, then your own explanation of its finding may go in front matter or main matter. If it pretends to be "about the book" with litle to say, then it can go in front matter (probably as an "Author's Note"). If it is a chapter-length tale of the adventure finding the rest of the book, then is should go in main matter (probably as an "Introduction" or possibly "Prologue"). I doubt if there is a bright line.</p> </div><!-- end class="d3" --> <h3 id="h9.3">9.3. Examples of Front Matter Pages</h3> @@ -2021,7 +2040,7 @@ Lord Withens was taken aback. How dare this mere gnome speak to him in such a to <h4 id="h9.3.1">9.3.1. Sample Title Page</h4> <div class="d4" id="d9.3.1"> -<p class="noindent">Below is a sample title page. The <code>\orbitron</code> command would be defined in Preamble using \NewFontFace. It calls for the font <i>Orbitron-Medium.otf</i>, which is not part of the TeX distribution. The \decoglyph command calls for a decorative element from the <i>NovelDeco.otf</i> font, which comes with the <i>novel</i> class. The length \nbs is the normal baseline skip of the book's main font. The \stake commands place an invisible zero-width reference point, for the use of adjacent commands. Here is the code:</p> +<p class="noindent">Below is a sample title page. The <code>\orbitron</code> command would be defined in Preamble using <code><a href="#h5.3">\NewFontFace</a></code>. It calls for the font <i>Orbitron-Medium.otf</i>, which is not part of the TeX distribution. The <code>\decoglyph</code> command calls for a decorative element from the <i>NovelDeco.otf</i> font, which comes with the <i>novel</i> class. The length \nbs is the normal baseline skip of the book's main font. The <code>\stake</code> commands place an invisible zero-width reference point, for the use of adjacent commands. Here is the code:</p> <p class="code"><img class="floatright" src="html-resources/starsmash.png" width="263" height="410" alt="sample title page"/> <code><small> \clearpage<br/> @@ -2048,6 +2067,7 @@ Eschwege • Merthyr Tydfil • Lethbridge\par<br/> <h4 id="h9.3.2">9.3.2. Sample Copyright Page</h4> <div class="d4" id="d9.3.2"> <p class="noindent">The Copyright Page should be styled differently from the main text. Note that you may past the copyright symbol © from a Unicode character map.</p> +<p>The simplest Copyright Page begins with <code>\null\vfill</code> so that the following text sinks to the bottom of the page. Ensure that the text is not hyphenated. One way to do that is to use the <i>legalese</i> environment, which prevents hyphenation and sets text ragged-right instead of justified. The <a href="#h7.1.3"><i>parascale</i></a> environment is helpful for setting the text size to something other than normal.</p> <p> </p> <p class="noindent"><img class="floatright" style="padding-top:2em" src="html-resources/copyrightcentered.png" width="264" height="408" alt="sample copyright page, centered"/> First Example: centered italics, limited width. This design is most effective when you don't have a lot to say.</p> <p class="code"><code><small> @@ -2141,8 +2161,9 @@ Let me tell you, there's nothing more exciting than the brouhaha at Mickey's Pub <h4 id="h9.3.5">9.3.5. Sample Table of Contents</h4> <div class="d4" id="d9.3.5"> -<p class="noindent">Most fiction does not have, and does not need, a Table of Contents. It is more useful when the story consists of discrete episodes with distinctive names, not just numbers. Or, if the book is a collection of short stories, a table of contents is mandatory. If your book is a critical edition, with sections by different authors, then a Table of Contents is appropriate. Avoid any of the table environments that come with TeX or its packages. These do not provide the most attractive presentation for fiction, without a lot of work on your part.</p> -<p>A Table of Contents has no header or footer, and no printed page number. Use \thispagestyle{empty}. If it continues to a second page, add \thispagestyle{empty} at the end, if you don't know where the page breaks.</p> +<p class="noindent">Most fiction does not have, and does not need, a Table of Contents. It is more useful when the story consists of discrete episodes with distinctive names, not just numbers. Or, if the book is a collection of short stories, a table of contents is mandatory. If your book is a critical edition, with sections by different authors, then a Table of Contents is appropriate.</p> +<p>Avoid any of the table environments that come with TeX or its packages. These do not provide the most attractive presentation for fiction, without a lot of work on your part.</p> +<p>A Table of Contents has no header or footer, and no printed page number. Use <code>\thispagestyle{empty}</code>. If it continues to a second page, add <code>\thispagestyle{empty}</code> at the end, if you don't know where the page breaks.</p> <p>If you use a Table of Contents, it must begin on a recto page.</p> <p>The Table of Contents does not include itself, Dedication, or Epigraph.</p> <p>A single front matter map, wherever it appears, need not be listed in a Table of Contents. If there are numerous maps and diagrams strewn throughout the book, then you may list them in the Table, or provide a separate List of Illustrations.</p> @@ -2152,23 +2173,23 @@ Let me tell you, there's nothing more exciting than the brouhaha at Mickey's Pub <div class="d5" id="d9.3.5.1"> <p class="code"><code>\begin{toc}[<em>extra entry separation</em>]{<em>extra margins</em>} <em>...</em> \end{toc}</code></p> <p>The table is not indented, and text within it is not indented.</p> -<p>• The optional argument is a number. It is the portion of normal baselineskip that will be added beneath each \tocitem entry (see next section). Default is 0, meaning that there is no extra skip between items, and normal baselineskip is maintained. A value greater than 0 spreads the entries, which could be attractive if there are only a few chapters and you'd like to use more space on the page. For example, a value of 0.25 means that a gap of 0.25 normal baselineskip will be added beneath each entry. A small negative value will crowd the lines together, but there is a limit (approximately -0.1) before the lines cannot be squeezed any tighter.</p> -<p>Note that the optional argument only applies to \tocitem entries, not to any other text within the environment.</p> +<p>• The optional argument is a number. It is the portion of normal baselineskip that will be added beneath each <code>\tocitem</code> entry (see next section). Default is 0, meaning that there is no extra skip between items, and normal baselineskip is maintained. A value greater than 0 spreads the entries, which could be attractive if there are only a few chapters and you'd like to use more space on the page. For example, a value of 0.25 means that a gap of 0.25 normal baselineskip will be added beneath each entry. A small negative value will crowd the lines together, but there is a limit (approximately -0.1) before the lines cannot be squeezed any tighter.</p> +<p>Note that the optional argument only applies to <code>\tocitem</code> entries, not to any other text within the environment.</p> <p>• The required argument is a length, which will be the amount of extra margin added at left and right of the table (using adjustwidth). A value of 0em allows the table to occupy the full width of the textblock. A value of 2em adds 2em to the margin on each side, so that the width of the table is 4em less than the width of the textblock.</p> -<p>It is best to specify horizontal lengths in units of <i>em</i> or the proportional <i>\parindent</i> or <i>\textwidth</i>.</p> -<p>• Place at least empty line above the Table, using \null or \vspace*. This will prevent the Table's title (which is normally anlarged using \charscale) from encroaching into the top margin.</p> +<p>It is best to specify horizontal lengths in units of <i>em</i> or the proportional <code>\parindent</code> or <code>\textwidth</code>.</p> +<p>• Place at least one empty line above the Table, using <code>\null</code> or <code>\vspace*</code>. This will prevent the Table's title (which is normally enlarged using <code>\charscale</code>) from encroaching into the top margin.</p> </div> -<h5 id="h9.3.5.2">9.3.5.2. \tocitem and \tocitem* Entries</h5> +<h5 id="h9.3.5.2">9.3.5.2. <code>\tocitem</code> and <code>\tocitem*</code> Entries</h5> <div class="d5" id="d9.3.5.2"> <p class="code"><code>\tocitem[<em>chapter number</em>]{<em>description</em>}{<em>page number</em>} and starred version</code></p> <p>• Use this command for entries in the Table. Do not use it for non-Table text on the page.</p> <p>• The optional argument is the chapter number, at most two digits. The number will be left-aligned, with a period automatically added. Following the period will be the amount of space needed to keep the following description aligned.</p> <p>• If the optional argument is omitted (or empty), then there is no space, and the following description will align to the left of the table.</p> <p>• If the optional argument is the tilde character ~ then no number or period is printed, but the space is occupied, so that the following description aligns as if you had entered a chapter number.</p> -<p>• The description is usually the chapter title. If it cannot easily fit on one line, then use an additional \tocitem, because the text cannot be wrapped. The following example shows how this can be done.</p> -<p>• Without the asterisk, \tocitem fills the area between the description and the page number with empty space. The more popular, starred \tocitem* command fills with a dotted line, and is very attractive.</p> -<p>• You may use ordinary style commands, such as \textit{}, in the entries.</p> +<p>• The description is usually the chapter title. If it cannot easily fit on one line, then use an additional <code>\tocitem</code>, because the text cannot be wrapped. The following example shows how this can be done.</p> +<p>• Without the asterisk, <code>\tocitem</code> fills the area between the description and the page number with empty space. The more popular, starred <code>\tocitem*</code> command fills with a dotted line, and is very attractive.</p> +<p>• You may use ordinary style commands, such as <code>\textit</code>, in the entries.</p> <p><b>Example of toc:</b></p> <p class="code" style="text-indent:0px; font-size:small"><img class="floatright" src="html-resources/toc.png" width="264" height="408" alt="toc example"/> <code> @@ -2279,7 +2300,7 @@ By the time I returned home...\par<br/> <p class="noindent">Many works of fiction have a map or other diagram. It might be the map of a real or fictional geographic area. It might be the map of a crime scene. It might be an inheritance chart. Even though fictional, it may be placed in front matter.</p> <p>A map may be placed verso or recto, as long as it does not visually interfere with material on the facing page. In particular, do not place a map on the verso that faces the opening of your story.</p> <p>Typically, a map appears late in front matter, but I have sometimes seen it early in front matter. I have not seen an authoritative guide to placement. A single map, or maybe two, need not be mentioned in a table of contents or illustrations. If you have a lot of them strewn around the book, then they should be listed in such a table; but this is very rare in fiction.</p> -<p>As with all images in <i>novel</i>, a map must be raster png or jpg (not vector artwork), of correct resolution, placed using <i>novel's</i> own image placement commands. These are described elsewhere in this documentation.</p> +<p>As with all images in <i>novel</i>, a map must be raster png or jpg (not vector artwork), of correct resolution, placed using <i>novel's</i> own image placement commands. These are described <a href="#h8">elsewhere</a> in this documentation.</p> <p>Normally, a map in front matter has no header/footer. For example:</p> <p class="code"><img class="floatright" src="html-resources/map.png" width="178" height="274" alt="sample map"/> <code><small> @@ -2302,6 +2323,15 @@ By the time I returned home...\par<br/> </small></code></p> <div style="clear:both"></div> </div> + +<h4 id="h9.3.10">9.3.10. Cast of Characters, Synopsis, etc.</h4> +<div class="d4" id="d9.3.10"> +<p class="noindent">Some authors like to provide a page or two that names the characters who will appear in the story, with a quick description. This seems fashionable in murder mysteries.</p> +<p>Example: "Lord Withens: Master of his ancestral estate, fond of horses and bridge. Who knew what he kept in that distant farmer's cottage?" (Plus a few other characters.)</p> +<p>Or, if your book is part of a series where this book begins where another left off, you may have a short Synopsis reminding the reader what came before. Example: "Space Captain Withens and his robo-sidekick are on a quest to find the lost Frgltz stone. After intercepting a secret message, they hastily sped to planet Wkertx, only to discover that it was a trap. They are now hiding in an abandoned mine, with a squad of Qltprs patrolling the skies above."</p> +<p>The Cast of Characters, or Synopsis, begins recto. It is placed very late in front matter, just before main matter begins.</p> +<p>What's the difference between a Synopsis and a Prologue? A Synopsis is very brief, rarely more than a page, and does not reveal anything that an avid reader would not already know, from previous books in the series. It belongs in front matter. A Prologue is brief (but may be a few pages), and does reveal something that the reader would not already know. It belongs in main matter. I cannot think of any occasion for using both.</p> +</div> </div><!-- end class="d3" --> @@ -2313,10 +2343,11 @@ By the time I returned home...\par<br/> <h2 id="h10">10. Transition from Front Matter to Main Matter</h2> <div class="d2" id="d10"> -<p class="noindent">Main matter always begins with the \mainmatter command, immediately following \clearpage or \cleartorecto. The \mainmatter command sets page numbering to Arabic 1.</p> +<p class="noindent">Main matter always begins with the <code>\mainmatter</code> command, immediately following <code>\clearpage</code> or \cleartorecto</code>. The <code>\mainmatter</code> command sets the page recto, numbering to Arabic 1.</p> <p>There is no middle-matter between front matter and main matter. So, it is necessary to decide whether a page belongs in one or the other. The final page of front matter is verso, with a lowercase roman page number that is almost never printed. The first page of main matter has Arabic page number 1, which may or may not be printed, depending on layout.</p> <p>In general, anything that is "about the book" is meta-information that belongs in front matter. "The story itself," and any aftermath, belongs in main matter. This section provides a guide to determining which is which.</p> -<p>Some situations are judgement calls. Where I provide an opinion, it is based on my obervations of popular fiction books, or the <i>Chicago Manual of Style, 16th Edition (CMoS)</i>, favoring actual books when there is room for disagreement. Opinions offered by non-authoritative web sites have been disregarded.</p> +<p>Some situations are judgement calls. Where I provide an opinion, it is based on my obervations of popular fiction books, or the <i>Chicago Manual of Style, 16th Edition (CMoS)</i>, favoring actual books when there is room for disagreement. Opinions offered by non-authoritative web sites have been disregarded. It's not that I am more authoritative; take my advice, or leave it, as you see fit.</p> +<p>Just the other day, I was looking at a famous book by a famous author, reprinted by a famous publisher in hard cover. Its page numbers began with 1 at the Half-Title and ran continuously. No separate numbering for front matter. Why bother thinking about it, when the book will sell the same number of copies anyway?</p> <h3 id="h10.1">10.1. Introduction in Front Matter</h3> <div class="d3" id="d10.1"> @@ -2354,7 +2385,7 @@ In the chapters pertaining to transmontane trade and cultural exchange, I have t <h3 id="h10.3">10.3. Second Half-Title in Front Matter</h3> <div class="d3" id="d10.3"> <p class="noindent">If a second Half-Title is used, <i>CMoS</i> acknowledges that theory and practice often differ. Here, I will go with the common practice in fiction.</p> -<p>If front matter is short, a second Half-Title is sometimes used to prevent verso front matter from clashing with recto main matter. This is one of the possibilities discussed in the basic six-page front matter (Appendix B). In this case, the second Half-Title is front matter, and so is its verso. Main matter begins at the following recto.</p> +<p>If front matter is short, a second Half-Title is sometimes used to prevent verso front matter from clashing with recto main matter. This is one of the possibilities discussed in the basic six-page front matter (<a href="#hB">Appendix B</a>). In this case, the second Half-Title is front matter, and so is its verso. Main matter begins at the following recto.</p> <p>You can also do this for more than the basic six pages of front matter, if you wish. However, there are situations where a second Half-Title should be the start of main matter. See below.</p> </div><!-- end class="d3" --> @@ -2362,10 +2393,10 @@ In the chapters pertaining to transmontane trade and cultural exchange, I have t <div class="d3" id="d10.4"> <p class="noindent">Some books are partitioned into distinct sub-books. A sub-book is of substantial length, not individual short stories.</p> <p>If your book has distinct sub-books, then each of them has its own recto cover page, known as a Part Separator. Its verso is blank or Epigraph. Then the accompanying story begins recto.</p> -<p>A Part Separator is always main matter. So, the first Part Separator is page 1. Its text begins on page 3. Do not re-initalize the page count when you get to the next Part Separator.</p> -<p>The simplest Part Separator is <i>Part I</i>, followed by <i>Part II</i>. You could also call them <i>Book I</i> and <i>Book II</i>, or perhaps <i>First Invasion</i> and <i>Second Invasion</i>. These are not chapters; each of them occupies a substantial portion of the entire book, and contains its own chapters.</p> +<p>A Part Separator is always main matter. So, the first Part Separator is page 1. Its text begins on page 3. Do not re-initialize the page count when you get to the next Part Separator.</p> +<p>The simplest Part Separator is <i>Part I</i>, followed by <i>Part II</i>. You could also call them <i>Book I</i> and <i>Book II</i>, or perhaps <i>First Invasion</i> and <i>Second Invasion</i>. These are not chapters; each part occupies a substantial portion of the entire book, and contains its own chapters.</p> <p>Sometimes a Part Separator has a brief description of its purpose, as in <i>Book I. On Earth</i> followed by <i>Book II. On Mars</i>.</p> -<p>Unless your book has a very complex structure, do not use both a second Half-Title and a Part Separator. Combine them as the recto main matter page 1: <i>The Withens Chronicles. Part I</i>. Then the next Part Separator might simply be <i>Part II</i>.</p> +<p>Unless your book has a very complex structure, do not use both a second Half-Title and a Part Separator. Combine them as the recto main matter page 1: <i>The Withens Chronicles. Part I</i>. Then the next Part Separator might simply be <i>Part II</i>. No particular rule.</p> </div><!-- end class="d3" --> <h3 id="h10.5">10.5. Second Half-Title in Main Matter</h3> @@ -2393,7 +2424,7 @@ In the chapters pertaining to transmontane trade and cultural exchange, I have t <h3 id="h10.8">10.8. Chapters</h3> <div class="d3" id="d10.8"> <p class="noindent">Finally, you have arrived at Chapter One! It is always recto, in main matter. As described above, its page number may be 1 or 3. If your book is a collection of short stories, the same applies to the first story.</p> -<p>Subsequent chapters may begin recto or verso, or the book may be designed so that each chapter always begins recto. In the majority of novels I have seen, recto/verso is used. The \clearpage command starts a new page (recto or verso), and the \cleartorecto command will (if necessary) insert a blank verso, so that the following material is always recto.</p> +<p>Subsequent chapters may begin recto or verso, or the book may be designed so that each chapter always begins recto. In the majority of novels I have seen, recto/verso is used. The <code>\clearpage</code> command starts a new page (recto or verso), and the \cleartorecto command will (if necessary) insert a blank verso, so that the following material is always recto.</p> <p>In the case of short stories, especially if they are by different authors, it is customary to begin each one as recto.</p> </div><!-- end class="d3" --> @@ -2406,7 +2437,7 @@ In the chapters pertaining to transmontane trade and cultural exchange, I have t <h2 id="h11">11. Chapter Structure</h2> <div class="d2" id="d11"> -<p class="noindent">This section describes how chapters, and chapter-like material such as Preface, are designed. The <i>novel</i> class has commands specifically for this purpose. Do not use the ordinary TeX \chapter command, or any other TeX partitioning such as \section.</p> +<p class="noindent">This section describes how chapters, and chapter-like material such as Preface, are designed. The <i>novel</i> class has commands specifically for this purpose. Do not use the ordinary TeX <code>\chapter</code> command, or any other TeX partitioning such as <code>\section</code>.</p> <p>The last command of the document body must be \cleartoend. This ensures that the final page will be a blank verso, if necessary preceded by a blank recto.</p> <h3 id="h11.1">11.1. ChapterStart Environment</h3> @@ -2421,13 +2452,13 @@ In the chapters pertaining to transmontane trade and cultural exchange, I have t % contents of chapter start<br/> \end{ChapterStart </code></p> -<p>The environment reserves a block of space, default 10 lines high. You may globally change that value in the Preamble, using the \SetChapterStartHeight{<em>lines</em>} command.</p> +<p>The environment reserves a block of space, default 10 lines high. You may globally change that value in the Preamble, using the <code>\SetChapterStartHeight{<em>lines</em>}</code> command.</p> <p>On a per-chapter basis, the height may be changed using the optional <i>lines</i> argument of the ChapterStart environment. For example, sometimes that is helpful if a chapter has only one or two lines on its final page; then, you can effectively move all lines forward, by reducing the height of its ChapterStart.</p> <p>In all cases, the height must be an integer, greater than or equal to 4.</p> <p>You can put almost anything you like within this environment. Its height does not shrink or expand with content. However, if you put too much for the reserved space, then the excess will flow out the bottom of the reserved area, and mingle with the main text below. That is usually undesirable. If you do put too much, no error or warning is generated (because it might have been by intent).</p> -<p>Note that ChapterStart does not, by itself, begin a new page. You have to issue the \clearpage (or \cleartorecto) command before ChapterStart. This is to allow for exotic designs with small ChapterStart space, and more than one chapter per page. But if that is the nature of your book, have a look at the \QuickChapter command.</p> -<p>If the header/footer style for this particular chapter is <i>not</i> the same as the ChapterStart default style, then locally over-ride the default using \thispagestyle <i>prior to</i> ChapterStart. See below.</p> -<p>In some books that have headers, their content varies from chapter to chapter. Commands \SetVersoHeadText and \SetRectoheadText control that content. Once issued, they do not expire at the end of a chapter, but remain in effect until re-issued.</p> +<p>Note that ChapterStart does not, by itself, begin a new page. You have to issue the <code>\clearpage</code> (or <code>\cleartorecto</code>) command before ChapterStart. This is to allow for exotic designs with small ChapterStart space, and more than one chapter per page. But if that is the nature of your book, have a look at the <code>\QuickChapter</code> command.</p> +<p>If the header/footer style for a particular chapter is <i>not</i> the same as the ChapterStart default style, then locally over-ride the default using <code>\thispagestyle</code> <i>prior to</i> ChapterStart. See below.</p> +<p>In some books that have headers, their content varies from chapter to chapter. Commands <code>\SetVersoHeadText</code> and <code>\SetRectoheadText</code> control that content. Once issued, they do not expire at the end of a chapter, but remain in effect until re-issued.</p> <h4 id="h11.1.1">11.1.1. Chapter Title, Subtitle, Deco</h4> <div class="d4" id="d11.1,1"> @@ -2437,23 +2468,23 @@ In the chapters pertaining to transmontane trade and cultural exchange, I have t <p class="code">\ChapterSubtitle[<em>alignment</em>]{<em>text</em>}</p> <p>The chapter subtitle will automatically use the font specifications of <i>subchfont</i>, unless you locally over-ride them using other font commands.</p> <p class="code">\ChapterDeco[<em>alignment</em>]{<em>text, image</em>}</p> -<p>The chapter deco is a non-committal way to place almost anything. It uses the ordinary text font, unless you over-ride it with a font command. Perhaps you will use the \decoglyph command to pick an item from the deco font. You can also use an image.</p> -<p>Each of the above commands is limited to one, non-wrapping line. However, they may be issued more than once in the same ChapterStart. So, if the chapter title requires two lines, use \ChapterTitle twice.<p> -<p>If you don't like the vertical positioning, you can change it using \vspace commands. You will usually need to use \vspace* above the chapter title, so that it is not too high on the page.</p> +<p>The chapter deco is a non-committal way to place almost anything. It uses the ordinary text font, unless you over-ride it with a font command. Perhaps you will use the <code>\decoglyph</code> command to pick an item from the deco font. You can also use an image.</p> +<p>Each of the above commands is limited to one, non-wrapping line. However, they may be issued more than once in the same <i>ChapterStart</i>. So, if the chapter title requires two lines, use <code>\ChapterTitle</code> twice.<p> +<p>If you don't like the vertical positioning, you can change it using <code>\vspace</code> commands. You will usually need to use <code>\vspace*</code> above the chapter title, so that it is not too high on the page.</p> </div> <h4 id="h11.1.2">11.1.2. Default Header/Footer at Chapter Start</h4> <div class="d4" id="d11.1,2"> -<p>By default, <i>novel</i> automatically uses \thispagestyle{footer} when it sees the ChapterStart environment. Then, no header will print above the chapter start. However, if there is a footer, it will print.</p> +<p>By default, <i>novel</i> automatically uses <code>\thispagestyle{footer}</code> when it sees the ChapterStart environment. Then, no header will print above the chapter start. However, if there is a footer, it will print.</p> <p>If you wish to use a different default behavior for ChapterStart, then write this command <i>in the Preamble</i>:</p> <p class="code"><code>\SetChapterStart{<em>choice</em>}</code></p> -<p>In the above, <i>choice</i> is one of the choices available for \thispagestyle, as listed below.</p> +<p>In the above, <i>choice</i> is one of the choices available for <code>\thispagestyle</code>, as listed below.</p> </div> -<h4 id="h11.1.3">11.1.3. \thispagestyle at Chapter Start</h4> +<h4 id="h11.1.3">11.1.3. <code>\thispagestyle</code> at Chapter Start</h4> <div class="d4" id="d11.1.3"> <p>No matter whether a book is fiction or nonfiction,the first page of a chapter almost never has a header. However, it may have a footer if the book design normally has one (typically the page number).</p> -<p>If the setting provided by \SetChapterStart is inappropriate for a particular chapter (or anything using ChapterStart environment), then locally over-ride it using one of these choices:</p> +<p>If the setting provided by <code>\SetChapterStart</code> is inappropriate for a particular chapter (or anything using ChapterStart environment), then locally over-ride it using one of these choices:</p> <p class="code"><code>\thispagestyle{footer}</code></p> <p>The above choice actually means, “footer, if normally available.” It does not create a footer that would not otherwise be present in your general book layout. This is the built-in default.</p> <p class="code"><code>\thispagestyle{empty}</code></p> @@ -2464,8 +2495,9 @@ In the chapters pertaining to transmontane trade and cultural exchange, I have t <p>The above choice is the same as \thispagestyle{footer}, if the layout has a footer. Otherwise, it is very tricky. It reduces the height of the ChapterStart environment by one line. Then, the text on that page is moved upward by one line, leaving a vacancy where the last line would normally be. The page number is centered there. This does not intrude into the lower margin.</p> <p>The following image shows three pages of a Foreword, from a book that uses header but no footer. On its start page, the folio has been dropped inside. Color added for illustration.</p> <p class="centerimg"><img src="html-resources/dfi.png" width="534" height="267" alt="example of inside drop folio"/></p> +<p>Note that the placement of page number does not honor \SetFootJump. The number is sized a little smaller than main text, but it is right where another line of text would be.</p> <p class="code"><code>\thispagestyle{forcenumber}</code></p> -<p>The above choice is the same as \thispagestyle{footer}, if the layout has a footer. Otherwise, it assumes that the page number is located at the outside of a header, and prints only that outside header portion. This is a very rare situation that I have only seen in some nonfiction, where the number of each new chapter (usually by different authors) must be printed somewhere on the page. Avoid it unless you are certain that you need it.</p> +<p>The above choice is the same as \thispagestyle{footer}, if the layout has a footer. Otherwise, it assumes that the page number is located at the outside of a header, and prints only that outside header portion. This is a very rare situation that I have only seen in some nonfiction, where the page number of each new chapter (usually by different authors) must be printed somewhere on the page. Avoid it unless you are certain that you need it.</p> </div> <h4 id="h11.1.4">11.1.4. ChapterStart With Image</h4> @@ -2476,7 +2508,7 @@ In the chapters pertaining to transmontane trade and cultural exchange, I have t <h5 id="h11.1.4.1">11.1.4.1 Text Over Image</h5> <div class="d5" id="d11.1.4.1"> <p class="noindent"><img class="floatright" src="html-resources/ctimg35.png" width="79" height="196" alt="example of chapter title image, text over"/> You may position text over an image. Be aware that overlapping text and graphics may be interpreted as a mistake, by human reviewers. It is best to use black text, or grayscale text that is much darker than the underlying image. Results are uncertain if you try to place light text over a dark image.</p> -<p>Example, where the command \unifrac calls for the font <i>UnifrakturMaguntia.ttf</i>. Note that the font command is <i>outside</i> \charscale:</p> +<p>Example, where the command <code>\unifrac</code> calls for the font <i>UnifrakturMaguntia.ttf</i>. Note that the font command is <i>outside</i> \charscale:</p> <p class="code"><code><small>\begin{ChapterStart}<br/> \BlockImage{sword.png} <span class="ap">% centered by default</span><br/> {\unifrak\centering\charscale[3,0pt,4\nbs]{35}\par}<br/> @@ -2494,15 +2526,15 @@ In the chapters pertaining to transmontane trade and cultural exchange, I have t <h3 id="h11.2">11.2. QuickChapter and Scene Breaks</h3> <div class="d3" id="d11.2"> -<p class="noindent">These commands are used for indicating a break, without the formality ChapterStart.</p> +<p class="noindent">These commands are used for indicating a break, without the formality of ChapterStart.</p> <p>You will need to inspect your layout, to ensure that the break does not occur at an inconvenient location, such as at the bottom of the page. This is not automated. If the break occurs in a bad place, you will simply have to re-write so that it occurs elsewhere.</p> -<h4 id="h11.2.1">11.2.1. \QuickChapter[<em>linelength</em>]{<em>chapter title</em>}</h4> +<h4 id="h11.2.1">11.2.1. <code>\QuickChapter[<em>linelength</em>]{<em>chapter title</em>}</code></h4> <div class="d4" id="d11.2.1"> <p class="noindent">If your novel is the kind of story that consists of numerous short chapters in rapid succession, then you probably do not wish to begin each chapter on its own page, with a block of whitespace at the top. The \QuickChapter command provides an alternative to ChapterStart.</p> -<p>\QuickChapter inserts two blank lines. In the gap, the chapter title is left-justified using <i>subchfont</i> (not <i>chapterfont</i>). It is slightly raised from the normal baseline, because this looks better; but the following text is back on-grid. By default, the start of the following text will be un-indented.</p> +<p><code>\QuickChapter</code> inserts two blank lines. In the gap, the chapter title is left-justified using <i>subchfont</i> (not <i>chapterfont</i>). It is slightly raised from the normal baseline, because this looks better; but the following text is back on-grid. By default, the start of the following text will be un-indented.</p> <p>If the optional <i>linelength</i> is provided, then a dash will be written after the title, at the position and thickness typical of the em dash in <i>subchfont</i>. If <i>linelength</i> is specified in units of length, then that will be the length of the line. But if <i>linelength</i> is an asterisk, then the line will fill to the right margin.</p> -<p>Note that this command is too obstrusive for mere scene changes within a chapter.</p> +<p>Note that this command is too obtrusive for mere scene changes within a chapter.</p> <p>Example:</p> <p class="code"><code><small>Then he looked at me with a sneer, and barked, ``You better haul your can over to Vinny's joint, before the Boss finds out.''\par<br/> \QuickChapter[3em]{16. At Vinny's}<br/> @@ -2514,9 +2546,9 @@ The bouncer wasn't the biggest one I'd ever seen, but he was the ugliest. ...</s <h4 id="h11.2.2">11.2.2. Scene Breaks</h4> <div class="d4" id="d11.2.2"> <p class="noindent">There are several commands dedicated to the purpose of scene breaks.</p> -<p class="code"><b>\scenebreak</b> inserts a one-line blank skip. The following line of text is not indented.</p> -<p class="code"><b>\sceneline</b> inserts a one-line skip, containing a short centered line. The following line of text is not indented.</p> -<p class="code"><b>\scenestars</b> inserts a one-line skip, containing three spaced, centered asterisks. The following line of text is not indented.</p> +<p class="code"><b><code>\scenebreak</code></b> inserts a one-line blank skip. The following line of text is not indented.</p> +<p class="code"><b><code>\sceneline</code></b> inserts a one-line skip, containing a short centered line. The following line of text is not indented.</p> +<p class="code"><b><code>\scenestars</code></b> inserts a one-line skip, containing three spaced, centered asterisks. The following line of text is not indented.</p> <p style="margin-top:20px">Examples:</p> <p class="code"><img style="float:right; margin-left:16px;" src="html-resources/scenebreaks.png" width="331" height="236" alt="scene breaks"/> <code><small> @@ -2532,30 +2564,30 @@ Who could blame them? It's not like they lived in Italy.\par<br/> Ah, such ill fortune haunted the Withens!\par<br/> Unfortunately, novelists of that era had so little to write about, or they would have chosen another family to pursue.\par </small></code></p> -<p>If you are using \scenebreak and the gap occurs at the very bottom or top of a page, then manually substitute \sceneline or \scenestars there. This is a standard way to indicate that the gap is intentional. The subtitution is not automatic.</p> +<p>If you are using \scenebreak and the gap occurs at the very bottom or top of a page, then manually substitute \sceneline or \scenestars there. This is a standard way to indicate that the gap is intentional. The substitution is not automatic.</p> </div> -<h4 id="h11.2.3">11.2.3. \IndentAfterScenebreak</h4> +<h4 id="h11.2.3">11.2.3. <code>\IndentAfterScenebreak</code></h4> <div class="d4" id="d11.2.3"> <p class="noindent">This global command may only be used in the Preamble.</p> -<p>Normally, text begins without a paragraph indent, after each scene break. This is standard in fiction. If you prefer that each new scene begins indented, use this command. It works with \scenebreak, \sceneline, and \scenestars.</p> +<p>Normally, text begins without a paragraph indent, after each scene break. This is standard in fiction. If you prefer that each new scene begins indented, use this command. It works with <code>\scenebreak</code>, <code>\sceneline</code>, and <code>\scenestars</code>.</p> </div> -<h4 id="h11.2.4">11.2.4. \linebreak</h4> +<h4 id="h11.2.4">11.2.4. <code>\linebreak</code></h4> <div class="d4" id="d11.2.4"> -<p class="noindent">The general method for breaking a line, without creating a new paragraph, is to use the double backslash \\. The break will be ragged-right. This is suitable for such things as poetry, and other places where the break does not need to be justified.</p> -<p>In some cases, you need the break to be justified. Command \linebreak does that. Use with caution, since lines earlier in the paragraph will not reflow! Instead, the broken line will justify by itself, possibly resulting in excessive stretch.</p> -<p>One possible use of \linebreak is when layout places something very short at the calculated break. This often happens in English first-person narration, where the word "I" is common. Then, placing \linebreak just before the "I" is likely to result in better appearance. But you will need to inspect the result, both before and after the manually inserted break.</p> +<p class="noindent">The general method for breaking a line, without creating a new paragraph, is to use the double backslash <code>\\</code>. The break will be ragged-right. This is suitable for such things as poetry, and other places where the break does not need to be justified.</p> +<p>In some cases, you need the break to be justified. Command <code>\linebreak</code> does that. Use with caution, since lines earlier in the paragraph will not reflow! Instead, the broken line will justify by itself, possibly resulting in excessive stretch.</p> +<p>One possible use of <code>\linebreak</code> is when layout places something very short at the calculated break. This often happens in English first-person narration, where the word "I" is common. Then, placing <code>\linebreak</code> just before the "I" is likely to result in better appearance. But you will need to inspect the result, both before and after the manually inserted break.</p> </div> <h4 id="h11.2.5">11.2.5. Widows and Orphans (Clubs)</h4> <div class="d4" id="d11.2.5"> <p class="noindent">The <i>novel</i> class applies virtually no penalty to widows and orphans (clubs). There are good reasons for this.</p> <p>In many other document classes, different pages can have different numbers of lines, to avoid widows and orphans. This is accomplished by stretching inter-line or inter-paragraph spaces. That kind of strategy is unacceptable in a novel, which is expected to have an identical line grid on facing pages.</p> -<p>Also, a novel typically has many short paragraphs, often consisting of dialog. It become problematic to deal with them, without causing excess hyphenation and other unpleasant results.</p> -<p>So, <i>novel</i> lets widows and orphans happen. This is actually common practice for the typesetting of many actual novels by major authors, with major publishers, as seen in the library.</p> +<p>Also, a novel typically has many short paragraphs, often consisting of dialog. It becomes problematic to deal with them, without causing excess hyphenation and other unpleasant results.</p> +<p>So, <i>novel</i> lets widows and orphans happen. This is common practice for the typesetting of many actual novels by major authors, with major publishers, as seen in the library.</p> <p>But do inspect your own work for widows and (especially) orphans that result in poor typesetting. Usually widows are not the problem, since they fill a line at the end of a page. But an orphan may only occupy a small part of its line at the top of a page, possibly as little as one word. There are also "paragraph orphans," where the final word (maybe even just a hyphenated syllable) is on a line by itself.</p> -<p>Sinc you are writing your own book, you have the liberty to edit your text, so that problematic paragraph layouts disappear. Really, that's the only way to do it. TeX cannot read your mind.</p> +<p>Since you are writing your own book, you have the liberty to edit your text, so that problematic paragraph layouts disappear. Really, that's the only way to do it. TeX cannot read your mind.</p> </div> </div><!-- end class="d3" --> @@ -2569,14 +2601,14 @@ Unfortunately, novelists of that era had so little to write about, or they would <h2 id="h12">12. Footnotes, Endnotes, Back Matter</h2> <div class="d2" id="d12"> <p class="noindent">The <i>novel</i> class has <em>limited</em> support for footnotes, because they are rarely used in fiction. Nevertheless, I have seen them. The notes may be factual or imaginary.</p> -<p>If there are more than a handful of notes, then use endnotes to avoid a constant disruption of the text flow. You may use both footnores and endnotes.</p> -<p>Footnotes and endnotes use superscripts at the appropriate point in the main text. The actual footnote or endnote begins with ordinary text, not a superscript. You can control the appearance of superscripts using \SetMarkers and related commands. See the section regarding fonts, earlier in this document.</p> +<p>If there are more than a handful of notes, then use endnotes to avoid a constant disruption of the text flow. You may use both footnotes and endnotes.</p> +<p>Footnotes and endnotes use superscripts at the appropriate point in the main text. The actual footnote or endnote begins with ordinary text, not a superscript. You can control the appearance of superscripts using <code>\SetMarkers</code> and related commands. See the section regarding fonts, earlier in this document.</p> <h3 id="h12.1">12.1 Footnotes</h3> <div class="d3" id="d12.1"> <p>Footnotes appear at the bottom of the page where they are placed. There is no option to accumulate them to another location. Very long footnotes might straddle pages, but that situation is uncommon in fiction (and not within your control).</p> <p class="code"><code>\footnote[<em>option</em>]{<em>text</em>}</code></p> -<p>The \footnote command places a superscript "marker" at the place where the command is written. The included text is written at the bottom of the page, beneath a short line that separates it from the main text. The footnote text is at smaller size and line skip, and has the same marker placed before it (but not as superscript). All of this is automatic.</p> +<p>The <code>\footnote</code> command places a superscript "marker" at the place where the command is written. The included text is written at the bottom of the page, beneath a short line that separates it from the main text. The footnote text is at smaller size and line skip, and has the same marker placed before it (but not as superscript). All of this is automatic.</p> <p>You may, if necessary, apply some style to the footnote text. For example, if you are referring to another work, its title might be in italics.</p> <p>Normally, no option is used. If you use option <i>0</i> (zero) then no marker will appear in the main text, and the footnote text will also appear without a marker. The count of markers is not incremented. This applies whether the markers are numbers or symbols.</p> <p>• Trick: If you are using footnote numbers, but wish to place a special footnote using a symbol, you can do it manually. For example:</p> @@ -2586,17 +2618,17 @@ Unfortunately, novelists of that era had so little to write about, or they would <h3 id="h12.2">12.2 Endnotes</h3> <div class="d3" id="d12.2"> -<p class="noindent">Endnotes are sometimes used in fiction. For example, J.R.R. Tolkien's <i>Lord of the Rings</i> trilogy has a large number of them.</p> +<p class="noindent">Endnotes are sometimes used in fiction. In general, the endnotes are also fictional.</p> <p>You may use both footnotes and endnotes, if you wish. However, if endnotes are used, then footnotes must be marked by symbols, rather than by numbers, to avoid confusion. The counts for endnotes and footnotes are independent.</p> -<h4 id="h12.2.1">12.2.1 \endnote, \ResetEndnote, \memo{}</h4> +<h4 id="h12.2.1">12.2.1 <code>\endnote</code>, <code>\ResetEndnote</code>, <code>\memo{}</code></h4> <div class="d4" id="d12.2.1"> -<p class="noindent">The \endnote command inserts a numerical superscript in the text. A running count of the numbers is automatically updated. This command does nothing else.</p> -<p>The endnote numbers run continuously through the text, without reset. If you wish to reset the count (perhaps at new chapters), you have to do it manually, using \ResetEndnote.</p> -<p>When you use \endnote, there is no provision for the actual note. The <i>novel</i> class does not know, and does not care, whether or not you actually write the endnote later. If you wish to write a reminder to yourself, about why you put an endnote marker there, use \memo{<i>text</i>}. The argument of \memo{} will not be printed, and will not be remembered for later use. Note that \memo is not like the percent % comment, because anything following \memo{} will be honored.</p> +<p class="noindent">The <code>\endnote</code> command inserts a numerical superscript in the text. A running count of the numbers is automatically updated. This command does nothing else.</p> +<p>The endnote numbers run continuously through the text, without reset. If you wish to reset the count (perhaps at new chapters), you have to do it manually, using <code>\ResetEndnote</code>.</p> +<p>When you use <code>\endnote</code>, there is no provision for the actual note. The <i>novel</i> class does not know, and does not care, whether or not you actually write the endnote later. If you wish to write a reminder to yourself, about why you put an endnote marker there, use <code>\memo{<i>text</i>}</code>. The argument of <code>\memo</code> will not be printed, and will not be remembered for later use. Note that <code>\memo</code> is not like the percent <code>%</code> comment, because anything following <code>\memo</code> will be honored.</p> </div> -<h4 id="h12.2.2">12.2.2 \endnotetext{<em>number</em>}{<em>text</em>}</h4> +<h4 id="h12.2.2">12.2.2 <code>\endnotetext{<em>number</em>}{<em>text</em>}</code></h4> <div class="d4" id="d12.2.2"> <p class="noindent">The <code>\endnotetext</code> command is a simple way of styling endnotes. You do not have to use it, if you have your own method. These may be placed per-chapter, or at the final end. The <i>novel</i> class does not keep track of them.</p> <p>The first argument is usually the endnote number. A period and following space will automatically be added, so that the text of the note is block-indented. You may use <code>\emph{<em>number</em>}</code> if you prefer the number to be in italics.</p> @@ -2617,11 +2649,15 @@ Unfortunately, novelists of that era had so little to write about, or they would <h3 id="h12.3">12.3 Regarding Back Matter</h3> <div class="d3" id="d12.3"> -<p class="noindent">TeX has a do-nothing \backmatter command. No different with <i>novel</i> class, from version 1.40. Earlier versions tried to do something with that command, but the tactic was abandoned.</p> +<p class="noindent">In <i>novel</i>, <code>\backmatter</code> command is an alias for <code>\cleartorecto</code>. It does nothing else. In particular, it does not change the page number style, or reset the page number. Back matter is rare nowadays, in fiction and nonfiction alike.</p> <p>Anything following the end of your story is still treated as main matter. Epilogue, Conclusion, Endnotes, Appendix, whatever: all of them continue the Arabic page numbers. This is recommended by <i>CMoS</i> and is also best on a practical basis. For example, J.R.R. Tolkien's <i>The Return of the King</i> has very extensive post-story material, such as a history of the Elves, some linguistics, and notes. Nevertheless, the page numbering is Arabic, continued from the main story without reset.</p> <p>Of course, you may add anything you wish, after your story ends. Call it what you wish. Such material must begin recto, and may have its own cover page.</p> <p>If your book is available in both hardcover and softcover, then the dust jacket of the hardcover may have "About the Author" on its interior flap. This information is not present on the soft cover, which has no flap. You may, if you wish, place it as an About the Author section, recto, after your story ends. However, I sugest that such material is better on a web site, where you can change or remove it.</p> -<p>The last command of the document body must be \cleartoend. This ensures that the final page will be a blank verso, if necessary preceded by a blank recto.</p> +</div><!-- end class="d3" --> + +<h3 id="h12.4">12.4 <code>\cleartoend</code></h3> +<div class="d3" id="d12.4"> +<p class="noindent">The last command of the document body must be <code>\cleartoend</code>. This ensures that the final page will be a blank verso, if necessary preceded by a blank recto.</p> </div><!-- end class="d3" --> @@ -2656,10 +2692,9 @@ Unfortunately, novelists of that era had so little to write about, or they would <h3 id="h13.2">13.2. Get Some Software</h3> <div class="d3" id="12.2"> -<p class="noindent">Get the 238% total ink limit color profile from <a href="http://www.newselfpublishing.com/TotalInkLimit.html" rel="external" target="new">Aaron Shepard</a>. This does the magic of ensuring that you comply with the 240% ink limit (the profile provides a little headroom, which seems useful). It can also be used for softproofing, if you know how to do that. This is not the only possible profile, but it seems to me that it is the best of several available. A good alternative s from <a class="external" rel="external" target="new" href="https://indesignsecrets.com/force-color-images-cmyk-240-ink-limit.php">David Blatner</a> (find "Here's a simple one") on that page).</p> +<p class="noindent">Get the 238% total ink limit color profile from <a href="http://www.newselfpublishing.com/TotalInkLimit.html" rel="external" target="new">Aaron Shepard</a>. This does the magic of ensuring that you comply with the 240% ink limit (the profile provides a little headroom, which seems useful). It can also be used for softproofing, if you know how to do that. This is not the only possible profile, but it seems to me that it is the best of several available. A good alternative s from <a class="external" rel="external" target="new" href="https://indesignsecrets.com/force-color-images-cmyk-240-ink-limit.php">David Blatner</a> (find "Here's a simple one" on that page).</p> <p>Included in the <i>novel</i> documentation <i>extras</i> folder is an open-source color profile for sRGB (file <i>srgb.icc</i>). There is also an open-source Equivalent to AdobeRGB (file <i>crgb.icc</i>). You will be using these when you convert your PNG image to a JPG in CMYK color space. I can think of no technical need to use the "real" profiles that may be lurking somewhere in your computer. These profiles are cross-platform.</p> <p>Get GraphicsMagick or ImageMagick. On Linux, you can install it via your system package manager. On Windows, get GraphicsMagick Q16 binaries for your system (32 or 64 bit) from <a href="https://sourceforge.net/projects/graphicsmagick/files/graphicsmagick-binaries/" rel="external" target="new">SourceForge</a>. I am told that versions for Mac are available via homebrew and macports, but again, I do not have a Mac, so I cannot check that. Or, get ImageMagick Q16 for various platforms from <a href="https://www.imagemagick.org/script/download.php" rel="external" target="new">here</a>.</p> -<p>You might or might not (probably will) need an sRGB color profile, because that's likely to be the default for images not prepared in a color-managed workflow. Your system has one, somewhere. Copy it, and rename the copy as "srgb.icc" (note extension icc, if necessary changed from icm).</p> </div><!-- end class="d3" --> <h3 id="h13.3">13.3. Convert Your Image to CMYK at 240% (or less) Ink Limit</h3> @@ -2710,13 +2745,13 @@ Unfortunately, novelists of that era had so little to write about, or they would <div class="d3" id="12.4"> <p class="noindent">Up to now, you did not need TeX. Now you do. Be sure that you have a working TeX installation, with the <em>novel</em> document class package.</p> <p>In folder (your TeX root)/doc/lualatex/novel/extras you will find file "novel-cover-template.tex". Place a copy in the same working folder as your image, and modify it as needed.</p> -<p><code>\SetMediaSize</code> refers to the full size of the image, with units (usually in). This includes the bleed box. For the example image, <code>\SetMediaSize{11.87in}{8.75in}</code>.</p> -<p><code>\SetTrimSize</code> refers to the trimmed image, without bleed. For the example image, <code>\SetTrimSize{11.62in}{8.5in}</code>.</p> -<p><code>\SetPDFX[CGATSTR001]{X-1a:2001}</code> will get you "Us Web Coated SWOP v2" output intent (most common the USA), and PDF/X-1a:2001 compliance. The Output Intent *.icc color profile will NOT be embedded, because this is almost always the way that print services want it. The PDF contains a code identifying the intent, so there is no need to embed the color profile (and disadvantages to embedding it). In the unlikely event that they demand the Output Intent color profile embedded, put an asterisk on the command.</p> +<p><code>\SetMediaSize</code> refers to the full size of the image, with units (usually in). This includes the bleed box. For example, <code>\SetMediaSize{11.87in}{8.75in}</code>.</p> +<p><code>\SetTrimSize</code> refers to the trimmed image, without bleed. For example, <code>\SetTrimSize{11.62in}{8.5in}</code>.</p> +<p><code>\SetPDFX[CGATSTR001]{X-1a:2001}</code> will get you "US Web Coated SWOP v2" output intent (most common the USA), and PDF/X-1a:2001 compliance. The Output Intent *.icc color profile will NOT be embedded, because this is almost always the way that print services want it. The PDF contains a code identifying the intent, so there is no need to embed the color profile (and disadvantages to embedding it). In the unlikely event that they demand the Output Intent color profile embedded, put an asterisk on the command.</p> <p>For compliance you need to use <code>\SetTitle</code>. The title for this file might not be the title of your book, because this file isn't your book. Ask you print service what they want. Same with <code>\SetAuthor</code>.</p> <p>You can use <code>\SetApplication</code> and <code>\SetProducer</code> to change internal identifiers. Don't use these unless you have a reason.</p> <p><code>\SetCoverImage</code> is self-explanatory. Must have file extension jpg, jpeg, JPG, or JPEG. Must be CMYK. Note that TeX cannot verify whether the image is in correct color space. It will compile, even if the image is wrong. Beware!</p> -<p>Do not attempt to write anything between <code>\begin{document}</code> and <code>\end{document}</code>. If you erroneously put some text there, the document will probably compile, and it may even be a valid PDF/X file. However, the resulting text color will almost surely be wrong. If so, the problem will be detected when you submit your file (wrong ink limit or color space). However, this is not a fundamental limit. It is possible to place TeX text over the image, but this documentation (as of version 1.32) does not show you how to do that.</p> +<p>Do not attempt to write anything between <code>\begin{document}</code> and <code>\end{document}</code>. If you erroneously put some text there, the document will probably compile, and it may even be a valid PDF/X file. However, the resulting text color will almost surely be wrong. If so, the problem will be detected when you submit your file (wrong ink limit or color space).</p> <p>Compiling may take a little longer than expected. If your TeX system opens a PDF viewer automatically, the image might be missing (or partial) until a few seconds after the viewer opens. Be patient. The file size is large.</p> </div><!-- end class="d3" --> @@ -2782,13 +2817,13 @@ Unfortunately, novelists of that era had so little to write about, or they would <p><img class="floatright" src="html-resources/smythsewn.png" width="177" height="141" alt="perfect binding"/> The best hardcovers, suitable for library use, are made using the <b>Smyth Sewing</b> process. A Smyth Sewn book has signatures of (typically) 12 or 16 folios. But instead of removing the creases after folding, each signature is sewn through its crease using strong thread, onto a durable spine material. The pages will remain attached, even with hard usage. If the spine material is sufficiently flexible, then the book will lie flat when opened.</p> <p>Be sure to ask about spine flexibility. The most flexible methods have a soft, curved spine, and are best suited to thick novels. There is also a variety that has a square (flat) spine, which will not quite lie flat when opened. Square-spine Smyth Sewn books seem to be the fashion for documenting intellectual property.</p> <p>If a major publisher is producing a book that is sure to be ordered by many libraries, due to its author's popularity or maybe a movie tie-in, then it is likely to be released as a Smyth Sewn hardcover. That's because the production method is affordable in quantity. But on a P.O.D. basis, it is a significant expense.</p> -<p>Note that it is possible to retroactively add a hard cover to what was originally a Perfect Binding softcover book. Depending on the technology, the result may be more durable, or not. But it will still be nothing like a Smyth Sewn library binding, because that has to be done at original manufacture. If you want a couple of Smyth Sewn copies for private use (your good children inherit the ranch, the bad ones inherit your books) then there are businesses that can build them, at fabulous cost, from your original PDF (minus its ISBN). If you need to change the Trim Size or margins to accomodate the different technology, then <i>novel</i> can help you. See the \ReworkTrimSize and \ReworkMargins commands.</p> +<p>Note that it is possible to retroactively add a hard cover to what was originally a Perfect Binding softcover book. Depending on the technology, the result may be more durable, or not. But it will still be nothing like a Smyth Sewn library binding, because that has to be done at original manufacture. If you want a couple of Smyth Sewn copies for private use (your good children inherit the ranch, the bad ones inherit your books) then there are businesses that can build them, at fabulous cost, from your original PDF (minus its ISBN). If you need to change the Trim Size or margins to accomodate the different technology, then <i>novel</i> can help you. See the <code>\ReworkTrimSize</code> and <code>\ReworkMargins</code> commands.</p> </div><!-- end class="d3" --> <h3 id="hA.6">A.6 Paper and Cover Materials</h3> <div class="d3" id="dA.6"> <p class="noindent">The interior paper may be white or "creme" (off-white). White paper is generally used for nonfiction, and must be used if there are interior color images. Creme paper is generally used for fiction. The idea is that white paper creates an air of authority, whereas creme paper is more comfortable for lengthy reading. I agree. I recently read a novel that was (mis-) printed on white paper, and it was hard to read in a bright area. So, for your novel, choose creme paper.</p> -<p>The cover of a Perfect-Binding softcover book may be produced with a glossy or a matte finish. The fashion is to use glossy for nonfiction, matte for fiction. Again, the idea is authority versus comfort. But you may choose what you wish. "Instant Best-Seller" paperbacks mass-market publishers often have an embossed teture, and maybe even metal foil. In the print-on-demand market, forget it. Don't even think about it.</p> +<p>The cover of a Perfect-Binding softcover book may be produced with a glossy or a matte finish. The fashion is to use glossy for nonfiction, matte for fiction. Again, the idea is authority versus comfort. But you may choose what you wish. "Instant Best-Seller" mass-market paperbacks often have an embossed texture, and maybe even metal foil. In the print-on-demand market, forget it. Don't even think about it.</p> <p>If you do request a hardcover edition, then it may or may not have a dust jacket (costs extra). The general rule is that books for libraries have a dust jacket, which will be encased in plastic by the library. Books for documentation generally have no dust jacket, with the title and other info embossed in the cover material, for permanance.</p> </div><!-- end class="d3" --> @@ -2806,7 +2841,7 @@ Unfortunately, novelists of that era had so little to write about, or they would <p class="noindent1">You can use six pages, provided that:</p> <p class="overhang">• Your front matter does not contain material written by someone else (such as a Foreword), no matter how short. Exception: You may use an Epigraph.</p> <p class="overhang">• Your front matter contains at most one of the following, limited to a single page: Dedication, Epigraph, Table of Contents, Acknowledgements, Author's Note, Map.</p> -<p class="noindent2">If both of the above points apply, then your front matter is organized as follows. Be sure that your document begins with the \frontmatter command, and that each page begins with \thispagestyle{empty} and ends with \clearpage.</p> +<p class="noindent2">If both of the above points apply, then your front matter is organized as follows. Be sure that your document begins with the <code>\frontmatter</code> command, and that each page begins with <code>\thispagestyle{empty}</code> and ends with <code>\clearpage</code>.</p> <h3 id="hB.1">B.1 Half-Title to Copyright</h3> <div class="d3" id="dB.1"> @@ -2866,7 +2901,7 @@ Unfortunately, novelists of that era had so little to write about, or they would <p class="noindent1">Since the <i>novel</i> class uses only <i>LuaLaTeX</i> and <i>fontspec</i> with utf-8 encoding, you may use any Open Type or TrueType font, subject to licensing. You are not limited to TeX fonts.</p> <p>Many TeX fonts are only available in older Type 1 format (PostScript) or even as bitmap metafonts. <i>Do not use them.</i></p> <p>In some other cases, a TeX font package provides both the older format, and a newer Open Type (*.otf or *.ttf) format. The different formats will have different font names. Sometimes the difference is very slight. Carefully look at the font name for the Open Type format. Remember that most on-line discussions will refer to the older fonts, simply because they have been around longer. For example: <i>Linux Biolinum</i> is a sans-serif font available via TeX as a PostScript font. But <i>Linux Biolinum O</i> (note the O) is an Open Type font. If you need this font, then call for <i>Linux Biolinum O</i>, not simply <i>Linux Biolinum</i>.</p> -<p><b>Important:</b> Do not attempt to load a font by the \RequirePackage or \usepackage commands. Instead, if you choose to use fonts other than the defaults, load them via the font setting commands described in this documentation. If you attempt to load a font the wrong way, you may get an error message.</p> +<p><b>Important:</b> Do not attempt to load a font by the <code>\RequirePackage</code> or <code>\usepackage</code> commands. Instead, if you choose to use fonts other than the defaults, load them via the font setting commands described in this documentation. If you attempt to load a font the wrong way, you may get an error message.</p> <h3 id="hC.1">C.1 Licensing Issues</h3> <div class="d3" id="dC.1"> @@ -2876,7 +2911,7 @@ Unfortunately, novelists of that era had so little to write about, or they would <p>You have numerous fonts already installed in your operating system, and perhaps others that came bundled with a particular application. If you intend to use those fonts, carefully read their licenses. It is often the case that fonts bundled with an application may <em>only</em> be used for documents created within, or processed by, that application. Or, the fonts may be OK to use for printing directly by your own home printer, but not for embedding in a PDF that will go to a commercial printer.</p> <p>Although it does not pertain to TeX, another issue can arise if you later publish an ebook version. Fonts licensed for printing are often not licensed for an ebook. Indeed, the ebook distributor may ban them.</p> <p>Always look for a Copyright notice, which can be identified with a particular person or organization. Copyright is good! It means that someone is claiming authorship of the font software. Only the Copyright owner has the right to give the font away for free, or license it to you after payment (often through an intermediary).</p> -<p>If you prefer free fonts, the most widely accepted license is the <em>SIL Open Font License</em>. This allows you to use the font for commercial purposes, embed it in PDF, modify it to suit your needs (if you change the font name), and even re-distribute the modifications. The recommended default <i>Libertinus</i> bears this font license.</p> +<p>If you prefer free fonts, the most widely accepted license is the <em>SIL Open Font License</em>. This allows you to use the font for commercial purposes, embed it in PDF, modify it to suit your needs (if you change the font name), and even re-distribute the modifications. The recommended default <i>Libertinus Serif</i> bears this font license.</p> </div><!-- end class="d3" --> <h3 id="hC.2">C.2 Technical Issues</h3> @@ -2906,7 +2941,7 @@ Unfortunately, novelists of that era had so little to write about, or they would <p class="noindent">The <i>gamut</i>, or range of available colors, is not the same for your computer monitor as it is for a printer. Obviously that depends on the technology of your monitor, and the technology of the printer. By and large, a good CMYK commercial printer can provide blue-greens that your monitor cannot accurately display. And, your monitor can display purple-violet colors that cannot accurately be printed. The monitor's advantage in purple-violet largely disappears for inexpensive LCD flat panels, which is what most of us have.</p> <p>However, the full CMYK gamut is only realized when each ink channel can act independently. That is, each spot on the paper must be able to retain as much as a full dose of each ink. At 0%-100% ink per channel, a spot of paper would have to hold up to 400% ink. For a variety of reasons, most printing technologies cannot apply that much ink. Or rather, if they did try to apply that much, the resulting print might smear, fail to dry, lift off, or soak through to the opposite side of the paper. Subsequent lamination might fail to adhere.</p> <p>Quality books and magazines, using coated paper, can typically hold 300%-360% ink (the technical name is TAC, Total Area Coverage). However, the color cover of a print-on-demand book might be produced by a method that holds less ink. The operative word is "might." Common P.O.D. printers are industrial-strength inkjet machines, capable of very high quality when used with suitable paper. However, the print job will be sent out to any number of different print shops, who may use other technology. Therefore, P.O.D. services may require that the color gamut be limited to those printable by a "lowest common denominator" process. One widely-used "lowest common denominator" is 240% ink limit.</p> -<p>At 240% ink limit, brightly colored areas are generally unaffected. Deep, rich colors cannot be produced, since they would require too much ink. You will be required to provide an image with colors that fit within the ink limit, or the P.O.D. service may quietly do it for you.</p> +<p>At 240% ink limit, brightly colored areas are generally unaffected. Deep, rich colors cannot be produced, since they would require too much ink. You will be required to provide an image with colors that fit within the ink limit, or the P.O.D. service may quietly alter your image for you.</p> <p>Print simulation, or <i>softproofing</i>, is a method of viewing an image on your computer, "as if it were printed" to some standard. GIMP can do this, as long as you provide the necessary *.icc color profile for the printer. Then you can decide whether or not the result is acceptable. The actual CMYK image is produced by the methods described in <a href="#h13">Chapter 13</a>, above.</p> <h3 id="hD.1">D.1. Example: Bright Colors Preserved</h3> @@ -2923,7 +2958,7 @@ Unfortunately, novelists of that era had so little to write about, or they would <h3 id="hD.3">D.3. Example: Dark, Rich Colors Lost</h3> <div class="d3" id="dD.3"> -<p>The biggest problem occurs when the artwork is naturally dark. That might occur in night scenes, or with dark-skinned humans. For copyright reasons I cannot show you the original image by Hyacinthe Rigaud, on display in a European museum. But if it is reduced to a map of 256 colors (as with GIF images), you can see the effect. The original, at left, has many rich browns and reddish-browns. When softproofed, those become nearly gray. The original image still is attractive when softproofed, but is colors might be surprising if you were unaware of the ink limit effect.</p> +<p>The biggest problem occurs when the artwork is naturally dark. That might occur in night scenes, or with dark-skinned humans. For copyright reasons I cannot show you the original image by Hyacinthe Rigaud, on display in a European museum. But if it is reduced to a map of 256 colors (as with GIF images), you can see the effect. The original, at left, has many rich browns and reddish-browns. When softproofed, those become nearly gray. The original image still is attractive when softproofed, but its muted dark colors might be surprising if you were unaware of the ink limit effect.</p> <p class="centerimg"><img src="html-resources/colormap-brown.jpg" width="674" height="305" title="Medieval Painting, monitor and softproof" alt="Dark color map, monitor and softproof"/></p> <p>You might wonder why the ink limit caused rich browns to appear <i>darker</i>. That's because a blend of yellow, magenta, and black (with too much ink) was changed to one with much less yellow and magenta, but more black (and not too much ink).</p> </div><!-- end class="d3" --> @@ -2998,14 +3033,14 @@ Unfortunately, novelists of that era had so little to write about, or they would <p class="overhang"><code>\SetSansFont[features]{font family}</code> Advanced. Default: Libertinus Sans. Alternate: Linux Biolinum O. Last Choice: Latin Modern Sans.</p> <p class="overhang"><code>\SetMonoFont[features]{font family}</code> Advanced. Default: Libertinus Mono. Alternate: Linux Libertine Mono O. Last Choice: Latin Modern Mono.</p> <p class="overhang"><code>\NewFontFamily\<i>yourfontcommand</i>[features]{font family}</code>. Advanced. Uses <i>fontspec</i> notation.</p> -<p class="overhang2">\NewFontFace\<i>yourfontcommand</i>[features]{font}. Advanced. Uses <i>fontspec</i> notation.</p> +<p class="overhang"><code>\NewFontFace\<i>yourfontcommand</i>[features]{font}</code>. Advanced. Uses <i>fontspec</i> notation.</p> </div> <h4 id="hE.1.5">E.1.5 Other Preamble Configuration</h4> <div class="d4" id="dE.1.5"> <p class="noindent2">These commands perform miscellaneous setup.</p> <p class="overhang"><code>\SetEmblems{<em>verso</em>}{<em>recto</em>}</code> Advanced. Default: empty. Applies decoration near page number, only for selected header/footer styles.</p> -<p class="overhang"><code>\SetPageNumberStyle{<em>code using \thepage</em>}</code> Advanced. Default: \thepage.</p> +<p class="overhang"><code>\SetPageNumberStyle{<em>code using \thepage</em>}</code> Advanced. Default: <code>\thepage</code>.</p> <p class="overhang"><code>\SetLooseHead{number}</code> Advanced. Default: 50. Adjusts header tracking.</p> <p class="overhang"><code>\SetChapterStart{<em>choice</em>}</code> Advanced. Default: footer (if present).</p> <p class="overhang"><code>\SetIndentAfterScenebreak</code> Advanced. Default: no indent after scenebreak.</p> @@ -3017,13 +3052,13 @@ Unfortunately, novelists of that era had so little to write about, or they would <h3 id="hE.2">E.2 Command Summary: Document Body</h3> <div class="d3" id="dE.2"> -<p class="noindent">Note that standard font size commands, such as \small and \Large, are disabled.</p> +<p class="noindent">Note that standard font size commands, such as <code>\small</code> and <code>\Large</code>, are disabled.</p> <h4 id="hE.2.1">E.2.1 Book Divisions</h4> <div class="d4" id="dE.2.1"> <p class="overhang"><code>\frontmatter</code> Page numbering (if shown) is lowercase roman.</p> -<p class="overhang"><code>\mainmatter</code> Page numbering re-starts at 1, and is Arabic.</p> -<p class="noindent">From version 1.40, \backmatter commands are ignored. Page numbering continues in Arbaic, as main matter. This is standard style. If your book must have back matter with different numbering, you must code it yourself.</p> +<p class="overhang"><code>\mainmatter</code> Forces recto, if necessary inserting blank verso. Page numbering re-starts at 1, and is Arabic.</p> +<p class="overhang"><code>\backmatter</code> Forces recto, if necessary inserting blank verso. Page numbering continues Arabic, without reset. If you need something else, you must code it yourself.</p> </div> <h4 id="hE.2.2">E.2.2 Page Management</h4> @@ -3057,7 +3092,7 @@ Unfortunately, novelists of that era had so little to write about, or they would <h4 id="hE.2.4">E.2.4 Scene Breaks and First Lines</h4> <div class="d4" id="dE.2.4"> -<p class="noindent2">Also see Preamble command \SetIndentAfterScenebreak.</p> +<p class="noindent2">Also see Preamble command <code>\SetIndentAfterScenebreak</code>.</p> <p class="overhang"><code>\QuickChapter[<em>dash size</em>]{<em>chapter title</em>}</code> Chapters without page breaks.</p> <p class="overhang"><code>\scenebreak</code> Skips a line, gap is blank.</p> <p class="overhang"><code>\sceneline</code> Skips a line, gap has centered long dash.</p> @@ -3068,10 +3103,10 @@ Unfortunately, novelists of that era had so little to write about, or they would <h4 id="hE.2.5">E.2.5 Inline Text Effects</h4> <div class="d4" id="dE.2.5"> <p class="noindent2">Note that standard LaTeX font size commands, such as <code>\small</code> and <code>\Large</code>, have no effect.</p> -<p class="overhang"><code>\charscale[<em>scale,x,y</em>]{<em>text</em>}</code> Scales and moves text. Single line. See also \parascale environment.</p> +<p class="overhang"><code>\charscale[<em>scale,x,y</em>]{<em>text</em>}</code> Scales and moves text. Single line. See also <i>parascale</i> environment.</p> <p class="overhang"><code>{\somefontcommand <em>text</em>}</code> Applies font defined by \somefontcommand to the included text.</p> -<p class="overhang"><code>\forceindent</code> When \indent fails. May be used multiple times.</p> -<p class="overhang"><code>\backindent</code> When \noindent fails. May be used multiple times.</p> +<p class="overhang"><code>\forceindent</code> When <code>\indent</code> fails. May be used multiple times.</p> +<p class="overhang"><code>\backindent</code> When <code>\noindent</code> fails. May be used multiple times.</p> <p class="overhang"><code>\hangindent{<em>text</em>}</code> Place text to the left of the command insertion point.</p> <p class="overhang"><code>\acronym{<em>text</em>}</code> Requires NovelDeco font. Caps become "medium" caps.<p> <p class="overhang"><code>\decoglyph{<em>code</em>}</code> Places decoration from the decofont, by code.</p> @@ -3105,7 +3140,7 @@ Unfortunately, novelists of that era had so little to write about, or they would <h4 id="hE.2.6">E.2.6 Footnotes and Endnotes</h4> <div class="d4" id="dE.2.6"> -<p class="noindent2">See also \realmarker and \fakemarker.</p> +<p class="noindent2">See also <code>\realmarker</code> and <code>\fakemarker</code>.</p> <p class="overhang"><code>\footnote[<em>option</em>]{<em>note text</em>}</code> Marker, with footnote at page bottom.</p> <p class="overhang"><code>\endnote</code> Places marker for subsequent endnote.</p> <p class="overhang"><code>\endnotetext{<em>number</em>}{<em>note text</em>}</code> Text of an endnote.</p> @@ -3135,7 +3170,7 @@ Unfortunately, novelists of that era had so little to write about, or they would <p class="noindent2">These commands may be used, but are likely to interfere with other commands defined by <i>novel</i>, or are likely to disturb the constant baseline grid. Only use them when you are willing to carefully inspect the output at magnification. These are less likely to be problematic when used on a display-only page, such as the book's title page.</p> <p class="overhang"><code>\parbox, \minipage</code> Perhaps use adjustwidth environment.</p> <p class="overhang"><code>center</code> (env.) If used, pay careful attention to line space above/below.</p> -<p class="overhang"><code>\raisebox</code> Use \charscale instead.</p> +<p class="overhang"><code>\raisebox</code> Use <code>\charscale</code> instead.</p> <p class="overhang"><code>\backmatter</code> Avoid in fictional works.</p> </div><!-- end class="d3" --> @@ -3154,16 +3189,16 @@ Unfortunately, novelists of that era had so little to write about, or they would <p>But if you re-size the book and don't knock the margins down, then the text width and height won't be the same. Your text doesn't fit the way it used to. All your lines re-flow, the page breaks are different, and all that work you put into getting just the right appearance must be re-done.</p> <p><em>Oh, nooooo ...</em></p> </div> -<p>Relax. Here is all you need to do: add \ReworkTrimSize{5.06in}{7.81in}. That's it. Your existing margins will be preserved. The font size, and line skip, will be cleverly re-scaled to fit the new dimensions. Paragraphs and pagination are the same as before.</p> +<p>Relax. Here is all you need to do: add <code>\ReworkTrimSize{5.06in}{7.81in}</code>. That's it. Your existing margins will be preserved. The font size, and line skip, will be cleverly re-scaled to fit the new dimensions. Paragraphs and pagination are the same as before.</p> <p>There are two Rework commands available. One changes the Trim Size without changing the margins. The other changes the margins without changing the Trim Size. If you wish to change both Trim Size and margins, you may use both commands.</p> -<h3 id="hF.1">F.1. \ReworkTrimSize{<em>width</em>}{<em>height</em>}</h3> +<h3 id="hF.1">F.1. <code>\ReworkTrimSize{<em>width</em>}{<em>height</em>}</code></h3> <div class="d3" id="dF.1"> <p>This command changes the <em>existing</em> Trim Size. If you do not use the <code>\SetTrimSize</code> command, then the existing Trim Size is the default. But if you do use <code>\SetTrimSize</code>, then you must leave that command as-is, and place <code>\ReworkTrimSize</code> later in the Preamble.</p> <p>If you used <code>\SetMediaSize</code>, you may leave that command as-is, or change it if you wish; the Trim Size does not care.</p> </div><!-- end class="d3" --> -<h3 id="hF.2">F.2. \ReworkMargins{<em>top</em>}{<em>outside</em>}{<em>bottom</em>}{<em>inside</em>}</h3> +<h3 id="hF.2">F.2. <code>\ReworkMargins{<em>top</em>}{<em>outside</em>}{<em>bottom</em>}{<em>inside</em>}</code></h3> <div class="d3" id="dF.2"> <p>This command changes the <em>existing</em> margins. If you do not use the <code>\SetMargins</code> command, then the existing margins are the defaults. But if you do use <code>\SetMargins</code>, then you must leave that command as-is, and place <code>\ReworkMargins</code> later in the Preamble.</p> </div><!-- end class="d3" --> @@ -3190,20 +3225,20 @@ Unfortunately, novelists of that era had so little to write about, or they would <p>• The technique has been tested, but it might not always work. Be sure to inspect the result carefully.</p> <p>• If you use Rework to make a radical size change, then the resulting font size or line skip might be unattractive.</p> <p>• If the reworked pages have one less line than expected (or one more), this is due to roundoff in the calculations. It can usually be fixed by adding or substracting as little as <code>0.001\nbs</code> from the top or bottom rework margin.</p> -<p>• The biggest obstacle occurs when you specify some internal length in terms of absolute units (such as pt). It is always best to use relative units (such as <code>em</code>, or sometimes <code>\nbs</code>), so that they can be scaled along with the text:</p> +<p>• The biggest obstacle occurs when you specify some internal length in terms of absolute units (such as pt). It is always best to use relative units (such as <i>em</i>, or sometimes <code>\nbs</code>), so that they can be scaled along with the text:</p> <p class="code"> Bad: <code>\hspace{6pt}</code> Good: <code>\hspace{0.5em}</code><br/> Bad: <code>\kern1pt</code> Good: <code>\kern.08em</code><br/> Bad: <code>\vspace{0.5in}</code> Good: <code>\vspace{2.4\nbs}</code> </p> -<p>• When you use <code>\Rework</code>, images are <em>not</em> scaled. Thus, they will have a different relationship to the surrounding text than they did before. In many cases, this is not a problem. However, an un-scaled image may disrupt the flow of text, or the number of lines in a page, or overlap text that was previously cleared. Look in the log file for an Alert message, which suggests an appropriate image scale, depending on how an image was placed. Problem areas can often be fixed be scaling the related image(s) in an external graphics program (see <a href="noveldocs-08-images.html#a8.3.3">Page 8</a>) then re-compiling with the scaled image(s).</p> +<p>• When you use Rework, images are <em>not</em> scaled. Thus, they will have a different relationship to the surrounding text than they did before. In many cases, this is not a problem. However, an un-scaled image may disrupt the flow of text, or the number of lines in a page, or overlap text that was previously cleared. Look in the log file for an Alert message, which suggests an appropriate image scale, depending on how an image was placed. Problem areas can often be fixed be scaling the related image(s) in an external graphics program (see <a href="noveldocs-08-images.html#a8.3.3">Page 8</a>) then re-compiling with the scaled image(s).</p> <p>• Note that you may see the Alert whether or not there are problem images, so scaling images will not make the Alert go away. It is a friendly message.</p> <div style="clear:both"></div> </div><!-- end class="d3" --> -<h3 id="hF.5">F.5. Scaling Images after \Rework.</h3> +<h3 id="hF.5">F.5. Scaling Images after <code>\Rework</code>.</h3> <div class="d3" id="dF.5"> -<p>When you use one or both of the \Rework commands, the font size and/or the baselineskip will change. However, it does not scale images. In many cases, there is no problem. But in some cases, an un-scaled image will disrupt the previous flow of text or pagination. If you look in the log file, you will see an Alert message, which suggests (only suggests) appropriate values for scaling problem images, depending on whether they are placed inline or block. Then, you should re-work the image in an external image editor. When you scale the image, be sure that the revised version is at the correct resolution of 300dpi or 600dpi, or whatever is necessary.</p> +<p>When you use one or both of the Rework commands, the font size and/or the baselineskip will change. However, it does not scale images. In many cases, there is no problem. But in some cases, an un-scaled image will disrupt the previous flow of text or pagination. If you look in the log file, you will see an Alert message, which suggests (only suggests) appropriate values for scaling problem images, depending on whether they are placed inline or block. Then, you should re-work the image in an external image editor. When you scale the image, be sure that the revised version is at the correct resolution of 300dpi or 600dpi, or whatever is necessary.</p> <p>It is best to go back to your copy of the original artwork, before you exported it to <i>png</i> or <i>jpg</i>. But what if you do not have anything but the 1-bit or grayscale images that you created earlier? Then do this (in GIMP):</p> <p>(1) If the image is 1-bit, change to Color>Mode grayscale.</p> <p>(2) Use Image>Scale Image to get new dimensions, at 600 or 300 pixels per inch. Careful: Sometimes when you change size, it auto-changes resolution, or vice-versa. Click back and forth in the dialog box, to ensure that both the dimensions and resolution are correct. Use Cubic interpolation or better.</p> @@ -3212,7 +3247,7 @@ Bad: <code>\vspace{0.5in}</code> Good: <code>\vspace{2.4\nbs}</code> <p>(5) Image>Flatten.</p> <p>(6) If the image is to be 1-bit line art, then use GaphicsMagick or ImageMagick as described in section 8.3.1.</p> <p>(7) Export as png, then use GraphicsMagick or Image Magick as described in section 8.3.2.</p> -<p>The above does not take too much time, and will provide superior results. Note that when an image is placed within text, the calculation for text positioning is different than the calculation for image positioning. It is possible (although unlikely) that a \Rework situation will cause an unexpected page break, due to roundoff error in the placement of the final line on a page. This can be fixed by subtracting (or, in some cases, adding) as little as <i>\vspace{-0.001\nbs}</i> before or after the re-scaled image.</p> +<p>The above does not take too much time, and will provide superior results. Note that when an image is placed within text, the calculation for text positioning is different than the calculation for image positioning. It is possible (although unlikely) that a <code>\Rework</code> situation will cause an unexpected page break, due to roundoff error in the placement of the final line on a page. This can be fixed by subtracting (or, in some cases, adding) as little as <code>\vspace{-0.001\nbs}</code> before or after the re-scaled image.</p> </div><!-- end class="d3" --> diff --git a/Master/texmf-dist/doc/lualatex/novel/novel.tex b/Master/texmf-dist/doc/lualatex/novel/novel.tex index bea53360680..d105019f726 100644 --- a/Master/texmf-dist/doc/lualatex/novel/novel.tex +++ b/Master/texmf-dist/doc/lualatex/novel/novel.tex @@ -3,7 +3,7 @@ % % SOURCE CODE FOR FILE novel.pdf, the cover info % for novel document class. -\documentclass{novel} % v. 1.40.1 or later +\documentclass{novel} % v. 1.40.2 or later % Almost all settings are defaults. \SetHeadFootStyle{3} \SetTitle{Novel Document Class} % only footer, with page number diff --git a/Master/texmf-dist/tex/lualatex/novel/novel-CGATSTR001.clo b/Master/texmf-dist/tex/lualatex/novel/novel-CGATSTR001.clo index bcc426d8ff3..ea0df257a5f 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel-CGATSTR001.clo +++ b/Master/texmf-dist/tex/lualatex/novel/novel-CGATSTR001.clo @@ -1,4 +1,4 @@ -% Typically used in the USA. Novel file version 1.40.1 +% Typically used in the USA. Novel file version 1.40.2 % The values of the arguments are public industry standards. diff --git a/Master/texmf-dist/tex/lualatex/novel/novel-CalculateLayout.sty b/Master/texmf-dist/tex/lualatex/novel/novel-CalculateLayout.sty index 2c0ea1d66be..eb4455ac5a8 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel-CalculateLayout.sty +++ b/Master/texmf-dist/tex/lualatex/novel/novel-CalculateLayout.sty @@ -12,7 +12,7 @@ %% %% \ProvidesFile{novel-CalculateLayout.sty}% -[2017/09/20 v1.40.1 LaTeX file (layout calculations)] +[2017/09/21 v1.40.2 LaTeX file (layout calculations)] %% %% diff --git a/Master/texmf-dist/tex/lualatex/novel/novel-ChapterScene.sty b/Master/texmf-dist/tex/lualatex/novel/novel-ChapterScene.sty index 40510d2ff84..c4ae78198f1 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel-ChapterScene.sty +++ b/Master/texmf-dist/tex/lualatex/novel/novel-ChapterScene.sty @@ -13,7 +13,7 @@ %% %% \ProvidesFile{novel-ChapterScene.sty}% -[2017/09/20 v1.40.1 LaTeX file (chapter and scene macros)] +[2017/09/21 v1.40.2 LaTeX file (chapter and scene macros)] %% @@ -36,11 +36,26 @@ % \sceneline centers a line, about 1/3 textwidth. % \scenestars centers three widely-spaced asterisks. % Default behavior is \noindent for following paragraph. -% Use \IndentAfterScenebreak in preamble to change this globally. +% Use \AfterScenebreak{indent or noindent} in preamble to change this globally. % Either way, the local behavior can be changed using \indent or \noindent. -% Note: The indent behavior is activated AtBeginDocument. \newif\if@indentAfterScenebreak \@indentAfterScenebreakfalse -\newcommand\IndentAfterScenebreak{\@indentAfterScenebreaktrue} +\newcommand\IndentAfterScenebreak{\@indentAfterScenebreaktrue} % deprected from v. 1.40.2 +\newcommand\AfterScenebreak[1]{% indent or noindent. From v. 1.40.2 + \def\ngoodarg{false} + \ifthenelse{\equal{#1}{indent}}{% + \def\ngoodarg{true} + \@indentAfterScenebreaktrue + }{}% + \ifthenelse{\equal{#1}{noindent}}{% + \def\ngoodarg{true} + \@indentAfterScenebreakfalse + }{}% + \ifthenelse{\equal{\ngoodarg}{false}}{% + \ClassError{novel}{Bad argument for \string\AfterScenebreak\space}% + {\string\AfterScenebreak\space argument must be indent or noindent.}% + }{}% +} +\AfterScenebreak{noindent} % default % \newcommand\scenebreak{\null} % diff --git a/Master/texmf-dist/tex/lualatex/novel/novel-FOGRA39.clo b/Master/texmf-dist/tex/lualatex/novel/novel-FOGRA39.clo index 3c7ca9474cb..e26989efedf 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel-FOGRA39.clo +++ b/Master/texmf-dist/tex/lualatex/novel/novel-FOGRA39.clo @@ -1,4 +1,4 @@ -% Typically used in Europe. Novel file version 1.40.1 +% Typically used in Europe. Novel file version 1.40.2 % The values of the arguments are public industry standards. diff --git a/Master/texmf-dist/tex/lualatex/novel/novel-FileData.sty b/Master/texmf-dist/tex/lualatex/novel/novel-FileData.sty index c67b4aaa52f..4cf07e74183 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel-FileData.sty +++ b/Master/texmf-dist/tex/lualatex/novel/novel-FileData.sty @@ -13,7 +13,7 @@ %% %% \ProvidesFile{novel-FileData.sty}% -[2017/09/20 v1.40.1 LaTeX file (File Data settings)] +[2017/09/21 v1.40.2 LaTeX file (File Data settings)] %% diff --git a/Master/texmf-dist/tex/lualatex/novel/novel-FontDefaults.sty b/Master/texmf-dist/tex/lualatex/novel/novel-FontDefaults.sty index a0b15753e25..632161afcf7 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel-FontDefaults.sty +++ b/Master/texmf-dist/tex/lualatex/novel/novel-FontDefaults.sty @@ -13,7 +13,7 @@ %% %% \ProvidesFile{novel-FontDefaults.sty}% -[2017/09/20 v1.40.1 LaTeX file (default fonts)] +[2017/09/21 v1.40.2 LaTeX file (default fonts)] %% diff --git a/Master/texmf-dist/tex/lualatex/novel/novel-Footnotes.sty b/Master/texmf-dist/tex/lualatex/novel/novel-Footnotes.sty index 9922200212e..f44f6433282 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel-Footnotes.sty +++ b/Master/texmf-dist/tex/lualatex/novel/novel-Footnotes.sty @@ -13,7 +13,7 @@ %% %% \ProvidesFile{novel-Footnotes.sty}% -[2017/09/20 v1.40.1 LaTeX file (commands for footnotes and endnotes)] +[2017/09/21 v1.40.2 LaTeX file (commands for footnotes and endnotes)] %% diff --git a/Master/texmf-dist/tex/lualatex/novel/novel-HeadFootStyles.sty b/Master/texmf-dist/tex/lualatex/novel/novel-HeadFootStyles.sty index 111bac6fac8..65da05fc9ac 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel-HeadFootStyles.sty +++ b/Master/texmf-dist/tex/lualatex/novel/novel-HeadFootStyles.sty @@ -13,7 +13,7 @@ %% %% \ProvidesFile{novel-HeadFootStyles.sty}% -[2017/09/20 v1.40.1 LaTeX file (header and footer styles)] +[2017/09/21 v1.40.2 LaTeX file (header and footer styles)] %% diff --git a/Master/texmf-dist/tex/lualatex/novel/novel-Images.sty b/Master/texmf-dist/tex/lualatex/novel/novel-Images.sty index b7daf49a89c..1fdda5b0dc9 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel-Images.sty +++ b/Master/texmf-dist/tex/lualatex/novel/novel-Images.sty @@ -13,7 +13,7 @@ %% %% \ProvidesFile{novel-Images.sty}% -[2017/09/20 v1.40.1 LaTeX file (image placement)] +[2017/09/21 v1.40.2 LaTeX file (image placement)] %% diff --git a/Master/texmf-dist/tex/lualatex/novel/novel-JC200103.clo b/Master/texmf-dist/tex/lualatex/novel/novel-JC200103.clo index 9b11ba6cc4f..bf507e64478 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel-JC200103.clo +++ b/Master/texmf-dist/tex/lualatex/novel/novel-JC200103.clo @@ -1,4 +1,4 @@ -% Typically used in Japan. Novel file version 1.40.1 +% Typically used in Japan. Novel file version 1.40.2 % The values of the arguments are public industry standards. diff --git a/Master/texmf-dist/tex/lualatex/novel/novel-LayoutSettings.sty b/Master/texmf-dist/tex/lualatex/novel/novel-LayoutSettings.sty index 7040730ac11..834e92238e4 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel-LayoutSettings.sty +++ b/Master/texmf-dist/tex/lualatex/novel/novel-LayoutSettings.sty @@ -13,7 +13,7 @@ %% %% \ProvidesFile{novel-LayoutSettings.sty}% -[2017/09/20 v1.40.1 LaTeX file (layout settings)] +[2017/09/21 v1.40.2 LaTeX file (layout settings)] %% @@ -701,7 +701,9 @@ } % \def\@backmatterns{% - \ClassWarning{novel}{Command \string\backmatter\ ignored. Do not use.^^J}% + \cleartorecto% v. 1.40.2 + \ClassWarning{novel}{Command \string\backmatter\ merely clears to recto.^^J}% v. 1.40.2 +% } % \def\Backmatter{\@ifstar\@Backmatterst\@Backmatterns} % obsolete from v. 1.40. diff --git a/Master/texmf-dist/tex/lualatex/novel/novel-TextMacros.sty b/Master/texmf-dist/tex/lualatex/novel/novel-TextMacros.sty index df7dfdaad7d..00eb0dac67c 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel-TextMacros.sty +++ b/Master/texmf-dist/tex/lualatex/novel/novel-TextMacros.sty @@ -13,7 +13,7 @@ %% %% \ProvidesFile{novel-TextMacros.sty}% -[2017/09/20 v1.40.1 LaTeX file (text macros usable within document body)] +[2017/09/21 v1.40.2 LaTeX file (text macros usable within document body)] %% @@ -41,7 +41,7 @@ % \footnote[]{}, \endnote, \endnotetext[]{} -- See novel-Footnotes.sty. % \thispagestyle{choice} and \dropfolio -- See novel-HeadFootStyles.sty. % \NewVersoHeadText{}, \NewRectoHeadText{} Also \Set and \Renew forms. -- See novel-HeadFootStyles.sty. -% \CreateFeature{substitutions}{feature code} fakes an Open Type feature -- See novel-LayoutSettings.sty. +% \CreateFontFeature{substitutions}{feature code} fakes an Open Type feature -- See novel-LayoutSettings.sty. % \Epigraph[align,scale,width]{text} creates an Epigraph -- See novel-ChapterScene.sty. diff --git a/Master/texmf-dist/tex/lualatex/novel/novel-glyphtounicode.tex b/Master/texmf-dist/tex/lualatex/novel/novel-glyphtounicode.tex index c773d74a706..8c3abf89ca0 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel-glyphtounicode.tex +++ b/Master/texmf-dist/tex/lualatex/novel/novel-glyphtounicode.tex @@ -14,7 +14,7 @@ %% %% \ProvidesFile{novel-gyphtounicode.tex}% -[2017/09/20 v1.40.1 LaTeX file (additional glyph to unicode)] +[2017/09/21 v1.40.2 LaTeX file (additional glyph to unicode)] %% diff --git a/Master/texmf-dist/tex/lualatex/novel/novel-microtype.cfg b/Master/texmf-dist/tex/lualatex/novel/novel-microtype.cfg index 333458827c7..aa5f707f73e 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel-microtype.cfg +++ b/Master/texmf-dist/tex/lualatex/novel/novel-microtype.cfg @@ -19,7 +19,7 @@ %% \NeedsTeXFormat{LaTeX2e} \ProvidesFile{novel-microtype.cfg}% -[2017/09/20 v1.40.1 LaTeX file (microtype configuration file for novel class)] +[2017/09/21 v1.40.2 LaTeX file (microtype configuration file for novel class)] %%% ----------------------------------------------------------------------- %%% FONT SETS diff --git a/Master/texmf-dist/tex/lualatex/novel/novel-pdfx.sty b/Master/texmf-dist/tex/lualatex/novel/novel-pdfx.sty index fd339a3370a..c67aa8cb44c 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel-pdfx.sty +++ b/Master/texmf-dist/tex/lualatex/novel/novel-pdfx.sty @@ -24,7 +24,7 @@ %% \NeedsTeXFormat{LaTeX2e} \ProvidesFile{novel-pdfx.sty}% -[2017/09/20 v1.40.1 LaTeX file (PDF/X support for novel class)] +[2017/09/21 v1.40.2 LaTeX file (PDF/X support for novel class)] % This package supports, and is part of, class `novel'. % No support for anything but LuaLaTeX. diff --git a/Master/texmf-dist/tex/lualatex/novel/novel-xmppacket.sty b/Master/texmf-dist/tex/lualatex/novel/novel-xmppacket.sty index 2a0cbe577ab..555f12c9a57 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel-xmppacket.sty +++ b/Master/texmf-dist/tex/lualatex/novel/novel-xmppacket.sty @@ -22,7 +22,7 @@ %% %% \ProvidesFile{novel-xmppacket.sty}% -[2017/09/20 v1.40.1 LaTeX file (novel XMP packet template)] +[2017/09/21 v1.40.2 LaTeX file (novel XMP packet template)] %% diff --git a/Master/texmf-dist/tex/lualatex/novel/novel.cls b/Master/texmf-dist/tex/lualatex/novel/novel.cls index 9850031ccab..73fb88c79c5 100644 --- a/Master/texmf-dist/tex/lualatex/novel/novel.cls +++ b/Master/texmf-dist/tex/lualatex/novel/novel.cls @@ -17,7 +17,7 @@ %% \NeedsTeXFormat{LaTeX2e}[1995/12/01] % Actually needs LuaLaTeX, at least version 0.95 from TeXLive 2016. -\ProvidesClass{novel}[2017/09/20 v1.40.1 LaTeX document class] +\ProvidesClass{novel}[2017/09/21 v1.40.2 LaTeX document class] %% %% Version 1.40: removed `debug' option (was not useful). Major docs rewrite. |