From 6e8997d86a0e6af3575f0f794380d4186fd446e4 Mon Sep 17 00:00:00 2001 From: Stefano Lattarini Date: Sat, 8 Dec 2012 19:49:33 +0100 Subject: [PATCH] docs: copy the 'gendocs.sh' script from Texinfo CVS repository As well as the 'gendocs_template' file. And enhance the "make fetch" target to keep them synced. It's better than having to fetch these files by hand each time a release is to be made. * Makefile.am (FETCHFILES): List 'gendocs.sh' and 'gendocs_template'. (fetch): Fetch them, into 'lib/'. (EXRA_DIST): Distribute them. * HACKING: Adjust instructions for generation of manuals. Signed-off-by: Stefano Lattarini --- HACKING | 5 +- Makefile.am | 7 +- lib/gendocs.sh | 434 +++++++++++++++++++++++++++++++++++++++++++++++++++ lib/gendocs_template | 87 +++++++++++ 4 files changed, 529 insertions(+), 4 deletions(-) create mode 100755 lib/gendocs.sh create mode 100644 lib/gendocs_template diff --git a/HACKING b/HACKING index fe2bc5136..118a2e322 100644 --- a/HACKING +++ b/HACKING @@ -261,9 +261,8 @@ * For stable releases, update the manuals at www.gnu.org: - Generate manuals: cd doc - wget "http://savannah.gnu.org/cgi-bin/viewcvs/~checkout~/texinfo/texinfo/util/gendocs.sh" - wget "http://savannah.gnu.org/cgi-bin/viewcvs/~checkout~/texinfo/texinfo/util/gendocs_template" - sh ./gendocs.sh --email bug-automake@gnu.org automake "GNU Automake" + export GENDOCS_TEMPLATE_DIR=../lib + sh ../lib/gendoc.sh --email bug-automake@gnu.org automake "GNU Automake" - copy manuals recursively to web cvs, - commit. - Check for link errors, fix them, recheck until convergence: diff --git a/Makefile.am b/Makefile.am index 304fca55d..8c5fa7198 100644 --- a/Makefile.am +++ b/Makefile.am @@ -963,8 +963,10 @@ FETCHFILES = \ INSTALL \ config.guess \ config.sub \ -gnupload \ +gendocs.sh \ +gendocs_template \ gitlog-to-changelog \ +gnupload \ texinfo.tex \ update-copyright @@ -977,6 +979,8 @@ fetch: $(WGET_SV_GIT_CF)config.guess -O config.guess && \ $(WGET_SV_GIT_CF)config.sub -O config.sub && \ $(WGET_SV_CVS)texinfo/texinfo/doc/texinfo.tex -O texinfo.tex && \ + $(WGET_SV_CVS)texinfo/texinfo/util/gendocs.sh -O gendocs.sh && \ + $(WGET_SV_CVS)texinfo/texinfo/util/gendocs_template -O gendocs_template && \ $(WGET_SV_GIT_GL)doc/INSTALL -O INSTALL && \ $(WGET_SV_GIT_GL)build-aux/gnupload -O gnupload && \ $(WGET_SV_GIT_GL)build-aux/update-copyright -O update-copyright && \ @@ -997,6 +1001,7 @@ fetch: exit $$stat .PHONY: fetch +EXTRA_DIST += lib/gendocs.sh lib/gendocs_template ## ------------------------------------------------ ## ## Update copyright years of all committed files. ## diff --git a/lib/gendocs.sh b/lib/gendocs.sh new file mode 100755 index 000000000..0c0bc4b0f --- /dev/null +++ b/lib/gendocs.sh @@ -0,0 +1,434 @@ +#!/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=2012-10-27.11 + +# Copyright 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 +# 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-texinfo@gnu.org. +# +# The latest version of this script, and the companion template, is +# available from Texinfo CVS: +# http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs.sh +# http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template +# +# An up-to-date copy is also maintained in Gnulib (gnu.org/software/gnulib). + +# TODO: +# - image importation 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://savannah.gnu.org/cgi-bin/viewcvs/~checkout~/texinfo/texinfo/util/gendocs.sh" +templateurl="http://savannah.gnu.org/cgi-bin/viewcvs/~checkout~/texinfo/texinfo/util/gendocs_template" + +: ${SETLANG="env LANG= LC_MESSAGES= LC_ALL= LANGUAGE="} +: ${MAKEINFO="makeinfo"} +: ${TEXI2DVI="texi2dvi -t @finalout"} +: ${DOCBOOK2HTML="docbook2html"} +: ${DOCBOOK2PDF="docbook2pdf"} +: ${DOCBOOK2TXT="docbook2txt"} +: ${GENDOCS_TEMPLATE_DIR="."} +: ${PERL='perl'} +: ${TEXI2HTML="texi2html"} +unset CDPATH +unset use_texi2html + +version="gendocs.sh $scriptversion + +Copyright 2012 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: + -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. + --email ADR use ADR as contact in generated web pages. + --docbook convert through DocBook too (xml, txt, html, pdf). + --html ARG pass indicated ARG to makeinfo or texi2html for HTML targets. + --info ARG pass indicated ARG to makeinfo for Info, instead of --no-split. + --texi2html use texi2html to generate HTML targets. + --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 do use the --email ADDRESS option to specify your bug-reporting +address 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 respected. + +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-texinfo@gnu.org. +" + +MANUAL_TITLE= +PACKAGE= +EMAIL=webmasters@gnu.org # please override with --email +commonarg= # Options passed to all the tools (-I dir). +dirs= # -I's directories. +htmlarg= +infoarg=--no-split +outdir=manual +srcfile= + +while test $# -gt 0; do + case $1 in + --email) shift; EMAIL=$1;; + --help) echo "$usage"; exit 0;; + --version) echo "$version"; exit 0;; + -s) shift; srcfile=$1;; + -o) shift; outdir=$1;; + -I) shift; commonarg="$commonarg -I '$1'"; dirs="$dirs $1";; + --docbook) docbook=yes;; + --html) shift; htmlarg=$1;; + --info) shift; infoarg=$1;; + --texi2html) use_texi2html=1;; + -*) + 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 + +# 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 the -I directories. +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 "Generating output formats for $srcfile" + +cmd="$SETLANG $MAKEINFO -o $PACKAGE.info $commonarg $infoarg \"$srcfile\"" +echo "Generating info file(s)... ($cmd)" +eval "$cmd" +mkdir -p "$outdir/" +tar czf "$outdir/$PACKAGE.info.tar.gz" $PACKAGE.info* +info_tgz_size=`calcsize "$outdir/$PACKAGE.info.tar.gz"` +# do not mv the info files, there's no point in having them available +# separately on the web. + +cmd="$SETLANG $TEXI2DVI $commonarg \"$srcfile\"" +echo "Generating dvi ... ($cmd)" +eval "$cmd" + +# compress/finish dvi: +gzip -f -9 $PACKAGE.dvi +dvi_gz_size=`calcsize $PACKAGE.dvi.gz` +mv $PACKAGE.dvi.gz "$outdir/" + +cmd="$SETLANG $TEXI2DVI --pdf $commonarg \"$srcfile\"" +echo "Generating pdf ... ($cmd)" +eval "$cmd" +pdf_size=`calcsize $PACKAGE.pdf` +mv $PACKAGE.pdf "$outdir/" + +opt="-o $PACKAGE.txt --no-split --no-headers $commonarg" +cmd="$SETLANG $MAKEINFO $opt \"$srcfile\"" +echo "Generating ASCII... ($cmd)" +eval "$cmd" +ascii_size=`calcsize $PACKAGE.txt` +gzip -f -9 -c $PACKAGE.txt >"$outdir/$PACKAGE.txt.gz" +ascii_gz_size=`calcsize "$outdir/$PACKAGE.txt.gz"` +mv $PACKAGE.txt "$outdir/" + +html_split() +{ + opt="--split=$1 $commonarg $htmlarg --node-files" + cmd="$SETLANG $TEXI2HTML --output $PACKAGE.html $opt \"$srcfile\"" + echo "Generating html by $1... ($cmd)" + eval "$cmd" + split_html_dir=$PACKAGE.html + ( + cd ${split_html_dir} || exit 1 + ln -sf ${PACKAGE}.html index.html + tar -czf "$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\"" + echo "Generating monolithic html... ($cmd)" + rm -rf $PACKAGE.html # in case a directory is left over + eval "$cmd" + html_mono_size=`calcsize $PACKAGE.html` + gzip -f -9 -c $PACKAGE.html >"$outdir/$PACKAGE.html.gz" + html_mono_gz_size=`calcsize "$outdir/$PACKAGE.html.gz"` + copy_images "$outdir/" $PACKAGE.html + mv $PACKAGE.html "$outdir/" + + opt="--html -o $PACKAGE.html $commonarg $htmlarg" + cmd="$SETLANG $MAKEINFO $opt \"$srcfile\"" + echo "Generating html by node... ($cmd)" + 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_node.tar.gz" -- * + ) + html_node_tgz_size=`calcsize "$outdir/$PACKAGE.html_node.tar.gz"` + rm -rf "$outdir/html_node/" + mv $split_html_dir "$outdir/html_node/" +else + opt="--output $PACKAGE.html $commonarg $htmlarg" + cmd="$SETLANG $TEXI2HTML $opt \"$srcfile\"" + echo "Generating monolithic html... ($cmd)" + rm -rf $PACKAGE.html # in case a directory is left over + eval "$cmd" + html_mono_size=`calcsize $PACKAGE.html` + gzip -f -9 -c $PACKAGE.html >"$outdir/$PACKAGE.html.gz" + html_mono_gz_size=`calcsize "$outdir/$PACKAGE.html.gz"` + mv $PACKAGE.html "$outdir/" + + html_split node + html_split chapter + html_split section +fi + +echo Making .tar.gz for sources... +d=`dirname $srcfile` +( + cd "$d" + srcfiles=`ls *.texinfo *.texi *.txi *.eps 2>/dev/null` || true + tar cvzfh "$abs_outdir/$PACKAGE.texi.tar.gz" $srcfiles +) +texi_tgz_size=`calcsize "$outdir/$PACKAGE.texi.tar.gz"` + +if test -n "$docbook"; then + opt="-o - --docbook $commonarg" + cmd="$SETLANG $MAKEINFO $opt \"$srcfile\" >${srcdir}/$PACKAGE-db.xml" + echo "Generating docbook XML... ($cmd)" + eval "$cmd" + docbook_xml_size=`calcsize $PACKAGE-db.xml` + gzip -f -9 -c $PACKAGE-db.xml >"$outdir/$PACKAGE-db.xml.gz" + docbook_xml_gz_size=`calcsize "$outdir/$PACKAGE-db.xml.gz"` + mv $PACKAGE-db.xml "$outdir/" + + split_html_db_dir=html_node_db + opt="$commonarg -o $split_html_db_dir" + cmd="$DOCBOOK2HTML $opt \"${outdir}/$PACKAGE-db.xml\"" + echo "Generating docbook HTML... ($cmd)" + 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\"" + echo "Generating docbook ASCII... ($cmd)" + eval "$cmd" + docbook_ascii_size=`calcsize $PACKAGE-db.txt` + mv $PACKAGE-db.txt "$outdir/" + + cmd="$DOCBOOK2PDF \"${outdir}/$PACKAGE-db.xml\"" + echo "Generating docbook PDF... ($cmd)" + eval "$cmd" + docbook_pdf_size=`calcsize $PACKAGE-db.pdf` + mv $PACKAGE-db.pdf "$outdir/" +fi + +echo "Writing index file..." +if test -z "$use_texi2html"; then + CONDS="/%%IF *HTML_SECTION%%/,/%%ENDIF *HTML_SECTION%%/d;\ + /%%IF *HTML_CHAPTER%%/,/%%ENDIF *HTML_CHAPTER%%/d" +else + 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/lib/gendocs_template b/lib/gendocs_template new file mode 100644 index 000000000..a62ad6167 --- /dev/null +++ b/lib/gendocs_template @@ -0,0 +1,87 @@ +<!--#include virtual="/server/header.html" --> +<title>%%TITLE%% - GNU Project - Free Software Foundation (FSF) + +

%%TITLE%%

+ +
Free Software Foundation
+
last updated %%DATE%%
+ +

This manual (%%PACKAGE%%) is available in the following formats:

+ + + +

You can buy printed copies of +some manuals (among other items) from the Free Software Foundation; +this helps support FSF activities.

+ +

(This page generated by the %%SCRIPTNAME%% +script.)

+ + + + + + + + -- 2.11.4.GIT