tutor.tutor (5305B)
1 # CREATING A VIM TUTORIAL WITH VIM-TUTOR-MODE 2 3 This tutorial will guide you through the steps required to create a tutorial 4 file for vim-tutor-mode. It is also meant as a demo of vim-tutor-mode 5 capabilities. 6 7 Table of contents: 8 9 - [Setting up](*setting-up*) 10 - [vim-tutor-mode's markup](*markup*) 11 - [emphasis](*emphasis*) 12 - [headers](*headers*) 13 - [links](*links*) 14 - [codeblocks](*codeblocks*) 15 - [Interactive elements](*interactive*) 16 - [expect](*expect*) 17 18 ## SETTING UP *setting-up* 19 20 Create a new .tutor file (we will be practicing on this very file, so you don't 21 need to do this now): 22 ~~~ cmd 23 :e new-tutorial.tutor 24 ~~~ 25 26 ## VIM-TUTOR-MODE's MARKDOWN *markup* 27 28 vim-tutor-mode uses a subset of markdown's syntax to format the tutorials. The 29 subset supported should be enough for most tutorials and the maintainers will 30 try to keep it as small as possible (if regular markdown allows for several 31 ways to do the same thing, tutor markdown will only provide the one the 32 maintainers think is easier to handle). 33 34 ### Emphasis *emphasis* 35 36 For emphasized text (italics), as in normal markdown, you use \*. E.g.: 37 38 \*text\* 39 40 is displayed like 41 42 *text* 43 44 Note: The underscores variant is not supported. 45 46 For strong emphasis (bold), you use \*\*. E.g.: 47 48 \*\*this\*\* 49 50 is displayed like 51 52 **this** 53 54 1. Format the line below so it becomes a lesson description: 55 56 This is text with important information 57 This is text with **important information** 58 59 Note: Some words (e.g., NOTE, IMPORTANT, tip, ATTENTION, etc.) will also be 60 highlighted. You don't need to mark them specially. 61 62 2. Turn the line below into a TODO item: 63 64 Document '&variable' 65 TODO: Document '&variable' 66 67 ### Headers *headers* 68 69 3. Practice fixing the lines below: 70 71 This is a level 1 header 72 # This is a level 1 header 73 This is a level 3 header 74 ### This is a level 3 header 75 This is a header with a label 76 # This is a header with a label {*label*} 77 78 4. Now, create a 4th level section here, and add a label like in the previous 79 exercise: 80 81 82 83 ATTENTION We will use this label later, so remember it. 84 85 ### Links *links* 86 87 It is good practice to include links in your tutorials to reference materials, 88 like vim's own help or external documents. You can also link to other parts of 89 the document. 90 91 Links have the syntax 92 93 \[label\]\(target\) 94 95 #### Help links 96 97 If the target of a link matches a help topic, opening it will open it. 98 99 5. Fix the following line: 100 101 A link to help for the 'breakindent' option 102 A link to help for the ['breakindent']('breakindent') option 103 104 #### Anchor links 105 106 A link can also lead to a place in the file itself. Anchors are written 107 108 \*anchor\* 109 110 and are hidden by default. Links to them look like 111 112 \[label\]\(\*anchor\*\) 113 114 6. Add the appropriate link: 115 116 A link to the Links section 117 A link to the [Links](*links*) section 118 119 7. Now, create a link to the section you created on exercise 4 120 above. 121 122 123 124 # Tutorial links 125 126 You can also have links to other tutorials. For this, you'll write the anchor in the format 127 128 @tutor:TUTORIAL 129 130 7. Create a link to this tutorial: 131 132 A link to the vim-tutor-mode tutorial 133 A link to [the vim-tutor-mode tutorial](@tutor:tutor) 134 135 ### Codeblocks *codeblocks* 136 137 vim-tutor-mode tutorials can include viml sections 138 139 ~~~ cmd 140 echom "hello" 141 ~~~ 142 143 is displayed as 144 ~~~ cmd 145 echom "hello" 146 ~~~ 147 148 8. Copy the viml section below 149 150 151 152 153 154 ~~~ viml 155 echom 'the value of &number is'.string(&number) 156 ~~~ 157 158 You can inline viml code using "\`" and "\`{vim}": 159 160 \`call myFunction()\`{vim} 161 162 is displayed as 163 164 `call myFunction()`{vim} 165 166 [normal](Normal-mode) commands can also be embedded in tutorials. 167 168 ~~~ normal 169 ftdaW 170 ~~~ 171 172 is displayed as 173 ~~~ normal 174 ftdaW 175 ~~~ 176 177 Note: you can also write `norm` or `normal`. 178 179 9. Copy the normal section below 180 181 182 183 184 185 ~~~ normal 186 d2w 187 ~~~ 188 189 You can also inline normal commands by using "\`" and "\`{normal}": 190 191 \`gq\`{normal} is very useful. 192 193 is displayed: 194 195 `gq`{normal} is very useful. 196 197 10. Complete the line as shown 198 199 d 200 `d2w`{normal} 201 202 Commands to run in the system shell can be highlighted by indenting a line 203 starting with "$". 204 205 ~~~ sh 206 $ vim --version 207 ~~~ 208 209 ## INTERACTIVE ELEMENTS *interactive* 210 211 As visible in this very document, vim-tutor-mode includes some interactive 212 elements to provide feedback to the user about their progress. If the text in 213 these elements satisfies some set condition, a ✓ sign will appear in the gutter 214 to the left. Otherwise, a ✗ sign is displayed. 215 216 ### expect *expect* 217 218 "expect" lines check that the contents of the line are identical to some preset text 219 (like in the exercises above). 220 221 These elements are specified in separate JSON files like this 222 223 ~~~ json 224 { 225 "expect": { 226 "1": "This is how this line should look.", 227 "2": "This is how this line should look.", 228 "3": -1 229 } 230 } 231 ~~~ 232 233 These files contain an "expect" dictionary, for which the keys are line numbers and 234 the values are the expected text. A value of -1 means that the condition for the line 235 will always be satisfied, no matter what (this is useful for letting the user play a bit). 236 237 This is an "expect" line that is always satisfied. Try changing it. 238 239 These files conventionally have the same name as the tutorial document with the `.json` 240 extension appended (for a full example, see the file that corresponds to this tutorial).