#!/usr/bin/perl -w

#############################################################################
#                               makepointerman
#############################################################################
#
# This program creates a Netpbm man page that says nothing except to use a
# web browser to look at a particular URL.
#
# In Netpbm, we believe that man pages, and the Nroff/Troff formats, are
# obsolete; that HTML and web browsers and the world wide web long ago replaced
# them as the best way to deliver documentation.  However, documentation is 
# useless when people don't know where it is.  People are very accustomed to
# typing "man" to get information on a Unix program or library or file type,
# so in the standard Netpbm installation, we install a conventional man page
# for every command, library, and file type, but all it says is to use your
# web browser to look at the real documentation.

# I believe what would be ideal is if the user simply had an enhanced 'man'
# program that went directly to the URL.  The program could recognize a
# file that ends in ".url" in the place where it would normally find a man
# page as a file that contains a URL to be viewed instead.  It would then 
# invoke a web browser.  If that browser were Lynx, it would run in 
# environments about as simple as where 'man' traditionally runs.

# But until such a man program becomes widespread, it wouldn't be practical for
# a Netpbm configuration to depend on it.

# Besides making the web documentation accessible, pointer man pages serve
# another important purpose:  Installing them causes obsolete man pages from
# before web documentation existed to be discarded.

use strict;
use Time::gmtime;

if (@ARGV < 5) {
    die("Need 5 arguments: filename, directory URL, man page directory, " .
        "man section, octal permissions");
}

my ($filename, $directoryURL, $mandir, $section, $permissions) = @ARGV;

my $manPageFileName = "$mandir/$filename.$section";

unlink($manPageFileName);

open(MANPAGE, ">$manPageFileName");

my ($wday, $mon, $mday, $tod, $year) = split(/ /,gmctime());
print(MANPAGE ".TH $filename $section Netpbm \"$mday $mon $year\" " .
      "\"Netpbm pointer man pages\"\n\n");

print(MANPAGE "$filename is part of the Netpbm package.\n");
print(MANPAGE "Netpbm documentation is kept in HTML format.\n");
print(MANPAGE "\n");
print(MANPAGE "Please refer to <$directoryURL/$filename>.\n\n");
print(MANPAGE "If that doesn't work, also try " .
      "<http://netpbm.sourceforge.net> and\n");
print(MANPAGE "emailing Bryan Henderson, bryanh\@giraffe-data.com.\n");

print(MANPAGE "./ This file was generated by the program 'makepointerman',\n");
print(MANPAGE "./ as part of Netpbm installation\n");

chmod(oct("0$permissions"),$manPageFileName);
close(MANPAGE);









