summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org>2019-07-10 06:54:32 (GMT)
committer Sergey Poznyakoff <gray@gnu.org>2019-07-10 06:54:32 (GMT)
commitd36275fe9adf1428fd2476defda9e1fcda56988a (patch) (side-by-side diff)
tree0d5c9b9aabac887a100934118955ed7736690a98
parent5742ab5a037160a115144b3bf45cf3349df24635 (diff)
downloadwordsplit-d36275fe9adf1428fd2476defda9e1fcda56988a.tar.gz
wordsplit-d36275fe9adf1428fd2476defda9e1fcda56988a.tar.bz2
Improve docs
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--README71
-rw-r--r--wordsplit.314
2 files changed, 47 insertions, 38 deletions
diff --git a/README b/README
index c08b680..59f3436 100644
--- a/README
+++ b/README
@@ -2,8 +2,11 @@
-This package provides a set of C functions for splitting a string into
-words. The splitting process is highly configurable and allows for
-considerable flexibility. The default splitting rules are similar to
-those used in Bourne shell. The splitting process includes tilde
-expansion, variable expansion, quote removal, command substitution,
-and path expansion. Each of these phases can be turned off by the caller.
+This package provides a set of C functions for parsing input strings.
+Default parsing rules are are similar to those used in Bourne shell.
+This includes tilde expansion, variable expansion, quote removal, word
+splitting, command substitution, and path expansion. Parsing is
+controlled by a number of settings which allow the caller to alter
+processing at each of these phases or even to disable any of them.
+Thus, wordsplit can be used for parsing inputs in different formats,
+from simple character-delimited entries, as in /etc/passwd, and up to
+complex shell statements.
@@ -11,3 +14,3 @@ The following code fragment shows the basic usage:
- /* This variable controls the splitting */
+ /* This variable controls parsing */
wordsplit_t ws;
@@ -33,3 +36,3 @@ The following code fragment shows the basic usage:
-For a detailed discussion, please see the man page wordsplit.3 inluded
+For a detailed discussion, please see the man page wordsplit.3 included
in the package.
@@ -53,16 +56,21 @@ are for building the autotest-based testsuite:
-The project is designed to be used as a git submodule. First, select
-the location DIR for the wordsplit directory within your project. Then
-add the submodule:
+The project is designed to be used as a git submodule. To incorporate
+it into your project, first select the location for the wordsplit
+directory within your project. Then add the submodule at this
+location. The rest is quite straightforward: you need to add
+wordsplit.c to your sources and add both wordsplit.c and wordsplit.h
+to the distributed files.
+
+The following will describe each step in detail. For the rest of this
+discussion it is supposed that 'wordsplit' is the name of the location
+selected for the submodule. It is also supposed that your project
+uses GNU autotools framework. If you are using plain makefiles, these
+instructions are easy to convert to such use as well.
- git submodule add git://git.gnu.org.ua/wordsplit.git DIR
+To add the submodule do:
-The rest is quite straightforward: you need to add wordsplit.c to your
-sources and add both wordsplit.c and wordsplit.h to the distributed files.
+ git submodule add git://git.gnu.org.ua/wordsplit.git wordsplit
-There are two methods of doing so: direct incorporation and
-incorporation via VPATH. The discussion below will describe both
-methods based on the assumption that your project is using GNU
-autotools framework. If you are using plain makefiles, these
-instructions are easy to convert to such use as well.
+There are two methods of including the sources to the project: direct
+incorporation and incorporation via VPATH.
@@ -90,4 +98,4 @@ You can also put wordsplit.h in the noinst_HEADERS variable, if you like:
-If you are building an installable library and wish to make wordsplit functions
-available, install wordsplit.h to $(pkgincludedir), e.g.
+If you are building an installable library and wish to export the
+wordsplit API, install wordsplit.h to $(pkgincludedir), e.g.
@@ -99,3 +107,3 @@ available, install wordsplit.h to $(pkgincludedir), e.g.
-** Vpath-based incorporation
+** VPATH-based incorporation
@@ -107,3 +115,3 @@ Notice the use of "+=": it is necessary for the vpath builds to work.
-Define the nodist_program_SOURCES variable:
+Add wordsplit.c to the nodist_program_SOURCES variable:
@@ -113,3 +121,3 @@ The nodist_ prefix is necessary to prevent Make from trying to
distribute this file from the current directory (where it doesn't
-exist of course). It will find it using VPATH during compilation.
+exist of course). During compilation it will be located using VPATH.
@@ -198,3 +206,3 @@ Add the following lines to your configure.ac:
-The makefile in lib must be modified to build the auxiliary program
+The Makefile.am in lib must be modified to build the auxiliary program
wsp and create the testsuite script. This is done by the following
@@ -230,7 +238,7 @@ fragment:
First version of wordsplit appeared in March 2009 as a part of the
-Wydawca[1] project. Its main usage there was to assist in
-configuration file parsing. The parser subsystem proved to be quite
-useful and it soon forked into a separate project - Grecs[2]. This
-package had been since used (as a git submodule) in a number of other
-projects, such as GNU Dico[3] and Direvent[4], to name a few.
+Wydawca[1] project. Its main usage was to assist in configuration
+file parsing. The parser subsystem proved to be quite useful and
+soon evolved into a separate project - Grecs[2]. This package had been
+since used (as a git submodule) in a number of other projects, such as
+GNU Dico[3] and Direvent[4], to name a few.
@@ -240,3 +248,4 @@ Mailutils uses its own configuration package, which meant that using
Grecs was not expedient. Therefore the sources had been exported from
-Grecs and are kept in sync with the changes in it.
+Grecs. Since then both Mailutils and Grecs versions are periodically
+synchronized.
diff --git a/wordsplit.3 b/wordsplit.3
index 139c73e..e742030 100644
--- a/wordsplit.3
+++ b/wordsplit.3
@@ -335,3 +335,3 @@ initialized. This member provides escape tables for unquoted words
(\fBws_escape[0]\fR) and quoted strings (\fBws_escape[1]\fR). Each
-table is a string consisting of an even number of charactes. In each
+table is a string consisting of an even number of characters. In each
pair of characters, the first one is a character that can appear after
@@ -602,6 +602,6 @@ strings (\fBws_escape[1]\fR). These are used to translate escape
sequences (\fB\\\fIC\fR) into characters. Each table is a string
-consisting of even number of charactes. In each pair of characters,
+consisting of even number of characters. In each pair of characters,
the first one is a character that can appear after backslash, and the
following one is its representation. For example, the string
-\fB\(dqt\\tn\\n\(dq\fR translates \fB\\t\fR into horisontal
+\fB\(dqt\\tn\\n\(dq\fR translates \fB\\t\fR into horizontal
tabulation character and \fB\\n\fR into newline.
@@ -757,4 +757,4 @@ Default flags. This is a shortcut for:
-i.e.: disable variable expansion and quote substituton, perform quote
-removal, treat any number of consequtive delimiters as a single
+i.e.: disable variable expansion and quote substitution, perform quote
+removal, treat any number of consecutive delimiters as a single
delimiter, replace \fBC\fR escapes appearing in the input string with
@@ -809,3 +809,3 @@ function is called instead. This function is not supposed to return.
.B WRDSF_WS
-Trim off any leading and trailind whitespace from the returned
+Trim off any leading and trailing whitespace from the returned
words. This flag is useful if the \fIws_delim\fR member does not
@@ -1009,3 +1009,3 @@ Undefined variable. This error is returned only if the
.B WRDSE_NOINPUT
-Input exhausted. This is not acually an error. This code is returned
+Input exhausted. This is not actually an error. This code is returned
if \fBwordsplit\fR (or \fBwordsplit_len\fR) is invoked in incremental

Return to:

Send suggestions and report system problems to the System administrator.