Rules for book development

For SafeAV, PDF validation and layout optimisation are deferred until the final formatting stage, after all chapters have been reviewed and the planned image updates have been completed. The PDF checks described below do not form part of routine SafeAV content or illustration editing; continue wiki syntax, reference and accessibility checks during that work. See the SafeAV review workflow.

A book's table of contents page has all the linked pages it will use for its materials. If a page is not linked in there, it will not appear in the book.

To exclude a page in the book, simply remove it from the ToC, or if you want to keep it in the ToC, then put the page between

<del> </del>

tags and it will not show up in the book.

Example: Chapter 3

<del> Chapter 3 </del>

More of this is under the " Comments in the pages" guidelines.

Place the top chapter (header level 1) title in six equation chars:

====== Title ======

Each page should start from the highest chapter level. The PDF book generator will automatically shift it down by the starting position, e.g.:

1. Introduction (page1) 1.1 Definition of the problem (page2)

page1 starts with:

======Introduction======

page2 starts with:

======Definition of the problem======

===

==

=

Use the RefNotes plugin for bibliographic references. A citation in the text points to a named source record. Keep the full records at the end of each content page that uses them. The book generator combines the source pages into one TXT document, and RefNotes produces one bibliography in the final References chapter.

This is the tested configuration used by the SafeAV handbook. Its References page contains the bibliography output settings; the active source records are stored on the individual content pages.

Use a stable key instead of a manually assigned number. Put the citation before the sentence's final punctuation. At the end of the same page, add the full record in a separate paragraph:

Planning and control form a connected part of the autonomy stack [(SafeAVPaden2016)].

[(SafeAVPaden2016>>
title: Paden, B., Čáp, M., Yong, S. Z., Yershov, D., and Frazzoli, E. (2016). A Survey of Motion Planning and Control Techniques for Self-Driving Urban Vehicles. IEEE Transactions on Intelligent Vehicles, 1(1), 33–55. [[https://doi.org/10.1109/TIV.2016.2578706|doi:10.1109/TIV.2016.2578706]]
)]

The record must stand on its own, separated from surrounding text by blank lines. Do not put a bullet, label or other text in the same paragraph as the definition. RefNotes treats this separate paragraph as a source definition, rather than an additional citation in the text. Do not wrap an active definition in a code block or a comment; the code blocks here are examples to copy.

The displayed number is generated automatically. It may change when earlier citations are added to the book; the source key must remain unchanged.

Write a separate citation marker for each source, directly next to the others:

Planning methods must account for vehicle motion and decisions [(SafeAVPaden2016)][(SafeAVSchwarting2018)].

With the book configuration below, this is displayed as a single group, for example [1,2]. The numbers depend on the order of first citation in the complete book. Three or more sources work the same way: add another complete marker. The source order follows the order of the markers; do not assume that the plugin sorts the group numerically.

Keep a full definition for every key used on the page. In addition to the Paden record above, this example needs:

[(SafeAVSchwarting2018>>
title: Schwarting, W., Alonso-Mora, J., and Rus, D. (2018). Planning and Decision-Making for Autonomous Vehicles. Annual Review of Control, Robotics, and Autonomous Systems, 1, 187–210. [[https://doi.org/10.1146/annurev-control-060117-105157|doi:10.1146/annurev-control-060117-105157]]
)]

[(SafeAVPaden2016, SafeAVSchwarting2018)]
[(SafeAVPaden2016), (SafeAVSchwarting2018)]

Reuse the same key for every citation of the same source:

A first statement [(SafeAVPaden2016)].

A later statement refers to the same source [(SafeAVPaden2016)].

On another content page, use the same marker and copy the identical full source definition to that page's end. When the pages are combined, the source keeps the same number and appears only once in the bibliography. A page's local numbering may differ from its numbering in the complete book.

• Check existing source keys before creating a new one. The same work under two different keys will produce two entries.
• Use letters and digits for keys, with an optional underscore. For new SafeAV keys, use a recognisable prefix and author/year, such as SafeAVPaden2016. Keep existing shared keys unchanged.
• Use a suffix when the same author has different works in the same year, for example SafeAVSmith2024a and SafeAVSmith2024b.
• Preserve the exact key spelling and capitalisation on every page.
• If a source record needs correction, update every copy consistently. Do not rely on the plugin to reconcile conflicting definitions.

A bibliographic source can also be cited in a caption. It uses the same source key and the same full record at the end of the page:

<caption>Overview of motion-planning methods, adapted from [(SafeAVPaden2016)].</caption>

Use wording such as “adapted from” only when it accurately describes the figure's origin. A bibliographic citation is separate from the figure's own identifier and cross-reference.

For SafeAV, integrate supporting readings into the relevant discussion instead of adding a separate further-reading line. For other standalone materials where such a recommendation is appropriate, use an explicit citation instead of a manually numbered local bibliography:

Further reading: [(SafeAVPaden2016)][(SafeAVSchwarting2018)].

In this configuration, the title field holds the complete, consistently formatted bibliographic record. Include authors or organisation, year, title, publication, and volume/pages or report number where applicable. For standards, identify the edition and relevant part. For web sources, include a descriptive title, the publisher or organisation, the URL and an access date where appropriate. Do not invent missing publication details.

Use explicit DokuWiki links inside source records. A bare URL in a structured field can be misinterpreted as formatting, and Markdown links are not the correct syntax here.

[[https://doi.org/10.1109/TIV.2016.2578706|doi:10.1109/TIV.2016.2578706]]
[[https://proceedings.mlr.press/v78/dosovitskiy17a.html|Publisher record]]

Prefer a DOI or stable publisher URL. Remove tracking parameters only when doing so preserves the intended destination.

The final References page must be included last in the book's table of contents. Place the following there once, after the heading:

====== References ======

<refnotes>
refnote-id : 1
reference-base : text
reference-format : []
reference-group : ,
multi-ref-id : note
note-id-base : text
note-id-format : []
back-ref-format : none
notes-separator : none
</refnotes>

These settings produce numeric citations in square brackets, group adjacent citations, and use the source's number for repeated citations. The back-ref-format setting hides return links from the bibliography to the citation locations; it does not merge duplicate source records. Deduplication depends on reusing the same key in the same reference scope.

The examples above use the default RefNotes namespace, matching the current SafeAV book. SafeAV is a key prefix, not a separate namespace. Do not introduce a namespace such as :safeav: into selected citations without coordinating the book configuration: separate namespaces can produce separate lists and numbering sequences.

A page with local source definitions can resolve its citations independently. The wiki's default RefNotes namespace displays bibliographic citations inline in square brackets, for example [2], using the same source number for repeated citations. This matches the book's citation format. Explicit page or namespace settings can override these defaults; grouping and bibliography layout may still differ. Native footnotes remain a separate numbering sequence and are shown as superscript numbers followed by a closing parenthesis in the SafeAV PDF.

For a standalone document that will not be concatenated into a book, add its own References heading and the output block from the previous example at its end. This gives the standalone document the same numeric style. Do not copy that local output block into a book content page.

Use native DokuWiki footnotes for notes that should remain associated with the text, rather than become bibliographic records:

The experiment used a restricted operating area ((The area was closed to public traffic during the test.)).

Write the note at its call location in the source page. Do not add it to the References page and do not give it a bibliographic source key.

For the SafeAV handbook PDF, the generator places these native footnotes at the bottom of the PDF page containing their call, using a separate superscript numbering sequence. A repeated note on another page receives a local footnote there. Bibliographic references remain in square brackets and their records remain at the end of the book.

The main book generator relocates native footnote content to each call before PDF layout, including repeated calls that DokuWiki combines into one note. The shared print stylesheet places the note at the bottom of the page and keeps its call line with it; pagination may move that line to the next page when necessary. Keep using normal native footnote syntax in chapter pages: do not manually duplicate endnote lists or replace notes with bibliography entries to work around PDF placement. In the normal web view, DokuWiki displays native footnotes at the end of the individual wiki page.

Keep native footnotes concise. Standards, official documents, and websites may use a short linked identifier or title; articles and longer bibliographic or licence records normally belong in the bibliography. Do not add adjacent bibliography and footnote calls merely to repeat the same source information.

In the SafeAV PDF, native footnote calls and note markers use superscript numbers followed by a closing parenthesis, such as 1). They have a separate continuous numbering sequence from bibliography citations [n]; numbering is not restarted on each page. Repeated notes receive an entry at each call site, including calls that DokuWiki merges in its web output. The note text uses 7 pt type with compact line spacing (1.1) and a thin 50% gray separator (#808080) above the page's footnote area. Footnote numbers start at the separator's left edge, inside the text area rather than hanging into the margin; the lower page-footer rule remains unchanged.

During the final SafeAV formatting stage, check the generated PDF after relevant layout changes, including repeated notes: every call must resolve and its note must appear on the same page. If there is insufficient space, the call line and its note may move together to the next page. Do not change correct wiki source into a manual endnote list to compensate for a generator defect.

Keep bulleted lists close to the main text edge while placing the bullet itself slightly inside that edge. Item text follows the marker, and wrapped lines align with the item text. Avoid both a wide empty left gutter and bullets hanging outside the paragraph margin. Preserve a visible additional indent for nested lists.

The accepted SafeAV print settings on 2026-09-30 are margin-left: 2mm and padding-left: 1.1em on content unordered lists, with no additional left padding on their .li text wrapper. The 2 mm value is the list-box margin, not the exact position of the bullet glyph. These settings do not redefine numbered lists or the table of contents. Use native wiki list syntax and control print indentation through the stylesheet, not inserted spaces or manual line breaks.

Figures with their captions should be placed using the Caption plug-in, i.e.:

If a picture is too small to be seen inline, then use the link to open it as a separate page; otherwise, use nolink.

<figure Ref.Pic.1>
{{ :logotyp_1_-_fb_-_square.png?nolink&200 | This is IOT-OPEN.EU logo}}
<caption>IOT-OPEN.EU Logo</caption>
</figure>

Internal references to figures should be done with the figure number using Caption plug-in syntax, i.e.: As shown on Figure 1

Figure {{ref>Ref.Pic.1}}

Note - when you insert a new figure, you must give it a unique name, here Ref. Pic.1, right by the HTML tag figure (default is a label), then you can refer to it as in regular HTML.

{{ref>Ref.Pic.1}}

{{:path:to:image.png?470|Description of the image}}

{{:en:iot-open:remotelab:sut:iotrx.jpg?470|Alternate text}}

Because we intend to use portrait rather than landscape layouts in printed books, please consider preparing diagrams as landscape ones rather than portrait. Eventually, portrait diagrams, images, and graphics could be rotated 90 degrees counterclockwise to fit into the printing layout.

A video presenting work with figures, tables and references is here:

The active SafeAV PDF stylesheet is src/styles.safeav-book.css in Book Creator. It sets ordinary wiki media images to width: 100%; max-width: 100%; height: auto. To make one numbered figure narrower, add a rule for its existing stable identifier, for example:

figure[id="Ref.Example"] img.media { width: 65%; }

Use the actual image class (media, medialeft, mediaright or mediacenter) and the actual figure identifier. This is a print-only adjustment; keep the caption, reference and source image unchanged. An uncaptioned opening image can instead be targeted by its unique media filename in the stylesheet. Do not use a general img width rule to enlarge interface icons or decorative marks.

For SafeAV, ordinary images use the full available text width in the final PDF by default, within the page margins and with their original proportions. The SafeAV print stylesheet overrides wiki pixel-width attributes for media images. During final formatting, reduce individual figures only when their full-width presentation is too large; use a figure-specific CSS rule rather than restoring a global pixel cap. Remove unnecessary internal whitespace and prefer low, compact layouts when the same relationships can be preserved. A tall pyramid may become horizontal tiers, and a cycle may become a single row with a return arrow. Preserve the meaning, labels, arrow directions, figure identifier, caption, and source relationships; update alternative text when the layout changes.

During the final SafeAV formatting stage, check the figure, caption, and following explanatory paragraph together in the actual book PDF. Avoid pushing a short continuation onto another page solely because of excess figure height. Meet any agreed page budget through layout improvements without making labels unreadable or deleting substantive text. The uncaptioned chapter-opening illustration remains a separate exception under the SafeAV introduction rules.

Tables with their captions should be placed using the Caption plug-in:

and referred in the text to the same mechanism as figures, i.e.: “as shown in Table ##REF:Ref. Tab . 1.1##”.

<table Ref.Tab.1.1>
<caption>caption</caption>
^ Header 1 ^ Header 2 ^
| cell 1 | cell 2|
| cell span ||
</table>

Our Dokuwiki has installed the table editor plugin, so once you create and save the page with a table, you can edit it in a simpler way using the GUI editor.

Mathematical equations should be inserted as figures and referenced as figures.

Code examples written within tags

<code>...</code>

<code c>

Code example here

</code>

Part of the code placed in the text like_this_function(var arg) should be written as monospace text within double apostrophes

’’printf(“something”);’’

Tips, warnings, tricks and important facts should be introduced using note plugin, classified as:

as below:

<note>regular note on something</note> 
<note warning>warning information</note> 
<note tip>some useful tip for reades</note>  
<note important>and some important information</note>

While you write about menu options in software applications – write names of options in italic, i.e. like this one home/file/open

Option and suboption chains write with “/” (slash) character

//home/file/open//

Write names of the buttons in square brackets, in bold.

[open]

**[open]**

Names of variables referred from the program code written in italic, i.e. Integer val1.

//variable//

Whole sentences cited write within parenthesis “I love DokuWiki.”, simply by:

“I love DokuWiki.”

When you need some text to be hidden for the audience but let it exist there, use comment plugin, similar to the source code comments. Simply put the text of the comment between slash-asterisk and asterisk-slash combination:

This is an example of the sentence whereas /*this text*/ is hidden

This is an example of the sentence whereas is hidden

If you need to exclude some section from PDF printed book file, use

<hidden>excluded section</hidden>

If some chapters need to be excluded use the del tag

<del>  </del>

To exclude part of the content (i.e. link lists by the end of the chapter) wrap a source code using the WRAP tags:

<WRAP excludefrompdf>

Some content is to be present in the Dokuwiki but not to be printed in PDF.

</WRAP>

Use British English. For example, use “licence” as a noun and “license” as a verb.

Use depersonated form, e.g. “in this chapter, details of drone security systems are presented” rather than “in this chapter, you can read about drone security”.

On top of the ToC, there is a link for the PDF version of the contents and another to generate a new one. The book is not generated automatically, so if you change anything and then wish to see the PDF version, click the Generate new PDF book! link and wait till it is finished.

If you want to print just one page as proper PDF, you can use a DW2PDF plugin. Just add in the end of page URL a command:

?do=export_pdf