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.
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).
12 Present files begin with a header giving the title of the document
13 and other metadata, which looks like:
19 Summary: This is a great document you want to read.
20 OldURL: former-path-for-this-doc
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.
28 The date line may be written without a time:
30 In this case, the time will be interpreted as 10am UTC on that date.
32 The tags line is a comma-separated list of tags that may be used to categorize
35 The summary line gives a short summary used in blog feeds.
37 The old URL line, which may be repeated, gives an older (perhaps relative) URL
39 A server might use these to generate appropriate redirects.
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.
46 After the header come zero or more author blocks, like this:
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
59 If multiple author blocks are listed, each new block must be preceded
60 by its own blank line.
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.
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
73 .code x.go /^func main/,/^}/
78 .link https://foo label
80 .caption _Gopher_ by [[https://instagram.com/reneefrench][Renee French]]
82 Other than the commands, the text in a section is interpreted
83 either as Markdown or as legacy present markup.
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.
91 In Markdown-enabled present,
92 section headings can end in {#name} to set the HTML anchor ID for the heading to "name".
94 Lines beginning with "//" (outside of code blocks, of course)
95 are treated as present comments and have no effect.
97 Lines beginning with ": " are treated as speaker notes, described below.
107 ## Title of Slide or Section (must begin with ##)
111 ### Subsection {#anchor}
122 Preformatted text (code block)
123 is indented (by one tab, or four spaces)
125 Further Text, including command invocations.
127 ## Section 2: Example formatting {#fmt}
132 // A comment that is completely ignored.
136 Markup—_especially italic text_—can easily be overused.
137 _Why use scoped\_ptr_? Use plain **\*ptr** instead.
139 Visit [the Go home page](https://golang.org/).
141 Legacy Present Syntax
143 Compared to Markdown,
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.
158 * Title of Slide or Section (must begin with *)
167 on the next line (indented at least one space)
173 Preformatted text (code block)
174 is indented (however you like)
176 Further Text, including command invocations.
178 * Section 2: Example formatting
185 Markup—_especially_italic_text_—can easily be overused.
186 _Why_use_scoped__ptr_? Use plain ***ptr* instead.
188 Visit [[https://golang.org][the Go home page]].
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.
201 Links can be included in any text with the form [[url][label]], or
202 [[url]] to use the URL itself as the label.
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
212 .play demo.go /^func show/,/^}/
214 (except that the ".play" must be at the beginning of the line and
215 not be indented as in this comment.)
217 Here follows a description of the functions:
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
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.
231 If no pattern is present, the entire file is displayed.
233 Any line in the program that ends with the four characters
235 is deleted from the source before inclusion, making it easy
237 .code test.go /START OMIT/,/END OMIT/
238 to find snippets like this
239 tedious_code = boring_function()
241 interesting_code = fascinating_function()
244 interesting_code = fascinating_function()
246 Also, inside the displayed text a line that ends
248 will be highlighted in the display. A highlighting mark may have a
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
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:
258 This command shows test.go with line numbers:
259 .code -numbers test.go
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.
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.
274 .link https://golang.org golang.org
278 The template uses the function "image" to inject picture files.
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.
287 .image images/betsy.jpg 100 200
288 .image images/janet.jpg _ 300
292 The template uses the function "video" to inject video files.
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.
302 .video videos/evangeline.mp4 video/mp4 400 600
304 .video videos/mabel.ogg video/ogg 500 _
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.
311 .background images/susan.jpg
315 The template uses the function "caption" to inject figure captions.
317 The text after ".caption" is embedded in a figcaption element after
318 processing styling and links as in standard text lines.
320 .caption _Gopher_ by [[https://instagram.com/reneefrench][Renee French]]
324 The function "iframe" injects iframes (pages inside pages).
325 Its syntax is the same as that of image.
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.
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.
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.
348 Notes may appear anywhere within the slide text. For example:
354 : Presenter notes (first paragraph)
358 : Presenter notes (subsequent paragraph(s))
361 package present // import "golang.org/x/tools/present"