1 // Copyright 2011 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 /* 6 Package present implements parsing and rendering of present files, 7 which can be slide presentations as in golang.org/x/tools/cmd/present 8 or articles as in golang.org/x/blog (the Go blog). 9 10 # File Format 11 12 Present files begin with a header giving the title of the document 13 and other metadata, which looks like: 14 15 # Title of document 16 Subtitle of document 17 15:04 2 Jan 2006 18 Tags: foo, bar, baz 19 Summary: This is a great document you want to read. 20 OldURL: former-path-for-this-doc 21 22 The "# " prefix before the title indicates that this is 23 a Markdown-enabled present file: it uses 24 Markdown for text markup in the body of the file. 25 If the "# " prefix is missing, the file uses 26 legacy present markup, described below. 27 28 The date line may be written without a time: 29 30 2 Jan 2006 31 32 In this case, the time will be interpreted as 10am UTC on that date. 33 34 The tags line is a comma-separated list of tags that may be used to categorize 35 the document. 36 37 The summary line gives a short summary used in blog feeds. 38 39 The old URL line, which may be repeated, gives an older (perhaps relative) URL 40 for this document. 41 A server might use these to generate appropriate redirects. 42 43 Only the title is required; 44 the subtitle, date, tags, summary, and old URL lines are optional. 45 In Markdown-enabled present, the summary defaults to being empty. 46 In legacy present, the summary defaults to the first paragraph of text. 47 48 After the header come zero or more author blocks, like this: 49 50 Author Name 51 Job title, Company 52 joe@example.com 53 https://url/ 54 @twitter_name 55 56 The first line of the author block is conventionally the author name. 57 Otherwise, the author section may contain a mixture of text, twitter names, and links. 58 For slide presentations, only the plain text lines will be displayed on the 59 first slide. 60 61 If multiple author blocks are listed, each new block must be preceded 62 by its own blank line. 63 64 After the author blocks come the presentation slides or article sections, 65 which can in turn have subsections. 66 In Markdown-enabled present files, each slide or section begins with a "##" header line, 67 subsections begin with a "###" header line, and so on. 68 In legacy present files, each slide or section begins with a "*" header line, 69 subsections begin with a "**" header line, and so on. 70 71 In addition to the marked-up text in a section (or subsection), 72 a present file can contain present command invocations, each of which begins 73 with a dot, as in: 74 75 .code x.go /^func main/,/^}/ 76 .play y.go 77 .image image.jpg 78 .background image.jpg 79 .iframe https://foo 80 .link https://foo label 81 .html file.html 82 .caption _Gopher_ by [[https://instagram.com/reneefrench][Renee French]] 83 84 Other than the commands, the text in a section is interpreted 85 either as Markdown or as legacy present markup. 86 87 # Markdown Syntax 88 89 Markdown typically means the generic name for a family of similar markup languages. 90 The specific variant used in present is CommonMark. 91 See https://commonmark.org/help/tutorial/ for a quick tutorial. 92 93 In Markdown-enabled present, 94 section headings can end in {#name} to set the HTML anchor ID for the heading to "name". 95 96 Lines beginning with "//" (outside of code blocks, of course) 97 are treated as present comments and have no effect. 98 99 Lines beginning with ": " are treated as speaker notes, described below. 100 101 Example: 102 103 # Title of Talk 104 105 My Name 106 9 Mar 2020 107 me@example.com 108 109 ## Title of Slide or Section (must begin with ##) 110 111 Some Text 112 113 ### Subsection {#anchor} 114 115 - bullets 116 - more bullets 117 - a bullet continued 118 on the next line 119 120 #### Sub-subsection 121 122 Some More text 123 124 Preformatted text (code block) 125 is indented (by one tab, or four spaces) 126 127 Further Text, including command invocations. 128 129 ## Section 2: Example formatting {#fmt} 130 131 Formatting: 132 133 _italic_ 134 // A comment that is completely ignored. 135 : Speaker notes. 136 **bold** 137 `program` 138 Markup—_especially italic text_—can easily be overused. 139 _Why use scoped\_ptr_? Use plain **\*ptr** instead. 140 141 Visit [the Go home page](https://golang.org/). 142 143 # Legacy Present Syntax 144 145 Compared to Markdown, 146 in legacy present 147 slides/sections use "*" instead of "##", 148 whole-line comments begin with "#" instead of "//", 149 bullet lists can only contain single (possibly wrapped) text lines, 150 and the font styling and link syntaxes are subtly different. 151 152 Example: 153 154 Title of Talk 155 156 My Name 157 1 Jan 2013 158 me@example.com 159 160 * Title of Slide or Section (must begin with *) 161 162 Some Text 163 164 ** Subsection 165 166 - bullets 167 - more bullets 168 - a bullet continued 169 on the next line (indented at least one space) 170 171 *** Sub-subsection 172 173 Some More text 174 175 Preformatted text (code block) 176 is indented (however you like) 177 178 Further Text, including command invocations. 179 180 * Section 2: Example formatting 181 182 Formatting: 183 184 _italic_ 185 *bold* 186 `program` 187 Markup—_especially_italic_text_—can easily be overused. 188 _Why_use_scoped__ptr_? Use plain ***ptr* instead. 189 190 Visit [[https://golang.org][the Go home page]]. 191 192 Within the input for plain text or lists, text bracketed by font 193 markers will be presented in italic, bold, or program font. 194 Marker characters are _ (italic), * (bold) and ` (program font). 195 An opening marker must be preceded by a space or punctuation 196 character or else be at start of a line; similarly, a closing 197 marker must be followed by a space or punctuation character or 198 else be at the end of a line. Unmatched markers appear as plain text. 199 There must be no spaces between markers. Within marked text, 200 a single marker character becomes a space and a doubled single 201 marker quotes the marker character. 202 203 Links can be included in any text with the form [[url][label]], or 204 [[url]] to use the URL itself as the label. 205 206 # Command Invocations 207 208 A number of special commands are available through invocations 209 in the input text. Each such invocation contains a period as the 210 first character on the line, followed immediately by the name of 211 the function, followed by any arguments. A typical invocation might 212 be 213 214 .play demo.go /^func show/,/^}/ 215 216 (except that the ".play" must be at the beginning of the line and 217 not be indented as in this comment.) 218 219 Here follows a description of the functions: 220 221 code: 222 223 Injects program source into the output by extracting code from files 224 and injecting them as HTML-escaped <pre> blocks. The argument is 225 a file name followed by an optional address that specifies what 226 section of the file to display. The address syntax is similar in 227 its simplest form to that of ed, but comes from sam and is more 228 general. See 229 230 https://plan9.io/sys/doc/sam/sam.html Table II 231 232 for full details. The displayed block is always rounded out to a 233 full line at both ends. 234 235 If no pattern is present, the entire file is displayed. 236 237 Any line in the program that ends with the four characters 238 239 OMIT 240 241 is deleted from the source before inclusion, making it easy 242 to write things like 243 244 .code test.go /START OMIT/,/END OMIT/ 245 246 to find snippets like this 247 248 tedious_code = boring_function() 249 // START OMIT 250 interesting_code = fascinating_function() 251 // END OMIT 252 253 and see only this: 254 255 interesting_code = fascinating_function() 256 257 Also, inside the displayed text a line that ends 258 259 // HL 260 261 will be highlighted in the display. A highlighting mark may have a 262 suffix word, such as 263 264 // HLxxx 265 266 Such highlights are enabled only if the code invocation ends with 267 "HL" followed by the word: 268 269 .code test.go /^type Foo/,/^}/ HLxxx 270 271 The .code function may take one or more flags immediately preceding 272 the filename. This command shows test.go in an editable text area: 273 274 .code -edit test.go 275 276 This command shows test.go with line numbers: 277 278 .code -numbers test.go 279 280 play: 281 282 The function "play" is the same as "code" but puts a button 283 on the displayed source so the program can be run from the browser. 284 Although only the selected text is shown, all the source is included 285 in the HTML output so it can be presented to the compiler. 286 287 link: 288 289 Create a hyperlink. The syntax is 1 or 2 space-separated arguments. 290 The first argument is always the HTTP URL. If there is a second 291 argument, it is the text label to display for this link. 292 293 .link https://golang.org golang.org 294 295 image: 296 297 The template uses the function "image" to inject picture files. 298 299 The syntax is simple: 1 or 3 space-separated arguments. 300 The first argument is always the file name. 301 If there are more arguments, they are the height and width; 302 both must be present, or substituted with an underscore. 303 Replacing a dimension argument with the underscore parameter 304 preserves the aspect ratio of the image when scaling. 305 306 .image images/betsy.jpg 100 200 307 .image images/janet.jpg _ 300 308 309 video: 310 311 The template uses the function "video" to inject video files. 312 313 The syntax is simple: 2 or 4 space-separated arguments. 314 The first argument is always the file name. 315 The second argument is always the file content-type. 316 If there are more arguments, they are the height and width; 317 both must be present, or substituted with an underscore. 318 Replacing a dimension argument with the underscore parameter 319 preserves the aspect ratio of the video when scaling. 320 321 .video videos/evangeline.mp4 video/mp4 400 600 322 323 .video videos/mabel.ogg video/ogg 500 _ 324 325 background: 326 327 The template uses the function "background" to set the background image for 328 a slide. The only argument is the file name of the image. 329 330 .background images/susan.jpg 331 332 caption: 333 334 The template uses the function "caption" to inject figure captions. 335 336 The text after ".caption" is embedded in a figcaption element after 337 processing styling and links as in standard text lines. 338 339 .caption _Gopher_ by [[https://instagram.com/reneefrench][Renee French]] 340 341 iframe: 342 343 The function "iframe" injects iframes (pages inside pages). 344 Its syntax is the same as that of image. 345 346 html: 347 348 The function html includes the contents of the specified file as 349 unescaped HTML. This is useful for including custom HTML elements 350 that cannot be created using only the slide format. 351 It is your responsibility to make sure the included HTML is valid and safe. 352 353 .html file.html 354 355 # Presenter Notes 356 357 Lines that begin with ": " are treated as presenter notes, 358 in both Markdown and legacy present syntax. 359 By default, presenter notes are collected but ignored. 360 361 When running the present command with -notes, 362 typing 'N' in your browser displaying your slides 363 will create a second window displaying the notes. 364 The second window is completely synced with the main 365 window, except that presenter notes are only visible in the second window. 366 367 Notes may appear anywhere within the slide text. For example: 368 369 ## Title of slide 370 371 Some text. 372 373 : Presenter notes (first paragraph) 374 375 Some more text. 376 377 : Presenter notes (subsequent paragraph(s)) 378 */ 379 package present // import "golang.org/x/tools/present" 380