Documentation ¶
Overview ¶
Package khipu is about encoding text into typesetting items.
"Khipu were recording devices fashioned from strings historically used by a number of cultures in the region of Andean South America. Khipu is the word for "knot" in Cusco Quechua. A khipu usually consisted of cotton or camelid fiber strings. The Inca people used them for collecting data and keeping records, monitoring tax obligations, properly collecting census records, calendrical information, and for military organization. The cords stored numeric and other values encoded as knots, often in a base ten positional system. A khipu could have only a few or thousands of cords." ––Excerpt from a Wikipedia article about khipus
The Khipukamayuqs (Quechua for “knot-makers”) were the scribes of those times, tasked with encoding tax figures and other administrative information in knots. We will use this analogy to call typesetting items "khipus" or "knots", and objects which produce khipus will be "Khipukamayuqs". Knots implement items for typesetting paragraphs. We will use a box-and-glue model, the various knot types more or less implementing the corresponding node types from the TeX typesetting system.
A Khipukamayuqs is part of a typsetting pipeline and will transform text into khipus. Khipus are the input for linebreakers. The overall process of creating them and the interaction with line breaking looks like this:
Create Khipus from Text ¶
(1) Normalize Unicode text
https://godoc.org/golang.org/x/text/unicode/norm
(2) Find natural text wrap opportunities (words in many scripts, syllables/character in East Asia, etc.)
https://godoc.org/github.com/npillmayer/gotype/core/uax
(3) Bi-directional text
https://godoc.org/golang.org/x/text/unicode/bidi https://www.w3.org/International/articles/inline-bidi-markup/
(4) Hyphenation: Lliang patterns + language-specific code
https://godoc.org/github.com/npillmayer/gotype/core/hyphenation
(5) Translate feasible breakpoints to penalties, glue and discretionaries
https://wiki.apache.org/xmlgraphics-fop/KnuthsModel
(6) Shape text -> Glyphs + alternative glyphs (end-of-line condensed in Arabic, etc.)
http://behdad.org/text/
At this point, text has been fully converted to khipus.
BSD License ¶
Copyright (c) 2017–20, Norbert Pillmayer ¶
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of this software nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Index ¶
- Constants
- func CT() tracing.Trace
- func HyphenateTextBoxes(khipu *Khipu, pipeline *TypesettingPipeline, regs *params.TypesettingRegisters)
- func HyphenateWord(word string, regs *params.TypesettingRegisters) ([]string, bool)
- func KnotString(k Knot) string
- type Cursor
- func (c Cursor) AsDiscretionary() *Discretionary
- func (c Cursor) AsGlue() Glue
- func (c Cursor) AsKern() Kern
- func (c Cursor) AsPenalty() Penalty
- func (c Cursor) AsTextBox() *TextBox
- func (c Cursor) IsValidPosition() bool
- func (c *Cursor) Khipu() *Khipu
- func (c *Cursor) Knot() Knot
- func (c *Cursor) Mark() Mark
- func (c *Cursor) Next() bool
- func (c *Cursor) Peek() (Knot, bool)
- func (c *Cursor) Position() int
- func (c *Cursor) Prev() bool
- func (c Cursor) ReplaceKnot(knot Knot) Knot
- func (c Cursor) String() string
- type Discretionary
- type Glue
- type Kern
- type Khipu
- func (kh *Khipu) AppendKhipu(k *Khipu) *Khipu
- func (kh *Khipu) AppendKnot(knot Knot) *Khipu
- func (kh *Khipu) Length() int
- func (kh *Khipu) MaxHeightAndDepth(from, to int) (dimen.Dimen, dimen.Dimen)
- func (kh *Khipu) MaxWidth(from, to int) dimen.Dimen
- func (kh *Khipu) Measure(from, to int) (dimen.Dimen, dimen.Dimen, dimen.Dimen)
- func (kh *Khipu) Reach(start int, distance dimen.Dimen) (int, int)
- func (kh *Khipu) ReplaceKnot(inx int, knot Knot) Knot
- func (kh *Khipu) String() string
- func (kh *Khipu) Text(from, to int) string
- type Knot
- type KnotType
- type Mark
- type Penalty
- type TextBox
- type TypesettingPipeline
Constants ¶
const ( HList int = iota // horizontal list VList // vertical list MList // math list )
List types
Variables ¶
This section is empty.
Functions ¶
func HyphenateTextBoxes ¶
func HyphenateTextBoxes(khipu *Khipu, pipeline *TypesettingPipeline, regs *params.TypesettingRegisters)
HyphenateTextBoxes hypenates all the words in a khipu. Words are contained inside TextBox knots.
Hyphenation is governed by the typesetting registers provided. If regs is nil, no hyphenation is done.
func HyphenateWord ¶
func HyphenateWord(word string, regs *params.TypesettingRegisters) ([]string, bool)
HyphenateWord hyphenates a single word.
func KnotString ¶
KnotString is a debugging helper and returns a textual representation of a knot.
Types ¶
type Cursor ¶
type Cursor struct {
// contains filtered or unexported fields
}
A Cursor navigates over the knots of a khipu
func NewCursor ¶
NewCursor creates a cursor for a given khipu. Usage is unsafe if the referenced khipu changes during lifetime of the cursor.
func (Cursor) AsDiscretionary ¶
func (c Cursor) AsDiscretionary() *Discretionary
AsDiscretionary returns the current knot as a discretionary item.
func (Cursor) IsValidPosition ¶
IsValidPosition returns true, if the cursor is located at a a valid position, false otherwise.
func (*Cursor) Khipu ¶
Khipu returns the underlying khipu. Clients should not modify it, except with the methods of the cursor. Different cursors should not modify the same khipu. Modifying a khipu may render previously returned marks invalid.
func (*Cursor) Next ¶
Next moves the cursor one knot ahead. Returns true if the cursor is still at a valid position, false otherwise.
func (*Cursor) Peek ¶
Peek is lookahead 1. Does not advance the cursor. Returns true if the lookahead is at a valid position, false otherwise.
func (*Cursor) Prev ¶
Prev moves the cursor one knot back. Returns true if the cursor is still at a valid position, false otherwise.
func (Cursor) ReplaceKnot ¶
ReplaceKnot replaces the knot under the cursor, if any. It it returns the current knot.
type Discretionary ¶
A Discretionary is a hyphenation opportunity
func (Discretionary) IsDiscardable ¶
func (d Discretionary) IsDiscardable() bool
IsDiscardable is part of interface Knot. Discretionaries are not discardable.
func (Discretionary) MaxW ¶
func (d Discretionary) MaxW() dimen.Dimen
MaxW is part of interface Knot. Returns the width of the post-hyphen text.
func (Discretionary) MinW ¶
func (d Discretionary) MinW() dimen.Dimen
MinW is part of interface Knot. Returns the width of the pre-hyphen text.
func (Discretionary) W ¶
func (d Discretionary) W() dimen.Dimen
W is part of interface Knot. Returns the width of the un-hyphenated text.
type Glue ¶
A Glue is a space which can shrink and expand
func (Glue) IsDiscardable ¶
IsDiscardable is part of interface Knot. Glue is discardable.
type Kern ¶
A Kern is an unshrinkable space
func (Kern) IsDiscardable ¶
IsDiscardable is part of interface Knot. Kerns are discardable.
type Khipu ¶
type Khipu struct {
// contains filtered or unexported fields
}
Khipu is a string of knots. We handle text/paragraphs as khipus.
func KnotEncode ¶
func KnotEncode(text io.Reader, pipeline *TypesettingPipeline, regs *params.TypesettingRegisters) *Khipu
KnotEncode transforms an input text into a khipu.
func (*Khipu) AppendKhipu ¶
AppendKhipu concatenates two khipus.
func (*Khipu) AppendKnot ¶
AppendKnot appends a knot at the end of the list.
func (*Khipu) MaxHeightAndDepth ¶
MaxHeightAndDepth finds the maximum height and depth of the knots in the range [from ... to-1]. Only knots of type TextBox are considered.
func (*Khipu) MaxWidth ¶
MaxWidth finds the maximum width of the knots in the range [from ... to-1].
func (*Khipu) Measure ¶
Measure returns the widths of a subset of this knot list. The subset runs from index [from ... to-1]. The method returns natural, maximum and minimum width.
func (*Khipu) Reach ¶
Reach iterates over a khipu to find a point beyond a given distance. Starting from a knot (index), return a set of knots which mark possible endpoints for a sequence of knots to cover a certain width distance. The knot set is returned as a pair (from,to) of indices. If the distance cannot be covered, (-1,-1) is returned.
func (*Khipu) ReplaceKnot ¶
ReplaceKnot replaces a knot within the khipu. If inx is not a valid index for the khipu, nothing is done.
Returns the current knot at position inx.
type Knot ¶
type Knot interface { Type() KnotType // type identifier of this knot W() dimen.Dimen // width MinW() dimen.Dimen // minimum width MaxW() dimen.Dimen // maximum width IsDiscardable() bool // is this knot discardable? }
A Knot has a width and may be discardable
type Penalty ¶
type Penalty int
A Penalty contributes to demerits, i.e. the quality index of paragraphs
func (Penalty) IsDiscardable ¶
IsDiscardable is part of interface Knot. Penalties are discardable.
type TextBox ¶
type TextBox struct { Width dimen.Dimen // width Height dimen.Dimen // height Depth dimen.Dimen // depth // contains filtered or unexported fields }
A TextBox is a fixed unit of text
func (TextBox) IsDiscardable ¶
IsDiscardable is part of interface Knot. Text is not discardable.
type TypesettingPipeline ¶
type TypesettingPipeline struct {
// contains filtered or unexported fields
}
A TypesettingPipeline consists of steps to produce a khipu from text.
func PrepareTypesettingPipeline ¶
func PrepareTypesettingPipeline(text io.Reader, pipeline *TypesettingPipeline) *TypesettingPipeline
PrepareTypesettingPipeline checks if a typesetting pipeline is correctly initialized and creates a new one if is is invalid.
We use a uax14.LineWrapper as the primary breaker and use a segment.SimpleWordBreaker to extract spans of whitespace. For the inner loop we use a uax29.WordBreaker. This is a default configuration adequate for western languages.
Directories ¶
Path | Synopsis |
---|---|
Package linebreak collects types for line-breaking.
|
Package linebreak collects types for line-breaking. |
firstfit
Package firstfit implements a straightforward line-breaking algorithm where lines are broken at the first suitable breakpoint.
|
Package firstfit implements a straightforward line-breaking algorithm where lines are broken at the first suitable breakpoint. |
knuthplass
Package knuthplass implements (in an early draft) a line breaking algorithm described by D.E. Knuth and M.F. Plass.
|
Package knuthplass implements (in an early draft) a line breaking algorithm described by D.E. Knuth and M.F. Plass. |