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

Bug fixed. Readme_for_developers.md is modified.

Browse source
This commit is contained in:
Toshio Sekiya 2021-01-11 23:32:09 +09:00
parent 568ecd439c
commit 9ecd1797da
7 changed files with 166 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

35
Rakefile
View file

@ -23,6 +23,26 @@ end
CLEAN.append(*mdfilenames)
CLEAN << "Readme.md"
# Abstract
abstract=<<'EOS'
This tutorial illustrates how to write C programs with Gtk4 library.
It focuses on beginners so the contents are limited to basic things such as widgets, GObject, signal, menus and build system.
Please refer [Gnome API reference](https://developer.gnome.org/) for further topics.
This tutorial is under development and unstable.
Even though the examples written in C language have been tested on gtk4 version 4.0,
there might exist bugs.
If you find any bugs, errors or mistakes in the tutorial and C examples,
please let me know.
You can post it to [github issues](https://github.com/ToshioCP/Gtk4-tutorial/issues).
EOS
abstract_html_array = abstract.gsub(/\[([^\]]*)\]\(([^\)]*)\)/,"<a href=\"\\2\">\\1</a>").split("\n\n")
abstract_html_array.map! { |s| s.gsub(/[^\n]\z/,"\n").gsub(/\A/,"<p>\n").gsub(/\z/,"</p>\n") }
abstract_html = abstract_html_array.join
abstract_latex = abstract.gsub(/\[([^\]]*)\]\(([^\)]*)\)/, "\\href{\\2}{\\1}")
# Headers or a tail which is necessary for html files.
header=<<'EOS'
<!doctype html>
@ -71,12 +91,13 @@ file_index =<<'EOS'
<body>
<h1>Gtk4 Tutorial for beginners</h1>
<p>
This tutorial is under development and unstable.
You should be careful because there exists bugs, errors or mistakes.
@@@ abstract
</p>
<ul>
EOS
file_index.gsub!(/@@@ abstract\n/, abstract_html)
# Preamble for latex files.
main = <<'EOS'
@ -87,8 +108,13 @@ main = <<'EOS'
\begin{document}
\maketitle
\tableofcontents
\begin{abstract}
@@@ abstract
\end{abstract}
EOS
main.gsub!(/@@@ abstract\n/, abstract_latex)
helper = <<'EOS'
\usepackage[pdftex]{graphicx}
\usepackage[colorlinks=true,linkcolor=black]{hyperref}
@ -96,17 +122,16 @@ helper = <<'EOS'
\providecommand{\tightlist}{%
\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
EOS
# tasks
task default: :md
task all: [:md, :html, :pdf]
task md: mdfilenames+["Readme.md"]
file "Readme.md" do
buf = [ "# Gtk4 Tutorial for beginners\n", "\n" ]
buf << "This tutorial is under development and unstable.\n"
buf << "You should be careful because there exists bugs, errors or mistakes.\n"
buf << abstract
buf << "\n"
0.upto(srcfiles.size-1) do |i|
h = File.open(srcfiles[i].path) { |file| file.readline }

10
Readme.md
View file

@ -1,7 +1,15 @@
# Gtk4 Tutorial for beginners
This tutorial illustrates how to write C programs with Gtk4 library.
It focuses on beginners so the contents are limited to basic things such as widgets, GObject, signal, menus and build system.
Please refer [Gnome API reference](https://developer.gnome.org/) for further topics.
This tutorial is under development and unstable.
You should be careful because there exists bugs, errors or mistakes.
Even though the examples written in C language have been tested on gtk4 version 4.0,
there might exist bugs.
If you find any bugs, errors or mistakes in the tutorial and C examples,
please let me know.
You can post it to [github issues](https://github.com/ToshioCP/Gtk4-tutorial/issues).
- [Prerequisite and Licence](sec1.md)
- [GtkApplication and GtkApplicationWindow](sec2.md)

103
Readme_for_developers.md
View file

@ -1,16 +1,37 @@
# How to build Gtk4 Tutorial
## Src.md file and .md file (markdown file)
## Prerequisites
This tutorial uses 'github flavored markdown', which is often shortened as GFM.
We will call it `markdown' as a simple form in this document.
- To clone the repository, git is necessary. Most distribution has its package.
- 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
## 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.
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 flavoer markdown spec](https://github.github.com/gfm/).
However, if you want to generate html or latex using pandoc, you need to use the markdown within the syntax common to GFM and pandoc.
## Pandoc's markdown
### Definition
This tutorial 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.
Src.md is similar to markdown but it has two commands which isn't included in markdown.
### Src.md file
Src.md is similar to markdown but it has two commands which isn't included in markdown syntax.
They are @@@ command and $$$ command.
@@@ C\_source\_file \[function_list\]
@ -72,7 +93,7 @@ These two commands have two advantages.
2. You don't need to modify your src.md file, even if the C sourcefile, which is included by @@@ command, is modified.
In the same way, any upgrade of the shell commands described between $$$ commands doesn't affect the src.md file.
There's a method `src2md` in the src2md.rb script.
There's a method `src2md` in the `lib/lib_src2md.rb` script.
This method converts src.md file into md file.
This method is also used in other ruby scripts like Rakefile.
@ -80,6 +101,8 @@ This method is also used in other ruby scripts like Rakefile.
There are five directories under `gtk4_tutorial` directory.
They are `src`, `image`, `html`, `latex` and `lib`.
Two directories `html` and `latex` are the destination directores for html and latex files respectively.
It is possible that these two directory 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.
@ -91,14 +114,15 @@ They are `src`, `image`, `html`, `latex` and `lib`.
Src directory contains src.md files and C-related source files.
The top directory, which is gtk\_tutorial directory, contains md files correspond to src.md files in src directory.
They are generated by scripts like src2md.rb.
However, usually they are generated by Rakefile.
They are generated by rake.
Md files are generated from src.md files, so most of the lines in each md file corresponds to the lines in the original src.md file.
But some lines in md files don't have their original lines and they are newly generated by ruby scripts.
Those are mainly links to other md files.
In addition, readme.md file, which have title, table of contents and abstract, is generated by ruby script
and it doesn't have an original src.md file.
$ rake
Rakefile describes how to convert src.md files into .md files.
Rake carries out the conversion according to the instruction written in Rakefile.
In addition, `Readme.md` file, which has title, abstract and table of contents , is generated.
It doesn't have an original src.md file.
### The name of files in src directory
@ -125,9 +149,9 @@ It is because of renumbering, which will be explained in the next subsection.
Sometimes you want to insert a section.
For example, inserting 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 following sections also must be added by one.
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.
This renumbering is done by a ruby script `renumber.rb`.
This renumbering is done by a method `renum` of the class `Sec_files`.
- It changes file names.
- If there are references to sections in src.md files, the section numbers will be automatically renumbered.
@ -139,14 +163,15 @@ Rakefile has the following tasks.
- md: generate markdown files. This is the default.
- html: generate html files.
- latex: generate latex files and a pdf file, which is generated by latex.
- pdf: generate latex files and a pdf file, which is generated by pdflatex.
- latex: generate latex files.
- all: generate md, html, latex and pdf files.
If renumbering is necessary, rake does it before the tasks above.
Rake does renumbering before the tasks above.
### Generate markdown files
### Generate markdown (GFM) files
Markdown files are generated by rake.
Markdown files (GFM) are generated by rake.
$ rake
@ -154,6 +179,14 @@ All the markdown files are located under the top directory (`gtk4_tutorial` dire
They are translated from src.md files except `Readme.md`, which is newly created.
When translated, it is added a navigation line at the top and bottom.
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 abd right brace is used in latex file and it is not fit to GFM syntax.
So the size is removed in the conversion.
If you want to clean the directory, that means remove all the generated markdown files, type `rake clean`.
$ rake clean
@ -173,7 +206,10 @@ Type `rake html` to generate html files.
$ rake html
The files are located under html directory.
First, it generates pandoc's markdown files under `html` directory.
Then, pandoc converts then to html files.
The description of the width and height of image files is removed.
`index.html` is the top html file.
If you want to clean `html` directory, type `rake cleanhtml`
@ -184,3 +220,28 @@ This comes from `header` string in `Rakefile`.
You can customize the style by modifying `Rakefile`.
### Generate latex files and a pdf file
Src.md files can be translated to latex files.
You need pandoc to do this.
Type `rake latex` to generate latex files.
$ rake latex
First, it generates pandoc's markdown files under `latex` directory.
Then, pandoc converts then to latex files.
Links to files or directories are removed because latex doesn't support them.
However, links to full URL are kept.
`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`.
You can generate pdf file by typing `rake pdf`.
$ rake pdf

31
lib/lib_sec_file.rb
View file

@ -49,12 +49,15 @@ class Sec_file < String
def to_tex
@name.gsub(/\.(src\.md|md|html|tex)$/, ".tex")
end
def num
@name.match(/\d+(\.\d+)?/)[0].to_f
def num # the return value is String
@name.match(/\d+(\.\d+)?/)[0]
end
def to_f
self.num.to_f
end
def <=> other
if other.instance_of?(Sec_file)
self.num <=> other.num
self.to_f <=> other.to_f
else
nil
end
@ -62,7 +65,7 @@ class Sec_file < String
# Note: is_i? indicates the number is integer mathematically. For example, 2.0 is an integer.
# It doesn't mean the class of the number is Integer.
def is_i?
self.num == self.num.floor
self.to_f == self.to_f.floor
end
def renum n
if n.instance_of?(String)
@ -99,10 +102,10 @@ class Sec_files < Array
def renum
self.sort!
tbl = []
n = 1.0
n = 1
self.each do |sec_file|
tbl << [ sec_file.num, n, sec_file.num == n ? true : false ]
n += 1.0
tbl << [ sec_file.num, n, sec_file.to_f == n ? true : false ]
n += 1
end
while any_diff?(tbl)
unless try_renum(tbl)
@ -128,17 +131,25 @@ private
if tbl[i][2] == false
n = tbl[i][1] # number to substitute
found = false
tbl.each do |t|
if t[0] == n
self.each do |sec_file|
if sec_file != self[i] && sec_file.to_f == n
found = true
break
end
end
unless found # OK to replace
self[i].renum n
tbl[i][0] = n.to_f
tbl[i][2] = true
# tbl[0] (old number (String) is kept in the array 'tbl')
changed = true
self.each do |sec_file|
buf = IO.readlines sec_file
buf.each do |line|
line.gsub!(/((S|s)ection *)#{tbl[0]}/, "\\1#{n}")
　　　　　　　　　　　.gsub!(/((S|s)ec *)#{tbl[0]}/, "\\1#{n}")
end
IO.write sec_file buf.join
end
end
end
end

2
lib/lib_src2md.rb
View file

@ -131,7 +131,7 @@ def src2md srcmd, md, width
elsif type == "latex"
line.gsub!(/(^|[^!])\[([^\]]*)\]\((?~http)\)/,"\\1\\2") # remove link
else # type == "markdown" or "html"
line.gsub!(/(!\[[^\]]*\]\([^\)]*\)) *{width *= *\d*(|\.\d*)cm *height *= *\d*(|\.\d*)cm}/,"\\1")
line.gsub!(/(!\[[^\]]*\]\([^\)]*\)) *{width *= *\d*(|\.\d*)cm *height *= *\d*(|\.\d*)cm}/,"\\1") # remove size option from link to image files.
end
md_buf << line
end

4
src/sec7.src.md
View file

@ -97,9 +97,9 @@ Only functions `on_open` are shown as follows.
@@@ tfe/tfe3.c on_open
The source code of `tfe3.c` is stored in [src/tfe](tfe) directory.
The source code of `tfe3.c` is stored in [src/tfe](https://github.com/ToshioCP/Gtk4-tutorial/tree/main/src/tfe) directory.
If you want to see it, click the link above.
In the same way, you can get the source files below in the directory [src/tfe](tfe).
In the same way, you can get the source files below in the directory [src/tfe](https://github.com/ToshioCP/Gtk4-tutorial/tree/main/src/tfe).
### Using ui string

21
src2md.rb Normal file
View file

@ -0,0 +1,21 @@
#!/bin/sh
exec ruby -x "$0" "$@"
#!ruby
# src2md.rb
require_relative 'lib/lib_src2md.rb'
def usage
$stderr.print "Usage: ruby srcd2md.rb src.md_file md_file\n"
end
if ARGV.size != 2
usage
exit 1
end
srcmd = ARGV[0]
md = ARGV[1]
src2md srcmd, md, 80