mirror of
https://github.com/ToshioCP/Gtk4-tutorial.git
synced 2025-01-12 20:03:28 +01:00
368 lines
26 KiB
HTML
368 lines
26 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="generator" content="pandoc" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
|
||
<title>Gtk4 tutorial for beginners</title>
|
||
<style>
|
||
code{white-space: pre-wrap;}
|
||
span.smallcaps{font-variant: small-caps;}
|
||
span.underline{text-decoration: underline;}
|
||
div.column{display: inline-block; vertical-align: top; width: 50%;}
|
||
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
|
||
ul.task-list{list-style: none;}
|
||
pre > code.sourceCode { white-space: pre; position: relative; }
|
||
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
|
||
pre > code.sourceCode > span:empty { height: 1.2em; }
|
||
code.sourceCode > span { color: inherit; text-decoration: inherit; }
|
||
div.sourceCode { margin: 1em 0; }
|
||
pre.sourceCode { margin: 0; }
|
||
@media screen {
|
||
div.sourceCode { overflow: auto; }
|
||
}
|
||
@media print {
|
||
pre > code.sourceCode { white-space: pre-wrap; }
|
||
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
|
||
}
|
||
pre.numberSource code
|
||
{ counter-reset: source-line 0; }
|
||
pre.numberSource code > span
|
||
{ position: relative; left: -4em; counter-increment: source-line; }
|
||
pre.numberSource code > span > a:first-child::before
|
||
{ content: counter(source-line);
|
||
position: relative; left: -1em; text-align: right; vertical-align: baseline;
|
||
border: none; display: inline-block;
|
||
-webkit-touch-callout: none; -webkit-user-select: none;
|
||
-khtml-user-select: none; -moz-user-select: none;
|
||
-ms-user-select: none; user-select: none;
|
||
padding: 0 4px; width: 4em;
|
||
color: #aaaaaa;
|
||
}
|
||
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
|
||
div.sourceCode
|
||
{ }
|
||
@media screen {
|
||
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
|
||
}
|
||
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
|
||
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
|
||
code span.at { color: #7d9029; } /* Attribute */
|
||
code span.bn { color: #40a070; } /* BaseN */
|
||
code span.bu { } /* BuiltIn */
|
||
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
|
||
code span.ch { color: #4070a0; } /* Char */
|
||
code span.cn { color: #880000; } /* Constant */
|
||
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
|
||
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
|
||
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
|
||
code span.dt { color: #902000; } /* DataType */
|
||
code span.dv { color: #40a070; } /* DecVal */
|
||
code span.er { color: #ff0000; font-weight: bold; } /* Error */
|
||
code span.ex { } /* Extension */
|
||
code span.fl { color: #40a070; } /* Float */
|
||
code span.fu { color: #06287e; } /* Function */
|
||
code span.im { } /* Import */
|
||
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
|
||
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
|
||
code span.op { color: #666666; } /* Operator */
|
||
code span.ot { color: #007020; } /* Other */
|
||
code span.pp { color: #bc7a00; } /* Preprocessor */
|
||
code span.sc { color: #4070a0; } /* SpecialChar */
|
||
code span.ss { color: #bb6688; } /* SpecialString */
|
||
code span.st { color: #4070a0; } /* String */
|
||
code span.va { color: #19177c; } /* Variable */
|
||
code span.vs { color: #4070a0; } /* VerbatimString */
|
||
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
|
||
body {width: 1080px; margin: 0 auto; font-size: large;}
|
||
h2 {padding: 10px; background-color: #d0f0d0; }
|
||
div.sourceCode { margin: 10px; padding: 16px 10px 8px 10px; border: 2px solid silver; background-color: ghostwhite; overflow-x:scroll}
|
||
pre:not(.sourceCode) { margin: 10px; padding: 16px 10px 8px 10px; border: 2px solid silver; background-color: ghostwhite; overflow-x:scroll}
|
||
table {margin-left: auto; margin-right: auto; border-collapse: collapse; border: 1px solid;}
|
||
th {padding: 2px 6px; border: 1px solid; background-color: ghostwhite;}
|
||
td {padding: 2px 6px; border: 1px solid;}
|
||
img {display: block; margin-left: auto; margin-right: auto;}
|
||
figcaption {text-align: center;}
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<h1 id="how-to-build-gtk4-tutorial">How to build Gtk4 Tutorial</h1>
|
||
<h2 id="quick-start-guide">Quick start guide</h2>
|
||
<ol type="1">
|
||
<li>You need linux operationg system, ruby, rake, pandoc and latex system.</li>
|
||
<li>download this repository and uncompress the files.</li>
|
||
<li>change your current directory to the top directory of the source files.</li>
|
||
<li>type <code>rake html</code> to create html files. The files are created under <code>html</code> directory.</li>
|
||
<li>type <code>rake pdf</code> to create pdf file. The file is created under <code>latex</code> directory.</li>
|
||
</ol>
|
||
<h2 id="prerequisites">Prerequisites</h2>
|
||
<ul>
|
||
<li>Linux operationg system. The programs in the repository has been tested on Ubuntu 21.04.</li>
|
||
<li>Download the files in this repository. There are two ways to download.
|
||
<ol type="1">
|
||
<li>Use git. Type <code>git clone https://github.com/ToshioCP/Gtk4-tutorial.git</code> on the command-line.</li>
|
||
<li>Download a zip file. Click on the code button (green button) in the top page of this repository. Then, click “Download ZIP”.</li>
|
||
</ol></li>
|
||
<li>Ruby and rake.</li>
|
||
<li>Pandoc. It is used to convert markdown to html and latex.</li>
|
||
<li>Latex system. Texlive2020 or later version is recommended. It is used to generate pdf file.</li>
|
||
</ul>
|
||
<h2 id="github-flavored-markdown">Github flavored markdown</h2>
|
||
<p>When you see <a href="https://github.com/ToshioCP/Gtk4-tutorial">gtk4_tutorial github page</a>, you’ll find the contents of <code>Readme.md</code> below the list of files. This file is written in markdown language. A markdown file has <code>.md</code> suffix.</p>
|
||
<p>There are several kinds of markdown language. <code>Readme.md</code> uses ‘github flavored markdown’, which is often shortened as GFM. Markdown files in the <code>gfm</code> directory also written in GFM. If you are not familiar with it, refer to the page <a href="https://github.github.com/gfm/">github flavor markdown spec</a>.</p>
|
||
<h2 id="pandocs-markdown">Pandoc’s markdown</h2>
|
||
<p>This tutorial also uses another markdown – pandoc’s markdown. Pandoc is a converter between markdown, html, latex, word docx and so on. This type of markdown is used to convert markdown to html and latex.</p>
|
||
<h2 id="src.md-file">Src.md file</h2>
|
||
<p>Src.md file has “.src.md” suffix. The syntax of .src.md file is similar to markdown but it has a special command which isn’t included in markdown syntax. It is @@@ command. The command starts with a line that begins with “@@@” and it ends with a line “@@@”. For example,</p>
|
||
<pre><code>@@@include
|
||
tfeapplication.c
|
||
@@@</code></pre>
|
||
<p>There are four types of @@@ command.</p>
|
||
<h3 id="include">@@<span class="citation" data-cites="include">@include</span></h3>
|
||
<p>This type of @@@ command starts with a line “@@<span class="citation" data-cites="include">@include</span>”.</p>
|
||
<pre><code>@@@include
|
||
tfeapplication.c
|
||
@@@</code></pre>
|
||
<p>This command replaces itself with the text read from the C source files surrounded by <code>@@@include</code> and <code>@@@</code>. If a function list follows the filename, only the functions are read. If no function list is given, the command can read any text file other than C source file.</p>
|
||
<pre><code>@@@include
|
||
tfeapplication.c main startup
|
||
@@@</code></pre>
|
||
<p>The command above is replaced by the contents of <code>main</code> and <code>startup</code> functions in <code>tfeapplication.c</code>.</p>
|
||
<pre><code>@@@include
|
||
lib_src2md.rb
|
||
@@@</code></pre>
|
||
<p>This command is replaced by the contents of <code>lib_src2md.rb</code> which is a ruby script (not C file).</p>
|
||
<p>The inserted text is converted to fence code block. Fence code block begins with <code>~~~</code> and ends with <code>~~~</code>. The contents are displayed verbatim. <code>~~~</code> is look like a fence so the block is called “fence code block”.</p>
|
||
<p>If the target markdown is GFM, then an info string follows the beginning fence. The following example shows that the @@@ command includes a C source file <code>sample.c</code>.</p>
|
||
<pre><code>$ cat src/sample.c
|
||
int
|
||
main (int argc, char **argv) {
|
||
... ...
|
||
}
|
||
$cat src/sample.src.md
|
||
... ...
|
||
@@@include -N
|
||
sample.c
|
||
@@@
|
||
... ...
|
||
$ ruby src2md.rb src/sample.src.md gfm/sample.md
|
||
$ cat gfm/sample.md
|
||
... ...
|
||
~~~C
|
||
int
|
||
main (int argc, char **argv) {
|
||
... ...
|
||
}
|
||
~~~
|
||
... ...</code></pre>
|
||
<p>Info strings are usually languages like C, ruby, xml and so on. This string is decided with the filename extension.</p>
|
||
<ul>
|
||
<li><code>.c</code> => C</li>
|
||
<li><code>.rb</code> => ruby</li>
|
||
<li><code>.xml</code> => xml</li>
|
||
</ul>
|
||
<p>The supported language is written in line 290 and 291 in <code>lib/lib_src2md.rb</code>.</p>
|
||
<p>A line number is inserted at the top of each line in the code block. If you don’t want to insert it, give “-N” option to @@<span class="citation" data-cites="include">@include</span> command.</p>
|
||
<p>Options:</p>
|
||
<ul>
|
||
<li><code>-n</code>: Inserts a line number at the top of each line (default).</li>
|
||
<li><code>-N</code>: No line number is inserted.</li>
|
||
</ul>
|
||
<p>The following shows that line numbers are inserted at the beginning of lines.</p>
|
||
<pre><code>$cat src/sample.src.md
|
||
... ...
|
||
@@@include
|
||
sample.c
|
||
@@@
|
||
... ...
|
||
$ ruby src2md.rb src/sample.src.md gfm/sample.md
|
||
$ cat gfm/sample.md
|
||
... ...
|
||
~~~C
|
||
1 int
|
||
2 main (int argc, char **argv) {
|
||
... ...
|
||
14 }
|
||
~~~
|
||
... ...</code></pre>
|
||
<p>If the target markdown is an intermediate file to html, then another type of info string follows the beginning fence. If @@<span class="citation" data-cites="include">@include</span> command doesn’t have -N option, then the generated markdown is:</p>
|
||
<pre><code>~~~{.C .numberLines}
|
||
int
|
||
main (int argc, char **argv) {
|
||
... ...
|
||
}
|
||
~~~</code></pre>
|
||
<p>The info string <code>.C</code> specifies C language. The info string <code>.numberLines</code> is a class of the pandoc markdown. If the class is given, pandoc generates CSS to insert line numbers to the source code in the html file. That’s why the fence code block in the markdown doesn’t have line numbers, which is different from gfm markdown. If <code>-N</code> option is given, then the info string is <code>{.C}</code> only.</p>
|
||
<p>If the target markdown is an intermediate file to latex, then the same info string follows the beginning fence.</p>
|
||
<pre><code>~~~{.C .numberLines}
|
||
int
|
||
main (int argc, char **argv) {
|
||
... ...
|
||
}
|
||
~~~</code></pre>
|
||
<p>Rake uses pandoc with –listings option when it converts markdown to latex. The generated latex file uses listings package to list source files instead of verbatim environment. The markdwon above is converted to the following latex source file.</p>
|
||
<pre><code>\begin{lstlisting}[language=C, numbers=left]
|
||
int
|
||
main (int argc, char **argv) {
|
||
... ...
|
||
}
|
||
\end{lstlisting}</code></pre>
|
||
<p>Listing package can color or emphasize keywords, strings, comments and directives. But it doesn’t analyze the syntax or token of the language, so the kind of emphasis target is limited.</p>
|
||
<p>@@<span class="citation" data-cites="include">@include</span> command have two advantages.</p>
|
||
<ol type="1">
|
||
<li>Less typing.</li>
|
||
<li>You don’t need to modify your .src.md file, even if the C source file is modified.</li>
|
||
</ol>
|
||
<h3 id="shell">@@<span class="citation" data-cites="shell">@shell</span></h3>
|
||
<p>This type of @@@ command starts with a line begins with “@@<span class="citation" data-cites="shell">@shell</span>”.</p>
|
||
<pre><code>@@@shell
|
||
shell command
|
||
... ...
|
||
@@@</code></pre>
|
||
<p>This command replaces itself with:</p>
|
||
<ul>
|
||
<li>the shell command</li>
|
||
<li>the standard output from the shell command</li>
|
||
</ul>
|
||
<p>For example,</p>
|
||
<pre><code>@@@shell
|
||
wc Rakefile
|
||
@@@</code></pre>
|
||
<p>This is converted to:</p>
|
||
<pre><code>~~~
|
||
$ wc Rakefile
|
||
164 475 4971 Rakefile
|
||
~~~</code></pre>
|
||
<h3 id="if-series">@@<span class="citation" data-cites="if">@if</span> series</h3>
|
||
<p>This type of @@@ command starts with a line begins with “@@<span class="citation" data-cites="if">@if</span>”, and followed by “@@<span class="citation" data-cites="elif">@elif</span>”, “@@<span class="citation" data-cites="else">@else</span>” or “@@<span class="citation" data-cites="end">@end</span>”. This command is similar to “#if”, “#elif”, #else" and “#endif” directives in C preprocessor. For example,</p>
|
||
<pre><code>@@@if gfm
|
||
Refer to [tfetextview API reference](../src/tfetextview_doc.md)
|
||
@@@elif html
|
||
Refer to [tfetextview API reference](../src/tfetextview_doc.html)
|
||
@@@elif latex
|
||
Refer to tfetextview API reference in appendix.
|
||
@@@end</code></pre>
|
||
<p><code>@@@if</code> and <code>@@@elif</code> have conditions. They are <code>gfm</code>, <code>html</code> or <code>latex</code> so far.</p>
|
||
<ul>
|
||
<li>gfm: if the target is GFM</li>
|
||
<li>html: if the target is html</li>
|
||
<li>latex: if the target is latex (or pdf).</li>
|
||
</ul>
|
||
<p>Other type of conditions may be available in the future version.</p>
|
||
<p>The code analyzing @@<span class="citation" data-cites="if">@if</span> series command is rather complicated. It is based on the state diagram below.</p>
|
||
<figure>
|
||
<img src="../image/state_diagram.png" alt="" /><figcaption>state diagram</figcaption>
|
||
</figure>
|
||
<h3 id="table">@@<span class="citation" data-cites="table">@table</span></h3>
|
||
<p>This type of @@@ command starts with a line begins with “@@<span class="citation" data-cites="table">@table</span>”. The contents of this command is a table of GFM or pandoc’s markdown. The command makes a table easy to read. For example, a text file <code>sample.md</code> has a table like this:</p>
|
||
<pre><code>Price list
|
||
|
||
@@@table
|
||
|item|price|
|
||
|:---:|:---:|
|
||
|mouse|$10|
|
||
|PC|$500|
|
||
@@@</code></pre>
|
||
<p>The command changes this into:</p>
|
||
<pre><code>Price list
|
||
|
||
|item |price|
|
||
|:---:|:---:|
|
||
|mouse| $10 |
|
||
| PC |$500 |</code></pre>
|
||
<p>This command just changes the appearance of the table. There’s no influence on html/latex files that is converted from the markdown.</p>
|
||
<p>A script <code>mktbl.rb</code> supports this command. If you run the script like this:</p>
|
||
<pre><code>$ ruby mktbl.rb sample.md</code></pre>
|
||
<p>Then, the appearance of the table will be changed The script also makes a backup file <code>sample.md.bak</code>.</p>
|
||
<p>The task of the script seems easy, but the program is not so simple. The script <code>mktbl.rb</code> uses a library <code>lib/lib_src2md.rb</code></p>
|
||
<p>@@<span class="citation" data-cites="commands">@commands</span> are effective in the whole text. This means you can’t stop the @@<span class="citation" data-cites="commands">@commands</span>. But sometimes you want to show the commands literally like this document. One solution is to add four blanks at the top of the line. Then @@<span class="citation" data-cites="commands">@commands</span> are not effective because @@<span class="citation" data-cites="commands">@commands</span> must be at the top of the line.</p>
|
||
<h2 id="conversion">Conversion</h2>
|
||
<p>The @@@ commands above (@@<span class="citation" data-cites="include">@include</span>, @@<span class="citation" data-cites="shell">@shell</span>, @@<span class="citation" data-cites="if">@if</span> series and @@<span class="citation" data-cites="table">@table</span>) are carried out by a method <code>src2md</code>, which is in the file <code>lib/lib_src2md.rb</code>. This method converts <code>src.md</code> file into <code>md</code> file. In addition, some other conversions are made by <code>src2md</code> method.</p>
|
||
<ul>
|
||
<li>Relative links are changed according to the change of the base directory.</li>
|
||
<li>Size option in image link is removed when the destination is GFM or html.</li>
|
||
<li>Relative link is removed when the destination is latex.</li>
|
||
</ul>
|
||
<p>The order of the conversions are:</p>
|
||
<ol type="1">
|
||
<li>@@<span class="citation" data-cites="if">@if</span></li>
|
||
<li>@@<span class="citation" data-cites="table">@table</span></li>
|
||
<li>@@<span class="citation" data-cites="include">@include</span></li>
|
||
<li>@@<span class="citation" data-cites="shell">@shell</span></li>
|
||
<li>others</li>
|
||
</ol>
|
||
<p>There is <code>src2md.rb</code> file in the top directory of this repository. It just invokes the method <code>src2md</code>. In the same way, the method is called in the action in <code>Rakefile</code>.</p>
|
||
<h2 id="directory-structure">Directory structure</h2>
|
||
<p>There are six directories under <code>gtk4_tutorial</code> directory. They are <code>gfm</code>, <code>src</code>, <code>image</code>, <code>html</code>, <code>latex</code> and <code>lib</code>. Three directories <code>gfm</code>, <code>html</code> and <code>latex</code> are the destination directories for GFM, html and latex files respectively. It is possible that these three directories don’t exist before the conversion.</p>
|
||
<ul>
|
||
<li>src: This directory contains .src.md files and C-related source files.</li>
|
||
<li>image: This directory contains image files like png or jpg.</li>
|
||
<li>gfm: <code>rake</code> converts src.md files to GFM files and store them in this directory.</li>
|
||
<li>html: This directory is empty at first. <code>rake html</code> will convert src.md files to html files and store them in this directory.</li>
|
||
<li>latex: This directory is empty at first. <code>rake latex</code> will convert src.md files to latex files and store them in this directory. <code>rake pdf</code> creates pdf file in <code>latex</code> directory.</li>
|
||
<li>lib: This directory includes ruby library files.</li>
|
||
</ul>
|
||
<h2 id="src-directory-and-the-top-directory">Src directory and the top directory</h2>
|
||
<p>Src directory contains .src.md files and C-related source files. The top directory, which is gtk_tutorial directory, contains <code>Rakefile</code>, <code>src2md.rb</code> and some other files. When <code>Readme.md</code> is generated, it will be located at the top directory. <code>Readme.md</code> has title, abstract, table of contents with links to GFM files.</p>
|
||
<p>Rakefile describes how to convert .src.md files into GFM files. Rake carries out the conversion according to the <code>Rakefile</code>.</p>
|
||
<h2 id="the-name-of-files-in-src-directory">The name of files in src directory</h2>
|
||
<p>Each file in <code>src</code> directory is an abstract, sections of the whole document and other .src.md files. An <code>abstract.src.md</code> contains the abstract of this tutorial. Each section filename is “sec”, number of the section and “.src.md” suffix. For example, “sec1.src.md”, “sec5.src.md” or “sec12.src.md”. They are the files correspond to section 1, section 5 and section 12 respectively.</p>
|
||
<h2 id="c-source-file-directory">C source file directory</h2>
|
||
<p>Most of .src.md files have <code>@@@include</code> commands and they include C source files. Such C source files are located in the subdirectories of <code>src</code> directory.</p>
|
||
<p>Those C files have been compiled and tested. When you compile source files, some auxiliary files and a target file like <code>a.out</code> are created. Or <code>_build</code> directory is made when <code>meson</code> and <code>ninja</code> is used when compiling. Those files are not tracked by <code>git</code> because they are specified in <code>.gitignore</code>.</p>
|
||
<p>The name of the subdirectories should be independent of section names. It is because of renumbering, which will be explained in the next subsection.</p>
|
||
<h2 id="renumbering">Renumbering</h2>
|
||
<p>Sometimes you might want to insert a section. For example, you want to insert it between section 4 and section 5. You can make a temporary section 4.5, that is a rational number between 4 and 5. However, section numbers are usually integer so section 4.5 must be changed to section 5. And the numbers of the following sections must be increased by one.</p>
|
||
<p>This renumbering is done by a method <code>renum!</code> of the class <code>Sec_files</code>. The method and class is written in <code>lib/lib_sec_file.rb</code>.</p>
|
||
<ul>
|
||
<li>It changes file names.</li>
|
||
<li>If there are references to sections in .src.md files, the section numbers will be automatically renumbered.</li>
|
||
</ul>
|
||
<h2 id="rakefile">Rakefile</h2>
|
||
<p>Rakefile is a similar file to Makefile but controlled by rake, which is a make-like program written in ruby. Rakefile in this tutorial has the following tasks.</p>
|
||
<ul>
|
||
<li>md: generate GFM markdown files. This is the default.</li>
|
||
<li>html: generate html files.</li>
|
||
<li>pdf: generate latex files and a pdf file, which is compiled by lualatex.</li>
|
||
<li>all: generate md, html and pdf files.</li>
|
||
</ul>
|
||
<p>Rake does renumbering before the tasks above.</p>
|
||
<h2 id="generate-gfm-markdown-files">Generate GFM markdown files</h2>
|
||
<p>Markdown files (GFM) are generated by rake.</p>
|
||
<pre><code>$ rake</code></pre>
|
||
<p>This command generates <code>Readme.md</code> with <code>src/abstract.src.md</code> and titles of .src.md files. At the same time, it converts each .src.md file into GFM file under <code>gfm</code> directory. Navigation lines are added at the top and bottom of each markdown section file.</p>
|
||
<p>You can describe width and height of images in .src.md files. For example,</p>
|
||
<pre><code></code></pre>
|
||
<p>The size between left brace and right brace is used in latex file and it is not fit to GFM syntax. So the size is removed in the conversion.</p>
|
||
<p>If a .src.md file has relative URL link, it will be changed by conversion. Because .src.md files are located under <code>src</code> directory and GFM files are located under <code>gfm</code> directory, base URL of GFM files is different from base URL of .src.md files. For example, <code>[src/sample.c](../src/sample.c)</code> is translated to <code>[src/sample.c](../src/sample.c)</code>.</p>
|
||
<p>If a link points another .src.md file, then the target filename will be changed to .md file. For example, <code>[Section 5](sec5.html)</code> is translated to <code>[Section 5](../src/sec5.md)</code>.</p>
|
||
<p>If you want to clean the directory, that means remove all the generated markdown files, type <code>rake clean</code>.</p>
|
||
<pre><code>$ rake clean</code></pre>
|
||
<p>Sometimes this is necessary before generating GFM files.</p>
|
||
<pre><code>$ rake clean
|
||
$ rake</code></pre>
|
||
<p>For example, if you append a new section and other files are still the same as before, <code>rake clean</code> is necessary. Because the navigation of the previous section of the newly added section needs to be updated. If you don’t do <code>rake clean</code>, then it won’t be updated because the the timestamp of .md file in gfm is newer than the one of .src.md file. In this case, using <code>touch</code> to the previous section .src.md also works to update the file.</p>
|
||
<p>If you see the github repository (ToshioCP/Gtk4-tutorial), <code>Readme.md</code> is shown below the code. And <code>Readme.md</code> includes links to each markdown files. The repository not only stores source files but also shows the whole tutorial.</p>
|
||
<h2 id="generate-html-files">Generate html files</h2>
|
||
<p>Src.md files can be translated to html files. You need pandoc to do this. Most linux distribution has pandoc package. Refer to your distribution document to install it.</p>
|
||
<p>Type <code>rake html</code> to generate html files.</p>
|
||
<pre><code>$ rake html</code></pre>
|
||
<p>First, it generates pandoc’s markdown files under <code>html</code> directory. Then, pandoc converts them to html files. The width and height of image files are removed.</p>
|
||
<p><code>index.html</code> is the top html file. If you want to clean <code>html</code> directory, type <code>rake cleanhtml</code></p>
|
||
<pre><code>$ rake cleanhtml</code></pre>
|
||
<p>Every html file has stylesheet in its header. This is created by <code>lib/lib_add_head_tail_html.rb</code>. This script has a sample markdown code and convert it with pandoc and <code>-s</code> option. Pandoc generates a html file with header. The script extracts the header and use it for html files. You can customize the style by modifying <code>lib/lib_add_head_tail_html.rb</code>.</p>
|
||
<p><code>html</code> directory contains all the necessary html files. So if you want to upload the html files to your own web site, just upload the files in the <code>html</code> directory.</p>
|
||
<h2 id="generate-a-pdf-file">Generate a pdf file</h2>
|
||
<p>You need pandoc to convert markdown files into latex source files.</p>
|
||
<p>Type <code>rake pdf</code> to generate latex files and finally make a pdf file.</p>
|
||
<pre><code>$ rake pdf</code></pre>
|
||
<p>First, it generates pandoc’s markdown files under <code>latex</code> directory. Then, pandoc converts them into latex files. Links to files or directories are removed because latex doesn’t support them. However, links to full URL and image files are kept. Image size is set with the size between the left brace and right brace.</p>
|
||
<pre><code></code></pre>
|
||
<p>You need to specify appropriate width and height. It is almost <code>0.015 x pixels</code> cm. For example, if the width of an image is 400 pixels, the width in a latex file will be almost 6cm.</p>
|
||
<p>A file <code>main.tex</code> is the root file of all the generated latex files. It has <code>\input</code> commands, which inserts each section file, between <code>\begin{document}</code> and <code>\end{document}</code>. It also has <code>\input</code>, which inserts <code>helper.tex</code>, in the preamble. Two files <code>main.tex</code> and <code>helper.tex</code> are created by <code>lib/lib_gen_main_tex.rb</code>. It has a sample markdown code and converts it witn <code>pandoc -s</code>. Then, it extracts the preamble in the generated file and puts it into <code>helper.tex</code>. You can customize <code>helper.tex</code> by modifying <code>lib/lib_gen_main_tex.rb</code>.</p>
|
||
<p>Finally, lualatex compiles the <code>main.tex</code> into a pdf file.</p>
|
||
<p>If you want to clean <code>latex</code> directory, type <code>rake cleanlatex</code></p>
|
||
<pre><code>$ rake cleanlatex</code></pre>
|
||
<p>This removes all the latex source files and a pdf file.</p>
|
||
</body>
|
||
</html>
|