From 652a90f0a8613ee3bc4112a69137730b5abd9938 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Fri, 2 Feb 2018 10:59:21 +1100 Subject: sb: Back port changes to support mailing list posting. Close #3287 --- .../website/publishing-ebooks-with-asciidoc.txt | 398 --------------------- 1 file changed, 398 deletions(-) delete mode 100644 source-builder/sb/asciidoc/examples/website/publishing-ebooks-with-asciidoc.txt (limited to 'source-builder/sb/asciidoc/examples/website/publishing-ebooks-with-asciidoc.txt') diff --git a/source-builder/sb/asciidoc/examples/website/publishing-ebooks-with-asciidoc.txt b/source-builder/sb/asciidoc/examples/website/publishing-ebooks-with-asciidoc.txt deleted file mode 100644 index 9d4d24c..0000000 --- a/source-builder/sb/asciidoc/examples/website/publishing-ebooks-with-asciidoc.txt +++ /dev/null @@ -1,398 +0,0 @@ -Publishing eBooks with AsciiDoc -=============================== -// Web page meta data. -:keywords: AsciiDoc, EPUB tools, EPUB, PDF, ebooks -:description: How to create EPUB and PDF ebooks using AsciiDoc. - -ifdef::blogpost[] -// Use the same article for both a blog post and on the AsciiDoc -// website. -:blogpost-title: Publishing eBooks with AsciiDoc -:blogpost-status: published -:blogpost-doctype: article -:blogpost-posttype: post -:blogpost-categories: AsciiDoc,eBook,EPUB,DocBook - -*Published*: 2010-08-23 + -*Updated*: 2010-05-08 -endif::blogpost[] - -It's easy to write and publish books in -http://en.wikipedia.org/wiki/EPUB[EPUB] and PDF formats using -http://www.methods.co.nz/asciidoc/[AsciiDoc]. -ifdef::blogpost[] -This article was originally published on the -http://www.methods.co.nz/asciidoc/publishing-ebooks-with-asciidoc.html[AsciiDoc -website]. -endif::blogpost[] - -Here are three examples: The first is a <> -introducing the AsciiDoc format, the second <> is a rather long multi-part book and the third <> includes a front cover image and -customized page styling. - -ifdef::blogpost[] -// Wordpress processing instruction. -pass::[] -endif::blogpost[] - -The examples presented below were created on a PC running Xubuntu -Linux 10.04 but should be applicable to any UNIX-based operating -system. - -NOTE: A number of 'asciidoc' and 'a2x' features used in this article -require newer versions of AsciiDoc -- version 8.6.5 or better is -recommended. The version of -http://wiki.docbook.org/topic/DocBookXslStylesheets[DocBook XSL -Stylesheets] used was 1.76.1. - -TIP: If you are experiencing 'xsltproc' errors when you run 'a2x' take -a look at Francis Shanahan's -http://francisshanahan.com/index.php/2011/fixing-epub-problem-docbook-xsl-asciidoc-a2x/[Fixing -the ePub problem with Docbook-XSL/A2X/Asciidoc] blog post. - - -[[X1]] -Minimal Book ------------- -This didactic example contains a title and two chapters. The AsciiDoc -source is a plain text file named `minimal-book.txt`: - ---------------------------------------------------------------------- -= The Book Title - -== The first chapter -Nec vitae mus fringilla eu vel pede sed pellentesque. Nascetur fugiat -nobis. Eu felis id mauris sollicitudin ut. Sem volutpat feugiat. -Ornare convallis urna vitae. - -Nec mauris sed aliquam nam mauris dolor lorem imperdiet. - -== The second chapter -Ut suspendisse nulla. Auctor felis facilisis. Rutrum vivamus nec -lectus porttitor dui dapibus eu ridiculus tempor sodales et. Sit a -cras. Id tellus cubilia erat. - -Quisque nullam et. Blandit dui tempor. Posuere in elit diam egestas -sem vivamus vel ac. ---------------------------------------------------------------------- - -To generate the EPUB formatted book file `minimal-book.epub` run -AsciiDoc's 'a2x' toolchain wrapper command from the command-line: - - a2x -fepub -dbook minimal-book.txt - -The `-f` option specifies the output format, the `-d` option specifies -the document type (book, article or manpage). The optional -`--epubcheck` option tells 'a2x' to validate the EPUB file using -http://code.google.com/p/epubcheck/[epubcheck]. To generate a PDF -version (`minimal-book.pdf`) with 'dblatex' run: - - a2x -fpdf -dbook minimal-book.txt - -The distributed example PDFs were built using FOP -- if you prefer -http://xmlgraphics.apache.org/fop/[FOP] over -http://dblatex.sourceforge.net/[dblatex] use: - - a2x -fpdf -dbook --fop minimal-book.txt - -You can also generate an HTML formatted book, either using DocBook XSL -Stylesheets: - - a2x -fxhtml -dbook minimal-book.txt - -or directly using the 'asciidoc' command: - - asciidoc -dbook minimal-book.txt - -[NOTE] -====== -The http://www.methods.co.nz/asciidoc/a2x.1.html[a2x toolchain -wrapper] uses the following programs (most will be available -prepackaged for your Linux distribution): - -- http://xmlsoft.org/XSLT/[xsltproc] -- http://docbook.sourceforge.net/projects/xsl/[DocBook XSL - Stylesheets] -- http://dblatex.sourceforge.net/[dblatex] (PDF file generator) -- http://xmlgraphics.apache.org/fop/[FOP] (alternative PDF file - generator) -- http://code.google.com/p/epubcheck/[epubcheck] (optional EPUB file - validator) -====== - - -[[X2]] -The Brothers Karamazov ----------------------- -'The Brothers Karamazov' is an example of a multi-part book. To -generate the AsciiDoc source I downloaded the -http://www.gutenberg.org[Project Gutenberg] plain text source and -edited it manually (this took around 15 minutes). To generate the -`brothers-karamazov.epub` EPUB file run this command: - - a2x brothers-karamazov.txt - -:examples-url: http://www.methods.co.nz/misc/examples/books/ - -[frame="topbot",options="header",caption=""] -.Brothers Karamazov source files and eBooks -|==================================================================== -|EPUB |PDF |AsciiDoc source |Project Gutenburg text -|{examples-url}brothers-karamazov.epub[brothers-karamazov.epub] - -|{examples-url}brothers-karamazov.pdf[brothers-karamazov.pdf] - -|{examples-url}brothers-karamazov.zip[brothers-karamazov.zip] - -|http://www.gutenberg.org/etext/28054 - -|==================================================================== - -Here's the start of the AsciiDoc source file showing the AsciiDoc -specific meta-data: - ---------------------------------------------------------------------- -// -// Text from Project Gutenburg http://www.gutenberg.org/etext/28054 -// -// Formatted for AsciiDoc by Stuart Rackham. -// -// a2x default options. -// a2x: -f epub -d book --epubcheck -// Suppress revision history in dblatex outputs. -// a2x: --dblatex-opts "-P latex.output.revhistory=0" -// Suppress book part, chapter and section numbering in DocBook XSL outputs. -// a2x: --xsltproc-opts -// a2x: "--stringparam part.autolabel 0 -// a2x: --stringparam chapter.autolabel 0 -// a2x: --stringparam section.autolabel.max.depth 0" -// - -= The Brothers Karamazov -:author: Fyodor Dostoyevsky -:encoding: iso-8859-1 -:plaintext: - -.......................................................................... -Translated from the Russian of Fyodor Dostoyevsky by Constance Garnett -The Lowell Press New York - - : - : - -***START OF THE PROJECT GUTENBERG EBOOK THE BROTHERS KARAMAZOV*** -.......................................................................... - - -= PART I - -== The History Of A Family - -=== Fyodor Pavlovitch Karamazov - -Alexey Fyodorovitch Karamazov was the third son of Fyodor Pavlovitch -... ---------------------------------------------------------------------- - -- The book, book part and chapter titles have been edited to conform - to http://www.methods.co.nz/asciidoc/userguide.html#X17[AsciiDoc - title conventions]. - -- Book part titles must be level zero titles: - - = Book title (level 0) - = Part one title (level 0) - == Chapter 1 title (level 1) - : - -- Sub-chapter levels can be accommodated with `===`, `====` and - `=====` title prefixes. - -- In this example the 'Project Gutenberg' front matter was put in the - untitled preface inside an AsciiDoc literal block. - -- The comment lines starting with `// a2x:` contain 'a2x' command - options for this document (it's easier to put them in the document - once than type them every time on the command-line). - -- A number of 'xsltproc' options are passed to 'a2x' to suppress book - part, chapter and section numbering. - -- Setting the AsciiDoc 'plaintext' attribute suppresses most of - http://www.methods.co.nz/asciidoc/userguide.html#_text_formatting[AsciiDoc's - text formatting] and substitution conventions, this allows large - amounts of text to be imported with little or no manual editing. - - * Once you have defined the AsciiDoc 'plaintext' attribute the only - requisite manual editing will be to format the titles and rectify - the odd paragraph being interpreted as some other AsciiDoc block - element. - * In the combined 49 thousand lines of imported 'Sherlock Holmes' - and 'Brothers Karamazov' text I only encountered two - misinterpreted list items, neither affected the rendered output or - necessitated editing. - * You can selectively enable and disable the 'plaintext' attribute - throughout your document using AsciiDoc - http://www.methods.co.nz/asciidoc/userguide.html#X18[attribute - entries]. - - -[[X3]] -The Adventures of Sherlock Holmes ---------------------------------- -This book includes a front cover image and a customized page design. -To generate the `adventures-of-sherlock-holmes.epub` EPUB file run -this command: - - a2x adventures-of-sherlock-holmes.txt - -[frame="topbot",options="header",caption=""] -.Sherlock Holmes source files and eBooks -|==================================================================== -|EPUB |PDF |AsciiDoc source |Project Gutenburg text -|{examples-url}adventures-of-sherlock-holmes.epub[adventures-of-sherlock-holmes.epub] - -|{examples-url}adventures-of-sherlock-holmes.pdf[adventures-of-sherlock-holmes.pdf] - -|{examples-url}adventures-of-sherlock-holmes.zip[adventures-of-sherlock-holmes.zip] - -|http://www.gutenberg.org/etext/1661 - -|==================================================================== - -Here's a screenshot of the first page of the first chapter (rendered -by the http://www.epubread.com/en/[Firefox EPUBReader addon]): - -image::images/epub.png[] - -The {examples-url}adventures-of-sherlock-holmes.zip[AsciiDoc source -Zip file] contains the following files: - -`adventures-of-sherlock-holmes.txt`:: - The AsciiDoc source (derived from the - http://www.gutenberg.org/etext/1661[Project Gutenberg plain text - source]). - -`adventures-of-sherlock-holmes.jpg`:: - The front cover image. - -`adventures-of-sherlock-holmes-docinfo.xml`:: - A http://www.methods.co.nz/asciidoc/userguide.html#X87[docinfo] file - containing DocBook markup for the front cover image and the Project - Gutenberg frontmatter. DocBook XSL Stylesheets identifies the book - cover image by the `role="cover"` attribute in the DocBook - `mediaobject` element. - -`adventures-of-sherlock-holmes.css`:: - CSS rules for styling the page layout. The design is based on the - http://epubzengarden.com[ePub Zen Garden] 'Gbs' style. Because this - file is not named `docbook-xsl.css` the name must be specified - explicitly using the 'a2x' `--stylesheet` option. - -`underline.png`:: - A title underline image that is used by the CSS stylesheet. This - resource has to be explicitly passed to 'a2x' because 'a2x' only - searches HTML files for resources. - -Here's the start of the AsciiDoc source file showing the AsciiDoc -specific meta-data: - ---------------------------------------------------------------------- -// -// Text from Project Gutenburg http://www.gutenberg.org/etext/1661 -// -// Formatted for AsciiDoc by Stuart Rackham. -// -// a2x default options. -// a2x: -f epub -d book -a docinfo --epubcheck -// a2x: --stylesheet adventures-of-sherlock-holmes.css -// Suppress revision history in dblatex outputs. -// a2x: --dblatex-opts "-P latex.output.revhistory=0" -// Suppress book part, chapter and section numbering in DocBook XSL outputs. -// a2x: --xsltproc-opts -// a2x: "--stringparam part.autolabel 0 -// a2x: --stringparam chapter.autolabel 0 -// a2x: --stringparam section.autolabel.max.depth 0" -// Additional resources. -// a2x: --resource underline.png -// - -= The Adventures of Sherlock Holmes -:author: Sir Arthur Conan Doyle -:encoding: iso-8859-1 -:plaintext: - -== A Scandal in Bohemia - -To Sherlock Holmes she is always THE woman. I have seldom heard -... ---------------------------------------------------------------------- - -The manual editing of imported plain text involves formatting the -title and chapter names as -http://www.methods.co.nz/asciidoc/userguide.html#X17[AsciiDoc titles] -(in this example we've used the 'single line' title format). Sherlock -Holmes only has two title levels: - ---------------------------------------------------------------------- -= The Adventures of Sherlock Holmes -== A Scandal in Bohemia -== The Red-Headed League -== A Case of Identity -== The Boscombe Valley Mystery -== The Five Orange Pips -== The Man with the Twisted Lip -== The Adventure of the Blue Carbuncle -== The Adventure of the Speckled Band -== The Adventure of the Engineer's Thumb -== The Adventure of the Noble Bachelor -== The Adventure of the Beryl Coronet -== The Adventure of the Copper Beeches -== Colophon ---------------------------------------------------------------------- - - -Styling your books ------------------- -You can customize the appearance of a document with CSS. CSS file. -Either create your own or copy and edit the existing default -`docbook-xsl.css` file (located in the AsciiDoc `stylesheets` -configuration directory) then place it in the same directory as your -AsciiDoc source file. Use the 'a2x' `--stylesheet` option if you want -to use a different stylesheet file. Take a look at the -`adventures-of-sherlock-holmes.css` CSS file. - -There are some great examples of EPUB book styles at -http://epubzengarden.com/[ePub Zen Garden]. - - -Including embedded fonts ------------------------- -See http://www.methods.co.nz/asciidoc/faq.html#X5[this FAQ]. - - -Reading EPUB documents ----------------------- -My current favorite software epub reader is the -http://www.epubread.com/en/[Firefox EPUBReader addon]. EPUBReader -honors the book's CSS styling rules and renders the page as the author -intended (many EPUB readers only process a sub-set of CSS styling -rules). - -Browsers are a natural fit for EPUB (EPUB is just a bunch of zipped -XHTML files) -- I'd love to see browsers support EPUB natively. - -As of writing this article most eBook readers (with the notable -exception of Amazon's Kindle) support the EPUB format. - - -Non-fiction Books and Manuals ------------------------------ -AsciiDoc supports a rich set of markup conventions and can generate -reference works and technical manuals complete with tables, -illustrations, indexes, bibliographies and appendices. All the -examples on the http:///www.methods.co.nz/asciidoc/[AsciiDoc web site] -can be formatted as EPUB eBooks. - -- cgit v1.2.3