Gtk4-tutorial/Readme_for_developers.md

# How to build Gtk4 Tutorial

## Src.md file and .md file (markdown file)

This tutorial uses 'github flavored markdown', which is often shortened as GFM.
We will call it `markdown' as a simple form in this document.
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.

### Definition

Src.md is similar to markdown but it has two commands which isn't included in markdown.
They are @@@ command and $$$ command.

    @@@ C\_source\_file \[function_list\]

This command includes the C source file, but if a function list is given, only the functions in the C source file are included.

    $$$
    shell command
    ... ...
    $$$

This command executes the shell command and substitutes the strings in the standard output for the lines between $$$ inclusive.

These two commands are carried out by scripts like src2md.rb, which is described in the next subsection.

### Conversion

A ruby script src2md converts src.md file to md file.

    ruby src2md.rb src.md_file md_file

This script recognizes and carrys out the commands described in the previous subsection.
For example, it is assumed that there are two files sample.src.md and sample.c.
Their contents are as follows.

    $ cat sample.src.md
    The following is the contents of the file 'sample.c'.

    @@@ sample.c

    $ cat sample.c
    #include <stdio.h>

    int
    main(int argc, char **argv) {
        printf("Hello world.\n");
    }

Now, convert sample.src.md to a markdown file sample.md with src2md.rb.

    $ ruby src2md.rb sample.src.md sample.md
    $ cat sample.md
    The following is the contents of the file 'sample.c'.

    #include <stdio.h>

    int
    main(int argc, char **argv) {
        printf("Hello world.\n");
    }

Compare sample.src.md and sample.md.
The contents of sample.c is substituted for the line `@@@ sample.c`.

These two commands have two advantages.

1. Less typing.
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.
This method converts src.md file into md file.
This method is also used in other ruby scripts like Rakefile.

## Directory structure

There are four directories under `gtk4_tutorial` directory.
They are `src`, `image`, `html` and `latex`.

-src: This directory contains src.md files.
-image: This directory contains image files like png or jpg.
-html: This directory is empty at first. A ruby script will convert md files to html files and store them in this directory.
-latex: This directory is empty at first. A ruby script will convert md files to latexl files and store them in this directory.
-lib: This directory includes ruby library files.
 
### Src and top directories

Src directory contains src.md 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.

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.

### The name of files in src directory

Each file in src directory is a section of the whole document.
The name of the files are "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.

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.

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

This renumbering is done by a ruby script `renumber.rb`.

- It changes file names.
- If there are references to sections in src.md files, the section numbers will be automatically renumbered.

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

- 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.
- all: generate md, html, latex and pdf files.

If renumbering is necessary, rake does it before the tasks above.

### Generate markdown files
#### Readme.nd file
#### Section files
#### Cross reference
### Generate html files
### Generate latex files and a pdf file