| // 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 either explicit labels |
| or the URL itself as the label. For example: |
| |
| [[url][label]] |
| [[url]] |
| |
| # 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" |