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 either explicit labels 204 or the URL itself as the label. For example: 205 206 [[url][label]] 207 [[url]] 208 209 # Command Invocations 210 211 A number of special commands are available through invocations 212 in the input text. Each such invocation contains a period as the 213 first character on the line, followed immediately by the name of 214 the function, followed by any arguments. A typical invocation might 215 be 216 217 .play demo.go /^func show/,/^}/ 218 219 (except that the ".play" must be at the beginning of the line and 220 not be indented as in this comment.) 221 222 Here follows a description of the functions: 223 224 code: 225 226 Injects program source into the output by extracting code from files 227 and injecting them as HTML-escaped <pre> blocks. The argument is 228 a file name followed by an optional address that specifies what 229 section of the file to display. The address syntax is similar in 230 its simplest form to that of ed, but comes from sam and is more 231 general. See 232 233 https://plan9.io/sys/doc/sam/sam.html Table II 234 235 for full details. The displayed block is always rounded out to a 236 full line at both ends. 237 238 If no pattern is present, the entire file is displayed. 239 240 Any line in the program that ends with the four characters 241 242 OMIT 243 244 is deleted from the source before inclusion, making it easy 245 to write things like 246 247 .code test.go /START OMIT/,/END OMIT/ 248 249 to find snippets like this 250 251 tedious_code = boring_function() 252 // START OMIT 253 interesting_code = fascinating_function() 254 // END OMIT 255 256 and see only this: 257 258 interesting_code = fascinating_function() 259 260 Also, inside the displayed text a line that ends 261 262 // HL 263 264 will be highlighted in the display. A highlighting mark may have a 265 suffix word, such as 266 267 // HLxxx 268 269 Such highlights are enabled only if the code invocation ends with 270 "HL" followed by the word: 271 272 .code test.go /^type Foo/,/^}/ HLxxx 273 274 The .code function may take one or more flags immediately preceding 275 the filename. This command shows test.go in an editable text area: 276 277 .code -edit test.go 278 279 This command shows test.go with line numbers: 280 281 .code -numbers test.go 282 283 play: 284 285 The function "play" is the same as "code" but puts a button 286 on the displayed source so the program can be run from the browser. 287 Although only the selected text is shown, all the source is included 288 in the HTML output so it can be presented to the compiler. 289 290 link: 291 292 Create a hyperlink. The syntax is 1 or 2 space-separated arguments. 293 The first argument is always the HTTP URL. If there is a second 294 argument, it is the text label to display for this link. 295 296 .link https://golang.org golang.org 297 298 image: 299 300 The template uses the function "image" to inject picture files. 301 302 The syntax is simple: 1 or 3 space-separated arguments. 303 The first argument is always the file name. 304 If there are more arguments, they are the height and width; 305 both must be present, or substituted with an underscore. 306 Replacing a dimension argument with the underscore parameter 307 preserves the aspect ratio of the image when scaling. 308 309 .image images/betsy.jpg 100 200 310 .image images/janet.jpg _ 300 311 312 video: 313 314 The template uses the function "video" to inject video files. 315 316 The syntax is simple: 2 or 4 space-separated arguments. 317 The first argument is always the file name. 318 The second argument is always the file content-type. 319 If there are more arguments, they are the height and width; 320 both must be present, or substituted with an underscore. 321 Replacing a dimension argument with the underscore parameter 322 preserves the aspect ratio of the video when scaling. 323 324 .video videos/evangeline.mp4 video/mp4 400 600 325 326 .video videos/mabel.ogg video/ogg 500 _ 327 328 background: 329 330 The template uses the function "background" to set the background image for 331 a slide. The only argument is the file name of the image. 332 333 .background images/susan.jpg 334 335 caption: 336 337 The template uses the function "caption" to inject figure captions. 338 339 The text after ".caption" is embedded in a figcaption element after 340 processing styling and links as in standard text lines. 341 342 .caption _Gopher_ by [[https://instagram.com/reneefrench][Renee French]] 343 344 iframe: 345 346 The function "iframe" injects iframes (pages inside pages). 347 Its syntax is the same as that of image. 348 349 html: 350 351 The function html includes the contents of the specified file as 352 unescaped HTML. This is useful for including custom HTML elements 353 that cannot be created using only the slide format. 354 It is your responsibility to make sure the included HTML is valid and safe. 355 356 .html file.html 357 358 # Presenter Notes 359 360 Lines that begin with ": " are treated as presenter notes, 361 in both Markdown and legacy present syntax. 362 By default, presenter notes are collected but ignored. 363 364 When running the present command with -notes, 365 typing 'N' in your browser displaying your slides 366 will create a second window displaying the notes. 367 The second window is completely synced with the main 368 window, except that presenter notes are only visible in the second window. 369 370 Notes may appear anywhere within the slide text. For example: 371 372 ## Title of slide 373 374 Some text. 375 376 : Presenter notes (first paragraph) 377 378 Some more text. 379 380 : Presenter notes (subsequent paragraph(s)) 381 */ 382 package present // import "golang.org/x/tools/present" 383