summaryrefslogtreecommitdiffabout
path: root/doc
authorSergey Poznyakoff <gray@gnu.org.ua>2009-10-18 19:18:06 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2009-10-18 19:18:06 (GMT)
commit4cb33c7c355491f602bbf09f97e90aa90afb4797 (patch) (side-by-side diff)
tree4e1bc48daf11741aee001680de36d35f3589aa95 /doc
parent1e7e504d1e0f019348f2d222932b1a27c0718e6d (diff)
downloadpies-4cb33c7c355491f602bbf09f97e90aa90afb4797.tar.gz
pies-4cb33c7c355491f602bbf09f97e90aa90afb4797.tar.bz2
Imrove the docs.
* doc/Config: New file. Configuration for texi2html. * doc/Makefile.am (manual): Update rule. (man-tar): New rule. * doc/gendocs_template: Rewrite using the new site layout. * doc/pies.texi: Minor changes.
Diffstat (limited to 'doc') (more/less context) (ignore whitespace changes)
-rw-r--r--doc/Config363
-rw-r--r--doc/Makefile.am6
-rwxr-xr-xdoc/gendocs_template114
-rw-r--r--doc/pies.texi15
4 files changed, 418 insertions, 80 deletions
diff --git a/doc/Config b/doc/Config
new file mode 100644
index 0000000..0e2742d
--- a/dev/null
+++ b/doc/Config
@@ -0,0 +1,363 @@
+# Texi2html configuration for Pies documentation. -*- perl-mode -*-
+# Copyright (C) 2009 Sergey Poznyakoff
+#
+# Pies 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, or (at your option)
+# any later version.
+#
+# Pies 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 Pies. If not, see <http://www.gnu.org/licenses/>.
+
+$top_html_dir="/software/pies";
+$graphics_dir="$top_html_dir/graphics";
+
+## texi2html configuration
+
+# Show TOC in place of the @contents directive.
+$INLINE_CONTENTS = 1;
+# Do not show Texinfo menus.
+$SHOW_MENU = 0;
+# Inhibit output of CSS lines in page headers.
+$CSS_LINES='';
+# Print footnotes at the end of each file (if the document is split).
+$SEPARATED_FOOTNOTES = 0;
+
+$BODYTEXT = "";
+
+$EXTRA_HEAD="\
+ <link rev=\"made\" href=\"mailto:gray@gnu.org.ua\">\
+ <link rel=\"stylesheet\" type=\"text/css\" href=\"${top_html_dir}/gray.css\">\
+ <link rel=\"stylesheet\" type=\"text/css\" href=\"${top_html_dir}/texi.css\">\
+ <link rel=\"icon\" type=\"image/png\" href=\"/graphics/gnu-head-icon.png\">";
+
+$AFTER_BODY_OPEN="\
+<!--#include virtual=\"${top_html_dir}/inc/header.html\" -->\
+<table class='tabs'>\
+ <tr>\
+ <td><a href=\"$top_html_dir/pies.html\">Main</a></td>\
+ <td><a href=\"$top_html_dir/example.html\">Examples</a></td>\
+ <td><a href=\"$top_html_dir/download.html\">Downloads</a></td>\
+ <td><a class=\"active\" href=\"$top_html_dir/manual.html\">Documentation</a></td>\
+ </tr>
+</table>";
+
+$PRE_BODY_CLOSE="Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.";
+
+$format_map{'multitable'}='table class="multitable"';
+
+$SMALL_RULE = '';
+$DEFAULT_RULE = '';
+$MIDDLE_RULE = '';
+# This is output at the end of a section.
+$BIG_RULE = '';
+
+# Use navigation icons
+$ICONS = 1;
+%ACTIVE_ICONS =
+ (
+ 'Top', "$graphics_dir/top.png",
+ 'Contents', "$graphics_dir/ctx.png",
+ 'Overview', '',
+ 'Index', "$graphics_dir/idx.png",
+ 'This', '',
+ 'Back', "$graphics_dir/left.png",
+ 'FastBack', "$graphics_dir/bwd.png",
+ 'Prev', "",
+ 'Up', "$graphics_dir/up.png",
+ 'Next', "$graphics_dir/right.png",
+ 'NodeUp', "$graphics_dir/left.png",
+ 'NodeNext', "$graphics_dir/up.png",
+ 'NodePrev', "$graphics_dir/right.png",
+ 'Following', "$graphics_dir/right.png",
+ 'Forward', "$graphics_dir/right.png",
+ 'FastForward', "$graphics_dir/fwd.png",
+ 'About' , '',
+ 'First', '',
+ 'Last', '',
+ ' ', ''
+ );
+
+@SECTION_BUTTONS =
+ (
+ \&gray_document_title,
+ \&gray_sec_ref,
+ 'Back', 'Forward',
+ \&gray_chap_ref, 'FastBack', 'Up', 'FastForward',
+ \&gray_doc_ref,
+ 'Contents', 'Index',
+ ' ','About',
+ );
+
+@SECTION_FOOTER_BUTTONS = @SECTION_BUTTONS;
+@NODE_FOOTER_BUTTONS = @SECTION_BUTTONS;
+
+# buttons for misc stuff
+@MISC_BUTTONS = (
+ \&gray_document_title,
+ 'Contents',
+ 'Index',
+ ' ',
+ 'About'
+ );
+
+
+$print_section = \&gray_print_section;
+$print_navigation = \&gray_print_navigation;
+$print_head_navigation = \&gray_print_head_navigation;
+$print_foot_navigation = \&gray_print_foot_navigation;
+$print_About = \&gray_print_About;
+$cell = \&gray_multitable_cell;
+$print_page_foot = \&gray_print_page_foot;
+
+sub gray_multitable_cell($$)
+{
+ my $text = shift;
+ my $row_macro = shift;
+
+ $text =~ s/<p>//;
+ $text =~ s/<\/p>//;
+ if ($row_macro eq 'headitem')
+ {
+ return '<th>' . $text . '</th>';
+ }
+ return '<td>' . $text . '</td>';
+}
+
+sub gray_print_About
+{
+ return &$print_misc(@_) if (!($SPLIT eq '') or $SECTION_NAVIGATION);
+}
+
+sub gray_split_status()
+{
+ if ($SPLIT eq '') {
+ return '';
+ } elsif ($SPLIT eq 'node') {
+ return ' <span class="splitstatus">(split by node)</span>';
+ } elsif ($SPLIT eq 'section') {
+ return ' <span class="splitstatus">(split by section)</span>';
+ } elsif ($SPLIT eq 'chapter') {
+ return ' <span class="splitstatus">(split by chapter)</span>';
+ }
+}
+
+sub gray_document_title($$)
+{
+ my $fh = shift;
+ my $vertical = shift;
+ my $status = gray_split_status();
+ print $fh qq{<td class="title">} . $Texi2HTML::THISDOC{title} . $status . ":</td>\n";
+}
+
+sub gray_node_ref($$)
+{
+ my $fh = shift;
+ my $vertical = shift;
+ print $fh qq{<span class="navtext">Node:</span>};
+}
+
+sub gray_sec_ref($$)
+{
+ my $fh = shift;
+ my $vertical = shift;
+ print $fh qq{<span class="navtext">Section:</span>};
+}
+
+sub gray_chap_ref($$)
+{
+ my $fh = shift;
+ my $vertical = shift;
+ print $fh qq{<span class="navtext">Chapter:</span>};
+}
+
+sub gray_doc_ref($$)
+{
+ my $fh = shift;
+ my $vertical = shift;
+ print $fh qq{<span class="navtext">Doc:</span>};
+}
+
+sub gray_print_navigation
+{
+ my $fh = shift;
+ my $buttons = shift;
+ my $vertical = shift;
+ my $spacing = 1;
+ my $class="nav";
+
+ print $fh qq{<table class="nav">\n};
+
+ print $fh "<tr>" unless $vertical;
+ for my $button (@$buttons)
+ {
+ if ($button =~ /^\@class=(.*)/) {
+ $class = "$class $1";
+ next;
+ }
+ print $fh "<tr>\n" if $vertical;
+ print $fh qq{<td class="$class">};
+
+ if (ref($button) eq 'CODE')
+ {
+ &$button($fh, $vertical);
+ }
+ elsif (ref($button) eq 'SCALAR')
+ {
+ print $fh "$$button" if defined($$button);
+ }
+ elsif (ref($button) eq 'ARRAY')
+ {
+ my $text = $button->[1];
+ my $button_href = $button->[0];
+ # verify that $button_href is simple text and text is a reference
+ if (defined($button_href) and !ref($button_href)
+ and defined($text) and (ref($text) eq 'SCALAR') and defined($$text))
+ { # use given text
+ if ($Texi2HTML::HREF{$button_href})
+ {
+ print $fh "" .
+ &$anchor('',
+ $Texi2HTML::HREF{$button_href},
+ $$text
+ )
+ ;
+ }
+ else
+ {
+ print $fh $$text;
+ }
+ }
+ }
+ elsif ($button eq ' ')
+ { # handle space button
+ print $fh
+ ($ICONS && $ACTIVE_ICONS{' '}) ?
+ &$button_icon_img($BUTTONS_NAME{$button}, $ACTIVE_ICONS{' '}) :
+ $NAVIGATION_TEXT{' '};
+ #next;
+ }
+ elsif ($Texi2HTML::HREF{$button})
+ { # button is active
+ my $btitle = $BUTTONS_GOTO{$button} ?
+ 'title="' . $BUTTONS_GOTO{$button} . '"' : '';
+ if ($ICONS && $ACTIVE_ICONS{$button})
+ { # use icon
+ print $fh '' .
+ &$anchor('',
+ $Texi2HTML::HREF{$button},
+ &$button_icon_img($BUTTONS_NAME{$button},
+ $ACTIVE_ICONS{$button},
+ $Texi2HTML::SIMPLE_TEXT{$button}),
+ $btitle
+ );
+ }
+ else
+ { # use text
+ print $fh
+ '' .
+ &$anchor('',
+ $Texi2HTML::HREF{$button},
+ $NAVIGATION_TEXT{$button},
+ $btitle
+ );
+ }
+ }
+ else { # button is passive
+ print $fh '<span class="passive">' .
+ ($ICONS && $PASSIVE_ICONS{$button} ?
+ &$button_icon_img($BUTTONS_NAME{$button},
+ $PASSIVE_ICONS{$button},
+ $Texi2HTML::SIMPLE_TEXT{$button}) :
+
+ $NAVIGATION_TEXT{$button}) . '</span>';
+ }
+ print $fh "</td>\n";
+ print $fh "</tr>\n" if $vertical;
+ $class = "nav";
+ }
+ print $fh "</tr>" unless $vertical;
+ print $fh "</table>\n";
+}
+
+sub gray_print_head_navigation($$)
+{
+ my $fh = shift;
+ my $buttons = shift;
+
+ return if ($SPLIT eq '');
+ if ($VERTICAL_HEAD_NAVIGATION)
+ {
+ print $fh <<EOT;
+<table class='nav'>
+<tr>
+<td>
+EOT
+ }
+ main::print_lines($fh, $Texi2HTML::THIS_HEADER);
+ &$print_navigation($fh, $buttons, $VERTICAL_HEAD_NAVIGATION);
+ if ($VERTICAL_HEAD_NAVIGATION)
+ {
+ print $fh <<EOT;
+</td>
+<td>
+EOT
+ }
+}
+
+sub gray_print_foot_navigation
+{
+ my $fh = shift;
+
+ return if ($SPLIT eq '');
+ if ($VERTICAL_HEAD_NAVIGATION)
+ {
+ print $fh <<EOT;
+</td>
+</tr>
+</table>
+EOT
+ }
+}
+
+sub gray_print_page_foot($)
+{
+ my $fh = shift;
+ my $program_string = program_string();
+ print $fh <<EOT;
+<div class="copyright">
+$program_string
+EOT
+ if (defined($PRE_BODY_CLOSE) && $PRE_BODY_CLOSE) {
+ print $fh "<p>$PRE_BODY_CLOSE</p>";
+ }
+ print $fh <<EOT;
+</div>
+</body>
+</html>
+EOT
+}
+
+sub gray_print_section
+{
+ my $fh = shift;
+ my $first_in_page = shift;
+ my $previous_is_top = shift;
+ my $buttons = \@SECTION_BUTTONS;
+
+ &$print_head_navigation($fh, $buttons) if ($first_in_page);
+ my $nw = main::print_lines($fh);
+ if (defined $SPLIT
+ and ($SPLIT eq 'node')) {
+ &$print_foot_navigation($fh);
+ print $fh "$SMALL_RULE\n";
+ &$print_navigation($fh, \@NODE_FOOTER_BUTTONS) if (!defined($WORDS_IN_PAGE) or (defined ($nw)
+ and $nw >= $WORDS_IN_PAGE));
+ }
+}
+
diff --git a/doc/Makefile.am b/doc/Makefile.am
index bb2ff49..094d660 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -141,11 +141,17 @@ GENDOCS=gendocs.sh
TEXI2DVI=texi2dvi -t '@set $(RENDITION)' -E
+.PHONY: manual man-tar
# Make sure you set TEXINPUTS.
# TEXINPUTS=/usr/share/texmf/pdftex/plain/misc/ is ok for most distributions
manual:
+ rm -rf manual
TEXINPUTS=$(srcdir):$(top_srcdir)/build-aux:$(TEXINPUTS) \
MAKEINFO="$(MAKEINFO) $(MAKEINFOFLAGS)" \
TEXI2DVI="$(TEXI2DVI) -t @finalout" \
$(GENDOCS) --texi2html $(PACKAGE) '$(PACKAGE_NAME) manual'
+manual.tar.bz2: manual
+ tar cfj manual.tar.bz2 manual
+
+man-tar: manual.tar.bz2 \ No newline at end of file
diff --git a/doc/gendocs_template b/doc/gendocs_template
index c8b7c05..a39d2de 100755
--- a/doc/gendocs_template
+++ b/doc/gendocs_template
@@ -1,123 +1,83 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<!-- $Id$ -->
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
-<title>%%TITLE%% - Free Software - puszcza.gnu.org.ua</title>
-<meta http-equiv="content-type" content='text/html; charset=utf-8' />
-<link rel="stylesheet" type="text/css" href="/local/css/gnu.css" />
-<link rev="made" href="mailto:gray@gnu.org" />
+ <title>Pies - gray.gnu.org.ua</title>
+ <meta name="Generator" content="%%SCRIPTNAME%%" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <link rev="made" href="mailto:gray@gnu.org.ua" />
+ <link rel="stylesheet" type="text/css" href="/software/pies/gray.css" />
<link rel="icon" type="image/png" href="/graphics/gnu-head-icon.png" />
</head>
-
-<!-- This document is in XML, and xhtml 1.0 -->
-<!-- Please make sure to properly nest your tags -->
-<!-- and ensure that your final document validates -->
-<!-- consistent with W3C xhtml 1.0 and CSS standards -->
-<!-- See validator.w3.org -->
-
<body>
+<!--#include virtual="inc/header.html" -->
+<table class='tabs'>
+ <tr>
+ <td><a href="pies.html">Main</a></td>
+ <td><a href="example.html">Examples</a></td>
+ <td><a href="download.html">Downloads</a></td>
+ <td><a class="active" href="manual.html">Documentation</a></td>
+ </tr>
+</table>
-<h3>%%TITLE%%</h3>
-
-<address>Sergey Poznyakoff</address>
-<address>last updated %%DATE%%</address>
-<p>
-<a href="/graphics/gnu-head.jpg">
- <img src="/graphics/gnu-head-sm.jpg"
- alt=" [image of the head of a GNU] "
- width="129" height="122" />
-</a>
-
-</p>
-<hr />
-
-<p>The manual for %%PACKAGE%% is available in the following formats:</p>
+<div id="main">
+<p>The manual for <b>%%PACKAGE%%</b> is available in the following formats:</p>
<ul>
- <li><a href="%%PACKAGE%%.html">HTML
+ <li><a href="manual/%%PACKAGE%%.html">HTML
(%%HTML_MONO_SIZE%%K bytes)</a> - entirely on one web page.</li>
- <li><a href="html_node/index.html">HTML</a> - with one web page per
+ <li><a href="manual/html_node/index.html">HTML</a> - with one web page per
node.</li>
%%IF HTML_SECTION%%
- <li><a href="html_section/index.html">HTML</a> - with one web page per
+ <li><a href="manual/html_section/index.html">HTML</a> - with one web page per
section.</li>
%%ENDIF HTML_SECTION%%
%%IF HTML_CHAPTER%%
- <li><a href="html_chapter/index.html">HTML</a> - with one web page per
+ <li><a href="manual/html_chapter/index.html">HTML</a> - with one web page per
chapter.</li>
%%ENDIF HTML_CHAPTER%%
- <li><a href="%%PACKAGE%%.html.gz">HTML compressed
+ <li><a href="manual/%%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
+ <li><a href="manual/%%PACKAGE%%.html_node.tar.gz">HTML compressed
(%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> -
with one web page per node.</li>
%%IF HTML_SECTION%%
- <li><a href="%%PACKAGE%%.html_section.tar.gz">HTML compressed
+ <li><a href="manual/%%PACKAGE%%.html_section.tar.gz">HTML compressed
(%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> -
with one web page per section.</li>
%%ENDIF HTML_SECTION%%
%%IF HTML_CHAPTER%%
- <li><a href="%%PACKAGE%%.html_chapter.tar.gz">HTML compressed
+ <li><a href="manual/%%PACKAGE%%.html_chapter.tar.gz">HTML compressed
(%%HTML_CHAPTER_TGZ_SIZE%%K gzipped tar file)</a> -
with one web page per chapter.</li>
%%ENDIF HTML_CHAPTER%%
- <li><a href="%%PACKAGE%%.info.tar.gz">Info document
+ <li><a href="manual/%%PACKAGE%%.info.tar.gz">Info document
(%%INFO_TGZ_SIZE%%K characters gzipped tar file)</a>.</li>
- <li><a href="%%PACKAGE%%.txt">ASCII text
+ <li><a href="manual/%%PACKAGE%%.txt">ASCII text
(%%ASCII_SIZE%%K characters)</a>.</li>
- <li><a href="%%PACKAGE%%.txt.gz">ASCII text compressed
+ <li><a href="manual/%%PACKAGE%%.txt.gz">ASCII text compressed
(%%ASCII_GZ_SIZE%%K gzipped characters)</a>.</li>
- <li><a href="%%PACKAGE%%.dvi.gz">TeX dvi file
+ <li><a href="manual/%%PACKAGE%%.dvi.gz">TeX dvi file
(%%DVI_GZ_SIZE%%K characters gzipped)</a>.</li>
- <li><a href="%%PACKAGE%%.ps.gz">PostScript file
+ <li><a href="manual/%%PACKAGE%%.ps.gz">PostScript file
(%%PS_GZ_SIZE%%K characters gzipped)</a>.</li>
- <li><a href="%%PACKAGE%%.pdf">PDF file
+ <li><a href="manual/%%PACKAGE%%.pdf">PDF file
(%%PDF_SIZE%%K characters)</a>.</li>
- <li><a href="%%PACKAGE%%.texi.tar.gz">Texinfo source
+ <li><a href="manual/%%PACKAGE%%.texi.tar.gz">Texinfo source
(%%TEXI_TGZ_SIZE%%K characters gzipped tar file)</a></li>
</ul>
-<p>(This page generated by the <a
-href="%%SCRIPTURL%%">%%SCRIPTNAME%%</a> script.)
-</p>
-
-<p>
-<a href="http://validator.w3.org/check?uri=referer"><img
- src="http://www.w3.org/Icons/valid-xhtml10"
- alt="Valid XHTML 1.0!" height="31" width="88" /></a>
-</p>
-
-<div class="copyright">
-<p>
-Return to <a href="http://gray.gnu.org.ua">Sergey Poznyakoff home page</a>.
-</p>
-<p>
-Return to the <a href="http://puszcza.gnu.org.ua">Puszcza home page</a>.
-</p>
-
-<p>
-Please send broken links and other corrections (or suggestions) to
-<a href="mailto:webmaster@gnu.org.ua"><em>webmaster at gnu dot org dot ua</em></a>.
-</p>
-
-<p>
-Copyright (C) 2005 Sergey Poznyakoff
-<br />
-Verbatim copying and distribution of this entire article is
-permitted in any medium, provided this notice is preserved.
-</p>
+</div>
-<p>
-Updated:
-<!-- timestamp start -->
-$Date$ $Author$
-<!-- timestamp end -->
+<div class="generator">
+<p>(This page is generated by the <a
+href="%%SCRIPTURL%%">%%SCRIPTNAME%%</a> script.)
</p>
</div>
+<!--#include virtual="inc/footer.html" -->
</body>
</html>
diff --git a/doc/pies.texi b/doc/pies.texi
index 142f425..353faa9 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -2,7 +2,7 @@
@smallbook
@c %**start of header
@setfilename pies.info
-@settitle Pies
+@settitle Pies Manual
@c %**end of header
@setchapternewpage odd
@@ -64,14 +64,17 @@ Software Foundation raise funds for GNU development.''
@insertcopying
@end titlepage
+@ifnothtml
@page
@summarycontents
+@end ifnothtml
+
@page
@contents
@ifnottex
@node Top
-@top Pies
+@top Pies Manual
This edition of the @cite{Pies Manual}, last updated @value{UPDATED},
documents @command{pies} Version @value{VERSION}.
@@ -351,7 +354,7 @@ with a single character according to the following rules:
@float Table, backslash-interpretation
@caption{Backslash escapes}
@multitable @columnfractions 0.30 .5
-@item Sequence @tab Replaced with
+@headitem Sequence @tab Replaced with
@item \a @tab Audible bell character (@acronym{ASCII} 7)
@item \b @tab Backspace character (@acronym{ASCII} 8)
@item \f @tab Form-feed character (@acronym{ASCII} 12)
@@ -676,6 +679,8 @@ by a number, that specifies the limit. The command letters are
case-insensitive and coincide with those used by the shell @code{ulimit}
utility:
+@float Table, Limits
+@caption{Limit Command Letters}
@multitable @columnfractions 0.3 0.6
@headitem Command @tab The limit it sets
@item A @tab max address space (KB)
@@ -690,6 +695,7 @@ utility:
@item U @tab max number of processes
@item P @tab process priority -20..20 (negative = high priority)
@end multitable
+@end float
For example:
@@ -800,6 +806,8 @@ return-code @var{codes} @{
Exit codes can be specified either as decimal numbers or as symbolic code
names from the table below:
+@float Table, exit-codes
+@caption{Standard Exit Codes}
@multitable @columnfractions 0.5 0.3
@headitem Name @tab Numeric value
@item EX_OK @tab 0
@@ -819,6 +827,7 @@ names from the table below:
@item EX_NOPERM @tab 77
@item EX_CONFIG @tab 78
@end multitable
+@end float
Signal numbers can be given either as @samp{SIG+@var{n}}, where @var{n}
is the signal number, or as signal names from the following list:

Return to:

Send suggestions and report system problems to the System administrator.