Update docs.

2 files changed, 152 insertions, 96 deletions

diff --git a/src/cmdline.opt b/src/cmdline.opt
index 93f752d..d0fb01c 100644
--- a/src/cmdline.opt
+++ b/src/cmdline.opt
@@ -27,6 +27,8 @@ char *program_name;
 #define PREPROC_DEFAULT 2
 static int preproc_settings = PREPROC_NOT_SET;
 
+static int flags_on, flags_off;
+
 struct format_flag {
 	char *name;
 	char *arg;
@@ -50,16 +52,7 @@ set_up_option(const char *str)
 static void
 set_delim_option(const char *str)
 {
-	flags |= *str & 0xff;
-}
-
-static void
-set_descend_flag(const char *str)
-{
-	if (strncmp(str, "no", 2) == 0)
-		flags |= GRECS_NODE_FLAG_NODESCEND;
-	else
-		flags &= ~GRECS_NODE_FLAG_NODESCEND;
+	flags_on |= *str & 0xff;
 }
 
 struct format_flag format_flag_table[] = {
@@ -82,7 +75,7 @@ struct format_flag format_flag_table[] = {
 	{ "quote-hex", NULL, "show unprintable characters as hex",
 	  GRECS_NODE_FLAG_QUOTE_HEX },
 	{ "descend", NULL, "descend into subnodes",
-	  GRECS_NODE_FLAG_NODESCEND, set_descend_flag },
+	  GRECS_NODE_FLAG_DESCEND },
 	{ "default", NULL, "set default options",
 	  GRECS_NODE_FLAG_DEFAULT },
 	{ NULL }
@@ -140,14 +133,14 @@ set_flag(const char *str)
 			if (fp->handler)
 				fp->handler(str);
 			else
-				flags |= fp->flag;
+				flags_on |= fp->flag;
 			return;
 		} else if (strncmp(str, "no", 2) == 0 &&
 			   strcmp(str + 2, fp->name) == 0) {
 			if (fp->handler)
 				fp->handler(str);
 			else
-				flags &= ~fp->flag;
+				flags_off |= fp->flag;
 			return;
 		}
 	}
@@ -341,8 +334,9 @@ parse_options(int argc, char *argv[])
 		program_name = argv[0];
 	print_help_hook = flags_help;
         GETOPT(argc, argv, file_index, exit(EX_USAGE))
-	if (!flags) 
-		flags = GRECS_NODE_FLAG_PATH|GRECS_NODE_FLAG_VALUE;
+	if (!(flags_on & _GRECS_NODE_MASK_OUTPUT)) 
+		flags_on |= GRECS_NODE_FLAG_DEFAULT;
+	flags = flags_on & ~flags_off;	
 	if (preproc_settings == PREPROC_DEFAULT)
 		grecs_preprocessor = DEFAULT_PREPROCESSOR;
 	if (pp_cmd_acc && grecs_preprocessor) {
diff --git a/src/guile.c b/src/guile.c
index e5e7644..63a7e9a 100644
--- a/src/guile.c
+++ b/src/guile.c
@@ -149,8 +149,8 @@ _guile_node_print(SCM smob, SCM port, scm_print_state *pstate)
 		scm_puts(".", port);
 	else
 		grecs_format_node(np->node,
-				  GRECS_NODE_FLAG_DEFAULT|
-				  GRECS_NODE_FLAG_NODESCEND,
+				  GRECS_NODE_FLAG_PATH|GRECS_NODE_FLAG_VALUE|
+				  GRECS_NODE_FLAG_QUOTE,
 				  &clos);
 	scm_puts(">", port);
 	return 1;
@@ -177,7 +177,7 @@ static SCM scm_from_grecs_value(struct grecs_value *val);
 SCM_DEFINE_PUBLIC(scm_grecs_node_p, "grecs-node?",
 		  1, 0, 0,
 		  (SCM obj),
-		  "Return true if @var{obj} is a Grecs tree node.")
+"Returns @samp{#t} if @var{obj} is a valid tree node.")
 #define FUNC_NAME s_scm_grecs_node_p
 {
 	return CELL_IS_NODE(obj) ? SCM_BOOL_T : SCM_BOOL_F;
@@ -187,7 +187,7 @@ SCM_DEFINE_PUBLIC(scm_grecs_node_p, "grecs-node?",
 SCM_DEFINE_PUBLIC(scm_grecs_node_root, "grecs-node-root",
 		  1, 0, 0,
 		  (SCM node),
-		  "Return root node for @var{node}.")
+"Returns the topmost node that can be traced up from @var{node}.")
 #define FUNC_NAME s_scm_grecs_node_root
 {
 	struct _guile_node *gnp;
@@ -204,7 +204,15 @@ SCM_DEFINE_PUBLIC(scm_grecs_node_root, "grecs-node-root",
 SCM_DEFINE_PUBLIC(scm_grecs_node_head, "grecs-node-head",
 		  1, 0, 0,
 		  (SCM node),
-"Return the first node located on the same nesting level as @var{node}.")
+"Returns the first node having the same parent and located on the "
+"same nesting level as @var{node}.  I.e. the following always holds "
+"true:\n\n"
+"@lisp\n"
+"(let ((head (grecs-node-head node)))\n"
+"  (and\n"
+"    (eq? (grecs-node-up node) (grecs-node-up head))\n"
+"    (not (grecs-node-prev? head))))\n"
+"@end lisp\n")
 #define FUNC_NAME s_scm_grecs_node_head
 {
 	struct _guile_node *gnp;
@@ -222,7 +230,15 @@ SCM_DEFINE_PUBLIC(scm_grecs_node_head, "grecs-node-head",
 SCM_DEFINE_PUBLIC(scm_grecs_node_tail, "grecs-node-tail",
 		  1, 0, 0,
 		  (SCM node),
-"Return the last node located on the same nesting level as @var{node}.")
+"Returns the last node having the same parent and located on the same "
+"nesting level as node.  In other words, the following relation is always "
+"@samp{#t}:\n\n"
+"@lisp\n"
+"(let ((tail (grecs-node-tail node)))\n"
+"  (and\n"
+"    (eq? (grecs-node-up node) (grecs-node-up tail))\n"
+"         (not (grecs-node-next? tail))))\n"
+"@end lisp\n")
 #define FUNC_NAME s_scm_grecs_node_tail
 {
 	struct _guile_node *gnp;
@@ -238,167 +254,180 @@ SCM_DEFINE_PUBLIC(scm_grecs_node_tail, "grecs-node-tail",
 
 SCM_DEFINE_PUBLIC(scm_grecs_node_up_p, "grecs-node-up?",
 		  1, 0, 0,
-		  (SCM obj),
-		  "Return true if @var{obj} has a parent node.")
+		  (SCM node),
+"Return true if @var{node} has a parent node.")
 #define FUNC_NAME s_scm_grecs_node_up_p
 {
 	struct _guile_node *gnp;
 	
-	SCM_ASSERT(CELL_IS_NODE(obj), obj, SCM_ARG1, FUNC_NAME);
-	gnp = node_from_scm(obj);
+	SCM_ASSERT(CELL_IS_NODE(node), node, SCM_ARG1, FUNC_NAME);
+	gnp = node_from_scm(node);
 	return gnp->node->up ? SCM_BOOL_T : SCM_BOOL_F;
 }
 #undef FUNC_NAME
 
 SCM_DEFINE_PUBLIC(scm_grecs_node_up, "grecs-node-up",
 		  1, 0, 0,
-		  (SCM obj),
-		  "Return parent node of @var{obj}.")
+		  (SCM node),
+"Return parent node of @var{node}.")
 #define FUNC_NAME s_scm_grecs_node_up
 {
 	struct _guile_node *gnp;
 	
-	SCM_ASSERT(CELL_IS_NODE(obj), obj, SCM_ARG1, FUNC_NAME);
-	gnp = node_from_scm(obj);
+	SCM_ASSERT(CELL_IS_NODE(node), node, SCM_ARG1, FUNC_NAME);
+	gnp = node_from_scm(node);
 	if (!gnp->node->up)
 		scm_misc_error(FUNC_NAME,
 			       "no up node in ~S",
-			       scm_list_1(obj));
+			       scm_list_1(node));
 	return node_to_scm(gnp->node->up);
 }
 #undef FUNC_NAME
 
 SCM_DEFINE_PUBLIC(scm_grecs_node_down_p, "grecs-node-down?",
 		  1, 0, 0,
-		  (SCM obj),
-		  "Return true if @var{obj} has child nodes.")
+		  (SCM node),
+"Returns @samp{#t} if @var{node} has child nodes.")
 #define FUNC_NAME s_scm_grecs_node_down_p
 {
 	struct _guile_node *gnp;
 	
-	SCM_ASSERT(CELL_IS_NODE(obj), obj, SCM_ARG1, FUNC_NAME);
-	gnp = node_from_scm(obj);
+	SCM_ASSERT(CELL_IS_NODE(node), node, SCM_ARG1, FUNC_NAME);
+	gnp = node_from_scm(node);
 	return gnp->node->down ? SCM_BOOL_T : SCM_BOOL_F;
 }
 #undef FUNC_NAME
 
 SCM_DEFINE_PUBLIC(scm_grecs_node_down, "grecs-node-down",
 		  1, 0, 0,
-		  (SCM obj),
-		  "Return parent node of @var{obj}.")
+		  (SCM node),
+"Returns the first child node of @var{node}.")
 #define FUNC_NAME s_scm_grecs_node_down
 {
 	struct _guile_node *gnp;
 	
-	SCM_ASSERT(CELL_IS_NODE(obj), obj, SCM_ARG1, FUNC_NAME);
-	gnp = node_from_scm(obj);
+	SCM_ASSERT(CELL_IS_NODE(node), node, SCM_ARG1, FUNC_NAME);
+	gnp = node_from_scm(node);
 	if (!gnp->node->down)
 		scm_misc_error(FUNC_NAME,
 			       "no down node in ~S",
-			       scm_list_1(obj));
+			       scm_list_1(node));
 	return node_to_scm(gnp->node->down);
 }
 #undef FUNC_NAME
 
 SCM_DEFINE_PUBLIC(scm_grecs_node_next_p, "grecs-node-next?",
 		  1, 0, 0,
-		  (SCM obj),
-		  "Return true if @var{obj} has next node.")
+		  (SCM node),
+"Returns @samp{#t} if @var{node} is followed by another node on the same "
+"nesting level.\n")
 #define FUNC_NAME s_scm_grecs_node_next_p
 {
 	struct _guile_node *gnp;
 	
-	SCM_ASSERT(CELL_IS_NODE(obj), obj, SCM_ARG1, FUNC_NAME);
-	gnp = node_from_scm(obj);
+	SCM_ASSERT(CELL_IS_NODE(node), node, SCM_ARG1, FUNC_NAME);
+	gnp = node_from_scm(node);
 	return gnp->node->next ? SCM_BOOL_T : SCM_BOOL_F;
 }
 #undef FUNC_NAME
 
 SCM_DEFINE_PUBLIC(scm_grecs_node_next, "grecs-node-next",
 		  1, 0, 0,
-		  (SCM obj),
-		  "Return next node from @var{obj}.")
+		  (SCM node),
+"Returns the node following @var{node} on the same nesting level.")
 #define FUNC_NAME s_scm_grecs_node_next
 {
 	struct _guile_node *gnp;
 	
-	SCM_ASSERT(CELL_IS_NODE(obj), obj, SCM_ARG1, FUNC_NAME);
-	gnp = node_from_scm(obj);
+	SCM_ASSERT(CELL_IS_NODE(node), node, SCM_ARG1, FUNC_NAME);
+	gnp = node_from_scm(node);
 	if (!gnp->node->next)
 		scm_misc_error(FUNC_NAME,
 			       "no next node in ~S",
-			       scm_list_1(obj));
+			       scm_list_1(node));
 	return node_to_scm(gnp->node->next);
 }
 #undef FUNC_NAME
 
 SCM_DEFINE_PUBLIC(scm_grecs_node_prev_p, "grecs-node-prev?",
 		  1, 0, 0,
-		  (SCM obj),
-		  "Return true if @var{obj} has a previous node.")
+		  (SCM node),
+"Returns @samp{#t} if @var{node} is preceded by another node on the same\n"
+"nesting level.\n")
 #define FUNC_NAME s_scm_grecs_node_prev_p
 {
 	struct _guile_node *gnp;
 	
-	SCM_ASSERT(CELL_IS_NODE(obj), obj, SCM_ARG1, FUNC_NAME);
-	gnp = node_from_scm(obj);
+	SCM_ASSERT(CELL_IS_NODE(node), node, SCM_ARG1, FUNC_NAME);
+	gnp = node_from_scm(node);
 	return gnp->node->prev ? SCM_BOOL_T : SCM_BOOL_F;
 }
 #undef FUNC_NAME
 
 SCM_DEFINE_PUBLIC(scm_grecs_node_prev, "grecs-node-prev",
 		  1, 0, 0,
-		  (SCM obj),
-		  "Return previous node from @var{obj}.")
+		  (SCM node),
+"Returns the node preceding @var{node} on the same nesting level.\n")
 #define FUNC_NAME s_scm_grecs_node_prev
 {
 	struct _guile_node *gnp;
 	
-	SCM_ASSERT(CELL_IS_NODE(obj), obj, SCM_ARG1, FUNC_NAME);
-	gnp = node_from_scm(obj);
+	SCM_ASSERT(CELL_IS_NODE(node), node, SCM_ARG1, FUNC_NAME);
+	gnp = node_from_scm(node);
 	if (!gnp->node->prev)
 		scm_misc_error(FUNC_NAME,
 			       "no next node in ~S",
-			       scm_list_1(obj));
+			       scm_list_1(node));
 	return node_to_scm(gnp->node->prev);
 }
 #undef FUNC_NAME
 
 SCM_DEFINE_PUBLIC(scm_grecs_node_ident, "grecs-node-ident",
                   1, 0, 0,
-                  (SCM obj),
-"Returns identifier of the node @var{obj}.")
+                  (SCM node),
+"Returns identifier of the node @var{node}.")
 #define FUNC_NAME s_scm_grecs_node_ident
 {
         struct _guile_node *gnp;
-        SCM_ASSERT(CELL_IS_NODE(obj), obj, SCM_ARG1, FUNC_NAME);
-        gnp = node_from_scm(obj);
+        SCM_ASSERT(CELL_IS_NODE(node), node, SCM_ARG1, FUNC_NAME);
+        gnp = node_from_scm(node);
         return scm_from_locale_string(gnp->node->ident ? gnp->node->ident : "");
 }
 #undef FUNC_NAME
 
 SCM_DEFINE_PUBLIC(scm_grecs_node_path_list, "grecs-node-path-list",
 		  1, 0, 0,
-		  (SCM obj),
-		  "Return a pathlist of @var{obj}.")
+		  (SCM node),
+"Returns the full path to the node, converted to a list. Each list element "
+"corresponds to a subnode identifier.  A subnode which has a tag is "
+"represented by a cons, whose car contains the subnode identifier, and cdr "
+"its value.  For example, the following path:\n\n"
+"@example\n"
+".foo.bar=x.baz\n"
+"@end example\n\n"
+"@noindent\n"
+"is represented as\n\n"
+"@lisp\n"
+"'(\"foo\" (\"bar\" . \"x\") \"baz\")\n"
+"@end lisp\n")
 #define FUNC_NAME s_scm_grecs_node_path_list
 {
-	struct grecs_node *node;
+	struct grecs_node *np;
 	struct _guile_node *gnp;
 	SCM scm_head = SCM_EOL;
 	
-	SCM_ASSERT(CELL_IS_NODE(obj), obj, SCM_ARG1, FUNC_NAME);
-	gnp = node_from_scm(obj);
-	for (node = gnp->node; node; node = node->up) {
+	SCM_ASSERT(CELL_IS_NODE(node), node, SCM_ARG1, FUNC_NAME);
+	gnp = node_from_scm(node);
+	for (np = gnp->node; np; np = np->up) {
 		SCM newent, cell;
 
-		if (node->type == grecs_node_root)
+		if (np->type == grecs_node_root)
 			break;
-		if (node->type == grecs_node_stmt || !node->v.value)
-			cell = scm_from_locale_string(node->ident);
+		if (np->type == grecs_node_stmt || !np->v.value)
+			cell = scm_from_locale_string(np->ident);
 		else
-			cell = scm_cons(scm_from_locale_string(node->ident),
-					scm_from_grecs_value(node->v.value));
+			cell = scm_cons(scm_from_locale_string(np->ident),
+					scm_from_grecs_value(np->v.value));
 		newent = scm_cons(cell, scm_head);
 		scm_head = newent;
 	}
@@ -429,23 +458,22 @@ fmtpathcomp(const char *str, void *data)
 
 SCM_DEFINE_PUBLIC(scm_grecs_node_path, "grecs-node-path",
 		  1, 1, 0,
-		  (SCM obj, SCM delim),
-		  "Return path of the node @var{obj}.")
+		  (SCM node, SCM delim),
+"Returns the full path to the @var{node} (a string).")
 #define FUNC_NAME s_scm_grecs_node_path
 {
-	struct grecs_node *node;
 	struct _guile_node *gnp;
 	struct grecs_format_closure clos;
 	struct scmlist list = { SCM_EOL, SCM_EOL };
 	char delim_chr = 0;
 	
-	SCM_ASSERT(CELL_IS_NODE(obj), obj, SCM_ARG1, FUNC_NAME);
+	SCM_ASSERT(CELL_IS_NODE(node), node, SCM_ARG1, FUNC_NAME);
 	if (!SCM_UNBNDP(delim)) {
 		SCM_ASSERT(scm_is_true(scm_char_p(delim)), delim,
 			   SCM_ARG2, FUNC_NAME);
 		delim_chr = scm_to_int(scm_char_to_integer(delim));
 	}
-	gnp = node_from_scm(obj);
+	gnp = node_from_scm(node);
 
 	clos.fmtfun = fmtpathcomp;
 	clos.data = &list;
@@ -458,28 +486,48 @@ SCM_DEFINE_PUBLIC(scm_grecs_node_path, "grecs-node-path",
 
 SCM_DEFINE_PUBLIC(scm_grecs_node_type, "grecs-node-type",
 		  1, 0, 0,
-		  (SCM obj),
-		  "Return a pathlist of @var{obj}.")
+		  (SCM node),
+"Returns the type of the node.  The following constants are defined:\n\n"
+"@table @asis\n"
+"@kwindex grecs-node-root\n"		  
+"@item grecs-node-root\n"
+"The node is a root node.  The following is always @samp{#t}:\n\n"
+"@lisp\n"
+"(and (= (grecs-node-type node) grecs-node-root)\n"
+"     (not (grecs-node-up? node))\n"
+"     (not (grecs-node-prev? node)))\n"
+"@end lisp\n"
+"@kwindex grecs-node-stmt\n"		  
+"@item grecs-node-stmt\n"
+"The node is a simple statement.  The following is always @samp{#t}:\n\n"
+"@lisp\n"
+"(and (= (grecs-node-type node) grecs-node-stmt)\n"
+"     (not (grecs-node-down? node)))\n"
+"@end lisp\n"
+"@kwindex grecs-node-block\n"		  
+"@item grecs-node-block\n"
+"The node is a block statement.\n"
+"@end table\n")
 #define FUNC_NAME s_scm_grecs_node_type
 {
 	struct _guile_node *gnp;
 	
-	SCM_ASSERT(CELL_IS_NODE(obj), obj, SCM_ARG1, FUNC_NAME);
-	gnp = node_from_scm(obj);
+	SCM_ASSERT(CELL_IS_NODE(node), node, SCM_ARG1, FUNC_NAME);
+	gnp = node_from_scm(node);
 	return scm_from_int(gnp->node->type);
 }
 #undef FUNC_NAME
 
 SCM_DEFINE_PUBLIC(scm_grecs_node_has_value_p, "grecs-node-has-value?",
 		  1, 0, 0,
-		  (SCM obj),
-		  "Return @samp{true} if @var{obj} has a value.")
+		  (SCM node),
+"Returns @samp{#t} if @var{node} has a value.")
 #define FUNC_NAME s_scm_grecs_node_has_value_p
 {
 	struct _guile_node *gnp;
 	
-	SCM_ASSERT(CELL_IS_NODE(obj), obj, SCM_ARG1, FUNC_NAME);
-	gnp = node_from_scm(obj);
+	SCM_ASSERT(CELL_IS_NODE(node), node, SCM_ARG1, FUNC_NAME);
+	gnp = node_from_scm(node);
 	return (gnp->node->type != grecs_node_root && gnp->node->v.value) ?
 		SCM_BOOL_T : SCM_BOOL_F;
 }
@@ -536,18 +584,18 @@ scm_from_grecs_value(struct grecs_value *val)
 
 SCM_DEFINE_PUBLIC(scm_grecs_node_value, "grecs-node-value",
 		  1, 0, 0,
-		  (SCM obj),
-"Return the value of @var{obj}.")
+		  (SCM node),
+"Returns the value of @var{node}.")
 #define FUNC_NAME s_scm_grecs_node_value
 {
 	struct _guile_node *gnp;
 	
-	SCM_ASSERT(CELL_IS_NODE(obj), obj, SCM_ARG1, FUNC_NAME);
-	gnp = node_from_scm(obj);
+	SCM_ASSERT(CELL_IS_NODE(node), node, SCM_ARG1, FUNC_NAME);
+	gnp = node_from_scm(node);
 	if (gnp->node->type == grecs_node_root || !gnp->node->v.value)
 		scm_misc_error(FUNC_NAME,
 			       "no value in ~S",
-			       scm_list_1(obj));
+			       scm_list_1(node));
 	return scm_from_grecs_value(gnp->node->v.value);
 }
 #undef FUNC_NAME
@@ -555,7 +603,10 @@ SCM_DEFINE_PUBLIC(scm_grecs_node_value, "grecs-node-value",
 SCM_DEFINE_PUBLIC(scm_grecs_node_locus, "grecs-node-locus",
 		  1, 0, 0,
 		  (SCM node),
-"Return locus of the @var{node}.")
+"Returns source location of the @var{node}.  Returned value is a cons:\n\n"
+"@lisp\n"
+"(@var{file-name} . @var{line-number})\n"
+"@end lisp\n")
 #define FUNC_NAME s_scm_grecs_node_locus
 {
 	struct _guile_node *gnp;
@@ -572,7 +623,8 @@ SCM_DEFINE_PUBLIC(scm_grecs_node_locus, "grecs-node-locus",
 SCM_DEFINE_PUBLIC(scm_grecs_find_node, "grecs-find-node",
 		  2, 0, 0,
 		  (SCM node, SCM path),
-"Find @var{path} starting from @var{node}.")
+"Returns the first node whose path is @var{path}.  Starts search from "
+"@var{node}.")
 #define FUNC_NAME s_scm_grecs_find_node
 {
 	struct _guile_node *gnp;
@@ -594,7 +646,8 @@ SCM_DEFINE_PUBLIC(scm_grecs_find_node, "grecs-find-node",
 SCM_DEFINE_PUBLIC(scm_grecs_match_first, "grecs-match-first",
 		  2, 0, 0,
 		  (SCM node, SCM pattern),
-"Find first node matching @var{pattern} starting from @var{node}.")
+"Returns the first node whose path matches @var{pattern}.  "
+"The search is started from @var{node}.\n")
 #define FUNC_NAME s_scm_grecs_match_first
 {
 	struct _guile_node *gnp;
@@ -621,9 +674,18 @@ SCM_DEFINE_PUBLIC(scm_grecs_match_first, "grecs-match-first",
 SCM_DEFINE_PUBLIC(scm_grecs_match_next, "grecs-match-next",
 		  1, 0, 0,
 		  (SCM node),
-"Look for the next match starting after @var{node}.  @var{node} must\n"
-"have been returned by a previous call to grecs-match-first or\n"
-"grecs-match-next.")
+"@var{Node} must be a node returned by a previous call to "
+"@code{grecs-match-first} or @samp{grecs-match-next}. "
+"The function returns next node matching the initial pattern, or @samp{#f} "
+"if no more matches are found.  For example, the following code iterates "
+"over all nodes matching @var{pattern}:\n\n"
+"@lisp\n"
+"(define (iterate-nodes root pattern thunk)\n"
+"  (do ((node (grecs-match-first root pattern)\n"
+"             (grecs-match-next node)))\n"
+"      ((not node))\n"
+"     (thunk node)))\n"
+"@end lisp\n")
 #define FUNC_NAME s_scm_grecs_match_next
 {
 	struct _guile_node *gnp;