docs - main - evo/Gtk4-tutorial

<!DOCTYPE html>

<head>

<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>

<span class="navbar-brand">Gtk4 tutorial</span>

</button>

</li>

</ul>

</div>

</nav>

<h1 id="how-to-build-the-gtk4-tutorial">How to Build the Gtk4

Tutorial</h1>

<h2 id="quick-start-guide">Quick Start Guide</h2>

<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:

<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>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>

<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>

</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>

<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>

<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

<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>

<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>

<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>

<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) => [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) => [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><head> ... </head></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>

<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

<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>

</body>

</html>