.config/coc/extensions/coc-go-data/tools/pkg/mod/golang.org/x/tools@v0.0.0-20201028153306-37f0764111ff/present/doc.go

   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         2 Jan 2006
  30 In this case, the time will be interpreted as 10am UTC on that date.
  31
  32 The tags line is a comma-separated list of tags that may be used to categorize
  33 the document.
  34
  35 The summary line gives a short summary used in blog feeds.
  36
  37 The old URL line, which may be repeated, gives an older (perhaps relative) URL
  38 for this document.
  39 A server might use these to generate appropriate redirects.
  40
  41 Only the title is required;
  42 the subtitle, date, tags, summary, and old URL lines are optional.
  43 In Markdown-enabled present, the summary defaults to being empty.
  44 In legacy present, the summary defaults to the first paragraph of text.
  45
  46 After 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
  54 The first line of the author block is conventionally the author name.
  55 Otherwise, the author section may contain a mixture of text, twitter names, and links.
  56 For slide presentations, only the plain text lines will be displayed on the
  57 first slide.
  58
  59 If multiple author blocks are listed, each new block must be preceded
  60 by its own blank line.
  61
  62 After the author blocks come the presentation slides or article sections,
  63 which can in turn have subsections.
  64 In Markdown-enabled present files, each slide or section begins with a "##" header line,
  65 subsections begin with a "###" header line, and so on.
  66 In legacy present files, each slide or section begins with a "*" header line,
  67 subsections begin with a "**" header line, and so on.
  68
  69 In addition to the marked-up text in a section (or subsection),
  70 a present file can contain present command invocations, each of which begins
  71 with 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
  82 Other than the commands, the text in a section is interpreted
  83 either as Markdown or as legacy present markup.
  84
  85 Markdown Syntax
  86
  87 Markdown typically means the generic name for a family of similar markup languages.
  88 The specific variant used in present is CommonMark.
  89 See https://commonmark.org/help/tutorial/ for a quick tutorial.
  90
  91 In Markdown-enabled present,
  92 section headings can end in {#name} to set the HTML anchor ID for the heading to "name".
  93
  94 Lines beginning with "//" (outside of code blocks, of course)
  95 are treated as present comments and have no effect.
  96
  97 Lines beginning with ": " are treated as speaker notes, described below.
  98
  99 Example:
 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
 141 Legacy Present Syntax
 142
 143 Compared to Markdown,
 144 in legacy present
 145 slides/sections use "*" instead of "##",
 146 whole-line comments begin with "#" instead of "//",
 147 bullet lists can only contain single (possibly wrapped) text lines,
 148 and the font styling and link syntaxes are subtly different.
 149
 150 Example:
 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
 190 Within the input for plain text or lists, text bracketed by font
 191 markers will be presented in italic, bold, or program font.
 192 Marker characters are _ (italic), * (bold) and ` (program font).
 193 An opening marker must be preceded by a space or punctuation
 194 character or else be at start of a line; similarly, a closing
 195 marker must be followed by a space or punctuation character or
 196 else be at the end of a line. Unmatched markers appear as plain text.
 197 There must be no spaces between markers. Within marked text,
 198 a single marker character becomes a space and a doubled single
 199 marker quotes the marker character.
 200
 201 Links can be included in any text with the form [[url][label]], or
 202 [[url]] to use the URL itself as the label.
 203
 204 Command Invocations
 205
 206 A number of special commands are available through invocations
 207 in the input text. Each such invocation contains a period as the
 208 first character on the line, followed immediately by the name of
 209 the function, followed by any arguments. A typical invocation might
 210 be
 211
 212         .play demo.go /^func show/,/^}/
 213
 214 (except that the ".play" must be at the beginning of the line and
 215 not be indented as in this comment.)
 216
 217 Here follows a description of the functions:
 218
 219 code:
 220
 221 Injects program source into the output by extracting code from files
 222 and injecting them as HTML-escaped <pre> blocks.  The argument is
 223 a file name followed by an optional address that specifies what
 224 section of the file to display. The address syntax is similar in
 225 its simplest form to that of ed, but comes from sam and is more
 226 general. See
 227         https://plan9.io/sys/doc/sam/sam.html Table II
 228 for full details. The displayed block is always rounded out to a
 229 full line at both ends.
 230
 231 If no pattern is present, the entire file is displayed.
 232
 233 Any line in the program that ends with the four characters
 234         OMIT
 235 is deleted from the source before inclusion, making it easy
 236 to write things like
 237         .code test.go /START OMIT/,/END OMIT/
 238 to find snippets like this
 239         tedious_code = boring_function()
 240         // START OMIT
 241         interesting_code = fascinating_function()
 242         // END OMIT
 243 and see only this:
 244         interesting_code = fascinating_function()
 245
 246 Also, inside the displayed text a line that ends
 247         // HL
 248 will be highlighted in the display. A highlighting mark may have a
 249 suffix word, such as
 250         // HLxxx
 251 Such highlights are enabled only if the code invocation ends with
 252 "HL" followed by the word:
 253         .code test.go /^type Foo/,/^}/ HLxxx
 254
 255 The .code function may take one or more flags immediately preceding
 256 the filename. This command shows test.go in an editable text area:
 257         .code -edit test.go
 258 This command shows test.go with line numbers:
 259         .code -numbers test.go
 260
 261 play:
 262
 263 The function "play" is the same as "code" but puts a button
 264 on the displayed source so the program can be run from the browser.
 265 Although only the selected text is shown, all the source is included
 266 in the HTML output so it can be presented to the compiler.
 267
 268 link:
 269
 270 Create a hyperlink. The syntax is 1 or 2 space-separated arguments.
 271 The first argument is always the HTTP URL.  If there is a second
 272 argument, it is the text label to display for this link.
 273
 274         .link https://golang.org golang.org
 275
 276 image:
 277
 278 The template uses the function "image" to inject picture files.
 279
 280 The syntax is simple: 1 or 3 space-separated arguments.
 281 The first argument is always the file name.
 282 If there are more arguments, they are the height and width;
 283 both must be present, or substituted with an underscore.
 284 Replacing a dimension argument with the underscore parameter
 285 preserves the aspect ratio of the image when scaling.
 286
 287         .image images/betsy.jpg 100 200
 288         .image images/janet.jpg _ 300
 289
 290 video:
 291
 292 The template uses the function "video" to inject video files.
 293
 294 The syntax is simple: 2 or 4 space-separated arguments.
 295 The first argument is always the file name.
 296 The second argument is always the file content-type.
 297 If there are more arguments, they are the height and width;
 298 both must be present, or substituted with an underscore.
 299 Replacing a dimension argument with the underscore parameter
 300 preserves 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
 306 background:
 307
 308 The template uses the function "background" to set the background image for
 309 a slide.  The only argument is the file name of the image.
 310
 311         .background images/susan.jpg
 312
 313 caption:
 314
 315 The template uses the function "caption" to inject figure captions.
 316
 317 The text after ".caption" is embedded in a figcaption element after
 318 processing styling and links as in standard text lines.
 319
 320         .caption _Gopher_ by [[https://instagram.com/reneefrench][Renee French]]
 321
 322 iframe:
 323
 324 The function "iframe" injects iframes (pages inside pages).
 325 Its syntax is the same as that of image.
 326
 327 html:
 328
 329 The function html includes the contents of the specified file as
 330 unescaped HTML. This is useful for including custom HTML elements
 331 that cannot be created using only the slide format.
 332 It is your responsibility to make sure the included HTML is valid and safe.
 333
 334         .html file.html
 335
 336 Presenter Notes
 337
 338 Lines that begin with ": " are treated as presenter notes,
 339 in both Markdown and legacy present syntax.
 340 By default, presenter notes are collected but ignored.
 341
 342 When running the present command with -notes,
 343 typing 'N' in your browser displaying your slides
 344 will create a second window displaying the notes.
 345 The second window is completely synced with the main
 346 window, except that presenter notes are only visible in the second window.
 347
 348 Notes 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 */
 361 package present // import "golang.org/x/tools/present"