xpod2man

#!/usr/bin/perl
# IBM(c) 2007 EPL license http://www.eclipse.org/legal/epl-v10.html

# First builds the xCAT summary man page from Synopsis of each man page.
# Then converts all of the pod man pages into html (including links to each other)

# We assume that this script is run in the xCAT-client-2.0 dir, so everything is
# done relative to that.

use strict;

#use lib '.';
use Pod::Man;
use Pod::Html;

my $poddir   = 'pods';
my $mandir   = 'share/man';
my $htmldir  = 'share/doc';
my $cachedir = "$ENV{'HOME'}/tmp";
if (system("mkdir -p $cachedir")) { die "Error: could not create $cachedir.\n"; }

my @pods = getPodList($poddir);

#foreach (@pods) { print "$_\n"; } exit;

# Build the cmd overview page.
writesummarypage("$poddir/man1/xcat.1.pod", @pods);
push @pods, "$poddir/man1/xcat.1.pod";

# Build the man page for each pod.
#mkdir($mandir) or die "Error: could not create $mandir.\n";
print "Converting PODs to man pages...\n";
foreach my $podfile (@pods) {
    my $manfile = $podfile;
    $manfile =~ s/^$poddir/$mandir/;    # change the beginning of the path
    $manfile =~ s/\.pod$//;             # change the ending
    my $mdir = $manfile;
    $mdir =~ s|/[^/]*$||;               # get rid of the basename part
    if (system("mkdir -p $mdir")) { die "Error: could not create $mdir.\n"; }
    my ($section) = $podfile =~ /\.(\d+)\.pod$/;
    convertpod2man($podfile, $manfile, $section);
}

my @dummyPods = createDummyPods($poddir, \@pods);

# Build the html page for each pod.
#mkdir($htmldir) or die "Error: could not create $htmldir.\n";
print "Converting PODs to HTML pages...\n";

# have to clear the cache, because old entries can cause a problem
unlink("$cachedir/pod2htmd.tmp", "$cachedir/pod2htmi.tmp");
foreach my $podfile (@pods) {
    my $htmlfile = $podfile;
    $htmlfile =~ s/^$poddir/$htmldir/;    # change the beginning of the path
    $htmlfile =~ s/\.pod$/\.html/;        # change the ending
    my $hdir = $htmlfile;
    $hdir =~ s|/[^/]*$||;                 # get rid of the basename part
    if (system("mkdir -p $hdir")) { die "Error: could not create $hdir.\n"; }

    #print "$podfile, $htmlfile, $poddir, $htmldir\n";
    convertpod2html($podfile, $htmlfile, $poddir, $htmldir);
}

# Remove the dummy pods
unlink @dummyPods;
rmdir "$poddir/man7";

exit;


# To enable linking between the cmd man pages and the db man pages, need to:
#	grep thru the cmd pods searching for references (L<>) to any section 5 man page
#	if that pod does not exist, create an empty one that will satisfy pod2html
#	keep track of all dummy pods created, so they can be removed later
sub createDummyPods {
    my ($poddir, $pods) = @_;
    my $cmd = "grep -r -E 'L<.+\\([57]\\)\\|.+\\.[57]>' " . $poddir;

    #print "Running cmd: ", $cmd, "\n";
    my @lines = `$cmd`;
    if ($?) { print "Did not find any section 5 man page, creating dummy pods...\n"; print join('', @lines); }

    #my @lines;
    #system($cmd);
    my @dummyPods;
    foreach my $l (@lines) {

        #print "$l\n";
        my @matches = $l =~ /L<([^\(]+)\(([57])\)\|\1\.[57]>/g; # get all the matches in the line
          # The above line should create the array with every other entry being the man page name
          # and every other entry is the section # (5 or 7)
        my $cmd;
        while ($cmd = shift @matches) {

            #foreach my $m (@matches) {
            my $section  = shift @matches;
            my $filename = "$poddir/man$section/$cmd.$section.pod";

            #print "$filename\n";
            if (!(grep /^$filename$/, @$pods) && !(grep /^$filename$/, @dummyPods)) { push @dummyPods, $filename; }
        }
    }

    # Also add xcattest.1.pod and buildkit.1.pod, because the xcat.1.pod summary page refers to it
    push @dummyPods, "$poddir/man1/xcattest.1.pod";
    push @dummyPods, "$poddir/man1/buildkit.1.pod";

    # Create these empty files
    print "Creating empty linked-to files: ", join(', ', @dummyPods), "\n";
    mkdir "$poddir/man7";
    foreach my $d (@dummyPods) {
        if (!open(TMP, ">>$d")) { warn "Could not create dummy pod file $d ($!)\n"; }
        else                    { close TMP; }
    }

    return @dummyPods;
}

# Recursively get the list of pod man page files.
sub getPodList {
    my $poddir = shift;
    my @files;

    # 1st get toplevel dir listing
    opendir(DIR, $poddir) or die "Error: could not read $poddir.\n";
    my @topdir = grep !/^\./, readdir(DIR);    # /
    close(DIR);

    # Now go thru each subdir (these are man1, man3, etc.)
    foreach my $mandir (@topdir) {
        opendir(DIR, "$poddir/$mandir") or die "Error: could not read $poddir/$mandir.\n";
        my @dir = grep !/^\./, readdir(DIR);    # /
        close(DIR);
        foreach my $file (@dir) {
            push @files, "$poddir/$mandir/$file";
        }
    }
    return sort @files;
}


# Create the xcat man page that gives a summary description of each xcat cmd.
sub writesummarypage {
    my $file = shift;    # relative path file name of the man page
         # the rest of @_ contains the pod files that describe each cmd

    open(FILE, ">$file") or die "Error: could not open $file for writing.\n";

    print FILE <<'EOS1';
=head1 NAME

B<xcat> - extreme Cluster Administration Tool.

=head1 DESCRIPTION

Extreme Cluster Administration Toolkit (xCAT). xCAT is a scalable distributed computing management
and provisioning tool that provides a unified interface for hardware control, discovery, and
OS diskful/diskfree deployment.


=head1 XCAT DATABASE

All of the cluster configuration information is in the xCAT database.  See L<xcatdb(5)|xcatdb.5> for
descriptions of every table in the database.

=head1 XCAT ADDITIONAL TOOLS

Some additional tools have been contributed to xCAT.  You can read about them at http://xcat-docs.readthedocs.org/en/latest/guides/admin-guides/references/index.html
or in /opt/xcat/share/xcat/tools/README.txt on your xCAT management node.

=head1 XCAT COMMANDS

What follows is a short description of each xCAT command.  To get more information about a particular
command, see its man page.  Note that the commands are listed in alphabetical order B<within each section>,
i.e. all the commands in section 1, then the commands in section 3, etc.

=over 12
EOS1

    # extract the summary for each cmd from its man page
    foreach my $manpage (@_) {
        my ($cmd, $sectionnum) = $manpage =~ /([^\/]+)\.(\d+)\.pod$/;

        # Suck in the whole file, then we will parse it.
        open(MANPAGE, "$manpage") or die "Error: could not open $manpage for reading.\n";
        my @contents = <MANPAGE>;
        my $wholemanpage = join('', @contents);
        close(MANPAGE);

        # This regex matches: optional space, =head1, space, title, space, cmd, space, description, newline
        my ($description) = $wholemanpage =~ /^\s*=head1\s+\S+\s+\S+\s+(.+?)\n/si;
        if (!defined($description)) { print "Warning: $manpage does not have a description for $cmd.  It will be ignored.\n"; next; }
        $description =~ s/^-\s*//; # if the description has a leading hypen, strip it off
        print FILE "\n=item L<$cmd($sectionnum)|$cmd.$sectionnum>\n\n" . $description . "\n";
    }

    # Artificially add the xcattest and buildkit cmds,
    #  because the xCAT-test and xCAT-buildkit rpms will add these
    print FILE "\n=item L<xcattest(1)|xcattest.1>\n\nRun automated xCAT test cases.\n";
    print FILE "\n=item L<buildkit(1)|buildkit.1>\n\nBuild product software kits to be installed in an xCAT cluster.\n";

    print FILE <<"EOS3";

=back
EOS3

    close FILE;
}


# Create the html page for one pod.
sub convertpod2html {
    my ($podfile, $htmlfile, $poddir, $htmldir) = @_;

    #TODO: use --css=<stylesheet> and --title=<pagetitle> to make the pages look better
    pod2html($podfile,
        "--outfile=$htmlfile",
        "--podpath=man1:man3:man5:man7:man8",
        "--podroot=$poddir",
        "--htmldir=$htmldir",
        "--recurse",
        "--cachedir=$cachedir",
    );

}


# Create the man page for one pod.
sub convertpod2man {
    my ($podfile, $manfile, $section) = @_;

    my $parser = Pod::Man->new(section => $section);
    $parser->parse_from_file($podfile, $manfile);
}