xcat-core/xCAT-client/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 = '/tmp';

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.sourceforge.net/tools/README.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);
}