GoPLS Viewer

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