lib/gendocs.sh

   1 #!/bin/sh -e
   2 # gendocs.sh -- generate a GNU manual in many formats.  This script is
   3 #   mentioned in maintain.texi.  See the help message below for usage details.
   4
   5 scriptversion=2017-09-12.23
   6
   7 # Copyright 2003-2017 Free Software Foundation, Inc.
   8 #
   9 # This program is free software: you can redistribute it and/or modify
  10 # it under the terms of the GNU General Public License as published by
  11 # the Free Software Foundation; either version 3 of the License, or
  12 # (at your option) any later version.
  13 #
  14 # This program is distributed in the hope that it will be useful,
  15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 # GNU General Public License for more details.
  18 #
  19 # You should have received a copy of the GNU General Public License
  20 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  21 #
  22 # Original author: Mohit Agarwal.
  23 # Send bug reports and any other correspondence to bug-gnulib@gnu.org.
  24 #
  25 # The latest version of this script, and the companion template, is
  26 # available from the Gnulib repository:
  27 #
  28 # https://git.savannah.gnu.org/cgit/gnulib.git/tree/build-aux/gendocs.sh
  29 # https://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/gendocs_template
  30
  31 # TODO:
  32 # - image importing was only implemented for HTML generated by
  33 #   makeinfo.  But it should be simple enough to adjust.
  34 # - images are not imported in the source tarball.  All the needed
  35 #   formats (PDF, PNG, etc.) should be included.
  36
  37 prog=`basename "$0"`
  38 srcdir=`pwd`
  39
  40 scripturl="https://git.savannah.gnu.org/cgit/gnulib.git/plain/build-aux/gendocs.sh"
  41 templateurl="https://git.savannah.gnu.org/cgit/gnulib.git/plain/doc/gendocs_template"
  42
  43 : ${SETLANG="env LANG= LC_MESSAGES= LC_ALL= LANGUAGE="}
  44 : ${MAKEINFO="makeinfo"}
  45 : ${TEXI2DVI="texi2dvi"}
  46 : ${DOCBOOK2HTML="docbook2html"}
  47 : ${DOCBOOK2PDF="docbook2pdf"}
  48 : ${DOCBOOK2TXT="docbook2txt"}
  49 : ${GENDOCS_TEMPLATE_DIR="."}
  50 : ${PERL='perl'}
  51 : ${TEXI2HTML="texi2html"}
  52 unset CDPATH
  53 unset use_texi2html
  54
  55 MANUAL_TITLE=
  56 PACKAGE=
  57 EMAIL=webmasters@gnu.org  # please override with --email
  58 commonarg= # passed to all makeinfo/texi2html invcations.
  59 dirargs=   # passed to all tools (-I dir).
  60 dirs=      # -I directories.
  61 htmlarg="--css-ref=/software/gnulib/manual.css -c TOP_NODE_UP_URL=/manual"
  62 infoarg=--no-split
  63 generate_ascii=true
  64 generate_html=true
  65 generate_info=true
  66 generate_tex=true
  67 outdir=manual
  68 source_extra=
  69 split=node
  70 srcfile=
  71 texarg="-t @finalout"
  72
  73 version="gendocs.sh $scriptversion
  74
  75 Copyright 2017 Free Software Foundation, Inc.
  76 There is NO warranty.  You may redistribute this software
  77 under the terms of the GNU General Public License.
  78 For more information about these matters, see the files named COPYING."
  79
  80 usage="Usage: $prog [OPTION]... PACKAGE MANUAL-TITLE
  81
  82 Generate output in various formats from PACKAGE.texinfo (or .texi or
  83 .txi) source.  See the GNU Maintainers document for a more extensive
  84 discussion:
  85   https://www.gnu.org/prep/maintain_toc.html
  86
  87 Options:
  88   --email ADR use ADR as contact in generated web pages; always give this.
  89
  90   -s SRCFILE   read Texinfo from SRCFILE, instead of PACKAGE.{texinfo|texi|txi}
  91   -o OUTDIR    write files into OUTDIR, instead of manual/.
  92   -I DIR       append DIR to the Texinfo search path.
  93   --common ARG pass ARG in all invocations.
  94   --html ARG   pass ARG to makeinfo or texi2html for HTML targets,
  95                  instead of '$htmlarg'.
  96   --info ARG   pass ARG to makeinfo for Info, instead of --no-split.
  97   --no-ascii   skip generating the plain text output.
  98   --no-html    skip generating the html output.
  99   --no-info    skip generating the info output.
 100   --no-tex     skip generating the dvi and pdf output.
 101   --source ARG include ARG in tar archive of sources.
 102   --split HOW  make split HTML by node, section, chapter; default node.
 103   --tex ARG    pass ARG to texi2dvi for DVI and PDF, instead of -t @finalout.
 104
 105   --texi2html  use texi2html to make HTML target, with all split versions.
 106   --docbook    convert through DocBook too (xml, txt, html, pdf).
 107
 108   --help       display this help and exit successfully.
 109   --version    display version information and exit successfully.
 110
 111 Simple example: $prog --email bug-gnu-emacs@gnu.org emacs \"GNU Emacs Manual\"
 112
 113 Typical sequence:
 114   cd PACKAGESOURCE/doc
 115   wget \"$scripturl\"
 116   wget \"$templateurl\"
 117   $prog --email BUGLIST MANUAL \"GNU MANUAL - One-line description\"
 118
 119 Output will be in a new subdirectory \"manual\" (by default;
 120 use -o OUTDIR to override).  Move all the new files into your web CVS
 121 tree, as explained in the Web Pages node of maintain.texi.
 122
 123 Please use the --email ADDRESS option so your own bug-reporting
 124 address will be used in the generated HTML pages.
 125
 126 MANUAL-TITLE is included as part of the HTML <title> of the overall
 127 manual/index.html file.  It should include the name of the package being
 128 documented.  manual/index.html is created by substitution from the file
 129 $GENDOCS_TEMPLATE_DIR/gendocs_template.  (Feel free to modify the
 130 generic template for your own purposes.)
 131
 132 If you have several manuals, you'll need to run this script several
 133 times with different MANUAL values, specifying a different output
 134 directory with -o each time.  Then write (by hand) an overall index.html
 135 with links to them all.
 136
 137 If a manual's Texinfo sources are spread across several directories,
 138 first copy or symlink all Texinfo sources into a single directory.
 139 (Part of the script's work is to make a tar.gz of the sources.)
 140
 141 As implied above, by default monolithic Info files are generated.
 142 If you want split Info, or other Info options, use --info to override.
 143
 144 You can set the environment variables MAKEINFO, TEXI2DVI, TEXI2HTML,
 145 and PERL to control the programs that get executed, and
 146 GENDOCS_TEMPLATE_DIR to control where the gendocs_template file is
 147 looked for.  With --docbook, the environment variables DOCBOOK2HTML,
 148 DOCBOOK2PDF, and DOCBOOK2TXT are also consulted.
 149
 150 By default, makeinfo and texi2dvi are run in the default (English)
 151 locale, since that's the language of most Texinfo manuals.  If you
 152 happen to have a non-English manual and non-English web site, see the
 153 SETLANG setting in the source.
 154
 155 Email bug reports or enhancement requests to bug-gnulib@gnu.org.
 156 "
 157
 158 while test $# -gt 0; do
 159   case $1 in
 160     -s)          shift; srcfile=$1;;
 161     -o)          shift; outdir=$1;;
 162     -I)          shift; dirargs="$dirargs -I '$1'"; dirs="$dirs $1";;
 163     --common)    shift; commonarg=$1;;
 164     --docbook)   docbook=yes;;
 165     --email)     shift; EMAIL=$1;;
 166     --html)      shift; htmlarg=$1;;
 167     --info)      shift; infoarg=$1;;
 168     --no-ascii)  generate_ascii=false;;
 169     --no-html)   generate_ascii=false;;
 170     --no-info)   generate_info=false;;
 171     --no-tex)    generate_tex=false;;
 172     --source)    shift; source_extra=$1;;
 173     --split)     shift; split=$1;;
 174     --tex)       shift; texarg=$1;;
 175     --texi2html) use_texi2html=1;;
 176
 177     --help)      echo "$usage"; exit 0;;
 178     --version)   echo "$version"; exit 0;;
 179     -*)
 180       echo "$0: Unknown option \`$1'." >&2
 181       echo "$0: Try \`--help' for more information." >&2
 182       exit 1;;
 183     *)
 184       if test -z "$PACKAGE"; then
 185         PACKAGE=$1
 186       elif test -z "$MANUAL_TITLE"; then
 187         MANUAL_TITLE=$1
 188       else
 189         echo "$0: extra non-option argument \`$1'." >&2
 190         exit 1
 191       fi;;
 192   esac
 193   shift
 194 done
 195
 196 # makeinfo uses the dirargs, but texi2dvi doesn't.
 197 commonarg=" $dirargs $commonarg"
 198
 199 # For most of the following, the base name is just $PACKAGE
 200 base=$PACKAGE
 201
 202 if test -n "$srcfile"; then
 203   # but here, we use the basename of $srcfile
 204   base=`basename "$srcfile"`
 205   case $base in
 206     *.txi|*.texi|*.texinfo) base=`echo "$base"|sed 's/\.[texinfo]*$//'`;;
 207   esac
 208   PACKAGE=$base
 209 elif test -s "$srcdir/$PACKAGE.texinfo"; then
 210   srcfile=$srcdir/$PACKAGE.texinfo
 211 elif test -s "$srcdir/$PACKAGE.texi"; then
 212   srcfile=$srcdir/$PACKAGE.texi
 213 elif test -s "$srcdir/$PACKAGE.txi"; then
 214   srcfile=$srcdir/$PACKAGE.txi
 215 else
 216   echo "$0: cannot find .texinfo or .texi or .txi for $PACKAGE in $srcdir." >&2
 217   exit 1
 218 fi
 219
 220 if test ! -r $GENDOCS_TEMPLATE_DIR/gendocs_template; then
 221   echo "$0: cannot read $GENDOCS_TEMPLATE_DIR/gendocs_template." >&2
 222   echo "$0: it is available from $templateurl." >&2
 223   exit 1
 224 fi
 225
 226 # Function to return size of $1 in something resembling kilobytes.
 227 calcsize()
 228 {
 229   size=`ls -ksl $1 | awk '{print $1}'`
 230   echo $size
 231 }
 232
 233 # copy_images OUTDIR HTML-FILE...
 234 # -------------------------------
 235 # Copy all the images needed by the HTML-FILEs into OUTDIR.
 236 # Look for them in . and the -I directories; this is simpler than what
 237 # makeinfo supports with -I, but hopefully it will suffice.
 238 copy_images()
 239 {
 240   local odir
 241   odir=$1
 242   shift
 243   $PERL -n -e "
 244 BEGIN {
 245   \$me = '$prog';
 246   \$odir = '$odir';
 247   @dirs = qw(. $dirs);
 248 }
 249 " -e '
 250 /<img src="(.*?)"/g && ++$need{$1};
 251
 252 END {
 253   #print "$me: @{[keys %need]}\n";  # for debugging, show images found.
 254   FILE: for my $f (keys %need) {
 255     for my $d (@dirs) {
 256       if (-f "$d/$f") {
 257         use File::Basename;
 258         my $dest = dirname ("$odir/$f");
 259         #
 260         use File::Path;
 261         -d $dest || mkpath ($dest)
 262           || die "$me: cannot mkdir $dest: $!\n";
 263         #
 264         use File::Copy;
 265         copy ("$d/$f", $dest)
 266           || die "$me: cannot copy $d/$f to $dest: $!\n";
 267         next FILE;
 268       }
 269     }
 270     die "$me: $ARGV: cannot find image $f\n";
 271   }
 272 }
 273 ' -- "$@" || exit 1
 274 }
 275
 276 case $outdir in
 277   /*) abs_outdir=$outdir;;
 278   *)  abs_outdir=$srcdir/$outdir;;
 279 esac
 280
 281 echo "Making output for $srcfile"
 282 echo " in `pwd`"
 283 mkdir -p "$outdir/"
 284
 285 # \f
 286 if $generate_info; then
 287   cmd="$SETLANG $MAKEINFO -o $PACKAGE.info $commonarg $infoarg \"$srcfile\""
 288   echo "Generating info... ($cmd)"
 289   rm -f $PACKAGE.info* # get rid of any strays
 290   eval "$cmd"
 291   tar czf "$outdir/$PACKAGE.info.tar.gz" $PACKAGE.info*
 292   ls -l "$outdir/$PACKAGE.info.tar.gz"
 293   info_tgz_size=`calcsize "$outdir/$PACKAGE.info.tar.gz"`
 294   # do not mv the info files, there's no point in having them available
 295   # separately on the web.
 296 fi  # end info
 297
 298 # \f
 299 if $generate_tex; then
 300   cmd="$SETLANG $TEXI2DVI $dirargs $texarg \"$srcfile\""
 301   printf "\nGenerating dvi... ($cmd)\n"
 302   eval "$cmd"
 303   # compress/finish dvi:
 304   gzip -f -9 $PACKAGE.dvi
 305   dvi_gz_size=`calcsize $PACKAGE.dvi.gz`
 306   mv $PACKAGE.dvi.gz "$outdir/"
 307   ls -l "$outdir/$PACKAGE.dvi.gz"
 308
 309   cmd="$SETLANG $TEXI2DVI --pdf $dirargs $texarg \"$srcfile\""
 310   printf "\nGenerating pdf... ($cmd)\n"
 311   eval "$cmd"
 312   pdf_size=`calcsize $PACKAGE.pdf`
 313   mv $PACKAGE.pdf "$outdir/"
 314   ls -l "$outdir/$PACKAGE.pdf"
 315 fi # end tex (dvi + pdf)
 316
 317 # \f
 318 if $generate_ascii; then
 319   opt="-o $PACKAGE.txt --no-split --no-headers $commonarg"
 320   cmd="$SETLANG $MAKEINFO $opt \"$srcfile\""
 321   printf "\nGenerating ascii... ($cmd)\n"
 322   eval "$cmd"
 323   ascii_size=`calcsize $PACKAGE.txt`
 324   gzip -f -9 -c $PACKAGE.txt >"$outdir/$PACKAGE.txt.gz"
 325   ascii_gz_size=`calcsize "$outdir/$PACKAGE.txt.gz"`
 326   mv $PACKAGE.txt "$outdir/"
 327   ls -l "$outdir/$PACKAGE.txt" "$outdir/$PACKAGE.txt.gz"
 328 fi
 329
 330 # \f
 331
 332 if $generate_html; then
 333 # Split HTML at level $1.  Used for texi2html.
 334 html_split()
 335 {
 336   opt="--split=$1 --node-files $commonarg $htmlarg"
 337   cmd="$SETLANG $TEXI2HTML --output $PACKAGE.html $opt \"$srcfile\""
 338   printf "\nGenerating html by $1... ($cmd)\n"
 339   eval "$cmd"
 340   split_html_dir=$PACKAGE.html
 341   (
 342     cd ${split_html_dir} || exit 1
 343     ln -sf ${PACKAGE}.html index.html
 344     tar -czf "$abs_outdir/${PACKAGE}.html_$1.tar.gz" -- *.html
 345   )
 346   eval html_$1_tgz_size=`calcsize "$outdir/${PACKAGE}.html_$1.tar.gz"`
 347   rm -f "$outdir"/html_$1/*.html
 348   mkdir -p "$outdir/html_$1/"
 349   mv ${split_html_dir}/*.html "$outdir/html_$1/"
 350   rmdir ${split_html_dir}
 351 }
 352
 353 if test -z "$use_texi2html"; then
 354   opt="--no-split --html -o $PACKAGE.html $commonarg $htmlarg"
 355   cmd="$SETLANG $MAKEINFO $opt \"$srcfile\""
 356   printf "\nGenerating monolithic html... ($cmd)\n"
 357   rm -rf $PACKAGE.html  # in case a directory is left over
 358   eval "$cmd"
 359   html_mono_size=`calcsize $PACKAGE.html`
 360   gzip -f -9 -c $PACKAGE.html >"$outdir/$PACKAGE.html.gz"
 361   html_mono_gz_size=`calcsize "$outdir/$PACKAGE.html.gz"`
 362   copy_images "$outdir/" $PACKAGE.html
 363   mv $PACKAGE.html "$outdir/"
 364   ls -l "$outdir/$PACKAGE.html" "$outdir/$PACKAGE.html.gz"
 365
 366   # Before Texinfo 5.0, makeinfo did not accept a --split=HOW option,
 367   # it just always split by node.  So if we're splitting by node anyway,
 368   # leave it out.
 369   if test "x$split" = xnode; then
 370     split_arg=
 371   else
 372     split_arg=--split=$split
 373   fi
 374   #
 375   opt="--html -o $PACKAGE.html $split_arg $commonarg $htmlarg"
 376   cmd="$SETLANG $MAKEINFO $opt \"$srcfile\""
 377   printf "\nGenerating html by $split... ($cmd)\n"
 378   eval "$cmd"
 379   split_html_dir=$PACKAGE.html
 380   copy_images $split_html_dir/ $split_html_dir/*.html
 381   (
 382     cd $split_html_dir || exit 1
 383     tar -czf "$abs_outdir/$PACKAGE.html_$split.tar.gz" -- *
 384   )
 385   eval \
 386     html_${split}_tgz_size=`calcsize "$outdir/$PACKAGE.html_$split.tar.gz"`
 387   rm -rf "$outdir/html_$split/"
 388   mv $split_html_dir "$outdir/html_$split/"
 389   du -s "$outdir/html_$split/"
 390   ls -l "$outdir/$PACKAGE.html_$split.tar.gz"
 391
 392 else # use texi2html:
 393   opt="--output $PACKAGE.html $commonarg $htmlarg"
 394   cmd="$SETLANG $TEXI2HTML $opt \"$srcfile\""
 395   printf "\nGenerating monolithic html with texi2html... ($cmd)\n"
 396   rm -rf $PACKAGE.html  # in case a directory is left over
 397   eval "$cmd"
 398   html_mono_size=`calcsize $PACKAGE.html`
 399   gzip -f -9 -c $PACKAGE.html >"$outdir/$PACKAGE.html.gz"
 400   html_mono_gz_size=`calcsize "$outdir/$PACKAGE.html.gz"`
 401   mv $PACKAGE.html "$outdir/"
 402
 403   html_split node
 404   html_split chapter
 405   html_split section
 406 fi
 407 fi # end html
 408
 409 # \f
 410 printf "\nMaking .tar.gz for sources...\n"
 411 d=`dirname $srcfile`
 412 (
 413   cd "$d"
 414   srcfiles=`ls -d *.texinfo *.texi *.txi *.eps $source_extra 2>/dev/null` || true
 415   tar czfh "$abs_outdir/$PACKAGE.texi.tar.gz" $srcfiles
 416   ls -l "$abs_outdir/$PACKAGE.texi.tar.gz"
 417 )
 418 texi_tgz_size=`calcsize "$outdir/$PACKAGE.texi.tar.gz"`
 419
 420 # \f
 421 # Do everything again through docbook.
 422 if test -n "$docbook"; then
 423   opt="-o - --docbook $commonarg"
 424   cmd="$SETLANG $MAKEINFO $opt \"$srcfile\" >${srcdir}/$PACKAGE-db.xml"
 425   printf "\nGenerating docbook XML... ($cmd)\n"
 426   eval "$cmd"
 427   docbook_xml_size=`calcsize $PACKAGE-db.xml`
 428   gzip -f -9 -c $PACKAGE-db.xml >"$outdir/$PACKAGE-db.xml.gz"
 429   docbook_xml_gz_size=`calcsize "$outdir/$PACKAGE-db.xml.gz"`
 430   mv $PACKAGE-db.xml "$outdir/"
 431
 432   split_html_db_dir=html_node_db
 433   opt="$commonarg -o $split_html_db_dir"
 434   cmd="$DOCBOOK2HTML $opt \"${outdir}/$PACKAGE-db.xml\""
 435   printf "\nGenerating docbook HTML... ($cmd)\n"
 436   eval "$cmd"
 437   (
 438     cd ${split_html_db_dir} || exit 1
 439     tar -czf "$abs_outdir/${PACKAGE}.html_node_db.tar.gz" -- *.html
 440   )
 441   html_node_db_tgz_size=`calcsize "$outdir/${PACKAGE}.html_node_db.tar.gz"`
 442   rm -f "$outdir"/html_node_db/*.html
 443   mkdir -p "$outdir/html_node_db"
 444   mv ${split_html_db_dir}/*.html "$outdir/html_node_db/"
 445   rmdir ${split_html_db_dir}
 446
 447   cmd="$DOCBOOK2TXT \"${outdir}/$PACKAGE-db.xml\""
 448   printf "\nGenerating docbook ASCII... ($cmd)\n"
 449   eval "$cmd"
 450   docbook_ascii_size=`calcsize $PACKAGE-db.txt`
 451   mv $PACKAGE-db.txt "$outdir/"
 452
 453   cmd="$DOCBOOK2PDF \"${outdir}/$PACKAGE-db.xml\""
 454   printf "\nGenerating docbook PDF... ($cmd)\n"
 455   eval "$cmd"
 456   docbook_pdf_size=`calcsize $PACKAGE-db.pdf`
 457   mv $PACKAGE-db.pdf "$outdir/"
 458 fi
 459
 460 # \f
 461 printf "\nMaking index.html for $PACKAGE...\n"
 462 if test -z "$use_texi2html"; then
 463   CONDS="/%%IF  *HTML_SECTION%%/,/%%ENDIF  *HTML_SECTION%%/d;\
 464          /%%IF  *HTML_CHAPTER%%/,/%%ENDIF  *HTML_CHAPTER%%/d"
 465 else
 466   # should take account of --split here.
 467   CONDS="/%%ENDIF.*%%/d;/%%IF  *HTML_SECTION%%/d;/%%IF  *HTML_CHAPTER%%/d"
 468 fi
 469
 470 curdate=`$SETLANG date '+%B %d, %Y'`
 471 sed \
 472    -e "s!%%TITLE%%!$MANUAL_TITLE!g" \
 473    -e "s!%%EMAIL%%!$EMAIL!g" \
 474    -e "s!%%PACKAGE%%!$PACKAGE!g" \
 475    -e "s!%%DATE%%!$curdate!g" \
 476    -e "s!%%HTML_MONO_SIZE%%!$html_mono_size!g" \
 477    -e "s!%%HTML_MONO_GZ_SIZE%%!$html_mono_gz_size!g" \
 478    -e "s!%%HTML_NODE_TGZ_SIZE%%!$html_node_tgz_size!g" \
 479    -e "s!%%HTML_SECTION_TGZ_SIZE%%!$html_section_tgz_size!g" \
 480    -e "s!%%HTML_CHAPTER_TGZ_SIZE%%!$html_chapter_tgz_size!g" \
 481    -e "s!%%INFO_TGZ_SIZE%%!$info_tgz_size!g" \
 482    -e "s!%%DVI_GZ_SIZE%%!$dvi_gz_size!g" \
 483    -e "s!%%PDF_SIZE%%!$pdf_size!g" \
 484    -e "s!%%ASCII_SIZE%%!$ascii_size!g" \
 485    -e "s!%%ASCII_GZ_SIZE%%!$ascii_gz_size!g" \
 486    -e "s!%%TEXI_TGZ_SIZE%%!$texi_tgz_size!g" \
 487    -e "s!%%DOCBOOK_HTML_NODE_TGZ_SIZE%%!$html_node_db_tgz_size!g" \
 488    -e "s!%%DOCBOOK_ASCII_SIZE%%!$docbook_ascii_size!g" \
 489    -e "s!%%DOCBOOK_PDF_SIZE%%!$docbook_pdf_size!g" \
 490    -e "s!%%DOCBOOK_XML_SIZE%%!$docbook_xml_size!g" \
 491    -e "s!%%DOCBOOK_XML_GZ_SIZE%%!$docbook_xml_gz_size!g" \
 492    -e "s,%%SCRIPTURL%%,$scripturl,g" \
 493    -e "s!%%SCRIPTNAME%%!$prog!g" \
 494    -e "$CONDS" \
 495 $GENDOCS_TEMPLATE_DIR/gendocs_template >"$outdir/index.html"
 496
 497 echo "Done, see $outdir/ subdirectory for new files."
 498
 499 # Local variables:
 500 # eval: (add-hook 'write-file-hooks 'time-stamp)
 501 # time-stamp-start: "scriptversion="
 502 # time-stamp-format: "%:y-%02m-%02d.%02H"
 503 # time-stamp-end: "$"
 504 # End: