Changes between Version 10 and Version 11 of User Guide/Wiki Style Guide
- Timestamp:
- May 11, 2020, 6:05:52 PM (4 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
User Guide/Wiki Style Guide
v10 v11 3 3 4 4 == Contributing to the Wiki 5 6 5 For consistent wiki formatting, please adhere to the following style guidelines. 6 [[PageOutline(3-6,,inline,unnumbered)]] 7 7 8 8 === General Guidelines … … 22 22 * On a console: make sure the prompt starts with {{{user@console:path$}}} 23 23 * On a compute machine: make sure the prompt starts with {{{root@console:path$}}} 24 25 24 26 25 === Page Specific Formatting 27 26 28 27 ==== Section Pages 29 Pages that are introductory to larger sections that contain many sub pages (eg. the main [wiki:TestbedInformation Testbed Information] page orthe [wiki:tutorials Tutorials] page) should use the following as a starting point:28 Pages that are introductory to larger sections that contain many sub-pages (e.g. the [wiki:tutorials Tutorials] page) should use the following as a starting point: 30 29 31 30 {{{ 32 [[ TOC(SectionPageName/SubsectionPageName/*, depth=1, noheading)]]31 [[Include(WikiToC)]] 33 32 34 33 = Section Title 35 Brief description of the section. 34 Brief description of the section... 36 35 37 To list pages below this one, use: 38 [[TOC(./*,nonumbering,depth=2)]] 36 [[TOC(SectionPageName/*,inline,nonumbering,notitle,noheading,depth=2)]] 39 37 }}} 40 38 41 '''NOTE:''' Please remember to put the wiki URL corresponding to the page name in the TOC macro. You can see the wiki URL at the top of the page during editing. 42 43 ''Example:'' For this page, the top of the page says "''Editing test/ExperimenterInformation/WikiStyleGuide''", so the TOC macro should then be `[[TOC(test/ExperimenterInformation/WikiStyleGuide/*,depth=1)]]`. Don't forget to add the `/*` at the end of the wiki URL. 44 45 The default TOC depth should be left at 1, unless it makes sense otherwise. 39 The TOC macro will auto-generate an alphabetical inline list of links to sub-pages of the section. If the sub-pages need to have a specific order, feel free to edit the TOC macro or create the list by hand, but try to keep the style as similar as possible. 46 40 47 41 ==== Individual Pages 48 42 Individual wiki pages should use the following as a starting point: 43 49 44 {{{ 50 45 [[Include(WikiToC)]] 51 [[TOC(noheading)]]52 46 53 = Page Title 54 Brief description of the page. 47 == Page Title 48 Brief description of the page... 49 [[PageOutline(3-6,,inline,unnumbered)]] 55 50 56 == Sub Section Title 57 Sub section content. 51 === Sub Section Title 52 Sub section content... 53 }}} 54 55 {{{#!box type=note 56 For pages nested deeper, please increase the number of equal signs in the headings to account for the page depth accordingly (though max heading depth is 6). Otherwise, the auto-generated table of contents on parent pages may not generate correctly. 58 57 }}} 59 58 60 59 ==== Tutorial Pages 61 62 60 Please us the following document skeleton when writing a tutorial. 63 61 64 62 {{{ 65 63 {{{ 66 [[ TOC(noheading)]]64 [[Include(WikiToC)]] 67 65 68 = Tutorial Title66 == Tutorial Title 69 67 70 == Description68 === Description 71 69 Description and goal of the tutorial described here... 70 [[PageOutline(3-6,,inline,unnumbered)]] 72 71 73 == Prerequisites72 === Prerequisites 74 73 In order to access the test bed, create a reservation and have it approved by the reservation service. Access to the resources is granted after the reservation is confirmed. Please follow the process shown on [wiki:cosmos_workflow the COSMOS work flow page] to get started. 75 74 76 == Resource Requirements75 === Resource Requirements 77 76 List of specific resources or requirements, including OMF image name if applicable. 78 77 79 == Setup78 === Setup 80 79 Steps to setup the tutorial... 81 80 82 == Execution81 === Execution 83 82 84 === The first thing you do83 ==== The first thing you do 85 84 First step of the tutorial... 86 85 87 === The second thing you do86 ==== The second thing you do 88 87 Second step of the tutorial... 89 88 }}} … … 91 90 92 91 93 === Syntax Highlighting and code blocks 92 === Code Blocks and Syntax Highlighting 93 When including raw source code blocks, try to use the appropriate syntax highlighting for the language used. Trac uses [https://pygments.org/docs/lexers/ pygments] to do syntax highlighting in code blocks. 94 94 95 Trac uses [https://pygments.org/docs/lexers/ pygments] to do syntax highlighting in code blocks 95 ==== Example 1 96 96 {{{ 97 97 {{{#!shell 98 echo "foo" 98 echo "foo" 99 }}} 99 100 }}} 100 101 101 or 102 will be rendered as 102 103 104 {{{#!shell 105 echo "foo" 106 }}} 107 108 ==== Example 2 109 {{{ 103 110 {{{#!ruby 104 111 defTopology('rxnode') { |t| … … 117 124 }}} 118 125 126 will be rendered as 127 128 {{{#!ruby 129 defTopology('rxnode') { |t| 130 # Load the topology of imaged nodes 131 # These nodes are from most recent omf load command 132 baseTopo = Topology['system:topo:imaged'] 133 134 # Draw a random node from the pool of active ones 135 aNode = baseTopo.getUniqueRandomNode 136 137 # Add this random node to this 'senderTopo' topology 138 t.addNode(aNode) 139 puts "RX: #{t.getNodeByIndex(0).to_s}" 140 } 141 }}} 142 119 143 ==== Common formats 120 144 121 || language || shortname for codeblock||122 || shell script || bash, sh, ksh, zsh, shell ||123 || shell session || console, shell-session ||124 || powershell || powershell, posh, ps1, psm1 ||125 || ruby session || rbcon, irb ||126 || ruby code || rb, ruby, duby ||127 || json || json ||128 || json w no braces || json-object ||129 || yaml, yml || yaml ||130 || mix of yaml and jinja ||yaml+jinja, salt, sls ||131 || docker || docker, dockerfile ||145 ||=Language =||=Shortname for Codeblock =|| 146 || shell script || bash, sh, ksh, zsh, shell || 147 || shell session || console, shell-session || 148 || powershell || powershell, posh, ps1, psm1 || 149 || ruby session || rbcon, irb || 150 || ruby code || rb, ruby, duby || 151 || json || json || 152 || json w no braces || json-object || 153 || yaml, yml || yaml || 154 || mix of yaml and jinja ||yaml+jinja, salt, sls || 155 || docker || docker, dockerfile || 132 156 133 157 === Using Markdown or !RestructuredText 134 158 135 Using code blocks like before, Trac can render other markup formats 159 To use Markdown instead of Tracs' own language, simply enclose the Markdown text in a code block starting with `#!Markdown` like this: 136 160 {{{ 137 161 {{{#!Markdown 138 # heading 1 139 ## heading 2 140 ### heading 3 162 # Some Title 163 Sample text. 164 165 ## A Sub Section 166 More sample text. 167 168 ### Yet another sub section 169 Even more sample text. 170 }}} 171 }}} 172 173 or if you want to use !RestructuredText instead, start the code block with `#!rst` like this: 174 {{{ 175 {{{#!rst 176 ********** 177 Some Title 178 ********** 179 Sample text. 180 181 A Sub Section 182 ############# 183 More sample text. 184 185 Yet another sub section 186 *********************** 187 Even more sample text. 141 188 }}} 142 189 }}} … … 145 192 146 193 147
