From 41c55a1a93840363c996fc9aae54329dadcf0a86 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Wed, 9 Dec 2009 15:48:09 +0200 Subject: 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. --- doc/Makefile.am | 22 ++++++++- doc/fix-sentence-spacing.sed | 4 ++ doc/pies.texi | 113 +++++++++++++++++++++++++++++++------------ 3 files changed, 106 insertions(+), 33 deletions(-) create mode 100644 doc/fix-sentence-spacing.sed (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am index 6d47f51..73bd72a 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -23,6 +23,7 @@ pies_TEXINFOS=\ EXTRA_DIST = \ check-docs.sh\ + fix-sentence-spacing.sed\ gendocs_template\ mastermenu.el\ untabify.el @@ -31,12 +32,20 @@ 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' \ @@ -130,7 +139,16 @@ master-menu: 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. 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 @@ -312,7 +312,7 @@ directives any time by running @command{pies --config-help}. 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. @@ -649,20 +649,20 @@ disabled by @command{pies}, even if they respawn too fast. 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 @@ -831,6 +831,11 @@ 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 @@ -1023,19 +1028,23 @@ statement. You must also declare a socket to listen on. 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 @@ -1058,15 +1067,57 @@ For example: 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 @@ -1738,7 +1789,7 @@ return-code (EX_USAGE, EX_CONFIG) @{ 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@}'' @@ -1962,7 +2013,7 @@ 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}. @@ -2000,13 +2051,13 @@ 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. @@ -2018,7 +2069,7 @@ 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} -- cgit v1.2.1