Categories
LaTeX

Adding TeX4ht to Your LaTeX Book Project

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

TeX4ht Configuration

Here, we will examine the technical details of converting LaTeX to HTML, and how to add that capability to an existing project that does not use the template. If you are already using the configuration set up by the template, you can safely ignore this chapter.

To convert LaTeX to HTML, we need an additional compiler, TeX4ht, which works only with pdfLaTeX. If you are using XeLaTeX (or other LaTeX compilers) for your project, you might run into some problems when switching to pdfLaTeX. You can stay compatible with both compilers by using the conditional \ifxetex statement we have discussed in another article and the book.

On the Overleaf platform, no separate installation for TeX4ht is needed. All you need to do is include it by adding a file named latexmkrc in the main directory (and thus overriding the latexmkrc provided by Overleaf by default) of your project and adding a configuration file.

Figure 1: Build chain using different tools to produce different output formats.

Latexmk ⋅  Latexmk is the build tool Overleaf uses to automatically build your LaTeX project. The configuration file latexmkrc can be used to override build settings and configure compilers for a different output format (like using TeX4ht to generate HTML output in addition to generating a PDF).

First, let us create the latexmkrc file in the main directory of your project and insert this code (depending on your project, if you are not using the template, you might need additional settings from https://www.overleaf.com/help/216-how-does-overleaf-compile-my-project):

 
 
$pdflatex = "rm tikz-cache/*.pdf; pdflatex -shell-escape -synctex=1 %O %S; htlatex %S \"htlatex/htlatex.cfg,MyFonts,NoFonts\" \"\" \"\" -shell-escape > output.txt"; 
END {system(’zip -r allfiles.zip . -x *.cache*’);}  

This creates a hook in the compilation chain of LaTeX (LaTeX calls $pdflatex at the end of the compilation). All this does is clear the cache, call pdflatex before calling htlatex, giving you a PDF output (and compilation of TikZ images) in addition to the HTML output. It also writes the output of the compilation of htlatex to a new file called output.txt to be used for debugging. At the end, it zips all the files of your project into the allfiles.zip for later download. You can download the output files (clicking on the Logs and output files icon at the top of the right window, scrolling all the way down to Other logs & files, and selecting the previously created allfiles.zip).

Converting that HTML file into a real e-book format like MOBI or EPUB takes some extra effort as we need to adjust the settings, take care of the table of contents, add a cover, and optimize our images. This is discussed in another article and the book.

HTML Output Formatting

Unfortunately, TeX4ht cannot do a 1:1 conversion simply because printed books are based on pages while HTML documents and e-books are continuous texts. Also, formatting, spacing, and images are handled differently, so we need to configure this separately. In the listing above, you can see a reference to htlatex.cfg—that is where the TeX4ht configuration resides:

 
 
\Preamble{xhtml} 
 
\Configure{VERSION}{} 
\Configure{DOCTYPE}{\HCode{<!DOCTYPE html>\Hnewline}} 
\Configure{HTML}{\HCode{<html>\Hnewline}}{\HCode{\Hnewline</html>}} 
\Configure{@HEAD}{\HCode{<!-- for beautifying --><link rel="stylesheet" type="text/css" href="site.css" />\Hnewline}} 
 
% Translate \textbf, \textit and \texttt directives into <strong>, <em> and <code> 
\Configure{emph}{\ifvmode\ShowPar\fi\HCode{<em>}}{\HCode{</em>}} 
\Configure{textbf}{\ifvmode\ShowPar\fi\HCode{<strong>}}{\HCode{</strong>}} 
\Configure{textit}{\ifvmode\ShowPar\fi\HCode{<em>}}{\HCode{</em>}} 
\Configure{texttt}{\ifvmode\ShowPar\fi\HCode{<code>}}{\HCode{</code>}} 
\Configure{textsc}{\ifvmode\ShowPar\fi\HCode{<span class="sc">}}{\HCode{</span>}} 
 
% Translate verbatim and lstlisting blocks into <pre> elements 
\ConfigureEnv{verbatim}{\HCode{<pre>}}{\HCode{</pre>}}{}{} 
\ConfigureEnv{lstlisting}{\HCode{<pre>}}{\HCode{</pre>}}{}{} 
\ConfigureEnv{minipage}{\ifvmode\IgnorePar\fi\HCode{<div class="minipage">}}{\ifvmode\IgnorePar\fi\HCode{</div>\Hnewline}}{}{}% 
 
% Do not set ‘indent‘/‘noindent‘ classes on paragraphs 
\Configure{HtmlPar} 
{\EndP\Tg<p>} 
{\EndP\Tg<p>} 
{\HCode{</p>\Hnewline}} 
{\HCode{</p>\Hnewline}} 
\begin{document} 
\EndPreamble  

What the file does is configure the mapping between LaTeX and HTML. If you are familiar with HTML, you see that you can configure the contents of the output HTML file with the htlatex.cfg file. It starts with setting up the HTML header and then configures how individual LaTeX commands (\emph\textbf\textit, …) should be translated into HTML. For example, text formatted in italics (\textit) is translated into HTML by using the emphasis HTML tag (¡em¿). The \HCode command directly inserts HTML commands in the output file and can also be used in the regular LaTeX files. For example, you can use

 
 
\HCode{<hr style="clear: both" />}  

to directly add a vertical line into the HTML output file and thus the e-book.

CSS ⋅  CSS files determine the final design and appearance of a website (or e-book).

Also, in the htlatex.cfg file, the site.css file is referenced. This can be adjusted according to your needs, although in my experience, some of the following settings work nicely for Kindle e-books:

1. You might want to adapt the sizes of the chapter title and section title fonts:

 
 
.chapterHead { font-size: 1.5em; margin-top: 0.83em; margin-bottom: 0.83em; font-weight: bold; text-align: left; } 
.sectionHead { font-size: 1.17em; margin-top: 1em; margin-bottom: 1em; font-weight: bold; } 
.subsectionHead { margin-top: 1.33em; margin-bottom: 1.33em; font-weight: bold; } 
.subsubsectionHead { font-size: 0.83em; margin-top: 1.67em; margin-bottom: 1.67em; font-weight: bold; }  

2. In Kindle e-books, new paragraphs have indents on the first line. If you do not like that, this is the workaround:

 
 
p { margin-top: 1em; margin-bottom: 1em; text-indent: 0.01em; }  

3. One way to highlight a quotation:

 
 
.quotation { margin: 0.25em 0; padding: 0.35em 40px; line-height: 1.45; position: relative; color: #383838; } 
.quotation:before { display: block; padding-left: 10px; content: "\201C"; font-size: 80px; position: absolute; left: -15px; top: -20px; color: #7a7a7a; } 
.quotation cite { color: #999999; font-size: 14px; display: block; margin-top: 5px; } 
.quotation cite:before { content: "\2014 \2009"; } 
div.quotation { width: auto; }  

4. Add support for small capitals:

 
 
.sc { font-variant: small-caps; }  

5. Print description list elements in bold:

 
 
dt.description { font-weight: bold; }  

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

Categories
Publishing

Writing a Series

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

LaTeX documents are projects consisting of an entire folder of files, as opposed to everything being in a single file such as with Word documents. While this initially requires more time to set up, this manner of creating documents shines once your project gets larger—or when you work on multiple books. For example, in my philosophy book series, each book can stand on its own. This means I have to repeat some of the definitions, examples, or explanations from previous books. Sure, you can copy and paste and you are done with it. But managing books over a lifetime requires working in updates. Will you be able to keep the texts identical? Or even for novels, you might want to bring out a new edition of a particular book. Will you manage several different author pages, publisher information pages, advertisement pages, and so on?

As you produce more work, you will have to advance one level and manage your content. LaTeX projects offer the solution for this: you can simply link files of another project to yours and insert them seamlessly. To do this in Overleaf:

  • Select the folder to which you want the file to be linked.
  • Click on the arrow to the right of the folder name and select Upload File and From Another Project.
  • Select the project, and then the file you want to link.

Once linked, you can use the file like a regular file in your project. Linked files show a different icon (a small chain) and you can access them via \input{folder/file}. Of course, you can also link images or any other type of file and use them with the corresponding commands (e.g., \includegraphics{folder/file}).

What are possible candidates for linking? Let us take a look at the template:

  • Whole sections if you create a new version of your book with a different focus.
  • The bibliography—imagine having a single library for all your projects.
  • Individual glossary, idea, or question items.
  • Images.
  • Template style files (all files in the lib directory).
  • The htlatex tools (latexmkrchtlatex.cfg, and main.css).

For the latter two items (the template style files, and the htlatex tools), you might have to be careful when linking them and making changes as it might change the pagination of all your projects that use the file. On the other hand, if you plan to create new editions with a new layout anyway, it is easier and less likely to cause errors if you have all your style files in one place and make each change only once.

For example, let us assume you have five LaTeX projects and want to change the book size from 5.25”x8” to 6”x9.” If the style files are linked, you would need to make only one change in the lib/bookformat.tex file, recompile the connected projects, re-polish the output files, and you are done.

So, ultimately, the benefit depends on your situation. I advise keeping this feature in mind as you write your first few books. Once you can see a possible benefit of reorganizing your books, start by creating a main project in Overleaf which houses your shared bibliography, glossary items, and so on, and link to them from the individual projects.

Whenever you make changes to your general template settings, you no longer have to make changes in each project individually. Instead, you can apply changes to the main project, and then just refresh all the linked files in each of your book projects for the changes to take effect. For example, let us say you have found a spelling error in your bibliography. You can fix this issue in the main project and refresh the file in other projects, instead of having to apply the fix to every single bibliography file of each project. All my projects share the “thank you” page, the “about the author” page, the main.css file, the htlatex.cfg, all the files in the lib folder, the bibliography folder, and the latexmkrc file.

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

Categories
Publishing

Publishing on Leanpub

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

As an alternative to Amazon and Google, you could try out the platform “Leanpub.” Leanpub is designed to provide you with just enough to get your book properly published, marketed, and sold. You can read more about how Leanpub applies Agile principles at https://leanpub.com/about. In this section, I will compare Leanpub to Amazon and Google.

Leanpub is still a niche platform (Amazon has around 70% of the e-book market, while Leanpub has maybe 0.25%), so you should examine the drawbacks but also the potential advantages of publishing on Leanpub. The good news is that there is much less competition, meaning that advertising is much easier on Leanpub than on Amazon or Google. The biggest challenge is to publish a book on a topic that interests Leanpub’s audience. In considering the likelihood of your book finding readers on the platform, check out its bestsellers at https://leanpub.com/bookstore/book (as of 2019, these are mostly non-fiction books about project management and software development).

Leanpub operates with a relatively low overhead compared to its competitors, which results in higher royalties for you, the author (80% with Leanpub, 70% with Amazon, and 52% with Google).

Like Google, Leanpub does not provide a print option: you can sell only e-books on both platforms and have to link to other services to sell a printed book. For editing your own work, you might want to have a printed copy in front of you to work on. Even if you do not plan to publish on Amazon, for the option of printing a draft copy of your work, it is worthwhile to use Amazon KDP. If you plan to publish your work exclusively in e-book form, printing it out yourself is probably the easiest option.

Leanpub currently (2019) provides no ratings. From the reader feedback I received on Leanpub for my books, I learned that some potential buyers will check out a book’s rating on Amazon before making a purchase. Google also provides a rating system but currently most people use Amazon to rate books.

Leanpub provides a direct way of contacting you and a basic forum. It uses a different comment system than Amazon, though: visitors do not have access to the forum until they have bought the book.

Leanpub is more lenient than Amazon about description texts in the shop. Feel free to link to your website or even to Amazon so that potential readers can check out the ratings there. On Amazon, book descriptions have to adhere to the rules stated in https://sellercentral.amazon.com/gp/help/external/200390640.

On Leanpub, linking to your book is simple, you can even choose a custom URL. For example, this book is available at https://www.leanpub.com/BBWLTAW. By contrast, linking to your e-book on Amazon can be a challenge as you have to know which of the many local Amazon platforms your visitor uses (Amazon.com, Amazon.co.jp, Amazon.co.uk, Amazon.de, etc.). For example, if you send visitors from Germany to the Amazon.com shop, they cannot buy your book there without being redirected again to the German site.

The upload and publishing process on Leanpub is very straightforward. Your book is available immediately for purchase after you have uploaded the files. You can offer a direct PDF, MOBI, or EPUB download and you can customize the PDF preview. The obvious downside is that you have to create the PDF preview yourself, while Amazon and Google automatically create one for you. Likewise, there are no automatic checks of your files on Leanpub. If there is a problem with your book, customers can contact you directly from the Leanpub website for help.

Leanpub allows you to set up a minimal and recommended price. Buyers can choose whether to donate additional money. This might be a good idea for your fans to show their gratitude but do not expect many strangers to use such an option. Still, compare that to Amazon and you notice how impersonal Amazon’s shopping page is. You do not feel connected with the author when purchasing a book, while Leanpub offers a few options (e.g., mailing list, forum, mailing the author) to connect.

Also, Leanpub allows you, the author, to contact your readers (at least those who opted in to e-mail updates). This is possibly one of the best options as you can directly advertise updates or new editions of the book they have purchased. Leanpub even offers to connect your readers to your external mailing list (if you are using Mailchimp).

Leanpub allows you to offer parts of your book before the book is complete. Selling the book as you are writing it gives people access to your research without having to wait for you to finish editing the entire book. This is especially relevant to books about current topics or technologies. In addition, this approach provides funding through pre-orders, and early feedback from readers which is an essential element of writing a book the Agile way. Amazon’s pre-order option is completely different: it is limited to placing an order for a book up to three months before the actual launch and a customer does not have access to any early drafts. Google’s policies are somewhere in between. There is no time limit for pre-orders but visitors have access only to a preview and customers cannot access the full book before launch day.

There is an advertising “shelf” to which you can add your book at no risk (you do not have to pay for advertising if the book is not sold). The conditions will probably change as the platform becomes more popular. As of 2019, you can buy a shelf position for $49 per month. A shelf means your book is advertised prominently on the main page, reaching a lot more people than on Amazon. One drawback is the shelf purchase page is not very easy to find; you can check out the description at https://leanpub.com/shelf/buy. By comparison, on Amazon, without advertising, your book is usually only found if people search for specific key words and if your book is already popular.

Leanpub has a 45-day no-questions-asked return policy—significantly longer than the seven-day return policies at Amazon and Google. As the founder of Leanpub, Peter Armstrong, explains: “The primary reason is that it makes people more comfortable buying an in-progress book. It removes all the risk of buying an in-progress book, and it will lower the refund %. If a book is not updated in 20 days, is it dead, or did the author just get busy for a few weeks?” (see https://groups.google.com/forum/#!topic/leanpub/Z17mvHboYaA).

Setting up Your Book on Leanpub

Setting up your book on Leanpub is straightforward:

  • 1.Sign up for an author account at https://leanpub.com/sign_up.
  • 2.Click on Store / Author (https://leanpub.com/author_dashboard). This is the overview for your royalties earned.
  • 3.Click on Metrics / Books / Create Book (https://leanpub.com/create/book).
  • 4.Fill out Title, choose the Book URL (the URL you can link to your book from your website), and set Language, and Book Theme.
  • 5.Leanpub offers you a book editor, a connection to Google Docs, a text upload, or uploading your book files (Bring your own book). Having created a MOBI and PDF file with Overleaf, choose the last option.
  • 6.Leanpub offers three subscription models. For up to 20 updates of your books, choose the Free plan. This should be enough to get you started. Custom themes are only of value if you design the book itself on Leanpub instead of using the imported files from Overleaf.
  • 7.Click on Add to plan to finish the creation. Once finished, your book title is accessible in the menu (Books / Your Books).
  • 8.Now fill in the rest of the info. That is, author name, book category, contributors, copyright, ISBN number, language, teaser text, book description, meta description (for search engines), and the table of contents. You can open the HTML version you created for your MOBI conversion, copy and paste the table of contents into the text field, and format it as you see fit.
  • 9.Further options are to show the reader count, page count, the “Also By” list, and a way to contact you. My recommendation is to be as transparent as possible.
  • 10.Finally, upload the book’s front cover, set the pricing, and upload the book’s content. For the preview PDF, the quickest way is to go to your main.tex file in Overleaf, use % to temporarily remove all but the first few chapters in the main matter, press Recompile, name the PDF file something like (your book’s title)-(date)-preview.PDF, and upload it to Leanpub.
  • 11.Double-check your uploaded files by downloading them and checking if they are the right version. That is it!

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

Categories
Publishing

Publishing on Google Play

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

While Amazon KDP is the current market leader, it might be worthwhile to also publish your book on other platforms. One alternative (only for e-books at this time) is Google Play, where people can buy directly from their pre-installed “Books” application on their Android smartphone (or online on their computers). The advantage of Google over other competitors is that many people already have a Google account and have added their payment information so that shopping online is seamless. Another point for Google is that fewer competitors offer their books there (compared to Amazon). This is partly due to the more complex initial setup and upload process which we will be discussing in this chapter, step by step. On the other hand, Google offers prominent display of your book on the Google search results page (see Figure 22.1).

Figure 22.1: Google Play books are displayed prominently on the Google search results page.

To publish your e-book on Google Play, you need to have or sign up for a Google account (ideally a separate account for business) on https://www.google.com, register yourself as a publisher, and make your EPUB file ready. Signing up for a Google account is straightforward, so we can move on to registering it as a publisher account.

If you already have the e-book on Amazon KDP, make sure it is not (or no longer) in the “KDP Select Program,” which prohibits the release of the e-book (or large parts of it) on other platforms.

Registering at Google Play

Google sets some limits on people registering as a publisher (or a self-publishing author). The first step is to fill out the form at https://play.google.com/books/publish.

This is generally also the address you can return to if you get lost during the publishing process.

Click on GET STARTED NOW which leads you to a login page (if you are not already logged into Google) and then to the entry page (Find new fans. Sell more books). Click on online interest form (https://support.google.com/books/partner/contact/playbooks_partner_program_interest_form) and fill out the Google Play Books Signup Request Form. The fields are all straightforward: fill in your info, and then press Submit. This submits a request to Google which will put you into a queue.

Please note that because publishing on Google Play is still in development, the links could change. If you encounter a broken link, let us know and we will get you on the right page.

Note that it now takes additional time for Google to confirm the data you have entered. You can set up your book(s), but you cannot publish until your account is confirmed by Google. This activation took, for me, about a week.

Creating EPUB Files for Google Play

To prepare for the EPUB conversion, make sure that your LaTeX code

  • does not use special characters (like colons) as the ID of entries in the bibliography, and
  • does not use the \url{} command for emails or other non-URLs.

Calibre ⋅  Calibre is an HTML to EPUB converter tool (see https://calibre-e-book.com/download) that also allows you to edit the metadata of the EPUB, add a cover image, and set the parameters of the conversion.

There are many free software tools to convert your HTML file into an EPUB file for Google Play. I recommend using Calibre. After download and installation, start the E-book management program which shows your current library. To add a book, click on Add books, browse to your directory where you have extracted the zip file you downloaded from Overleaf, and select the HTML file. On the right side, you will see a default picture for the cover (we have not assigned any yet), as well as a list of formats. As we have not yet converted the file to EPUB, ZIP is the only format we have.

Next, left-click on your book entry, and click on Convert books. On the top left, you will see the input file format (ZIP), and on the top right, you will see the output format (EPUB). If another output format is shown on the top right corner, click on it and select EPUB. All that is left to do is to fill in the meta data and adapt the page setup—all other items are good at their default setting.

On the right-hand side, you need to enter the title, author(s), publisher, series name, and series number. You can skip the large text field below—the book’s description can be filled out on the particular platform where you release the EPUB file and might need several revisions there.

As Google has no inbuilt cover creator and as you cannot download the cover file from Amazon, create (or re-use) a cover file as previously discussed in Chapter 21. Next, click on Page setup on the left, and select Tablet from the Output profile list. This disables image scaling for the conversion, and the images will instead later be scaled according to the device the reader is using to read your book. While this increases the size of the EPUB file, it allows your e-book to be read on any device.

Then, click on Search & replace. This looks a bit cryptic, but we need to fix how TeX4ht builds its links in the file. Insert the following string into Search regular expression:

 
 
<a id="\w[0-9]-[0-9]+doc"></a>  

Leave Replacement text empty, and click Add. Clear the Search regular expression field and now enter:

 
 
<a id="chapter\*\.[0-9]+"></a>  

and click Add again. These two regular expressions will remove faulty links that will otherwise show up as errors on Google Play.

Finally, press OK, wait for the conversion to be completed, and click on EPUB to open the e-book reader to see if the conversion was successful. Now you have an EPUB file we can later use to upload to Google Play’s e-book platform and release it.

After you have added your book the first time, you can simply re-use this meta data and the cover image for new versions of the book. For this, right-click on an existing entry, select Edit metadataCopy metadata, and then right-click on the new entry, selecting Edit metadata, and Paste metadata. You will probably import your book several times while learning how to work with Overleaf and LaTeX, so this feature can be helpful.

Adding Books to Your Catalog

Once approved, you can visit https://play.google.com/books/publish again. Click on GET STARTED NOW, make sure you are logged in with the right account, and you will arrive in the “Partner Center” window. Click on Book Catalog and then on Add book.

Select Sell ebook on Google Play for the “Select a sell option.” If you are not keen on having yet another platform where people can buy your books, you can also select “Offer a preview on Google Books only” and link to your website or Amazon instead.

For “Select a book ID,” you can either use the same ISBN you used for your e-book, or use the automatically generated one from Google (GGKEY, a unique key like the ASIN on Amazon) which you can get for free.

If you are releasing multiple editions of your book (for example, due to updates) on multiple platforms, you might want to think about acquiring ISBNs and assigning one ISBN to each edition. This helps you keep track of what edition you have released where, and makes it easier for authors to cite, or for readers to review, your work.

Next comes a series of forms that are similar to the ones to set up your book on Amazon KDP. If you have already entered your book on KDP, you can copy and paste most of the information (title, subtitle, description, publication date, page count, format, about the author, series, genre, etc.). For the content, you can upload the PDF and EPUB files, providing both a download (or preview) of your printed book version and the format optimized for e-book reader devices. You have also more flexibility regarding pricing: you can set up specific countries and time periods where prices apply.

After you have entered all the meta data and uploaded the PDF or EPUB, the file is automatically scanned for issues (this might take an hour or two). If you encounter any error messages, re-read Chapter 22.2 or let us know at [email protected] But if you have not made any significant changes to the template, your file should be ready to be released. If you have just set up your account, you might still have to wait a while.

The book will show up at https://play.google.com/books of your Google account (or in the books application on your smartphone).

Once released, you can find your book by going to https://play.google.com/store/books and search for the title of your book. That is it!

Troubleshooting

Instead of waiting for Google Play to process and check your EPUB file, you can also use an EPUB validator like http://validator.idpf.org/. The downside is that it is more strict than the Google Play validator—the output of Calibre will tend to identify issues that are accepted by Google Play:

  • Error while parsing file “value of attribute ‘id’ is invalid” The id of one of your bibliography entries contains a special character.
  • Referenced resource could not be found in the EPUB. This issue shows up if your \url commands are erroneous (for example, the given URL does not start with “http”).
  • CSS selector specifies absolute position. This is an issue of Calibre and cannot be fixed but has no effect on the actual e-book displayed on a device.

For reasons of optimization, Calibre splits the HTML file into parts. Thus, the line numbers shown both by Google Play as well as the EPUB validator relate to those split files, not your original HTML file. To access those split files, go to the Calibre output directory, right-click on the EPUB file, and unzip it with WinZip (or another similar unzip program).

If you encounter further errors, you can also refer to Google’s checklist of how to make a book available online: https://support.google.com/books/partner/checklist/4489282. If all else fails—and while not recommended—you can also convert the PDF version of your book directly into an EPUB file. The downside is that it will look just like a small PDF and will be hard to read, as it is not adapted to a device’s specific size, resolution, or page orientation.

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

Categories
Publishing

How to Create Cover Graphics

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.


Cover graphics are separate from the LaTeX project. You can neither create a cover graphic in LaTeX nor include it in your project. Instead, you need to use an external program to design it. I can give you only a technical guideline and some ideas. I recommend hiring a designer to produce the final version. If you are somewhat proficient with a graphics editor, the following sections can get you started with your cover. If you do not plan to publish a print edition, simply skip the following section.

Download KDP Template

A cover consists of the front cover, the back cover, and the side, called the “spine.” Paperback covers are usually printed in one piece, meaning you need to provide an image with your back cover on the left, the spine in the middle, and the front cover on the right. Later, this is folded and glued to the printed pages of your book.

First, you need a template that fits the size specifications exactly. You do not want half of your front cover to bleed over onto the spine or to have your text cut off at the edges. KDP provides a service for this, simply go to https://kdp.amazon.com/en_US/cover-templates and enter the trim sizepage count, and paper color (which affects the thickness of each page and hence the width of the spine). For the trim size, use the same size as specified in lib/bookformat.tex. For the page count, use the actual page count of your PDF (which has nothing to do with the numbering you put into the book). Likewise, for the paper color, use the same setting you have selected previously so that you will have the correct spine size.

Amazon will check your template, but not automatically, meaning you might lose a few days waiting for approval if your cover template does not match your PDF with the book’s content (for example if it shows a different title, or if the spine size does not fit the number of pages).

Once all is entered correctly, click on Download cover template. Note that the resulting template rounds your number of pages up to a multiple of 10. If possible, the best approach is to also align your content’s pages to a multiple to 10, but this is not required. There is a margin of error and KDP might decide to add empty pages. If your book has 251 pages (thus you need the 260-page template), you might want to check, though, if you can edit your material to reduce the page count by one.

The template file contains both a PNG file and a PDF file. Depending on your graphics editor, choose the one with which you are most familiar. The template itself is self-explanatory: use the whole back cover space, spine space, and front cover space (including the areas marked with red) for your back cover, spine, and front cover picture. Then enter your text while being careful not to touch any of the areas marked with red. The ISBN number on the back is added automatically, so be careful not to have any content in or near that area.

Front Cover Structure

  • If your front cover is white, you need to add small gray lines (maybe 3-4 pixels) around your template. This is because while the borders are clearly visible when the book is printed, the book cover preview on Amazon is displayed in front of a white background. Adding a gray border will make it stand out.
  • As a designer, you might be inclined to make it look as good as possible when you hold it in your hands. While this is a fine approach, the front cover also needs to look good (and readable!) when shown on the Amazon website. Scale down your cover and see if you can still recognize the writing and the image.

For the second point, let us look at the details currently at Amazon:1.346-pixel height in the product page (where the customer decides to buy your book or not).2.218-pixel height in the search results page.3.160-pixel height in the “Sponsored products related to this item” view.4.115-pixel height in the “Shop by Category” view.

I propose that the following elements should be easily readable for the corresponding sizes:1.(346-pixel height): Main title, subtitle, author name, additional subtitle.2.(218-pixel height): Main title, subtitle, additional subtitle.3.(160-pixel height): Main title, subtitle.4.(115-pixel height): Main title.

You might also have to use fonts that are easily readable at those sizes. This might reduce the quality of the high-resolution image and the printed cover, but the only thing a potential buyer (on Amazon) initially sees is the “minified” version of the cover. With printed books primarily sold in a (physical) book shop, the situation is different because customers can actually hold the final product in their hands.

For the e-book cover, the process is the same as described above. The only major difference is that you are not bound by your selected trim size of the book. Instead, Amazon recommends using a resolution of 2,560 x 1,600 pixel (1.6:1 aspect ratio). If your aspect ratio of the cover for your printed book is larger (meaning it has a smaller width), it might be worthwhile to create a new cover that makes use of this additional space. I recommend saving the e-book cover as a lossless PNG file. If you upload it to an online platform like KDP, Google Play, or Leanpub, the platform will convert it automatically to the best format and resolution suited to each website.

Back Cover Structure

The back cover is the text a potential buyer turns to after seeing the front cover. The reader now knows what the book is about and is deciding whether or not to buy it. Thus, the back cover is the place where you make the sale. You should list a more detailed description of the contents at the top, and a short author biography, ideally with a picture of you, in the middle. Unlike the front cover, there are no special requirements for the font sizes for the back cover. An interested reader will look at it in full resolution.

Spine Considerations

The spine provides space for the book’s title and your name (rotated by 90 degrees). If your title is part of a series, you could put the series name here, too. Also, you might wonder how your book will look on the shelves in stores or libraries. There, your spine is the point of sale. If it is part of a series, you might want to go fancy and provide a nicely composed picture for when the books are arranged side by side.

Cover Design

As mentioned above, it is recommended to have a professional designer create your cover. Contact us at [email protected] if you need help in that regard. If you want to select a freelancer on your own, I recommend hiring someone with whom you can communicate very clearly, as cover design goes beyond simply “Draw this,” “Here, I am done,” and “Thank you.” The designer needs to know what sets book covers apart from other graphics (like the different sizes of the cover graphic for advertisement discussed above). Examine his or her portfolio closely and do not expect that he or she will create a design that is significantly better (or worse) for your project.

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

Categories
Publishing

Publishing Your Book on Amazon KDP

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

Publishing on Amazon KDP is relatively straightforward once you have the MOBI file, or the PDF file (for the print release) ready (this is discussed in the book in detail).

To start, head over to https://kdp.amazon.com and click on Sign in. If you do not have an Amazon account, click Sign up and follow the instructions. When you sign in the first time, it creates a new KDP account and connects it to your Amazon account.

I use two different Amazon accounts, one for my personal orders, the other for anything related to publishing. For easier management, it is generally advised not to mix private and business accounts. You just have to make sure that when signing in, you are using the right account. If you are worried about the number of passwords you would have to manage, I recommend https://keepass.info where you can back up all your passwords safely and easily generate new ones.

Once signed in, you will see the main menu (Bookshelf |Reports |Community |KDP Select). Also, at the top, there is a link to Help (https://kdp.amazon.com/help) which leads to very detailed documentation of all the functions of KDP. If you are stuck, you can refer to that and easily find the solution. You are always free to contact us at [email protected]!

E-book Publishing

For now, click on Bookshelf. You will see a box, Create a New Title. Click on + Kindle e-book. Here, you have to fill out all the basic information about the book. Most items are self-explanatory, but I have a few comments on the following items:

  • Book Title. If the book is part of a series, include only the part title. For example, instead of putting “Philosophy for Heroes: Knowledge” into the box, just use “Knowledge” and put “Philosophy for Heroes” into the Series field. Changing the title after the release is possible, but needs to be done via Amazon support which can be slow (as of 2019)—maybe that depends on your sales rank, though. An advantage of using the Series Title is that your other titles are referenced from each individual book product page.
  • DescriptionKeywords, and Categories. Enter the description and the keywords that describe the contents of your work. Also, select two categories (as specific as possible). These entries can be updated later, even after release.
  • Edition Number. This is optional. Use it only if you have already released a version and made significant updates to it.
  • Pre-order. The option to pre-order a book can be an important marketing tool. For now, select I am ready to release my book now—even if you are not ready. It will not be released before going through all the steps, so do not worry.

Press Save and Continue and continue to Kindle e-book Content. Here is where you upload your MOBI file (press Upload e-book manuscript). While the file is processing, we can move on to the cover setup. While KDP offers a book cover creator, I strongly advise against using it. Covers sell books, and if your cover looks like you clicked it together in 10 minutes, people will think the book’s contents are of equally low quality. We discuss cover creation in another article (and the book). If you already have a cover, select Upload a cover you already have and Upload your cover fileIf you just want to test the publishing process, the cover creation process is straightforward. Start the cover creator, select a picture, select a design, and you are done.

Finally, once the cover is set, click on Launch Previewer to look at the generated e-book in your web browser. Depending on your e-book size, it might take a while until the previewer has finished loading. Alternatively, you can look at it directly on your Kindle (if you have one) or in the Kindle application on your computer or smartphone.

If the upload went well and if there are no issues with the previewer, you could move on with Save and Continue and then publish your work on Amazon. That is it!

At the end of the page, you can assign your e-book an ISBN number. This can help to organize your e-books among different platforms. See the next section for more information about ISBN numbers.

Paperback Publishing

Let us now move on to how to publish a paperback with KDP. Click on Bookshelf. If this is a new title (meaning you have not yet created a corresponding e-book title), click on + Paperback in the Create a New Title box. Here, you have to fill out all the basic information about the book. The form you have filled out is similar to what we have discussed above. Press Save and Continue to edit the paperback’s content.

  • ISBN. The least complicated choice is to select Get a free KDP ISBN. On the downside, if you ever move your book away from KDP (or upload it on other platforms), you cannot take your ISBN with you, which means you will have to create a new edition. If you decide to Use your own ISBN, you need to acquire a block of ISBNs. On the upside, your publishing company’s name shows up when using those ISBNs. Depending on the number of ISBNs you buy and where you buy them, you can pay $.50 up to $50 each. There are dozens of providers, so comparing prices is recommended. Paying extra for additional services like bar codes is usually not worth the money. You can generate them yourself, and at least if you plan to publish on Amazon via KDP, bar codes are automatically generated. Plan for at least three ISBNs for each book in the long term, as new editions (new size, hard-cover, and soft-cover, changes within the book that move content to different pages, etc.) each need a separate ISBN.
  • Publication date. Assuming you have not released this book earlier, leave it blank. If you have already published the book on another platform or by printing and selling it yourself, enter the original publication date here.
  • Interior & paper type. I recommend the option Black & white interior with white paper. A white background will improve the contrast for any graphics you are using. If you are creating a text-only book, you might consider cream paper, which is a bit more yellowish, heavier, and thicker. If you plan to use color graphics, select color interior. Please note the significantly increased cost for this print option (for example, as of 2019, $21.85 instead of $4.45 for a 300-page book, see https://kdp.amazon.com/en_US/help/topic/G201834340) which reduces your profit margin. You will have higher quality and thicker paper than with the black & white option. Some authors use this option even if they do not use any colored graphics. As with the cream option, selecting this option might influence your spine size and hence your cover template.
  • Trim size. KDP offers a variety of trim sizes. Select the same size you have previously set in lib/bookformat.tex.
  • Bleed settings. Bleed refers to whether graphics are allowed to print beyond the usual print margin; select No Bleed.
  • Paperback cover finish. As an option, you can have KDP bind your book cover with a glossy foil. My recommendation is to check out both options in a test print. I prefer the Matte option as the foil of the glossy option can tear off.

Next, upload the PDF of your book that you have generated in Overleaf. For the cover, using a cover created by a professional designer is recommended, but for test prints, using the KDP cover creator is sufficient. If you already have a print-ready PDF cover, press Upload a cover you already have (print-ready PDF only). Next, click on Launch Previewer and check all the pages as you have previously done with the PDF itself. In the previewer, take note of any warnings on the left side. If all is correct, press Approve and move on to Paperback Rights & Pricing by pressing Save and Continue. There, you can set up the pricing.

Before actually publishing the book to Amazon, I strongly recommend ordering a proof copy by clicking on Click here to request a proof copy. Looking at a physical copy always gives you a different perspective on your work than seeing it on your screen.

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

Categories
LaTeX Publishing

Polishing for E-book Release

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

Polishing for an e-book release is significantly easier than for a PDF print release. This is because the reading software or device on which your book is displayed for the reader reformats your book to fit correctly on a particular screen. Also, printed books have individual pages, while e-books do not. Your e-book’s contents are handled like a one-page website where you simply scroll from top to bottom. In some cases (for example, new chapters, title pages, or publisher pages), it makes sense to enforce a page break even in an e-book with \nextpage.

If you plan to release your book as an e-book as well as releasing a print version (which I recommend), you should first finish and release the e-book version and then work on polishing the print version. This is because there are additional steps required for the print version (like cleaning up empty pages and creating the index).

Preparing Images for E-books

Text can easily fit on any screen because it is very flexible, but images are not. They are not reinterpreted and adapted to a specific device; rather they are simply scaled to fit into the reader’s screen. Text does not lose quality when being adapted to a particular screen resolution, while image quality might suffer significantly.

For e-books, lossy JPG files are preferred because, on Amazon, distribution costs per book are not by page, but by the file size of the e-book for each download. Except for the cover graphic (which is uploaded separately), you should use low-resolution images (300 dpi) throughout your book as the device on which the image will be shown will most likely have a low resolution, too.

One major difference between e-books and printed books is that you can get color for free, at least on some devices. On other devices, all graphics are converted to grayscale versions. Here, it is up to you whether you want to provide an extra service for owners of more modern devices (or who read the book on a smartphone) or have print and electronic versions of your book identical when it comes to graphics. If you decide on grayscale images, you will save around a third of the file size. For example, this photo of the Milky Way has a size of 328 kb in color, but only 250 kb in grayscale (see Figure 19.1).

Figure 19.1: An image of the Milky Way (image source: wikipedia)

Another difference is scaling. For the print version, you can use \adjustbox{} to fit an image into the dimensions of a page. For the e-book version, images are scaled automatically to the width of the screen. While this saves you the work of scaling it yourself, you might end up with images larger than intended (and thus having a lower resolution) in those cases where you have scaled down the picture in the PDF version.

For all TikZ graphics, this is configured in the lib/inittikz.tex file (see Chapter 17.1.8): all TikZ graphics are automatically converted to PNG files with a fixed width (1,245 pixels by default). Instead of being scaled up, the transparent background of smaller graphics is simply extended.

For smaller, non-TikZ graphics that you include from external sources (e.g., JPG images), you should make sure that there is sufficient space left and right of the image. This ensures that they are not distorted during the e-book conversion process. Larger images for which you are already using the full width of the page in the print version do not have to be edited as they will be scaled down automatically. Alternatively, make it a rule for yourself to not use \adjustbox{} in the print version and instead do all the scaling manually by editing the image externally in a graphics editor. The benefit of this approach is that you do not need a separate e-book version of your images.

If you are using images with fonts, lines, or diagrams in them, make sure to be consistent and use the same font sizes and line thickness throughout your book. This can be a significant challenge if you do not have access to the original image files. For that reason, for any new images you want to add, I strongly recommend using vector graphics (or TikZ graphics) as the image source.

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

Categories
Editing LaTeX Publishing

Polishing a Book for Print

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

While using LaTeX can save you a lot of time by automatically formatting each page, it has its limits. For example, you might end up finishing a section or chapter with one line that ends up alone on a page. This is ugly but it is not something LaTeX can do anything about. The program’s hands are tied because it cannot rewrite the text for you. It will display every line—even if the final line in a chapter is “orphaned.”

Let us now look at a checklist you should go through before releasing the book (and after you have completed all the writing, indexes, bibliography, etc.).

Clean up Empty Space

Skimming through a book and seeing large unused white spaces is a telltale sign of an unpolished book. Do not be tempted to add a photo of your cat or some meaningless diagram just to fill the empty spaces. It is literally a waste of space and ultimately of book pages (affecting printing costs, weight, shipping costs, etc.). Depending on your contents, it is possible to save a dozen pages by cleverly arranging your text.

While LaTeX provides some functionality by automatically arranging images, you do not want to end up in a situation where the image is far from the position in the text where it is referenced. Most of the time, you want the image to show up exactly where it should be (the default setting of the template). Likewise, forcing page breaks and having sections starting on the right side can lead to a number of blank pages.

Let us examine several items to keep in mind:

  • Combining paragraphs. If you need to save space, you can combine two closely related paragraphs into one large paragraph. While this might come at the cost of some readability, it is easy to implement.
  • Breaking paragraphs. On the other hand, if you need to fill white space, be more generous with starting new paragraphs. This reexamination of your text might improve readability by splitting it into smaller parts.
  • Shortening sentences. If your paragraph spans to the next page due to just a few words, edit the paragraph.
  • Rearranging images. You can play around with moving an image before or after a paragraph and check if this solves the problem. For example, if you have a paragraph followed by white space followed by a picture on the next page, you could simply switch the picture with the paragraph, ending up with half of the paragraph on the first page and half on the second page, eliminating unused white space.
  • Shrinking images. Besides simply rearranging images, you can also limit their size by either changing the limits of the \adjustbox{} command or by making the image itself smaller. Be advised that using \adjustbox{} should be the last resort. While scaling photographic images is no problem, any image containing fonts, lines, tables, etc. will end up not looking good. If you want to scale such vector graphics down, the better option is to make changes to the actual graphic, for example by reducing the distance between elements in a diagram, making the overall image more compact while keeping the original font and line sizes.
  • New page. Sometimes you want to add a blank page or have the next section start on a new page. For example, you have a section starting at the lower right page, with just half a paragraph fitting on that part of the page. Here, it is best to move the whole section to the next page and fill the blank space as discussed above. You can do that by simply adding \newpage (or \blankpage if you want to finish the current page and add a blank page). As mentioned in Chapter 14.1, this does not affect the e-book version of your book.

As each change will possibly affect subsequent pages, you have to check the results page by page from front to back. When moving things around, take special care to have images near their references in the text—and to have a reference for every single image! The best experience for the reader with respect to images is if he or she does not need to browse back and forth to connect what you write about a particular image and the image itself.

If you encounter any “orphaned lines” (single lines that are put on the next page although they could fit on the current one), try adding a \newpage command at the end of the paragraph. This is an issue that sometimes occurs with the LaTeX compiler.

Left Hand / Right Hand Pages

When you have cleaned up your empty white spaces, you should again preview your entire PDF file. For this, you can either use Amazon’s online previewer or a prepared PDF file in your PDF reader. For the latter, I use Adobe Acrobat Reader DC (https://get.adobe.com/reader/), load the generated PDF file, select File / Print…, select Microsoft Print to PDF, and select pages ii – (your last page). By moving the second page to the first page, we can now open the new file and switch to View / Page View / Two Page View and look at the pages exactly as they would appear in the printed book, with the even page numbers on the left and the odd page numbers on the right. The formal terms for these are “verso” for the left-side page of a book and “recto” for the right-side page. By book publishing convention, the first page of a book (and in the template, of each chapter) is a recto page.

Now, go through the entire book again to double-check whether the chapters and sections start on the correct side of the book.

Clean Up Graphics

To understand graphics in the book production process, you have to understand file formats. In principle, there are three types of image files:

  • Vector graphics. Vector graphic files like EPS or PDF contain code to actually draw the picture in question. This code is understood even by the printer itself, which can help to improve the print quality tremendously. Use these file formats whenever possible. TikZ graphics produce vector graphics, and stock image sites like shutterstock.com offer many files both as regular image files and vector graphics. Both EPS and PDF files will work, although PDF files are the preferred format because they do not need to be converted but can be embedded by LaTeX directly into the final PDF.
  • Lossless PNG images. PNG images undergo a compression algorithm, but the type of compression used does not cause any loss of quality—the resulting PNG image has the same exact image information as the original picture. If you do not have vector graphics available, use PNG files.
  • Lossy JPG images. The limiting factor of e-books is the total file size; the limiting factor for printed books is the number of pages. JPG images are optimized for size, so if possible, do not use JPG files for any graphic in your printed book. As image size is not an issue in print, it is better to use lossless PNG images if you have them available.

With this in mind, examine the images you are using now and maybe try to find better versions of those images or replace them with vector graphics (we can help you with that, see Chapter 14.9). For lossless and lossy images, choose a resolution of 600 dots per inch (dpi), as printers usually use this resolution for black on white printing.

resolutionuseuse it with
Lossy JPG300-600 dpie-booksphotos
Lossless PNG600 dpiPDFphotos, diagrams
Vector graphicsn/abothgraphs, diagrams
Figure 18.1:Comparison of graphic formats and their application.

Gimp ⋅  Gimp is a free graphics editor (https://www.gimp.org) with which you can create, scale, or convert images.

Gimp can show you the resolution, but you can easily calculate it yourself. Simply take the width of your picture in pixels (e.g., 1,245) and divide it by the width of your page in inches (e.g., 4.15”, which would result in 300 dots per inch). Please note that when scaling JPG and PNG files in Gimp, you can also scale the DPI resolution. For example, a 1,245-pixel-wide image with 300 dpi will appear smaller than a 1,245-pixel-wide image with 100 dpi.

To calculate the whole width of a page in your book, take a look at your settings in lib/bookformat.tex:

 
 
\usepackage[paperwidth=5.25in, paperheight=8in, inner=0.80in, outer=0.3in, top=0.7in, bottom=0.5in]{geometry}  

The space where you can actually put text is paperwidth – inner – outer. In this case, 5.25 in – 0.8 in – 0.3 in = 4.15 in. With a desired resolution of 600 dots per inch, you need an image with a width of 4.15 in * 600 = 2,490 pixels.

Lightshot ⋅  Lightshot is a free screenshot utility (see https://app.prntscr.com) that saves the entire screen or parts of it into an image file at the press of a button.

One problem I faced with the screenshots in this book is that (at least with Lightshot) images are saved at 120 dpi. If I include them directly into the book, they will look pixelated and way too large. Opening the image in Gimp, selecting Image / Scale Image, and changing the X/Y resolution from 119.990 dpi to 300 dpi does the trick.

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

Categories
Editing LaTeX Publishing

The LaTeX Book Template

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

In a previous article (and the book), we we have covered the mainfront, and the back chapter folders of the LaTeX Template. Now we will discuss those folders again in more detail and go through the remaining folders. This will help you to know where the configuration for each part of the template can be found and allow you to make changes.

Template Library Files

Let us first focus on the lib directory. There, each file is a set of new commands or configurations to set up the style and contents of your book.

Packages File

A packages file is simply a LaTeX file linking to a number of other LaTeX files or containing additional functionality not provided in the default LaTeX configuration. To import a package in LaTeX, you simply use the \usepackage command before the \begin{document} command. In the template, the lib/packages.tex file loads all the other files in the lib directory and also loads some additional packages, depending on the output format.

The first two commands load the nag package to provide additional warnings if you are using outdated or invalid packages and expand the output of error messages (\errorcontextlines 1000) in the log file to help you fix issues quickly.

The ifxetex package loads a small script that we can use to check whether the target platform is a printed PDF (with XeLaTeX) or an HTML file (with pdfLaTeX). It follows the basic format of:

\ifxetex{} (executed if XeLaTeX is used) \else{} (executed if pdfLaTeX is used) \fi{}

Think of \ifxetex{} as the main junction between the e-book (the HTML file output using pdfLaTeX) and the print book (the PDF file output using XeLaTeX).

Next are several packages and configurations specific to either of those platforms. The adjustbox packages adjust figures to fit onto a page—a feature needed only for the printed PDF as e-book readers automatically adjust graphics depending on the screen resolution. The psvectorian package allows us to add curly horizontal lines at the end of sections and chapters—a feature not supported by e-books.

TeX4ht ⋅ TeX4ht is a tool to translate LaTeX code into an HTML document.

The next command, \hrule, is not supported by TeX4ht, so we create a specific command, \myrule, and translate it into an HTML <hr /> command correspondingly. For the em dash, we need to add spaces (even if it is just 0) left and right of it to allow for line breaks. For the HTML output, we simply use the ASCII code for the em dash (#8212;).

At the end of the file, all relevant packages of the lib directory are loaded, so we need only to include lib/packages.tex to load the entire configuration. On the following pages, I will discuss each package.

Language Selector

In an Overleaf project that is based on the template, you can select the language by changing the parameter of the babel package in output.tex. In the file, either the command \babelDE or \babelEN gets activated by the command \usepackage[ngerman]{babel} or \usepackage[american]{babel}, respectively. The command sets \languagename either to “ngerman” or “american.” In lib/languageselector.tex, the new command \babelDE{content} checks whether “ngerman” is set, and then displays the content. If it is not set, nothing is displayed. Likewise with the \babelEN{content} command, resulting in only one of the languages being displayed. The first use of this command can be seen at the end of the file, where we overwrite the naming of the table of contents depending on the language we have selected.

If you want to add a different language, for example, Spanish, replace “american” with “spanish” in output.tex (\usepackage[spanish]{babel}). Next, add the following commands in lib/languageselector.tex and you are ready to use \babelES as a command in your text.

 
 
\newcommand{\babelES}[1]{\ifnum\pdfstrcmp{\languagename}{spanish}=0 {#1}\fi} 
\babelES{\renewcommand{\contentsname}{Contenido}}  

Bibliography

In lib/bibliography.tex, the bibliography feature is added to the document and (due to compatibility issues) either loads biblatex or natbib depending on whether you use XeLaTeX or pdfLaTeX. It also loads the actual bibliography file from the bibliography directory, depending on the language you have selected previously (see Chapter 17.1.2). The parameters of loading biblatex determine whether cited titles should be added to the index automatically (“indexing=cite”) and what citations look like. There are numerous possible combinations of the author name, the year of publication, and the title, each with different degrees of detail and verbosity. The setting authortitle in my template replaces citations with the author name followed by the title. Without the setting, the default would be a simple number that is referenced again at the back of the book in the bibliography.

At the end, the file also loads the nameref library. With it, you can reference the label of a chapter or section and get the chapter or section title in return. Instead of just referencing an abstract chapter number, adding the title helps the reader to know what you are talking about. Any changes to the referenced chapter or section title are automatically synchronized. For example, look at this code:

 
 
\chapter{My First Chapter}\label{c1_myfirstchapter:sec} 
Yesterday, I bought a car. 
\chapter{My Second Chapter}\label{c2_mysecondchapter:sec} 
Chapter ‘‘My First Chapter’’ discussed buying a car.  

If we changed the chapter title “My First Chapter” to “How I Bought My Car,” we would have to update the reference in the second chapter. With the \nameref{} command, this is no longer necessary:

                                                         
                                                         
 
 
\chapter{How I Bought My Car}\label{c1_myfirstchapter:sec} 
Yesterday, I bought a car. 
\chapter{My Second Chapter}\label{c2_mysecondchapter:sec} 
Chapter~\nameref{c1_mychapter:sec} discussed buying a car.  

Book Format

Next is lib/bookformat.tex. The first thing you notice is the long list of \usepackage commands with the one marked with 5.25” x 8” uncommented. Here is your choice of how large your book should be. This applies only to a printed version of your book. For e-books, the size of your book is determined by the device your reader will use.

 
 
\usepackage[paperwidth=13.34cm, paperheight=20.32cm, inner=0.80in, outer=0.3in, top=0.7in, bottom=0.5in]{geometry} % 5.25’’ x 8’’  

Did you know?


Why choose 5 x 8? Ratios like 5 x 8 are found throughout nature. We find them appealing because our perception is “calibrated” to find objects displaying this particular ratio. Why? In nature, the fundamental problem for plants is to get as much sunlight as possible. If the leaves are arranged according to a regular pattern, such as “Leaf / quarter-turn / leaf / quarter-turn, …” the leaves will overshadow one another. The challenge is to find an angle of rotation which can be continuously repeated so that no two leaves grow directly above one another (see Figure 17.1). Nature’s solution is using a Fibonacci number sequence (1, 1, 2, 3, 5, 8, 13, 21, …) to calculate the “golden ratio” (5/3, 8/5, 13/8, 21/13, …). → Read more in Philosophy for Heroes: Knowledge [Lode2016]


PIC
Figure 17.1: Optimal leaf arrangement

Personally, I like 5.25” x 8” but it is totally up to you. Look at your personal library (and take a ruler) and check out the different formats. Besides personal preference, the only thing to keep in mind is that smaller formats lead to more pages if you do not also reduce the font size (which is not recommended!). Amazon KDP supports all those formats, but if you decide to have the PDF printed by your local printer, first check which formats your local printer supports, otherwise you might have to do some redesigning.

Looking at the \usepackage[…]{geometry} command itself, you see the self-explanatory paperwidth and paperheight parameters, as well as four parameters to determine the space between the margins of the book and your text. Instead of parameters that determine left and right margins, you see the parameters inner and outer. Given the way paperback books are bound, the inner margin needs to be significantly larger, otherwise the reader would have difficulties reading the book. Also, printers are not 100% accurate, so you need to keep some safe space to account for printing errors.

The parameters as defined in the file work nicely for my books. Feel free to experiment with different settings, but make sure you keep them within the range the printing company (be it Amazon or another provider) has defined.

Fonts

If you want to adapt the typography, lib/fonts.tex is the place to look. It consists of:

  • Little tweaks for footnotes,
  • Line height for listings,
  • Space between paragraphs and paragraph indentation,
  • Font sizes for captions and the index,
  • Font of URLs,
  • Background color and font size of listings,
  • Typographical tweaks (microtypelmodern),
  • The selection of the font (libertine), and
  • A command that inserts blank pages.

The tweaks are universally recommended, although feel free to select a different font instead of libertine. As the typography is under the control of the specific device when reading an e-book, this applies to only the printable PDF, not the HTML (and thus e-book) output.

The \sloppy command is optional; it reduces the readability of some lines, but it ensures that no lines go beyond the left or right border (something that makes printing the book impossible). For further optimization, you could (after having finished the book using the sloppy command) replace it with the \fussy and manually fix any issues with text going beyond the border. Both commands change parameters of how to stretch spaces between words and how to handle hyphenation.

Chapter Design

For ease of use, you can use the command:

\begin{chapterpage}{title}{label}…\end{chapterpage}

which is loaded from lib/chapterpage.tex. It sets up the style of the chapter page, as well as the following blank page.

The actual design of the chapter page for the print version is changed in the file lib/chapterbox.tex. It replaces the standard chapter design and uses a full page with a border and the chapter title in large letters.

To reset the chapter page design to the default settings (for example, for all back matter chapters) with a simple headline with the chapter title and a horizontal line, use either \input{lib/chapterfont.tex} or \chapter instead of \begin{chapterpage}.

Header and Footer

In lib/headerfooter.tex, you can edit the style and content of the header and footer. The command:

\ihead[\headmark]{\headmark}\ohead{\pagemark}

puts the chapter or section title to the inside and the page numbers to the outside of a page. Whether left or right is “inside” depends on whether it is an odd or even page. If you are working on an e-book, you can safely ignore this command because pages of an e-book have no header, footer, or page number.

The next command, \automark[section]{chapter}, lets the title in the header alternate between the chapter title and section title. If you do not want the section to show up in the header, replace “chapter” with “section.” The third command redefines \headfont and causes the heading to be in small capitals and italics. Finally, the naming of the chapter is redefined, setting it to “Chapter X name of the chapter” without adding a period after the chapter number.

TikZ Initialization

TikZ ⋅ TikZ is a vector-based drawing language with which you can draw diagrams, charts, tables, fractals, etc.  in high resolution using minimal space.

In lib/inittikz.tex, the TikZ graphics system is loaded. Creating graphics in TikZ goes beyond the scope of this book, but we can help to get you started (see Chapter 14.9). For now, we will look only at the initialization.

After loading the basic TikZ packages (including the float package, which allows you to put a figure at a specific place in the text instead of having the LaTeX compiler decide), the style of various graphical elements is set up. For example, the text in the nodes of a diagram should have a small font, thick borders, and should be placed a certain distance from other nodes.

By default, TeX4ht exports TikZ graphics as vector graphic files (SVG files) and then loads them in the HTML file. Most modern browsers can show vector graphics, but the current e-book converters cannot. They work only with regular images, hence we need to change the behavior of TeX4ht. This is achieved by the code block at the end of the file. It causes all TikZ graphics to be exported into a cache folder, and then to be loaded again from there—as opposed to directly embedded into the PDF as vector graphics.

Long story short, we have to override the tikzpicture command to produce an external PNG file and load that in the HTML file. The PNG files are stored in the tikz-cache/ folder. Their resolution can be adapted by changing the density parameter value of the convert command.

Let us look at the details:

  • -extent 1245 This extends the transparent part of the graphic to 1,245 pixels. This means all converted TikZ vector graphics will have a width of 1,245 pixels.
  • -gravity center If the image is smaller than 1,245 pixels, this centers the graphic in the middle of the extended file.
  • -quality 100 Sets maximum compression for TikZ graphics. This reduces the file size, at the cost of an increased compile time.
  • -density 300 Sets the output to 300 dots per inch. This affects the effective size in pixels of the generated graphic.

Table of Contents

Turning to the next file, lib/tableofcontents.tex, we now arrive at more intricate programming. For the table of contents in the e-book, we need to insert code directly into the HTML output file. So, we check whether the current compiler supports \HCode (only TeX4ht supports that), and insert <nav> commands to tell Amazon that what follows now is the table of contents.

For the PDF output, in the case that \HCode is undefined, the command \KOMAoptions{open=…} changes on which side (left or right) the new chapter begins. The template is configured to start chapters on the right side by default (by using the documentclass scrbook—we will discuss this later). For the table of contents, I have decided to let it start on the left (even) page so that the reader can see the full contents of the book in one view. With the following command \KOMAoptions{open=right}, the original setting is restored. Finally, the page needs to be cleared and reset with an empty page style in order to hide the header—we do not want any page numbers in the table of contents section itself. This is accomplished by the command \thispagestyle{empty}\pagestyle{empty}\clearpage.

Boxes

After finishing my first book, Philosophy for Heroes: Knowledge , I found that it needed additional layers of information to accommodate different types of readers. After considering various options, I decided to add summary (idea) boxes at the end of each section, additional examples, biographies, questions for the reader, and boxes that provide a preview of future books in a series.

Building these boxes is the task of lib/boxes.tex. This file contains graphical elements you can add throughout your book and adapt to your needs. Please note that the box icons are not included in the template; upload them on your own and uncomment the relevant lines in lib/boxes.tex.

\begin{lstlisting}\end{lstlisting} In this environment, everything will be output as you wrote it. This is useful to print out code (like this paragraph) without having to replace all the slashes and braces. The \lstset command determines the formatting of the output, such as break lines at the end of the page, light gray background, indentation, and small font size.

\begin{problem}…\end{problem} For the print book, it creates a box with a question mark icon and the text “Question” at the top of the box. Use it at the beginning of a section to ask the reader a question that is answered in the text.

\begin{idea}…\end{idea} For the print book, it creates a box with a lightbulb icon and the text “Idea.” Use it to summarize the previous section and answer the question in the question box.


Example

\begin{example}\end{example} Creates a box with a book and test tube icon and the text “Example.” Use it for examples that deepen the understanding of the topic in question, but could be safely skipped.



Biography —Name

\begin{biography}{Name}\end{biography} Creates a box with a book and an identity card as an icon and the text “Biography.” Some readers want to know more about the people you are discussing in your book, while others want to skip that part. Creating a biography box will accommodate both types of readers. Note the additional parameter (the name of the person), use it like this: \begin{biography}{Alan Watts} Alan Watts was born in …\end{biography}.



Did you know?


\begin{preview}{bibliography id} …\end{preview} Creates a box with an opened book as an icon and the text “Did you know?” at the top. When referencing your previous books (or giving a preview of your future books), you can use these boxes as additional promotional space. It gives the reader an interesting bit to read and might make him or her curious enough to buy or pre-order your next book. Notice the additional parameter (the name of the book), use it like this: \begin{preview}{BBWLtAW} In my previous book …\end{preview}. → Read more in Better Books with LaTeX the Agile Way [Lode2019]


Definition ⋅  \begin{definition}{Term}\end{definition} Creates an indented block of text with a black bar to the left (for the PDF output) and the given parameter (the name of the term) in bold and small capitals. This can be used for glossary items to precisely define a concept you have written about in your text.

\begin{quotation} …\end{quotation} Creates an intended block of text with a quotation mark graphic in front of it. It signals that this is a quotation from another author. You can use this throughout your book, but I would recommend putting it at the beginning of a section to set the theme or to bring up a particular question.

Finally, we need to display multiple columns in the glossary with lib/multicolbalance.tex.

\begin{multicols}{number of columns}\end{multicols} Splits the text into several columns. This is the typical format of the glossary at the end of the book. Books with larger formats might use these throughout the book if necessary. The contents of the columns are balanced (as opposed to filling first the left column and then the right). For readability, the ideal number of columns is two.

Core Files

We already filled the folders main/back/front/biographies/examples/ideas/questions/glossary/, and images/ in Chapter 13. We will discuss the remaining files for the HTML conversion in the css/ and htlatex/ folder, as well as the latexmkrc and pgfsys-tex4ht.def files in the appendix in Chapter 24. Let us now take a look at the core files of a LaTeX project in the root directory. There you can find the entry file that initializes the language settings (output.tex), and the main project file that binds everything together and provides the structure of the book (main.tex).

As pointed out above in Chapter 17.1.2, in Overleaf, you can change the language of your project in output.tex. The parameters american or ngerman of the \usepackage{babel} command reflect this choice. Other than that, the following settings are configured:

  • \documentclass[ …]{scrbook}. This sets the document class of your project to a book, introducing odd and even pages with extra space in the middle for the binding. The standard document class is book, using scrbook instead loads several additional commands (the KOMA scripts) which we will be using throughout the template. For detailed documentation of the KOMA script, check out https://www.ctan.org/pkg/koma-script. In the template, the pagesize is set to auto, and the bibliography is set to totocnumbered so that it shows up in the table of contents.
  • \title{Title}. This sets the title of your LaTeX project. This title will not show up in the final document but is the name of the project listed in Overleaf.
  • \hyphenation{…}. Here, you can enter custom hyphenations for fine-tuning. The packages xspace and hyphenat are required for it to work. Not every word is known to LaTeX, and the rules differ between, for example, British and American English. With the hyphenation command, you can enter the hyphenation for special cases yourself. For example, in the Oxford dictionary, “everywhere” is hyphenated as “ev-ery-where” but it might look odd in your text, so you can add \hyphenation{every-where} to tell LaTeX to hyphenate only in the middle. For additional words, simply add them into the bracket: \hyphenation{every-where ti-ger la-tex kit-ten}. You do not need to add a comma or semicolon to separate additional words, just put a space before each new word.

Once the language is set up, the entry file loads lib/packages.tex and then goes into the main file main.tex which is split into five parts:

  • Preamble. For the PDF output, the index is initialized. E-books do not have indexes as they do not have fixed page numbers. Then, the document is started. Everything between \begin{document} and \end{document} is written to the output.
  • Front matter. Front matter pages are numbered with Roman numerals (i, ii, iii, iv, …) to set it apart from the main matter. The numbering begins on the title page (not the cover itself) with the command \frontmatter. The template is also set up to use only basic chapter title formatting (no fancy box) for all the chapters in the front matter. To hide page numbering on a certain page (for example, the title page), add \thispagestyle{empty} at the beginning of the page.We start with the half title page showing the title, and the title page with the book cover image when compiling it as a PDF. Then come the publisher, dedication, epigraph, and table of contents page. For the PDF version, we activate the chapterbox formatting to show fancy full-page chapter titles. Next, we show the foreword and the preface by the author.
  • Main matter. For the main matter, we switch back to numeric page numbering and insert all the chapter and section files. This is where the bulk of your writing will be added. This is also the place where you can move around or remove individual sections. For example, if you do not want a page with book advertisements, simply put the comment symbol (%) in front of \input{back/advertisement} and it will no longer appear in the output. Remember to use a separate tex file for each individual chapter. If you copied your entire book into the main.tex file, organization would become difficult.
  • Back matter. In the back matter, we show the reader how to proceed from here by advertising our other books and recommending additional books written by other authors. Next, we insert the author’s biography, as well as the story of how the book was created, giving the interested reader a look behind the curtain. We switch back to the basic chapter design and provide the reader with summaries of the boxes we used (question, idea, and glossary items), as well as a list of sources for the quotations (which we omitted in the text for better readability). Finally, the full bibliography is added.
  • Appendix. The appendix provides the reader with the index (for the PDF output), a reminder to write a short review online, and farewell words.

Again, you are free to move sections around as you see fit or even disable individual parts by commenting them out (adding a percentage % sign in front of the line). As you organize your book, think about what the reader would expect in a particular location of the book. While especially the front and back matter are more or less superfluous parts of a book, they also tell a story and give the reader a context to better understand what you have written in the main part of the book, and why.

This concludes the discussion of the template. In the remaining chapters, we will proceed to discuss how to polish both the e-book and the print version for release, especially when it comes to graphics, and how to publish the book via specific platforms.

While we have tested the template together with this book several times, you will likely encounter an issue not discussed here. Creating a document in LaTeX is more complicated than in Word. Remember: If you encounter any error or have a question about LaTeX in the template, please do not hesitate to contact us at [email protected] and we will see what we can do!

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

Categories
Editing LaTeX Publishing

Index Creation in LaTeX

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.

As opposed to their electronic counterparts, printed books do not have a search functionality to find specific words in the text. Instead, they have an index at the end as a service for the reader to quickly find certain parts of the book that he or she wants to read. If you are planning to publish only an e-book version of your book, you could skip this section—e-books do not have indexes because they do not have fixed page numbers: they are formatted differently on different devices. Keep in mind, though, that you might want to create a paperback edition at a later date and that your knowledge about your book is still fresh now. Even without a paperback edition, working on an index will help you to find possible keywords you could use for marketing, and it is a useful method of reviewing your book’s content paragraph by paragraph.

Unfortunately, there is no easy way to generate an index automatically—at least not in the quality a human can. Why is that?

Beyond merely listing all the concepts in a book, a good index is like an intelligent filter. The person creating the index has to think about what a reader might search for and list that word, even though it might never literally appear in the book. Likewise, if a concept consists of multiple words, it might be good to include both variations, for example, “language → mathematics” and “mathematics → language” to refer to the language of mathematics and mathematics as a language.

But how can LaTeX help in this regard? In traditional bookmaking, creating the index of a book is a separate process after the actual book is finished. You can imagine it basically as having the printed book in front of you, then going through page by page, noting which concepts appear on a particular page. This approach gets problematic if you want to make changes to the book that affect the page numbers: you would have to redo the entire index each time.

Indexing in Word

In Word, you can select the word or words you would like to use as an index entry and click on Mark Entry (on the References tab, in the Index group). A dialog shows up (see Figure 16.1) where you can configure the index entry (search for “Create and update an index” to find Microsoft Office help on this topic). Once done, Word switches into a hybrid mode that shows things like line breaks or index entries which are usually hidden (you can activate/deactivate the mode yourself by clicking on the ¶ button). If you want to edit an existing index entry, you have to edit the generated code. For example, the code for a subentry “mathematics” of the index entry “language” looks like this in Word:

 
 
Mathematics{*XE*"language:mathematics"*}  
PIC
Figure 16.1: Marking an entry to add it to the index in Microsoft Word.

Indexing in LaTeX

In LaTeX, insert the index command by adding the \index{…} directly into the text. For example, if you have the sentence “The yellow lab was voted America’s favorite dog again this year,” you could add two entries: “The yellow lab\index{yellow lab} was voted America’s favorite dog\index{favorite dog} again this year.” The page number that shows up in the index will then correspond to the place where you have inserted the index command. If the sentence “The yellow lab was voted America’s favorite dog again this year,” is printed on page 7 of the book, the index will show “yellow lab, 7” and “favorite dog, 7” assuming there is no mid-sentence page break.

The big question is: which words should you index? Let us look at an overall indexing strategy.

My approach in the first phase is to index all the terms that need to be indexed no matter what. Those are:

  • Names of persons. Whenever you mention (or quote) a person, add the index command after his or her name. The format for indexing someone’s name is \index{last name, first name middle name}, for example, \index{Darwin, Charles Robert}.
  • Media titles. Likewise, whenever mentioning a work of art (book, movie, software, etc.), add the index command after its title. If you have the title in your bibliography, \citetitle{bookid} does the job for you and adds the item automatically to the index. The “bookid” stands for the id you have given in the bibliography file. The exception to using \citetitle would be titles that start with an article (a, the) which is usually put at the end (e.g., Last Unicorn, The instead of The Last Unicorn). In those cases (or when you do not reference a book from your bibliography), use \index{title of the [email protected]\textit{title of the work}}. The “@” character is necessary for the indexing engine to recognize the italic font formatting.
  • Concept definitions. When introducing a concept and providing its definition (especially in glossary items), you want the reader to look at a particular passage before any other. When indexing, you can accomplish this by marking those entries in bold by adding “|textbf”: \index{word|textbf}. For example:  
    Science\index{science|textbf} is the formalized process of gaining new knowledge.  

Note that you must not index entries within captions of figures. This will cause problems during compilation. Instead, index the place where the figure is referenced in the text.

Once those basics are implemented, you move into the second phase. Here, you go from paragraph to paragraph and ask yourself each time what concepts are discussed. Add the first occurrence of each concept to the index. This paragraph-by-paragraph approach is the best compromise between accuracy and usability. You save time by adding a particular concept to the index only once per paragraph. The reader sees if a paragraph on a particular page spills over to the next page and will read on. The index page number basically says “start reading here until the paragraph is finished.”

If the same word is indexed in multiple paragraphs, LaTeX will combine them into a single index entry. That is, a single number if all occurrences are on the same page, or a list (or range) of pages where the concept is discussed (e.g., “5-7, 9”, “273-279, 401”, etc.).

To prevent confusing the reader with too many index entries, it is important to not index simply because a particular word is mentioned; the paragraph should explain something about the word or concept in question. Imagine the reader looking up the word in the index, going to the page, and then wanting to read what the word in question is about. For example, take the sentence “A republic is different than a democracy as it sets the constitution as its highest arbiter.” Of course, you would index “republic” in this sentence. But if you also indexed “democracy,” a reader will gain little value from it. From this sentence, the reader does not get any explanation of what democracy is about. If the sentence was instead “A republic is different than a democracy as it puts the constitution, not the people, as its highest arbiter,” the situation would be different. It describes (an aspect of) democracy. Of course, it is not a definition of democracy, so you would not mark it as bold in the index. Alternatively, you can also always use more general concepts in an index. Here, you could use “systems of government” instead of either republic or democracy, especially when you are just comparing different systems of government in that paragraph. Even if you never use the expression “systems of government” in your book, a reader will be satisfied reading the paragraph as it compares systems of government. As the following phases will only remove or combine indexes, it is safe to “overindex” in this second phase. You can even add multiple index entries for individual words. Using the example from above, you could add both “republic” and “systems of government.”

Once you are done with indexing individual words, in phase three, you can take a break and have your editor (or a friend) take the role of a reviewer. Alternatively, take an extended break and revisit your book one month later with a fresh mind. For the review, go one by one through the index, go to the page specified, and ask yourself if the passage really explains the concept. If not, remove the entry from the index.

Phase four then deals with cleaning up this “overindexed” index. Look at the index and see if you can find entries that can be combined. For example, you might find you have the following entries in your index: “Greek alphabet,” “Latin alphabet,” and “Phoenician alphabet.” Here you have to ask yourself if your readers might also search for “alphabet” or already have a specific language in mind. In my book Philosophy for Heroes: Knowledge , I decided for the former and combined the index entries into the category “alphabet” with “Greek,” “Latin,” and “Phoenician” as subcategories. This categorization can be done in LaTeX with the following construct:

 
\index{main category!subcategory}
 
                                                       
                                                         

In our example, use \index{alphabet!Greek}\index{alphabet!Latin}, and \index{alphabet!Phoenician}, respectively. You can also go one level deeper, although that should be the exception. For example, you could categorize “natural numbers in mathematics” as \index{mathematics!number!natural}. In both cases, LaTeX will automatically combine those three entries and arrange them together. With this in mind, I recommend reading a few indexes of the books in your library to learn how the authors combined their concepts. If you want to know more about the theory of knowledge and categorization of language in philosophy, check out Philosophy for Heroes: Knowledge , which explains it in detail.

Next, in phase five, you might want to explain to the reader the case of two different words in the index referring to the same concept. Maybe there is a popular expression for something and (in your field of work) the correct expression for something. In the index, you can point one expression to the other. For example, one application is when citing a person who has different names, maybe a real name and an artist name. Readers might look for either version of the name. For example, the mathematician Leonardo Bonacci is also known as Fibonacci. You might list both names and tell the reader that you are referring to the same person. If you used “Leonardo Bonacci” in your text, you could add an index entry with the following format: \index{one version of the word|see{other version of the word}}. In our case this would be “Leonardo Bonacci was a famous mathematician.\index{Bonacci, Leonardo}\index{Fibonacci|see{Bonacci, Leonardo}}.” Another example and a bit of an inside joke would be recursion: “If a statement relates to itself, it is called recursive.\index{recursion}\index{recursion|see{recursion}}.”

Finally, read through the entire index again to identify double entries, e.g., the same concept listed twice because of a misspelling. These can happen because the LaTeX commands are hidden in any PDF output you might be using for proofreading. That is it!

Here again are the steps of the index creation as a list:

  • Index all the basic terms (titles, people and place names, definitions).
  • Go through the entire text and index all the terms that are explained in a particular passage.
  • Check all index entries by going backward from the index to the text.
  • Combine index entries into groups.
  • Add references from one index entry to another (e.g., for people with several names).
  • Check for spelling errors.

This is an excerpt from Better Books with LaTeX the Agile Way. You can get a copy here.