diff options
author | Sergey Poznyakoff <gray@gnu.org> | 2021-03-01 20:30:56 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org> | 2021-03-01 20:44:31 +0200 |
commit | c67d223854d7c0f457dc6c7518a04e648873b50b (patch) | |
tree | b970a3adddb7cffbb30e9e3bd8339b0851fd1ef9 | |
parent | 55f2a0772e08b9febac3ac0de5cb048d4c60d2f5 (diff) | |
download | tar-c67d223854d7c0f457dc6c7518a04e648873b50b.tar.gz |
Fix building the online version of the manual.
* doc/Makefile.am (GENDOCS): Use the version from the tar repository.
(manual): Set the DISTRIN rendition.
(manual-rebuild): New goal.
* doc/README.manual: New file. Instructions for maintainers on how to
update web documentation.
* doc/gendocs.sh: A version from gnulib fixed as per
https://lists.gnu.org/archive/html/bug-gnulib/2021-03/msg00002.html.
* doc/gendocs_template: Updated version from gnulib.
* doc/intern.texi: Fix the use of UNREVISED.
* doc/tar.texi: Fix the use of GNUTAR.
-rw-r--r-- | doc/Makefile.am | 9 | ||||
-rw-r--r-- | doc/README.manual | 91 | ||||
-rwxr-xr-x | doc/gendocs.sh | 512 | ||||
-rw-r--r--[-rwxr-xr-x] | doc/gendocs_template | 147 | ||||
-rw-r--r-- | doc/intern.texi | 4 | ||||
-rw-r--r-- | doc/tar.texi | 32 |
6 files changed, 692 insertions, 103 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 55ddcf46..b8c90202 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -138,9 +138,9 @@ check-docs: clean-local: rm -rf manual -GENDOCS=gendocs.sh +GENDOCS=$(srcdir)/gendocs.sh -TEXI2DVI=texi2dvi -t '@set $(RENDITION)' -E +TEXI2DVI=texi2dvi -E # Make sure you set TEXINPUTS # Usual value is: @@ -148,5 +148,8 @@ TEXI2DVI=texi2dvi -t '@set $(RENDITION)' -E manual: TEXINPUTS=$(srcdir):$(top_srcdir)/build-tex:$(TEXINPUTS) \ MAKEINFO="$(MAKEINFO) $(MAKEINFOFLAGS)" \ - TEXI2DVI="$(TEXI2DVI) -t @finalout" \ + TEXI2DVI="$(TEXI2DVI) -t '@set DISTRIB' -t @finalout" \ $(GENDOCS) --texi2html tar 'GNU tar manual' + +manual-rebuild: clean-local manual + diff --git a/doc/README.manual b/doc/README.manual new file mode 100644 index 00000000..b75e9134 --- /dev/null +++ b/doc/README.manual @@ -0,0 +1,91 @@ +* Overview + +This file is a short instruction for maintainers on how to create and +publish the online version of the Tar Manual. + +In the sections below we assume that the tar project has been properly +cloned from the git repo, bootstrapped and configured. We also assume +that top-level directory of the project is the current local directory. + +* Creating the web manual + +To create the online version of the documentation, run + + make -C doc manual-rebuild + +This will create the directory doc/manual populated with the tar +documentation files in various formats. If the doc/manual directory +already exists, it will be removed prior to rebuilding. + +The command produces very copious output. We advise you to examine it +closely to make sure no error messages slip your attention. + +For the completeness sake, there are two more Makefile goals related +to the online manual: + +** make -C doc clean-local + +Removes the doc/manual directory, if it exists. + +** make -C doc manual + +Builds the doc/manual, unless it already exists. + +* CVS Repository + +The online tar manual[1] is a part of tar web pages[2] and is +traditionally maintained in the CVS repository[3]. To publish the +generated documentation, you will need first to check out tar web +pages from the CVS. To do so, run + + cvs -z3 -d:ext:<username>@cvs.savannah.gnu.org:/web/tar co tar + +where <username> is your user name on Savannah. For the rest of this +document we will assume that the checked out version of the tar web +pages resides in the ~/websrc/tar directory. + +If you have already checked out the web pages, be sure to update them +before publishing: + + cd ~/websrc/tar + cvs update + +* Publishing + +To publish the created manual, change to the tar top-level directory +and run: + + rsync -avz --exclude CVS --delete manual ~/websrc/tar + +This will synchronize the newly created manual pages with the content +of the CVS sandbox. Then, change to the ~/websrc/tar directory and +schedule any removed files for removal and any new files for addition +to the repository: + + cvs diff --brief 2>&1 | sed -n 's/.*cannot find //p' | xargs cvs rm + cvs diff --brief 2>&1 | sed -n 's/^? //p' | xargs cvs add + +Then commit your changes: + + cvs commit + +Once the changes are committed to CVS a job is scheduled on the server, +which synchronizes them with the content of the directory served by +the httpd daemon. Normally such synchronization happens within +several seconds from the commit. + +For more information about CVS, please see its documentation[4]. + +* References + +[1] https://www.gnu.org/software/tar/manual/ +[2] https://www.gnu.org/software/tar/ +[3] https://web.cvs.savannah.gnu.org/viewvc/tar/ +[4] https://www.nongnu.org/cvs/#documentation + + +Local Variables: +mode: outline +paragraph-separate: "[ ]*$" +version-control: never +End: diff --git a/doc/gendocs.sh b/doc/gendocs.sh new file mode 100755 index 00000000..0828905f --- /dev/null +++ b/doc/gendocs.sh @@ -0,0 +1,512 @@ +#!/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=2021-03-01.13 + +# Copyright 2003-2021 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 <https://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: +# +# https://git.savannah.gnu.org/cgit/gnulib.git/tree/build-aux/gendocs.sh +# https://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="https://git.savannah.gnu.org/cgit/gnulib.git/plain/build-aux/gendocs.sh" +templateurl="https://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" +default_htmlarg=true +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 2021 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: + https://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; default_htmlarg=false; 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 $default_htmlarg && test -n "$use_texi2html"; then + # The legacy texi2html doesn't support TOP_NODE_UP_URL + htmlarg="--css-ref=/software/gnulib/manual.css" +fi + +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 + if [ ! -f index.html ]; then + ln -sf ${PACKAGE}.html index.html + fi + 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 'before-save-hook 'time-stamp) +# time-stamp-start: "scriptversion=" +# time-stamp-format: "%:y-%02m-%02d.%02H" +# time-stamp-end: "$" +# End: diff --git a/doc/gendocs_template b/doc/gendocs_template index b448d26a..36e60ff7 100755..100644 --- a/doc/gendocs_template +++ b/doc/gendocs_template @@ -1,23 +1,23 @@ <?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> -<!-- $Id: gendocs_template,v 1.5 2007/10/30 14:58:52 gray Exp $ --> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> +<!-- +Copyright (C) 2007-2021 Free Software Foundation, Inc. + +Copying and distribution of this file, with or without modification, +are permitted in any medium without royalty provided the copyright +notice and this notice are preserved. This file is offered as-is, +without any warranty. +--> + <head> -<title>%%TITLE%% - GNU Project - Free Software Foundation (FSF)</title> +<title>%%TITLE%% - GNU Project - Free Software Foundation</title> <meta http-equiv="content-type" content='text/html; charset=utf-8' /> <link rel="stylesheet" type="text/css" href="/gnu.css" /> -<link rev="made" href="mailto:gray@gnu.org" /> - <link rel="icon" type="image/png" href="/graphics/gnu-head-icon.png" /> </head> -<!-- This document is in XML, and xhtml 1.0 --> -<!-- Please make sure to properly nest your tags --> -<!-- and ensure that your final document validates --> -<!-- consistent with W3C xhtml 1.0 and CSS standards --> -<!-- See validator.w3.org --> - <body> <h3>%%TITLE%%</h3> @@ -27,99 +27,82 @@ <p> <a href="/graphics/gnu-head.jpg"> <img src="/graphics/gnu-head-sm.jpg" - alt=" [image of the head of a GNU] " - width="129" height="122" /> + alt=" [image of the head of a GNU] " width="129" height="122"/> </a> </p> <hr /> -<p>The manual for %%PACKAGE%% is available in the following formats:</p> +<p>This manual (%%PACKAGE%%) is available in the following formats:</p> <ul> - <li><a href="%%PACKAGE%%.html">HTML - (%%HTML_MONO_SIZE%%K bytes)</a> - entirely on one web page.</li> - <li><a href="html_node/index.html">HTML</a> - with one web page per - node.</li> +<li><a href="%%PACKAGE%%.html">HTML + (%%HTML_MONO_SIZE%%K bytes)</a> - entirely on one web page.</li> +<li><a href="html_node/index.html">HTML</a> - with one web page per + node.</li> %%IF HTML_SECTION%% - <li><a href="html_section/index.html">HTML</a> - with one web page per - section.</li> +<li><a href="html_section/index.html">HTML</a> - with one web page per + section.</li> %%ENDIF HTML_SECTION%% %%IF HTML_CHAPTER%% - <li><a href="html_chapter/index.html">HTML</a> - with one web page per - chapter.</li> +<li><a href="html_chapter/index.html">HTML</a> - with one web page per + chapter.</li> %%ENDIF HTML_CHAPTER%% - <li><a href="%%PACKAGE%%.html.gz">HTML compressed - (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on - one web page.</li> - <li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed - (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> - - with one web page per node.</li> +<li><a href="%%PACKAGE%%.html.gz">HTML compressed + (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on + one web page.</li> +<li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed + (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> - + with one web page per node.</li> %%IF HTML_SECTION%% - <li><a href="%%PACKAGE%%.html_section.tar.gz">HTML compressed - (%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> - - with one web page per section.</li> +<li><a href="%%PACKAGE%%.html_section.tar.gz">HTML compressed + (%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> - + with one web page per section.</li> %%ENDIF HTML_SECTION%% %%IF HTML_CHAPTER%% - <li><a href="%%PACKAGE%%.html_chapter.tar.gz">HTML compressed - (%%HTML_CHAPTER_TGZ_SIZE%%K gzipped tar file)</a> - - with one web page per chapter.</li> +<li><a href="%%PACKAGE%%.html_chapter.tar.gz">HTML compressed + (%%HTML_CHAPTER_TGZ_SIZE%%K gzipped tar file)</a> - + with one web page per chapter.</li> %%ENDIF HTML_CHAPTER%% - <li><a href="%%PACKAGE%%.info.tar.gz">Info document - (%%INFO_TGZ_SIZE%%K characters gzipped tar file)</a>.</li> - <li><a href="%%PACKAGE%%.txt">ASCII text - (%%ASCII_SIZE%%K characters)</a>.</li> - <li><a href="%%PACKAGE%%.txt.gz">ASCII text compressed - (%%ASCII_GZ_SIZE%%K gzipped characters)</a>.</li> - <li><a href="%%PACKAGE%%.dvi.gz">TeX dvi file - (%%DVI_GZ_SIZE%%K characters gzipped)</a>.</li> - <li><a href="%%PACKAGE%%.ps.gz">PostScript file - (%%PS_GZ_SIZE%%K characters gzipped)</a>.</li> - <li><a href="%%PACKAGE%%.pdf">PDF file - (%%PDF_SIZE%%K characters)</a>.</li> - <li><a href="%%PACKAGE%%.texi.tar.gz">Texinfo source - (%%TEXI_TGZ_SIZE%%K characters gzipped tar file)</a></li> +<li><a href="%%PACKAGE%%.info.tar.gz">Info document + (%%INFO_TGZ_SIZE%%K bytes gzipped tar file)</a>.</li> +<li><a href="%%PACKAGE%%.txt">ASCII text + (%%ASCII_SIZE%%K bytes)</a>.</li> +<li><a href="%%PACKAGE%%.txt.gz">ASCII text compressed + (%%ASCII_GZ_SIZE%%K bytes gzipped)</a>.</li> +<li><a href="%%PACKAGE%%.dvi.gz">TeX dvi file + (%%DVI_GZ_SIZE%%K bytes gzipped)</a>.</li> +<li><a href="%%PACKAGE%%.pdf">PDF file + (%%PDF_SIZE%%K bytes)</a>.</li> +<li><a href="%%PACKAGE%%.texi.tar.gz">Texinfo source + (%%TEXI_TGZ_SIZE%%K bytes gzipped tar file).</a></li> </ul> -<p>(This page generated by the <a -href="%%SCRIPTURL%%">%%SCRIPTNAME%%</a> script.) -</p> +<p>(This page generated by the <a href="%%SCRIPTURL%%">%%SCRIPTNAME%% +script</a>.)</p> -<p> -<a href="http://validator.w3.org/check?uri=referer"><img - src="http://www.w3.org/Icons/valid-xhtml10" - alt="Valid XHTML 1.0!" height="31" width="88" /></a> -</p> +<!-- If needed, change the copyright block at the bottom. In general, + all pages on the GNU web server should have the section about + verbatim copying. Please do NOT remove this without talking + with the webmasters first. + Please make sure the copyright date is consistent with the document + and that it is like this: "2001, 2002", not this: "2001-2002". --> +<div id="footer" class="copyright"> -<div class="copyright"> -<p> -Return to the <a href="/home.html">GNU Project home page</a>. -</p> +<p>Please send general FSF & GNU inquiries to +<a href="mailto:gnu@gnu.org"><gnu@gnu.org></a>. +There are also <a href="/contact/">other ways to contact</a> +the FSF. Broken links and other corrections or suggestions can be sent +to <a href="mailto:%%EMAIL%%"><%%EMAIL%%></a>.</p> +</div> -<p> -Please send FSF & GNU inquiries to -<a href="mailto:gnu@gnu.org"><em>gnu@gnu.org</em></a>. -There are also <a href="/home.html#ContactInfo">other ways to contact</a> -the FSF. -<br /> -Please send broken links and other corrections (or suggestions) to -<a href="mailto:webmasters@gnu.org"><em>webmasters@gnu.org</em></a>. -</p> +<p>Copyright © 2020 Free Software Foundation, Inc.</p> -<p> -Copyright 2004-2021 Free Software Foundation, Inc., -51 Franklin Street, Fifth Floor, Boston, MA 02111, USA -<br /> -Verbatim copying and distribution of this entire article is -permitted in any medium, provided this notice is preserved. -</p> +<p>This page is licensed under a <a rel="license" +href="https://creativecommons.org/licenses/by-nd/3.0/us/">Creative +Commons Attribution-NoDerivs 3.0 United States License</a>.</p> -<p> -Updated: -<!-- timestamp start --> -$Date: 2007/10/30 14:58:52 $ $Author: gray $ -<!-- timestamp end --> -</p> -</div> +<!--#include virtual="/server/bottom-notes.html" --> +</div> </body> </html> diff --git a/doc/intern.texi b/doc/intern.texi index 78b357c0..b7fc7207 100644 --- a/doc/intern.texi +++ b/doc/intern.texi @@ -13,7 +13,7 @@ @node Standard @unnumberedsec Basic Tar Format -@UNREVISED +@UNREVISED{} While an archive may contain many files, the archive itself is a single ordinary file. Like any other file, an archive file can be @@ -266,7 +266,7 @@ IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940 @node Extensions @unnumberedsec @acronym{GNU} Extensions to the Archive Format -@UNREVISED +@UNREVISED{} The @acronym{GNU} format uses additional file types to describe new types of files in an archive. These are listed below. diff --git a/doc/tar.texi b/doc/tar.texi index fba10ae6..389a3448 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -1803,7 +1803,7 @@ will extract the file @file{folk} into the current working directory. @node going further @section Going Further Ahead in this Manual -@UNREVISED +@UNREVISED{} @FIXME{need to write up a node here about the things that are going to be in the rest of the manual.} @@ -2940,7 +2940,7 @@ the pattern specified in @var{name}. @xref{Tape Files}. @opsummary{level} @item --level=@var{n} -Force incremental backup of level @var{n}. As of @GNUTAR version +Force incremental backup of level @var{n}. As of @GNUTAR{} version @value{VERSION}, the option @option{--level=0} truncates the snapshot file, thereby forcing the level 0 dump. Other values of @var{n} are effectively ignored. @xref{--level=0}, for details and examples. @@ -5632,7 +5632,7 @@ controlled by the following command line arguments: @table @option @item --xattrs Enable extended attributes support. When used with @option{--create}, -this option instructs @GNUTAR to store extended file attribute in the +this option instructs @GNUTAR{} to store extended file attribute in the created archive. This implies POSIX.1-2001 archive format (@option{--format=pax}). @@ -5870,7 +5870,7 @@ encountered while reading an archive. Use in conjunction with @node Writing @subsection Changing How @command{tar} Writes Files -@UNREVISED +@UNREVISED{} @FIXME{Introductory paragraph} @@ -6383,7 +6383,7 @@ Remove files after adding them to the archive. @node Scarce @subsection Coping with Scarce Resources -@UNREVISED +@UNREVISED{} @cindex Small memory @cindex Running out of space @@ -6630,7 +6630,7 @@ called @dfn{dumps}. @node Full Dumps @section Using @command{tar} to Perform Full Dumps -@UNREVISED +@UNREVISED{} @cindex full dumps @cindex dumps, full @@ -7867,7 +7867,7 @@ $ @kbd{find . -size +800 -print0 | This example uses short options for typographic reasons, to avoid very long lines. -@GNUTAR is tries to automatically detect @code{NUL}-terminated file +@GNUTAR{} is tries to automatically detect @code{NUL}-terminated file lists, so in many cases it is safe to use them even without the @option{--null} option. In this case @command{tar} will print a warning and continue reading such a file as if @option{--null} were @@ -10645,7 +10645,7 @@ a @command{tar} able to read the good archives they receive. @cindex large values @cindex future time stamps @cindex negative time stamps -@UNREVISED +@UNREVISED{} The above sections suggest to use @samp{oldest possible} archive format if in doubt. However, sometimes it is not possible. If you @@ -11028,7 +11028,7 @@ Done @node cpio @section Comparison of @command{tar} and @command{cpio} -@UNREVISED +@UNREVISED{} @FIXME{Reorganize the following material} @@ -11140,7 +11140,7 @@ easily test, because the resulting archive gets smaller, and @node Media @chapter Tapes and Other Archive Media -@UNREVISED +@UNREVISED{} A few special cases about tape handling warrant more detailed description. These special cases are discussed below. @@ -11184,7 +11184,7 @@ not a good idea. @node Device @section Device Selection and Switching -@UNREVISED +@UNREVISED{} @table @option @item -f [@var{hostname}:]@var{file} @@ -11552,7 +11552,7 @@ device. @cindex Format Options @cindex Options, archive format specifying @cindex Options, format specifying -@UNREVISED +@UNREVISED{} Format parameters specify how an archive is written on the archive media. The best choice of format parameters will vary depending on @@ -11576,7 +11576,7 @@ examples of format parameter considerations. @cindex Number of bytes per record @cindex Bytes per record @cindex Blocks per record -@UNREVISED +@UNREVISED{} @opindex blocking-factor The data in an archive is grouped into blocks, which are 512 bytes. @@ -11929,7 +11929,7 @@ you should do the proper things for that as well. @xref{Blocking}. @node Tape Positioning @subsection Tape Positions and Tape Marks -@UNREVISED +@UNREVISED{} Just as archives can store more than one file from the file system, tapes can store more than one archive file. To keep track of where @@ -11970,7 +11970,7 @@ rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**---------------- @node mt @subsection The @command{mt} Utility -@UNREVISED +@UNREVISED{} @FIXME{Is it true that this only works on non-block devices? should explain the difference, (fixed or variable).} @@ -12355,7 +12355,7 @@ implementation, read @ref{Split Recovery}. @subsection Tape Files @cindex labeling archives @opindex label -@UNREVISED +@UNREVISED{} To give the archive a name which will be recorded in it, use the @option{--label=@var{volume-label}} (@option{-V @var{volume-label}}) |