Repository files navigation

BookGen is a makefile which can be used to generate a wide variety offormats from a per‐chapter Markdown source.It is designed to ease the technical aspects of publishing electronicdocuments so that authors can focus on simply writing.

In order to use BookGen, you will need to make or acquire.css and/or.cls styles, which will be used to format your work.Some styles which are known to work with this version (0.9.0) ofBookGen are :—

• FellStyle:An oldfashioned layout for documents.Primarily aimed at PDF/print documents, but supports HTMLgeneration as well.

• SerialStyle:Somewhat minimal HTML and PDF styles intended for serialized works.

• ArchiveStyle:HTML‐only style modelled afterArchive of OurOwn.

TheBookGen organization README providesa broad overview of how to set up and install BookGen and itsaccompanying styles.

BookGen uses Pandoc under‐the‐hood; click to read aboutPandoc’sapproach to Markdown.In contrast with normal Pandoc, BookGen doesnot perform automaticquote‐ or dash‐substitutions; it is expected that you write what youmean in your Markdown source.

BookGen runs on the command line; consequently, basic understanding ofhow to use a terminal emulator is advised.Basic LaTeX knowledge will help in debugging PDF generation andensuring good output, but is (hopefully) not required.

BookGen is designed for GNU Make 3.81, and will hopefully work withthis and any later version.It willnot work properly with earlier versions of GNU Make, or withothermake programs.

You can test which version ofmake you have by runningmake -v.On my device, I get the following output :—

GNU Make 3.81Copyright (C) 2006  Free Software Foundation, Inc.This is free software; see the source for copying conditions.There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR APARTICULAR PURPOSE.This program built for i386-apple-darwin11.3.0

As you can see from the first line, I am running GNU Make 3.81.

If your version of make is out‐of‐date (or nonexistent), you candownload a new one by following the directions here :—https://www.gnu.org/software/make/

In addition to GNU Make, you will need to make sure you have thefollowing installed on your computer :—

• For general usage :—
  • pandoc (version 2.8 or higher)
    • This is what BookGen uses to process Markdown and generateLaTeX and HTML documents
    • You will needpandoc-citeproc if you are planning on using abibliography
    • Seehttps://pandoc.org/installing.html for installationinstructions
    • Usepandoc -v to see if you already have it installed
  • Python 3, including the following packages :—
    • panflute (can be installed withpip3 install panflute; seehttp://scorreia.com/software/panflute/install.html)
    • This is required for running the various filters which transformyour document into their final state.
    • Seehttps://www.python.org/downloads/ for installationinstructions.
    • Usepython3 -V to see if you already have it installed
• For PDF generation :—
  • TeX, LaTeX, XeTeX, etc…
    • I useTeXLive (or, more properly,MacTeX)
    • xelatex is the recommended LaTeX command, and the default
    • Usexelatex -v to see if you already have it installed
• For PNG generation :—
  • Everything required for PDF generation (PNGs are built from PDFs)
  • GhostScript
    • Seehttps://ghostscript.com/
    • For macOS, MacTeX offers their own GhostScript package here, ifyou didn’t install it as part of MacTeX :—http://www.tug.org/mactex/morepackages.html
    • Usegs -v to see if you already have it installed
  • ImageMagick
    • Seehttps://imagemagick.org/
    • For macOS, you may want to useHomebrew(brew install imagemagick)
    • Usemagick -version to see if you already have it installed
  • pdftotext
    • A part of the Xpdf command line tools available here :—http://www.xpdfreader.com/
    • For macOS, you may want to useHomebrew(brew install xpdf)
    • Usepdftotext -v to see if you already have it installed
• For zip generation:
  • Zip
    • Seehttp://infozip.sourceforge.net/Zip.html
    • Comes preinstalled on many platforms
    • Usezip -v to see if you already have it installed

Generally speaking, you will not want to use your BookGen installationas your working directory, but rather install it somewhere else (as asubdirectory or in another location on your computer) and then callit remotely (from the command line or from another Makefile).

To install,git clone this repository someplace you will be able tofind it later :—

git clone https://github.com/marrus-sh/BookGen.git

You can then update BookGen to the latest version at any time with :—

git pull

If you don't want to usegit, simply download and unzip thisrepository from GitHub.

Within your project, source files are principally located in twofolders :—Markdown/, which will contain the markdown texts of theproject, andStyles/, which will contain.css and.cls files touse when rendering your source into various formats.In addition to these, you will need aninfo.yml file, specifyingmetadata about the project as a whole.SeeCONFIGURING.md for more on the contents of thisfile.

There are three types of source text you can create :—

• Chapter files, located atMarkdown/Chapters/$N.md, where$N isa two‐digit number identifying the chapter, optionally followedby a hyphen and some text.Do not use ascii spaces!!

• Appendix files, located atMarkdown/Chapters/A$N.md, where$Nis a two‐digit number identifying the appendix, optionallyfollowed by a hyphen and some text.Do not use ascii spaces!!

• Standalone files, as all other.md files in theMarkdown/directory.Do not use ascii spaces!!Standalone files cannot be placed in any subdirectories, and aretreated as frontmatter.These are ordered alphabetically, but you can of course manuallyadjust the ordering by prefixing them with a number.

A sample project (prior to running this Makefile) might look asfollows :—

Markdown/  Chapters/    01.md    02.md    03.md    04.md    05.md    A01.md  Foreword.md  Preface.mdStyles/  MyStyle.cls  MyStyle.cssinfo.yml

This being a Makefile,you should not use colons, semicolons,parentheses, or spaces in filenames.Ascii special characters in general should be avoided (non‐asciicharacters should be fine).You also should not create source files atMarkdown/index.md orMarkdown/text.md without adjusting theINDEX orFULLTEXToverrides, respectively.Finally, style names which are the same as an existing argument definedby this makefile (html.css,latex.cls, etc.) are not supported,as they would otherwise make compiling by style ambiguous.

There are a few added features you can take advantage of in yourMarkdown for special formatting and display :—

• A Div with a class ofchapterprecis can be used at the beginningof a chapter to insert a chapter precis :—

  #My Chapter::: chapterprecis :::| A very good chapter,| Yes, very good indeed.:::::::::::::::::::::

• A Div with a class ofverse can be used for verse.

  If you also set the classalternating, then every other line willbe indented :—

  ::: {.verse .alternating}| A couplet writ in very little time,| With indentation on this second line.:::

  Alternatively, you can use an empty Span with a class ofindentto manually indent verse lines :—

  ::: verse :::| There once was a limerick, quite good,| And people assumed that it would|[]{.indent}End with some joke|[]{.indent}About some poor bloke,| But I don't see whyfor it should.:::::::::::::

• A Div with arole ofnote can be used for notes :—

  ::: {role=note}This is a note.:::

• A Div with a class ofcontinuation can be used to create aparagraph which continues from the previous, useful if ablockquote or line of verse comes between them :—

  To quote Light Yagami from <cite>Death Note</cite>,>This useless Pride, I suppose I'll have to… Get Rid of It!::: continuation :::(as translated by the English dub).::::::::::::::::::::

• A Div with a class ofplain, which contains only one paragraph,can be used to "unwrap" the paragraph (so that no<p> tag isused) :—

  ::: plain :::This will not use a`<p>` tag.:::::::::::::

• A Div or Span withdata-from-metadata set will have its contentsreplaced by the corresponding metadata value, if set.This is especially useful for localization :—

  See[Chapter]{data-from-metadata="localization-type-chapter"} 02.

• A Span with a class oflettrine can be used for leading text.An initial span will produce a drop cap :—

  [[T]{}his is the beginning]{.lettrine} of a section of text.

• A Span with adata-colour (ordata-color) attribute can be usedto set the text colour.This can be either a 6-digit HTML hex value or an SVG colour name.In the latter case, the name must be properly capitalized :—

  Some[red]{data-colour=#FF0000} and[blue]{data-colour=MidnightBlue} text.

• A Span with adata-font attribute may be used to manually set thetext font.Which values are supported depends on your current style.

  This is[fantastic]{data-font=fantasyfont}.

• An empty Span with a class ofat can be used to generate a\@for sentence-spacing adjustment in LaTeX.This is only necessary if you are generating PDFs with a stylewhich does not use\frenchspacing:

  Reading Rainbow, Mr.[]{.at} Rogers, etc.[]{.at} are all fond  memories for I[]{.at}.

• A raw HTML block of the form<hr/> represents aplain (unfancy) break.

Although these are standard BookGen features, full support may dependon your selected style.Furthermore, your style may have additional features besides these.

You can use citations and/or a bibliography with Pandoc by specifyingit via theBIBLIOGRAPHY override.This must be a BibLaTeX bibliography file with the extension.bib.By default, the Chicago Manual of Style notes-bibliography style isused for citations.

All entries which appear in your bibliography will be printed,regardless of whether you actually cite them in one of your texts.

TheWikibooks page on LaTeX bibliographymanagementmay be useful in learning the overall structure of a.bib file.

make [❲make-options❳] [❲args❳] [❲options❳] [❲overrides❳]

If you are callingmake from your work directory, you will want tospecify the-f option with the path toGNUmakefile.Conversely, if you are callingmake from this directory, you willneed the-C option to specify the work directory in which tooperate.

There are two other❲make-options❳ which are likely to be of use toyou :—-B will consider all targets out‐of‐date (and consequently remakeeverything), and-s will runmake in “quiet mode” to avoidcluttering up your console.

The⟨args⟩ you provide will determine which files to make.If blank, this is the same asall.

If you only want a specific file to be generated, you can specify itsfile name as an argument (for example,HTML/$style/$file.xhtml).Of course, there are a number of more generalized arguments you can useto generate multiple files at once.

Arguments:md,markdown

Unless you have theDRAFTS override set, this only creates zip filesof your markdown source, unless theNOARCHIVE option is toggled, inwhich case this does nothing.If theDRAFTS override is set, this will create all of the symlinksin theMarkdown/ directory.

Arguments:latex,tex

LaTeX files are generated with a.tex extension in theLaTeX/directory.These arenot complete files (they do not have a\begin{document}),but rather are intended to be\included into other documents.This process happens automatically when you use this makefile togenerate a PDF.

Arguments:tex.hs

Native AST files for debugging LaTeX generation.

Arguments:tex.json

JSON files for debugging LaTeX generation.

Arguments:htm,html,html5,xht,xhtml,xhtml5,xml

HTML files will be placed in theHTML/$style/ directory, where$style is the name of the stylesheet used to generate the file.By default, this will run for every.css stylesheet defined in theStyles/ directory; you can limit it to particular stylesheets usingtheSTYLE override.

If theALLSTYLES option is provided, then all of the styles will beavailable in every HTML document, as alternative stylesheetsspecified by using thetitle attribute on the<style> element.Note that currently only Firefox actually provides a mechanism fortoggling between alternative style sheets.

Each generated file is a standalone (X)HTML file (embedded CSS) with an.xhtml extension.A table of contents file will also be generated; see theINDEXoverride for the name of this file.

Arguments:xhtml.hs

Native AST files for debugging HTML generation.

Arguments:xhtml.json

JSON files for debugging HTML generation.

Arguments:pdf

PDF files are generated with a.pdf extension in thePDF/$style/directory, where$style is the name of the stylesheet used togenerate the file.By default, this will run for every.cls stylesheet defined in theStyles/ directory; you can limit it to particular stylesheets usingtheSTYLE override.

Styles need to bememoir extensions as some of the Markdown to LaTeXconversions take advantage ofmemoir features.In particular, horizontal rules will be transformed into a\pfbreak.Blockquotes use thequoting environment, which will be loadedautomatically (but which you may want to configure in your style).

Arguments:png

PNG files are generated, one per page, with a.png extension in afolder in thePNG/$style/ directory, where$style is the name ofthe stylesheet used to generate the file.By default, this will run for every.cls stylesheet defined in theStyles/ directory; you can limit it to particular stylesheets usingtheSTYLE override.

Anindex.html file will be placed in the folder containing the PNGs,which you can open in any browser with JavaScript enabled to browsethem.BookGen will attempt to generate proper alt‐text for this file from thePDF for each PNG, using GhostScript.

Arguments:dist,zip

Using thedist orzip arguments will generateevery zip.However, zip files will also be created when you use another genericargument (likehtml) unless theNOARCHIVE option is set.Zip files are generated in theZip/ directory, matching the directorystructure of the files they contain.

There are a few special arguments which don't just generate a singletype of file:

• all oreverything :—This is the same as specifyingmd xhtml tex pdf png.

• clean :—Removes the build directory and temporary build files.

• hs ornative :—This is the same as specifyingxhtml.hs tex.hs.

• json :—This is the same as specifyingxhtml.json tex.json.

• unclean :—Removes theLaTeX/,HTML/,PDF/,PNG/, andZip/directories.Also removes theMarkdown/ directory if theDRAFTS override isset.These are the directories which contain files generated by thismakefile.

• clobber,distclean, orgone :—This is the same as specifyingclean unclean.

Finally, you can use a specific style name (the name of a file inStyles/) to compile all of the formats which make use of thatstyle.

❲options❳ are a special kind of makefile override which are eithertrue (if set to any nonempty value) or false (the default).The available options to you are as follows :—

• ALLSTYLES :—Embed every CSS stylesheet in every HTML document.Note that only the filter provided by the primary stylesheet (ifapplicable) will be run, so the effectiveness of this option mayvary.

• NOARCHIVE :—Do not generate zips (unless specifically requested, e.g. with thezip argument).

• VECTORIZE :—Vectorize the final PDFs instead of leaving them with embeddedfonts.Specifying this option may help with fonts which do not play nicelywith printers.However, this will disable text selection on computers, so youshould not use this option when compiling for digitaldistribution.

• VERBOSE :—Shows verbose output; especially useful for debugging LaTeX.

There are a number of❲overrides❳ which can be used to furtherconfigure themake.These are :—

• APPENDIXPREFIX :—The prefix for appendixes.Defaults to$(CHAPTERPREFIX)A.Must not contain colons or spaces.

• BIBLIOGRAPHY :—The name of the work's bibliography file, which must have a suffixof.bib.Requiresbiber to process.

• BIBREQUIRE :—The arguments to\RequirePackage/\usepackage for the properbibliography package to use in LaTeX.Defaults to[notes,annotation]{biblatex-chicago}.

• BUILD :—The directory in which to place LaTeX build files.Defaults toBuild.

• CHAPTERPREFIX :—The prefix for non‐appendix chapters.Defaults toChapters/.Must not contain colons or spaces.

• DRAFTS :—If nonempty, automatically symlinks in theMarkdown/ folder tothe last file in the equivalent folder in the specifieddirectory.For example,DRAFTS=Drafts will symlinkMarkdown/Chapters/01 toDrafts/Chapters/01/$N.md.If you use this, you should not place files in theMarkdown/directory, as it will be deleted ongone.Defaults to empty.

  As a standard makefile limitation, symlinks will not update if theyare more recent than the files they “should” be pointing to(especially relevant in the case that they once pointed to anewer file which was deleted).Simply delete any outdated symlinks to force their regeneration.

• FULLTEXT :—The name to use for the fulltext PDF/PNG file(s).Defaults totext.Naturally, it will cause problems if you have a source file withthe same name as this file.

• HTML :—The directory in which to place HTML files.Defaults toHTML.

• INDEX :—The name to use for outputted index files.Defaults to$(CHAPTERPREFIX)index.Naturally, it will cause problems if you have a source file withthe same name as this file.

• LATEX :—The directory in which to place LaTeX files.Defaults toLaTeX.

• MARKDOWN :—The directory in which to find/place Markdown files.Defaults toMarkdown.

• PDF :—The directory in which to place PDF files.Defaults toPDF.

• PNG :—The directory in which to place LaTeX files.Defaults toPNG.

• FILEPREFIX :—A prefix to prepend to theMarkdown,LaTeX,HTML,PDF,PNG, andZip folders on input and output.Empty by default.

• STYLE :—The names of the styles to compile.If empty, every style available for a given type will be used.Empty by default.

• STYLES :—The directory in which to find style files.Defaults toStyles.

• YAML :—The name of the YAML metadata file.Defaults toinfo.yml.

• ZIP :—The directory in which to place Zip files.Defaults toZip.

The following❲overrides❳ can be used to point to the specificprograms required by BookGen :—

• BIBER (biber):biber
• CITEPROC (pandoc-citeproc):pandoc-citeproc
• CONVERT (ImageMagick):magick
• GS (GhostScript):gs
• INFOZIP (Zip):zip
• PANDOC (Pandoc):pandoc
• PDFTOTEXT (pdftotext):pdftotext
• TEX ([Xe]LaTeX):xelatex

You may want toinclude this makefile from another one, for examplein your work directory, to avoid having to directly use the-C or-f options.In this case, you will need to override thesrcdir variable toproperly point to this directory from the other makefile.For example, you might configure a makefile as follows :—

overridesrcdir := BookGeninclude$(srcdir)/GNUmakefile

You can naturally include any number of other overrides in this file aswell.Here is one sample configuration :—

# Default make.default: html pdf;# The path to the BookGen source.overridesrcdir := BookGen# Overrides.overrideAPPENDIXPREFIX := Appendices/overrideBIBLIOGRAPHY := bibliography.biboverrideDRAFTS := Drafts/overrideFULLTEXT := my-amazing-storyoverrideINDEX := contents# BookGen rule imports.include$(srcdir)/GNUmakefile

If you save such a file asMakefile (orGNUmakefile) in your workdirectory, then you need only callmake to compile your project.

If you have other build tasks which you need to complete, a simpleinclude may not work for you.In this case, a match‐anything pattern rule can be used to achieve thesame effect.You don't need to overridesrcdir with a match‐anything pattern rulebecause it will properly be inferred through callingmake thesecond time :—

Makefile: ;%: ; @$(MAKE) -ef BookGen/GNUmakefile$@

Setting the-e flag allows you to export options and overrides fromthe parent makefile.Be sure to always writeGNUmakefile with correct capitalization.

This Makefile began as an extension of my work onDeluxe Makefile forLaTeX,to allow it to be used in conjunction with Pandoc to generatedocuments of a variety of filetypes.After hacking together solutions for a number of projects, I decided towrite a new, comprehensive makefile which was much more robust.

The filechicago-note-bibliography-16th-edition.cslis licensed under a Creative Commons Attribution-ShareAlike 3.0License, as specified in that file.

The fileMakefile.sty is licensed under the LaTeXProject Public License; see that file for more information.

The filestorytime.html is licensed under theUnlicense.

All other files in this repository are licensed under the terms of theMozilla Public License, version 2.0.For more information, seeLICENSE.