summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org.ua>2007-10-23 13:35:01 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2007-10-23 13:35:01 (GMT)
commit13b3191f6d774341df664222adc5f85cad0a00cb (patch) (side-by-side diff)
tree29d5ae33681cc1eea8e2bcb9d8cea419446e1cbb
parent9e569139583178c7e1c35147cef3fd17493a11da (diff)
downloadmailfromd-13b3191f6d774341df664222adc5f85cad0a00cb.tar.gz
mailfromd-13b3191f6d774341df664222adc5f85cad0a00cb.tar.bz2
Generate html docs using texi2html
git-svn-id: file:///svnroot/mailfromd/trunk@1521 7a8a7f39-df28-0410-adc6-e0d955640f24
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--ChangeLog6
-rw-r--r--doc/Makefile.am2
-rwxr-xr-xdoc/gendocs.sh310
-rwxr-xr-xdoc/gendocs_template10
-rw-r--r--doc/mailfromd.texi59
5 files changed, 364 insertions, 23 deletions
diff --git a/ChangeLog b/ChangeLog
index c47d8ed..0f5a8c3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -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 3ecc4b7..77ac5ef 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 0000000..fc5beeb
--- a/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 0e7d319..030f311 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 6aa44c6..33d6b20 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:

Return to:

Send suggestions and report system problems to the System administrator.