From: ng0 Date: Sat, 21 Oct 2017 15:45:29 +0000 (+0000) Subject: doc changes X-Git-Tag: gnunet-0.11.0rc0~101^2~26 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=f40c4ab2de20ec6a070b3c07a082633be10be80f;p=oweals%2Fgnunet.git doc changes 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 --- diff --git a/contrib/packages/guix/gnunet-doc.scm b/contrib/packages/guix/gnunet-doc.scm index da714077f..98ab0ede7 100644 --- a/contrib/packages/guix/gnunet-doc.scm +++ b/contrib/packages/guix/gnunet-doc.scm @@ -144,7 +144,10 @@ (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"))))))) diff --git a/doc/.gitignore b/doc/.gitignore index 25617d1b0..f46d61e70 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -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 diff --git a/doc/Makefile.am b/doc/Makefile.am index 74b1300b4..bb0c5e0bf 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -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 diff --git a/doc/chapters/installation.texi b/doc/chapters/installation.texi index c7f15f335..63ab98e6d 100644 --- a/doc/chapters/installation.texi +++ b/doc/chapters/installation.texi @@ -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 index 000000000..8b6cbe35a --- /dev/null +++ b/doc/chapters/vocabulary.texi @@ -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 index 000000000..8719248d0 --- /dev/null +++ b/doc/docstyle.css @@ -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 index 000000000..3b71b36a2 --- /dev/null +++ b/doc/gendocs.sh @@ -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 . +# +# 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 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/" + +# +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 + +# +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) + +# +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 + +# + +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 + +# +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"` + +# +# 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 + +# +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: diff --git a/doc/gnunet-c-tutorial.texi b/doc/gnunet-c-tutorial.texi index 87ae71e1e..69a4c6478 100644 --- a/doc/gnunet-c-tutorial.texi +++ b/doc/gnunet-c-tutorial.texi @@ -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 diff --git a/doc/gnunet.texi b/doc/gnunet.texi index 035ade80e..cbceccbb3 100644 --- a/doc/gnunet.texi +++ b/doc/gnunet.texi @@ -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 index 000000000..9f271b3af --- /dev/null +++ b/doc/hacks.el @@ -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 "@\\&")))))