present

Documentation

Overview

The present file format

Present files have the following format. The first non-blank non-comment line is the title, so the header looks like

Title of document
Subtitle of document
15:04 2 Jan 2006
Tags: foo, bar, baz
<blank line>
Author Name
Job title, Company
joe@example.com
http://url/
@twitter_name

The subtitle, date, and tags lines are optional.

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 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.

Multiple presenters may be specified, separated by a blank line.

After that come slides/sections, each after a blank line:

• Title of slide or section (must have asterisk)

  Some Text

  ** Subsection

• bullets

• more bullets

• a bullet with

  *** Sub-subsection

  Some More text

  Preformatted text is indented (however you like)

  Further Text, including invocations like:

  .code x.go /^func main/,/^}/ .play y.go .image image.jpg .iframe http://foo .link http://foo label .html file.html .caption _Gopher_ by [[http://www.reneefrench.com][Renée French]]

  Again, more text

Blank lines are OK (not mandatory) after the title and after the text. Text, bullets, and .code etc. are all optional; title is not.

Lines starting with # in column 1 are commentary.

Fonts:

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). Unmatched markers appear as plain text. Within marked text, a single marker character becomes a space and a doubled single marker quotes the marker character.

_italic_
*bold*
`program`
_this_is_all_italic_
_Why_use_scoped__ptr_? Use plain ***ptr* instead.

Inline links:

Links can be included in any text with the form [url[label]], or [url] to use the URL itself as the label.

Functions:

A number of template functions 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 like this.)

Here follows a description of the functions:

mega:

Load a minimega script:

.mega foo.mm

You can specify an optional integer height for the mega script, in case it's too large to render:

.mega foo.mm 300

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 http://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

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 [[http://www.reneefrench.com][Renée 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 responsibilty to make sure the included HTML is valid and safe.

.html file.html

Index

• Variables
• func Register(name string, parser ParseFunc)
• func Style(s string) template.HTML
• func Template() *template.Template
• type Author
  • func (p *Author) TextElem() (elems []Elem)
• type Caption
  • func (c Caption) TemplateName() string
• type Context
  • func (ctx *Context) Parse(r io.Reader, name string, mode ParseMode) (*Doc, error)
• type Doc
  • func Parse(r io.Reader, name string, mode ParseMode) (*Doc, error)
  • func (d *Doc) Render(w io.Writer, t *template.Template) error
• type Elem
• type HTML
  • func (s HTML) TemplateName() string
• type Iframe
  • func (i Iframe) TemplateName() string
• type Image
  • func (i Image) TemplateName() string
• type Lines
• type Link
  • func (l Link) TemplateName() string
• type List
  • func (l List) TemplateName() string
• type ParseFunc
• type ParseMode
• type Section
  • func (s Section) FormattedNumber() string
  • func (s Section) Level() int
  • func (s *Section) Render(w io.Writer, t *template.Template) error
  • func (s Section) Sections() (sections []Section)
  • func (s Section) TemplateName() string
• type Text
  • func (t Text) TemplateName() string

Examples

• Style

Variables

var (
	PlayEnabled = false
)

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 {
	Text string
}

func (Caption) TemplateName

func (c Caption) 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
	Time     time.Time
	Authors  []Author
	Sections []Section
	Tags     []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 {
	template.HTML
}

func (HTML) TemplateName

func (s HTML) TemplateName() string

type Iframe

type Iframe struct {
	URL    string
	Width  int
	Height int
}

func (Iframe) TemplateName

func (i Iframe) TemplateName() string

type Image

type Image struct {
	URL    string
	Width  int
	Height int
}

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

type Link struct {
	URL   *url.URL
	Label string
}

func (Link) TemplateName

func (l Link) TemplateName() string

type List

type List struct {
	Bullet []string
	Nested bool
}

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
	Elem   []Elem
}

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) 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)

func (Section) TemplateName

func (s Section) TemplateName() string

type Text

type Text struct {
	Lines []string
	Pre   bool
}

Text represents an optionally preformatted paragraph.

func (Text) TemplateName

func (t Text) TemplateName() string