Experimenting HTML build with mdbook

idoleat commented 1 month ago

The book is currently available for experimentation on https://idoleat.github.io/concurrency-primer/, with content up to section 6. The rest will be added once styling are converted. mdbook is similar to gitbook. Some changes on styling are:

Unify all \textit , \introcude and \emph as italic text since there's no visual difference in current pdf publication
smart-punctuation is enabled to achieve same affect as ``some words''
mathjax-support is enabled to write math inside \\( \\) (inline) and \\[ \\] (block)
\clang{} and \Cplusplus are expanded to normal C and C++
\textsc are expanded as <small> tag and capital letters, as the sc suggested
Images are all converted to SVGs and embedded using {{#include images/xxx.svg}} instead of ![image](images/xxx.svg) to make characters in SVGs select-able. SVGs now are poorly converted/made and should be remade later.

Some advantages of mdbook are:

cargo install mdbook (or just download the binary) is all you need to setup build environment
Live preview in browser on changes saved with mdbook serve
Easier custom styling via CSS
Fast build time in GitHub action (13s)

Some conserncs are:

pdf rendering backend options: mdbook-pdf and mdbook-pandoc. The first one is hard to deploy in CI. Haven't tried the later yet. The print button on in the upper-right corner can print a pretty raw pdf though.
Maybe figure captions need costum styling

Source code link and "new issue" button are enabled at the upper-right corner.

Another HTML build option is typst but the feature is still on the 2024 roadmap. In typst you can edit like markdown, styling and arranging like CSS (but richer) and scripting like python.

jserv commented 1 month ago

The book is currently available for experimentation on https://idoleat.github.io/concurrency-primer/, with content up to section 6. The rest will be added once styling are converted. mdbook is similar to gitbook.

It looks pretty! How can you deal with code listing such getFoo and its Arm assembly?

idoleat commented 1 month ago

How can you deal with code listing such getFoo and its Arm assembly?

A new chapter is added to demonstrate this: https://idoleat.github.io/concurrency-primer/seq_cst_on_weakly_rodered_hw.html

Wrap content inside a div with flexbox property like this:

<div class="hori_container">

```c
int getFoo()
{
    return foo;
}

\[ \text{ } \xrightarrow{\textit{becomes}} \text{ } \]

getFoo:
  ldr r3, <&foo>
  dmb
  ldr r0, [r3, #0]
  dmb
  bx lr

Notice that the blank line after `<div class="hori_container">` should not be omitted.
The following css classes will then arrange the content horizontally
```css
.hori_container {
    display: flex;
    overflow-x: auto;
    white-space: nowrap;
}

.hori_container > * {
    min-width: 200px;
    margin: 10px;
}

Flexbox is adaptive on different screen aspect ratio so it works well on mobile phone as well.

If writing tags is considered too tedious, we could use custom syntax like

:::horizontal
contents
:::

by writing an mdbook prepocessor to expand that syntax to a div tag.

tigercosmos commented 1 month ago

@idoleat seems that the URL(https://idoleat.github.io/concurrency-primer/seq_cst_on_weakly_rodered_hw.html) is invalid.

idoleat commented 1 month ago

@tigercosmos The site is now online. I reverted GitHub workflow back to the state without pdf ouput.

Pdf release workflow has been separated. It can be downloaded at the release page

idoleat commented 1 month ago

A custom syntax has been added for horizontal container using a preprocessor. Now you can write

:::horizontal
content block A
content block B
content block C
:::

\secref{}s and \fig{}s are now replaced with corresponding links to anchors in HTML, with subtle changes around links (see e9e1615). Links do not work in PDF right now. A PR has been sent to mdBook to fix this. Temporarily, we can use forked mdBook to make links work. See explanation of broken links [1].

[1]: https://github.com/HollowMan6/mdbook-pdf#common-issues

idoleat commented 1 month ago

A syntax is added to run code on Compiler Explorer.

:::CE
{{#include ./examples/order_exmaple.c}}
// or write code here directly
:::

The above code block will be converted to a link like this: ▶ Open in Compiler Explorer

A new page[1] is added to demonstrate this.

Since the link is generated by encoding the code and config as a base64 string and concatenating after API end point, it is limited by the max length of URL. The linked generated from example introduced in #7 exceeds the limit. So eventually the new syntax might not be so useful. If a link to Compiler Explorer is desired, one can just paste code in Compiler Explorer and get a short link back, which is aimed to be valid forever[2], in a few clicks.

[1]: https://idoleat.github.io/concurrency-primer/ce_test.html [2]: https://github.com/compiler-explorer/compiler-explorer/wiki/FAQ

sysprog21 / concurrency-primer

Experimenting HTML build with mdbook #10