contents/glyph/book/compiling/compiling.html
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 |
----- title: "Glyph – Compiling a project" content-type: page ----- <nav class="navigation"><a href="/glyph/book/text_editing/evaluation.html">← Simple Programming and Code Evaluation</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/compiling/lite_mode.html">Compiling single Glyph files →</a></nav> <p>By default, a Glyph project can be “compiled” into an <span class="caps">HTML</span> document. Additionally, Glyph can also be used to produce documents in the following formats:</p> <ul> <li>HTML5</li> <li><span class="caps">PDF</span> (generated from <span class="caps">HTML</span> using a third-party generator like <a href="http://www.princexml.com/">Prince</a> or <a href="http://code.google.com/p/wkhtmltopdf/">wkhtmltopdf</a>)</li> <li>Web (i.e. multiple <span class="caps">HTML</span> files)</li> <li>Web5 (i.e. multiple HTML5 files)</li> </ul> <section class="section"> <header><h1 id="h_50" class="toc">HTML/HTML5 output</h1></header> <p>To compile a Glyph project to an HTML document, use the <a href="/glyph/book/ref_commands.html#c_compile"><code>compile</code></a> command within your Glyph project folder. Glyph parses the <code>document.glyph</code> file (and all included files and snippets); if no errors are found, Glyph creates an HTML document in the <code>/output/html</code> folder.</p> <p>The name of the HTML file can be set in the configuration (<a href="/glyph/book/config/document.html#s_document_filename"><code>document.filename</code></a> setting).</p> <p>To create an HTML5 file instead, you must specify it explicitly like this:</p> <p> <code> glyph compile -f html5 </code> </p> </section> <section class="section"> <header><h1 id="h_51" class="toc">PDF Output</h1></header> <p>To generate a PDF document, you must specify <code>pdf</code> as format, like this:</p> <p> <code> glyph compile -f pdf </code> </p> <p>The command above will attempt to compile the project into an HTML document and then call a third-party PDF generator to convert it into a PDF file.</p> <p>Currently, Glyph supports:</p> <ul> <li><a href="http://www.princexml.com/">Prince</a> (version 7.0 or higher) — a commercial generator that can be used freely for personal use. Prince produces high-quality <span class="caps">PDF</span> files and implement most of the new features introduced in CSS3, used heavily in Glyph’s <a href="/glyph/book/text_editing/stylesheets.html#default_stylesheets"><code>pagination.css</code></a> default stylesheet.</li> <li><a href="http://code.google.com/p/wkhtmltopdf/">wkhtmltopdf</a> (version 1.0 beta4 or higher) — an open source generator that uses the WebKit rendering engine to transform <span class="caps">HTML</span> files into <span class="caps">PDF</span>. Although not as advanced as Prince, it produces very satisfactory results.</li> </ul> <p>By default, Glyph attempts to use wkhtmltopdf. To change this, set the <a href="/glyph/book/config/output.html#s_output_pdf_generator"><code>output_pdf_generator</code></a> setting to <code>prince</code>.</p> <aside class="note"> <span class="note-title">Note</span>Glyph expects PDF generators to be installed on the local machine and callable via command line using the <code>wkhtmltopdf</code> or the <code>prince</code> commands. Just install them as you would with any other program, depending on your operating system (yes, they both offer Windows installers). </aside> </section> <section class="section"> <header><h1 id="h_52" class="toc">EPUB/MOBI output</h1></header> <p>To generate .epub or .mobi e-books, you must specify <code>epub</code> or <code>mobi</code> as format, like this:</p> <p> <code> glyph compile -f mobi </code> </p> <p> <code> glyph compile -f epub </code> </p> <p>This option requires that you have <a href="http://calibre-ebook.com/">Calibre</a> and its command-line tools installed. Glyph assumes the ebook-convert command is installed in /usr/bin. If this is not so, you can set the <code>options.ebook.converter</code> option to the path to the ebook-convert command.</p> <p>If you have cover art for your e-book, put it in the <code>images</code> folder, and specify the name of the file in the <code>document.cover</code> configuration option.</p> <p>You can also specify the output profile used by the <code>ebook-convert</code> command by setting the <code>output.epub.profile</code> and <code>output.mobi.profile</code> options. If these are not specified, the conversion will use the <code>kindle</code> output profile for mobi files, and the <code>nook</code> output profile for epub files. See the documentation for Calibre for a list of available output profiles.</p> <aside class="tip"> <span class="note-title">Tip</span>Giving the command <code> glyph compile -f ebooks </code> will generate both mobi and epub files. </aside> </section> <section class="section"> <header><h1 id="web_output" class="toc">Web/Web5 Output</h1></header> <p>To generate a Web or Web5 output, specify <code>web</code> or <code>web5</code> as format. These two output formats behave different way from the others, and require that your project uses <a href="/glyph/book/text_editing/topics.html#topics">topics</a> and <a href="/glyph/book/extending/layouts.html#layouts">layouts</a>.</p> <p>Basically, here’s what happens when you compile your project in web or web5 format:</p> <ol> <li>The document code is parsed as normal</li> <li>Separate topic files are generated according to the <code>@src</code> attributes of your sections</li> <li>The <code>document.glyph</code> (or whatever file you’re using as document source) is <em>not</em> rendered. Instead, an <code>index.html</code> file will be created in the output folder based on the contents of your <a href="/glyph/book/extending/layouts.html#index_layout">index layout</a>.</li> </ol> </section> <section class="section"> <header><h1 id="auto_regeneration" class="toc">Auto Regeneration</h1></header> <p>You can also call the <a href="/glyph/book/ref_commands.html#c_compile"><code>compile</code></a> command with a <code>--auto</code> switch. If you do so, your project will be recompiled automatically every time any source file is changed.</p> <aside class="note"> <span class="note-title">Note</span>Auto regeneration requires the <a href="http://rubygems.org/gems/directory_watcher">directory_watcher</a> gem to be installed. </aside> </section> <nav class="navigation"><a href="/glyph/book/text_editing/evaluation.html">← Simple Programming and Code Evaluation</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/compiling/lite_mode.html">Compiling single Glyph files →</a></nav> |