doc changes
authorng0 <ng0@infotropique.org>
Sat, 21 Oct 2017 15:45:29 +0000 (15:45 +0000)
committerng0 <ng0@infotropique.org>
Sat, 21 Oct 2017 15:45:29 +0000 (15:45 +0000)
modified:   contrib/packages/guix/gnunet-doc.scm

adapt to the changes in this mixed commit

modified:   doc/.gitignore

add new files

modified:   doc/Makefile.am

make use of canonical, included, rules
generate html output with docstyle.css from taler exchange.

modified:   doc/chapters/installation.texi
new file:   doc/chapters/vocabulary.texi
modified:   doc/gnunet-c-tutorial.texi
modified:   doc/gnunet.texi
new file:   doc/docstyle.css

not really in use yet, but collected for later:
doc/gendocs.sh , doc/hacks.el

contrib/packages/guix/gnunet-doc.scm
doc/.gitignore
doc/Makefile.am
doc/chapters/installation.texi
doc/chapters/vocabulary.texi [new file with mode: 0644]
doc/docstyle.css [new file with mode: 0644]
doc/gendocs.sh [new file with mode: 0644]
doc/gnunet-c-tutorial.texi
doc/gnunet.texi
doc/hacks.el [new file with mode: 0644]

index da714077fad969bd2b48f78c1843ea115e4761ca..98ab0ede70f00af68018d3cb8c5c9c4764e66ad8 100644 (file)
            (replace 'build
              (lambda _
                (chdir "doc")
-               (zero? (system* "make" "doc-all-give-me-the-noise"))))
+               (zero? (system* "make" "pdf"))
+               (zero? (system* "make" "html"))
+               (zero? (system* "make" "info"))))
+               ;;(zero? (system* "make" "doc-all-give-me-the-noise"))))
            (replace 'install
              (lambda _
                (zero? (system* "make" "doc-all-install")))))))
index 25617d1b071e43e7378ba4d7bfb8a133912c2109..f46d61e707ad62e859bff218060321b92f23cb87 100644 (file)
@@ -8,11 +8,13 @@
 *.html
 *~
 *.info
+*.info-1
+*.info-2
+*.info-3
 \#*\#
 version.texi
-gnunet.info-1
-gnunet.info-2
-gnunet.info-3
 mdate-sh
 stamp-vti
 texinfo.tex
+gnunet.t2p/
+gnunet-c-tutorial.t2p/
\ No newline at end of file
index 74b1300b476d67c7a05257ba0ef66b6a26bb89d9..bb0c5e0bf6046ccff858fbdfd62f4ad99a0c8e7a 100644 (file)
@@ -11,6 +11,8 @@ infoimagedir = $(infodir)/images
 #      $(DOT_FILES:%.dot=%.eps)                                                \
 #      $(DOT_FILES:%.dot=%.pdf)
 
+AM_MAKEINFOHTMLFLAGS = --no-split --css-ref=docstyle.css
+
 dist_infoimage_DATA =                                          \
        images/gnunet-gtk-0-10-gns-a-done.png                   \
        images/gnunet-gtk-0-10-gns-a.png                        \
@@ -106,7 +108,7 @@ gnunet_tutorial_examples =                                  \
        026.c
 
 info_TEXINFOS =                                                \
-       gnunet.texi                                             \
+       gnunet.texi                                             \
        gnunet-c-tutorial.texi
 
 gnunet_TEXINFOS =                                              \
@@ -114,6 +116,7 @@ gnunet_TEXINFOS =                                           \
        chapters/installation.texi                              \
        chapters/philosophy.texi                                \
        chapters/user.texi                                      \
+       chapters/vocabulary.texi                                \
        fdl-1.3.texi                                            \
        gpl-3.0.texi
 
@@ -122,7 +125,8 @@ EXTRA_DIST =                                                        \
        outdated-and-old-installation-instructions.txt          \
        gnunet-c-tutorial-v1.pdf                                \
        $(gnunet_tutorial_examples)                             \
-       README.txt
+       README.txt                                              \
+       docstyle.css
 
 
 #      $(DOT_FILES)                                                            \
@@ -152,11 +156,11 @@ lego_stack.png: images/lego_stack.svg
        pngcrush images/lego_stack.png images/lego_stack.png
 
 # FIXME: The usage of 'date' strings causes a warning.
-version.texi:
-       echo "@set UPDATED $(date +'%d %B %Y')" > $@
-       echo "@set UPDATED-MONTH $(date +'%B %Y')" >> $@
-       echo "@set EDITION $(PACKAGE_VERSION)" >> $@
-       echo "@set VERSION $(PACKAGE_VERSION)" >> $@
+version.texi:
+#      echo "@set UPDATED $(date +'%d %B %Y')" > $@
+#      echo "@set UPDATED-MONTH $(date +'%B %Y')" >> $@
+#      echo "@set EDITION $(PACKAGE_VERSION)" >> $@
+#      echo "@set VERSION $(PACKAGE_VERSION)" >> $@
 
 # Workaround for makeinfo error. Whcih in turn introduces more
 # date-related 'warnings'. Well.
@@ -166,45 +170,11 @@ version2.texi:
        echo "@set EDITION $(PACKAGE_VERSION)" >> $@
        echo "@set VERSION $(PACKAGE_VERSION)" >> $@
 
-doc-pdf: version.texi
-       @makeinfo --pdf --quiet gnunet.texi
-doc-pdf-tutorial: version.texi version2.texi
-       @makeinfo --pdf --quiet gnunet-c-tutorial.texi
-
-doc-html: version.texi
-       @makeinfo --html gnunet.texi
-doc-html-tutorial: version.texi version2.texi
-       @makeinfo --html gnunet-c-tutorial.texi
-
-doc-info: version.texi
-       @makeinfo --no-split gnunet.texi
-doc-info-tutorial: version.texi version2.texi
-       @makeinfo --no-split gnunet-c-tutorial.texi
-
 # FIXME: rm *.html and *.pdf
-doc-clean:
-       @rm *.aux *.log *.toc *.cp *.cps
-
-doc-all: doc-pdf doc-html doc-info doc-pdf-tutorial doc-html-tutorial doc-info-tutorial
-
-doc-pdf-noise: version.texi
-       @makeinfo --pdf gnunet.texi
-doc-pdf-tutorial-noise: version.texi version2.texi
-       @makeinfo --pdf gnunet-c-tutorial.texi
-
-doc-html-noise: version.texi
-       @makeinfo --html gnunet.texi
-doc-html-tutorial-noise: version.texi version2.texi
-       @makeinfo --html gnunet-c-tutorial.texi
-
-doc-info-noise: version.texi
-       @makeinfo --no-split gnunet.texi
-doc-info-tutorial-noise: version.texi version2.texi
-       @makeinfo --no-split gnunet-c-tutorial.texi
-
-doc-all-give-me-the-noise: doc-pdf-noise doc-html-noise doc-info-noise doc-pdf-tutorial-noise doc-html-tutorial-noise doc-info-tutorial-noise
+#doc-clean:
+#      @rm *.aux *.log *.toc *.cp *.cps
 
-doc-all-install: doc-all-give-me-the-noise
+doc-all-install:
        @mkdir -p $(DESTDIR)/$(docdir)
        @mkdir -p $(DESTDIR)/$(infoimagedir)
        @mkdir -p $(DESTDIR)/$(infodir)
@@ -212,17 +182,24 @@ doc-all-install: doc-all-give-me-the-noise
        @install -m 0755 gnunet-c-tutorial.pdf $(DESTDIR)/$(docdir)
        @install -m 0755 gnunet-c-tutorial.info $(DESTDIR)/$(infodir)
        @install -m 0755 gnunet.info $(DESTDIR)/$(infodir)
-       @cp -r gnunet $(DESTDIR)/$(docdir)
-       @cp -r gnunet-c-tutorial $(DESTDIR)/$(docdir)
+       @install gnunet.html $(DESTDIR)/$(docdir)
+       @install gnunet-c-tutorial.html $(DESTDIR)/$(docdir)
 
 #      @cp -r images $(DESTDIR)/$(infoimagedir)
 
 # TODO: Add more to clean.
-# clean:
-#      @rm gnunet.pdf
-#      @rm gnunet-c-tutorial.pdf
-#      @rm gnunet.info
-#      @rm gnunet-c-tutorial.info
+clean:
+       @rm gnunet.pdf
+       @rm gnunet.html
+       @rm gnunet.info
+       @rm gnunet.info-1
+       @rm gnunet.info-2
+       @rm gnunet.info-3
+       @rm gnunet-c-tutorial.pdf
+       @rm gnunet-c-tutorial.info
+       @rm gnunet-c-tutorial.html
+       @rm -r gnunet.t2p
+       @rm -r gnunet-c-tutorial.t2p
 
 # CLEANFILES =                                         \
 #      gnunet.log                                      \
@@ -232,7 +209,7 @@ doc-all-install: doc-all-give-me-the-noise
 #      $(wildcard *.cp)                                \
 #      $(wildcard *.cps)
 
-.PHONY: version.texi
+#.PHONY: version.texi
 # if HAVE_EXTENDED_DOCUMENTATION_BUILDING_PDF
 
 # if HAVE_EXTENDED_DOCUMENTATION_BUILDING_HTML
index c7f15f3358a520e06a95584a9c0ff8509d07d159..63ab98e6dd9331511fb7c5e500a8fdc78debfc60 100644 (file)
@@ -9,8 +9,6 @@ to interact with the network.
 This manual is far from complete, and we welcome informed contributions,
 be it in the form of new chapters or insightful comments.
 
-
-
 @menu
 * Dependencies::
 * Pre-installation notes::
@@ -34,8 +32,6 @@ This section lists the various known dependencies for
 GNUnet @value{EDITION}.
 Suggestions for missing dependencies or wrong version numbers are welcome.
 
-
-
 @menu
 * External dependencies::
 * Fixing libgnurl build issues::
@@ -51,17 +47,32 @@ These packages must be installed before a typical GNUnet installation
 can be performed:
 
 @itemize @bullet
-@item GNU libmicrohttpd 0.9.30 or higher@footnote{We recommend to build it
+@item autoconf
+@item automake
+@item pkg-config
+@item libltdl
+@item gstreamer
+@item gst-plugins-base
+@item perl
+@item python (only 2.7 supported)@footnote{tests and gnunet-qr}
+@item jansson
+@item nss
+@item glib
+@item gmp
+@item bluez
+@item miniupnpc
+@item gettext
+@item which
+@item texinfo
+@item GNU libmicrohttpd @geq{} 0.9.30 @footnote{We recommend to build it
 with a GnuTLS version that was configured with libunbound ("DANE support")}
-@item GNU libextractor 1.0 or higher
-@item GNU libtool 2.2 or higher 
-@item GNU libunistring 0.9.1.1 or higher
-@item GNU libidn 1.0.0 or higher
-@item @uref{https://gnupg.org/software/libgcrypt/, GNU libgcrypt}
-@uref{https://gnupg.org/ftp/gcrypt/libgcrypt/, 1.6.0} or higher
-@item @uref{https://gnutls.org/, GnuTLS}@footnote{We recommend to use a
-GnuTLS version that was configured with libunbound ("DANE support")}
-@uref{https://www.gnupg.org/ftp/gcrypt/gnutls/v3.2/, 3.2.7} or higher
+@item GNU libextractor @geq{} 1.0
+@item GNU libtool @geq{} 2.2
+@item GNU libunistring @geq{} 0.9.1.1
+@item GNU libidn @geq{} 1.0.0
+@item @uref{https://gnupg.org/software/libgcrypt/, GNU libgcrypt} @geq{}
+@uref{https://gnupg.org/ftp/gcrypt/libgcrypt/, 1.6.0}
+@item @uref{https://gnutls.org/, GnuTLS} @geq{} 3.2.7
 @footnote{We recommend to compile with libunbound for DANE support;
 GnuTLS also requires GNU nettle 2.7 (update: GnuTLS 3.2.7 appears NOT
 to work against GNU nettle > 2.7, due to some API updatings done by
@@ -70,13 +81,13 @@ and, in case you get some error on the reference to `rpl_strerror' being
 undefined, follow the instructions on
 @uref{http://lists.gnupg.org/pipermail/gnutls-devel/2013-November/006588.html, this}
 post (and the link inside it)).}
-@item @uref{https://gnunet.org/gnurl, gnURL} libgnurl 7.34.0 or
-higher@footnote{must be compiled after @code{GnuTLS}}
-@item libglpk 4.45 or higher
-@item @uref{http://www.openssl.org/, OpenSSL} (binary) 1.0 or higher
-@item TeX Live 2012 or higher, optional (for gnunet-bcd)
-@item Texinfo 5.2 or higher (for documentation)
-@item libsqlite 3.8.0 or higher @footnote{(note that the code will
+@item @uref{https://gnunet.org/gnurl, gnURL} libgnurl @geq{} 7.34.0
+@footnote{must be compiled after @code{GnuTLS}}
+@item libglpk @geq{} 4.45
+@item @uref{http://www.openssl.org/, OpenSSL} @geq{} 1.0
+@item TeX Live @geq{} 2012, optional (for gnunet-bcd)
+@item Texinfo @geq{} 5.2 (for documentation)
+@item libsqlite @geq{} 3.8.0 @footnote{(note that the code will
 compile and often work with lower version numbers, but you may get subtle
 bugs with respect to quota management in certain rare cases);
 alternatively, MySQL or Postgres can also be installed, but those
diff --git a/doc/chapters/vocabulary.texi b/doc/chapters/vocabulary.texi
new file mode 100644 (file)
index 0000000..8b6cbe3
--- /dev/null
@@ -0,0 +1,47 @@
+@node Vocabulary
+@chapter Vocabulary
+
+@menu
+* Words and characters::
+* Technical Assumptions::
+@end menu
+
+@node Words and characters
+@section Words and characters
+
+Throughout this document we use certain words and characters.
+
+@enumerate
+@item
+``@command{#}'' in example code blocks describes commands, ie comments.
+
+@example
+# Do the foobar thing:
+$ make foobar
+@end example
+
+@item
+Dollarsign ``@command{$}'' in example code blocks describes commands you
+execute as unprivileged users.
+
+@example
+$ cd foo; ./configure --example-switch
+@end example
+
+@item
+Backslash ``@command{\}'' describes linebreaks.
+
+@example
+./configure --foo --bar --baz \
+ --short-loop
+@end example
+
+...expands to @code{./configure --foo --bar --baz --short-loop}
+
+@end enumerate
+
+@node Technical Assumptions
+@section Technical Assumptions
+
+@c Is it really assuming Bash (ie Bash extensions of POSIX being used)?
+The shell on GNU systems is assumed to be Bash.
diff --git a/doc/docstyle.css b/doc/docstyle.css
new file mode 100644 (file)
index 0000000..8719248
--- /dev/null
@@ -0,0 +1,76 @@
+html, body {
+    font-size: 1em;
+    text-align: left;
+    text-decoration: none;
+}
+html { background-color: #e7e7e7; }
+
+body {
+    max-width: 74.92em;
+    margin: 0 auto;
+    padding: .5em 1em 1em 1em;
+    background-color: white;
+    border: .1em solid #c0c0c0;
+}
+
+h1, h2, h3, h4 { color: #333; }
+h5, h6, dt { color: #222; }
+
+
+a h3 {
+    color: #005090;
+}
+
+a[href] { color: #005090; }
+a[href]:visited { color: #100070; }
+a[href]:active, a[href]:hover {
+    color: #100070;
+    text-decoration: none;
+}
+
+.linkrow {
+    margin: 3em 0;
+}
+
+.linkrow {
+    text-align: center;
+}
+
+div.example { padding: .8em 1.2em .4em; }
+pre.example { padding: .8em 1.2em; }
+div.example, pre.example {
+    margin: 1em 0 1em 3% ;
+    -webkit-border-radius: .3em;
+    -moz-border-radius: .3em;
+    border-radius: .3em;
+    border: 1px solid #d4cbb6;
+    background-color: #f2efe4;
+}
+div.example > pre.example {
+    padding: 0 0 .4em;
+    margin: 0;
+    border: none;
+}
+
+
+/* This makes the very long tables of contents in Gnulib and other
+   manuals easier to read. */
+.contents ul, .shortcontents ul { font-weight: bold; }
+.contents ul ul, .shortcontents ul ul { font-weight: normal; }
+.contents ul { list-style: none; }
+
+/* For colored navigation bars (Emacs manual): make the bar extend
+   across the whole width of the page and give it a decent height. */
+.header, .node { margin: 0 -1em; padding: 0 1em; }
+.header p, .node p { line-height: 2em; }
+
+/* For navigation links */
+.node a, .header a { display: inline-block; line-height: 2em; }
+.node a:hover, .header a:hover { background: #f2efe4; }
+
+table.cartouche {
+    border-collapse: collapse;
+    border-color: darkred;
+    border-style: solid;
+    border-width: 3px;
+}
diff --git a/doc/gendocs.sh b/doc/gendocs.sh
new file mode 100644 (file)
index 0000000..3b71b36
--- /dev/null
@@ -0,0 +1,504 @@
+#!/bin/sh -e
+# 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=2016-12-31.18
+
+# Copyright 2003-2017 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-gnulib@gnu.org.
+#
+# The latest version of this script, and the companion template, is
+# available from the Gnulib repository:
+#
+# http://git.savannah.gnu.org/cgit/gnulib.git/tree/build-aux/gendocs.sh
+# http://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/gendocs_template
+
+# TODO:
+# - image importing was only implemented for HTML generated by
+#   makeinfo.  But it should be simple enough to adjust.
+# - images are not imported in the source tarball.  All the needed
+#   formats (PDF, PNG, etc.) should be included.
+
+prog=`basename "$0"`
+srcdir=`pwd`
+
+scripturl="http://git.savannah.gnu.org/cgit/gnulib.git/plain/build-aux/gendocs.sh"
+templateurl="http://git.savannah.gnu.org/cgit/gnulib.git/plain/doc/gendocs_template"
+
+: ${SETLANG="env LANG= LC_MESSAGES= LC_ALL= LANGUAGE="}
+: ${MAKEINFO="makeinfo"}
+: ${TEXI2DVI="texi2dvi"}
+: ${DOCBOOK2HTML="docbook2html"}
+: ${DOCBOOK2PDF="docbook2pdf"}
+: ${DOCBOOK2TXT="docbook2txt"}
+: ${GENDOCS_TEMPLATE_DIR="."}
+: ${PERL='perl'}
+: ${TEXI2HTML="texi2html"}
+unset CDPATH
+unset use_texi2html
+
+MANUAL_TITLE=
+PACKAGE=
+EMAIL=webmasters@gnu.org  # please override with --email
+commonarg= # passed to all makeinfo/texi2html invcations.
+dirargs=   # passed to all tools (-I dir).
+dirs=      # -I directories.
+htmlarg="--css-ref=/software/gnulib/manual.css -c TOP_NODE_UP_URL=/manual"
+infoarg=--no-split
+generate_ascii=true
+generate_html=true
+generate_info=true
+generate_tex=true
+outdir=manual
+source_extra=
+split=node
+srcfile=
+texarg="-t @finalout"
+
+version="gendocs.sh $scriptversion
+
+Copyright 2017 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 output in various 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:
+  --email ADR use ADR as contact in generated web pages; always give this.
+
+  -s SRCFILE   read Texinfo from SRCFILE, instead of PACKAGE.{texinfo|texi|txi}
+  -o OUTDIR    write files into OUTDIR, instead of manual/.
+  -I DIR       append DIR to the Texinfo search path.
+  --common ARG pass ARG in all invocations.
+  --html ARG   pass ARG to makeinfo or texi2html for HTML targets,
+                 instead of '$htmlarg'.
+  --info ARG   pass ARG to makeinfo for Info, instead of --no-split.
+  --no-ascii   skip generating the plain text output.
+  --no-html    skip generating the html output.
+  --no-info    skip generating the info output.
+  --no-tex     skip generating the dvi and pdf output.
+  --source ARG include ARG in tar archive of sources.
+  --split HOW  make split HTML by node, section, chapter; default node.
+  --tex ARG    pass ARG to texi2dvi for DVI and PDF, instead of -t @finalout.
+
+  --texi2html  use texi2html to make HTML target, with all split versions.
+  --docbook    convert through DocBook too (xml, txt, html, pdf).
+
+  --help       display this help and exit successfully.
+  --version    display version information and exit successfully.
+
+Simple example: $prog --email bug-gnu-emacs@gnu.org emacs \"GNU Emacs Manual\"
+
+Typical sequence:
+  cd PACKAGESOURCE/doc
+  wget \"$scripturl\"
+  wget \"$templateurl\"
+  $prog --email BUGLIST MANUAL \"GNU MANUAL - 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.
+
+Please use the --email ADDRESS option so your own bug-reporting
+address will be used in the generated HTML pages.
+
+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 MANUAL 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.)
+
+As implied above, by default monolithic Info files are generated.
+If you want split Info, or other Info options, use --info to override.
+
+You can set the environment variables MAKEINFO, TEXI2DVI, TEXI2HTML,
+and PERL 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, and DOCBOOK2TXT are also consulted.
+
+By default, makeinfo and texi2dvi are 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, see the
+SETLANG setting in the source.
+
+Email bug reports or enhancement requests to bug-gnulib@gnu.org.
+"
+
+while test $# -gt 0; do
+  case $1 in
+    -s)          shift; srcfile=$1;;
+    -o)          shift; outdir=$1;;
+    -I)          shift; dirargs="$dirargs -I '$1'"; dirs="$dirs $1";;
+    --common)    shift; commonarg=$1;;
+    --docbook)   docbook=yes;;
+    --email)     shift; EMAIL=$1;;
+    --html)      shift; htmlarg=$1;;
+    --info)      shift; infoarg=$1;;
+    --no-ascii)  generate_ascii=false;;
+    --no-html)   generate_ascii=false;;
+    --no-info)   generate_info=false;;
+    --no-tex)    generate_tex=false;;
+    --source)    shift; source_extra=$1;;
+    --split)     shift; split=$1;;
+    --tex)       shift; texarg=$1;;
+    --texi2html) use_texi2html=1;;
+
+    --help)      echo "$usage"; exit 0;;
+    --version)   echo "$version"; exit 0;;
+    -*)
+      echo "$0: Unknown 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
+
+# makeinfo uses the dirargs, but texi2dvi doesn't.
+commonarg=" $dirargs $commonarg"
+
+# For most of the following, the base name is just $PACKAGE
+base=$PACKAGE
+
+if test -n "$srcfile"; then
+  # but here, we use the basename of $srcfile
+  base=`basename "$srcfile"`
+  case $base in
+    *.txi|*.texi|*.texinfo) base=`echo "$base"|sed 's/\.[texinfo]*$//'`;;
+  esac
+  PACKAGE=$base
+elif 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
+
+# Function to return size of $1 in something resembling kilobytes.
+calcsize()
+{
+  size=`ls -ksl $1 | awk '{print $1}'`
+  echo $size
+}
+
+# copy_images OUTDIR HTML-FILE...
+# -------------------------------
+# Copy all the images needed by the HTML-FILEs into OUTDIR.
+# Look for them in . and the -I directories; this is simpler than what
+# makeinfo supports with -I, but hopefully it will suffice.
+copy_images()
+{
+  local odir
+  odir=$1
+  shift
+  $PERL -n -e "
+BEGIN {
+  \$me = '$prog';
+  \$odir = '$odir';
+  @dirs = qw(. $dirs);
+}
+" -e '
+/<img src="(.*?)"/g && ++$need{$1};
+
+END {
+  #print "$me: @{[keys %need]}\n";  # for debugging, show images found.
+  FILE: for my $f (keys %need) {
+    for my $d (@dirs) {
+      if (-f "$d/$f") {
+        use File::Basename;
+        my $dest = dirname ("$odir/$f");
+        #
+        use File::Path;
+        -d $dest || mkpath ($dest)
+          || die "$me: cannot mkdir $dest: $!\n";
+        #
+        use File::Copy;
+        copy ("$d/$f", $dest)
+          || die "$me: cannot copy $d/$f to $dest: $!\n";
+        next FILE;
+      }
+    }
+    die "$me: $ARGV: cannot find image $f\n";
+  }
+}
+' -- "$@" || exit 1
+}
+
+case $outdir in
+  /*) abs_outdir=$outdir;;
+  *)  abs_outdir=$srcdir/$outdir;;
+esac
+
+echo "Making output for $srcfile"
+echo " in `pwd`"
+mkdir -p "$outdir/"
+
+# \f
+if $generate_info; then
+  cmd="$SETLANG $MAKEINFO -o $PACKAGE.info $commonarg $infoarg \"$srcfile\""
+  echo "Generating info... ($cmd)"
+  rm -f $PACKAGE.info* # get rid of any strays
+  eval "$cmd"
+  tar czf "$outdir/$PACKAGE.info.tar.gz" $PACKAGE.info*
+  ls -l "$outdir/$PACKAGE.info.tar.gz"
+  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.
+fi  # end info
+
+# \f
+if $generate_tex; then
+  cmd="$SETLANG $TEXI2DVI $dirargs $texarg \"$srcfile\""
+  printf "\nGenerating dvi... ($cmd)\n"
+  eval "$cmd"
+  # compress/finish dvi:
+  gzip -f -9 $PACKAGE.dvi
+  dvi_gz_size=`calcsize $PACKAGE.dvi.gz`
+  mv $PACKAGE.dvi.gz "$outdir/"
+  ls -l "$outdir/$PACKAGE.dvi.gz"
+
+  cmd="$SETLANG $TEXI2DVI --pdf $dirargs $texarg \"$srcfile\""
+  printf "\nGenerating pdf... ($cmd)\n"
+  eval "$cmd"
+  pdf_size=`calcsize $PACKAGE.pdf`
+  mv $PACKAGE.pdf "$outdir/"
+  ls -l "$outdir/$PACKAGE.pdf"
+fi # end tex (dvi + pdf)
+
+# \f
+if $generate_ascii; then
+  opt="-o $PACKAGE.txt --no-split --no-headers $commonarg"
+  cmd="$SETLANG $MAKEINFO $opt \"$srcfile\""
+  printf "\nGenerating ascii... ($cmd)\n"
+  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/"
+  ls -l "$outdir/$PACKAGE.txt" "$outdir/$PACKAGE.txt.gz"
+fi
+
+# \f
+
+if $generate_html; then
+# Split HTML at level $1.  Used for texi2html.
+html_split()
+{
+  opt="--split=$1 --node-files $commonarg $htmlarg"
+  cmd="$SETLANG $TEXI2HTML --output $PACKAGE.html $opt \"$srcfile\""
+  printf "\nGenerating html by $1... ($cmd)\n"
+  eval "$cmd"
+  split_html_dir=$PACKAGE.html
+  (
+    cd ${split_html_dir} || exit 1
+    ln -sf ${PACKAGE}.html index.html
+    tar -czf "$abs_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}
+}
+
+if test -z "$use_texi2html"; then
+  opt="--no-split --html -o $PACKAGE.html $commonarg $htmlarg"
+  cmd="$SETLANG $MAKEINFO $opt \"$srcfile\""
+  printf "\nGenerating monolithic html... ($cmd)\n"
+  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"`
+  copy_images "$outdir/" $PACKAGE.html
+  mv $PACKAGE.html "$outdir/"
+  ls -l "$outdir/$PACKAGE.html" "$outdir/$PACKAGE.html.gz"
+
+  # Before Texinfo 5.0, makeinfo did not accept a --split=HOW option,
+  # it just always split by node.  So if we're splitting by node anyway,
+  # leave it out.
+  if test "x$split" = xnode; then
+    split_arg=
+  else
+    split_arg=--split=$split
+  fi
+  #
+  opt="--html -o $PACKAGE.html $split_arg $commonarg $htmlarg"
+  cmd="$SETLANG $MAKEINFO $opt \"$srcfile\""
+  printf "\nGenerating html by $split... ($cmd)\n"
+  eval "$cmd"
+  split_html_dir=$PACKAGE.html
+  copy_images $split_html_dir/ $split_html_dir/*.html
+  (
+    cd $split_html_dir || exit 1
+    tar -czf "$abs_outdir/$PACKAGE.html_$split.tar.gz" -- *
+  )
+  eval \
+    html_${split}_tgz_size=`calcsize "$outdir/$PACKAGE.html_$split.tar.gz"`
+  rm -rf "$outdir/html_$split/"
+  mv $split_html_dir "$outdir/html_$split/"
+  du -s "$outdir/html_$split/"
+  ls -l "$outdir/$PACKAGE.html_$split.tar.gz"
+
+else # use texi2html:
+  opt="--output $PACKAGE.html $commonarg $htmlarg"
+  cmd="$SETLANG $TEXI2HTML $opt \"$srcfile\""
+  printf "\nGenerating monolithic html with texi2html... ($cmd)\n"
+  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 node
+  html_split chapter
+  html_split section
+fi
+fi # end html
+
+# \f
+printf "\nMaking .tar.gz for sources...\n"
+d=`dirname $srcfile`
+(
+  cd "$d"
+  srcfiles=`ls -d *.texinfo *.texi *.txi *.eps $source_extra 2>/dev/null` || true
+  tar czfh "$abs_outdir/$PACKAGE.texi.tar.gz" $srcfiles
+  ls -l "$abs_outdir/$PACKAGE.texi.tar.gz"
+)
+texi_tgz_size=`calcsize "$outdir/$PACKAGE.texi.tar.gz"`
+
+# \f
+# Do everything again through docbook.
+if test -n "$docbook"; then
+  opt="-o - --docbook $commonarg"
+  cmd="$SETLANG $MAKEINFO $opt \"$srcfile\" >${srcdir}/$PACKAGE-db.xml"
+  printf "\nGenerating docbook XML... ($cmd)\n"
+  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/"
+
+  split_html_db_dir=html_node_db
+  opt="$commonarg -o $split_html_db_dir"
+  cmd="$DOCBOOK2HTML $opt \"${outdir}/$PACKAGE-db.xml\""
+  printf "\nGenerating docbook HTML... ($cmd)\n"
+  eval "$cmd"
+  (
+    cd ${split_html_db_dir} || exit 1
+    tar -czf "$abs_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\""
+  printf "\nGenerating docbook ASCII... ($cmd)\n"
+  eval "$cmd"
+  docbook_ascii_size=`calcsize $PACKAGE-db.txt`
+  mv $PACKAGE-db.txt "$outdir/"
+
+  cmd="$DOCBOOK2PDF \"${outdir}/$PACKAGE-db.xml\""
+  printf "\nGenerating docbook PDF... ($cmd)\n"
+  eval "$cmd"
+  docbook_pdf_size=`calcsize $PACKAGE-db.pdf`
+  mv $PACKAGE-db.pdf "$outdir/"
+fi
+
+# \f
+printf "\nMaking index.html for $PACKAGE...\n"
+if test -z "$use_texi2html"; then
+  CONDS="/%%IF  *HTML_SECTION%%/,/%%ENDIF  *HTML_SECTION%%/d;\
+         /%%IF  *HTML_CHAPTER%%/,/%%ENDIF  *HTML_CHAPTER%%/d"
+else
+  # should take account of --split here.
+  CONDS="/%%ENDIF.*%%/d;/%%IF  *HTML_SECTION%%/d;/%%IF  *HTML_CHAPTER%%/d"
+fi
+
+curdate=`$SETLANG date '+%B %d, %Y'`
+sed \
+   -e "s!%%TITLE%%!$MANUAL_TITLE!g" \
+   -e "s!%%EMAIL%%!$EMAIL!g" \
+   -e "s!%%PACKAGE%%!$PACKAGE!g" \
+   -e "s!%%DATE%%!$curdate!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!%%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_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" \
+   -e "$CONDS" \
+$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"
+# time-stamp-end: "$"
+# End:
index 87ae71e1e72ade85dd40249a7e78012787159a18..69a4c6478e95f75d4beeca50c5f62017581db068 100644 (file)
@@ -3,6 +3,7 @@
 @setfilename gnunet-c-tutorial.info
 @documentencoding UTF-8
 @settitle GNUnet C Tutorial
+@exampleindent 2
 @c %**end of header
 
 @c including 'version.texi' makes makeinfo throw errors.
@@ -73,7 +74,6 @@ team: @uref{https://gnunet.org/contact_information}
 
 @menu
 
-* Vocabulary::                          Vocabulary used throughout this document
 * Installing GNUnet::                   Installing GNUnet
 * Introduction to GNUnet Architecture:: Introduction to GNUnet Architecture
 * First Steps with GNUnet::             First Steps with GNUnet
@@ -82,8 +82,6 @@ team: @uref{https://gnunet.org/contact_information}
 @detailmenu
  --- The Detailed Node Listing ---
 
-Vocabulary
-
 Installing GNUnet
 
 * Obtaining a stable version::
@@ -116,55 +114,6 @@ Developing Applications
 @end detailmenu
 @end menu
 
-@node Vocabulary
-@chapter Vocabulary
-
-@menu
-* Words and characters::
-* Technical Assumptions::
-@end menu
-
-@node Words and characters
-@section Words and characters
-
-Throughout this document we use certain words and characters.
-
-@enumerate
-@item
-@c ``@command{#}'' in example code blocks describes commands you execute as root.
-``@command{#}'' in example code blocks describes commands, ie comments.
-
-@example
-# Do the foobar thing:
-$ make foobar
-@end example
-
-@item
-Dollarsign ``@command{$}'' in example code blocks describes commands you execute as
-unprivileged users.
-
-@example
-$ cd foo; ./configure --example-switch
-@end example
-
-@item
-Backslash ``@command{\}'' describes linebreaks.
-
-@example
-./configure --foo --bar --baz \
- --short-loop
-@end example
-
-...expands to @code{./configure --foo --bar --baz --short-loop}
-
-@end enumerate
-
-@node Technical Assumptions
-@section Technical Assumptions
-
-@c Is it really assuming Bash (ie Bash extensions of POSIX being used)?
-The shell on GNU systems is assumed to be Bash.
-
 @node Installing GNUnet
 @chapter Installing GNUnet
 
index 035ade80e6796ffcf6e78e3ef158843b827d19fa..cbceccbb35652715cf9bcc4e02539b410d67bb93 100644 (file)
@@ -5,6 +5,7 @@
 @setfilename gnunet.info
 @documentencoding UTF-8
 @settitle GNUnet Reference Manual
+@exampleindent 2
 @c %**end of header
 
 @include version.texi
@@ -58,11 +59,12 @@ Edition @value{EDITION} @*
 @insertcopying
 @end titlepage
 
+@summarycontents
 @contents
-@c *********************************************************************
+
 @node Top
 @top Contributing to GNUnet
-@c *********************************************************************
+
 
 This document describes GNUnet version @value{VERSION}.
 
@@ -105,6 +107,7 @@ in the respective authors file or section, please do let us know.
 @menu
 
 * Philosophy::                      About GNUnet
+* Vocabulary::                      Vocabulary
 * GNUnet Installation Handbook::    How to install GNUnet
 * Using GNUnet::                    Using GNUnet
 * GNUnet Developer Handbook::       Developing GNUnet
@@ -134,10 +137,75 @@ Philosophy
 * Backup of Identities and Egos::
 * Revocation::
 
-Installation
+Vocabulary
+
+* Words and characters::
+* Technical Assumptions::
+
+GNUnet Installation Handbook
 
 * Dependencies::
-* External dependencies::
+* Pre-installation notes::
+* Generic installation instructions::
+* Build instructions for Ubuntu 12.04 using Git::
+* Build Instructions for Microsoft Windows Platforms::
+* Build instructions for Debian 7.5::
+* Installing GNUnet from Git on Ubuntu 14.4::
+* Build instructions for Debian 8::
+* Outdated build instructions for previous revisions::
+* Portable GNUnet::
+* The graphical configuration interface::
+* How to start and stop a GNUnet peer::
+
+Using GNUnet
+
+* Checking the Installation::
+* First steps - File-sharing::
+* First steps - Using the GNU Name System::
+* First steps - Using GNUnet Conversation::
+* First steps - Using the GNUnet VPN::
+* File-sharing::
+* The GNU Name System::
+* Using the Virtual Public Network::
+
+GNUnet Developer Handbook
+
+* Developer Introduction::
+* Code overview::
+* System Architecture::
+* Subsystem stability::
+* Naming conventions and coding style guide::
+* Build-system::
+* Developing extensions for GNUnet using the gnunet-ext template::
+* Writing testcases::
+* GNUnet's TESTING library::
+* Performance regression analysis with Gauger::
+* GNUnet's TESTBED Subsystem::
+* libgnunetutil::
+* The Automatic Restart Manager (ARM)::
+* GNUnet's TRANSPORT Subsystem::
+* NAT library::
+* Distance-Vector plugin::
+* SMTP plugin::
+* Bluetooth plugin::
+* WLAN plugin::
+* The ATS Subsystem::
+* GNUnet's CORE Subsystem::
+* GNUnet's CADET subsystem::
+* GNUnet's NSE subsystem::
+* GNUnet's HOSTLIST subsystem::
+* GNUnet's IDENTITY subsystem::
+* GNUnet's NAMESTORE Subsystem::
+* GNUnet's PEERINFO subsystem::
+* GNUnet's PEERSTORE subsystem::
+* GNUnet's SET Subsystem::
+* GNUnet's STATISTICS subsystem::
+* GNUnet's Distributed Hash Table (DHT)::
+* The GNU Name System (GNS)::
+* The GNS Namecache::
+* The REVOCATION Subsystem::
+* GNUnet's File-sharing (FS) Subsystem::
+* GNUnet's REGEX Subsystem::
 
 @end detailmenu
 @end menu
@@ -146,6 +214,8 @@ Installation
 @include chapters/philosophy.texi
 @c *********************************************************************
 
+@include chapters/vocabulary.texi
+
 @c *********************************************************************
 @include chapters/installation.texi
 @c *********************************************************************
@@ -156,9 +226,9 @@ Installation
 
 @c *********************************************************************
 @include chapters/developer.texi
+@c @include gnunet-c-tutorial.texi
 @c *********************************************************************
 
-
 @c *********************************************************************
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License
diff --git a/doc/hacks.el b/doc/hacks.el
new file mode 100644 (file)
index 0000000..9f271b3
--- /dev/null
@@ -0,0 +1,17 @@
+;;;; hacks.el --- a few functions to help me work on the manual
+;;;; Jim Blandy <jimb@red-bean.com> --- October 1998
+;;;; -- imported from https://git.savannah.gnu.org/cgit/guile.git/tree/doc/hacks.el
+
+(defun jh-exemplify-region (start end)
+  (interactive "r")
+  (save-excursion
+    (save-restriction
+      (narrow-to-region start end)
+
+      ;; Texinfo doesn't handle tabs well.
+      (untabify (point-min) (point-max))
+
+      ;; Quote any characters special to texinfo.
+      (goto-char (point-min))
+      (while (re-search-forward "[{}@]" nil t)
+       (replace-match "@\\&")))))