WIP: Switch to markdown and fix code blocks

[BuonOmo]

Hi @markburns and thanks for making the book available!

I'm currently going over it to give it a style refresh/fix. This is still a work in progress but I wanted to share already so that if anyone want to discuss my choices it can be done here.

While first reading the repository I also had some troubles guessing which was the correct branch to work on. I've chosen the master and I think it should be made default (and maybe renamed main).

Since I'm reading the book at the same time as I am doing this PR, I may also fix some typos. I'll prefix typo related commits with typo: if there are some for one to be able to review those separately.

If you do not want to maintain the repository anymore, I'd be glad to help as well 🙂. However, I am French and my English is far from perfect (and I don't know anything about Japanese). Hence my focus being on style and minor typos.

Best, Ulysse

---

Fixes #47

---

TODO:

• [x] 22/23 pages.
• [ ] Maybe chose another syntax color (See README.md).
• [ ] Fix changes made to _config.yml, remove useless configuration.
• [ ] Verify pages.
• [ ] Rework specific formatting (tables, footnotes, maybe something else?).
• [ ] Fix figure related css (some are going past the max size).
• [x] Fix max width for h1 (renders badly when multiline).
• [ ] Harmony between captions before code
• [ ] Fix code blocks in figures

---

I had a lot of difficulties while reading this great book, and most where related to code blocks being badly formatted. For instance, the RCLASS(tmp)->iv_tbl would render as RCLASS->iv_tbl.

Rather than fixing textile which really is not the goto language nowadays. I've made another attempt to switch to markdown (seeing that the former wasn't successful).

I've done that using the script below, and allowing myself a few changes:

1. add syntax highlighter (See README.md),
2. wrap images in figure html tags, and show captions below,
3. make a few small cosmetic changes (See styles.css),
4. remove the old textile related plugin,
5. remove differentiation between small and large code blocks.

BEGIN {
    # Set it to 1 and remove the first `!` of any rule to only print that rule.
    DEBUG = 0
    figure_count = 0
    in_code = 0
}

function esc(s) {
    gsub("%", "%%", s)
    return s
}

function print_all_but_first() {
    for (i=2; i<NF; i++) printf esc($i) " "
    printf esc($NF) "\n"
}
function print_header(char) {
    print_all_but_first()
    n = length - length($1) - 1
    while(n--) printf(char)
    printf("\n")
}

!DEBUG && !in_code && /^#/ {
    printf "* "
    print_all_but_first()
    next
}
!DEBUG && !in_code && /^h1\./ { print_header("-"); next }
!DEBUG && !in_code && /^h2\./ { print_header("="); next }
!DEBUG && !in_code && /^h([3-9])\./ {
    n = substr($1, 2, 1)
    while(n--) printf("#")
    printf " "
    print_all_but_first()
    next
}
!DEBUG && !in_code && /^<pre/ {
    in_code = 1
    print "```TODO-lang"
    next
}
!DEBUG && in_code && /^<\/pre/ {
    in_code = 0
    print "```"
    next
}
!DEBUG && !in_code && /^!images\// {
    figure = ++figure_count
    match($0, /images\/[^(]+/)
    path = substr($0, RSTART, RLENGTH)
    match($0, /\([^)]+/)
    alt = substr($0, RSTART + 1, RLENGTH - 1)
    alt = "figure "figure": "alt
    print "<figure>"
    print "\t<img src=\""path"\" alt=\""alt"\">"
    print "\t<figcaption>"alt"</figcaption>"
    print "</figure>"
    next
}
!DEBUG && !in_code && /"[^""]+":[^ ]+/ {
    rv = $0
    i = 10
    while(match(rv, /"[^""]+":[^ ]+/)) {
        if (!i--) exit 1 # inifinte loop somehow in preface.textile, change by hand.

        full_length = RLENGTH
        match(rv, /"[^""]+":[^ ]/)
        text = substr(rv, RSTART + 1, RLENGTH - 4)
        link = substr(rv, RSTART + RLENGTH - 1, full_length - RLENGTH + 1)
        if (match(link, /^[a-z]+\.html$/)) link = substr(link, 0, length(link) - length(".html"))
        sub(/"[^""]+":[^ ]+/, "["text"]("link")TODO-checklink", rv)
    }
    print rv
    next
}
!DEBUG { print } # default (thanks to `next` in every action)

[markburns]

Hey sorry for the incredible delay. I need to tweak my notification settings a little so I don't miss important contributions on the few open source things I maintain.

I'll have a read through now!

[BuonOmo]

@markburns I'm already glad you answered! I think the PR still needs some love, but it is already more readable than the current version (I'm actually reading it on my fork 😅)