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/*
6The present file format
7
8Present files have the following format.  The first non-blank non-comment
9line is the title, so the header looks like
10
11	Title of document
12	Subtitle of document
13	15:04 2 Jan 2006
14	Tags: foo, bar, baz
15	<blank line>
16	Author Name
17	Job title, Company
18	joe@example.com
19	http://url/
20	@twitter_name
21
22The subtitle, date, and tags lines are optional.
23
24The date line may be written without a time:
25	2 Jan 2006
26In this case, the time will be interpreted as 10am UTC on that date.
27
28The tags line is a comma-separated list of tags that may be used to categorize
29the document.
30
31The author section may contain a mixture of text, twitter names, and links.
32For slide presentations, only the plain text lines will be displayed on the
33first slide.
34
35Multiple presenters may be specified, separated by a blank line.
36
37After that come slides/sections, each after a blank line:
38
39	* Title of slide or section (must have asterisk)
40
41	Some Text
42
43	** Subsection
44
45	- bullets
46	- more bullets
47	- a bullet with
48
49	*** Sub-subsection
50
51	Some More text
52
53	  Preformatted text
54	  is indented (however you like)
55
56	Further Text, including invocations like:
57
58	.code x.go /^func main/,/^}/
59	.play y.go
60	.image image.jpg
61	.background image.jpg
62	.iframe http://foo
63	.link http://foo label
64	.html file.html
65	.caption _Gopher_ by [[https://www.instagram.com/reneefrench/][Renée French]]
66
67	Again, more text
68
69Blank lines are OK (not mandatory) after the title and after the
70text.  Text, bullets, and .code etc. are all optional; title is
71not.
72
73Lines starting with # in column 1 are commentary.
74
75Fonts:
76
77Within the input for plain text or lists, text bracketed by font
78markers will be presented in italic, bold, or program font.
79Marker characters are _ (italic), * (bold) and ` (program font).
80An opening marker must be preceded by a space or punctuation
81character or else be at start of a line; similarly, a closing
82marker must be followed by a space or punctuation character or
83else be at the end of a line. Unmatched markers appear as plain text.
84There must be no spaces between markers. Within marked text,
85a single marker character becomes a space and a doubled single
86marker quotes the marker character.
87
88	_italic_
89	*bold*
90	`program`
91	Markup—_especially_italic_text_—can easily be overused.
92	_Why_use_scoped__ptr_? Use plain ***ptr* instead.
93
94Inline links:
95
96Links can be included in any text with the form [[url][label]], or
97[[url]] to use the URL itself as the label.
98
99Functions:
100
101A number of template functions are available through invocations
102in the input text. Each such invocation contains a period as the
103first character on the line, followed immediately by the name of
104the function, followed by any arguments. A typical invocation might
105be
106	.play demo.go /^func show/,/^}/
107(except that the ".play" must be at the beginning of the line and
108not be indented like this.)
109
110Here follows a description of the functions:
111
112code:
113
114Injects program source into the output by extracting code from files
115and injecting them as HTML-escaped <pre> blocks.  The argument is
116a file name followed by an optional address that specifies what
117section of the file to display. The address syntax is similar in
118its simplest form to that of ed, but comes from sam and is more
119general. See
120	https://plan9.io/sys/doc/sam/sam.html Table II
121for full details. The displayed block is always rounded out to a
122full line at both ends.
123
124If no pattern is present, the entire file is displayed.
125
126Any line in the program that ends with the four characters
127	OMIT
128is deleted from the source before inclusion, making it easy
129to write things like
130	.code test.go /START OMIT/,/END OMIT/
131to find snippets like this
132	tedious_code = boring_function()
133	// START OMIT
134	interesting_code = fascinating_function()
135	// END OMIT
136and see only this:
137	interesting_code = fascinating_function()
138
139Also, inside the displayed text a line that ends
140	// HL
141will be highlighted in the display. A highlighting mark may have a
142suffix word, such as
143	// HLxxx
144Such highlights are enabled only if the code invocation ends with
145"HL" followed by the word:
146	.code test.go /^type Foo/,/^}/ HLxxx
147
148The .code function may take one or more flags immediately preceding
149the filename. This command shows test.go in an editable text area:
150	.code -edit test.go
151This command shows test.go with line numbers:
152	.code -numbers test.go
153
154play:
155
156The function "play" is the same as "code" but puts a button
157on the displayed source so the program can be run from the browser.
158Although only the selected text is shown, all the source is included
159in the HTML output so it can be presented to the compiler.
160
161link:
162
163Create a hyperlink. The syntax is 1 or 2 space-separated arguments.
164The first argument is always the HTTP URL.  If there is a second
165argument, it is the text label to display for this link.
166
167	.link http://golang.org golang.org
168
169image:
170
171The template uses the function "image" to inject picture files.
172
173The syntax is simple: 1 or 3 space-separated arguments.
174The first argument is always the file name.
175If there are more arguments, they are the height and width;
176both must be present, or substituted with an underscore.
177Replacing a dimension argument with the underscore parameter
178preserves the aspect ratio of the image when scaling.
179
180	.image images/betsy.jpg 100 200
181
182	.image images/janet.jpg _ 300
183
184video:
185
186The template uses the function "video" to inject video files.
187
188The syntax is simple: 2 or 4 space-separated arguments.
189The first argument is always the file name.
190The second argument is always the file content-type.
191If there are more arguments, they are the height and width;
192both must be present, or substituted with an underscore.
193Replacing a dimension argument with the underscore parameter
194preserves the aspect ratio of the video when scaling.
195
196	.video videos/evangeline.mp4 video/mp4 400 600
197
198	.video videos/mabel.ogg video/ogg 500 _
199
200background:
201
202The template uses the function "background" to set the background image for
203a slide.  The only argument is the file name of the image.
204
205	.background images/susan.jpg
206
207caption:
208
209The template uses the function "caption" to inject figure captions.
210
211The text after ".caption" is embedded in a figcaption element after
212processing styling and links as in standard text lines.
213
214	.caption _Gopher_ by [[http://www.reneefrench.com][Renée French]]
215
216iframe:
217
218The function "iframe" injects iframes (pages inside pages).
219Its syntax is the same as that of image.
220
221html:
222
223The function html includes the contents of the specified file as
224unescaped HTML. This is useful for including custom HTML elements
225that cannot be created using only the slide format.
226It is your responsibility to make sure the included HTML is valid and safe.
227
228	.html file.html
229
230Presenter notes:
231
232Presenter notes may be enabled by appending the "-notes" flag when you run
233your "present" binary.
234
235This will allow you to open a second window by pressing 'N' from your browser
236displaying your slides. The second window is completely synced with your main
237window, except that presenter notes are only visible on the second window.
238
239Lines that begin with ": " are treated as presenter notes.
240
241	* Title of slide
242
243	Some Text
244
245	: Presenter notes (first paragraph)
246	: Presenter notes (subsequent paragraph(s))
247
248Notes may appear anywhere within the slide text. For example:
249
250	* Title of slide
251
252	: Presenter notes (first paragraph)
253
254	Some Text
255
256	: Presenter notes (subsequent paragraph(s))
257
258This has the same result as the example above.
259
260*/
261package present // import "golang.org/x/tools/present"
262