build details

# Basic Markduck guide

Modified 2019-09-22 by Andrea Censi

The Duckiebooks are written in Markduck, a Markdown dialect.

It supports many features that make it possible to create publication-worthy materials.

## Markdown

Modified 2018-06-02 by Andrea Censi

The Duckiebook are written in a Markdown dialect.

Modified 2020-09-02 by Andrea Censi

You can insert comments using the HTML syntax for comments: any text between “`<!–`” and “`–>`” is ignored.

``````# My section

<!-- this text is ignored -->

Let's start by...
``````

## Variables in command lines and command output

Modified 2018-06-02 by Andrea Censi

Use the syntax “`![name]`” for describing the variables in the code.

For example, to obtain:

``````$ssh robot name.local `````` Use the following: ``````For example, to obtain:$ ssh ![robot name].local``````

Make sure to quote (with 4 spaces) all command lines. Otherwise, the dollar symbol confuses the LaTeX interpreter.

## Character escapes

Modified 2019-10-01 by Rohit Suri

Use the string `&#36;` to write the dollar symbol `\$`, otherwise it gets confused with LaTeX math materials. Also notice that you should probably use “USD” to refer to U.S. dollars.

Other symbols to escape are shown in Table 1.1.

## Keyboard keys

Modified 2018-06-02 by Andrea Censi

Use the `kbd` element for keystrokes.

For example, to obtain:

Press a then Ctrl-C.

use the following:

``````Press <kbd>a</kbd> then <kbd>Ctrl</kbd>-<kbd>C</kbd>.
``````

## Figures

Modified 2018-06-02 by Andrea Censi

To create a figure, use the element `figure`:

``````<figure>
<figcaption>Hello</figcaption>
<img style='width:8em' src="duckietown-logo-transparent.png"/>
</figure>
``````

### More attributes

Modified 2018-06-02 by Andrea Censi

Use `class="caption-left"` to have the caption show up on the left rather than on the bottom:

``````<figure class="caption-left">
<figcaption>Hello</figcaption>
<img style='width:8em' src="duckietown-logo-transparent.png"/>
</figure>
``````

## Subfigures

Modified 2018-06-02 by Andrea Censi

You can create subfigures by nesting `figure` elements:

``````<figure>
<figcaption>Main caption</figcaption>
<figure>
<figcaption>Hello</figcaption>
<img style='width:8em' src="duckietown-logo-transparent.png"/>
</figure>
<figure>
<figcaption>second</figcaption>
<img style='width:8em' src="duckietown-logo-transparent.png"/>
</figure>
</figure>
``````

By default, they are displayed one per block. To make them flow horizontally, add `class="flow-subfigures"` to the external figure:

``````<figure class="flow-subfigures">
<figcaption>Main caption</figcaption>
<figure>
<figcaption>Hello</figcaption>
<img style='width:8em' src="duckietown-logo-transparent.png"/>
</figure>
<figure>
<figcaption>second</figcaption>
<img style='width:8em' src="duckietown-logo-transparent.png"/>
</figure>
</figure>
``````

For any element, adding an attribute called `figure-id` with value `fig:figure ID` or `tab:table ID` will create a figure that wraps the element.

## Shortcut for tables

Modified 2020-09-02 by Andrea Censi

The shortcuts `col2`, `col3`, `col4`, `col5` are expanded in tables with 2, 3, 4 or 5 columns.

The following code:

``````<col2 figure-id="tab:mytable" figure-caption="My table">
<span>A</span>
<span>B</span>
<span>C</span>
<span>D</span>
</col2>
``````

gives the following result:

### `labels-row1` and `labels-row1`

Modified 2018-06-02 by Andrea Censi

Use the classes `labels-row1` and `labels-row1` to make pretty tables like the following.

`labels-row1`: the first row is the headers.

`labels-col1`: the first column is the headers.

Modified 2018-06-02 by Andrea Censi

Modified 2020-09-02 by Andrea Censi

You give IDs to headers using the format:

``````### header title {#topic ID}
``````

For example, for this subsection, we have used:

``````### Establishing names of headers {#establishing}
``````

With this, we have given this header the ID “`establishing`”.

By convention, we use consistently dashes rather than underscores. For example, instead of using the ID `#my_cool_section`, use `#my-cool-section`.

### How to name IDs - and why it’s not automated

Modified 2020-09-02 by Andrea Censi

Some time ago, if there was a section called

``````## My section
``````

then it would be assigned the ID “my-section”.

This behavior has been removed, for several reasons.

One is that if you don’t see the ID then you will be tempted to just change the name:

``````## My better section
``````

and silently the ID will be changed to “my-better-section” and all the previous links will be invalidated.

The current behavior is to generate an ugly link like “autoid-209u31j”.

This will make it clear that you cannot link using the PURL if you don’t assign an ID.

Also, I would like to clarify that all IDs are global (so it’s easy to link stuff, without thinking about namespaces, etc.).

Therefore, please choose descriptive IDs, with at least two IDs.

E.g. if you make a section called

``````## Localization  {#localization}
``````

that’s certainly a no-no, because “localization” is too generic.

``````## Localization {#intro-localization}
``````

Also note that you don’t need to add IDs to everything, only the things that people could link to. (e.g. not subsubsections)

### Linking from the documentation to the documentation

Modified 2020-09-02 by Andrea Censi

You can use the syntax:

``````[](#topic ID)
``````

You can also use some slightly more complex syntax that also allows to link to only the name, only the number or both (Table 1.5).

Modified today by Liam Paull

It is possible to link from one book to another.

The syntax is a slightly extended syntax. Instead of using something like

``````See this [interesting section](#interesting-section).
``````

You need to use add `+other-book-id` before the `#`:

``````See this [interesting section in another book](+other-book-id#interesting-section).
``````

To find out what is the book ID, go to the current index of all the books, which, for `daffy`, is `https://docs.duckietown.org/daffy/`. Go to the book you want to link, and note the URL. The book ID is the part after `daffy`.

For example, this book is published at

``````https://docs.duckietown.org/daffy/duckumentation/out/index.html
``````

The book ID is `duckumentation`.

To link to the entire book, use something like `+BOOKID#book`. (By convention, each book will have the main header assigned the header `#book:book`.)

Here is a list of some of the books as of August 2020:

### (For developers) How to update the list of books that can be crossreferenced.

Modified 2020-09-02 by Andrea Censi

The dictionary between book ID and URL is maintained in the repo `docs-build` in the file `books.crossref.yaml`. When a new book is added, the list needs to be updated and the image `duckietown/docs-build` be updated.