2013-09-18 18:55:46 -06:00
|
|
|
// Copyright 2011 The Go Authors. All rights reserved.
|
|
|
|
// Use of this source code is governed by a BSD-style
|
|
|
|
// license that can be found in the LICENSE file.
|
|
|
|
|
|
|
|
/*
|
2020-03-09 21:04:59 -06:00
|
|
|
Package present implements parsing and rendering of present files,
|
|
|
|
which can be slide presentations as in golang.org/x/tools/cmd/present
|
|
|
|
or articles as in golang.org/x/blog (the Go blog).
|
2013-09-18 18:55:46 -06:00
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
File Format
|
2013-09-18 18:55:46 -06:00
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
Present files begin with a header giving the title of the document
|
|
|
|
and other metadata, which looks like:
|
|
|
|
|
|
|
|
# Title of document
|
2013-09-18 18:55:46 -06:00
|
|
|
Subtitle of document
|
|
|
|
15:04 2 Jan 2006
|
|
|
|
Tags: foo, bar, baz
|
2020-03-09 21:04:59 -06:00
|
|
|
Summary: This is a great document you want to read.
|
2020-03-15 14:22:23 -06:00
|
|
|
OldURL: former-path-for-this-doc
|
2013-09-18 18:55:46 -06:00
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
The "# " prefix before the title indicates that this is
|
|
|
|
a Markdown-enabled present file: it uses
|
|
|
|
Markdown for text markup in the body of the file.
|
|
|
|
If the "# " prefix is missing, the file uses
|
|
|
|
legacy present markup, described below.
|
2013-09-18 18:55:46 -06:00
|
|
|
|
|
|
|
The date line may be written without a time:
|
|
|
|
2 Jan 2006
|
|
|
|
In this case, the time will be interpreted as 10am UTC on that date.
|
|
|
|
|
|
|
|
The tags line is a comma-separated list of tags that may be used to categorize
|
|
|
|
the document.
|
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
The summary line gives a short summary used in blog feeds.
|
|
|
|
|
2020-03-15 14:22:23 -06:00
|
|
|
The old URL line, which may be repeated, gives an older (perhaps relative) URL
|
|
|
|
for this document.
|
|
|
|
A server might use these to generate appropriate redirects.
|
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
Only the title is required;
|
2020-03-15 14:22:23 -06:00
|
|
|
the subtitle, date, tags, summary, and old URL lines are optional.
|
2020-03-09 21:04:59 -06:00
|
|
|
In Markdown-enabled present, the summary defaults to being empty.
|
|
|
|
In legacy present, the summary defaults to the first paragraph of text.
|
|
|
|
|
|
|
|
After the header come zero or more author blocks, like this:
|
|
|
|
|
|
|
|
Author Name
|
|
|
|
Job title, Company
|
|
|
|
joe@example.com
|
|
|
|
https://url/
|
|
|
|
@twitter_name
|
|
|
|
|
|
|
|
The first line of the author block is conventionally the author name.
|
|
|
|
Otherwise, the author section may contain a mixture of text, twitter names, and links.
|
2013-09-18 18:55:46 -06:00
|
|
|
For slide presentations, only the plain text lines will be displayed on the
|
|
|
|
first slide.
|
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
If multiple author blocks are listed, each new block must be preceded
|
|
|
|
by its own blank line.
|
|
|
|
|
|
|
|
After the author blocks come the presentation slides or article sections,
|
|
|
|
which can in turn have subsections.
|
|
|
|
In Markdown-enabled present files, each slide or section begins with a "##" header line,
|
|
|
|
subsections begin with a "###" header line, and so on.
|
|
|
|
In legacy present files, each slide or section begins with a "*" header line,
|
|
|
|
subsections begin with a "**" header line, and so on.
|
|
|
|
|
|
|
|
In addition to the marked-up text in a section (or subsection),
|
|
|
|
a present file can contain present command invocations, each of which begins
|
|
|
|
with a dot, as in:
|
|
|
|
|
|
|
|
.code x.go /^func main/,/^}/
|
|
|
|
.play y.go
|
|
|
|
.image image.jpg
|
|
|
|
.background image.jpg
|
|
|
|
.iframe https://foo
|
|
|
|
.link https://foo label
|
|
|
|
.html file.html
|
2020-03-29 17:41:33 -06:00
|
|
|
.caption _Gopher_ by [[https://instagram.com/reneefrench][Renee French]]
|
2020-03-09 21:04:59 -06:00
|
|
|
|
|
|
|
Other than the commands, the text in a section is interpreted
|
|
|
|
either as Markdown or as legacy present markup.
|
2013-09-18 18:55:46 -06:00
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
Markdown Syntax
|
2013-09-18 18:55:46 -06:00
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
Markdown typically means the generic name for a family of similar markup languages.
|
|
|
|
The specific variant used in present is CommonMark.
|
|
|
|
See https://commonmark.org/help/tutorial/ for a quick tutorial.
|
|
|
|
|
|
|
|
In Markdown-enabled present,
|
|
|
|
section headings can end in {#name} to set the HTML anchor ID for the heading to "name".
|
|
|
|
|
|
|
|
Lines beginning with "//" (outside of code blocks, of course)
|
|
|
|
are treated as present comments and have no effect.
|
|
|
|
|
|
|
|
Lines beginning with ": " are treated as speaker notes, described below.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
# Title of Talk
|
|
|
|
|
|
|
|
My Name
|
|
|
|
9 Mar 2020
|
|
|
|
me@example.com
|
|
|
|
|
|
|
|
## Title of Slide or Section (must begin with ##)
|
2013-09-18 18:55:46 -06:00
|
|
|
|
|
|
|
Some Text
|
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
### Subsection {#anchor}
|
2013-09-18 18:55:46 -06:00
|
|
|
|
|
|
|
- bullets
|
|
|
|
- more bullets
|
2020-03-09 20:15:04 -06:00
|
|
|
- a bullet continued
|
|
|
|
on the next line
|
2013-09-18 18:55:46 -06:00
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
#### Sub-subsection
|
|
|
|
|
|
|
|
Some More text
|
|
|
|
|
|
|
|
Preformatted text (code block)
|
|
|
|
is indented (by one tab, or four spaces)
|
|
|
|
|
|
|
|
Further Text, including command invocations.
|
|
|
|
|
|
|
|
## Section 2: Example formatting {#fmt}
|
|
|
|
|
|
|
|
Formatting:
|
|
|
|
|
|
|
|
_italic_
|
|
|
|
// A comment that is completely ignored.
|
|
|
|
: Speaker notes.
|
|
|
|
**bold**
|
|
|
|
`program`
|
|
|
|
Markup—_especially italic text_—can easily be overused.
|
|
|
|
_Why use scoped\_ptr_? Use plain **\*ptr** instead.
|
|
|
|
|
|
|
|
Visit [the Go home page](https://golang.org/).
|
|
|
|
|
|
|
|
Legacy Present Syntax
|
|
|
|
|
|
|
|
Compared to Markdown,
|
|
|
|
in legacy present
|
|
|
|
slides/sections use "*" instead of "##",
|
|
|
|
whole-line comments begin with "#" instead of "//",
|
|
|
|
bullet lists can only contain single (possibly wrapped) text lines,
|
|
|
|
and the font styling and link syntaxes are subtly different.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
Title of Talk
|
|
|
|
|
|
|
|
My Name
|
|
|
|
1 Jan 2013
|
|
|
|
me@example.com
|
|
|
|
|
|
|
|
* Title of Slide or Section (must begin with *)
|
|
|
|
|
|
|
|
Some Text
|
|
|
|
|
|
|
|
** Subsection
|
|
|
|
|
|
|
|
- bullets
|
|
|
|
- more bullets
|
|
|
|
- a bullet continued
|
|
|
|
on the next line (indented at least one space)
|
|
|
|
|
2013-09-18 18:55:46 -06:00
|
|
|
*** Sub-subsection
|
|
|
|
|
|
|
|
Some More text
|
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
Preformatted text (code block)
|
2013-09-18 18:55:46 -06:00
|
|
|
is indented (however you like)
|
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
Further Text, including command invocations.
|
2013-09-18 18:55:46 -06:00
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
* Section 2: Example formatting
|
2013-09-18 18:55:46 -06:00
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
Formatting:
|
2013-09-18 18:55:46 -06:00
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
_italic_
|
|
|
|
*bold*
|
|
|
|
`program`
|
|
|
|
Markup—_especially_italic_text_—can easily be overused.
|
|
|
|
_Why_use_scoped__ptr_? Use plain ***ptr* instead.
|
2013-09-18 18:55:46 -06:00
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
Visit [[https://golang.org][the Go home page]].
|
2013-09-18 18:55:46 -06:00
|
|
|
|
|
|
|
Within the input for plain text or lists, text bracketed by font
|
|
|
|
markers will be presented in italic, bold, or program font.
|
|
|
|
Marker characters are _ (italic), * (bold) and ` (program font).
|
2016-11-29 11:39:51 -07:00
|
|
|
An opening marker must be preceded by a space or punctuation
|
|
|
|
character or else be at start of a line; similarly, a closing
|
|
|
|
marker must be followed by a space or punctuation character or
|
|
|
|
else be at the end of a line. Unmatched markers appear as plain text.
|
|
|
|
There must be no spaces between markers. Within marked text,
|
|
|
|
a single marker character becomes a space and a doubled single
|
|
|
|
marker quotes the marker character.
|
|
|
|
|
2013-09-18 18:55:46 -06:00
|
|
|
Links can be included in any text with the form [[url][label]], or
|
|
|
|
[[url]] to use the URL itself as the label.
|
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
Command Invocations
|
2013-09-18 18:55:46 -06:00
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
A number of special commands are available through invocations
|
2013-09-18 18:55:46 -06:00
|
|
|
in the input text. Each such invocation contains a period as the
|
|
|
|
first character on the line, followed immediately by the name of
|
|
|
|
the function, followed by any arguments. A typical invocation might
|
|
|
|
be
|
2020-03-09 21:04:59 -06:00
|
|
|
|
2013-09-18 18:55:46 -06:00
|
|
|
.play demo.go /^func show/,/^}/
|
2020-03-09 21:04:59 -06:00
|
|
|
|
2013-09-18 18:55:46 -06:00
|
|
|
(except that the ".play" must be at the beginning of the line and
|
2020-03-09 21:04:59 -06:00
|
|
|
not be indented as in this comment.)
|
2013-09-18 18:55:46 -06:00
|
|
|
|
|
|
|
Here follows a description of the functions:
|
|
|
|
|
|
|
|
code:
|
|
|
|
|
|
|
|
Injects program source into the output by extracting code from files
|
|
|
|
and injecting them as HTML-escaped <pre> blocks. The argument is
|
|
|
|
a file name followed by an optional address that specifies what
|
|
|
|
section of the file to display. The address syntax is similar in
|
|
|
|
its simplest form to that of ed, but comes from sam and is more
|
|
|
|
general. See
|
2017-12-26 12:45:35 -07:00
|
|
|
https://plan9.io/sys/doc/sam/sam.html Table II
|
2013-09-18 18:55:46 -06:00
|
|
|
for full details. The displayed block is always rounded out to a
|
|
|
|
full line at both ends.
|
|
|
|
|
|
|
|
If no pattern is present, the entire file is displayed.
|
|
|
|
|
|
|
|
Any line in the program that ends with the four characters
|
|
|
|
OMIT
|
|
|
|
is deleted from the source before inclusion, making it easy
|
|
|
|
to write things like
|
|
|
|
.code test.go /START OMIT/,/END OMIT/
|
|
|
|
to find snippets like this
|
|
|
|
tedious_code = boring_function()
|
|
|
|
// START OMIT
|
|
|
|
interesting_code = fascinating_function()
|
|
|
|
// END OMIT
|
|
|
|
and see only this:
|
|
|
|
interesting_code = fascinating_function()
|
|
|
|
|
|
|
|
Also, inside the displayed text a line that ends
|
|
|
|
// HL
|
2018-10-19 23:03:24 -06:00
|
|
|
will be highlighted in the display. A highlighting mark may have a
|
|
|
|
suffix word, such as
|
2013-09-18 18:55:46 -06:00
|
|
|
// HLxxx
|
|
|
|
Such highlights are enabled only if the code invocation ends with
|
|
|
|
"HL" followed by the word:
|
|
|
|
.code test.go /^type Foo/,/^}/ HLxxx
|
|
|
|
|
2013-09-26 17:46:08 -06:00
|
|
|
The .code function may take one or more flags immediately preceding
|
|
|
|
the filename. This command shows test.go in an editable text area:
|
|
|
|
.code -edit test.go
|
|
|
|
This command shows test.go with line numbers:
|
|
|
|
.code -numbers test.go
|
|
|
|
|
2013-09-18 18:55:46 -06:00
|
|
|
play:
|
|
|
|
|
|
|
|
The function "play" is the same as "code" but puts a button
|
|
|
|
on the displayed source so the program can be run from the browser.
|
|
|
|
Although only the selected text is shown, all the source is included
|
|
|
|
in the HTML output so it can be presented to the compiler.
|
|
|
|
|
|
|
|
link:
|
|
|
|
|
|
|
|
Create a hyperlink. The syntax is 1 or 2 space-separated arguments.
|
|
|
|
The first argument is always the HTTP URL. If there is a second
|
|
|
|
argument, it is the text label to display for this link.
|
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
.link https://golang.org golang.org
|
2013-09-18 18:55:46 -06:00
|
|
|
|
|
|
|
image:
|
|
|
|
|
|
|
|
The template uses the function "image" to inject picture files.
|
|
|
|
|
|
|
|
The syntax is simple: 1 or 3 space-separated arguments.
|
|
|
|
The first argument is always the file name.
|
|
|
|
If there are more arguments, they are the height and width;
|
2014-06-12 16:45:26 -06:00
|
|
|
both must be present, or substituted with an underscore.
|
|
|
|
Replacing a dimension argument with the underscore parameter
|
|
|
|
preserves the aspect ratio of the image when scaling.
|
2013-09-18 18:55:46 -06:00
|
|
|
|
|
|
|
.image images/betsy.jpg 100 200
|
2014-06-12 16:45:26 -06:00
|
|
|
.image images/janet.jpg _ 300
|
|
|
|
|
2016-01-10 15:03:33 -07:00
|
|
|
video:
|
|
|
|
|
|
|
|
The template uses the function "video" to inject video files.
|
|
|
|
|
|
|
|
The syntax is simple: 2 or 4 space-separated arguments.
|
|
|
|
The first argument is always the file name.
|
|
|
|
The second argument is always the file content-type.
|
|
|
|
If there are more arguments, they are the height and width;
|
|
|
|
both must be present, or substituted with an underscore.
|
|
|
|
Replacing a dimension argument with the underscore parameter
|
|
|
|
preserves the aspect ratio of the video when scaling.
|
|
|
|
|
|
|
|
.video videos/evangeline.mp4 video/mp4 400 600
|
|
|
|
|
|
|
|
.video videos/mabel.ogg video/ogg 500 _
|
|
|
|
|
2016-01-06 17:52:04 -07:00
|
|
|
background:
|
|
|
|
|
|
|
|
The template uses the function "background" to set the background image for
|
|
|
|
a slide. The only argument is the file name of the image.
|
|
|
|
|
|
|
|
.background images/susan.jpg
|
2014-07-15 09:23:16 -06:00
|
|
|
|
|
|
|
caption:
|
|
|
|
|
|
|
|
The template uses the function "caption" to inject figure captions.
|
|
|
|
|
|
|
|
The text after ".caption" is embedded in a figcaption element after
|
|
|
|
processing styling and links as in standard text lines.
|
|
|
|
|
2020-03-29 17:41:33 -06:00
|
|
|
.caption _Gopher_ by [[https://instagram.com/reneefrench][Renee French]]
|
2014-07-15 09:23:16 -06:00
|
|
|
|
2013-09-18 18:55:46 -06:00
|
|
|
iframe:
|
|
|
|
|
|
|
|
The function "iframe" injects iframes (pages inside pages).
|
|
|
|
Its syntax is the same as that of image.
|
|
|
|
|
|
|
|
html:
|
|
|
|
|
|
|
|
The function html includes the contents of the specified file as
|
|
|
|
unescaped HTML. This is useful for including custom HTML elements
|
|
|
|
that cannot be created using only the slide format.
|
2018-08-10 12:13:41 -06:00
|
|
|
It is your responsibility to make sure the included HTML is valid and safe.
|
2013-09-18 18:55:46 -06:00
|
|
|
|
|
|
|
.html file.html
|
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
Presenter Notes
|
2016-04-03 17:39:49 -06:00
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
Lines that begin with ": " are treated as presenter notes,
|
|
|
|
in both Markdown and legacy present syntax.
|
|
|
|
By default, presenter notes are collected but ignored.
|
2016-04-03 17:39:49 -06:00
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
When running the present command with -notes,
|
|
|
|
typing 'N' in your browser displaying your slides
|
|
|
|
will create a second window displaying the notes.
|
|
|
|
The second window is completely synced with the main
|
|
|
|
window, except that presenter notes are only visible in the second window.
|
2016-04-03 17:39:49 -06:00
|
|
|
|
|
|
|
Notes may appear anywhere within the slide text. For example:
|
|
|
|
|
|
|
|
* Title of slide
|
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
Some text.
|
|
|
|
|
2016-04-03 17:39:49 -06:00
|
|
|
: Presenter notes (first paragraph)
|
|
|
|
|
2020-03-09 21:04:59 -06:00
|
|
|
Some more text.
|
2016-04-03 17:39:49 -06:00
|
|
|
|
|
|
|
: Presenter notes (subsequent paragraph(s))
|
|
|
|
|
2013-09-18 18:55:46 -06:00
|
|
|
*/
|
2014-12-08 21:00:58 -07:00
|
|
|
package present // import "golang.org/x/tools/present"
|