I've updated the docs on the web and added the tool I used to do it in the findutils source tree. The patch (which I already pushed) is attached. Improvements welcome!
From 755a22b9820d554d1dd8b82fd3c3ad1d3d688c81 Mon Sep 17 00:00:00 2001 From: James Youngman <[email protected]> Date: Sun, 5 May 2019 16:49:12 +0100 Subject: [PATCH] doc: add a tool for updating the online manual. To: [email protected]
* build-aux/update-online-manual.sh: add a script (originally written in 2005 but not previously included in the source distribution) which automates the updating of the online manual. * doc/Makefile.am: Add some targets useful for update-online-manual.sh. * doc/find-maint.texi (Documentation): Explain how to check out the web pages and how to update the findutils documentation there. --- build-aux/update-online-manual.sh | 243 ++++++++++++++++++++++++++++++++++++++ doc/Makefile.am | 25 +++- doc/find-maint.texi | 13 ++ 3 files changed, 279 insertions(+), 2 deletions(-) create mode 100755 build-aux/update-online-manual.sh diff --git a/build-aux/update-online-manual.sh b/build-aux/update-online-manual.sh new file mode 100755 index 00000000..bfce0465 --- /dev/null +++ b/build-aux/update-online-manual.sh @@ -0,0 +1,243 @@ +#! /bin/sh +# Copyright (C) 2019 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/>. + +## +## This script updates the online manual for findutils. +## +## When you run it, make sure you are in the "manual" directory. +PACKAGE=findutils +TITLE="Findutils" +TEXIBASE=find + +set -e + +usage() { +cat <<EOF +usage: $0 location-of-${PACKAGE}-build-directory +EOF +} + +checkfiles="CVS dvi ${TEXIBASE}.html html_node html_mono info ps texi text" +targets="dvi html info ${TEXIBASE}.ps ${TEXIBASE}.txt ${PACKAGE}.texi_html_node.tar.gz ${TEXIBASE}_mono.html ${TEXIBASE}.texi.tar.gz ${TEXIBASE}-info.tar.gz" + +if [ $# -ne 1 ]; then + usage >&2 + exit 1 +fi + +BUILDDIR="$1" +DOC_OUTPUT_DIR="`pwd`" + +echo Current directory is `pwd` + +echo "Are we in the right place? " +for f in $checkfiles +do + if test -e "$f"; then + echo " $f seems to be there" + else + printf " No, %s is missing.\n" "$f" >&2 + exit 1 + fi +done +echo "Yes, we are in the right place" + + +printf "Can we see the build directory? " +if [ -d "$BUILDDIR" ]; then + echo Yes. +else + echo "No." >&2 ; exit 1 +fi + +printf "Does the build directory have a 'doc' subdirectory? " +if [ -d "$BUILDDIR/doc" ]; then + echo Yes. +else + echo "No." >&2 ; exit 1 +fi +BUILDDIR="$BUILDDIR"/doc + +printf "Does the (doc) build directory have a Makefile? " +if [ -f "$BUILDDIR"/Makefile ]; then + echo Yes. +else + echo "No." >&2 ; exit 1 +fi + + +## +## Figure out where the source code lives by asking Make. +## +REL_SRCDIR="$(cd $BUILDDIR && grep '^srcdir =' Makefile | cut -d= -f2)" +echo Build directory is $BUILDDIR. +echo Relative path to source directory is $REL_SRCDIR + +SRCDIR="$(cd $BUILDDIR && cd $REL_SRCDIR && /bin/pwd)" +unset REL_SRCDIR +echo Source directory is $SRCDIR. + + +if true +then + ## + ## Build (most of) the files we need. + ## We collect them from the build directory afterwards. + ## + make -C "$BUILDDIR" $targets + cp ${BUILDDIR}/${TEXIBASE}.texi.tar.gz texi/${TEXIBASE}.texi.tar.gz + cp ${BUILDDIR}/${TEXIBASE}-info.tar.gz info/${TEXIBASE}-info.tar.gz + + echo Collecting the PostScript file... + rm -f ps/${TEXIBASE}.ps.gz + gzip -9 < ${BUILDDIR}/${TEXIBASE}.ps > ps/${TEXIBASE}.ps.gz + + echo Collecting the DVI file... + cp $BUILDDIR/${TEXIBASE}.dvi dvi/ + rm dvi/${TEXIBASE}.dvi.gz + gzip -9 dvi/${TEXIBASE}.dvi + + + echo "Collecting the text files (compressed and uncompressed)..." + rm -f text/${TEXIBASE}.txt text/${TEXIBASE}.txt.gz + cp $BUILDDIR/${TEXIBASE}.txt text/ + gzip -9 text/${TEXIBASE}.txt + cp $BUILDDIR/${TEXIBASE}.txt text/ + + echo "Collecting the all-in-one-file HTML (compressed and uncompressed)..." + rm -f html_mono/${TEXIBASE}.html html_mono/${TEXIBASE}.html.gz + cp $BUILDDIR/${TEXIBASE}_mono.html html_mono/${TEXIBASE}.html + gzip -9 html_mono/${TEXIBASE}.html + cp $BUILDDIR/${TEXIBASE}_mono.html html_mono/${TEXIBASE}.html + + + echo "Collecting the file-per-node HTML tar file..." + rm -f html_node/${PACKAGE}.texi_html_node.tar.gz + find html_node/${TEXIBASE}_html -name '*.html' -type f -delete + cp $BUILDDIR/${PACKAGE}.texi_html_node.tar.gz html_node/ + + echo "Unpacking the node-per-node HTML tar file..." + ( cd html_node && tar zxf ${PACKAGE}.texi_html_node.tar.gz && mv ${TEXIBASE}.html/*.html ${TEXIBASE}_html ) + +fi + +size () { + du -sh --apparent-size "$1" | awk '{print $1;}' +} + + +linkfor() { + what="$1" + type="$2" + shift 2 + printf '<A HREF="%s">%s (%s %s)</A>' \ + "$what" "$*" "$(size $what)" "$type" +} + +## +## +## Now the rather complex bit; generate the index page! +## +## +echo "Generating the index page..." +cat >${TEXIBASE}.html <<EOF +<!--#include virtual="/server/header.html" --> +<TITLE>Finding Files: Table of Contents - GNU Project - Free Software Foundation (FSF)</TITLE> +<LINK REV="made" HREF="mailto:[email protected]"> +<META NAME="keywords" CONTENT="GNU, findutils, xargs, find, locate, finding files, file search, disk search, file name database, expand arguments, free software"> +<meta http-equiv="Description" content="Tools for searching file systems" /> +<BASE HREF="http://www.gnu.org/software/findutils/manual/find.html";> +<!--#include virtual="/server/banner.html" --> +<H2>Findutils: Table of Contents</H2> +<P> +This manual is available in the following formats: + +<P> +<UL> + <LI> + $(linkfor html_mono/${TEXIBASE}.html "characters" HTML) + entirely on one web page. + <P> + <LI> + $(linkfor html_mono/${TEXIBASE}.html.gz "gzipped characters" HTML) + entirely on one web page. + <P> + <LI> <a href="html_node/${TEXIBASE}_html/index.html">HTML (total size $(size html_node/${TEXIBASE}_html))</a> + with one web page per node. + <p> + <LI> $(linkfor "html_node/${PACKAGE}.texi_html_node.tar.gz" "gzipped tar file" HTML) + with one web page per node. + <p> + <LI> + $(linkfor "info/${TEXIBASE}-info.tar.gz" "gzipped tar file" "Info document") + <P> + <LI> + $(linkfor "text/${TEXIBASE}.txt" "characters" "ASCII text") + <P> + <LI> + $(linkfor "text/${TEXIBASE}.txt.gz" "gzipped characters" "ASCII text") + <P> + <LI> + $(linkfor "dvi/${TEXIBASE}.dvi.gz" "gzipped" "a TeX dvi file") + <P> + <li> + $(linkfor "ps/${TEXIBASE}.ps.gz" "gzipped characters" "a PostScript file") + <p> + <LI>the original + $(linkfor "texi/${TEXIBASE}.texi.tar.gz" "character gzipped tar file" "Texinfo source") + <P> +</UL> + +</div><!-- for id="content", starts in the include above --> +<!--#include virtual="/server/footer.html" --> +<div id="footer"> + +<P> +Return to <A HREF="/home.html">GNU's home page</A>. + +<P> +Please send FSF & GNU inquiries & questions to +<A HREF="mailto:[email protected]"><EM>[email protected]</EM></A>. +Other <A HREF="http://www.fsf.org/about/contact.html";>ways to contact</A> the FSF. + +<P> +Please send comments on these web pages to +<A HREF="mailto:[email protected]"><EM>[email protected]</EM></A>, +send other questions to +<A HREF="mailto:[email protected]"><EM>[email protected]</EM></A>. + +<P> +Copyright © 1997, 1998, 2003, 2005, 2006, 2008 Free Software Foundation, Inc., +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA + +<P> +Verbatim copying and distribution of this entire article is +permitted in any medium, provided this notice is preserved. + +<!-- This document was updated $(LC_TIME=C date +"%B %d, %Y") by $0 "$@" --> +<P> +Updated: +\$Date: 2019/05/05 15:13:38 $ \$Author: james $ + +<P> +<HR> + +</BODY> +</HTML> + +EOF + +echo "All done." diff --git a/doc/Makefile.am b/doc/Makefile.am index 2ec77274..661d8551 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -20,8 +20,10 @@ BUILT_SOURCES = dblocation.texi nodist_find_TEXINFOS = dblocation.texi find_maint_TEXINFOS = fdl.texi MOSTLYCLEANFILES = find.cps -CLEANFILES = find.txt find_mono.html findutils.texi_html_node.tar.gz dblocation.texi - +CLEANFILES = find.txt find_mono.html findutils.texi_html_node.tar.gz dblocation.texi \ + find_mono.html findutils.texi_html_node.tar.gz \ + find-info.tar.gz find.texi find.texi.tar.gz \ + find.txt tmp-doc-install find_mono.html.gz MAKEINFOTXT = $(MAKEINFO) --plaintext find.txt: find.texi $(srcdir)/version.texi $(find_TEXINFOS) @@ -73,3 +75,22 @@ findutils.texi_html_node.tar.gz: find.html dblocation.texi: ../locate/dblocation.texi $(LN_S) ../locate/dblocation.texi $@ + +find-info.tar.gz: + $(MKDIR_P) tmp-doc-install/info + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="tmp-doc-install" distdir="tmp-doc-install/info" \ + dist-info + ( cd tmp-doc-install && tar -c -f - info ) | GZIP=$(GZIP_ENV) gzip -c >| $@ + rm -rf tmp-doc-install/info + rmdir tmp-doc-install + +find.texi.tar.gz: $(TEXINFOS) $(find_TEXINFOS) $(nodist_find_TEXINFOS) $(info_TEXINFOS) $(find_maint_TEXINFOS) $(srcdir)/version.texi $(srcdir)/versionmaint.texi Makefile + $(MKDIR_P) tmp-doc-install/texi + for f in $(TEXINFOS) $(find_TEXINFOS) $(info_TEXINFOS) $(find_maint_TEXINFOS) version.texi versionmaint.texi ; \ + do cp $(srcdir)/"$$f" tmp-doc-install/texi/ || break; done && cp dblocation.texi tmp-doc-install/texi/ + ( cd tmp-doc-install/texi/ && tar -c -f - *.texi ) | GZIP=$(GZIP_ENV) gzip -c >| $@ + rm -rf tmp-doc-install/texi + rmdir tmp-doc-install + + diff --git a/doc/find-maint.texi b/doc/find-maint.texi index eb9209a0..20eea5af 100644 --- a/doc/find-maint.texi +++ b/doc/find-maint.texi @@ -609,6 +609,19 @@ Texinfo documentation. The manual pages are suitable for reference use, but the Texinfo manual should also include introductory and tutorial material. +We make the user documentation available on the web, on the GNU +project web site. These web pages are source-controlled via CVS +(still!). If you are a member of the @samp{findutils} project on +Savannah you should be able to check the web pages out like this +(@samp{$USER} is a placeholder for your Savannah username): + +@smallexample +cvs -d :ext:$USER@@cvs.savannah.gnu.org:/web/findutils checkout findutils/manual +@end smallexample + +You can automatically update the documentation in this repository +using the script @samp{build-aux/update-online-manual.sh} in the +findutils Git repository. @section Build Guidance -- 2.11.0
