====== General rules for creating the DokuWiki-based books. v.1.5 ======

===== Table of Contents =====

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.
<note important>The ToC does not assign the chapters in the book. That is done on every linked page separately, depending on the header. Info about headers is down below.</note>
<note warning>Do not use capital letters or spaces in the chapter links!</note>


==== Exclude a page ====

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 <code><del> </del></code> tags and it will not show up in the book.

Example:
<del>Chapter 3</del>
<code><del> Chapter 3 </del></code>

More of this is under the [[https://robolabor.ee/homelab/en/iot-open/rules#comments_in_the_pages|" Comments in the pages"]] guidelines.

===== Chapters and headers =====

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

<code>====== Title ======</code>
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:\\
<code>======Introduction======</code>

page2 starts with:\\
<code>======Definition of the problem======</code>

<note warning>Note, in the final document, page1's header will be rendered as HTML's H1, while page2's header will be rendered as H2, thus it is automatically converted from 6x= to 5x=.\\
This is particularly important when using <code>===</code> headers because depending on the chapter nesting, they can be decreased down to either <code>==</code> or even <code>=</code> that does not represent legit header!</note>
==== Subchapter ====


</note>
<note warning>DO NOT INCLUDE CHAPTER NUMBERS in the headers!!!! The sample above is to present the relation between chapters, but numbers are to be generated automatically!</note>


===== References =====

References should appear in the text as footnotes. <note warning>This is subject to change in case we employ a working plugin for DokuWiki that lets us introduce IEEE-style references.</note>

<code>((Reference))</code>

===== Figures =====
Figures with their captions should be placed using the [[http://www.till-biskup.de/de/software/dokuwiki/caption|Caption plug-in]], i.e.: 
<figure RefPic1>
{{:en:iot:logotyp_1a_.png?nolink&200 | This is IOT-OPEN.EU logo}}
<caption>IOT-OPEN.EU Logo</caption>
</figure>
If a picture is too small to be seen inline, then use the link to open it as a separate page; otherwise, use //nolink//.
<code>
<figure Ref.Pic.1>
{{ :logotyp_1_-_fb_-_square.png?nolink&200 | This is IOT-OPEN.EU logo}}
<caption>IOT-OPEN.EU Logo</caption>
</figure>
</code>
Internal references to figures should be done with the figure number using [[http://www.till-biskup.de/de/software/dokuwiki/caption|Caption plug-in]] syntax, i.e.:
As shown on Figure {{ref>RefPic1}}
<code>
Figure {{ref>Ref.Pic.1|Alternate text for Figure 1}}
</code>
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.

<note important>Due to the WCAG compatibility, add a copy of the Figure's caption as its alternative text: <code>{{ref>Ref.Pic.1|Alternate text for Figure 1}}</code></note>

<note important>Maximum image width is 470 pixels for A4 portrait printing. 
<code>
{{:en:iot-open:remotelab:sut:iotrx.jpg?470|Alternate text}}
</code>
</note>

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 counter-wise to fit into the printing layout.

===== Tables =====

Tables with their captions should be placed using the [[http://www.till-biskup.de/de/software/dokuwiki/caption|Caption plug-in]]: 
<table Ref.Tab.1.1>
<caption>caption</caption>
^ Header 1 ^ Header 2 ^
| cell 1 | cell 2|
| cell span ||
</table>
and refereed in the text the same mechanism as figures, i.e.: “as shown in Table {{ref>Ref.Tab.1.1}}”.
<code>
<table Ref.Tab.1.1>
<caption>caption</caption>
^ Header 1 ^ Header 2 ^
| cell 1 | cell 2|
| cell span ||
</table>
</code>
===== Equations =====

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

 

===== Code =====

Code examples written within tags

%%<code>...</code>%%

<file>

<code c>

Code example here

</code>

</file>

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

<code>’’printf(“something”);’’</code>

 

===== Important information =====

Tips, warnings, tricks and important facts should be introduced using [[https://www.dokuwiki.org/plugin:note|note plugin]], classified as: 

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

as below:

<code>
<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>
</code>

===== Description of programming environment =====

==== Navigating in the menu ====

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

 

<code>//home/file/open//</code>


==== Buttons ====

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

**[open]**

<code>
**[open]**
</code>

 

==== Variables ====

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

<code>//variable//</code>

 

===== Citing =====

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

===== Comments in the pages =====

When you need some text to be hidden for the audience but let it exist there, use [[https://www.dokuwiki.org/plugin:comment|comment plugin]], similar to the source code comments.
Simply put the text of the comment between slash-asterisk and asterisk-slash combination:
<code>
This is an example of the sentence whereas /*this text*/ is hidden
</code>
This is an example of the sentence whereas /*this text*/ is hidden

If you need to exclude some section from PDF printed book file, use 
<code><hidden>excluded section</hidden></code>

If some chapters need to be excluded use the del tag
<code><del>  </del></code>

===== Parts to exclude from the PDF generator =====
To exclude part of the content (i.e. link lists by the end of the chapter)
wrap a source code using the WRAP tags:
<code>
<WRAP excludefrompdf>

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

</WRAP>
</code>

<note important>You must explicitly use the name **excludefrompdf** identifier, otherwise it won't work.</note>