stonewalljones / hfyebook Goto Github PK

* EPUB, which is convenient for people consuming the material using small form-factor
  devices like smartphones, dedicated ebook readers or smaller tablets.

* HTML for online self-publishing, embedding and interchange.

* LaTeX for creation of high-quality PDF output with LuaLaTex or XeLaTeX.

The following filters are included:

SOURCES:
    
    Source filters that fetch online resources cache the downloaded data in the
    'cache' directory. Clear the 'cache' directory to redownload the source material.
    
    Local files are not cached.

	* "from-local-html"
	    Read the chapter data from a local (X)HTML file, given a filename relative
	    to the root directory.

	* "from-local-markdown"
	    Read the chapter data from a local Markdown file, given a filename relative
	    to the root directory.

	* "from-hfy-archive"
	    Downloads and caches the chapter contents from a HFY Archive post given
	    a source URL.

	* "from-reddit-post"
	    Downloads and caches the chapter contents from a Reddit post given a source
	    URL. Since Reddits JSON API is used - so that post tagged NSFW can be
	    automatically retrieved - URL-shorteners (like http://redd.it) are not
	    supported. To use such resources, first resolve the actual Reddit link
	    by visiting the URL in a browser.

	    Submission continuations in comments are automatically detected and
	    concatenated with the main submission text before further processing.
	
	* "from-url"
		Downloads and caches the full response from an arbitrary URL. It is the
		responsibility of the user to insert additional filters in the processing
		chain that extracts the content, and presents it as a DOM that is useable
		with subsequent filters, if desired.

FILTERS:

	* "clean-reddit"
	    Removes HTML comment elements, CSS classes on any other element and
	    replaces any HTTP/HTTPS link to reddit with its text. Links to other
	    domains are retained.

	* "custom-break-to-hr"
	    Different series use a variety of ways to indicate breaks / segments or pauses
	    in the text. This filter harmonizes all known instances of this into <hr />
	    elements, which can then be further processed by the typography
	    filter (see below)

	* "finalize"
		Removal of DOM elements by other filters tends to leave surrounding text
		blocks containing newlines. This can lead to undesirable formatting in
		output formats where whitespace is not completely ignored (latex). This filter
		removes such blocks if and only if they're redundant (i.e. more than one
		such block occurs in a row). It also removes any completely empty paragraphs.
		
	* "no-preamble"
	    Removes any post content preceding the first horizontal rule, if the total
	    length of the content does not exceed 2500 characters. The threshold value
	    has been determined empirically and works for most of the content in the
	    test corpus.
	    The default maximum preable length can be changed with the parameter
	    "no-preamble-threshold", which can be specified for either the spec, one or
	    more chapters, or both. If both are specified, the chapter parameter takes
	    precedence (used by BatS).

	* "print-dom"
		Makes no changes, but displays a visual representation of the DOM at the
		point in the filtering chain in which it's inserted. Very handy for
		tracking down when and why undesirable DOM transformations are performed.
		
	* "typography"
	    Replaces opening and closing quotes and apostrophes with right / left versions,
	    replaces '...' with proper ellipsis, removes redundant, leading or trailing
	    horizontal rules and replaces the ones remaining with asterisms. Note that
	    unicode characters are used rather than HTML entities, since practically
	    all EPUB readers have problems rendering these correctly. Conversely,
	    not using entites can be correctly handled by all modern browsers.

	* Series-specific filters for the following:

	    * All Sapiens Go To Heaven
	    * Billy-Bob Space Trucker
	    * Blessed Are The Simple
	    * Builders In The Void: Peace / War
	    * Chrysalis
	    * Client Stone: Freedom / Rebellion
	    * Corridors
	    * Deathworld Origins
	    * Good Training
	    * Guttersnipe
	    * Henosis
	    * HFY Anthology
	    * Humans Don't Make Good Pets
	    * Memories of Creature 88
	    * MIA
	    * Pact
	    * QED
	    * Salvage
	    * The Deathworlders
	    * The Fourth Wave
	    * The Lost Minstrel
	    * The Salvation War: Amageddon / Pantheocide
	    * The Xiu Chang Saga
	    * Worm

    * epub:
        Emits an EPUB file in the root directory with the name [title].epub

    * latex:
        Emits a TEX file with the name [title].tex. The format is optimized for
        processing with lualatex, but xelatex can be used.
        
    * html:
        Emits a HTML file in the root directory with the name [title].html. The
        generated file has no external dependencies and can be uploaded or viewed
        as-is.

    * "title" (string):
        The chapter title. Used to generate headings and when building TOCs.

    * "byline" (string, optional):
        If specified, this will add an author byline to this chapter. This can
        be used to support collected content by various authors with full
        per-chapter attribution.

    * "src" (string):
        The source location of the material for the given chapter. This can
        be any value appropriate to the chosen input filter (see above).

	* "filter" (string, optional):
		If a set of filter chains have been specified, this reference to a chain
		by name is mandatory. This feature can be used to support multi-source
		or variably filtered content.

NOTE: It is possible to add aditional user-defined parameters to each chapter,
      which can be used to influence the operation of filters in the relevant
      processing chain. This has many potential uses, notably to sub-select
      chapter content in situations where content for multiple chapters
      originates from the same source URL. For an example of this, see the
      spec and content filter implementation for The Salvation War.

function apply(params, next);

* "params" (object)
    Represents the current task to be performed by the filter. Has two members:

    * "spec" (object)
        Represents the loaded specification file and contains members data as
        described above.

    * "chap" (object)
        A reference to the spec.contents elements this filter is to process (if
        used as a chapter filter), or null (if used as an output filter).

        In addition to the fields from above, it will be decorated by the
        following members:

        * "dom" (object)
            A Cheerio DOM object. For more information on how to work with
            Cheerio, refer to the documentation at:

            https://github.com/cheeriojs/cheerio

* "next" (function())
    A function that must be called by the filter when it completes and any
    modifications to "params.chap.dom" have been completed.

function apply(params, next)
{
    next();
}

module.exports =
{
    apply: apply
};

function apply(params, next)
{
    setTimeout(next, 1000);
}

function apply(params, next)
{
    var chap = params.chap;

    // Create the HTML DOM subsequent filters will operate on:
    chap.dom = cheerio.load('');

    // Create a unique (per book) id. This will be used both
    // as an XML/HTML element identifier and as a chapter filename
    // in the case of EPUB output, and is thus subject to the
    // union of the restriction imposed on all of the above. I suggest
    // ensuring that it contains only alphanumerics, dashes and underscores.
    chap.id = sanitize(chap.src);
}