gauthiier/wwwriting
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

new html / fixed template

Browse Source
This commit is contained in:
gauthiier
2021-12-11 15:50:05 +01:00
parent 5028093ee8
commit 2ddccd4072
7 changed files with 180 additions and 207 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Lesson4.html
+16 -22
View File
@@ -4,11 +4,8 @@
<meta charset="utf-8">
<meta name="generator" content="pandoc">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
<title></title>
<title>Lesson4</title>
<style type="text/css">code{white-space: pre;}</style>
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link rel="stylesheet" href="style/html5.css">
</head>
<body>
@@ -18,13 +15,13 @@
<h3 id="goals">Goals</h3>
<p>Assuming that you have a basic knowledge of the Markdown language, in this lesson you will learn how to convert a text file written in markdown to both an HTML and EPUB3 output. In order to do so, you need to instal <a href="http://johnmacfarlane.net/pandoc/">Pandoc</a> on your system as we will be using this specific markdown converter.</p>
<p>The goals of this lesson are:</p>
<ol style="list-style-type: decimal">
<ol type="1">
<li>Acquire basic understanding of how to employ pandoc to produce both HTML and EPUB output.</li>
<li>Acquire basic knowledge of how pandoc can be tailored to produce other types of output.</li>
</ol>
<h3 id="how">How</h3>
<p>In order to complete this lesson, you should be familiar with how to operated your computer's CLI (<a href="Lesson2.html">Lesson2</a>) and capable of writing markdown valid text (<a href="Lesson3.html">Lesson3</a>).</p>
<p>The following exercises assumes that you have markdown input file ready to convert to both HTML and EPUB. If you don't already, simply use this file (<a href="Lesson4.md">Lesson4.md</a>).</p>
<p>In order to complete this lesson, you should be familiar with how to operated your computer’s CLI (<a href="Lesson2.html">Lesson2</a>) and capable of writing markdown valid text (<a href="Lesson3.html">Lesson3</a>).</p>
<p>The following exercises assumes that you have markdown input file ready to convert to both HTML and EPUB. If you don’t already, simply use this file (<a href="Lesson4.md">Lesson4.md</a>).</p>
<p>To make sure that your system is set up properly, open a CLI window and type the following</p>
<pre><code>pandoc --version</code></pre>
<p>If you get an error message, this means that you did not install pandoc properly. If so please visit <a href="http://johnmacfarlane.net/pandoc/">Pandoc</a> and install the required software. If not you are ready to go!</p>
@@ -34,8 +31,8 @@
<p>will produce an <em>output</em> file (-o Lesson4.html) from the <em>input</em> file (<em>Lesson4.md</em>). Here the argument -s will force pandoc to produce an entire valid document rather than a snippet of it.</p>
<p>More formally, the former command could be</p>
<pre><code>pandoc -s -f markdown Lesson4.md -t html5 -o Lesson4.html</code></pre>
<p>meaning the input file (Lesson4.md) is of type &quot;markdown&quot; and the output file (-o Lesson4.html) is of type &quot;html5&quot;. You can basically omit these details if you want, markdown can recognise valid input files while the extension of your output file (here .html) will inform the program on the type of output expected. However, since pandoc has multiple possible output files to choose from, some of them of the same type but of different version (for example html and html5), it is a good practice to specify the type of output.</p>
<p>Now let's simply change the output to the Rich Text Format (rtf)</p>
<p>meaning the input file (Lesson4.md) is of type “markdown” and the output file (-o Lesson4.html) is of type “html5”. You can basically omit these details if you want, markdown can recognise valid input files while the extension of your output file (here .html) will inform the program on the type of output expected. However, since pandoc has multiple possible output files to choose from, some of them of the same type but of different version (for example html and html5), it is a good practice to specify the type of output.</p>
<p>Now let’s simply change the output to the Rich Text Format (rtf)</p>
<pre><code>pandoc -s -f markdown Lesson4.md -t rtf -o Lesson4.rtf</code></pre>
<p>or in a more compact version</p>
<pre><code>pandoc -s Lesson4.md -o Lesson4.rtf</code></pre>
@@ -54,20 +51,20 @@
<pre><code>pandoc -s Lesson4.md --template=style/template.html5 -c style/html5.css --bibliography=wwwrite.bib -o Lesson4.html</code></pre>
<p>Now refresh your web browser and see if something changed. Perhaps not (yet). You may not realise it but you have (re)generated the entire HTML in a single pandoc command!</p>
<p>As you can see there is a little more arguments in the above pandoc than previously exposed in the first section.</p>
<ol style="list-style-type: decimal">
<ol type="1">
<li><p>As expected we have</p>
<pre><code>-s Lesson4.md -o Lesson4.html</code></pre>
<pre><code> -s Lesson4.md -o Lesson4.html</code></pre>
<p>which specifies the markdown <em>input</em> (Lesson4.md) and HTML <em>output</em> (Lesson4.html)</p></li>
<li><p>There is a few extra options</p>
<pre><code>--template=style/template.html5 -c style/html5.css --bibliography=wwwrite.bib</code></pre>
<p>which are instructing pandoc to (1) use the HTML5 template &quot;style/template.html5&quot;, (2) use the <a href="https://en.wikipedia.org/wiki/Cascading_Style_Sheets">stylesheet</a> &quot;style/html5.css&quot; and (3) use the bibliographical information in &quot;wwwrite.bib&quot; if in-text referencing is needed.</p></li>
<pre><code> --template=style/template.html5 -c style/html5.css --bibliography=wwwrite.bib</code></pre>
<p>which are instructing pandoc to (1) use the HTML5 template “style/template.html5”, (2) use the <a href="https://en.wikipedia.org/wiki/Cascading_Style_Sheets">stylesheet</a> “style/html5.css” and (3) use the bibliographical information in “wwwrite.bib” if in-text referencing is needed.</p></li>
</ol>
<p>Without going in too much details (since this is the topic of <a href="/">Lesson6</a>), the current site employs custom templates and stylesheets (in the directory <a href="style/">&quot;style/&quot;</a>). In these file you will find all the markup code used to (automatically) generate the layout this web page in HTML and <a href="(https://en.wikipedia.org/wiki/Cascading_Style_Sheets)">CSS</a> formats. In a nutshell, on the one hand a template is responsible to instruct how to convert pandoc's median representation into an HTML format while on the other a CSS stylesheet is responsible for the layout and (design) parametrisation of the content of this HTML. Hence, rather than specifying a default pandoc output, we use our own custom templates to generate our own tailored HTML outputs.</p>
<p>Without going in too much details (since this is the topic of <a href="/">Lesson6</a>), the current site employs custom templates and stylesheets (in the directory <a href="style/">“style/”</a>). In these file you will find all the markup code used to (automatically) generate the layout this web page in HTML and <a href="(https://en.wikipedia.org/wiki/Cascading_Style_Sheets)">CSS</a> formats. In a nutshell, on the one hand a template is responsible to instruct how to convert pandoc’s median representation into an HTML format while on the other a CSS stylesheet is responsible for the layout and (design) parametrisation of the content of this HTML. Hence, rather than specifying a default pandoc output, we use our own custom templates to generate our own tailored HTML outputs.</p>
<h4 id="epub3">EPUB(3)</h4>
<p>It is worth mentioning at this stage that in previous example, pandoc is converting files written in one markup language &quot;markdown&quot; to another markup language &quot;HTML5&quot;. At its core, EPUB is yet another markup language. Both HTML and EPUB are standard markups that are both interpreted by a web browser and epub reader respectively.</p>
<p>It is worth mentioning at this stage that in previous example, pandoc is converting files written in one markup language “markdown” to another markup language “HTML5”. At its core, EPUB is yet another markup language. Both HTML and EPUB are standard markups that are both interpreted by a web browser and epub reader respectively.</p>
<p>Now here is the pandoc command to generate an epub(3) of the whole site</p>
<pre><code>pandoc -S index.md Lesson1.md Lesson2.md Lesson3.md metadata.epub3.yaml --toc --template=style/template.epub3 --epub-stylesheet=style/epub3.css --epub-cover-image=img/DSP6.png --bibliography=wwwrite.bib -o WWWRITE.epub </code></pre>
<p>As you may notice, the command is a bit more &quot;complex&quot; than the previous HTML one, yet basically resembles it in many ways.</p>
<p>As you may notice, the command is a bit more “complex” than the previous HTML one, yet basically resembles it in many ways.</p>
<p>The arguments</p>
<pre><code>-S index.md Lesson1.md Lesson2.md Lesson3.md Lesson4.md metadata.epub3.yaml -o WWWRITE.epub </code></pre>
<p>specify a list of <em>input</em> files (index.md, Lesson1.md, Lesson2.md, Lesson3.md, Lesson4.md, and metadata.epub3.yaml) and an <em>output</em> file (-o WWWRITE.epub). Pandoc will concatenate input files into a single one when listed as inputs. This is convenient as it enables a writer to segment a book into self-contained chapters for example.</p>
@@ -79,15 +76,12 @@
<p>which tells pandoc to use the specified image as cover page for the EPUB.</p>
<p>Finally the argument</p>
<pre><code>--toc</code></pre>
<p>is a feature that instructs pandoc to generate a &quot;Table Of Content&quot; (toc) out of the various markdown Headings (symbol '#' <a href="Lesson3.html">Lesson3</a>) present in the input file(s).</p>
<p>Let's now have a look at the EPUB output!</p>
<p>is a feature that instructs pandoc to generate a “Table Of Content” (toc) out of the various markdown Headings (symbol ‘#’ <a href="Lesson3.html">Lesson3</a>) present in the input file(s).</p>
<p>Let’s now have a look at the EPUB output!</p>
<h3 id="extra">Extra</h3>
<p><a href="http://johnmacfarlane.net/pandoc/try/">Try pandoc!</a></p>
<p><a href="http://johnmacfarlane.net/pandoc/README.html#epub-metadata">Pandoc User's Guide</a></p>
<p><a href="http://johnmacfarlane.net/pandoc/README.html#epub-metadata">Pandoc User’s Guide</a></p>
<p><a href="http://johnmacfarlane.net/pandoc/getting-started.html">Getting Started</a></p>
<div class="references">
</div>
</content>
</body>
</html>