=================================================================== RCS file: /cvs/mandoc/mdoc.h,v retrieving revision 1.103 retrieving revision 1.109 diff -u -p -r1.103 -r1.109 --- mandoc/mdoc.h 2010/08/20 01:02:07 1.103 +++ mandoc/mdoc.h 2010/12/22 11:15:16 1.109 @@ -1,4 +1,4 @@ -/* $Id: mdoc.h,v 1.103 2010/08/20 01:02:07 schwarze Exp $ */ +/* $Id: mdoc.h,v 1.109 2010/12/22 11:15:16 kristaps Exp $ */ /* * Copyright (c) 2008, 2009, 2010 Kristaps Dzonsons * @@ -17,16 +17,9 @@ #ifndef MDOC_H #define MDOC_H -/* - * This library implements a validating scanner/parser for ``mdoc'' roff - * macro documents, a.k.a. BSD manual page documents. The mdoc.c file - * drives the parser, while macro.c describes the macro ontologies. - * validate.c pre- and post-validates parsed macros, and action.c - * performs actions on parsed and validated macros. +/* + * What follows is a list of ALL possible macros. */ - -/* What follows is a list of ALL possible macros. */ - enum mdoct { MDOC_Ap = 0, MDOC_Dd, @@ -153,8 +146,9 @@ enum mdoct { MDOC_MAX }; -/* What follows is a list of ALL possible macro arguments. */ - +/* + * What follows is a list of ALL possible macro arguments. + */ enum mdocargt { MDOC_Split, MDOC_Nosplit, @@ -186,7 +180,9 @@ enum mdocargt { MDOC_ARG_MAX }; -/* Type of a syntax node. */ +/* + * Type of a syntax node. + */ enum mdoc_type { MDOC_TEXT, MDOC_ELEM, @@ -197,9 +193,12 @@ enum mdoc_type { MDOC_ROOT }; -/* Section (named/unnamed) of `Sh'. */ +/* + * Section (named/unnamed) of `Sh'. Note that these appear in the + * conventional order imposed by mdoc.7. + */ enum mdoc_sec { - SEC_NONE, /* No section, yet. */ + SEC_NONE = 0, /* No section, yet. */ SEC_NAME, SEC_LIBRARY, SEC_SYNOPSIS, @@ -220,42 +219,58 @@ enum mdoc_sec { SEC_CAVEATS, SEC_BUGS, SEC_SECURITY, - SEC_CUSTOM, /* User-defined. */ + SEC_CUSTOM, /* User-defined. */ SEC__MAX }; -/* Information from prologue. */ +/* + * Information from prologue. + */ struct mdoc_meta { - char *msec; - char *vol; - char *arch; - time_t date; - char *title; - char *os; - char *name; + char *msec; /* `Dt' section (1, 3p, etc.) */ + char *vol; /* `Dt' volume (implied) */ + char *arch; /* `Dt' arch (i386, etc.) */ + time_t date; /* `Dd' normalised date */ + char *title; /* `Dt' title (FOO, etc.) */ + char *os; /* `Os' system (OpenBSD, etc.) */ + char *name; /* leading `Nm' name */ }; -/* An argument to a macro (multiple values = `It -column'). */ +/* + * An argument to a macro (multiple values = `-column xxx yyy'). + */ struct mdoc_argv { - enum mdocargt arg; + enum mdocargt arg; /* type of argument */ int line; int pos; - size_t sz; - char **value; + size_t sz; /* elements in "value" */ + char **value; /* argument strings */ }; +/* + * Reference-counted macro arguments. These are refcounted because + * blocks have multiple instances of the same arguments spread across + * the HEAD, BODY, TAIL, and BLOCK node types. + */ struct mdoc_arg { size_t argc; struct mdoc_argv *argv; unsigned int refcnt; }; +/* + * Indicates that a BODY's formatting has ended, but the scope is still + * open. Used for syntax-broken blocks. + */ enum mdoc_endbody { ENDBODY_NOT = 0, - ENDBODY_SPACE, - ENDBODY_NOSPACE + ENDBODY_SPACE, /* is broken: append a space */ + ENDBODY_NOSPACE /* is broken: don't append a space */ }; +/* + * Normalised `Bl' list type. + */ enum mdoc_list { LIST__NONE = 0, LIST_bullet, @@ -268,9 +283,13 @@ enum mdoc_list { LIST_inset, LIST_item, LIST_ohang, - LIST_tag + LIST_tag, + LIST_MAX }; +/* + * Normalised `Bd' display type. + */ enum mdoc_disp { DISP__NONE = 0, DISP_centred, @@ -280,12 +299,18 @@ enum mdoc_disp { DISP_literal }; +/* + * Normalised `An' splitting argument. + */ enum mdoc_auth { AUTH__NONE = 0, AUTH_split, AUTH_nosplit }; +/* + * Normalised `Bf' font type. + */ enum mdoc_font { FONT__NONE = 0, FONT_Em, @@ -293,12 +318,18 @@ enum mdoc_font { FONT_Sy }; +/* + * Normalised arguments for `Bd'. + */ struct mdoc_bd { const char *offs; /* -offset */ enum mdoc_disp type; /* -ragged, etc. */ int comp; /* -compact */ }; +/* + * Normalised arguments for `Bl'. + */ struct mdoc_bl { const char *width; /* -width */ const char *offs; /* -offset */ @@ -308,18 +339,48 @@ struct mdoc_bl { const char **cols; /* -column val ptr */ }; +/* + * Normalised arguments for `Bf'. + */ struct mdoc_bf { enum mdoc_font font; /* font */ }; +/* + * Normalised arguments for `An'. + */ struct mdoc_an { enum mdoc_auth auth; /* -split, etc. */ }; -/* Node in AST. */ +/* + * Consists of normalised node arguments. These should be used instead + * of iterating through the mdoc_arg pointers of a node: defaults are + * provided, etc. + */ +union mdoc_data { + struct mdoc_an An; + struct mdoc_bd Bd; + struct mdoc_bf Bf; + struct mdoc_bl Bl; +}; + +/* + * Reference-counted structure for containing normalised arguments of + * certain macros (those listed in union mdoc_data). + */ +struct mdoc_norm { + int refcnt; + union mdoc_data d; +}; + +/* + * Single node in tree-linked AST. + */ struct mdoc_node { struct mdoc_node *parent; /* parent AST node */ struct mdoc_node *child; /* first child AST node */ + struct mdoc_node *last; /* last child AST node */ struct mdoc_node *next; /* sibling AST node */ struct mdoc_node *prev; /* prior sibling AST node */ int nchild; /* number children */ @@ -335,33 +396,33 @@ struct mdoc_node { #define MDOC_ENDED (1 << 5) /* rendering has been ended */ enum mdoc_type type; /* AST node type */ enum mdoc_sec sec; /* current named section */ + struct mdoc_norm *norm; /* ref-counted, normalised args */ /* FIXME: these can be union'd to shave a few bytes. */ - struct mdoc_arg *args; /* BLOCK/ELEM */ - struct mdoc_node *pending; /* BLOCK */ - struct mdoc_node *head; /* BLOCK */ - struct mdoc_node *body; /* BLOCK */ - struct mdoc_node *tail; /* BLOCK */ - char *string; /* TEXT */ - enum mdoc_endbody end; /* BODY */ - - union { - struct mdoc_an An; - struct mdoc_bd *Bd; - struct mdoc_bf *Bf; - struct mdoc_bl *Bl; - } data; + struct mdoc_arg *args; /* BLOCK/ELEM */ + struct mdoc_node *pending; /* BLOCK */ + struct mdoc_node *head; /* BLOCK */ + struct mdoc_node *body; /* BLOCK */ + struct mdoc_node *tail; /* BLOCK */ + char *string; /* TEXT */ + enum mdoc_endbody end; /* BODY */ }; -/* See mdoc.3 for documentation. */ - +/* + * Names of macros. Index is enum mdoct. Indexing into this returns + * the normalised name, e.g., mdoc_macronames[MDOC_Sh] -> "Sh". + */ extern const char *const *mdoc_macronames; + +/* + * Names of macro args. Index is enum mdocargt. Indexing into this + * returns the normalised name, e.g., mdoc_argnames[MDOC_File] -> + * "file". + */ extern const char *const *mdoc_argnames; __BEGIN_DECLS struct mdoc; - -/* See mdoc.3 for documentation. */ void mdoc_free(struct mdoc *); struct mdoc *mdoc_alloc(struct regset *, void *, mandocmsg);