mirror of
https://github.com/xcat2/xcat-core.git
synced 2025-11-04 05:12:30 +00:00
235 lines
8.0 KiB
Perl
Executable File
235 lines
8.0 KiB
Perl
Executable File
#!/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);
|
|
}
|