Re: pdftk and apropos - general questions

["Lee D. Rothstein" <l1ee057 at veritech dot com>]

Mike Marchywka wrote:
> I've had a persistent problem getting apropos to work
> as it never finds anything appropriate. Is there
> something I need to do to make this work?
After each setup session, you need to run, /usr/sbin/makewhatis -u.




> The immediate need was trying to find pdf tools. Browsing
> the installs, it looks like pdftk will probably
> do what I need, along with other utilities I have.
> Are there additional pdf tools internal or external to cygwin
> people have found useful?
$ apropos pdf

on my system with all Cygwin packages installed yields:

a2x                  (1)  - convert Asciidoc text file to PDF, XHTML, 
HTML Help, manpage or plain text
dvipdf               (1)  - Convert TeX DVI file to PDF using 
ghostscript and dvips
dvipdfm              (1)  - Produce PDF files directly from DVI files
dvipdft              (1)  - create thumbnail images for use with dvipdfm
e2pall               (1)  - convert all EPS files in a LaTeX document to PDF
ebb                  (1)  - extract a bounding box from JPEG, PNG, and 
PDF files
epstopdf             (1)  - convert an EPS file to PDF
fdf2tex              (1)  - Convert PDF formular data (FDF) into 
something (Con)TeX(t) can handle
gs                   (1)  - Ghostscript (PostScript and PDF language 
interpreter and previewer)
gsnd                 (1)  - Run ghostscript (PostScript and PDF engine) 
without display
gv                   (1)  - Postscript and PDF viewer
makempy              (1)  - Helper script for conversion of (PDF or 
PostScript) text to Metapost graphics
pdf2dsc              (1)  - generate a PostScript page list of a PDF 
document
pdf2ps               (1)  - Ghostscript PDF to PostScript translator
pdfeinitex [pdfetex] (1)  - PDF output from e-TeX
pdfetex              (1)  - PDF output from e-TeX
pdfevirtex [pdfetex] (1)  - PDF output from e-TeX
pdffonts             (1)  - Portable Document Format (PDF) font analyzer 
(version 3.02)
pdfimages            (1)  - Portable Document Format (PDF) image 
extractor (version 3.02)
pdfinfo              (1)  - Portable Document Format (PDF) document 
information extractor (version 3.02)
pdfinitex [pdftex]   (1)  - PDF output from TeX
pdflatex [latex]     (1)  - structured text formatting and typesetting
pdfopt               (1)  - Ghostscript PDF Optimizer
pdfroff              (1)  - create PDF documents using groff
pdftex               (1)  - PDF output from TeX
pdftk                (1)  - A handy tool for manipulating PDF
pdftoppm             (1)  - Portable Document Format (PDF) to Portable 
Pixmap (PPM) converter (version 3.02)
pdftops              (1)  - Portable Document Format (PDF) to PostScript 
converter (version 3.02)
pdftotext            (1)  - Portable Document Format (PDF) to text 
converter (version 3.02)
pdfvirtex [pdftex]   (1)  - PDF output from TeX
pdfxinitex [pdfxtex] (1)  - PDF output from e-TeX
pdfxtex              (1)  - PDF output from e-TeX
pdfxvirtex [pdfxtex] (1)  - PDF output from e-TeX
ps2ascii             (1)  - Ghostscript translator from PostScript or 
PDF to ASCII
ps2pdf               (1)  - Convert PostScript to PDF using ghostscript
ps2pdf12 [ps2pdf]    (1)  - Convert PostScript to PDF 1.2 (Acrobat 
3-and-later compatible) using ghostscript
ps2pdf13 [ps2pdf]    (1)  - Convert PostScript to PDF 1.3 (Acrobat 
4-and-later compatible) using ghostscript
ps2pdfwr             (1)  - Convert PostScript to PDF without specifying 
CompatibilityLevel, using ghostscript
pstoedit             (1)  - a tool converting PostScript and PDF files 
into various vector graphic formats
rtf2pdf              (1)  - MicroSoft Rich Text Format (RTF) to Portable 
Document Format (PDF) translator
texexec              (1)  - ConTeXt and PDF auxiliary program and batch 
processor
texi2dvi4a2ps        (1)  - Compile Texinfo and LaTeX files to DVI or PDF
thumbpdf             (1)  - generate thumbnail images for a PDF file 
created with pdftex
tiff2pdf             (1)  - convert a TIFF image to a PDF document
xpdf                 (1)  - Portable Document Format (PDF) file viewer 
for X (version 3.02)
xpdfrc               (5)  - configuration file for Xpdf tools (version 3.02)

The above, however, misses my favorite:

man -t, which generates Postscript output that can be filtered thru 
ps2pdf. generating man pages in pdf format

Attached is a script that does this
> Basically on this new computer
> I've managed to do without Flash so far and I'd like to try
> to avoid installing any Adobe reader stuff.
Try Ghostgum ghostview. Windows compatible (no Cygwin, or X windows 
required and with print capability) and FOSS (free and open source 
software).

#!/usr/bin/bash

# man2pdf / man2lpr: render the specified MAN "pages" as PDF;
#   in the current directory; then browse or print

# By Lee Rothstein, 2008-05-17, 01:44 PM

# See:
# * 'usage ()', in this file
#   or:
# * $ man2pdf -h
#   at a command prompt
# for a complete script description

ProgName="$(basename $0)"
. set_title.s "$*"

#----------------------------------------------------------------
# Defaults & Other Initializations

Version=0.3.5alpha  # Version number of this script
AllFlag=false       # Print all pages that meet the command line
                    # specified topic?
BrowseFlag=false    # Browse the specified pages?
HelpFlag=false      # Output help?
DebugFlag=false     # Print information relevant to debugging
                    # script, parameters or results
ManFile=""          # Full path name of 'man' file; useful for
                    # checking alternate man page (e.g., debugging a
                    # man page before releasing or installing
PrintFlag=false     # Print the specified pages?
QueryFlag=false     # Just query for filenames to be processed and
                    # quit?
VerboseFlag=false   # Print all status as you go?
VersionFlag=false   # Print version?
ShortOpts="abf:hip:PqvV"
                    # Short options specification
LongOpts="all,browse,file:,help,inform,path:,query,print,verbose,version"
                    # Long options specification

#----------------------------------------------------------------
# usage () -- Help & exit with an apprpriate exit code

usage () {
  cat $(pathname $0)/../help/${ProgName}.1.txt|less
  exit $1
} # end of usage()

#------------------------------------------------------------------
# Preliminaries

TmpPath="$(tmpdir -l /tmp)"
if [[ "$?" -ne 0 ]] ; then
  echo "${ProgName}: * error *:"
  echo "  Neither \$TMPDIR, \$TEMP, nor /tmp reference a valid"
  echo "  directory that can be used for temporary files and"
  echo "  directories. Therefore execution has been aborted."
  usage 99
fi

# Define default path to save PDF output; i.e., a temp file.
SavePath="$TmpPath"

# Validate and normalize options requested

# Does the available version of 'getopt' supports long options?

if $(getopt -T &> /dev/null) ; [ $? -eq 4 ] ; then
  echo "'getopt' is correct version!" >/dev/null
else
  echo "$ProgName: * error *:"
  echo "  'getopt' command is obsolete!  Update 'getopt'!"
  usage 98
fi

# Store results in OptionsParsed variable in case 'getopt' "barfs"
OptionsParsed=$(getopt --options "$ShortOpts" --longoptions "$LongOpts"\
    -n "$ProgName" -- "$@")
error_code=$?
if [[ $error_code -ne 0 ]] ; then
  echo "$ProgName: * error *:"
  echo "  Error in options passed to 'getopt'. Error code is:"
  echo "  $error_code ."
  usage $error_code
fi

if [[ $DebugFlag == true ]] ; then
  echo "Options, after parsing are:"
  echo "  $OptionsParsed"
fi

# Reset args to this script terminating options with '--'
eval set -- "$OptionsParsed"

#------------------------------------------------------------------

# Process all flags based on (a) name this script invoked by, and
#   (b) command line options regardless of whether long or short
#   option format

# Set Browse or Print Flags based on script name used

case $ProgName in
  man2pdf) BrowseFlag=true ;;
  man2lpr) PrintFlag=true  ;;
  *) echo "${ProgName}: * error *: Unrecognized name for this script!"
     usage 99
     ;;
esac

# Set all other flags required by options

while [[ "$1" != "--" ]] ; do
  case $1 in
    -a|--all)
      AllFlag=true
      shift
      ;;
    -b|--browse)
      BrowseFlag=true
      shift
      ;;
    -f|--file)
      shift
      ManFile=$1
      shift
      if [[ ! -f "$ManFile" ]] ; then
        echo ""
        echo "${ProgName}: * error *:"
        echo "  'man' file name specified ('$ManFile') with the '-f|--file'"
        echo "  option does" not exist. This must be the full path name of"
        echo "  an existing" 'man' source file."
        echo ""
        usage 1
      fi
      ;;
    -h|--help)
      HelpFlag=true
      shift
      ;;
    -d|--debug)
      DebugFlag=true
      shift
      ;;
    -p|--path)
      shift
      SavePath="$1"
      shift
      ;;
    -P|--print)
      PrintFlag=true
      shift
      ;;
    -q|--query)
      QueryFlag=true
      shift
      ;;
    -v|--verbose)
      VerboseFlag=true
      shift
      ;;
    -V|--version)
      VersionFlag=true
      shift
      ;;
    *)
      echo "$ProgName: Error in option processing escaped"
      echo "  'getopt' sanity checking. Option being processed"
      echo "  is $1 ."
      usage 99
      ;;
  esac
done
shift # All options and terminating '--' have been processed and
      # purged from the command line arguments

#------------------------------------------------------------------
# Administrative Options Processing

# Debug?
if [[ $DebugFlag == true ]] ; then
  VariablesOfInterest=" \
    AllFlag \
    BrowseFlag \
    DebugFlag \
    HelpFlag \
    LongOpts \
    ManFile \
    PrintFlag \
    ProgName \
    SavePath \
    ShortOpts \
    TMPDIR \
    VerboseFlag \
    VersionFlag \
  "
  for var in $VariablesOfInterest ; do
    eval echo -n "$var == \$$var"
  done
fi

# Version?
if [[ "$VersionFlag" == true ]] ; then
  echo "${ProgName}, v. $Version"
  echo ""
fi

# Help -- If you ask for help, that's all you get (except for the
# version and debug info output already)
if [[ "$HelpFlag" == true ]] ; then usage 0 ; fi

#******************************************************************
# Main Body

# Respectively: create a PDF for a (a) those 'man' files that match a
#               specified section number and topic, or (b) specified
#               'man' file (option '-f')
# In either case carry out all appropriate options requested

# If "$ManFile" is null, then man page comes from specified path, as
# opposed to 'man' retrieving it from "its domain"

if [[ -z "$ManFile" ]] ; then

  #==================================================================
  # 'man' page from general arguments: <sect_num> <topic>

  # Test sanity of remaining non-option arguments
  # All others should have been eaten ('shift') in options processing
  case $# in
    0)
      echo ""
      echo "${ProgName}: * error *: Missing argument(s)!"
      echo ""
      echo "  Requires 1 or 2 arguments, other than options!"
      echo ""
      usage 2
      ;;
    1)
      ArgTopic=$1
      ArgSectNum=""
      ;;
    2)
      ArgTopic=$2
      ArgSectNum=$1
      ;;
    *)
      echo ""
      echo "${ProgName}: * error *: Takes one or two arguments,"
      echo "  other than options (and their arguments), only."
      echo ""
      usage 3
      ;;
  esac

  # Find 'man' "page" source files that match topic and section
  #   number & report if required

  # Collect them & count them
  #   If $ArgSectNum is null, then all section numbers of "$ArgTopic"
  #   will be collected/rendered/browsed
  ManPages="$(man -aw $ArgSectNum $ArgTopic)"
  NumManPageFiles=$(wc -l<<<"$ManPages")

  if [[ "$VerboseFlag" == true || $QueryFlag == true ]] ; then
    echo "$NumManPageFiles were found that matched: '${ArgSectNum}' '${ArgTopic}'"
    if [[ "$NumManPageFiles" -ne 0 ]] ; then
      echo "These are:"
      for ManPageFile in $ManPages ; do
        printf "  $s\n" "$ManPageFile"
      done
    fi
  fi

  if [[ "$QueryFlag" == true ]] ; then # We've queried, were outta' here.
    exit 0
  fi

  if [[ "$NumManPageFiles" == 0 ]] ; then
    echo "${ProgName}: * error *: No 'man' pages match the topic, $ArgTopic,"
    echo "  in any section of 'man'!"
    usage 4
  fi

  # Output 'man' "pages" appropriate to flags (PDF to browse, or PDF to print)

  for ManPageFile in $ManPages ; do

    # man_page_file_path_parse -- parse the full pathname of a 'man' page
    #   ("$1"), remove extraneous information and output it as:
    #   <section number> <topic>
    SectNumTopic="$(echo $ManPageFile|xargs --max-lines=1 man_page_file_path_parse)"
    SectNum="$(echo "$SectNumTopic"|gawk '{ print $1 }')"
    Topic="$(echo $SectNumTopic|gawk '{ print $2 }')"
    PdfFile="${SavePath}/${Topic}.${SectNum}.pdf"

    # Get the page to current directory and capture resulting file name
    #   Remember, $SectNum only contains the section number of the file,
    #   the extension may be appended with letters, as in 'echo.3x'.
    #   We make a local copy of the man page file because we're going to
    #   remove blank lines from it and we don't want to muck with the
    #   original

    ManFile="$(man_get $SectNumTopic -p $TmpPath)"
    ManFile="$TmpPath/$ManFile"

    # 'man -t' -- render in Postscript
    # 'ps2pdf' (part of Ghostscript package) -- convert Postscript to PDF

    man -t $ManFile|ps2pdf - ${PdfFile}
    if [[ "$BrowseFlag" == true ]] ; then
      cygstart ${PdfFile}
    fi
    if [[ "$PrintFlag" == true ]] ; then
      pdf2lpr ${PdfFile}
    fi
    if [[ "$AllFlag" == false ]] ; then break ; fi
  done

#=======================================================================
# 'man' page comes from specified file ('-f' option)

else
  # "Trick" man for current directory man file if necessary
  if [[ "$(basename $ManFile)" == "$ManFile" ]] ; then
    ManFile="./${ManFile}"
  fi

  PdfFile="${SavePath}/$(basename $ManFile).pdf"

  # Note that blank lines are not removed here, as above. The script, here,
  # assumes you must be the author of this man page; and therfore the
  # you "know" that you can't have embedded blank lines
  # outside of '.nf' ... '.fi' sequences and expect to get Postscript
  # (typset) rendering.
  man -t $ManFile|ps2pdf - ${PdfFile}
  if [[ $BrowseFlag == true ]] ; then
    cygstart ${PdfFile}
  fi
  if [[ $PrintFlag == true ]] ; then
    pdf2lpr ${PdfFile}
  fi
fi

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Problem reports:       http://cygwin.com/problems.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/