Miroirs/Gtk4-tutorial
1
0
Fork 0
mirror of https://github.com/ToshioCP/Gtk4-tutorial.git synced 2025-01-28 19:58:41 +01:00
Code Issues Projects Releases Packages Wiki Activity

Modify Readme_for_developers.md.

Browse source
This commit is contained in:
Toshio Sekiya 2021-04-20 21:36:12 +09:00
parent 74b2be2aef
commit b38840de37
2 changed files with 150 additions and 93 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

241
doc/Readme_for_developers.md
View file

@ -1,39 +1,52 @@
# How to build Gtk4 Tutorial
## Quick start guide
1. You need linux operationg system, ruby, rake, pandoc and latex system.
2. download this repository and uncompress the files.
3. change your current directory to the top directory of the source files.
4. type `rake html` to create html files. The files are generated under `html` directory.
5. type `rake pdf` to create pdf file. The file is generated under `latex` directory.
## Prerequisites
- To clone the repository, git is necessary. Most distribution has its package.
- Linux operationg system.
The programs in the repository has been tested on Ubuntu 20.04.
- Download the files in this repository.
There are two ways to download.
1. Use git.
Type `git clone https://github.com/ToshioCP/Gtk4-tutorial.git` on the command-line.
2. Download a zip file.
Click on the code button (green button) in the top page of this repository.
Then, click "Download ZIP".
- Ruby and rake.
- To generate html and latex files, pandoc is necessary.
- To make pdf, latex system is necessary. Texlive2020 or later version is recommended.
## Clone the repository
type the following command.
$ git clone https://github.com/ToshioCP/Gtk4-tutorial.git
- Pandoc. It is used to generate html and latex files.
- Latex system. Texlive2020 or later version is recommended.
It is used to generate pdf file.
## Github flavored markdown
When you see [gtk4_tutorial github page](https://github.com/ToshioCP/Gtk4-tutorial), you'll find `Readme.md` contents below the list of files.
This file is written in markdown language, of which the file has `.md` suffix.
This file is written in markdown language.
A markdown file has `.md` suffix.
There are several kinds of markdown language.
`Readme.md` uses 'github flavored markdown', which is often shortened as GFM.
Markdown files in the top directory also written in GFM.
If you are not familiar with it, refer the website [github flavor markdown spec](https://github.github.com/gfm/).
Markdown files in the gfm directory also written in GFM.
If you are not familiar with it, refer to the page [github flavor markdown spec](https://github.github.com/gfm/).
## Pandoc's markdown
This tutorial uses another markdown -- pandoc's markdown.
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 generate html and latex files in this tutorial.
This type of markdown is used to convert markdown to html and latex in this tutorial.
## Src.md file
Src.md is similar to markdown but it has a command which isn't included in markdown syntax.
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 at a line begins with "@@@" and ends at a line begins with "@@@".
The command starts with a line that begins with "@@@" and it ends with a line "@@@".
For example,
~~~
@ -42,11 +55,11 @@ tfeapplication.c
@@@
~~~
There are three types of @@@ command.
There are four types of @@@ command.
### @@@include
This type of @@@ command starts with a line begins "@@@include".
This type of @@@ command starts with a line "@@@include".
~~~
@@@include
@ -54,9 +67,9 @@ tfeapplication.c
@@@
~~~
This command replaces itself with the text read from the C source file.
If a function list follows the filename, only the functions in the C source file are read.
If no function list is given, the command can read any text files even it is not C source file.
This command replaces itself with the text read from the C source files surrounded by `@@@include` and `@@@`.
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.
~~~
@@@include
@ -64,15 +77,23 @@ tfeapplication.c main startup
@@@
~~~
The command above is replaced by the contents of `main` and `startup` functions in `tfeapplication.c`.
~~~
@@@include
lib_src2md.rb
@@@
~~~
This command is replaced by the contents of `lib_src2md.rb` which is a ruby script (not C file).
The inserted text is converted to fence code block.
Fence code block begins with `~~~` and ends with `~~~`.
The contents are displayed verbatim.
`~~~` is look like a fence so the block is called "fence code block".
If the target markdown is GFM, then an info string follows the beginning fence.
The following example shows the command includes a C source file "sample.c".
The following example shows that the @@@ command includes a C source file `sample.c`.
$ cat src/sample.c
int
@ -96,16 +117,24 @@ The following example shows the command includes a C source file "sample.c".
~~~
... ...
Info strings are usually language like C, ruby, xml and so on.
Info strings are usually languages like C, ruby, xml and so on.
This string is decided with the filename extension.
- `.c` => C
- `.rb` => ruby
- `.xml` => xml
The supported language is written in line 274 and 275 in `lib/lib_src2md.rb`.
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 @@@include command.
Options:
- "-n": Inserts a line number at the top of each line (default).
- "-N": No line number is inserted.
- `-n`: Inserts a line number at the top of each line (default).
- `-N`: No line number is inserted.
The following shows that line numbers are inserted at the beginning of lines.
$cat src/sample.src.md
... ...
@ -133,13 +162,14 @@ If @@@include command doesn't have -N option, then the generated markdown is:
... ...
}
~~~
The info string `.C` specifies C language.
The info string `.numberLines` 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 "-N" option is given, then the info string is `{.C}` only.
If `-N` option is given, then the info string is `{.C}` only.
If the target markdown is an intermediate file to latex, then an info string follows the beginning fence.
If the target markdown is an intermediate file to latex, then the same info string follows the beginning fence.
~~~{.C .numberLines}
int
@ -169,7 +199,7 @@ But it doesn't analyze the syntax or token of the language, so the kind of empha
### @@@shell
This type of @@@ command starts with a line begins "@@@shell".
This type of @@@ command starts with a line begins with "@@@shell".
~~~
@@@shell
@ -193,14 +223,14 @@ wc Rakefile
This is converted to:
~~~
$ wc Rakefile
164 475 4971 Rakefile
~~~
~~~
$ wc Rakefile
164 475 4971 Rakefile
~~~
### @@@if series
This type of @@@ command starts with a line begins "@@@if", "@@@elif", "@@@else" or "@@@end".
This type of @@@ command starts with a line begins with "@@@if", "@@@elif", "@@@else" or "@@@end".
This command is similar to "#if", "#elif", #else" and "#end" directives in C preprocessor.
For example,
@ -214,16 +244,21 @@ Refer to tfetextview API reference in appendix.
@@@end
~~~
Conditions follow "@@@if" or "@@@elif".
They are "gfm", "html" or "latex" so far.
Other words or expressions may be available in the future version.
`@@@if` and `@@@elif` have conditions.
They are `gfm`, `html` or `latex` so far.
- gfm: builds a GFM file
- html: builds a html file
- latex: builds a latex file or pdf file.
Other type of conditions may be available in the future version.
## Conversion
The @@@ commands are carried out by `src2md.rb`.
In addition, some conversion is made by `src2md.rb`.
The @@@ commands above (@@@include, @@@shell and @@@if series) are carried out by `src2md.rb`.
In addition, some other conversions are made by `src2md.rb`.
- Relative links are changed according to the change of base directory.
- Relative links are changed according to the change of the base directory.
- Size option in image link is removed when the destination is GFM or html.
- Relative link is removed when the destination is latex.
- Lines in fence code block are folded when the destination is latex.
@ -233,29 +268,31 @@ This method converts src.md file into md file.
The script `src2md.rb` just invokes this method.
In the same way, the method is called in the action in `Rakefile`.
The code analyzing @@@if series command in the method is rather complicated.
The code analyzing @@@if series command is rather complicated.
It is based on the state diagram below.
![state diagram](../image/state_diagram.png)
## mktbl.rb script
The script "mktbl.rb" is in `src` directory.
This script makes a table easy to read.
For example, a text file "sample.md" has a table like this:
The fourth @@@ command begins with "@@@table".
The contents of this command is a table of GFM or pandoc's markdown.
The script `mktbl.rb` in `src` directory makes a table easy to read.
For example, a text file `sample.md` has a table like this:
~~~
Price list
Price list
|item |price|
|:---:|:---:|
|mouse| $10 |
| PC |$500 |
~~~
@@@table
|item|price|
|:---:|:---:|
|mouse|$10|
|PC|$500|
@@@
Run the script.
~~~
$ cd src
$ ruby mktbl.rb sample.md
~~~
@ -270,68 +307,69 @@ Price list
| PC |$500 |
~~~
The script makes a backup file "sample.md.bak".
The script makes a backup file `sample.md.bak`.
The task of the script seems easy, but the program is not so simple.
The script "mktbl.rb" uses a library script "lib/lib\_mktbl.rb"
This script is independent from "src2md.rb".
The script `mktbl.rb` uses a library `lib/lib_mktbl.rb`
This script is independent from `src2md.rb`.
## Directory structure
There are six directories under `gtk4_tutorial` directory.
They are `gfm`, `src`, `image`, `html`, `latex` and `lib`.
There are seven directories under `gtk4_tutorial` directory.
They are `gfm`, `src`, `image`, `html`, `latex`, `doc` and `lib`.
Three directories `gfm`, `html` and `latex` are the destination directories for GFM, html and latex files respectively.
It is possible that these three directories don't exist before the conversion.
- src: This directory contains src.md files and C-related source files.
- image: This directory contains image files like png or jpg.
- gfm: This directory is empty at first. A ruby script will convert src.md files to GFM files and store them in this directory.
- html: This directory is empty at first. A ruby script will convert src.md files to html files and store them in this directory.
- latex: This directory is empty at first. A ruby script will convert src.md files to latex files and store them in this directory.
- gfm: `rake` converts src.md files to GFM files and store them in this directory.
- html: This directory is empty at first. `rake html` will convert src.md files to html files and store them in this directory.
- latex: This directory is empty at first. `rake latex` will convert src.md files to latex files and store them in this directory.
`rake pdf` creates pdf file in `latex` directory.
- doc: This directory contains `Readme_for_developers.md` (this file).
- lib: This directory includes ruby library files.
## Src and top directories
## Src directory and the top directory
Src directory contains src.md files and C-related source files.
The top directory, which is gtk\_tutorial directory, contains `Rakefile`, `Readme_for_developers.md` and some other files.
`Readme.md` is generated and located at the top directory by rake.
`Readme.md` has title, abstract, table of contents and links to GFM files,
which rake also generates under `gfm` directory.
$ rake
The top directory, which is gtk\_tutorial directory, contains `Rakefile`, `src2md.rb` and some other files.
When `Readme.md` is generated, it will be located at the top directory.
`Readme.md` has title, abstract, table of contents and links to GFM files under `gfm` directory.
Rakefile describes how to convert src.md files into GFM files.
Rake carries out the conversion according to the instruction written in Rakefile.
Rake carries out the conversion according to the `Rakefile`.
## The name of files in src directory
Each file in src directory is an abstract or section of the whole document.
The name of the abstract file is "abstract.src.md".
The name of the section files are "sec", number of the section and ".src.md" suffix.
Each file in `src` directory is an abstract or section of the whole document.
A `abstract.src.md` 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.
## C source file directory
Src.md files might have @@@ commands and they include C source files.
Such C source files are located in the src directory or its subdirectories.
Most of Src.md files have `@@@include` commands and they include C source files.
Such C source files are located in the subdirectories of `src` directory.
Usually, those C files are compiled and tested.
At that time, some auxiliary files and target file like a.out are generated.
If you locate the C source files under src directory, those temporary files make the directory messy.
Therefore, It is a good idea to make subdirectories under src directory and put each C source file under the corresponding subdirectory.
Those C files have been compiled and tested.
When you compile source files, some auxiliary files and a target file like `a.out` are created.
Or `_build` directory is made when `meson` and `ninja` is used when compiling.
Those files are not tracked by `git` because they are specified in `.gitignore`.
The name of the subdirectories should be independent of section names.
It is because of renumbering, which will be explained in the next subsection.
## Renumbering
Sometimes you want to insert a section.
For example, inserting it between section 4 and section 5.
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 it must change to section 5 and the numbers of following sections also must be added by one.
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.
This renumbering is done by a method `renum` of the class `Sec_files`.
The method and class is written in `lib/lib_sec_file.rb`.
- It changes file names.
- If there are references to sections in src.md files, the section numbers will be automatically renumbered.
@ -339,11 +377,11 @@ This renumbering is done by a method `renum` of the class `Sec_files`.
## Rakefile
Rakefile is a similar file to Makefile but controlled by rake, which is a make-like program written in ruby.
Rakefile has the following tasks.
Rakefile in this tutorial has the following tasks.
- md: generate GFM markdown files. This is the default.
- html: generate html files.
- pdf: generate latex files and a pdf file, which is generated by pdflatex.
- pdf: generate latex files and a pdf file, which is compiled by lualatex.
- latex: generate latex files.
- all: generate md, html, latex and pdf files.
@ -355,21 +393,21 @@ Markdown files (GFM) are generated by rake.
$ rake
This command generates `Readme.md`, which has no original src.md file.
At the same time, it converts each .src.md file into GFM file under `gfm` directory.
When translated, it is added a navigation line at the top and bottom.
This command generates `Readme.md` with `src/abstract.src.md` and titles of src.md files.
At the same time, it converts each src.md file into GFM file under `gfm` directory.
Navigation lines are added at the top and bottom of each markdown section file.
You can describe width and height of images in .src.md files.
You can describe width and height of images in src.md files.
For example,
![sample image](../image/sample_image.png){width=10cm height=6cm}
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 above.
So the size is removed in the conversion.
If a src.md file has relative URL link, it will be changed by conversion.
Because src.md files are located under `src` directory and GFM files are located under `gfm` directory, base URL of GFM files is different from base URL of src.md files.
For example, `[Sample.c](sample.c)` is translated to `[Sample.c](../src/sample.c)`.
For example, `[src/sample.c](sample.c)` is translated to `[src/sample.c](../src/sample.c)`.
If a link points another src.md file, then the target filename will be changed to .md file.
For example, `[Section 5](sec5.src.md)` is translated to `[Section 5](sec5.md)`.
@ -378,9 +416,9 @@ If you want to clean the directory, that means remove all the generated markdown
$ rake clean
If you see the github repository (ToshioCP/Gtk4-tutorial), `Readme.md` is shown below the list of the top directory.
If you see the github repository (ToshioCP/Gtk4-tutorial), `Readme.md` is shown below the code.
And `Readme.md` includes links to each markdown files.
The repository not only stores source files but also shows the tutorial in it.
The repository not only stores source files but also shows the whole tutorial.
## Generate html files
@ -395,7 +433,7 @@ Type `rake html` to generate html files.
First, it generates pandoc's markdown files under `html` directory.
Then, pandoc converts them to html files.
The description of the width and height of image files is removed.
The width and height of image files are removed.
`index.html` is the top html file.
If you want to clean `html` directory, type `rake cleanhtml`
@ -403,8 +441,11 @@ If you want to clean `html` directory, type `rake cleanhtml`
$ rake cleanhtml
Every html file has stylesheet in its header.
This comes from `header` string in `Rakefile`.
You can customize the style by modifying `Rakefile`.
This is created by `lib/lib_add_head_tail_html.rb`.
This script has a sample markdown code and convert it with pandoc and `-s` 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 `lib/lib_add_head_tail_html.rb`.
## Generate latex files and a pdf file
@ -419,15 +460,31 @@ First, it generates pandoc's markdown files under `latex` directory.
Then, pandoc converts them to latex files.
Links to files or directories are removed because latex doesn't support them.
However, links to full URL are kept.
Image size is set with the size between the left brace and right brace.
![sample image](../image/sample_image.png){width=10cm height=6cm}
You need to specify appropriate width and height.
It is almost `0.015 x pixels` cm.
For example, if the width of an image is 400 pixels, the width in a latex file will be almost 6cm.
`main.tex` is the top latex file.
If you want to clean `latex` directory, type `rake cleanlatex`
$ rake cleanlatex
You can customize `main.tex` and `helper.tex`, which describes preamble, by modifying `Rakefile`.
`main.tex` is a root file and it includes each section file between `\begin{document}` and `\end{document}`.
`main.tex` also includes `helper.tex` in its preamble.
`main.tex` and `helper.tex` is created by `lib/lib_gen_main_tex.rb`.
It has a sample markdown code and convert it witn pandoc and `-s` option.
Pandoc generates preamble.
`lib/lib_gen_main_tx.rb` extracts the preamble and put a part of it into `helper.tex`.
You can customize `helper.tex` by modifying `lib/lib_gen_main_tex.rb`.
You can generate pdf file by typing `rake pdf`.
$ rake pdf
This does `rake latex` first.
After that the latex files are compiled by lualatex.

2
lib/lib_src2md.rb
View file

@ -35,7 +35,7 @@ require 'pathname'
# The source code of `tfe3.c` is stored in [src/tfe](../src/tfe) directory.
# (sec7.tex)
# The source code of \texttt{tfe3.c} is stored in \href{../src/tfe}{src/tfe} directory.
# The pdf file generated by pdflatex recognizes that the link 'href{../src/tfe}' points a pdf file '../src/tfe.pdf'.
# The pdf file generated by lualatex recognizes that the link 'href{../src/tfe}' points a pdf file '../src/tfe.pdf'.
# To avoid generating such incorrect links, it is good to remove the links from the original markdown file.
# If the target is full URL, which means absolute URL begins with "http", no problem happens.