From 4cb33c7c355491f602bbf09f97e90aa90afb4797 Mon Sep 17 00:00:00 2001
From: Sergey Poznyakoff <gray@gnu.org.ua>
Date: Sun, 18 Oct 2009 22:18:06 +0300
Subject: 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.
---
 doc/Config           | 363 +++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/Makefile.am      |   6 +
 doc/gendocs_template | 114 ++++++----------
 doc/pies.texi        |  15 ++-
 4 files changed, 418 insertions(+), 80 deletions(-)
 create mode 100644 doc/Config

(limited to 'doc')

diff --git a/doc/Config b/doc/Config
new file mode 100644
index 0000000..0e2742d
--- /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:
-- 
cgit v1.2.1