frundis

Documentation

Index

• func BeginPhrasingMacroInParagraph(exp Exporter, nospace bool)
• func DefaultExporterMacros() map[string]func(Exporter)
• func EnglishTypography(exp Exporter, text []ast.Inline) []ast.Inline
• func FrenchTypography(exp Exporter, text []ast.Inline) []ast.Inline
• func IsTrue(s string) bool
• func MinimalExporterMacros() map[string]func(Exporter)
• func ProcessFrundisSource(exp Exporter, filename string) error
• func SearchIncFile(exp Exporter, filename string) (string, bool)
• type BaseExporter
• type Context
  • func NewContext(format string) *Context
  • func (ctx *Context) Error(msgs ...interface{})
  • func (ctx *Context) Errorf(format string, msgs ...interface{})
  • func (ctx *Context) InlinesToText(elts []ast.Inline) string
  • func (ctx *Context) ParseOptions(spec map[string]Option, args [][]ast.Inline) (map[string][]ast.Inline, map[string]bool, [][]ast.Inline)
  • func (ctx *Context) Reset()
  • func (ctx *Context) W() io.Writer
• type Dtag
• type Exporter
• type Ftag
• type IDInfo
• type IDType
• type LoXinfo
• type Mtag
• type Option
• type ParagraphBreak
• type Renderer
• type TableData
• type TableInfo
• type TocInfo
  • func (t *TocInfo) HeaderLevel(macro string) int
  • func (t *TocInfo) HeaderNum(macro string, nonum bool) (num string)
  • func (t *TocInfo) NavCount() int
• type VerseInfo

Functions

func BeginPhrasingMacroInParagraph

func BeginPhrasingMacroInParagraph(exp Exporter, nospace bool)

BeginPhrasingMacroInParagraph is a function for default use with the method of same name of Exporter interface, which works for inline markup in most output formats.

func DefaultExporterMacros

func DefaultExporterMacros() map[string]func(Exporter)

DefaultExporterMacros returns a mapping from macros to handling functions, with the standard set of frundis macros.

func EnglishTypography

func EnglishTypography(exp Exporter, text []ast.Inline) []ast.Inline

EnglishTypography replaces apostrophes with typographic ones.

func FrenchTypography

func FrenchTypography(exp Exporter, text []ast.Inline) []ast.Inline

FrenchTypography inserts non-breaking spaces following french punctuation rules, as well as replacing apostrophes with typographic ones.

func IsTrue

func IsTrue(s string) bool

IsTrue returns true unless string is empty or "0".

func MinimalExporterMacros

func MinimalExporterMacros() map[string]func(Exporter)

MinimalExporterMacros returns a mapping from macros to handling functions, with only the following macros: Bd, Bf, Bm, Ed, Ef, Em, Ft, If, Sm, X.

func ProcessFrundisSource

func ProcessFrundisSource(exp Exporter, filename string) error

ProcessFrundisSource processes a frundis file with a given exporter.

func SearchIncFile

func SearchIncFile(exp Exporter, filename string) (string, bool)

SearchIncFile returns the path to filename relative to the current directory or the FRUNDISLIB environnment variable, and boolean true if such a file exists. Otherwise it returns a false boolean.

Types

type BaseExporter

type BaseExporter interface {
	// Context returns processing context. It can be used to set some
	// configure options.
	Context() *Context
	// Reset resets temporary data (for use between info and process
	// phases), and initializes output writer for output phase.
	Reset() error
	// PostProcessing does some final processing, and flushes any buffered
	// output data.
	PostProcessing()
}

BaseExporter is a basic interface with essential Exporter methods.

type Context

type Context struct {
	Args         [][]ast.Inline                 // current macro args
	Dtags        map[string]Dtag                // display block tags set with "X dtag"
	FigCount     int                            // current figure number
	Filters      map[string]func(string) string // function filters (for Ft and Bf)
	Format       string                         // export format name (set by NewContext)
	FS           fs.FS                          // (optional) filesystem for frundis source
	Ftags        map[string]Ftag                // filter tags set with "X ftag"
	ID           string                         // current part/chapter id (if any)
	IDX          string                         // current header id
	IDs          map[string]IDInfo              // id information
	Images       []string                       // list of image paths
	Inline       bool                           // inline processing of Sm-like macros (e.g. in header)
	LoXstack     map[string][]*LoXinfo          // (list-type => information list) map
	Macro        string                         // current macro
	Macros       map[string]func(Exporter)      // frundis macro handlers
	Mtags        map[string]Mtag                // markup tags set with "X mtag"
	OutputPhase  bool                           // whether in info pass or output phase (after Reset)
	Params       map[string]string              // parameters set with "X set"
	PrevMacro    string                         // previous non-user macro called, or "" for text-block
	Table        TableInfo                      // current table information
	Tables       []*TableData                   // some non-LoX information about tables (e.g. number of columns)
	Toc          *TocInfo                       // Toc information
	Unrestricted bool                           // unrestricted mode (#run and shell filters allowed)
	Vars         map[string]string              // interpolation variables
	Verse        VerseInfo                      // poem information
	WantsSpace   bool                           // whether previous in-paragraph stuff reclaims a space
	Wout         io.Writer                      // where final output goes (set first by Exporter in Reset)
	// contains filtered or unexported fields
}

Context gathers main context information for Exporter. Most fields should not be modified and used only when writing an Exporter for a new format.

The Filters field can be used to add new custom filters; FS can be used to use a custom filesystem for searching source files; Unrestricted can be set to allow #run and -shell filters.

func NewContext

func NewContext(format string) *Context

NewContext returns a new initialized Context for writing output to an io.Writer in the given format.

func (*Context) Error

func (ctx *Context) Error(msgs ...interface{})

Error logs msgs with some additional context information.

func (*Context) Errorf

func (ctx *Context) Errorf(format string, msgs ...interface{})

Errorf logs formatted msgs with some additional context information.

func (*Context) InlinesToText

func (ctx *Context) InlinesToText(elts []ast.Inline) string

InlinesToText stringifies a slice of inline elements, performing variable interpolation and simple escaping rules.

func (*Context) ParseOptions

func (ctx *Context) ParseOptions(
	spec map[string]Option, args [][]ast.Inline) (
	map[string][]ast.Inline, map[string]bool, [][]ast.Inline)

ParseOptions takes a specification spec of options and a arguments slice args and returns a mapping from option names to values, a mapping for flags and an updated arguments slice.

func (*Context) Reset

func (ctx *Context) Reset()

Reset resets a context, preserving only immutable information from first pass.

func (*Context) W

func (ctx *Context) W() io.Writer

W returns a writer to be used in macro methods. It should be used in place of ctx.Wout, because it may write paragraph text to a buffer instead.

type Dtag

type Dtag struct {
	Cmd   string   // "-c" option of "X dtag"
	Pairs []string // "-a" option of "X dtag" (list of pairs key=value)
}

Dtag represents tags set with "X dtag".

type Exporter

type Exporter interface {
	BaseExporter
	Renderer
	// Xdtag builds a Dtag (e.g. frundis.Dtag{Cmd: cmd}).
	Xdtag(cmd string, pairs []string) Dtag
	// Xmtag builds a Mtag. The begin and end arguments are unescaped and
	// may require processing. The cmd argument can benefit from checks.
	// pairs is a list of even length of key=value pairs.
	Xmtag(cmd *string, begin string, end string, pairs []string) Mtag
}

Exporter is the interface that should satisfy any exporter for the frundis input format.

type Ftag

type Ftag struct {
	Shell string // "-shell" option of "X ftag"
}

Ftag represents tags set with "X ftag".

type IDInfo

type IDInfo struct {
	Ref  string
	Name string
	Type IDType
}

IDInfo gathers identifier information.

type IDType

type IDType int

IDType corresponds to different elements that can have an identifier.

const (
	NoID IDType = iota
	SmID
	BdID
	InlineImID
	FigureID
	HeaderID
	PoemID
	TableID
	UntitledList
)

Types of elements having an identifier

type LoXinfo

type LoXinfo struct {
	Count     int    // entry occurrence count
	Macro     string // macro inducing info entry (e.g. "Ch", etc.)
	Nonum     bool   // whether entry should be numbered
	Num       string // formatted string representing entry number
	Ref       string // reference (e.g. in an "href")
	RefPrefix string // reference prefix (e.g. "fig" for figures)
	Title     string // title (rendered)
	ID        string // id for ctx.IDs
}

LoXinfo gathers misc information for cross-references and TOC-like stuff.

type Mtag

type Mtag struct {
	Begin string   // "-b" option of "X mtag"
	Cmd   string   // "-c" option of "X mtag"
	End   string   // "-e" option of "X mtag"
	Pairs []string // "-a" option of "X mtag" (list of pairs key=value)
}

Mtag represents tags set with "X mtag".

type Option

type Option int

Option represents the type of option (flag or with argument).

const (
	FlagOption Option = iota // boolean flag
	ArgOption                // option with argument
)

Option types

type ParagraphBreak

type ParagraphBreak int

ParagraphBreak represents different kinds of paragraph breaks.

const (
	ParBreakNormal ParagraphBreak = iota
	ParBreakBlock
	ParBreakItem
	ParBreakForced
)

Those constants represent different kinds of paragraphs breaks: normal ones, soft ones next to blocks boundaries, as well as paragraph breaks in lists and tables before new items.

type Renderer

type Renderer interface {
	// BeginDescList starts a description list (e.g. prints to Context.W a "<dl>").
	BeginDescList(id string)
	// BeginDescValue starts a description value (e.g. "<dd>").
	BeginDescValue()
	// BeginDialogue starts a dialogue (e.g. a "—").
	BeginDialogue()
	// BeginDisplayBlock starts a display block with given tag and id.
	BeginDisplayBlock(tag string, id string)
	// BeginEnumItem starts a list numbered item (e.g. "<li>").
	BeginEnumItem()
	// BeginEnumList starts an enumeration list (e.g. "<ol>").
	BeginEnumList(id string)
	// BeginHeader handles beginning of a specific header macro (name), and
	// a given title (e.g. prints <h1 class="Ch" id="3">). It can also be
	// used as a hook for more complex things (such as writing new chapters
	// to a new file).
	BeginHeader(macro string, numbered bool, title string)
	// BeginItem starts a list item (e.g. "<li>").
	BeginItem()
	// BeginItem starts an item list (e.g. "<ul>").
	BeginItemList(id string)
	// BeginMarkupBlock starts markup with given tag and id (e.g. "<" +
	// mtag.Cmd + " id=\"" + id + "\">" + mtag.Begin, where mtag is the
	// Context.Mtag corresponding to tag).
	BeginMarkupBlock(tag string, id string)
	// BeginParagraph starts a paragraph (e.g. "<p>")
	BeginParagraph()
	// BeginPhrasingMacroinParagraph introduces a phrasing macro within a
	// paragraph (often adding a newline or space)
	BeginPhrasingMacroInParagraph(nospace bool)
	// BeginTable starts a table (e.g. "<table>"). The table can have an
	// optional title, and count is the table number.
	BeginTable(tableinfo *TableData)
	// BeginTableCell starts a new cell (e.g. "<td>").
	BeginTableCell()
	// BeginTableRow starts a new row (e.g. "<tr>").
	BeginTableRow()
	// BeginVerse starts a poem.
	BeginVerse(title string, id string)
	// BeginVerseLine begins a poem line.
	BeginVerseLine()
	// CheckParamAssignement checks parameter assignement.
	CheckParamAssignement(param string, value string) bool
	// Crossreference builds a reference link. It can have an explicit id
	// from Context.IDs, or it can correspond to a loXentry.
	CrossReference(idf IDInfo, punct string)
	// DescName generates a description list item name (e.g. "<dt>" + name
	// + "</dt>")
	DescName(name string)
	// EndDescList ends a description list (e.g. "</dl>")
	EndDescList()
	// EndDescValue ends a description list item value (e.g. "</dd>").
	EndDescValue()
	// EndDisplayBlock ends a display block with a given tag (e.g. "</div>"
	// or "</" + Dtag.Cmd + ">").
	EndDisplayBlock(tag string)
	// EndEnumItem ends a enumeration list value (e.g. "</li>").
	EndEnumItem()
	// EndEnumList ends an enumeration list (e.g. "</ol>").
	EndEnumList()
	// EndHeader ends a header (e.g. "</h1>") of level given by macro, with
	// some title, numbered or not.
	EndHeader(macro string, numbered bool, title string)
	// EndItem ends an item list value. As with EndEnumValue.
	EndItem()
	// EndItemList ends an item list (e.g. "</ul>").
	EndItemList()
	// EndMarkupBlock ends a markup block (e.g. "</em>").
	EndMarkupBlock(tag string, id string, punct string)
	// EndParagraph ends a paragraph (e.g. "</p>").
	EndParagraph(ParagraphBreak)
	// EndStanza ends a stanza.
	EndStanza()
	// EndTable ends a table (e.g. "</table>").
	EndTable(*TableData)
	// EndTableCell ends a table cell (e.g. "</td>").
	EndTableCell()
	// EndTableRow ends a table row (e.g. "</tr>").
	EndTableRow()
	// EndVerse ends a poem (e.g. \end{verse}).
	EndVerse()
	// EndVerseLine ends a poem line (e.g. "<br />\n").
	EndVerseLine()
	// FormatParagraph can be used to do post-processing of paragraph-like text.
	FormatParagraph(text []byte) []byte
	// FigureImage handles an image with a caption; image argument is
	// not escaped. The image can be embedded in a link. The alt argument
	// provides alternate text for use in exporters when it makes sense.
	FigureImage(image string, caption string, link string, alt string)
	// GenRef generates a suitable reference string using a prefix and an
	// id.
	GenRef(prefix string, id string, hasfile bool) string
	// HeaderReference returns a reference string for a header macro (e.g.
	// an html href suitable for pointing to some id of an <h1
	// id="some-id">)
	HeaderReference(macro string) string
	// InlineImage handles an inline image. The alt argument
	// provides alternate text for use in exporters when it makes sense.
	InlineImage(image string, link string, id string, punct string, alt string)
	// LkWithLabel produces a labeled link (e.g. "<a href="url">label</a>").
	LkWithLabel(url string, label string, punct string)
	// LkWithoutLabel produces a link (e.g. "<a href="url">url</a>").
	LkWithoutLabel(url string, punct string)
	// ParagraphTitle starts a titled paragraph (e.g. "<p><strong>title</strong>\n").
	ParagraphTitle(title string)
	// RenderText renders regular inline text, processing escapes
	// secuences, and performing format specific escapes (e.g. "&amp;" and
	// the like) as necessary, and other processings.
	RenderText([]ast.Inline) string
	// Tableofcontents produces a table of content (it can be just
	// \tableofcontents in LaTeX, or more complicated stuff in html).
	TableOfContents(opts map[string][]ast.Inline, flags map[string]bool)
	// TableOfContentsInfos can be used to collect some additional
	// information from a header macro (e.g. the presence of a minitoc in
	// LaTeX, to add necessary packages as necessary)
	TableOfContentsInfos(flags map[string]bool)
}

Renderer is an interface regrouping rendering methods common to all exporters.

type TableData

type TableData struct {
	Title string // title of the table (empty if no title)
	Cols  int    // number of columns
	ID    string // label from "-id label"
}

TableData contains some table data.

type TableInfo

type TableInfo struct {
	Cell     int // current table cell
	Count    int // current table number (with or without title)
	TitCount int // current titled table number
	// contains filtered or unexported fields
}

TableInfo contains table information.

type TocInfo

type TocInfo struct {
	HasPart         bool
	HasChapter      bool
	HeaderCount     int
	PartCount       int
	ChapterCount    int
	SectionCount    int
	SubsectionCount int
	PartNum         int
	ChapterNum      int
	SectionNum      int
	SubsectionNum   int
}

TocInfo gathers information about headers.

func (*TocInfo) HeaderLevel

func (t *TocInfo) HeaderLevel(macro string) int

HeaderLevel returns the level of the header. Natural order between part, chapter, section and subsection is preserved. Level starts at 1 (which can be for a part, a chapter or a section, depending on the document).

func (*TocInfo) HeaderNum

func (t *TocInfo) HeaderNum(macro string, nonum bool) (num string)

HeaderNum returns a string representing the number of a given header macro at current place.

func (*TocInfo) NavCount

func (t *TocInfo) NavCount() int

NavCount returns the number of current navigation unit (a file with part or chapter in indexed html).

type VerseInfo

type VerseInfo struct {
	Used bool // whether there is a poem in the source
	// contains filtered or unexported fields
}

VerseInfo gathers verse information.