Previous  Up  Next

Module Document

module Document: sig .. end
High-level representation of documents

The module defines the Document.tree type, which describes whole documents. This tree is typically produced by running the OCaml executable obtained after parsing a .txp file, but can be produced by anyy other mean. It is the main input to Patoline Typography library in order to produce the final document.

Values of type Document.tree are meant to be transformed by some format's output routine.

We also provide a tree zipper interface to ease construction of a Document.tree when reading linearly an input file.


Font, substitutions, positioning


type fontAlternative =
| Regular
| Bold
| Caps
| Demi 
val simpleFamilyMember : (unit -> Fonts.font) ->
       (Fonts.font * (string -> string) *
        (FTypes.glyph_id list -> FTypes.glyph_id list) *
        (FTypes.glyph_ids list -> FTypes.glyph_ids list))
       Lazy.t
val make_ligature : int list -> FTypes.glyph_id -> FTypes.glyph_id list -> FTypes.glyph_id list
type fontFamily = fontAlternative *
       ((Fonts.font * (string -> string) *
         (FTypes.glyph_id list -> FTypes.glyph_id list) *
         (FTypes.glyph_ids list -> FTypes.glyph_ids list))
        Lazy.t *
        (Fonts.font * (string -> string) *
         (FTypes.glyph_id list -> FTypes.glyph_id list) *
         (FTypes.glyph_ids list -> FTypes.glyph_ids list))
        Lazy.t) 
module TS: Break.Make(sig
type t = Box.line 
val compare : Box.line -> Box.line -> int
val hash : 'a -> int
end)

Mathematical formulae


module Mathematical: sig .. end

Environments


type environment = {
   fontFamily : fontFamily list;
   fontMonoFamily : fontFamily list;
   fontMonoRatio : float;
   fontItalic : bool;
   fontAlternative : fontAlternative;
   fontFeatures : string list;
   fontColor : Color.color;
   font : Fonts.font;
   mathsEnvironment : Mathematical.environment;
   mathStyle : Mathematical.style;
   size : float;
   lead : float;
   footnote_y : float;
   normalMeasure : float;
   normalLead : float;
   normalLeftMargin : float;
   normalPageFormat : float * float;
   par_indent : Box.box list;
   hyphenate : string -> (string * string) array;
   word_substitutions : string -> string;
   substitutions : FTypes.glyph_id list -> FTypes.glyph_id list;
   positioning : FTypes.glyph_ids list -> FTypes.glyph_ids list;
   counters : (int * int list) Extra.StrMap.t; (*
Niveau du compteur, état.
*)
   last_changed_counter : string;
   names : ((int * int list) Extra.StrMap.t * string * Box.line) Extra.StrMap.t; (*
Niveaux de tous les compteurs à cet endroit, type, position
*)
   fixable : bool Pervasives.ref;
   new_page : Box.frame_zipper -> Box.frame_zipper;
   new_line : environment ->
Box.line ->
Box.parameters ->
Box.line -> Box.parameters -> Box.frame_zipper -> float -> float;
   user_positions : Box.line Box.MarkerMap.t;
   show_boxes : bool;
   show_frames : bool;
   adjust_optical_alpha : float;
   adjust_optical_beta : float;
   adjust_epsilon : float;
   adjust_min_space : float;
   math_break_badness : float;
   stdGlue : float * float * float;
}
Environments. These are typically folded on document trees, and control many different things about the fonts, counters, or labels.
val env_accessed : bool Pervasives.ref
val names : environment ->
       ((int * int list) Extra.StrMap.t * string * Box.line) Extra.StrMap.t
val user_positions : environment -> Box.line Box.MarkerMap.t
val displayname : Driver.structure -> RawContent.raw list

Document content


type content =
| B of (environment -> Box.box list) * Box.box list option Pervasives.ref
| C of (environment -> content list)
| T of string * Box.box list Extra.IntMap.t option Pervasives.ref
| Env of (environment -> environment)
| Scoped of (environment -> environment) * content list
| N of tree
Main type used to hold document contents.
type paragraph = {
   par_contents : content list;
   par_env : environment -> environment;
   par_post_env : environment -> environment -> environment;
   par_parameters : environment ->
Box.box array array ->
Box.drawingBox array ->
Box.parameters ->
Break.figurePosition Extra.IntMap.t ->
Box.line Box.MarkerMap.t -> Box.line -> Box.line -> Box.parameters;
   par_badness : environment ->
Box.box array array ->
Box.drawingBox array ->
Break.figurePosition Extra.IntMap.t ->
Box.line ->
Box.box array ->
int ->
Box.parameters ->
float -> Box.line -> Box.box array -> int -> Box.parameters -> float -> float;
   par_completeLine : environment ->
Box.box array array ->
Box.drawingBox array ->
Break.figurePosition Extra.IntMap.t ->
Box.line Box.MarkerMap.t -> Box.line -> bool -> Box.line list;
   par_states : int list;
   par_paragraph : int;
}
First type of leaves in a document: paragraphs.
type figuredef = {
   fig_contents : environment -> Box.drawingBox;
   fig_env : environment -> environment;
   fig_post_env : environment -> environment -> environment;
   fig_parameters : environment ->
Box.box array array ->
Box.drawingBox array ->
Box.parameters ->
Break.figurePosition Extra.IntMap.t ->
Box.line Box.MarkerMap.t -> Box.line -> Box.line -> Box.parameters;
}
Second type of leaves in a document: figures.
type node = {
   name : string;
   displayname : content list;
   mutable boxified_displayname : RawContent.raw list;
   children : tree Extra.IntMap.t;
   node_tags : (string * string) list;
   node_env : environment -> environment;
   node_post_env : environment -> environment -> environment;
   node_states : int list;
   mutable node_paragraph : int;
}
Internal node of the document tree (e.g. section, chapter...).
type tree =
| Paragraph of paragraph
| FigureDef of figuredef
| Node of node
Type of a document tree.
val empty : node
Empty node (with no child tree).
val singleton : tree -> node
Build a node with a single child tree.
type tree_zipper = tree * (int * node) list
The main datatype is a zipper over a document tree. It consists in a couple whose first component is a tree. The second component represents the context identifying a position in the tree.

The tree represented by the zipper (t, [(p1,t1), ... , (pn,tn)]) is built by:


val up : tree_zipper -> tree_zipper
Function that takes a tree zipper (t,cxt) pointing to some node t and returns a zipper pointing to the father node of t. If this function is called on a zipper that points to the root of the tree, a new empty node is created to have t as its only child.
val up_n : int -> tree_zipper -> tree_zipper
Function that applies Document.up n times on a zipper, effectively moving the zipper to the n-th ancestor of the currently pointed node.
val top : tree_zipper -> tree_zipper
Move the zipper to the root of the tree
val lastChild : tree_zipper -> tree_zipper
Move the zipper to point to the child of the pointed node with the higher index. It the pointed tree is not a node the zipper is left unchanged.
val newChildAfter : tree_zipper -> tree -> tree_zipper
Take a zipper (t,cxt) and a tree c and adds c as the last child of the pointed node. If the pointed subtree is not a node, a new node is created to hold t and c. The returned zipper points to c.
val newChildBefore : tree_zipper -> tree -> tree_zipper
Same as Document.newChildAfter but adds the tree as the first child.
val child : tree_zipper -> int -> tree_zipper
Take a zipper pointing to a node and move it down its i-th child. If the zipper does not point to a node, Invalid_argument is raised. If the i-th child does not exists, it is created as a new empty node.
val follow : tree_zipper -> int list -> tree_zipper
Take a tree zipper and an path represented as a list of integers and move the zipper down the path (i.e. calling child on the successive indices.
module type Format = sig .. end
Module type of a document format. 
module type DocumentStructure = sig .. end
Module type to be used as a document wrapper. 
val doc_tags : tree -> (string * string) list
val init_env_hook : (environment -> environment) list Pervasives.ref
val add_env_hook : (environment -> environment) -> unit
val bB : (environment -> Box.box list) -> content
val uB : (environment -> Box.box list) -> content
val tT : string -> content
val uT : string -> content
val string_of_contents : content list -> string
val _names : environment ->
       ((int * int list) Extra.StrMap.t * string * Box.line) Extra.StrMap.t
val _user_positions : environment -> Box.line Box.MarkerMap.t
val incr_counter : ?level:int ->
       Extra.StrMap.key -> environment -> environment
val pop_counter : Extra.StrMap.key -> environment -> environment
val push_counter : Extra.StrMap.key -> environment -> environment
val tags : tree -> (string * string) list
val envApp : ('a -> 'a) list -> 'a -> 'a
val map_paragraphs : (paragraph -> paragraph) -> tree -> tree
exception Found
val find_last : (tree -> bool) -> tree -> Extra.IntMap.key list
Finds the last node satisfying a given predicate in a document tree.
val is_paragraph : tree -> bool
Is the node a paragraph ?
val is_node : tree -> bool
Is the node an internal node ?
val prev : (tree -> bool) ->
       tree * (Extra.IntMap.key * tree) list ->
       tree * (Extra.IntMap.key * tree) list
val go_up : tree_zipper Pervasives.ref -> unit
val n_go_up : int -> tree_zipper Pervasives.ref -> unit

Environment transformations


val change_env : tree * 'a ->
       (environment -> environment) -> tree * 'a
exception Not_found_in_family
val selectFont : ('a * ('b Lazy.t * 'b Lazy.t)) list -> 'a -> bool -> 'b
val updateFont : environment ->
       Fonts.font ->
       (string -> string) ->
       (FTypes.glyph_id list -> FTypes.glyph_id list) ->
       (FTypes.glyph_ids list -> FTypes.glyph_ids list) -> environment
val change_font : Fonts.font -> environment -> environment
val font : Fonts.font -> content list -> content list
val add_features : string list -> environment -> environment
val envItalic : bool -> environment -> environment
val italic : content list -> content list
val notItalic : content list -> content list
val toggleItalic : content list -> content list
val envAlternative : ?features:string list ->
       fontAlternative -> environment -> environment
val alternative : ?features:string list ->
       fontAlternative -> content list -> content list
val font_size_ratio : (fontAlternative * ((Fonts.font * 'a * 'b * 'c) Lazy.t * 'd)) list ->
       (fontAlternative * ((Fonts.font * 'e * 'f * 'g) Lazy.t * 'h)) list ->
       float
val envFamily : fontFamily list -> environment -> environment
val family : fontFamily list -> content list -> content list
val envMonoFamily : fontFamily list -> environment -> environment
val monoFamily : fontFamily list -> content list -> content list
val envSize : float -> environment -> environment
val size : float -> content list -> content list
val envScale : float -> environment -> environment
val scale : float -> content list -> content list
val envScaleLead : float -> environment -> environment
val scaleLead : float -> content list -> content list
val envColor : Color.color -> environment -> environment
val color : Color.color -> content list -> content list
val envBold : environment -> environment
val bold : content list -> content list
val envSv : environment -> environment
val sc : content list -> content list
val verbEnv : environment -> environment
val verb : content list -> content list
val emph : content list -> content list
val id : 'a -> 'a
val parameters : environment ->
       Box.box array array ->
       Box.drawingBox array ->
       'a ->
       Break.figurePosition Extra.IntMap.t -> 'b -> 'c -> Box.line -> Box.parameters
val set_parameters : (Box.parameters -> Box.parameters) -> content list
val vspaceBefore : float -> content list
val vspaceAfter : float -> content list
val pagesBefore : int -> content list
val pagesAfter : int -> content list
val linesBefore : int -> content list
val linesAfter : int -> content list
val notFirstLine : content list
val notLastLine : content list
val hspace : float -> content list
val hfill : content list
val do_center : ('a -> 'b -> 'c -> 'd -> 'e -> 'f -> 'g -> Box.line -> Box.parameters) ->
       'a -> 'b -> 'c -> 'd -> 'e -> 'f -> 'g -> Box.line -> Box.parameters
val do_ragged_left : ('a -> 'b -> 'c -> 'd -> 'e -> 'f -> 'g -> Box.line -> Box.parameters) ->
       'a -> 'b -> 'c -> 'd -> 'e -> 'f -> 'g -> Box.line -> Box.parameters
val do_ragged_right : ('a -> 'b -> 'c -> 'd -> 'e -> 'f -> 'g -> Box.line -> Box.parameters) ->
       'a -> 'b -> 'c -> 'd -> 'e -> 'f -> 'g -> Box.line -> Box.parameters
val badness : environment ->
       Box.box array array ->
       'a ->
       'b ->
       Box.line ->
       Box.box array ->
       int ->
       Box.parameters ->
       float -> Box.line -> Box.box array -> int -> Box.parameters -> float -> float

Figures


val figure : tree_zipper Pervasives.ref ->
       (environment ->
        Box.box array array ->
        Box.drawingBox array ->
        Box.parameters ->
        Break.figurePosition Extra.IntMap.t ->
        Box.line Box.MarkerMap.t -> Box.line -> Box.line -> Box.parameters) ->
       ?name:Extra.StrMap.key -> (environment -> Box.drawingBox) -> unit
val flushFigure : Extra.StrMap.key -> content list
val beginFigure : Extra.StrMap.key -> content list
val newPar : tree_zipper Pervasives.ref ->
       ?environment:(environment -> environment) ->
       ?badness:(environment ->
                 Box.box array array ->
                 Box.drawingBox array ->
                 Break.figurePosition Extra.IntMap.t ->
                 Box.line ->
                 Box.box array ->
                 int ->
                 Box.parameters ->
                 float ->
                 Box.line ->
                 Box.box array -> int -> Box.parameters -> float -> float) ->
       ?states:int list ->
       (environment ->
        Box.box array array ->
        Box.drawingBox array ->
        Break.figurePosition Extra.IntMap.t ->
        Box.line Box.MarkerMap.t -> Box.line -> bool -> Box.line list) ->
       (environment ->
        Box.box array array ->
        Box.drawingBox array ->
        Box.parameters ->
        Break.figurePosition Extra.IntMap.t ->
        Box.line Box.MarkerMap.t -> Box.line -> Box.line -> Box.parameters) ->
       content list -> unit
val newStruct : tree_zipper Pervasives.ref ->
       ?in_toc:bool ->
       ?label:string ->
       ?numbered:bool ->
       ?extra_tags:(string * string) list -> content list -> unit
Adds a new node, just below the last one.


val pageref : Extra.StrMap.key -> content list
val make_name : string -> string
val label : ?labelType:string -> string -> content list
val pass_number : int Pervasives.ref
val lref : ?refType:Extra.StrMap.key -> string -> content list
val generalRef : Extra.StrMap.key -> string -> content list
val sectref : string -> content list
val extLink : string -> content list -> content list
val link : string -> content list -> content list
val button_name : unit -> string
val button : RawContent.button_kind -> content list -> content list

Images


val image : ?scale:float ->
       ?width:float ->
       ?height:float -> ?offset:float -> string -> 'a -> Box.drawingBox
val video : ?scale:float ->
       ?width:float ->
       ?height:float ->
       ?offset:float -> string -> environment -> Box.drawingBox
val includeGraphics : ?scale:float ->
       ?width:float ->
       ?height:float -> ?offset:float -> string -> content list
val includeVideo : ?scale:float ->
       ?width:float ->
       ?height:float -> ?offset:float -> string -> content list

Boxification


val makeGlue : environment -> int -> Box.box
Makes a glue from the unicode character code given in the argument.
val gl_of_str : environment -> string -> Box.box list
Converts a string to a list of glyphs, according to the environment.
val boxify : Box.box array Pervasives.ref ->
       int Pervasives.ref ->
       environment -> content list -> environment
Converts a list of contents into a list of boxes, which is the next Patoline layer.
val draw_boxes : environment -> Box.box list -> RawContent.raw list
Typesets boxes on a single line, then converts them to a list of basic drawing elements: RawContent.raw.
val bezier_of_boxes : RawContent.raw list -> Bezier.curve list
val adjust_width : environment ->
       Box.box array Pervasives.ref -> int Pervasives.ref -> unit
val boxify_scoped : environment -> content list -> Box.box list
The same as boxify, but discards the final environment.
val draw : environment -> content list -> RawContent.raw list
Composes boxify and draw_boxes
val states : int list -> content list -> content list
val altStates : (int list * content list) list -> content list
val flatten : ?initial_path:Extra.IntMap.key list ->
       environment ->
       tree ->
       environment *
       (Box.box array array ->
        Box.drawingBox array ->
        Box.parameters ->
        Break.figurePosition Extra.IntMap.t ->
        Box.line Box.MarkerMap.t -> Box.line -> Box.line -> Box.parameters)
       array *
       (Box.box array array ->
        Box.drawingBox array ->
        Box.parameters ->
        Break.figurePosition Extra.IntMap.t ->
        Box.line Box.MarkerMap.t -> Box.line -> Box.line -> Box.parameters)
       array * (Box.frame_zipper -> Box.frame_zipper) array *
       (Box.line ->
        Box.parameters ->
        Box.line -> Box.parameters -> Box.frame_zipper -> float -> float)
       array *
       (Box.box array array ->
        Box.drawingBox array ->
        Break.figurePosition Extra.IntMap.t ->
        Box.line Box.MarkerMap.t -> Box.line -> bool -> Box.line list)
       array *
       (Box.box array array ->
        Box.drawingBox array ->
        Break.figurePosition Extra.IntMap.t ->
        Box.line ->
        Box.box array ->
        int ->
        Box.parameters ->
        float ->
        Box.line -> Box.box array -> int -> Box.parameters -> float -> float)
       array * Box.box array array *
       (tree * (Extra.IntMap.key * tree) list) array *
       Box.drawingBox array *
       (tree * (Extra.IntMap.key * tree) list) array *
       int list array
"flattens" a document tree to an array of paragraphs, a paragraph being an array of boxes.
val make_struct : (int * float * float) array -> tree -> Driver.structure
val tag : tree -> (string * string) list -> tree
Adds a tag to the given structure.
val update_names : environment ->
       Break.figurePosition Extra.IntMap.t ->
       Box.line Box.MarkerMap.t -> environment * bool
Label updating after optimization.
val reset_counters : environment -> environment
Resets all the counters, preserving their levels.