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 [2021/03/25 08:04] – [Important information] adminen:iot-open:rules [2023/11/21 15:54] (current) – [Comments in the pages] pczekalski
Line 1: Line 1:
-===== General rules for creating the IoT-OPEN.EU DokuWiki document. v.1.=====+====== General rules for creating the DokuWiki-based books. v.1.5 ======
  
- +===== Table of Contents =====
  
-==== Overview ====+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>
  
-The IO1 results will be created in DokuWiki so it’s syntax would be used for document formatting. Here we provide the rules for elements of the documents created. 
  
-===== Chapters and headers =====+==== Exclude a page ====
  
-Place top chapter (header level 1) title in six equation chars:+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.
  
-<code>====== Title ======</code> +Example: 
-Note, first chapter level on the page should correspond with ToC indentation as in case Dokuwiki page is part of the book. +<del>Chapter 3</del> 
- +<code><del> Chapter 3 </del></code>
  
-==== Subchapter ====+More of this is under the [[https://robolabor.ee/homelab/en/iot-open/rules#comments_in_the_pages|" Comments in the pages"]] guidelines.
  
-Subchapters of first level (header level 2) need four equation marks, second level (header level 3) – three and so on:+===== Chapters and headers =====
  
-<code>===== Subchapter =====</code>+Place the top chapter (header level 1) title in six equation chars:
  
-Do not use any font modifiers to the titleWe assume that three levels of subchapters should be enough (four totalincluding top-level chapter).+<code>====== Title ======</code> 
 +Each page should start from the highest chapter levelThe PDF book generator will automatically shift it down by the starting positione.g.:
  
-<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. +1. Introduction (page1) 
-<code> +1.1 Definition of the problem (page2)
-ToC:+
  
-Level 1 (page 1, first chapter no 1) +page1 starts with:\\ 
-Level 1 (page 2, first chapter no 2) +<code>======Introduction======</code>
-- 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)+
  
----------------------------------+page2 starts with:\\ 
 +<code>======Definition of the problem======</code>
  
-Page 1: +<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=.\\ 
-====== Header level 1 (1.) ======+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 ====
  
-Page 2: 
-====== Header level 1 (2.) ====== 
  
-Page 3: 
-===== Header level 2 (2.1.) ===== 
- 
-Page 4: 
-===== Header level 2 (2.2.) ===== 
- 
-Page 5: 
-==== 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> 
 </note> </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>+<note warning>DO NOT INCLUDE CHAPTER NUMBERS in the headers!!!! The sample above is to present the relation between chaptersbut numbers are to be generated automatically!</note>
  
  
 ===== References ===== ===== References =====
  
-References should appear in the text as footnotes. <note warning>This is subject to change in case we employ working plugin for DokuWiki that let us introduce IEEE-style references.</note>+References should appear in the text as footnotes. <note warning>This is subject to change in case we employ working plugin for DokuWiki that lets us introduce IEEE-style references.</note>
  
 <code>((Reference))</code> <code>((Reference))</code>
Line 87: Line 55:
 <caption>IOT-OPEN.EU Logo</caption> <caption>IOT-OPEN.EU Logo</caption>
 </figure> </figure>
-If picture is too small to be seen inline then use link opening it as separate pageotherwise use //nolink//.+If picture is too small to be seen inlinethen use the link to open it as separate pageotherwiseuse //nolink//.
 <code> <code>
 <figure Ref.Pic.1> <figure Ref.Pic.1>
Line 94: Line 62:
 </figure> </figure>
 </code> </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]] sytnax, i.e.:+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}} 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 an unique name, here Ref.Pic.1, right by the HTML tag figure (default is label) then you can refer to is as in regular HTML.+Note - when you insert a new figure, you must give it unique name, here Ref. Pic.1, right by the HTML tag figure (default is label)then you can refer to it as in regular HTML.
  
-<note important>Maximum image width is 470 pixels for A4 portrait printing.+<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 layout 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-wiseto 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, imagesand graphics could be rotated 90 degrees counter-wise to fit into the printing layout.
  
 ===== Tables ===== ===== Tables =====
Line 118: Line 88:
 | 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 refereed in the text the same mechanism as figuresi.e.: “as shown in Table {{ref>Ref.Tab.1.1}}”.
 <code> <code>
 <table Ref.Tab.1.1> <table Ref.Tab.1.1>
Line 135: Line 105:
 ===== Code ===== ===== Code =====
  
-Code examples write within tags+Code examples written within tags
  
 %%<code>...</code>%% %%<code>...</code>%%
Line 173: Line 143:
 </code> </code>
  
-==== Description of programming environment ====+===== Description of programming environment =====
  
-=== Navigating in the menu ===+==== 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// While you write about menu options in software applications – write names of options in italic, i.e. like this one //home/file/open//
Line 186: Line 156:
  
  
-=== Buttons ===+==== Buttons ====
  
 Write names of the buttons in square brackets, in bold. Write names of the buttons in square brackets, in bold.
Line 199: Line 169:
    
  
-=== Variables ===+==== Variables ====
  
-Names of variables referred from the program code write in italic, i.e. //Integer val1//.+Names of variables referred from the program code written in italic, i.e. //Integer val1//.
  
 <code>//variable//</code> <code>//variable//</code>
Line 207: Line 177:
    
  
-==== Citing ====+===== Citing =====
  
 Whole sentences cited write within parenthesis “I love DokuWiki.”, simply by: Whole sentences cited write within parenthesis “I love DokuWiki.”, simply by:
Line 214: Line 184:
 </code> </code>
  
-==== Comments in the pages ====+===== 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. 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.
Line 226: Line 196:
 <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>
en/iot-open/rules.1616659497.txt.gz · Last modified: 2021/03/25 10:00 (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