about summary refs log tree commit diff
path: root/buildtools/makepointerman
blob: 8fbb0f4954c12985b66f38c0b09ec7a24143c0b1 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
#!/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 making the documentation available this way was\n");
print(MANPAGE "a choice of the person who installed Netpbm on this system.\n");
print(MANPAGE "It is also possible to install Netpbm such that you would\n");
print(MANPAGE "simply see the documentation instead of the message you are\n");
print(MANPAGE "reading now.\n");
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);