+++ /dev/null
-// 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.
-
-/*
-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).
-
-File Format
-
-Present files begin with a header giving the title of the document
-and other metadata, which looks like:
-
- # Title of document
- Subtitle of document
- 15:04 2 Jan 2006
- Tags: foo, bar, baz
- Summary: This is a great document you want to read.
- OldURL: former-path-for-this-doc
-
-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.
-
-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.
-
-The summary line gives a short summary used in blog feeds.
-
-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.
-
-Only the title is required;
-the subtitle, date, tags, summary, and old URL lines are optional.
-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.
-For slide presentations, only the plain text lines will be displayed on the
-first slide.
-
-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
- .caption _Gopher_ by [[https://instagram.com/reneefrench][Renee French]]
-
-Other than the commands, the text in a section is interpreted
-either as Markdown or as legacy present markup.
-
-Markdown Syntax
-
-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 ##)
-
- Some Text
-
- ### Subsection {#anchor}
-
- - bullets
- - more bullets
- - a bullet continued
- on the next line
-
- #### 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)
-
- *** Sub-subsection
-
- Some More text
-
- Preformatted text (code block)
- is indented (however you like)
-
- Further Text, including command invocations.
-
- * Section 2: Example formatting
-
- Formatting:
-
- _italic_
- *bold*
- `program`
- Markup—_especially_italic_text_—can easily be overused.
- _Why_use_scoped__ptr_? Use plain ***ptr* instead.
-
- Visit [[https://golang.org][the Go home page]].
-
-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).
-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.
-
-Links can be included in any text with the form [[url][label]], or
-[[url]] to use the URL itself as the label.
-
-Command Invocations
-
-A number of special commands are available through invocations
-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
-
- .play demo.go /^func show/,/^}/
-
-(except that the ".play" must be at the beginning of the line and
-not be indented as in this comment.)
-
-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
- https://plan9.io/sys/doc/sam/sam.html Table II
-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
-will be highlighted in the display. A highlighting mark may have a
-suffix word, such as
- // HLxxx
-Such highlights are enabled only if the code invocation ends with
-"HL" followed by the word:
- .code test.go /^type Foo/,/^}/ HLxxx
-
-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
-
-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.
-
- .link https://golang.org golang.org
-
-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;
-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.
-
- .image images/betsy.jpg 100 200
- .image images/janet.jpg _ 300
-
-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 _
-
-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
-
-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.
-
- .caption _Gopher_ by [[https://instagram.com/reneefrench][Renee French]]
-
-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.
-It is your responsibility to make sure the included HTML is valid and safe.
-
- .html file.html
-
-Presenter Notes
-
-Lines that begin with ": " are treated as presenter notes,
-in both Markdown and legacy present syntax.
-By default, presenter notes are collected but ignored.
-
-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.
-
-Notes may appear anywhere within the slide text. For example:
-
- * Title of slide
-
- Some text.
-
- : Presenter notes (first paragraph)
-
- Some more text.
-
- : Presenter notes (subsequent paragraph(s))
-
-*/
-package present // import "golang.org/x/tools/present"
projects / dotfiles / .git / blobdiff