diff options
-rw-r--r-- | ChangeLog | 6 | ||||
-rw-r--r-- | doc/Makefile.am | 2 | ||||
-rwxr-xr-x | doc/gendocs.sh | 310 | ||||
-rwxr-xr-x | doc/gendocs_template | 10 | ||||
-rw-r--r-- | doc/mailfromd.texi | 59 |
5 files changed, 364 insertions, 23 deletions
@@ -1,5 +1,11 @@ 2007-10-23 Sergey Poznyakoff <gray@gnu.org.ua> + * doc/mailfromd.texi: Do not use subheading commands inside of + deffn. + * doc/Makefile.am + * doc/gendocs.sh: New file. A customized version. + * doc/gendocs_template: Update + * configure.ac, src/syslog_async.c, src/syslog_async.h, src/main.c, src/Makefile.am: Reimplement syslog-async. Thanks Simon Kelley for relicensing it under GPLv3. diff --git a/doc/Makefile.am b/doc/Makefile.am index 3ecc4b7e..77ac5efe 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -127,7 +127,7 @@ final: untabify master-menu MAKEINFOFLAGS=-D$(RENDITION) -GENDOCS=gendocs.sh +GENDOCS=${top_srcdir}/doc/gendocs.sh TEXI2DVI=texi2dvi -t '@set $(RENDITION)' -E diff --git a/doc/gendocs.sh b/doc/gendocs.sh new file mode 100755 index 00000000..fc5beeb6 --- /dev/null +++ b/doc/gendocs.sh @@ -0,0 +1,310 @@ +#!/bin/sh +# gendocs.sh -- generate a GNU manual in many formats. This script is +# mentioned in maintain.texi. See the help message below for usage details. + +scriptversion=2007-10-23.16.gray + +# Copyright (C) 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, +# or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# 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 this program. If not, see <http://www.gnu.org/licenses/>. +# +# Original author: Mohit Agarwal. +# Send bug reports and any other correspondence to bug-texinfo@gnu.org. + +prog=`basename "$0"` +srcdir=`pwd` + +scripturl="http://svn.gnu.org.ua/viewvc/mailfromd/trunk/doc/gendocs.sh" +templateurl="http://svn.gnu.org.ua/viewvc/mailfromd/trunk/doc/gendocs_template" + +: ${SETLANG="env LANG= LC_MESSAGES= LC_ALL= LANGUAGE="} +: ${MAKEINFO="makeinfo"} +: ${TEXI2DVI="texi2dvi -t @finalout"} +: ${DVIPS="dvips"} +: ${DOCBOOK2HTML="docbook2html"} +: ${DOCBOOK2PDF="docbook2pdf"} +: ${DOCBOOK2PS="docbook2ps"} +: ${DOCBOOK2TXT="docbook2txt"} +: ${GENDOCS_TEMPLATE_DIR="."} +: ${TEXI2HTML="texi2html"} +unset CDPATH + +version="gendocs.sh $scriptversion + +Copyright (C) 2007 Free Software Foundation, Inc. +There is NO warranty. You may redistribute this software +under the terms of the GNU General Public License. +For more information about these matters, see the files named COPYING." + +usage="Usage: $prog [OPTION]... PACKAGE MANUAL-TITLE + +Generate various output formats from PACKAGE.texinfo (or .texi or .txi) source. +See the GNU Maintainers document for a more extensive discussion: + http://www.gnu.org/prep/maintain_toc.html + +Options: + -o OUTDIR write files into OUTDIR, instead of manual/. + --docbook convert to DocBook too (xml, txt, html, pdf and ps). + --html ARG pass indicated ARG to makeinfo for HTML targets. + --help display this help and exit successfully. + --version display version information and exit successfully. + +Simple example: $prog emacs \"GNU Emacs Manual\" + +Typical sequence: + cd YOURPACKAGESOURCE/doc + wget \"$scripturl\" + wget \"$templateurl\" + $prog YOURMANUAL \"GNU YOURMANUAL - One-line description\" + +Output will be in a new subdirectory \"manual\" (by default, use -o OUTDIR +to override). Move all the new files into your web CVS tree, as +explained in the Web Pages node of maintain.texi. + +MANUAL-TITLE is included as part of the HTML <title> of the overall +manual/index.html file. It should include the name of the package being +documented. manual/index.html is created by substitution from the file +$GENDOCS_TEMPLATE_DIR/gendocs_template. (Feel free to modify the +generic template for your own purposes.) + +If you have several manuals, you'll need to run this script several +times with different YOURMANUAL values, specifying a different output +directory with -o each time. Then write (by hand) an overall index.html +with links to them all. + +If a manual's texinfo sources are spread across several directories, +first copy or symlink all Texinfo sources into a single directory. +(Part of the script's work is to make a tar.gz of the sources.) + +You can set the environment variables MAKEINFO, TEXI2DVI, and DVIPS to +control the programs that get executed, and GENDOCS_TEMPLATE_DIR to +control where the gendocs_template file is looked for. (With --docbook, +the environment variables DOCBOOK2HTML, DOCBOOK2PDF, DOCBOOK2PS, and +DOCBOOK2TXT are also respected.) + +By default, makeinfo is run in the default (English) locale, since +that's the language of most Texinfo manuals. If you happen to have a +non-English manual and non-English web site, check the SETLANG setting +in the source. + +Email bug reports or enhancement requests to bug-texinfo@gnu.org. +" + +calcsize() +{ + size=`ls -ksl $1 | awk '{print $1}'` + echo $size +} + +outdir=manual +html= +PACKAGE= +MANUAL_TITLE= + +while test $# -gt 0; do + case $1 in + --help) echo "$usage"; exit 0;; + --version) echo "$version"; exit 0;; + -o) shift; outdir=$1;; + --docbook) docbook=yes;; + --html) shift; html=$1;; + -*) + echo "$0: Unknown or ambiguous option \`$1'." >&2 + echo "$0: Try \`--help' for more information." >&2 + exit 1;; + *) + if test -z "$PACKAGE"; then + PACKAGE=$1 + elif test -z "$MANUAL_TITLE"; then + MANUAL_TITLE=$1 + else + echo "$0: extra non-option argument \`$1'." >&2 + exit 1 + fi;; + esac + shift +done + +if test -s "$srcdir/$PACKAGE.texinfo"; then + srcfile=$srcdir/$PACKAGE.texinfo +elif test -s "$srcdir/$PACKAGE.texi"; then + srcfile=$srcdir/$PACKAGE.texi +elif test -s "$srcdir/$PACKAGE.txi"; then + srcfile=$srcdir/$PACKAGE.txi +else + echo "$0: cannot find .texinfo or .texi or .txi for $PACKAGE in $srcdir." >&2 + exit 1 +fi + +if test ! -r $GENDOCS_TEMPLATE_DIR/gendocs_template; then + echo "$0: cannot read $GENDOCS_TEMPLATE_DIR/gendocs_template." >&2 + echo "$0: it is available from $templateurl." >&2 + exit 1 +fi + +echo Generating output formats for $srcfile + +cmd="$SETLANG $MAKEINFO -o $PACKAGE.info \"$srcfile\"" +echo "Generating info files... ($cmd)" +eval "$cmd" +mkdir -p $outdir/ +tar czf $outdir/$PACKAGE.info.tar.gz $PACKAGE.info* +info_tgz_size=`calcsize $outdir/$PACKAGE.info.tar.gz` +# do not mv the info files, there's no point in having them available +# separately on the web. + +cmd="${TEXI2DVI} \"$srcfile\"" +echo "Generating dvi ... ($cmd)" +eval "$cmd" + +# now, before we compress dvi: +echo Generating postscript... +${DVIPS} $PACKAGE -o +gzip -f -9 $PACKAGE.ps +ps_gz_size=`calcsize $PACKAGE.ps.gz` +mv $PACKAGE.ps.gz $outdir/ + +# compress/finish dvi: +gzip -f -9 $PACKAGE.dvi +dvi_gz_size=`calcsize $PACKAGE.dvi.gz` +mv $PACKAGE.dvi.gz $outdir/ + +cmd="${TEXI2DVI} --pdf \"$srcfile\"" +echo "Generating pdf ... ($cmd)" +eval "$cmd" +pdf_size=`calcsize $PACKAGE.pdf` +mv $PACKAGE.pdf $outdir/ + +cmd="$SETLANG $MAKEINFO -o $PACKAGE.txt --no-split --no-headers \"$srcfile\"" +echo "Generating ASCII... ($cmd)" +eval "$cmd" +ascii_size=`calcsize $PACKAGE.txt` +gzip -f -9 -c $PACKAGE.txt >$outdir/$PACKAGE.txt.gz +ascii_gz_size=`calcsize $outdir/$PACKAGE.txt.gz` +mv $PACKAGE.txt $outdir/ + +cmd="$SETLANG $TEXI2HTML --output $PACKAGE.html $html \"$srcfile\"" +echo "Generating monolithic html... ($cmd)" +rm -rf $PACKAGE.html # in case a directory is left over +eval "$cmd" +html_mono_size=`calcsize $PACKAGE.html` +gzip -f -9 -c $PACKAGE.html >$outdir/$PACKAGE.html.gz +html_mono_gz_size=`calcsize $outdir/$PACKAGE.html.gz` +mv $PACKAGE.html $outdir/ + +html_split() { + cmd="$SETLANG $TEXI2HTML --output $PACKAGE.html --split=$1 $html \"$srcfile\"" + echo "Generating html by $1... ($cmd)" + eval "$cmd" + split_html_dir=$PACKAGE.html + ( + cd ${split_html_dir} || exit 1 + ln -sf ${PACKAGE}.html index.html + tar -czf ../$outdir/${PACKAGE}.html_$1.tar.gz -- *.html + ) + eval html_$1_tgz_size=`calcsize $outdir/${PACKAGE}.html_$1.tar.gz` + rm -f $outdir/html_$1/*.html + mkdir -p $outdir/html_$1/ + mv ${split_html_dir}/*.html $outdir/html_$1/ + rmdir ${split_html_dir} +} + +html_split node +html_split chapter +html_split section + +echo Making .tar.gz for sources... +srcfiles=`ls *.texinfo *.texi *.txi *.eps 2>/dev/null` +tar cvzfh $outdir/$PACKAGE.texi.tar.gz $srcfiles +texi_tgz_size=`calcsize $outdir/$PACKAGE.texi.tar.gz` + +if test -n "$docbook"; then + cmd="$SETLANG $MAKEINFO -o - --docbook \"$srcfile\" > ${srcdir}/$PACKAGE-db.xml" + echo "Generating docbook XML... $(cmd)" + eval "$cmd" + docbook_xml_size=`calcsize $PACKAGE-db.xml` + gzip -f -9 -c $PACKAGE-db.xml >$outdir/$PACKAGE-db.xml.gz + docbook_xml_gz_size=`calcsize $outdir/$PACKAGE-db.xml.gz` + mv $PACKAGE-db.xml $outdir/ + + cmd="${DOCBOOK2HTML} -o $split_html_db_dir ${outdir}/$PACKAGE-db.xml" + echo "Generating docbook HTML... ($cmd)" + eval "$cmd" + split_html_db_dir=html_node_db + ( + cd ${split_html_db_dir} || exit 1 + tar -czf ../$outdir/${PACKAGE}.html_node_db.tar.gz -- *.html + ) + html_node_db_tgz_size=`calcsize $outdir/${PACKAGE}.html_node_db.tar.gz` + rm -f $outdir/html_node_db/*.html + mkdir -p $outdir/html_node_db + mv ${split_html_db_dir}/*.html $outdir/html_node_db/ + rmdir ${split_html_db_dir} + + cmd="${DOCBOOK2TXT} ${outdir}/$PACKAGE-db.xml" + echo "Generating docbook ASCII... ($cmd)" + eval "$cmd" + docbook_ascii_size=`calcsize $PACKAGE-db.txt` + mv $PACKAGE-db.txt $outdir/ + + cmd="${DOCBOOK2PS} ${outdir}/$PACKAGE-db.xml" + echo "Generating docbook PS... $(cmd)" + eval "$cmd" + gzip -f -9 -c $PACKAGE-db.ps >$outdir/$PACKAGE-db.ps.gz + docbook_ps_gz_size=`calcsize $outdir/$PACKAGE-db.ps.gz` + mv $PACKAGE-db.ps $outdir/ + + cmd="${DOCBOOK2PDF} ${outdir}/$PACKAGE-db.xml" + echo "Generating docbook PDF... ($cmd)" + eval "$cmd" + docbook_pdf_size=`calcsize $PACKAGE-db.pdf` + mv $PACKAGE-db.pdf $outdir/ +fi + +echo Writing index file... +curdate=`date '+%B %d, %Y'` +sed \ + -e "s!%%TITLE%%!$MANUAL_TITLE!g" \ + -e "s!%%DATE%%!$curdate!g" \ + -e "s!%%PACKAGE%%!$PACKAGE!g" \ + -e "s!%%HTML_MONO_SIZE%%!$html_mono_size!g" \ + -e "s!%%HTML_MONO_GZ_SIZE%%!$html_mono_gz_size!g" \ + -e "s!%%HTML_NODE_TGZ_SIZE%%!$html_node_tgz_size!g" \ + -e "s!%%HTML_SECTION_TGZ_SIZE%%!$html_section_tgz_size!g" \ + -e "s!%%HTML_CHAPTER_TGZ_SIZE%%!$html_chapter_tgz_size!g" \ + -e "s!%%INFO_TGZ_SIZE%%!$info_tgz_size!g" \ + -e "s!%%DVI_GZ_SIZE%%!$dvi_gz_size!g" \ + -e "s!%%PDF_SIZE%%!$pdf_size!g" \ + -e "s!%%PS_GZ_SIZE%%!$ps_gz_size!g" \ + -e "s!%%ASCII_SIZE%%!$ascii_size!g" \ + -e "s!%%ASCII_GZ_SIZE%%!$ascii_gz_size!g" \ + -e "s!%%TEXI_TGZ_SIZE%%!$texi_tgz_size!g" \ + -e "s!%%DOCBOOK_HTML_NODE_TGZ_SIZE%%!$html_node_db_tgz_size!g" \ + -e "s!%%DOCBOOK_ASCII_SIZE%%!$docbook_ascii_size!g" \ + -e "s!%%DOCBOOK_PS_GZ_SIZE%%!$docbook_ps_gz_size!g" \ + -e "s!%%DOCBOOK_PDF_SIZE%%!$docbook_pdf_size!g" \ + -e "s!%%DOCBOOK_XML_SIZE%%!$docbook_xml_size!g" \ + -e "s!%%DOCBOOK_XML_GZ_SIZE%%!$docbook_xml_gz_size!g" \ + -e "s,%%SCRIPTURL%%,$scripturl,g" \ + -e "s!%%SCRIPTNAME%%!$prog!g" \ +$GENDOCS_TEMPLATE_DIR/gendocs_template >$outdir/index.html + +echo "Done! See $outdir/ subdirectory for new files." + +# Local variables: +# eval: (add-hook 'write-file-hooks 'time-stamp) +# time-stamp-start: "scriptversion=" +# time-stamp-format: "%:y-%02m-%02d.%02H.gray" +# time-stamp-end: "$" +# End: diff --git a/doc/gendocs_template b/doc/gendocs_template index 0e7d3190..030f311c 100755 --- a/doc/gendocs_template +++ b/doc/gendocs_template @@ -41,12 +41,22 @@ (%%HTML_MONO_SIZE%%K characters)</a> - entirely on one web page.</li> <li><a href="html_node/index.html">HTML</a> - with one web page per node.</li> + <li><a href="html_section/index.html">HTML</a> - with one web page per + section.</li> + <li><a href="html_chapter/index.html">HTML</a> - with one web page per + chapter.</li> <li><a href="%%PACKAGE%%.html.gz">HTML compressed (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on one web page.</li> <li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> - with one web page per node.</li> + <li><a href="%%PACKAGE%%.html_section.tar.gz">HTML compressed + (%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> - + with one web page per section.</li> + <li><a href="%%PACKAGE%%.html_chapter.tar.gz">HTML compressed + (%%HTML_CHAPTER_TGZ_SIZE%%K gzipped tar file)</a> - + with one web page per chapter.</li> <li><a href="%%PACKAGE%%.info.tar.gz">Info document (%%INFO_TGZ_SIZE%%K characters gzipped tar file)</a>.</li> <li><a href="%%PACKAGE%%.txt">ASCII text diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi index 6aa44c6b..33d6b208 100644 --- a/doc/mailfromd.texi +++ b/doc/mailfromd.texi @@ -4769,10 +4769,11 @@ where @var{n} is the ordinal number of the argument. Here we describe the available handlers and their arguments: @deffn {Handler} connect (string $1, number $2, number $3, string $4) -@subsubheading Invocation +@table @b +@item Invocation: This handler is called once at the beginning of each @acronym{SMTP} connection. -@subsubheading Arguments +@item Arguments: @enumerate 1 @item @code{string}; The host name of the message sender, as reported by @acronym{MTA}. Usually it @@ -4803,6 +4804,7 @@ Remote @acronym{IP} address if @samp{$2} is @samp{FAMILY_INET} or full file name of the socket if @samp{$2} is @samp{FAMILY_UNIX}. If @samp{$2} is @samp{FAMILY_STDIO}, @samp{$4} is an empty string. @end enumerate +@end table @cindex actions, using in @code{connect} handler The actions (@pxref{Actions}) appearing in this handler @@ -4876,31 +4878,34 @@ versions of Sendmail up to 8.14. @end deffn @deffn {Handler} helo (string $1) -@subsubheading Invocation +@table @b +@item Invocation: This handler is called whenever the @acronym{SMTP} client sends @code{HELO} or @code{EHLO} command. Depending on the actual @acronym{MTA} configuration, it can be called several times or even not at all. -@subsubheading Arguments +@item Arguments: @enumerate 1 @item @code{string}; Argument to @code{HELO} (@code{EHLO}) commands. @end enumerate -@subsubheading Notes +@item Notes: According to @acronym{RFC} 28221, @code{$1} must be domain name of the sending host, or, in case this is not available, its @acronym{IP} address enclosed in square brackets. Be careful when taking decisions based on this value, because in practice many hosts send arbitrary strings. We recommend to use @code{heloarg_test} function (@pxref{heloarg_test}) if you wish to analyze this value. +@end table @end deffn @deffn {Handler} envfrom (string $1, string $2) -@subsubheading Invocation +@table @b +@item Invocation: Called when the @acronym{SMTP} client sends @code{MAIL FROM} command, i.e. once at the beginning of each message. -@subsubheading Arguments +@item Arguments: @enumerate 1 @item @code{string}; First argument to the @code{MAIL FROM} command, i.e. the email address of the sender. @@ -4908,7 +4913,7 @@ i.e. the email address of the sender. by space character. This argument can be @samp{""}. @end enumerate -@subsubheading Notes +@item Notes @enumerate 1 @item @code{$1} is not the same as @code{$f} Sendmail variable, because the latter contains the sender email after address rewriting and @@ -4918,14 +4923,15 @@ sending party. @item When the array type is implemented, @code{$2} will contain an array of arguments. @end enumerate - +@end table @end deffn @deffn {Handler} envrcpt (string $1, string $2) -@subsubheading Invocation +@table @b +@item Invocation: Called once for each @code{RCPT TO} command, i.e. once for each recipient, immediately after @code{envfrom}. -@subsubheading Arguments +@item Arguments: @enumerate 1 @item @code{string}; First argument to the @code{RCPT TO} command, i.e. the email address of the sender. @@ -4933,15 +4939,17 @@ i.e. the email address of the sender. by space character. This argument can be @samp{""}. @end enumerate -@subsubheading Notes +@item Notes: When the array type is implemented, @code{$2} will contain an array of arguments. +@end table @end deffn @deffn {Handler} header (string $1, string $2) -@subsubheading Invocation +@table @b +@item Invocation: Called once for each header line received after @acronym{SMTP} @code{DATA} command. -@subsubheading Arguments +@item Arguments: @enumerate 1 @item @code{string}; Header field name. @item @code{string}; Header field value. The content of the header may @@ -4949,41 +4957,48 @@ include folded white space, i.e., multiple lines with following white space where lines are separated by @sc{lf} (@acronym{ASCII} 10). The trailing line terminator (@sc{cr/lf}) is removed. @end enumerate +@end table @end deffn @deffn {Handler} eoh -@subsubheading Invocation +@table @b +@item Invocation: This handler is called once per message, after all headers have been sent and processed. -@subsubheading Arguments +@item Arguments: None. +@end table @end deffn @deffn {Handler} body (string $1, number $2) -@subsubheading Invocation +@table @b +@item Invocation: This header is called zero or more times, for each piece of the message body obtained from the remote host. -@subsubheading Arguments +@item Araguments: @enumerate 1 @item @code{string}; Piece of body text. See @samp{Notes} below. @item @code{number}; Length of @code{$1}, in bytes. @end enumerate -@subsubheading Notes +@item Notes: As of version @value{VERSION}, @code{$1} cannot be processed with usual string functions, because it is not null-terminated. This limitation will be removed in future versions. +@end table @end deffn @deffn {Handler} eom -@subsubheading Invocation +@table @b +@item Invocation: This handler is called once per message, when the terminating dot after @code{DATA} command has been received. -@subsubheading Arguments +@item Arguments: None -@subsubheading Notes +@item Notes: This handler is useful for calling @dfn{message capturing} functions, such as @code{sa} or @code{clamav}. For more information about these, refer to @ref{Interfaces to Third-Party Programs}. +@end table @end deffn For your reference, the following table shows each handler with its arguments: |