#!/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.

# What would be ideal is if the user simply had Manweb (or something like
# it) installed as the 'man' command and configured to find the Netpbm
# web documentation.

# But because of the high probability that Netpbm installers will not 
# install Manweb, pointer man pages are necessary.

# 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 6 arguments: filename, directory URL, man page directory, " .
        "man section, format, octal permissions");
}

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

if ($format ne "nroff" && $format ne "cat") {
    die("format argument must be 'nroff' or 'cat', not '$format'.");
}
my $manPageFileName = "$mandir/$filename.$section";

unlink($manPageFileName);

open(MANPAGE, ">$manPageFileName") or
    die("Unable to create file '$manPageFileName'");

my ($wday, $mon, $mday, $tod, $year) = split(/ /,gmctime());
if ($format eq "nroff") {
    print(MANPAGE ".TH $filename $section Netpbm \"$mday $mon $year\" " .
          "\"Netpbm pointer man pages\"\n\n");
    
    # NAME and DESCRIPTION section headings help some automated processors,
    # such as Doclifter.  From ESR 2004.11.14.

    # avoid a double slash in the URL
    (my $cleanedUpDirectoryUrl = $directoryUrl) =~ s{^(.*?)/*$}{$1};

    print(MANPAGE ".SH NAME\n");
    print(MANPAGE "$filename \\- see $cleanedUpDirectoryUrl/$filename.html\n");
    print(MANPAGE ".SH DESCRIPTION\n");
} else {
    print(MANPAGE "        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.html>.\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 "\n");
print(MANPAGE "Note that it is possible to install Netpbm with the\n");
print(MANPAGE "documentation available differently.  For example, you\n");
print(MANPAGE "could simply see the documentation instead of the message\n");
print(MANPAGE "you are reading now.  The file 'doc/USERDOC' in the Netpbm\n");
print(MANPAGE "source tree contains details.");
print(MANPAGE "\n");

if ($format eq "nroff") {
    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);