present

package
v0.0.0-...-3c20124 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 28, 2023 License: BSD-3-Clause Imports: 21 Imported by: 0

Documentation

Overview

Package present implements parsing and rendering of present files, which can be slide presentations as in github.com/Deng-Xian-Sheng/goplus-lsp/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))

Index

Examples

Constants

This section is empty.

Variables

View Source 
var NotesEnabled = false

NotesEnabled specifies whether presenter notes should be displayed in the present user interface.

View Source 
var PlayEnabled = false

PlayEnabled specifies whether runnable playground snippets should be displayed in the present user interface.

Functions

func Register 

func Register(name string, parser ParseFunc)

Register binds the named action, which does not begin with a period, to the specified parser to be invoked when the name, with a period, appears in the present input text.

func Style 

func Style(s string) template.HTML

Style returns s with HTML entities escaped and font indicators turned into HTML font tags.

Example 
const s = "*Gophers* are _clearly_ > *cats*!"
fmt.Println(Style(s))

Output:

<b>Gophers</b> are <i>clearly</i> &gt; <b>cats</b>!

func Template 

func Template() *template.Template

Template returns an empty template with the action functions in its FuncMap.

Types

type Author 

type Author struct {
	Elem []Elem
}

Author represents the person who wrote and/or is presenting the document.

func (*Author) TextElem 

func (p *Author) TextElem() (elems []Elem)

TextElem returns the first text elements of the author details. This is used to display the author' name, job title, and company without the contact details.

type Caption 

type Caption struct {
	Cmd  string // original command from present source
	Text string
}

func (Caption) PresentCmd 

func (c Caption) PresentCmd() string

func (Caption) TemplateName 

func (c Caption) TemplateName() string

type Code 

type Code struct {
	Cmd      string // original command from present source
	Text     template.HTML
	Play     bool   // runnable code
	Edit     bool   // editable code
	FileName string // file name
	Ext      string // file extension
	Raw      []byte // content of the file
}

func (Code) PresentCmd 

func (c Code) PresentCmd() string

func (Code) TemplateName 

func (c Code) TemplateName() string

type Context 

type Context struct {
	// ReadFile reads the file named by filename and returns the contents.
	ReadFile func(filename string) ([]byte, error)
}

A Context specifies the supporting context for parsing a presentation.

func (*Context) Parse 

func (ctx *Context) Parse(r io.Reader, name string, mode ParseMode) (*Doc, error)

Parse parses a document from r.

type Doc 

type Doc struct {
	Title      string
	Subtitle   string
	Summary    string
	Time       time.Time
	Authors    []Author
	TitleNotes []string
	Sections   []Section
	Tags       []string
	OldURL     []string
}

Doc represents an entire document.

func Parse 

func Parse(r io.Reader, name string, mode ParseMode) (*Doc, error)

Parse parses a document from r. Parse reads assets used by the presentation from the file system using ioutil.ReadFile.

func (*Doc) Render 

func (d *Doc) Render(w io.Writer, t *template.Template) error

Render renders the doc to the given writer using the provided template.

type Elem 

type Elem interface {
	TemplateName() string
}

Elem defines the interface for a present element. That is, something that can provide the name of the template used to render the element.

type HTML 

type HTML struct {
	Cmd string // original command from present source
	template.HTML
}

func (HTML) PresentCmd 

func (s HTML) PresentCmd() string

func (HTML) TemplateName 

func (s HTML) TemplateName() string

type Iframe 

type Iframe struct {
	Cmd    string // original command from present source
	URL    string
	Width  int
	Height int
}

func (Iframe) PresentCmd 

func (i Iframe) PresentCmd() string

func (Iframe) TemplateName 

func (i Iframe) TemplateName() string

type Image 

type Image struct {
	Cmd    string // original command from present source
	URL    string
	Width  int
	Height int
}

func (Image) PresentCmd 

func (i Image) PresentCmd() string

func (Image) TemplateName 

func (i Image) TemplateName() string

type Lines 

type Lines struct {
	// contains filtered or unexported fields
}

Lines is a helper for parsing line-based input. 

type Link struct {
	Cmd   string // original command from present source
	URL   *url.URL
	Label string
}

func (Link) PresentCmd 

func (l Link) PresentCmd() string

func (Link) TemplateName 

func (l Link) TemplateName() string

type List 

type List struct {
	Bullet []string
}

List represents a bulleted list.

func (List) TemplateName 

func (l List) TemplateName() string

type ParseFunc 

type ParseFunc func(ctx *Context, fileName string, lineNumber int, inputLine string) (Elem, error)

type ParseMode 

type ParseMode int

ParseMode represents flags for the Parse function. 

const (
	// If set, parse only the title and subtitle.
	TitlesOnly ParseMode = 1
)

type Section 

type Section struct {
	Number  []int
	Title   string
	ID      string // HTML anchor ID
	Elem    []Elem
	Notes   []string
	Classes []string
	Styles  []string
}

Section represents a section of a document (such as a presentation slide) comprising a title and a list of elements.

func (Section) FormattedNumber 

func (s Section) FormattedNumber() string

FormattedNumber returns a string containing the concatenation of the numbers identifying a Section.

func (Section) HTMLAttributes 

func (s Section) HTMLAttributes() template.HTMLAttr

HTMLAttributes for the section

func (Section) Level 

func (s Section) Level() int

Level returns the level of the given section. The document title is level 1, main section 2, etc.

func (*Section) Render 

func (s *Section) Render(w io.Writer, t *template.Template) error

Render renders the section to the given writer using the provided template.

func (Section) Sections 

func (s Section) Sections() (sections []Section)

Sections contained within the section.

func (Section) TemplateName 

func (s Section) TemplateName() string

type Text 

type Text struct {
	Lines []string
	Pre   bool
	Raw   string // original text, for Pre==true
}

Text represents an optionally preformatted paragraph.

func (Text) TemplateName 

func (t Text) TemplateName() string

type Video 

type Video struct {
	Cmd        string // original command from present source
	URL        string
	SourceType string
	Width      int
	Height     int
}

func (Video) PresentCmd 

func (v Video) PresentCmd() string

func (Video) TemplateName 

func (v Video) TemplateName() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.