Update the docs.

2 files changed, 68 insertions, 6 deletions

diff --git a/doc/grecs_error.3 b/doc/grecs_error.3
index 4f82dc5..1c2b62f 100644
--- a/doc/grecs_error.3
+++ b/doc/grecs_error.3
@@ -11,13 +11,13 @@
 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 .\" GNU General Public License for more details.
 .\"
 .\" You should have received a copy of the GNU General Public License
 .\" along with Grecs.  If not, see <http://www.gnu.org/licenses/>.
 .\"
-.TH GRECS_ERROR 3 "May 4, 2011" "GRECS" "Grecs User Reference"
+.TH GRECS_ERROR 3 "July 1, 2011" "GRECS" "Grecs User Reference"
 .SH NAME
 grecs_error, grecs_warning \- grecs error reporting functions
 .SH SYNOPSIS
 .nf
 .B #include <grecs.h>
 .sp
@@ -83,25 +83,79 @@ condition and \fB0\fR otherwise (i.e. a warning).
 .I errnum
 System error code, or \fB0\fR, if no system error occurred.
 .TP
 .I msg
 Formatted message.
 .PP
-The \fBgrecs_locus_t\fR structure is defined as:
+The \fBgrecs_locus_t\fR structure consists of two \fBpoints\fR, each
+point describing the beginning and the end of the input fragment in
+question:
 .sp
 .nf
 .in +5
-typedef struct {
+struct grecs_locus_point {
      char *file;
-     int line;
+     unsigned line;
+     unsigned col;
+};
+typedef struct {
+     struct grecs_locus_point beg;
+     struct grecs_locus_point end;
 } grecs_locus_t;
 .in
 .fi
 .PP
 The \fBfile\fR member points to the file name, and the \fBline\fR
-member contains the input line number.
+member contains the input line number and the \fBcol\fR member
+contains the column number. Both lines and columns are numbered from
+1.
+.PP
+On output, the \fBgrecs_locus_t\fR structure is formatted as follows:
+.sp
+.nf
+.in +5
+\fBBEGFILE\fR:\fBBEGLINE\fR.\fBBEGCOL\fR\-\fBENDFILE\fR:\fBENDLINE\fR.\fBENDCOL\fR
+.in
+.fi
+.PP
+If \fBBEGFILE\fR equals \fBENDFILE\fR in the sense of
+.BR strcmp (3),
+then the output is contracted to:
+.sp
+.nf
+.in +5
+\fBFILE\fR:\fBBEGLINE\fR.\fBBEGCOL\fR\-\fBENDLINE\fR.\fBENDCOL\fR
+.in
+.fi
+.PP
+Furthermore, if \fBBEGLINE\fR equals \fBENDLINE\fR, then the format
+is:
+.sp
+.nf
+.in +5
+\fBFILE\fR:\fBLINE\fR.\fBBEGCOL\fR\-\fBENDCOL\fR
+.in
+.fi
+.PP
+Finally, if \fBBEGCOL\fR\ equals \fBENDCOL\fR, the output is
+simplified to
+.sp
+.nf
+.in +5
+\fBFILE\fR:\fBLINE\fR.\fBCOL\fR
+.in
+.fi
+.PP
+If \fBbeg.col\fR is \fB0\fR, then only the \fBbeg\fR part is
+formatted:
+.sp
+.nf
+.in +5
+\fBFILE\fR:\fBLINE\fR
+.in
+.fi
 .SH RETURN VALUE
 None.
 .SH "SEE ALSO"
 .BR errno (3)
 .SH AUTHORS
 Sergey Poznyakoff
diff --git a/doc/grecs_parse.3 b/doc/grecs_parse.3
index dff6759..a8b70ca 100644
--- a/doc/grecs_parse.3
+++ b/doc/grecs_parse.3
@@ -11,13 +11,13 @@
 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 .\" GNU General Public License for more details.
 .\"
 .\" You should have received a copy of the GNU General Public License
 .\" along with Grecs.  If not, see <http://www.gnu.org/licenses/>.
 .\"
-.TH GRECS_PARSE 3 "May 7, 2011" "GRECS" "Grecs User Reference"
+.TH GRECS_PARSE 3 "July 1, 2011" "GRECS" "Grecs User Reference"
 .SH NAME
 grecs_parse \- parse a configuration file.
 .SH SYNOPSIS
 .nf
 .B #include <grecs.h>
 .sp
@@ -43,12 +43,13 @@ typedef struct grecs_node {
      grecs_locus_t locus;
      struct grecs_node *up;
      struct grecs_node *down;
      struct grecs_node *next;
      struct grecs_node *prev;
      char *ident;
+     grecs_locus_t idloc;
      union {
           struct grecs_value *value;
           struct grecs_symtab *texttab;
      } v;
 } grecs_node_t;
 .in
@@ -96,12 +97,15 @@ example, a node corresponding to the input line:
 pidfile "/var/run/mypid";
 .in
 .fi
 .sp
 will have \fBident\fR pointing to the string \fB/var/run/mypid\fR.
 .PP
+The \fIidloc\fR contains the location of the identifier portion in the
+input file. Notice, that it differs from \fBlocus\fR described above.
+.PP
 The \fBv\fR union keeps data which depend on the type of this node.
 The \fBv.texttab\fR member is defined only for the root node (type
 \fBgrecs_node_root\fR). It points to a symbol table which holds shared
 strings for this tree. In particular, this table holds file names
 referenced by \fBlocus\fR members of all underlying nodes.
 .PP
@@ -109,12 +113,13 @@ For non-root nodes,the \fBv.value\fR member is defined.  It points to
 the value associated with this statement.  A value is defined as:
 .sp
 .nf
 .in +5
 typedef struct grecs_value {
      int type;
+     grecs_locus_t locus;
      union {
           struct grecs_list *list;
           char *string;
           struct {
                size_t c;
                struct grecs_value **v;
@@ -135,12 +140,15 @@ Actual string value is pointed to by \fBv.string\fR.
 .B GRECS_TYPE_LIST
 The list value is pointed to by \fBv.list\fR.
 .TP
 .B GRECS_TYPE_ARRAY
 The array itself is stored in \fBv.arg.v\fR.  The \fBv.arg.c\fR member
 contains the number of elements in the array.
+.PP
+The \fBlocus\fR member contains the location of this value in the
+input file.
 .SH RETURN VALUE
 On success, a pointer to the root node.  On error, \fBNULL\fR.
 .SH EXAMPLE
 The following program parses the file and prints its contents on
 screen:
 .sp