Hello !
Trace: • Programmeerimine • IOT-OPEN.EU - The Blue Book - Introduction to IoT • Projekt 5 Alalisvoolumootor ja selle kiirus • Exercises • Data storage • Components of IoT Network Architectures • Harjutusülesanded • General rules for creating the DokuWiki-based books. v.1.7 • Robootika praktilised näited • Distributed sensor network

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
en:iot-open:rules [2023/08/29 07:20] – [Figures] pczekalskien:iot-open:rules [2025/10/30 07:53] (current) – raivo.sell
Line 1: Line 1:
-====== General rules for creating the DokuWiki based books. v.1.4 ======+====== General rules for creating the DokuWiki-based books. v.1.7 ======
  
 ===== Table of Contents ===== ===== Table of Contents =====
  
-The table of contents page for a book has all the linked pages that the book will use for its materials. If a page is not linked in there it will not appear in the book. +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 what header it is given. Info about headers is down below.</note>+<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 ==== ==== 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.+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: Example:
Line 14: Line 16:
 <code><del> Chapter 3 </del></code> <code><del> Chapter 3 </del></code>
  
-More of this under the [[https://robolabor.ee/homelab/en/iot-open/rules#comments_in_the_pages|" Comments in the pages"]] guidelines.+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 ===== ===== Chapters and headers =====
  
-Place top chapter (header level 1) title in six equation chars:+Place the top chapter (header level 1) title in six equation chars:
  
 <code>====== Title ======</code> <code>====== Title ======</code>
-Note, the first chapter level on the page should correspond with ToC indentation as in case the Dokuwiki page is part of the book. +Each page should start from the highest chapter level. The PDF book generator will automatically shift it down by the starting position, e.g.:
- +
  
-==== Subchapter ====+1. Introduction (page1) 
 +1.1 Definition of the problem (page2)
  
-Subchapters of first level (header level 2) need four equation marks, second level (header level 3) – three and so on:+page1 starts with:\\ 
 +<code>======Introduction======</code>
  
-<code>===== Subchapter =====</code>+page2 starts with:\\ 
 +<code>======Definition of the problem======</code>
  
-Do not use any font modifiers to the title. We assume that three levels of subchapters should be enough (four total, including top-level chapters).+<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 important>Level of the first chapter is determined by the ToC level if the page is supposed to be a part of the book in the feature, i.e. 
-<code> 
-ToC: 
  
-Level 1 (page 1, first chapter no 1) +<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>
-Level 1 (page 2, first chapter no 2) +
-- Level 2 (page 3, first chapter no 2.1) +
-- Level 2 (page 4, first chapter no 2.2) +
-- - Level 3 (page 5, first chapter no 2.2.1) +
-- Level 2 (page 6, first chapter no 2.3) +
-- - Level 3 (page 7, first chapter no 2.3.1) +
-- - Level 3 (page 8, first chapter no 2.3.2) +
-- - Level 3 (page 9, first chapter no 2.3.3) +
-Level 1 (page 10, first chapter no 3)+
  
---------------------------------- 
  
-Page 1: +===== References ===== 
-====== Header level 1 (1.) ======+References should appear in the text as pointers e.g. <code>[(AuthorsYear)]</code> The full record of this reference must be in the separate References page, e.g. [[en:safeav:references|]]. Make sure that all pointers are correctly listed in the Reference page.
  
-Page 2: +<note>You can see the references only in Edit mode. In standard View mode, the Reference page looks empty. This is normal behaviour</note>
-====== Header level 1 (2.) ======+
  
-Page 3: 
-===== Header level 2 (2.1.) ===== 
  
-Page 4: +If using the **RefNotes plugin** for structured or bibliographical references (e.g., Harvard or IEEE-style), make sure to disable the automatic backlink numbers that appear in the reference list.   
-===== Header level 2 (2.2.) =====+Otherwise, the same citation may appear with duplicated numbers such as `[2], [2]`.
  
-Page 5: +To make each reference appear only once in the footer (as in proper academic formatting), add the following to the **end of your page**:
-==== Header level 3 (2.2.1.) ==== +
- +
-Page 6: +
-===== Header level 2 (2.3.) ===== +
- +
-Page 7: +
-==== Header level 3 (2.3.1.) ==== +
- +
-Page 8: +
-==== Header level 3 (2.3.2.) ==== +
- +
-Page 9: +
-==== Header level 3 (2.3.3.) ==== +
- +
-Page 10: +
-====== Header level 1 (3.) ======+
  
 +<code>
 +<refnotes>
 +back-ref-format : none
 +</refnotes>
 </code> </code>
-</note> 
-<note warning>DO NOT INCLUDE CHAPTER NUMBERS in the headers!!!! The sample above is to present 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 let us introduce IEEE-style references.</note> 
- 
-<code>((Reference))</code> 
  
 ===== Figures ===== ===== Figures =====
Line 106: Line 75:
 As shown on Figure {{ref>RefPic1}} As shown on Figure {{ref>RefPic1}}
 <code> <code>
-Figure {{ref>Ref.Pic.1}}+Figure {{ref>Ref.Pic.1|Alternate text for Figure 1}}
 </code> </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 - 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>Maximum image width is 470 pixels for A4 portrait printing. The maximum width can be increased.+<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> <code>
-{{:en:iot-open:remotelab:sut:iotrx.jpg?470|}}+{{:en:iot-open:remotelab:sut:iotrx.jpg?470|Alternate text}}
 </code> </code>
 </note> </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.+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. 
 + 
 +<note important>Due to the requirement of the accessibility of the contents, it is necessary to provide **Alternative text** for all figures.</note>
  
 +A video presenting work with figures, tables and references is here:
 +{{ youtube>88N9eoKgakw?large }}
 ===== Tables ===== ===== Tables =====
  
Line 127: Line 102:
 | cell span || | cell span ||
 </table> </table>
-and refereed in text same mechanism as figures i.e.: “as shown in Table {{ref>Ref.Tab.1.1}}”.+and referred in the text to the same mechanism as figures, i.e.: “as shown in Table {{ref>Ref. Tab . 1.1}}”.
 <code> <code>
 <table Ref.Tab.1.1> <table Ref.Tab.1.1>
Line 136: Line 111:
 </table> </table>
 </code> </code>
 +
 +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.
 ===== Equations ===== ===== Equations =====
  
Line 144: Line 121:
 ===== Code ===== ===== Code =====
  
-Code examples write within tags+Code examples written within tags
  
 %%<code>...</code>%% %%<code>...</code>%%
Line 235: Line 212:
 <code><hidden>excluded section</hidden></code> <code><hidden>excluded section</hidden></code>
  
-If some chapters needs to be exclude use del tag+If some chapters need to be excluded use the del tag
 <code><del>  </del></code> <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>
 +
 +===== Common language settings ======
 +Please use UK English, not US English; thus, e.g. use UK's "license", not US's "licence", etc.
 +
 +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".
 +
 +===== Book printing to PDF remarks =====
 +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.
 +
 +<note tip>Dokuwiki server struggles with a caching issue: if you generate PDFs in a row, when downloading the PDF book, you may get an older copy instead of the recently generated one. Open the PDF book in the private tab of your browser (it does not use session cache, thus always downloads full content from the Dokuwiki server). Simply right-click the **Current version of PDF Book** and select **Open in new private tab** (or similar, browser dependent).</note>
 +===== Useful tools =====
 +
 +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:
 +<code>?do=export_pdf</code>
 +
en/iot-open/rules.1693293605.txt.gz · Last modified: 2023/08/29 04:20 (external edit)
CC Attribution-Share Alike 4.0 International
www.chimeric.de Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0