mirror of
https://github.com/lise-henry/crowbook
synced 2024-09-22 05:00:51 +02:00
329 lines
20 KiB
HTML
329 lines
20 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="generator" content="crowbook">
|
||
<meta name="author" content="Élisabeth Henry">
|
||
<meta name="viewport" content="width=device-width">
|
||
<link rel = "icon" href = "images/image_1.svg">
|
||
<title>Crowbook User Guide - 2. Arguments</title>
|
||
<link rel = "stylesheet" href = "stylesheet.css" type = "text/css"
|
||
/>
|
||
<link rel = "stylesheet" href = "print.css" type = "text/css"
|
||
media = "print" />
|
||
<script>
|
||
function on(name) {
|
||
var elements = document.getElementsByClassName(name);
|
||
for (var i = 0; i < elements.length; i++) {
|
||
var elem = elements[i];
|
||
elem.style.backgroundColor = "pink";
|
||
}
|
||
}
|
||
function off(name) {
|
||
var elements = document.getElementsByClassName(name);
|
||
for (var i = 0; i < elements.length; i++) {
|
||
var elem = elements[i];
|
||
elem.style.backgroundColor = "white";
|
||
}
|
||
}
|
||
|
||
var display_menu = false;
|
||
function toggle() {
|
||
if (display_menu == true) {
|
||
display_menu = false;
|
||
document.getElementById("nav").style.left = "-21%";
|
||
document.getElementById("content").style.marginLeft = "0%";
|
||
document.getElementById("menu").style.left = "1em";
|
||
/* if(document.getElementById("top")) {
|
||
document.getElementById("top").style.left = "0";
|
||
}
|
||
if(document.getElementById("footer")) {
|
||
document.getElementById("footer").style.marginLeft = "0%";
|
||
}*/
|
||
} else {
|
||
display_menu = true;
|
||
document.getElementById("nav").style.left = "0";
|
||
document.getElementById("content").style.marginLeft = "20%";
|
||
document.getElementById("menu").style.left = "20%";
|
||
/* if(document.getElementById("top")) {
|
||
document.getElementById("top").style.left = "20%";
|
||
}
|
||
if(document.getElementById("footer")) {
|
||
document.getElementById("footer").style.marginLeft = "20%";
|
||
}*/
|
||
}
|
||
}
|
||
|
||
</script>
|
||
|
||
|
||
</head>
|
||
<body>
|
||
|
||
<script type = 'application/ld+json'>
|
||
{
|
||
"@context": "http://schema.org/",
|
||
"@type": "Book",
|
||
"author": "Élisabeth Henry",
|
||
"name": "Crowbook User Guide",
|
||
"version": "0.13.0",
|
||
|
||
|
||
"license": "This guide is published under the Creative Commons Attribution-ShareAlike 4.0-International license.",
|
||
"about": "Crowbook allows to render a book written in Markdown in various formats. This is some kind of manual for it, and a way to demonstrate and test it.",
|
||
"inLanguage": "en"
|
||
|
||
|
||
|
||
|
||
}
|
||
</script>
|
||
<nav id = "nav">
|
||
<h2><a href = "index.html">Crowbook User Guide</a></h2>
|
||
<ul>
|
||
<li><a href = "chapter_000.html#link-1">1. Crowbook</a>
|
||
<ul><li><a href = "chapter_000.html#link-2">1.1. Example</a></li>
|
||
<li><a href = "chapter_000.html#link-3">1.2. Installing</a></li>
|
||
<li><a href = "chapter_000.html#link-6">1.3. Dependencies</a></li>
|
||
<li><a href = "chapter_000.html#link-7">1.4. Quick tour</a></li>
|
||
<li><a href = "chapter_000.html#link-8">1.5. Current features</a></li>
|
||
<li><a href = "chapter_000.html#link-18">1.6. Contributors</a></li>
|
||
<li><a href = "chapter_000.html#link-19">1.7. Acknowledgements</a></li>
|
||
<li><a href = "chapter_000.html#link-20">1.8. ChangeLog</a></li>
|
||
<li><a href = "chapter_000.html#link-21">1.9. Contributing</a></li>
|
||
<li><a href = "chapter_000.html#link-22">1.10. Library</a></li>
|
||
<li><a href = "chapter_000.html#link-23">1.11. License</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_001.html#link-24">2. Arguments</a>
|
||
<ul><li><a href = "chapter_001.html#link-25">2.1. <code>--create</code></a></li>
|
||
<li><a href = "chapter_001.html#link-26">2.2. <code>--single</code></a></li>
|
||
<li><a href = "chapter_001.html#link-27">2.3. <code>--set</code></a></li>
|
||
<li><a href = "chapter_001.html#link-28">2.4. <code>--list-options</code></a></li>
|
||
<li><a href = "chapter_001.html#link-29">2.5. <code>--print-template</code></a></li>
|
||
<li><a href = "chapter_001.html#link-30">2.6. <code>--stats</code></a></li>
|
||
<li><a href = "chapter_001.html#link-31">2.7. <code>--proofread</code></a></li>
|
||
<li><a href = "chapter_001.html#link-32">2.8. <code>--verbose</code></a></li>
|
||
<li><a href = "chapter_001.html#link-33">2.9. <code>--to</code></a></li>
|
||
<li><a href = "chapter_001.html#link-35">2.10. <code>--output</code></a></li>
|
||
<li><a href = "chapter_001.html#link-36">2.11. <code>--lang</code></a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_002.html#link-38">3. The configuration file</a>
|
||
<ul><li><a href = "chapter_002.html#link-39">3.1. Configuration in an inline YAML block</a></li>
|
||
<li><a href = "chapter_002.html#link-40">3.2. The list of files</a></li>
|
||
<li><a href = "chapter_002.html#link-43">3.3. Crowbook options</a></li>
|
||
<li><a href = "chapter_002.html#link-58">3.4. Full list of options</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_003.html#link-75">4. Markdown format</a>
|
||
<ul><li><a href = "chapter_003.html#link-76">4.1. Tables</a></li>
|
||
<li><a href = "chapter_003.html#link-77">4.2. Footnotes</a></li>
|
||
<li><a href = "chapter_003.html#link-78">4.3. Superscript and subscript</a></li>
|
||
<li><a href = "chapter_003.html#link-79">4.4. “Standalone” images</a></li>
|
||
<li><a href = "chapter_003.html#link-80">4.5. Interactive fiction</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_004.html#link-81">5. Templates</a>
|
||
<ul><li><a href = "chapter_004.html#link-82">5.1. Create and edit template</a></li>
|
||
<li><a href = "chapter_004.html#link-86">5.2. List of templates</a></li>
|
||
<li><a href = "chapter_004.html#link-100">5.3. List of accessible variables</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_005.html#link-104">6. Proofreading with Crowbook</a>
|
||
<ul><li><a href = "chapter_005.html#link-105">6.1. Enabling proofreading</a></li>
|
||
<li><a href = "chapter_005.html#link-106">6.2. Repetition detection</a></li>
|
||
<li><a href = "chapter_005.html#link-107">6.3. Grammar checking</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_006.html#link-110">7. Interactive fiction</a>
|
||
<ul><li><a href = "chapter_006.html#link-111">7.1. Basics</a></li>
|
||
<li><a href = "chapter_006.html#link-112">7.2. The interactive fiction renderer</a></li>
|
||
<li><a href = "chapter_006.html#link-113">7.3. Using Javascript in your interactive fiction</a></li>
|
||
<li><a href = "chapter_006.html#link-114">7.4. Embedding Makdown in your Javascript code embedded in your Markdown</a></li>
|
||
<li><a href = "chapter_006.html#link-115">7.5. Conditional blocks</a></li>
|
||
<li><a href = "chapter_006.html#link-116">7.6. Interactive fiction options</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_007.html#link-117">8. Tips and tricks</a>
|
||
<ul><li><a href = "chapter_007.html#link-118">8.1. Using Crowbook with Emacs’ markdown mode</a></li>
|
||
<li><a href = "chapter_007.html#link-120">8.2. Embedding fonts in an EPUB file</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_008.html#link-121">9. Contributing</a>
|
||
<ul><li><a href = "chapter_008.html#link-122">9.1. Internationalization</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_009.html#link-123">ChangeLog</a>
|
||
<ul><li><a href = "chapter_009.html#link-124">0.13.0 (2017-07-14)</a></li>
|
||
<li><a href = "chapter_009.html#link-125">0.12.0 (2017-06-05)</a></li>
|
||
<li><a href = "chapter_009.html#link-126">0.11.4 (2017-03-21)</a></li>
|
||
<li><a href = "chapter_009.html#link-127">0.11.3 (2017-03-19)</a></li>
|
||
<li><a href = "chapter_009.html#link-128">0.11.2 (2017-03-05)</a></li>
|
||
<li><a href = "chapter_009.html#link-129">0.11.1 (2017-01-05)</a></li>
|
||
<li><a href = "chapter_009.html#link-130">0.11.0 (2016-12-31)</a></li>
|
||
<li><a href = "chapter_009.html#link-131">0.10.4 (2016-12-16)</a></li>
|
||
<li><a href = "chapter_009.html#link-132">0.10.3 (2016-11-19)</a></li>
|
||
<li><a href = "chapter_009.html#link-133">0.10.2 (2016-10-21)</a></li>
|
||
<li><a href = "chapter_009.html#link-134">0.10.1 (2016-10-18)</a></li>
|
||
<li><a href = "chapter_009.html#link-135">0.10.0 (2016-10-18)</a></li>
|
||
<li><a href = "chapter_009.html#link-136">0.9.1 (2016-09-29)</a></li>
|
||
<li><a href = "chapter_009.html#link-137">0.9.0 (2016-09-23)</a></li>
|
||
<li><a href = "chapter_009.html#link-138">0.8.0 (2016-09-19)</a></li>
|
||
<li><a href = "chapter_009.html#link-139">0.7.0 (2016-09-11)</a></li>
|
||
<li><a href = "chapter_009.html#link-140">0.6.0 (2016-09-09)</a></li>
|
||
<li><a href = "chapter_009.html#link-141">0.5.1 (2016-04-14)</a></li>
|
||
<li><a href = "chapter_009.html#link-142">0.5.0 (2016-04-02)</a></li>
|
||
<li><a href = "chapter_009.html#link-143">0.4.0 (2016-03-01)</a></li>
|
||
<li><a href = "chapter_009.html#link-144">0.3.0 (2016-02-27)</a></li>
|
||
<li><a href = "chapter_009.html#link-145">0.2.2 (2016-02-25)</a></li>
|
||
<li><a href = "chapter_009.html#link-146">0.2.1 (2016-02-25)</a></li>
|
||
<li><a href = "chapter_009.html#link-147">0.2.0 (2016-02-25)</a></li>
|
||
<li><a href = "chapter_009.html#link-148">0.1.0 (2016-02-21)</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_010.html#link-149">GNU LESSER GENERAL PUBLIC LICENSE</a></li>
|
||
|
||
</ul>
|
||
|
||
</nav>
|
||
|
||
<div id = "content">
|
||
<div id = "top"><p id = "para-343">Crowbook User Guide 0.13.0</p>
|
||
</div>
|
||
<div id = "page">
|
||
<header>
|
||
<div id = "menu">
|
||
<img id = "menu-button" onclick="toggle();"
|
||
src="menu.svg" alt = "Table of contents" title = "Table of contents" />
|
||
</div>
|
||
</header>
|
||
<p class = "prev_chapter">
|
||
<a href = "chapter_000.html">
|
||
« 1. Crowbook
|
||
</a>
|
||
</p>
|
||
<h1 id = 'link-24'><span class = 'chapter-header'>Chapter 2</span><br />Arguments</h1><p id = "para-46">Crowbook can take a number of arguments, generally in the form:</p>
|
||
<pre><span style="color:#839496;">crowbook [OPTIONS] [BOOK]
|
||
</span></pre><p id = "para-47">The most important argument is obviously the book configuration file. It is mandatory in most cases: if you don’t pass it, Crowbook will simply display an error. In a normal use case this is the only argument you’ll need to pass, as most options will be set in this configuration file.</p>
|
||
<p id = "para-48">It is, however, possible to pass more arguments to <code>crowbook</code>:</p>
|
||
<h2 id = "link-25">2.1. <code>--create</code></h2>
|
||
<p id = "para-49"><b>Usage</b>: <code>crowbook [BOOK] --create file_1.md file_2.md ...</code></p>
|
||
<p id = "para-50">(or <code>crowbook [BOOK] -c file_1.md file_2.md ...</code>)</p>
|
||
<p id = "para-51">Creates a new book from a list of Markdown files. It will generate a book configuration file with all file names specified as chapters. It either prints the result to stdout (if <code>BOOK</code> is not specified) or generate the file <code>BOOK</code> (or abort if it already exists).</p>
|
||
<pre><span style="color:#839496;">crowbook foo.book --create chapter_1.md chapter_2.md chapter_3.md
|
||
</span></pre><p id = "para-52">will thus generate a file <code>foo.book</code> containing:</p>
|
||
<pre><span style="color:#268bd2;">author</span><span style="color:#839496;">:</span><span style="color:#839496;"> </span><span style="color:#268bd2;">Your name</span><span style="color:#839496;">
|
||
</span><span style="color:#268bd2;">title</span><span style="color:#839496;">:</span><span style="color:#839496;"> </span><span style="color:#268bd2;">Your title</span><span style="color:#839496;">
|
||
</span><span style="color:#268bd2;">lang</span><span style="color:#839496;">:</span><span style="color:#839496;"> </span><span style="color:#2aa198;">en</span><span style="color:#839496;">
|
||
|
||
</span><span style="color:#586e75;">#</span><span style="color:#586e75;"># Output formats
|
||
|
||
# Uncomment and fill to generate files
|
||
# output.html: some_file.html
|
||
# output.epub: some_file.epub
|
||
# output.pdf: some_file.pdf
|
||
|
||
# Or uncomment the following to generate PDF, HTML and EPUB files based on this file's name
|
||
# output: [pdf, epub, html]
|
||
|
||
# Uncomment and fill to set cover image (for EPUB)
|
||
# cover: some_cover.png
|
||
|
||
## List of chapters
|
||
+ chapter_1.md
|
||
+ chapter_2.md
|
||
+ chapter_3.md
|
||
</span></pre><p id = "para-53">while</p>
|
||
<pre><span style="color:#839496;">crowbook --create chapter_1.md chapter_2.md chapter_3.md
|
||
</span></pre><p id = "para-54">will print the same result, but to stdout (without creating a file).</p>
|
||
<h2 id = "link-26">2.2. <code>--single</code></h2>
|
||
<p id = "para-55"><b>Usage</b>: <code>crowbook --single <FILE></code></p>
|
||
<p id = "para-56">(or <code>crowbook -s <FILE></code>)</p>
|
||
<p id = "para-57">This argument allows you to give <code>crowbook</code> a single Markdown file. This file can contain an inline YAML block to set some book options. Inline YAML blocks must start and end with a line containing only <code>---</code> (three dashes). E.g:</p>
|
||
<pre><span style="color:#839496;">---</span><span style="color:#839496;">
|
||
</span><span style="color:#268bd2;">author</span><span style="color:#839496;">:</span><span style="color:#839496;"> </span><span style="color:#268bd2;">Joan Doe</span><span style="color:#839496;">
|
||
</span><span style="color:#268bd2;">title</span><span style="color:#839496;">:</span><span style="color:#839496;"> </span><span style="color:#268bd2;">A short story</span><span style="color:#839496;">
|
||
</span><span style="color:#268bd2;">output</span><span style="color:#839496;">:</span><span style="color:#839496;"> </span><span style="color:#839496;">[</span><span style="color:#2aa198;">html</span><span style="color:#839496;">,</span><span style="color:#839496;"> </span><span style="color:#2aa198;">epub</span><span style="color:#839496;">,</span><span style="color:#839496;"> </span><span style="color:#2aa198;">pdf</span><span style="color:#839496;">]</span><span style="color:#839496;">
|
||
</span><span style="color:#839496;">---</span><span style="color:#839496;">
|
||
|
||
</span><span style="color:#2aa198;">Content of the story in Markdown.</span><span style="color:#839496;">
|
||
</span></pre><p id = "para-58">If this YAML block is not at the beginning of a file, it must also be preceded by a blank line.</p>
|
||
<p id = "para-59">This allows to not have to write a <code>.book</code> configuration file for a short story or an article. <code>crowbook -s foo.md</code> is rougly equivalent to having a book configuration file containing:</p>
|
||
<pre><span style="color:#268bd2;">!</span><span style="color:#839496;"> </span><span style="color:#2aa198;">foo.md</span><span style="color:#839496;">
|
||
</span></pre><p id = "para-60">That is, the chapter heading (if any) won’t be displayed in the output documents (though they still appear in the TOC).</p>
|
||
<blockquote><p id = "para-61">Note that by default, using <code>--single</code> or <code>-s</code> sets the default LaTeX class of the book to <code>article</code> instead of <code>book</code>.</p>
|
||
</blockquote>
|
||
<h2 id = "link-27">2.3. <code>--set</code></h2>
|
||
<p id = "para-62"><b>Usage</b>: <code>crowbook <BOOK> --set [KEY] [VALUE]...</code></p>
|
||
<p id = "para-63">This argument takes a list of <code>KEY</code> <code>VALUE</code> pairs and allows setting or overriding a book configuration option. All valid options in the configuration files are valid as keys. For more information, see <a href = "chapter_002.html">the configuration file</a>.</p>
|
||
<pre><span style="color:#839496;">$ crowbook foo.book --</span><span style="color:#859900;">set</span><span style="color:#839496;"> tex.paper.size a4paper
|
||
</span></pre><p id = "para-64">will override the paper size for PDF generation.</p>
|
||
<h2 id = "link-28">2.4. <code>--list-options</code></h2>
|
||
<p id = "para-65"><b>Usage</b>: <code>crowbook --list-options</code></p>
|
||
<p id = "para-66">(or <code>crowbook -l</code>)</p>
|
||
<p id = "para-67">Displays all the valid options that can be used, whether in a book configuration file, with <code>--set</code>, or in an inline YAML block.</p>
|
||
<h2 id = "link-29">2.5. <code>--print-template</code></h2>
|
||
<p id = "para-68"><b>Usage</b>: <code>crowbook --print-template <TEMPLATE></code></p>
|
||
<p id = "para-69">Prints the built-in template to stdout. Useful if you want to customize the appearance of your document. E.g., if you want to modify the CSS used for HTML rendering:</p>
|
||
<pre><span style="color:#839496;">$ crowbook --print-template html.css </span><span style="color:#859900;">></span><span style="color:#839496;"> my_style.css
|
||
</span><span style="color:#586e75;">#</span><span style="color:#586e75;"> edit my_style.css in your favourite editor</span><span style="color:#839496;">
|
||
$ crowbook my.book --</span><span style="color:#859900;">set</span><span style="color:#839496;"> html.css my_style.css
|
||
</span><span style="color:#586e75;">#</span><span style="color:#586e75;"> or add "html.css: my_style.css" in my.book</span><span style="color:#839496;">
|
||
</span></pre><h2 id = "link-30">2.6. <code>--stats</code></h2>
|
||
<p id = "para-70"><b>Usage</b>: <code>crowbook --stats <BOOK></code></p>
|
||
<p id = "para-71">(or <code>crowbook -S <BOOK></code>)</p>
|
||
<p id = "para-72">Display some statistics (word and character counts) about the book.</p>
|
||
<h2 id = "link-31">2.7. <code>--proofread</code></h2>
|
||
<p id = "para-73"><b>Usage</b>: <code>crowbook --proofread <BOOK></code></p>
|
||
<p id = "para-74">(or <code>crowbook -p <BOOK></code>)</p>
|
||
<p id = "para-75">Equivalent to <code>--set proofread true</code>. Enable proofreading. See <a href = "chapter_005.html">Proofreading</a>.</p>
|
||
<h2 id = "link-32">2.8. <code>--verbose</code></h2>
|
||
<p id = "para-76"><b>Usage</b>: <code>crowbook <BOOK> --verbose</code></p>
|
||
<p id = "para-77">If this flag is set, Crowbook will print more warnings it detects while parsing and rendering.</p>
|
||
<h2 id = "link-33">2.9. <code>--to</code></h2>
|
||
<p id = "para-78"><b>Usage</b>: <code>crowbook <BOOK> --to [FORMAT]</code></p>
|
||
<p id = "para-79">(or <code>crowbook <BOOK> -t [FORMAT]</code>)</p>
|
||
<p id = "para-80">Generate only the specified format. <code>FORMAT</code> must be either <code>epub</code>, <code>pdf</code>, <code>html</code>, <code>html.dir</code>, <code>odt</code> or <code>tex</code>.</p>
|
||
<p id = "para-81">If an output file for the format is not specified in the book configuration file, <code>crowbook</code> will fail to render PDF, ODT and EPUB, whereas it will print HTML and TeX files on stdout. It is, however, possible to specify a file with the <code>--output</code> option.</p>
|
||
<h3 id = "link-34">Examples</h3>
|
||
<pre><span style="color:#839496;">crowbook --to html foo.book
|
||
</span></pre><p id = "para-82">will generate some HTML, and prints it either to the file specified by <code>output.html</code> in <code>foo.book</code>, or to stdout if it is not specified.</p>
|
||
<pre><span style="color:#839496;">crowbook --to pdf --output foo.pdf foo.book
|
||
</span></pre><p id = "para-83">will generate a <code>foo.pdf</code> file.</p>
|
||
<h2 id = "link-35">2.10. <code>--output</code></h2>
|
||
<p id = "para-84"><b>Usage</b>: <code>crowbook <BOOK> --to <FORMAT> --output <FILE></code></p>
|
||
<p id = "para-85">(or <code>crowbook -t <FORMAT> -o <FILE> <BOOK></code>)</p>
|
||
<p id = "para-86">Specifies an output file. Only valid when <code>--to</code> is used.</p>
|
||
<h2 id = "link-36">2.11. <code>--lang</code></h2>
|
||
<p id = "para-87"><b>Usage</b>: <code>crowbook --lang <LANG></code></p>
|
||
<p id = "para-88">(or <code>crowbook -L <LANG></code>)</p>
|
||
<p id = "para-89">Set the runtime language used by Crowbook. Currently, only a french translation is available. By default, Crowbook uses the <code>LANG</code> environment variable to determine which language to use, but this option allows to override it (e.g. for operating systems that don’t use such an option, such as Windows).</p>
|
||
<h3 id = "link-37">Example</h3>
|
||
<p id = "para-90"><code>$ crowbook --lang fr --help</code></p>
|
||
<p id = "para-91">will display Crowbook’s help message in french.</p>
|
||
<blockquote><p id = "para-92">Note that this argument has nothing to do with the <code>lang</code> option that you can set in the book configuration file, which specifies the language <em>of the book</em>. This argument specifies the language of the text messages that Crowbook will display while running, but has no effect on the generated documents.</p>
|
||
</blockquote>
|
||
|
||
<p class = "next_chapter">
|
||
<a href = "chapter_002.html">
|
||
3. The configuration file »
|
||
</a>
|
||
</p>
|
||
</div>
|
||
<footer id = "footer"><p id = "para-342">Generated by <a href = "https://github.com/lise-henry/crowbook">Crowbook</a> 0.13.0</p>
|
||
</footer>
|
||
</div>
|
||
</body>
|
||
</html>
|