httrack/man/makeman.sh

#!/bin/sh
#
# Regenerate man/httrack.1 from "httrack --help" and the top-level README.
#
# Usage:
#   man/makeman.sh [HTTRACK_BINARY] > man/httrack.1
#
# HTTRACK_BINARY defaults to "httrack" (looked up in $PATH). Set SOURCE_DATE_EPOCH
# for a reproducible page date.
#
# The OPTIONS section is derived from --help by indentation, which is what makes
# it robust (no more prose turning into bogus options, see Debian #1061053):
#   column 0 starting with "--"  -> long option    (.IP)
#   column 0 otherwise           -> section header  (.SS)
#   1-2 leading spaces           -> option          (.IP)
#   3+ leading spaces            -> continuation / sub-value (description text)
#
# This replaces the previous out-of-tree script that grepped the first token of
# every indented line and mislabelled continuations as options.

set -eu

httrack=${1:-httrack}
script_dir=$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)
topdir=${TOPDIR:-$(CDPATH='' cd -- "$script_dir/.." && pwd)}
readme=${README:-$topdir/README}

# Reproducible date when SOURCE_DATE_EPOCH is set, otherwise today.
if [ -n "${SOURCE_DATE_EPOCH:-}" ]; then
    date_str=$(LC_ALL=C date -u -d "@${SOURCE_DATE_EPOCH}" '+%d %B %Y' 2>/dev/null ||
        LC_ALL=C date -u -r "${SOURCE_DATE_EPOCH}" '+%d %B %Y')
else
    date_str=$(LC_ALL=C date '+%d %B %Y')
fi
year=${date_str##* }

help=$("$httrack" --quiet --help 2>/dev/null)

st=$(printf '%s\n' "$help" | grep -n 'General options' | head -1 | cut -d: -f1)
en=$(printf '%s\n' "$help" | grep -nE '^example' | head -1 | cut -d: -f1)
en2=$(printf '%s\n' "$help" | grep -nE '^HTTrack version' | tail -1 | cut -d: -f1)

# SYNOPSIS: one "[ -x, --long ]" per option carrying a long name (skip "#" guru
# options, as the original did).
synopsis=$(printf '%s\n' "$help" | awk '
  $0 ~ /\(--/ && $0 !~ / #/ {
    short = $1
    if (match($0, /\(--[^ )]+/)) {
      lng = substr($0, RSTART + 3, RLENGTH - 3)
      gsub(/-/, "\\-", short); gsub(/-/, "\\-", lng)
      printf "[ \\fB\\-%s, \\-\\-%s\\fR ]\n", short, lng
    }
  }')

# OPTIONS: indentation-driven classifier (see header comment).
options=$(printf '%s\n' "$help" | sed -n "${st},$((en - 2))p" | awk '
  function esc(s) {
    gsub(/\\/, "\\\\", s)
    gsub(/-/, "\\-", s)
    return s
  }
  function emit(s) {                       # body text: escape + guard ./%apostrophe leaders
    s = esc(s)
    if (substr(s, 1, 1) == "." || substr(s, 1, 1) == "\x27") s = "\\&" s
    print s
  }
  /^[ \t]*$/ { next }
  {
    match($0, /^ */); ind = RLENGTH
    if (ind == 0 && substr($0, 1, 2) == "--") {        # long option
      opt = $1
      rest = $0; sub(/^[^ \t]+[ \t]+/, "", rest)
      printf ".IP %s\n", esc(opt)
      emit(rest)
    } else if (ind == 0) {                             # section header
      printf ".SS %s\n", esc($0)
    } else if (ind <= 2) {                             # option
      opt = $1
      gsub(/^\x27|\x27$/, "", opt)                     # drop quotes around tokens like %t
      rest = $0; sub(/^[ \t]+[^ \t]+[ \t]*/, "", rest)
      printf ".IP \\-%s\n", esc(opt)
      if (rest != "") emit(rest)
    } else {                                           # continuation / sub-value
      line = $0; sub(/^[ \t]+/, "", line)
      print ".br"
      emit(line)
    }
  }')

# EXAMPLES: "example: <cmd>" / "means: <text>" pairs after the options block.
examples=$(printf '%s\n' "$help" | sed -n "${en},$((en2 - 1))p" | awk '
  function esc(s) { gsub(/\\/, "\\\\", s); gsub(/-/, "\\-", s); return s }
  /^example:/ { sub(/^example:[ \t]*/, ""); printf ".TP\n.B %s\n", esc($0); next }
  /^means:/   { sub(/^means:[ \t]*/, "");   if ($0 != "") print esc($0); next }
')

# LIMITS: the "Engine limits" block from the README.
limits=$(awk '
  function esc(s) { gsub(/\\/, "\\\\", s); gsub(/-/, "\\-", s); return s }
  /^Engine limits/ { grab = 1; next }
  /^Advanced options/ { grab = 0 }
  grab {
    if ($0 ~ /^-/) { print ".SM"; print esc($0) }
    else if ($0 !~ /^[ \t]*$/) print esc($0)
  }' "$readme")

# --- assemble the page: static prose in quoted heredocs, dynamic parts printf'd ---
cat <<'EOF'
.\" Process this file with
.\" groff -man -Tascii httrack.1
.\"
.\" This file is generated by man/makeman.sh; do not edit by hand.
.\" SPDX-License-Identifier: GPL-3.0-or-later
EOF
printf '.TH httrack 1 "%s" "httrack website copier"\n' "$date_str"
cat <<'EOF'
.SH NAME
httrack \- offline browser : copy websites to a local directory
.SH SYNOPSIS
.B httrack [ url ]... [ \-filter ]... [ +filter ]...
EOF
printf '%s\n' "$synopsis"
cat <<'EOF'
.SH DESCRIPTION
.B httrack
allows you to download a World Wide Web site from the Internet to a local directory, building recursively all directories, getting HTML, images, and other files from the server to your computer. HTTrack arranges the original site's relative link-structure. Simply open a page of the "mirrored" website in your browser, and you can browse the site from link to link, as if you were viewing it online. HTTrack can also update an existing mirrored site, and resume interrupted downloads.
.SH EXAMPLES
EOF
printf '%s\n' "$examples"
cat <<'EOF'
.SH OPTIONS
EOF
printf '%s\n' "$options"
cat <<'EOF'
.SH FILES
.I /etc/httrack.conf
.RS
The system wide configuration file.
.SH ENVIRONMENT
.IP HOME
Is being used if you defined in /etc/httrack.conf the line
.I path ~/websites/#
.SH DIAGNOSTICS
Errors/Warnings are reported to
.I hts\-log.txt
by default, or to stderr if the
.I \-v
option was specified.
.SH LIMITS
EOF
printf '%s\n' "$limits"
cat <<'EOF'
.SH BUGS
Please reports bugs to
.B <bugs@httrack.com>.
Include a complete, self-contained example that will allow the bug to be reproduced, and say which version of httrack you are using. Do not forget to detail options used, OS version, and any other information you deem necessary.
.SH COPYRIGHT
EOF
printf 'Copyright (C) 1998-%s Xavier Roche and other contributors\n' "$year"
cat <<'EOF'

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 <http://www.gnu.org/licenses/>.

.SH AVAILABILITY
The  most  recent released version of httrack can be found at:
.B http://www.httrack.com
.SH AUTHOR
Xavier Roche <roche@httrack.com>
.SH "SEE ALSO"
The
.B HTML
documentation (available online at
.B http://www.httrack.com/html/
) contains more detailed information. Please also refer to the
.B httrack FAQ
(available online at
.B http://www.httrack.com/html/faq.html
)
EOF