aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2009-12-09 15:48:09 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2009-12-09 15:48:09 +0200
commit41c55a1a93840363c996fc9aae54329dadcf0a86 (patch)
tree737d4789555e44ee1dc7356ae1edcad54cdee623 /doc
parentb63563c9c5271d088d80a31f780be74d1c16fef4 (diff)
downloadpies-41c55a1a93840363c996fc9aae54329dadcf0a86.tar.gz
pies-41c55a1a93840363c996fc9aae54329dadcf0a86.tar.bz2
Improve docs.
* doc/fix-sentence-spacing.sed: New file. * doc/Makefile.am (EXTRA_DIST): Add fix-sentence-spacing.sed. (check-tabs, check-sentence-spacing) (fix-sentence-spacing): New rules. (check-format): Rewrite rule. * doc/pies.texi: Update.
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am22
-rw-r--r--doc/fix-sentence-spacing.sed4
-rw-r--r--doc/pies.texi113
3 files changed, 106 insertions, 33 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 6d47f51..73bd72a 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -20,26 +20,35 @@ pies_TEXINFOS=\
macros.texi\
rendition.texi\
usr-acl.texi
EXTRA_DIST = \
check-docs.sh\
+ fix-sentence-spacing.sed\
gendocs_template\
mastermenu.el\
untabify.el
clean-local:
@rm -rf manual
# Checking
-check-format:
+check-tabs:
@if test -n "`cat $(info_TEXINFOS) $(pies_TEXINFOS) | tr -d -c '\t'`"; then \
echo "Sources contain tabs; run make untabify"; \
false; \
fi
+check-sentence-spacing:
+ @if cat $(info_TEXINFOS) $(pies_TEXINFOS) | sed 's/i\.e\. //g;s/e\.g\. //g;s/\.\.\. @//g' | grep -q '\. [@A-Z]'; then \
+ echo >&2 "Sources contain single-space sentence separators"; \
+ echo >&2 "Run make fix-sentence-spacing to fix"; \
+ fi
+
+check-format: check-tabs check-sentence-spacing
+
check-options:
@check-docs.sh options \
'/argp_option options\[\] = /,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \
's/@opindex *\([^@,]*\).*/\1/p' \
$(top_srcdir)/src/pies.c -- \
$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
@@ -127,13 +136,22 @@ check-docs:
master-menu:
$(AM_V_GEN)emacs -batch -l mastermenu.el -f make-master-menu $(info_TEXINFOS)
untabify:
@emacs -batch -l untabify.el $(info_TEXINFOS) $(pies_TEXINFOS)
-final: untabify master-menu
+fix-sentence-spacing:
+ for file in $(info_TEXINFOS) $(wydawca_TEXINFOS); \
+ do \
+ if grep -q '\. [@A-Z]' $$file; then \
+ mv $$file $${file}~; \
+ sed -r 's/\. ([@A-Z])/. \1/g' $${file}~ > $$file; \
+ fi; \
+ done
+
+final: untabify fix-sentence-spacing master-menu
# The rendering level is one of PUBLISH, DISTRIB or PROOF.
# Just call `make RENDITION=PROOF [target]' if you want PROOF rendition.
MAKEINFOFLAGS=-D$(RENDITION)
diff --git a/doc/fix-sentence-spacing.sed b/doc/fix-sentence-spacing.sed
new file mode 100644
index 0000000..906a670
--- /dev/null
+++ b/doc/fix-sentence-spacing.sed
@@ -0,0 +1,4 @@
+s/\. ([@A-Z])/. \1/g
+s/e\.g\. /e.g. /g
+s/i\.e\. /i.e. /g
+s/\.\.\. @\}/... @}/g
diff --git a/doc/pies.texi b/doc/pies.texi
index 96cbfb5..e21ea62 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -309,13 +309,13 @@ directives any time by running @command{pies --config-help}.
@node Syntax
@section Configuration File Syntax
The configuration file consists of statements and comments.
There are three classes of lexical tokens: keywords, values, and
-separators. Blanks, tabs, newlines and comments, collectively called
+separators. Blanks, tabs, newlines and comments, collectively called
@dfn{white space} are ignored except as they serve to separate
tokens. Some white space is required to separate otherwise adjacent
keywords and values.
@menu
* Comments::
@@ -646,26 +646,26 @@ Mark this component as @dfn{precious}. Precious components are never
disabled by @command{pies}, even if they respawn too fast.
@item wait
This flag is valid only for @samp{inetd} components. It has the same
meaning as @samp{wait} in @file{inetd.conf} file, i.e. it tells
@command{pies} to wait for the server program to
-return. @FIXME-xref{inetd}.
+return. @FIXME-xref{inetd}.
@item tcpmux
-This is a @acronym{TCPMUX} component. @FIXME-xref{tcpmux}.
+This is a @acronym{TCPMUX} component. @xref{TCPMUX}.
@item tcpmuxplus
-This is a @acronym{TCPMUX+} component. @FIXME-xref{tcpmux}.
+This is a @acronym{TCPMUX+} component. @xref{TCPMUX}.
@item internal
-This is an internal inetd component. @FIXME-xref{internal inetd}.
+This is an internal inetd component. @xref{builtin}.
@item sockenv
This inetd component wants socket description variables in its
-environment. @FIXME-xref{sockenv}.
+environment. @FIXME-xref{sockenv}.
@item resolve
When used with @samp{sockenv}, the @env{LOCALHOST} and
@env{REMOTEHOST} environment variables will contain resolved host
names, instead of IP addresses.
@end table
@@ -828,12 +828,17 @@ value. If no such variable is present in the environment, it is
created and @var{value} is assigned to it. However, if @var{value}
ends with a punctuation character, this character is removed from it
before assignment.
@end table
@end deffn
+@deffn {Config: component} max-instances @var{n}
+Sets the maximum number of simultaneously running instances of this
+component.
+@end deffn
+
@node Actions Before Startup
@subsection Actions Before Startup
Several statements are available that specify actions to perform
immediately before starting the component:
@@ -1020,25 +1025,29 @@ statement. You must also declare a socket to listen on.
@anchor{inetd-socket}
@deffn {Config: component} socket @var{url}
Define a socket to listen on. Allowed values for @var{url} are:
@table @asis
-@item file name
-Specifies a @acronym{UNIX} socket file name. You may use a relative
-file name, provided that @code{chdir} statement is used for this
-component (@pxref{Actions Before Startup, chdir}).
-
-@item local://@var{file}[;@var{args}]
-@itemx file://@var{file}[;@var{args}]
-@itemx unix://@var{file}[;@var{args}]
+@flindex /etc/protocols
+@item inet[+@var{proto}]://@var{ip}:@var{port}
+Listen on IPv4@footnote{Support for IPv6 will be added in future
+versions.}. address @var{ip} (may be given as a symbolic host name),
+on port @var{port}. Optional @var{proto} defines the protocol
+to use. It must be a valid protocol name as given in
+@file{/etc/protocols}. Default is @samp{tcp}.
+
+@item local[+@var{proto}]://@var{file}[;@var{args}]
+@itemx file[+@var{proto}]://@var{file}[;@var{args}]
+@itemx unix[+@var{proto}]://@var{file}[;@var{args}]
Listen on the @acronym{UNIX} socket file @var{file}, which is either
-an absolute or relative file name, as described above. Optional
-arguments @var{args} control ownership and file mode of @var{file}. They
-are a list of assignments, separated by semicolons. The following
-values are allowed:
+an absolute or relative file name, as described above. The
+@var{proto} part is as described above. Optional arguments, @var{args},
+control ownership and file mode of @var{file}. They are a list of
+assignments, separated by semicolons. The following values are
+allowed:
@table @asis
@item user
User name of the socket owner.
@item group
@@ -1055,21 +1064,63 @@ and @samp{777}).
For example:
@smallexample
socket "unix:/var/run/socket;user=nobody;group=mail;mode=770";
@end smallexample
-@item inet://@var{ip}:@var{port}
-Listen on IPv4 address @var{ip} (may be given as a symbolic host name),
-on port @var{port}.
+@item file name
+Specifies a @acronym{UNIX} socket file name. It is a shortcut for
+@samp{unix:@var{file-name}}. You may use a relative file name,
+provided that @code{chdir} statement is used for this component
+(@pxref{Actions Before Startup, chdir}).
@end table
+@end deffn
+
+@deffn {Config: component} socket-type @var{type}
+Sets the socket type. Allowed values for @var{type} are:
+@samp{stream}, @samp{dgram}, @samp{raw}, @samp{rdm},
+@samp{seqpacket}. Default is @samp{stream}. Notice that
+some socket types may not be implemented by all protocol
+families, e.g. @samp{seqpacket} is not implemented for
+@samp{inet}.
+@end deffn
+
+@anchor{max-rate}
+@deffn {Config: component} max-rate @var{n}
+Specifies the maximum number of times the component can be invoked in
+one minute; the default is unlimited. A rate of @samp{0} stands for
+@samp{unlimited}.
+@end deffn
+
+@deffn {Config: component} max-instances @var{n}
+Sets the maximum number of simultaneously running instances of this
+component. It is equivalent to the maximum number of simultaneously
+opened connections.
+@end deffn
+
+@menu
+* builtin:: Built-in Inetd Services
+* TCPMUX:: TCPMUX Services
+@end menu
+
+@node builtin
+@subsubsection Built-in Inetd Services
+@cindex builtin services
+@WRITEME
+
+@node TCPMUX
+@subsubsection TCPMUX Services
+@cindex TCPMUX
+@UNREVISED
+
+@deffn {Config: component} service @var{name}
+Sets the name of the service for TCPMUX sub-services.
+@end deffn
-Notice, that @command{pies} version @value{VERSION} handles only
-@acronym{TCP} sockets and only IPv4 addresses. Support for IPv6 will
-be added in future versions. Support for @acronym{UDP} sockets will
-be added if there is a demand.
+@deffn {Config: component} tcpmux-master @var{name}
+Sets the name of the master TCPMUX service.
@end deffn
@node Meta1-Style Components
@subsection Meta1-Style Components
@cindex meta1-style components
Meta1-style components are declared using @code{mode pass}
@@ -1735,13 +1786,13 @@ return-code (EX_USAGE, EX_CONFIG) @{
From: Pies <>
X-Agent: $@{canonical-program-name@} ($@{package@} $@{version@})
Subject: Component $@{component@} disabled.
Component "$@{component@}" has terminated with code $@{retcode@},
which means it encountered some configuration problem.
- I will not restart it automatically. Please fix its configuration
+ I will not restart it automatically. Please fix its configuration
and restart it manually at your earliest convenience.
To restart, run ``$@{program-name@} -R $@{component@}''
---
Wuff-wuff,
Pies
@@ -1959,13 +2010,13 @@ Remain in foreground.
@item --help
Display a short usage summary and exit.
@opsummary{inetd}
@item --inetd
@itemx -i
-Run in @command{inetd}-compatibility mode. It is roughly
+Run in @command{inetd}-compatibility mode. It is roughly
equivalent to @command{pies --instance=inetd --syntax=inetd}.
@FIXME-xref{inetd}.
@opsummary{instance}
@item --instance=@var{name}
Define the name of the @command{pies} @dfn{instance}. @FIXME-xref{instances}.
@@ -1997,31 +2048,31 @@ Stop the running instance.
Define the syntax for parsing the configuration files specified by any
@option{--config-file} options that follow this one. Possible values
for @var{type} are:
@table @asis
@item pies
-Native @command{pies} configuration. @xref{Pies Configuration File}.
+Native @command{pies} configuration. @xref{Pies Configuration File}.
@item inetd
-@samp{Inetd}-style configuration files. @FIXME-xref{inetd}.
+@samp{Inetd}-style configuration files. @FIXME-xref{inetd}.
@item meta1
-@samp{meta1}-style configuration files. @FIXME-xref{meta1}.
+@samp{meta1}-style configuration files. @FIXME-xref{meta1}.
@end table
@xref{config syntax}, for a detailed description of this option.
@opsummary{syslog}
@item --syslog
Log to syslog. This is the default.
@opsummary{rate}
@item --rate=@var{r}
Set maximum connection rate (connections per second) for inetd-style
-components. @FIXME-xref{inetd rate}.
+components. @xref{max-rate,, inetd component rate}.
@opsummary{reload}
@opsummary{hup}
@item -r
@itemx --reload
@itemx --hup

Return to:

Send suggestions and report system problems to the System administrator.