mirror of
https://github.com/lise-henry/crowbook
synced 2024-05-28 18:16:32 +02:00
292 lines
17 KiB
HTML
292 lines
17 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 - 7. Interactive fiction</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.14.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>--autograph</code></a></li>
|
||
<li><a href = "chapter_001.html#link-34">2.9. <code>--verbose</code></a></li>
|
||
<li><a href = "chapter_001.html#link-35">2.10. <code>--to</code></a></li>
|
||
<li><a href = "chapter_001.html#link-37">2.11. <code>--output</code></a></li>
|
||
<li><a href = "chapter_001.html#link-38">2.12. <code>--lang</code></a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_002.html#link-40">3. The configuration file</a>
|
||
<ul><li><a href = "chapter_002.html#link-41">3.1. Configuration in an inline YAML block</a></li>
|
||
<li><a href = "chapter_002.html#link-42">3.2. The list of files</a></li>
|
||
<li><a href = "chapter_002.html#link-45">3.3. Crowbook options</a></li>
|
||
<li><a href = "chapter_002.html#link-60">3.4. Full list of options</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_003.html#link-77">4. Markdown format</a>
|
||
<ul><li><a href = "chapter_003.html#link-78">4.1. Tables</a></li>
|
||
<li><a href = "chapter_003.html#link-79">4.2. Footnotes</a></li>
|
||
<li><a href = "chapter_003.html#link-80">4.3. Superscript and subscript</a></li>
|
||
<li><a href = "chapter_003.html#link-81">4.4. “Standalone” images</a></li>
|
||
<li><a href = "chapter_003.html#link-82">4.5. Interactive fiction</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_004.html#link-83">5. Templates</a>
|
||
<ul><li><a href = "chapter_004.html#link-84">5.1. Create and edit template</a></li>
|
||
<li><a href = "chapter_004.html#link-88">5.2. List of templates</a></li>
|
||
<li><a href = "chapter_004.html#link-102">5.3. List of accessible variables</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_005.html#link-106">6. Proofreading with Crowbook</a>
|
||
<ul><li><a href = "chapter_005.html#link-107">6.1. Enabling proofreading</a></li>
|
||
<li><a href = "chapter_005.html#link-108">6.2. Repetition detection</a></li>
|
||
<li><a href = "chapter_005.html#link-109">6.3. Grammar checking</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_006.html#link-112">7. Interactive fiction</a>
|
||
<ul><li><a href = "chapter_006.html#link-113">7.1. Basics</a></li>
|
||
<li><a href = "chapter_006.html#link-114">7.2. The interactive fiction renderer</a></li>
|
||
<li><a href = "chapter_006.html#link-115">7.3. Using Javascript in your interactive fiction</a></li>
|
||
<li><a href = "chapter_006.html#link-116">7.4. Embedding Makdown in your Javascript code embedded in your Markdown</a></li>
|
||
<li><a href = "chapter_006.html#link-117">7.5. Conditional blocks</a></li>
|
||
<li><a href = "chapter_006.html#link-118">7.6. Interactive fiction options</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_007.html#link-119">8. Tips and tricks</a>
|
||
<ul><li><a href = "chapter_007.html#link-120">8.1. Using Crowbook with Emacs’ markdown mode</a></li>
|
||
<li><a href = "chapter_007.html#link-122">8.2. Embedding fonts in an EPUB file</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_008.html#link-123">9. Contributing</a>
|
||
<ul><li><a href = "chapter_008.html#link-124">9.1. Internationalization</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_009.html#link-125">ChangeLog</a>
|
||
<ul><li><a href = "chapter_009.html#link-126">unreleased</a></li>
|
||
<li><a href = "chapter_009.html#link-127">0.14.0-beta (2017-10-08)</a></li>
|
||
<li><a href = "chapter_009.html#link-128">0.13.0 (2017-07-14)</a></li>
|
||
<li><a href = "chapter_009.html#link-129">0.12.0 (2017-06-05)</a></li>
|
||
<li><a href = "chapter_009.html#link-130">0.11.4 (2017-03-21)</a></li>
|
||
<li><a href = "chapter_009.html#link-131">0.11.3 (2017-03-19)</a></li>
|
||
<li><a href = "chapter_009.html#link-132">0.11.2 (2017-03-05)</a></li>
|
||
<li><a href = "chapter_009.html#link-133">0.11.1 (2017-01-05)</a></li>
|
||
<li><a href = "chapter_009.html#link-134">0.11.0 (2016-12-31)</a></li>
|
||
<li><a href = "chapter_009.html#link-135">0.10.4 (2016-12-16)</a></li>
|
||
<li><a href = "chapter_009.html#link-136">0.10.3 (2016-11-19)</a></li>
|
||
<li><a href = "chapter_009.html#link-137">0.10.2 (2016-10-21)</a></li>
|
||
<li><a href = "chapter_009.html#link-138">0.10.1 (2016-10-18)</a></li>
|
||
<li><a href = "chapter_009.html#link-139">0.10.0 (2016-10-18)</a></li>
|
||
<li><a href = "chapter_009.html#link-140">0.9.1 (2016-09-29)</a></li>
|
||
<li><a href = "chapter_009.html#link-141">0.9.0 (2016-09-23)</a></li>
|
||
<li><a href = "chapter_009.html#link-142">0.8.0 (2016-09-19)</a></li>
|
||
<li><a href = "chapter_009.html#link-143">0.7.0 (2016-09-11)</a></li>
|
||
<li><a href = "chapter_009.html#link-144">0.6.0 (2016-09-09)</a></li>
|
||
<li><a href = "chapter_009.html#link-145">0.5.1 (2016-04-14)</a></li>
|
||
<li><a href = "chapter_009.html#link-146">0.5.0 (2016-04-02)</a></li>
|
||
<li><a href = "chapter_009.html#link-147">0.4.0 (2016-03-01)</a></li>
|
||
<li><a href = "chapter_009.html#link-148">0.3.0 (2016-02-27)</a></li>
|
||
<li><a href = "chapter_009.html#link-149">0.2.2 (2016-02-25)</a></li>
|
||
<li><a href = "chapter_009.html#link-150">0.2.1 (2016-02-25)</a></li>
|
||
<li><a href = "chapter_009.html#link-151">0.2.0 (2016-02-25)</a></li>
|
||
<li><a href = "chapter_009.html#link-152">0.1.0 (2016-02-21)</a></li>
|
||
|
||
</ul>
|
||
</li>
|
||
<li><a href = "chapter_010.html#link-153">GNU LESSER GENERAL PUBLIC LICENSE</a></li>
|
||
|
||
</ul>
|
||
|
||
</nav>
|
||
|
||
<div id = "content">
|
||
<div id = "top"><p id = "para-358">Crowbook User Guide 0.14.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_005.html">
|
||
« 6. Proofreading with Crowbook
|
||
</a>
|
||
</p>
|
||
<h1 id = 'link-112'><span class = 'chapter-header'>Chapter 7</span><br />Interactive fiction</h1><p id = "para-246">Version <code>0.12.0</code> added experimental support for writing interactive fiction.</p>
|
||
<blockquote><p id = "para-247">Since this support is experimental, it means it can change at anytime, and there is no guarentee that the interactive fiction you write for the current version of Crowbook will work with the next release, even if it isn’t a major release.</p>
|
||
</blockquote>
|
||
<h2 id = "link-113">7.1. Basics</h2>
|
||
<p id = "para-248">If you want to have a non-linear story, you can simply use Markdown links just as you would for any other link:</p>
|
||
<pre><span style="color:#839496;">*</span><span style="color:#839496;"> </span><span style="color:#839496;">[</span><span style="color:#839496;">Open the treasure chest</span><span style="color:#839496;">]</span><span style="color:#839496;">(</span><span style="color:#2aa198;">open_chest.md</span><span style="color:#839496;">)</span><span style="color:#839496;">
|
||
</span><span style="color:#839496;">*</span><span style="color:#839496;"> </span><span style="color:#839496;">[</span><span style="color:#839496;">It might be trapped, stay away from it</span><span style="color:#839496;">]</span><span style="color:#839496;">(</span><span style="color:#2aa198;">stay_away.md</span><span style="color:#839496;">)</span><span style="color:#839496;">
|
||
</span></pre><p id = "para-249">All Crowbook renderers should render this correctly, allowing the reader to “choose her adventure”. Note, however, that you still need to include all these Markdown files in you book configuration files.</p>
|
||
<h2 id = "link-114">7.2. The interactive fiction renderer</h2>
|
||
<p id = "para-250">While the above allows you to generate correct EPUB and PDF files, it will still display all the content if the reader chooses to read your book linearly. While this may not be a problem, you might want to only display the part of the book that the reader is actually exploring.</p>
|
||
<p id = "para-251">In order to do so, you can use the interactive fiction html renderer:</p>
|
||
<pre><span style="color:#268bd2;">output.html.if</span><span style="color:#839496;">:</span><span style="color:#839496;"> </span><span style="color:#2aa198;">my_book.html</span><span style="color:#839496;">
|
||
</span></pre><p id = "para-252">This output is similar to the standalone HTML output, except the option to display only a chapter at a time is always true, and there is no way to display the table of contents.</p>
|
||
<h2 id = "link-115">7.3. Using Javascript in your interactive fiction</h2>
|
||
<p id = "para-253">While the above allows the reader to choose his own path, its interactivity is quite limited. With the interactive fiction renderer, it is possible to include Javascript code in your Markdown files, using a code block element:</p>
|
||
<pre><span style="color:#839496;">You open the chest, and you find a shiny sword. Yay!
|
||
</span><span style="color:#839496;">
|
||
</span><span style="color:#839496;"> user_has_sword = true;
|
||
</span></pre><p id = "para-254">This Javascript code can return a string value, which will be displayed inside the document according to the reader’s previous choices:</p>
|
||
<pre><span style="color:#839496;">You encounter a goblin, armed with a knife!
|
||
</span><span style="color:#839496;">
|
||
</span><span style="color:#839496;"> if (user_has_sword) {
|
||
</span><span style="color:#839496;"> return "You kill him with your sword, congratulations!";
|
||
</span><span style="color:#839496;"> } else {
|
||
</span><span style="color:#839496;"> return "You don't have any weapon, you die :(";
|
||
</span><span style="color:#839496;"> }
|
||
</span></pre><blockquote><p id = "para-255">Note that <em>only</em> the interactive fiction renderer supports this way of embedding Javascript code. If you try to render a document containing such code blocks to EPUB, PDF, or the “normal” HTML renderer, they will be displayed as regular code blocks.</p>
|
||
</blockquote>
|
||
<h2 id = "link-116">7.4. Embedding Makdown in your Javascript code embedded in your Markdown</h2>
|
||
<p id = "para-256">If you want to include Markdown formatting in the Javascript code (to display a passage or another without having to write HTML code), you can use the <code>@"..."@</code> syntax:</p>
|
||
<pre><span style="color:#839496;"> @"You face a troll!"@
|
||
</span><span style="color:#839496;"> if (user_has_sword) {
|
||
</span><span style="color:#839496;"> @"* [Attack him with your sword](fight_troll.md)"@
|
||
</span><span style="color:#839496;"> } else {
|
||
</span><span style="color:#839496;"> @"* [Better run away](run_away.md)"@
|
||
</span><span style="color:#839496;"> }
|
||
</span></pre><p id = "para-257">Note that in this case you don’t need to return a value, this is done behind your back. Similarly, <code>@"..."@</code> blocks don’t require semicolons.</p>
|
||
<p id = "para-258">If you need to access the value of a Javascript variable inside this Markdown code, you can use the <code>{{...}}</code> syntax:</p>
|
||
<pre><span style="color:#839496;"> var name = prompt("Enter your name", "world");
|
||
</span><span style="color:#839496;"> @"Hello, {{name}}"@
|
||
</span></pre><h2 id = "link-117">7.5. Conditional blocks</h2>
|
||
<p id = "para-259">Sometimes, you want some text (or Javascript code) to only be displayed (or run) when the reader reads this passage the first time, or alternatively when she goes back to it. While it is trivial to add some code to check that, it is a common enough pattern to justify its own variant : you’ll juste have to insert a named code block with the number:</p>
|
||
<pre><span style="color:#839496;">```1
|
||
@"Only displayed at first passage"@
|
||
```
|
||
|
||
```2
|
||
@"Only displayed at second passage"@
|
||
```
|
||
|
||
```>2
|
||
@"Displayed at passage 3, 4 and so on.
|
||
```
|
||
</span></pre><h2 id = "link-118">7.6. Interactive fiction options</h2>
|
||
<p id = "para-260">As other renderers, there are options specific to the interactive fiction.</p>
|
||
<p id = "para-261"><b>html.if.new_game</b> allows you to specify the path to a Javascript that will be run at the beginning of the game. Since this code is not embedded in a function and is at the root (and the beginning) of the document, it is a good place to declare all the functions and the global variables you might need for your interactive fiction mechanics. e.g.:</p>
|
||
<pre><span style="color:#268bd2;">html.if.new_game</span><span style="color:#839496;">:</span><span style="color:#839496;"> </span><span style="color:#2aa198;">some_file.js</span><span style="color:#839496;">
|
||
</span></pre><p id = "para-262"><b>html.if.new_turn</b> and <b>html.if.end_turn</b> allow you to specify some Javascript code that will be executed at the beginning and the end of each segment. Unlike <code>html.if.new_game</code>, the (usually shorter) code is specified inline, and can return a string value that will be displayed at the beginning and the end of each segment. This is exactly like including code blocks at the beginning or the end of each of your Markdown file. E.g.:</p>
|
||
<pre><span style="color:#268bd2;">html.if.new_turn</span><span style="color:#839496;">:</span><span style="color:#839496;"> </span><span style="color:#839496;">"</span><span style="color:#2aa198;">nb_turns += 1;</span><span style="color:#839496;">"</span><span style="color:#839496;">
|
||
</span><span style="color:#268bd2;">html.end_turn</span><span style="color:#839496;">:</span><span style="color:#839496;"> </span><span style="color:#839496;">"</span><span style="color:#2aa198;">return 'Turn: ' + nb_turns;</span><span style="color:#839496;">"</span><span style="color:#839496;">
|
||
</span></pre><p id = "para-263"><b>html.if.script</b> allows you to specify the name of a Javascript file to override the default script.</p>
|
||
|
||
<p class = "next_chapter">
|
||
<a href = "chapter_007.html">
|
||
8. Tips and tricks »
|
||
</a>
|
||
</p>
|
||
</div>
|
||
<footer id = "footer"><p id = "para-357">Generated by <a href = "https://github.com/lise-henry/crowbook">Crowbook</a> 0.14.0</p>
|
||
</footer>
|
||
</div>
|
||
</body>
|
||
</html>
|