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