docs/Readme_for_developers.html - main - evo/Gtk4-tutorial

docs/Readme_for_developers.html
624 строки29 KB
Toshio Sekiya
Update Readme_for_developers files.
13 янв 2026, 09:35
13 янв 2026, 09:358f00680
  <!DOCTYPE html>
  <html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="generator" content="pandoc" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-9ndCyUaIbzAi2FUVXJi0CjmCapSmO7SnpJef0486qhLnuZ2cdeRhO02iuK6FUUVM" crossorigin="anonymous">
    <title>GTK 4 tutorial</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{overflow: visible;}
      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::after
        { 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 */
      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 style="padding-top: 70px;">
    <div class="container">
    <nav class="navbar fixed-top navbar-expand-lg navbar-dark bg-primary">
      <div class="container-fluid">
        <span class="navbar-brand">Gtk4 tutorial</span>
        <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
          <span class="navbar-toggler-icon"></span>
        </button>
        <div class="collapse navbar-collapse" id="navbarSupportedContent">
          <ul class="navbar-nav me-auto mb-2 mb-lg-0">
            <li class="nav-item">
<a class="nav-link" href="index.html">Home</a>
</li>

            
            
          </ul>
        </div>
      </div>
    </nav>
      <div class="row justify-content-center">
        <div class="col-xl-10 col-xxl-9">
<h1 id="how-to-build-the-gtk4-tutorial">How to Build the Gtk4
Tutorial</h1>
<h2 id="quick-start-guide">Quick Start Guide</h2>
<ol type="1">
<li>You will need a Linux operating system, Ruby, Rake, Pandoc, and a
LaTeX system.</li>
<li>Download this repository and extract its contents.</li>
<li>Change your current directory to the root directory of the source
files.</li>
<li>Run <code>rake html</code> to create HTML files. These files will be
generated in the <code>docs</code> directory.</li>
<li>Run <code>rake pdf</code> to create a PDF file. The file is
generated in the <code>latex</code> directory.</li>
</ol>
<h2 id="prerequisites">Prerequisites</h2>
<ul>
<li>Linux operating system: The programs in this repository have been
tested on Ubuntu 21.04.</li>
<li>Files in this repository: There are two ways to obtain the files:
<ol type="1">
<li>Using Git: Run
<code>git clone https://github.com/ToshioCP/Gtk4-tutorial.git</code> in
your terminal.</li>
<li>Download Zip: Click the green <code>Code</code> button on the
repository’s main page and select “Download ZIP”.</li>
</ol></li>
<li>Ruby and Rake.</li>
<li>Pandoc: Used to convert Markdown to HTML and/or LaTeX.</li>
<li>Latex system: Tex Live 2020 or later is recommended for generating
the PDF file.</li>
</ul>
<h2 id="markdown-variants-and-.src.md-files">Markdown Variants and
.src.md Files</h2>
<h3 id="github-flavored-markdown-gfm">GitHub Flavored Markdown
(GFM)</h3>
<p>When you visit the <a
href="https://github.com/ToshioCP/Gtk4-tutorial">Gtk4_tutorial GitHub
repository</a>, the <code>README.md</code> file is displayed on the main
page. This file is written in Markdown, which typically uses the .md
extension.</p>
<p>There are several dialects of Markdown. The <code>README.md</code>
file uses “GitHub Flavored Markdown” or simply, GFM. The files in the
<code>gfm</code> directory are also written in GFM. For more details,
please refer to the <a href="https://github.github.com/gfm/">GitHub
Flavor Markdown spec</a>.</p>
<h3 id="pandocs-markdown">Pandoc’s Markdown</h3>
<p>This tutorial also utilizes another dialect known as “Pandoc’s
Markdown.” Pandoc is a powerful tool for converting between formats such
as Markdown, HTML, LaTeX, and Word (.docx). In this project, this
specific dialect is used when converting the source files into HTML or
LaTeX.</p>
<h2 id="the-.src.md-file-and-commands">The .src.md File and @@@
Commands</h2>
<h3 id="the-.src.md-file">The .src.md File</h3>
<p>Source files in this project use the .src.md extension. The syntax of
a .src.md file is similar to standard Markdown, but it includes a
special custom command: the @@@ command. Each command block starts with
a line beginning with @@@, followed by a command name and ends with a
line containing only <code>@@@</code>.</p>
<p>For example,</p>
<pre><code>@@@include
tfeapplication.c
@@@</code></pre>
<p>The first line is called a directive, which consists of “@@@” and
“include” (the command name).</p>
<p>There are four types of @@@ commands, as described below.</p>
<h3 id="include">@@<span class="citation"
data-cites="include">@include</span></h3>
<p>This command starts with the directive <code>@@@include</code>.</p>
<pre><code>@@@include
tfeapplication.c
@@@</code></pre>
<p>It is replaced by the content of the source file specified between
the <code>@@@include</code> and <code>@@@</code> markers. The example
above includes a C source file <code>tfeapplication.c</code>.</p>
<p>If specific function names follow the filename, only those functions
will be extracted.</p>
<pre><code>@@@include
tfeapplication.c main startup
@@@</code></pre>
<p>The above command would be replaced specifically by the
<code>main</code> and <code>startup</code> functions found in
<code>tfeapplication.c</code>.</p>
<p>You can also include source files from other languages. The following
example shows that the ruby file <code>lib_src2md.rb</code> is inserted
by the command.</p>
<pre><code>@@@include
lib_src2md.rb
@@@</code></pre>
<p>Note that function-specific extraction is only supported for C source
files.</p>
<p>The inserted text is automatically converted into a fenced code
block. Fenced code blocks start and end with <code>~~~</code>, and the
contents are displayed verbatim. Three consecutive tildes are called a
“code fence” because they look like a fence.</p>
<p>When the target format is GFM, an “info string” (language identifier)
is added after the opening 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
$ 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
identifier is determined by the file extension:</p>
<ul>
<li><code>.c</code> =&gt; C</li>
<li><code>.rb</code> =&gt; ruby</li>
<li><code>.xml</code> =&gt; xml</li>
</ul>
<p>The list of supported languages is defined in the <code>lang</code>
method within <code>lib/lib_src2md.rb</code>.</p>
<p>By default, line numbers are inserted at the beginning of each line.
To disable this, use the -N option with the <code>@@@include</code>
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 the line numbers are inserted at the
beginning of each line.</p>
<pre><code>$cat src/sample.src.md
  ... ...
@@@include
sample.c
@@@
  ... ...
$ ruby src2md.rb src/sample.src.md
$ cat gfm/sample.md
  ... ...
~~~C
 1 int
 2 main (int argc, char **argv) {
  ... ...
14 }
~~~
  ... ...</code></pre>
<p>If the Markdown file is an intermediate step for HTML output, a
different info string is used. If the <code>@@@include</code> command
doesn’t have <code>-N</code> 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
<code>.numberLines</code> class is a feature of Pandoc’s Markdown; it
allows Pandoc to generate CSS that inserts line numbers into the final
HTML. As a result, the fenced code block in the Markdown source does not
contain hard-coded line numbers, unlike GFM. If <code>-N</code> option
is given, then the info string is <code>{.C}</code> only.</p>
<p>If the Markdown file is an intermediate step for LaTeX file, 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 the –listings option to convert Markdown into a
LaTeX file. The resulting LaTeX file utilizes the listings package to
display source code rather than a simple verbatim environment. The
Markdown file 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>The listings package can color or emphasize keywords, strings,
comments and directives. But it doesn’t really analyze the syntax of the
language, so the emphasis tokens are limited.</p>
<p>The @@<span class="citation" data-cites="include">@include</span>
command has two advantages:</p>
<ol type="1">
<li>Less typing.</li>
<li>Modifying a C source file does not require manual updates to the
.src.md file, making maintenance much easier for authors.</li>
</ol>
<h3 id="shell">@@<span class="citation"
data-cites="shell">@shell</span></h3>
<p>This command begins with the <code>@@@shell</code> directive.</p>
<pre><code>@@@shell
shell command
 ... ...
@@@</code></pre>
<p>It is replaced by both the executed command itself and its standard
output.</p>
<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-conditional-branching">@@<span class="citation"
data-cites="if">@if</span> series (Conditional Branching)</h3>
<p>This command block starts with <code>@@@if</code> and can be followed
by <code>@@@elif</code>, <code>@@@else</code>, or <code>@@@end</code>.
These work similarly to the <code>#if</code>, <code>#elif</code>,
<code>#else</code>, and <code>#endif</code> preprocessor directives in
C. For example,</p>
<pre><code>@@@if gfm
Refer to  [tfetextview API reference](tfetextview_doc.md)
@@@elif html
Refer to  [tfetextview API reference](tfetextview_doc.html)
@@@elif latex
Refer to tfetextview API reference in appendix.
@@@end</code></pre>
<p>The directives <code>@@@if</code> and <code>@@@elif</code> accept
conditions such as <code>gfm</code>, <code>html</code>, or
<code>latex</code>.</p>
<ul>
<li>gfm: If the target is GFM.</li>
<li>html: If the target is HTML.</li>
<li>latex: If the target is 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 commands is rather complicated. It is
based on the state diagram below.</p>
<figure>
<img src="image/state_diagram.png" alt="state diagram" />
<figcaption aria-hidden="true">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 that begins with
<code>@@@table</code>. This command takes a GFM or Pandoc-style table as
input and formats it to be more human-readable in the source file. 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 only affects the visual alignment of the table in
Markdown; it does not change the final HTML or LaTeX output. Notice that
the command supports only the above type of Markdown table format.</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 tables in ‘sample.md’ will be arranged. 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 the library
<code>lib/lib_src2md.rb</code></p>
<p>The @@@ commands are effective throughout the whole text. This means
you can’t stop the @@@ commands. But sometimes you want to show the
commands literally. One solution is to add four blanks at the top of the
lines. Then @@@ commands are not effective because <code>@@@</code> must
be at the top of the line.</p>
<h2 id="conversion">Conversion</h2>
<p>The @@@ commands are processed by the <code>src2md</code> method in
<code>lib/lib_src2md.rb</code>. This method converts .src.md files into
standard Markdown files. In addition, the <code>src2md</code> method
performs the following transformations:</p>
<ul>
<li><strong>Relative links:</strong> These are updated to reflect the
change in the base directory.</li>
<li><strong>Image sizes:</strong> Image size options (e.g., {width=…})
are removed when the target format is GFM or HTML.</li>
<li><strong>HTML-specific links:</strong> For HTML output, all relative
links are removed, except for those pointing to other
<code>.src.md</code> files.</li>
<li><strong>LaTeX-specific links:</strong> For LaTeX output, all
relative links are removed.</li>
</ul>
<p>The conversions are executed in the following order:</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>The <code>src2md.rb</code> script in the root directory simply
invokes the <code>src2md</code> method. Similarly, the
<code>Rakefile</code> also calls this method as part of its tasks.</p>
<h2 id="directory-structure">Directory Structure</h2>
<p>The <code>Gtk4-tutorial</code> directory contains seven
subdirectories: <code>gfm</code>, <code>docs</code>, <code>latex</code>,
<code>src</code>, <code>image</code>, <code>test</code> and
<code>lib</code>. The <code>gfm</code>, <code>docs</code>, and
<code>latex</code> directories serve as the destination folders for GFM,
HTML, and LaTeX files, respectively. Note that these three destination
directories may not exist at the beginning of the conversion. The
conversion program automatically makes the directories if they do not
exist.</p>
<ul>
<li><code>src</code>: Contains the .src.md source files and C source
code.</li>
<li><code>image</code>: Contains image files, such as PNG or JPG.</li>
<li><code>gfm</code>: Contains GFM files converted by Rake from the
.src.md source files.</li>
<li><code>docs</code>: Contains HTML files converted by Rake
(<code>rake html</code>) from the .src.md source files.</li>
<li><code>latex</code>: Contains a PDF file and intermediate LaTeX files
converted by Rake (<code>rake pdf</code>) from the .src.md source
files.</li>
<li><code>lib</code>: Contains ruby library files.</li>
<li><code>test</code>: Contains test files, which are executed by
running <code>rake test</code> in the terminal.</li>
</ul>
<h2 id="organization-of-the-source-files">Organization of the Source
Files</h2>
<h3 id="the-src-and-root-directory">The <code>src</code> and Root
Directory</h3>
<p>The <code>src</code> directory contains .src.md files and C-related
source files. The root directory (<code>Gtk4-tutorial</code>) contains
the <code>Rakefile</code>, <code>src2md.rb</code>, and other essential
files. The generated <code>README.md</code> is placed in this root
directory. It includes the title, an overview, and a table of contents
with links to the GFM files.</p>
<p><code>Rakefile</code> describes how to convert .src.md files into
GFM, HTML and/or PDF files. Rake converts the source files according to
the <code>Rakefile</code>.</p>
<h3 id="file-naming-in-the-src-directory">File Naming in the
<code>src</code> Directory</h3>
<p>The <code>src</code> directory contains <code>abstract.src.md</code>,
individual section files, and other .src.md documents. Rake converts
<code>abstract.src.md</code> to the overview of this tutorial such as
<code>gfm/README.md</code>, <code>docs/index.html</code> and/or
corresponding part of the PDF file. Section files are named using the
prefix “sec” followed by the section number and the .src.md extension
(e.g., <code>sec1.src.md</code>, <code>sec5.src.md</code>, or
<code>sec12.src.md</code>). They are the files that correspond to the
section 1, section 5 and section 12 respectively.</p>
<h3 id="c-source-code-storage">C Source Code Storage</h3>
<p>Most .src.md files use the <code>@@@include</code> command to pull in
C source code. These C files are organized into subdirectories under the
<code>src</code> directory.</p>
<p>All included C files have been tested. When you compile the source
files, some auxiliary files and a target file like <code>a.out</code>
are created. When you use <code>meson</code> and <code>ninja</code> for
compilation, they create a temporary <code>_build</code> directory.
Those files and directories are ignored by Git as specified in the
.gitignore file.</p>
<h2 id="renumbering">Renumbering</h2>
<p>Occasionally, you may need to insert a new section, for example,
between Section 4 and Section 5. You can temporarily name it “Section
4.5” to place it between the two. However, since section numbers should
be integers, Section 4.5 must be renamed to Section 5, and all
subsequent section numbers must be incremented by one.</p>
<p>This renumbering process is handled automatically by the
<code>renumber</code> method in <code>lib/lib_renumber.rb</code>. This
method performs two main tasks:</p>
<ul>
<li>Renaming the physical files.</li>
<li>Updating any internal links or references within the .src.md files
to match the new section numbers.</li>
</ul>
<h2 id="rakefile">Rakefile</h2>
<p>The <code>Rakefile</code> is similar to a Makefile but is executed by
Rake, a Ruby-based build tool. The <code>Rakefile</code> in this project
defines the following tasks:</p>
<ul>
<li><code>md</code>: Generates GFM Markdown files (default task).</li>
<li><code>html</code>: Generates HTML files.</li>
<li><code>pdf</code>: Generates LaTeX source files and compiles them
into a PDF using lualatex.</li>
<li><code>all</code>: Generates GFM, HTML and PDF files.</li>
<li><code>clean</code>: Deletes LaTeX intermediate files.</li>
<li><code>clobber</code>: Deletes all the generated files.</li>
</ul>
<p>Rake automatically performs the renumbering process before executing
any of these tasks.</p>
<h3 id="generating-gfm-files">Generating GFM Files</h3>
<p>You can generate GFM files by simply running Rake in your
terminal:</p>
<pre><code>$ rake</code></pre>
<p>This command generates <code>README.md</code> from
<code>src/abstract.src.md</code> and titles of each .src.md file. At the
same time, it converts each .src.md file into a GFM file and store it
under the <code>gfm</code> directory. Navigation links (e.g., “Next” and
“Previous”) are automatically inserted to the top and bottom of each
generated Markdown file.</p>
<p>You can specify the width and height of images within .src.md files
using the following syntax:</p>
<pre><code>![sample image](../image/sample_image.png){width=10cm height=6cm}</code></pre>
<p>Since image size attributes (e.g., {width=10cm}) are specific to
LaTeX and are not supported by GFM syntax, they are automatically
stripped out during the conversion to GFM or HTML.</p>
<p>If a .src.md file has relative URL links, they will be changed by
conversion, since GFM files are located under the <code>gfm</code>
directory while .src.md files lie in the <code>src</code> directory.
That means the base directory of the relative links is different. For
example, <code>[src/sample.c](sample.c)</code> is translated to
<code>[src/sample.c](../src/sample.c)</code>.</p>
<p>Similarly, if a link points another .src.md file, the target
extension is automatically updated to .md. For example,
<code>[Section 5](sec5.src.md)</code> is translated to
<code>[Section 5](sec5.md)</code>.</p>
<p>The following command cleans all the generated files.</p>
<pre><code>$ rake clobber</code></pre>
<p>Sometimes this is necessary before generating GFM files.</p>
<pre><code>$ rake clobber
$ rake</code></pre>
<p>If you add a new section, running rake clobber is necessary to ensure
that the “Next” and “Previous” navigation links are correctly updated.
Without <code>rake clobber</code>, these links may not be updated
because Rake’s dependency tracking will see that the existing .md files
in the <code>gfm</code> directory are already newer than their
corresponding .src.md sources. Alternatively, using the touch command on
the previous section’s .src.md file will also force an update of its
navigation links.</p>
<p>If you view 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 file. This allows
the GitHub repository to function not just as a source code host, but as
a readable online version of the entire tutorial.</p>
<h3 id="generating-html-files">Generating HTML Files</h3>
<p>The .src.md files can also be converted into HTML. This process
requires Pandoc. Most Linux distributions include a Pandoc package;
please refer to your distribution’s documentation for installation
instructions.</p>
<p>Type <code>rake html</code> to generate HTML files.</p>
<pre><code>$ rake html</code></pre>
<p>Rake first generates intermediate Pandoc-style Markdown files in the
<code>docs</code> directory. Then, it executes <code>pandoc</code> to
convert them into final HTML files. The width and height of image files
are removed. Links to .src.md files will be converted like this.</p>
<pre><code>[Section 5](sec5.src.md) =&gt; [Section 5](sec5.html)</code></pre>
<p>Image files are copied to the <code>docs/image</code> directory, and
their links are updated accordingly:</p>
<pre><code>[sample.png](../image/sample.png) =&gt; [sample.png](image/sample.png)</code></pre>
<p>Other relative links will be removed.</p>
<p>The top HTML file <code>index.html</code> corresponds to the
<code>README.md</code> file in the <code>gfm</code> directory. If you
want to clean HTML files, type <code>rake clobber</code> or
<code>cleanhtml</code>.</p>
<pre><code>$ rake clobber</code></pre>
<p>Each HTML file includes a standard header
(<code>&lt;head&gt; ... &lt;/head&gt;</code>), generated by Pandoc using
the standalone (-s) option. You can customize the output with your own
template file for pandoc. Rake uses
<code>lib/lib_mk_html_template.rb</code> to create its own template.
This template integrates Bootstrap CSS and JavaScript via the jsDelivr
CDN.</p>
<p>The <code>docs</code> directory contains all the necessary html
files. They are used in the <a
href="https://ToshioCP.github.io/Gtk4-tutorial">GitHub pages</a> of this
repository.</p>
<p>To publish this tutorial on your own website, simply upload the
contents of the <code>docs</code> directory to your web server.</p>
<h3 id="generating-a-pdf-file">Generating a PDF File</h3>
<p>Converting Markdown files into LaTeX source files also requires
Pandoc.</p>
<p>Type <code>rake pdf</code> to generate laTeX files and finally create
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 local
files or directories are removed during conversion because LaTeX does
not support them in the same way. However, external URLs and image
references are preserved. Image dimensions are determined by the values
specified within the curly braces in the source file.</p>
<pre><code>![sample image](../image/sample_image.png){width=10cm height=6cm}</code></pre>
<p>You should specify appropriate dimensions; a good rule of thumb is
roughly 0.015 x (width in pixels) cm. For example, if the width of an
image is 400 pixels, the width in a LaTeX file will be almost 6cm.</p>
<p>The file <code>main.tex</code> serves as the root LaTeX file. It
contains <code>\input</code> commands between the
<code>\begin{document}</code> and <code>\end{document}</code> tags to
include each individual section. It also has <code>\input</code>, which
inserts <code>helper.tex</code> in the preamble. Both
<code>main.tex</code> and <code>helper.tex</code> are generated by the
<code>lib/lib_gen_main_tex.rb</code> script. The script converts a
sample piece of Markdown using <code>pandoc -s</code>, extracts the
resulting LaTeX preamble, and saves 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 the <code>latex</code> directory, type
<code>rake clobber</code> or <code>rake cleanlatex</code></p>
<pre><code>$ rake clobber</code></pre>
<p>This removes all the LaTeX source files and a PDF file.</p>
        </div>
      </div>
    </div>
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/js/bootstrap.bundle.min.js" integrity="sha384-MrcW6ZMFYlzcLA8Nl+NtUVF0sA7MsXsP1UyJoMp4YLEuNSfAP+JcXn/tWtIaxVXM" crossorigin="anonymous"></script>
  </body>
  </html>