Noted lacking areas in mdocterm.1.

[mandoc.git] / mdoc.h

diff --git a/mdoc.h b/mdoc.h
index a79834ca6bc8bf7a7d47c3f6996a99fdc33172ce..6ec0e467d246216ff3ac381a0ae7c18a4802aeec 100644 (file)
--- a/mdoc.h
+++ b/mdoc.h
@@ -1,4 +1,4 @@
-/* $Id: mdoc.h,v 1.22 2009/01/15 17:38:57 kristaps Exp $ */
+/* $Id: mdoc.h,v 1.36 2009/03/02 12:09:32 kristaps Exp $ */
 /*
  * Copyright (c) 2008 Kristaps Dzonsons <kristaps@kth.se>
  *
@@ -19,9 +19,13 @@
 #ifndef MDOC_H
 #define MDOC_H
 
-/* FIXME: move this elsewhere (it's 9, too). */
-
-#define        MDOC_LINEARG_MAX 12
+/*
+ * 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. */
 
@@ -199,11 +203,13 @@
 #define        MDOC_Symbolic    61
 #define        MDOC_ARG_MAX     62
 
+/* Warnings are either syntax or groff-compatibility. */
 enum   mdoc_warn {
-       WARN_SYNTAX,            /* Syntax warn (at line/col). */
-       WARN_COMPAT             /* Groff compat warn (at line/col). */
+       WARN_SYNTAX,
+       WARN_COMPAT
 };
 
+/* Possible values for the `At' macro. */
 enum   mdoc_att {
        ATT_DEFAULT = 0,
        ATT_v1,
@@ -214,12 +220,14 @@ enum      mdoc_att {
        ATT_v6,
        ATT_v7,
        ATT_32v,
+       ATT_V,
        ATT_V1,
        ATT_V2,
        ATT_V3,
        ATT_V4
 };
 
+/* An argument to a macro (multiple values = `It -column'). */
 struct mdoc_arg {
        int               arg;
        int               line;
@@ -228,6 +236,7 @@ struct      mdoc_arg {
        char            **value;
 };
 
+/* Type of a syntax node. */
 enum   mdoc_type {
        MDOC_TEXT,
        MDOC_ELEM,
@@ -238,6 +247,7 @@ enum        mdoc_type {
        MDOC_ROOT
 };
 
+/* Manual section. */
 enum   mdoc_msec {
        MSEC_DEFAULT = 0,
        MSEC_1,
@@ -260,6 +270,7 @@ enum        mdoc_msec {
        MSEC_paper
 };
 
+/* Section (named/unnamed) of `Ss'. */
 enum   mdoc_sec {
        SEC_PROLOGUE = 0,
        SEC_BODY,
@@ -281,6 +292,7 @@ enum        mdoc_sec {
        SEC_CUSTOM
 };
 
+/* Volume of `Dt'. */
 enum   mdoc_vol {
        VOL_DEFAULT = 0,
        VOL_AMD,
@@ -294,12 +306,14 @@ enum      mdoc_vol {
        VOL_USD
 };
 
+/* Architecture of `Dt'. */
 enum   mdoc_arch {
        ARCH_DEFAULT = 0,
        ARCH_alpha, 
        ARCH_amd64, 
        ARCH_amiga, 
        ARCH_arc, 
+       ARCH_arm, 
        ARCH_armish, 
        ARCH_aviion, 
        ARCH_hp300,
@@ -323,21 +337,23 @@ enum      mdoc_arch {
        ARCH_zaurus
 };
 
+/* Information from prologue. */
 struct mdoc_meta {
        enum mdoc_msec    msec;
        enum mdoc_vol     vol;
        enum mdoc_arch    arch;
        time_t            date;
-#define        META_TITLE_SZ    (64)
-       char              title[META_TITLE_SZ];
-#define        META_OS_SZ       (64)
-       char              os[META_OS_SZ];
+       char             *title;
+       char             *os;
+       char             *name;
 };
 
+/* Text-only node. */
 struct mdoc_text {
        char             *string;
 };
 
+/* Block (scoped) node. */
 struct mdoc_block {
        size_t            argc;
        struct mdoc_arg  *argv;
@@ -346,19 +362,20 @@ struct    mdoc_block {
        struct mdoc_node *tail;
 };
 
+/* In-line element node. */
 struct mdoc_elem {
-       size_t            sz;
-       char            **args;
        size_t            argc;
        struct mdoc_arg  *argv;
 };
 
+/* Typed nodes of an AST node. */
 union  mdoc_data {
        struct mdoc_text  text;
        struct mdoc_elem  elem;
        struct mdoc_block block;
 };
 
+/* Node in AST. */
 struct mdoc_node {
        struct mdoc_node *parent;
        struct mdoc_node *child;
@@ -367,10 +384,15 @@ struct    mdoc_node {
        int               line;
        int               pos;
        int               tok;
+       int               flags;
+#define        MDOC_VALID       (1 << 0)
+#define        MDOC_ACTED       (1 << 1)
        enum mdoc_type    type;
        union mdoc_data   data;
+       enum mdoc_sec     sec;
 };
 
+/* Call-backs for parse messages. */
 struct mdoc_cb {
        void    (*mdoc_msg)(void *, int, int, const char *);
        int     (*mdoc_err)(void *, int, int, const char *);
@@ -378,21 +400,42 @@ struct    mdoc_cb {
                        enum mdoc_warn, const char *);
 };
 
+/* Global table of macro names (`Bd', `Ed', etc.). */
 extern const char *const *mdoc_macronames;
+
+/* Global table of argument names (`column', `tag', etc.). */
 extern const char *const *mdoc_argnames;
 
 __BEGIN_DECLS
 
 struct mdoc;
 
+/* Free memory allocated with mdoc_alloc. */
 void             mdoc_free(struct mdoc *);
+
+/* Allocate a new parser instance. */
 struct mdoc     *mdoc_alloc(void *data, const struct mdoc_cb *);
+
+/* Parse a single line in a stream (boolean retval). */
 int              mdoc_parseln(struct mdoc *, int, char *buf);
-const struct mdoc_node
-                *mdoc_result(struct mdoc *);
+
+/* Get result first node (after mdoc_endparse!). */
+const struct mdoc_node *mdoc_node(const struct mdoc *);
+
+/* Get result meta-information (after mdoc_endparse!). */
+const struct mdoc_meta *mdoc_meta(const struct mdoc *);
+
+/* Signal end of parse sequence (boolean retval). */
 int              mdoc_endparse(struct mdoc *);
 
-char            *mdoc_type2a(enum mdoc_type);
+/* The following are utility functions. */
+const char      *mdoc_arch2a(enum mdoc_arch);
+const char      *mdoc_vol2a(enum mdoc_vol);
+const char      *mdoc_msec2a(enum mdoc_msec);
+const char      *mdoc_att2a(enum mdoc_att);
+enum   mdoc_att  mdoc_atoatt(const char *);
+const char      *mdoc_st2a(int);
+int              mdoc_isdelim(const char *);
 
 __END_DECLS