From cd9d9eb42b2814eb721c234f07ba3a18c16d246e Mon Sep 17 00:00:00 2001 From: bp-sawyers Date: Mon, 17 Mar 2008 13:34:40 +0000 Subject: [PATCH] Added man pages, and automatically convert them to html. git-svn-id: https://svn.code.sf.net/p/xcat/code/xcat-core/trunk@792 8638fb3e-16cb-4fca-ae20-7b5d299a9bcd --- perl-xCAT-2.0/db2man | 117 ++++++++++-- perl-xCAT-2.0/perl-xCAT.spec | 16 +- perl-xCAT-2.0/xCAT/Schema.pm | 48 ++--- xCAT-client-2.0/pods/man1/chtab.1.pod | 71 -------- xCAT-client-2.0/pods/man1/nodestat.1.pod | 4 +- xCAT-client-2.0/pods/man1/prsync.1.pod | 6 +- xCAT-client-2.0/pods/man1/pscp.1.pod | 4 +- xCAT-client-2.0/pods/man1/psh.1.pod | 8 +- xCAT-client-2.0/pods/man1/rcons.1.pod | 4 +- xCAT-client-2.0/pods/man1/updte_SNimage.1.pod | 24 +-- xCAT-client-2.0/pods/man1/wcons.1.pod | 4 +- xCAT-client-2.0/pods/man1/wkill.1.pod | 4 +- xCAT-client-2.0/pods/man1/xdsh.1.pod | 2 + xCAT-client-2.0/pods/man1/xdshbak.1.pod | 2 + xCAT-client-2.0/pods/man8/chtab.8.pod | 71 ++++++++ .../makedhcp.1.pod => man8/makedhcp.8.pod} | 0 .../nodeadd.1.pod => man8/nodeadd.8.pod} | 0 .../nodeset.1.pod => man8/nodeset.8.pod} | 32 ++-- .../tabdump.1.pod => man8/tabdump.8.pod} | 0 .../tabedit.1.pod => man8/tabedit.8.pod} | 0 .../tabrestore.8.pod} | 0 xCAT-client-2.0/share/doc/index.html | 30 ++++ xCAT-client-2.0/xCAT-client.spec | 45 +++-- xCAT-client-2.0/xpod2man | 167 ++++++++++++++++++ xCAT-web/etc/apache2/conf.d/xcat-web.conf | 2 +- xCAT/xcat.conf | 10 +- 26 files changed, 497 insertions(+), 174 deletions(-) delete mode 100644 xCAT-client-2.0/pods/man1/chtab.1.pod create mode 100644 xCAT-client-2.0/pods/man8/chtab.8.pod rename xCAT-client-2.0/pods/{man1/makedhcp.1.pod => man8/makedhcp.8.pod} (100%) rename xCAT-client-2.0/pods/{man1/nodeadd.1.pod => man8/nodeadd.8.pod} (100%) rename xCAT-client-2.0/pods/{man1/nodeset.1.pod => man8/nodeset.8.pod} (82%) rename xCAT-client-2.0/pods/{man1/tabdump.1.pod => man8/tabdump.8.pod} (100%) rename xCAT-client-2.0/pods/{man1/tabedit.1.pod => man8/tabedit.8.pod} (100%) rename xCAT-client-2.0/pods/{man1/tabrestore.1.pod => man8/tabrestore.8.pod} (100%) create mode 100644 xCAT-client-2.0/share/doc/index.html create mode 100644 xCAT-client-2.0/xpod2man diff --git a/perl-xCAT-2.0/db2man b/perl-xCAT-2.0/db2man index 8483a562f..0e1fb160e 100755 --- a/perl-xCAT-2.0/db2man +++ b/perl-xCAT-2.0/db2man @@ -8,30 +8,117 @@ # We assume that this script is run in the perl-xCAT-2.0 dir, so everything is # done relative to that. +use strict; use lib '.'; use xCAT::Schema; use xCAT::Table; +use Pod::Man; +use Pod::Html; -my $poddir = 'pods/man5'; -if (system("mkdir -p $poddir")) { die "Error: could not create $poddir.\n"; } +my $poddir = 'pods'; +my $mandir = 'share/man'; +my $htmldir = 'share/doc'; + +my $poddir5 = 'pods/man5'; +if (system("mkdir -p $poddir5")) { die "Error: could not create $poddir5.\n"; } # Build the DB overview page. -writesummarypage("$poddir/xcatdb.5.pod", xCAT::Table->getDescriptions()), +print "Building PODs pages for the database tables...\n"; +writesummarypage("$poddir5/xcatdb.5.pod", xCAT::Table->getDescriptions()), -# Build the man page for each table. +# Build the pod man page for each table. my $tabspecref = \%xCAT::Schema::tabspec; foreach my $tablekey (keys %$tabspecref) { my $table = $tabspecref->{$tablekey}; my $summary = $table->{table_desc}; my $colorder = $table->{cols}; my $descriptions = $table->{descriptions}; - writemanpage("$poddir/$tablekey.5.pod", $tablekey, $summary, $colorder, $descriptions); + writepodmanpage("$poddir5/$tablekey.5.pod", $tablekey, $summary, $colorder, $descriptions); +} + +my @pods = getPodList($poddir); +#foreach (@pods) { print "$_\n"; } exit; + +# 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); +} + +# Build the html page for each pod. +#mkdir($htmldir) or die "Error: could not create $htmldir.\n"; +print "Converting PODs to HTML pages...\n"; +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"; } + convertpod2html($podfile, $htmlfile, $poddir, $htmldir); } exit; +# 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 html page for one pod. +sub convertpod2html { + my ($podfile, $htmlfile, $poddir, $htmldir) = @_; + + #TODO: use --css= and --title= to make the pages look better + pod2html($podfile, + "--outfile=$htmlfile", + "--podpath=man5", + "--podroot=$poddir", + "--htmldir=$htmldir", + "--recurse", + "--cachedir=/tmp", + ); + +} + + +# 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); +} + + # Create the xcatdb man page that gives a summary description of each table. sub writesummarypage { my $file = shift; # relative path file name of the man page @@ -127,7 +214,7 @@ all of the information should go in. EOS1 foreach my $table (sort keys %$descriptions) { - print FILE "\n=item I<$table>\n\n".$descriptions->{$table}."\n"; + print FILE "\n=item L<$table(5)|$table.5>\n\n".$descriptions->{$table}."\n"; } print FILE <<"EOS3"; @@ -136,7 +223,7 @@ foreach my $table (sort keys %$descriptions) { =head1 SEE ALSO -nodels(1), tabedit(1), chtab(1), tabdump(1), lsdef(1), mkdef(1), chdef(1), rmdef(1) +B, B, B, B, B, B, B, B EOS3 close FILE; @@ -144,7 +231,7 @@ EOS3 # Create the man page for one table. -sub writemanpage { +sub writepodmanpage { my $file = shift; # relative path file name of the man page my $tablename = shift; # name of table my $summary = shift; # description of table @@ -171,20 +258,26 @@ foreach my $a (@$colorder) { print FILE " I<$a>\n"; } $summary -B<$tablename Attributes:> +=head1 $tablename Attributes: + +=over 10 + EOS2 foreach my $a (@$colorder) { my $d = $descriptions->{$a}; $d =~ s/\n/\n\n/; # if there are newlines, double them so pod sees a blank line, otherwise pod will ignore them - print FILE "\nI<$a> - $d\n"; + #print FILE "\nB<$a> - $d\n"; + print FILE "\n=item B<$a>\n\n$d\n"; } print FILE <<"EOS3"; -=head1 NOTES +=back -This command is part of the xCAT software product. +=head1 SEE ALSO + +B, B, B, B EOS3 close FILE; diff --git a/perl-xCAT-2.0/perl-xCAT.spec b/perl-xCAT-2.0/perl-xCAT.spec index 511c8a4f2..fd6fbdb07 100644 --- a/perl-xCAT-2.0/perl-xCAT.spec +++ b/perl-xCAT-2.0/perl-xCAT.spec @@ -28,14 +28,15 @@ Includes xCAT::Table, xCAT::NodeRange, among others. # as it is in svn. # Build the pod version of the man pages for each DB table. It puts them in the man5 subdir. +# The convert the pods to man pages and html pages. ./db2man # Convert pods to man pages, e.g.: pod2man pods/man5/chain.5.pod share/man/man5/chain.1 -for i in pods/*/*.pod; do - man="share/man${i#pods}" # the substitute form is not supported on aix: ${i/pods/share\/man} - mkdir -p ${man%/*} - pod2man $i ${man%.pod} -done +# for i in pods/*/*.pod; do +# man="share/man${i#pods}" # the substitute form is not supported on aix: ${i/pods/share\/man} +# mkdir -p ${man%/*} +# pod2man $i ${man%.pod} +# done %install # The install phase puts all of the files in the paths they should be in when the rpm is @@ -47,6 +48,7 @@ rm -rf $RPM_BUILD_ROOT mkdir -p $RPM_BUILD_ROOT/%{prefix}/lib/perl/xCAT/data mkdir -p $RPM_BUILD_ROOT/%{prefix}/share/doc/packages/perl-xCAT mkdir -p $RPM_BUILD_ROOT/%{prefix}/share/man/man5 +mkdir -p $RPM_BUILD_ROOT/%{prefix}/share/doc/man5 cp -r xCAT/* $RPM_BUILD_ROOT/%{prefix}/lib/perl/xCAT/ chmod 644 $RPM_BUILD_ROOT/%{prefix}/lib/perl/xCAT/* @@ -60,7 +62,9 @@ chmod 644 $RPM_BUILD_ROOT/%{prefix}/README # These were built dynamically in the build phase cp share/man/man5/* $RPM_BUILD_ROOT/%{prefix}/share/man/man5 -chmod 444 $RPM_BUILD_ROOT/%{prefix}/share/man/man5/* +chmod 644 $RPM_BUILD_ROOT/%{prefix}/share/man/man5/* +cp share/doc/man5/* $RPM_BUILD_ROOT/%{prefix}/share/doc/man5 +chmod 644 $RPM_BUILD_ROOT/%{prefix}/share/doc/man5/* %clean # This step does not happen until *after* the %files packaging below diff --git a/perl-xCAT-2.0/xCAT/Schema.pm b/perl-xCAT-2.0/xCAT/Schema.pm index 0c267a4fb..d8214111d 100644 --- a/perl-xCAT-2.0/xCAT/Schema.pm +++ b/perl-xCAT-2.0/xCAT/Schema.pm @@ -369,30 +369,30 @@ site => { table_desc => 'Global settings for the whole cluster. This table is different from the other tables in that each attribute is just named in the key column, rather than having a separate column for each attribute.', descriptions => { key => "Name of the attribute. Valid values:\n". - "\t master (xCAT management node)\n". - "\t xcatconfdir (default /etc/xcat)\n". - "\t domain (DNS domain name used for the cluster)\n". - "\t installdir (directory that holds the node deployment pkgs)\n". - "\t xcatdport (port used by xcatd daemon for client/server communication)\n". - "\t xcatiport (port used by xcatd to receive install status updates from nodes)\n". - "\t timezone (e.g. America/New_York)\n". - "\t nameservers (list of DNS servers for the cluster)\n". - "\t rsh (path of remote shell command)\n". - "\t rcp (path of remote copy command)\n". - "\t blademaxp (max # of processes for blade hw ctrl)\n". - "\t ppcmaxp (max # of processes for PPC hw ctrl)\n". - "\t ipmimaxp\n". - "\t ipmitimeout\n". - "\t ipmiretries\n". - "\t ipmisdrcache\n". - "\t iscsidir\n". - "\t xcatservers (service nodes??)\n". - "\t dhcpinterfaces (network interfaces DHCP should listen on??)\n". - "\t forwarders (DNS forwarders??)\n". - "\t genpasswords (generate BMC passwords??)\n". - "\t defserialport (default if not specified in noderes table)\n". - "\t defserialspeed (default if not specified in nodehm table)\n". - "\t defserialflow (default if not specified in nodehm table)", + " master (xCAT management node)\n". + " xcatconfdir (default /etc/xcat)\n". + " domain (DNS domain name used for the cluster)\n". + " installdir (directory that holds the node deployment pkgs)\n". + " xcatdport (port used by xcatd daemon for client/server communication)\n". + " xcatiport (port used by xcatd to receive install status updates from nodes)\n". + " timezone (e.g. America/New_York)\n". + " nameservers (list of DNS servers for the cluster)\n". + " rsh (path of remote shell command)\n". + " rcp (path of remote copy command)\n". + " blademaxp (max # of processes for blade hw ctrl)\n". + " ppcmaxp (max # of processes for PPC hw ctrl)\n". + " ipmimaxp\n". + " ipmitimeout\n". + " ipmiretries\n". + " ipmisdrcache\n". + " iscsidir\n". + " xcatservers (service nodes??)\n". + " dhcpinterfaces (network interfaces DHCP should listen on??)\n". + " forwarders (DNS forwarders??)\n". + " genpasswords (generate BMC passwords??)\n". + " defserialport (default if not specified in noderes table)\n". + " defserialspeed (default if not specified in nodehm table)\n". + " defserialflow (default if not specified in nodehm table)", value => 'The value of the attribute specified in the "key" column.', comments => 'Any user-written notes.', disable => "Set to 'yes' or '1' to comment out this row.", diff --git a/xCAT-client-2.0/pods/man1/chtab.1.pod b/xCAT-client-2.0/pods/man1/chtab.1.pod deleted file mode 100644 index ee9de72cf..000000000 --- a/xCAT-client-2.0/pods/man1/chtab.1.pod +++ /dev/null @@ -1,71 +0,0 @@ -=head1 NAME - -B -To add, delete or update rows in the database tables. - -=head1 SYNOPSIS - -I - -I - -I - -I - -=head1 DESCRIPTION - - The chtab command adds or deletes or updates the attribute value in the input table.column for the input keyvalue. - - -=head1 OPTIONS - - -B<-h> Display usage message. - -B<-v> Command Version. - -B<-d> Delete option. - - - -=head1 RETURN VALUE - -0 The command completed successfully. - -1 An error has occurred. - -=head1 EXAMPLES - -1. To add a node=node1 to the nodelist table with groups=all: - -I - -2. To add a keyword (tftpdir) and value (/tftpboot) to the site table: - -I - - -3. To add node1 to the nodetype table with os=rhel5: - -I - - -4. To change node1 in nodetype table setting os=sles: - -I - -5. To delete node1 from nodetype table: - -I - - -=head1 FILES - -/opt/xcat/bin/chtab - - -=head1 NOTES - -This command is part of the xCAT software product. - - diff --git a/xCAT-client-2.0/pods/man1/nodestat.1.pod b/xCAT-client-2.0/pods/man1/nodestat.1.pod index 67cf25c6c..690ff0b44 100644 --- a/xCAT-client-2.0/pods/man1/nodestat.1.pod +++ b/xCAT-client-2.0/pods/man1/nodestat.1.pod @@ -11,7 +11,7 @@ B [I<-h>|I<--help>|I<-v>|I<--version>] =head1 B B is a small utility used to display the running status of a -single or range of nodes or groups. See L. +single or range of nodes or groups. See L. B will first check for pbs_mom, if that fails then B will check for snmpd, then ping. If ping fails, then B returns "nop- @@ -47,4 +47,4 @@ Egan Ford =head1 B B -L, L, L, L +L, L, L diff --git a/xCAT-client-2.0/pods/man1/prsync.1.pod b/xCAT-client-2.0/pods/man1/prsync.1.pod index 5d2a30e07..a7d657621 100644 --- a/xCAT-client-2.0/pods/man1/prsync.1.pod +++ b/xCAT-client-2.0/pods/man1/prsync.1.pod @@ -26,7 +26,7 @@ B is NOT multicast, but is parallel unicasts. =item B -rsync options. See L. +rsync options. See B. =item B @@ -38,7 +38,7 @@ A space delimited list of directories to rsync. =item B -A L and destination directory. The : is required. +A L and destination directory. The : is required. =item B<-h>|B<--help> @@ -71,4 +71,4 @@ Egan Ford =head1 B B -L, L, L, L +L, L, L, L diff --git a/xCAT-client-2.0/pods/man1/pscp.1.pod b/xCAT-client-2.0/pods/man1/pscp.1.pod index 3c85b1780..c289e3a96 100644 --- a/xCAT-client-2.0/pods/man1/pscp.1.pod +++ b/xCAT-client-2.0/pods/man1/pscp.1.pod @@ -40,7 +40,7 @@ A space delimited list of directories to copy. =item B -A L and destination directory. The : is required. +A L and destination directory. The : is required. =item B<-h>|B<--help> @@ -64,4 +64,4 @@ Egan Ford =head1 B B -L, L, L, L +L, L, L, L diff --git a/xCAT-client-2.0/pods/man1/psh.1.pod b/xCAT-client-2.0/pods/man1/psh.1.pod index 7cbcd166c..3720789c5 100644 --- a/xCAT-client-2.0/pods/man1/psh.1.pod +++ b/xCAT-client-2.0/pods/man1/psh.1.pod @@ -26,17 +26,17 @@ Issues the commands serially. =item B -See L. +See L. =item B -Run against nodes owned by "me" as listed by PBS's L +Run against nodes owned by "me" as listed by PBS's B command. =item B Run against nodes assigned to a PBS job as listed by PBS's -L command. +B command. =item B @@ -77,4 +77,4 @@ Egan Ford =head1 B B -L, L, L, L +L, L, L, L diff --git a/xCAT-client-2.0/pods/man1/rcons.1.pod b/xCAT-client-2.0/pods/man1/rcons.1.pod index 1fe271ea5..0c05c880f 100644 --- a/xCAT-client-2.0/pods/man1/rcons.1.pod +++ b/xCAT-client-2.0/pods/man1/rcons.1.pod @@ -30,7 +30,7 @@ Print version. =head1 B B table - -xCAT node hardware management table. See L for +xCAT node hardware management table. See B for further details. This is used to determine the console access method. @@ -45,4 +45,4 @@ Egan Ford =head1 B B -L, L, L +B, L, B diff --git a/xCAT-client-2.0/pods/man1/updte_SNimage.1.pod b/xCAT-client-2.0/pods/man1/updte_SNimage.1.pod index cfb54fae8..9699d8425 100644 --- a/xCAT-client-2.0/pods/man1/updte_SNimage.1.pod +++ b/xCAT-client-2.0/pods/man1/updte_SNimage.1.pod @@ -1,14 +1,14 @@ =head1 NAME - + B - Adds the needed Service Node configuration files to the install image. - + =head1 SYNOPSIS - + I -I +I -I +I =head1 DESCRIPTION @@ -22,7 +22,7 @@ B<-h |--help> Display usage message. B<-v |--version> Display xCAT version. -B<-n | --node> A remote host name or ip address that contains the install image to be updated. +B<-n | --node> A remote host name or ip address that contains the install image to be updated. B<-p |--path> Path to the install image. @@ -38,16 +38,16 @@ B<-p |--path> Path to the install image. 1. To update the image on the local host. -I - +I + 2. To update the image on a remote host. -I +I =head1 FILES - + $XCATROOT/bin/chdef (The XCATROOT environment variable is set when xCAT is installed. The @@ -57,8 +57,8 @@ default value is "/opt/xcat".) =head1 NOTES This command is part of the xCAT software product. -When going to a remote host, the command uses scp. It is best to have ssh keys setup so you will not be prompted for a password on each copy. +When going to a remote host, the command uses scp. It is best to have ssh keys setup so you will not be prompted for a password on each copy. + - diff --git a/xCAT-client-2.0/pods/man1/wcons.1.pod b/xCAT-client-2.0/pods/man1/wcons.1.pod index f0f50592a..0ad1b3996 100644 --- a/xCAT-client-2.0/pods/man1/wcons.1.pod +++ b/xCAT-client-2.0/pods/man1/wcons.1.pod @@ -73,7 +73,7 @@ Print version. =head1 B B table - -xCAT node hardware management table. See L for further details. This is used to determine the console access +xCAT node hardware management table. See B for further details. This is used to determine the console access method. =head1 B @@ -99,4 +99,4 @@ Egan Ford =head1 B B -L, L +L, L diff --git a/xCAT-client-2.0/pods/man1/wkill.1.pod b/xCAT-client-2.0/pods/man1/wkill.1.pod index 9af786e49..9268a3b95 100644 --- a/xCAT-client-2.0/pods/man1/wkill.1.pod +++ b/xCAT-client-2.0/pods/man1/wkill.1.pod @@ -16,7 +16,7 @@ range or nodes or groups. B was written because I'm too lazy to point and click off 64 windows. B will only kill windows on your display and for only the -L you specify. If no L is specified, then all +L you specify. If no L is specified, then all wcons windows on your $DISPLAY will be killed. =head1 B @@ -44,4 +44,4 @@ Egan Ford =head1 B B -L, L. +L, L. diff --git a/xCAT-client-2.0/pods/man1/xdsh.1.pod b/xCAT-client-2.0/pods/man1/xdsh.1.pod index e04cf6f08..542d1e3f8 100644 --- a/xCAT-client-2.0/pods/man1/xdsh.1.pod +++ b/xCAT-client-2.0/pods/man1/xdsh.1.pod @@ -420,6 +420,8 @@ Specifies the time, in seconds, to wait for output from each remote target. This variable is overridden by the B<-t> flag. +=back + =head1 B diff --git a/xCAT-client-2.0/pods/man1/xdshbak.1.pod b/xCAT-client-2.0/pods/man1/xdshbak.1.pod index f11ce32f7..28dc38844 100644 --- a/xCAT-client-2.0/pods/man1/xdshbak.1.pod +++ b/xCAT-client-2.0/pods/man1/xdshbak.1.pod @@ -83,6 +83,8 @@ more compact output, but xdshbak still sorts the output by node name for easier viewing. This option should not be used with B<-c>. +=back + =head1 B diff --git a/xCAT-client-2.0/pods/man8/chtab.8.pod b/xCAT-client-2.0/pods/man8/chtab.8.pod new file mode 100644 index 000000000..eac7c63e5 --- /dev/null +++ b/xCAT-client-2.0/pods/man8/chtab.8.pod @@ -0,0 +1,71 @@ +=head1 NAME + +B - Add, delete or update rows in the database tables. + +=head1 SYNOPSIS + +I + +I + +I + +I + +=head1 DESCRIPTION + + The chtab command adds or deletes or updates the attribute value in the input table.column for the input keyvalue. + + +=head1 OPTIONS + + +B<-h> Display usage message. + +B<-v> Command Version. + +B<-d> Delete option. + + + +=head1 RETURN VALUE + +0 The command completed successfully. + +1 An error has occurred. + +=head1 EXAMPLES + +1. To add a node=node1 to the nodelist table with groups=all: + +I + +2. To add a keyword (tftpdir) and value (/tftpboot) to the site table: + +I + + +3. To add node1 to the nodetype table with os=rhel5: + +I + + +4. To change node1 in nodetype table setting os=sles: + +I + +5. To delete node1 from nodetype table: + +I + + +=head1 FILES + +/opt/xcat/bin/chtab + + +=head1 NOTES + +This command is part of the xCAT software product. + + diff --git a/xCAT-client-2.0/pods/man1/makedhcp.1.pod b/xCAT-client-2.0/pods/man8/makedhcp.8.pod similarity index 100% rename from xCAT-client-2.0/pods/man1/makedhcp.1.pod rename to xCAT-client-2.0/pods/man8/makedhcp.8.pod diff --git a/xCAT-client-2.0/pods/man1/nodeadd.1.pod b/xCAT-client-2.0/pods/man8/nodeadd.8.pod similarity index 100% rename from xCAT-client-2.0/pods/man1/nodeadd.1.pod rename to xCAT-client-2.0/pods/man8/nodeadd.8.pod diff --git a/xCAT-client-2.0/pods/man1/nodeset.1.pod b/xCAT-client-2.0/pods/man8/nodeset.8.pod similarity index 82% rename from xCAT-client-2.0/pods/man1/nodeset.1.pod rename to xCAT-client-2.0/pods/man8/nodeset.8.pod index 8fcab1211..48701f168 100644 --- a/xCAT-client-2.0/pods/man1/nodeset.1.pod +++ b/xCAT-client-2.0/pods/man8/nodeset.8.pod @@ -20,7 +20,7 @@ B [I<-h>|I<--help>|I<-v>|I<--version>] B sets the next cold or warm boot state for a single or range of nodes or groups. This tells xCAT what you want to happen the next time the -nodes are booted up. See L. B accomplishes this by +nodes are booted up. See L. B accomplishes this by changing the network boot files. Each xCAT node always boots from the network and downloads a boot file with instructions on what action to take next. @@ -29,7 +29,7 @@ B only supports PXELINUX, Etherboot, Etherboot/NBGRUB, and ELILO as network boot loaders. B calls B, B, B B, and B to perform the updates. -Assume that /tftpboot is the root for tftpd (set in L). +Assume that /tftpboot is the root for tftpd (set in B). B makes changes to /tftpboot/pxelinux.0/{node hex ip} @@ -50,10 +50,10 @@ installation process remotely to set the boot state back to "boot". When B is called to set a node for an installation state, a NODE- TYPE-RESOURCE.BOOTTYPE template must exist in /tftpboot/xcat (or the -appropriate directory as defined in L), where NODETYPE is -defined per node in L, RESOURCE is defined per node or -group in L, and BOOTTYPE is defined per node in -L. +appropriate directory as defined in B), where NODETYPE is +defined per node in B, RESOURCE is defined per node or +group in B, and BOOTTYPE is defined per node in +B. =head1 B @@ -80,7 +80,7 @@ Instruct node to boot from network image stage2. This involves TFTP downloading a special prebuilt kernel, initrd, and kernel options used for MAC address collection. For a new node this is the default action and cannot be changed until a node entry -exists in L. It is not necessary to explicitly set +exists in B. It is not necessary to explicitly set stage2, unless it is used for testing and development purposes. =item B @@ -102,7 +102,7 @@ tainance shell. Only available for IA64 systems. Instruct node to boot from network into clone mode. In clone mode the node will poll the management node for nodes in clone- server mode, once a clone lock is established the clone node -clones the cloneserver node. Usually called from L. +clones the cloneserver node. Usually called from B. =item B @@ -119,7 +119,7 @@ create partition images. =item B=I Instruct node to boot from network load DOS and flash I. -Usually called from L. +Usually called from B. =item B<-h>|B<--help> @@ -135,27 +135,27 @@ Print version. =head1 B B table - -xCAT node hardware management file. See L for fur- +xCAT node hardware management file. See B for fur- ther details. This is used to determine the network boot type: PXE, Etherboot, ELILO, or NA. B table - -xCAT node resources file. See L for further +xCAT node resources file. See B for further details. This is used to determine the node's resource group. B table - -xCAT node installation type file. See L for fur- +xCAT node installation type file. See B for fur- ther details. This is used to determine the node installation image type. B table - -xCAT main configuration file. See L for further +xCAT main configuration file. See B for further details. This is used to determine the location of the TFTP root directory and the TFTP xCAT subdirectory. /tftpboot and /tftpboot/xcat is the default. B file - -xCAT dhcpd configuration file. See L for further +xCAT dhcpd configuration file. See B for further details. This is used by B to determine if a node will only boot stage2 because no statically assigned IP exists for that node. Also used by nodeset.eb to set the boot state for @@ -178,5 +178,5 @@ Egan Ford =head1 B B -L, L, L, L, -L, L +L, L, L, B, +B, L diff --git a/xCAT-client-2.0/pods/man1/tabdump.1.pod b/xCAT-client-2.0/pods/man8/tabdump.8.pod similarity index 100% rename from xCAT-client-2.0/pods/man1/tabdump.1.pod rename to xCAT-client-2.0/pods/man8/tabdump.8.pod diff --git a/xCAT-client-2.0/pods/man1/tabedit.1.pod b/xCAT-client-2.0/pods/man8/tabedit.8.pod similarity index 100% rename from xCAT-client-2.0/pods/man1/tabedit.1.pod rename to xCAT-client-2.0/pods/man8/tabedit.8.pod diff --git a/xCAT-client-2.0/pods/man1/tabrestore.1.pod b/xCAT-client-2.0/pods/man8/tabrestore.8.pod similarity index 100% rename from xCAT-client-2.0/pods/man1/tabrestore.1.pod rename to xCAT-client-2.0/pods/man8/tabrestore.8.pod diff --git a/xCAT-client-2.0/share/doc/index.html b/xCAT-client-2.0/share/doc/index.html new file mode 100644 index 000000000..4eca5a318 --- /dev/null +++ b/xCAT-client-2.0/share/doc/index.html @@ -0,0 +1,30 @@ + + + + + +xCAT 2 + + +

xCAT 2

+ + +

xCAT 2 on the Internet

+ + + \ No newline at end of file diff --git a/xCAT-client-2.0/xCAT-client.spec b/xCAT-client-2.0/xCAT-client.spec index 43abdf21a..b7154d451 100644 --- a/xCAT-client-2.0/xCAT-client.spec +++ b/xCAT-client-2.0/xCAT-client.spec @@ -29,11 +29,14 @@ xCAT-client provides the fundamental xCAT commands (chtab, chnode, rpower, etc) # as it is in svn. # Convert pods to man pages, e.g.: pod2man pods/man1/tabdump.1.pod share/man/man1/tabdump.1 -for i in pods/*/*.pod; do - man="share/man${i#pods}" # the substitute form is not supported on aix: ${i/pods/share\/man} - mkdir -p ${man%/*} - pod2man $i ${man%.pod} -done +# for i in pods/*/*.pod; do +# man="share/man${i#pods}" # the substitute form is not supported on aix: ${i/pods/share\/man} +# mkdir -p ${man%/*} +# pod2man $i ${man%.pod} +# done + +# Convert pods to man pages and html pages +./xpod2man %install # The install phase puts all of the files in the paths they should be in when the rpm is @@ -49,13 +52,17 @@ mkdir -p $RPM_BUILD_ROOT/%{prefix}/share/man/man3 mkdir -p $RPM_BUILD_ROOT/%{prefix}/share/man/man5 mkdir -p $RPM_BUILD_ROOT/%{prefix}/share/man/man8 mkdir -p $RPM_BUILD_ROOT/%{prefix}/share/doc/packages/xCAT-client +mkdir -p $RPM_BUILD_ROOT/%{prefix}/share/doc/man1 +mkdir -p $RPM_BUILD_ROOT/%{prefix}/share/doc/man3 +mkdir -p $RPM_BUILD_ROOT/%{prefix}/share/doc/man5 +mkdir -p $RPM_BUILD_ROOT/%{prefix}/share/doc/man8 cp bin/* $RPM_BUILD_ROOT/%{prefix}/bin chmod 755 $RPM_BUILD_ROOT/%{prefix}/bin/* cp sbin/* $RPM_BUILD_ROOT/%{prefix}/sbin chmod 755 $RPM_BUILD_ROOT/%{prefix}/sbin/* -# Most of these were built dynamically in the build phase +# These were built dynamically in the build phase cp share/man/man1/* $RPM_BUILD_ROOT/%{prefix}/share/man/man1 chmod 444 $RPM_BUILD_ROOT/%{prefix}/share/man/man1/* cp share/man/man3/* $RPM_BUILD_ROOT/%{prefix}/share/man/man3 @@ -65,14 +72,24 @@ chmod 444 $RPM_BUILD_ROOT/%{prefix}/share/man/man5/* cp share/man/man8/* $RPM_BUILD_ROOT/%{prefix}/share/man/man8 chmod 444 $RPM_BUILD_ROOT/%{prefix}/share/man/man8/* -%ifos linux -cp share/doc/xCAT2.0.odt $RPM_BUILD_ROOT/%{prefix}/share/doc -cp share/doc/xCAT2.0.pdf $RPM_BUILD_ROOT/%{prefix}/share/doc -%else -cp share/doc/xCAT2onAIX.odt $RPM_BUILD_ROOT/%{prefix}/share/doc -cp share/doc/xCAT2onAIX.pdf $RPM_BUILD_ROOT/%{prefix}/share/doc -%endif -chmod 644 $RPM_BUILD_ROOT/%{prefix}/share/doc/* +# %ifos linux +# cp share/doc/xCAT2.0.odt $RPM_BUILD_ROOT/%{prefix}/share/doc +# cp share/doc/xCAT2.0.pdf $RPM_BUILD_ROOT/%{prefix}/share/doc +# %else +# cp share/doc/xCAT2onAIX.odt $RPM_BUILD_ROOT/%{prefix}/share/doc +# cp share/doc/xCAT2onAIX.pdf $RPM_BUILD_ROOT/%{prefix}/share/doc +# %endif +cp -r share/doc/* $RPM_BUILD_ROOT/%{prefix}/share/doc +chmod 755 $RPM_BUILD_ROOT/%{prefix}/share/doc/* +# These were built dynamically during the build phase +# cp share/doc/man1/* $RPM_BUILD_ROOT/%{prefix}/share/doc/man1 +chmod 644 $RPM_BUILD_ROOT/%{prefix}/share/doc/man1/* +# cp share/doc/man3/* $RPM_BUILD_ROOT/%{prefix}/share/doc/man3 +chmod 644 $RPM_BUILD_ROOT/%{prefix}/share/doc/man3/* +# cp share/doc/man5/* $RPM_BUILD_ROOT/%{prefix}/share/doc/man5 +chmod 644 $RPM_BUILD_ROOT/%{prefix}/share/doc/man5/* +# cp share/doc/man8/* $RPM_BUILD_ROOT/%{prefix}/share/doc/man8 +chmod 644 $RPM_BUILD_ROOT/%{prefix}/share/doc/man8/* cp LICENSE.html $RPM_BUILD_ROOT/%{prefix}/share/doc/packages/xCAT-client chmod 644 $RPM_BUILD_ROOT/%{prefix}/share/doc/packages/xCAT-client/* diff --git a/xCAT-client-2.0/xpod2man b/xCAT-client-2.0/xpod2man new file mode 100644 index 000000000..cc716346c --- /dev/null +++ b/xCAT-client-2.0/xpod2man @@ -0,0 +1,167 @@ +#!/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 @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); +} + +#TODO: 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 a minimal one that will satisfy pod2html +# keep track of all dummy pods created +# convert all original pod pages +# remove the dummy 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"; +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"; } + convertpod2html($podfile, $htmlfile, $poddir, $htmldir); +} + +exit; + + +# 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 - 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 B for +descriptions of every table in the database. + +=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. + +=over 12 +EOS1 + +# extract the summary for each cmd from its man page +foreach my $manpage (@_) { + my ($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 = ; + my $wholemanpage = join('', @contents); + close(MANPAGE); + # This regex matches: optional space, =head1, space, title, space, cmd, space, description, newline + my ($cmd, $description) = $wholemanpage =~ /^\s*=head1\s+\S+\s+(\S+)\s+(.+?)\n/si; + if (!defined($cmd)) { print "Warning: $manpage is not in a recognized structure. It will be ignored.\n"; next; } + if (!defined($description)) { print "Warning: $manpage does not have a description for $cmd. It will be ignored.\n"; next; } + $cmd =~ s/^.<(.+)>$/$1/; # if the cmd name has pod formatting around it, strip it off + $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"; +} + + print FILE <<"EOS3"; + +=back +EOS3 + + close FILE; +} + + +# Create the html page for one pod. +sub convertpod2html { + my ($podfile, $htmlfile, $poddir, $htmldir) = @_; + + #TODO: use --css= and --title= to make the pages look better + pod2html($podfile, + "--outfile=$htmlfile", + "--podpath=man1:man3:man5:man8", + "--podroot=$poddir", + "--htmldir=$htmldir", + "--recurse", + "--cachedir=/tmp", + ); + +} + + +# 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); +} diff --git a/xCAT-web/etc/apache2/conf.d/xcat-web.conf b/xCAT-web/etc/apache2/conf.d/xcat-web.conf index 54f17aaf0..9e47d5e60 100644 --- a/xCAT-web/etc/apache2/conf.d/xcat-web.conf +++ b/xCAT-web/etc/apache2/conf.d/xcat-web.conf @@ -1,4 +1,4 @@ -Alias /xcat "/opt/xcat/web" +Alias /xcat-web "/opt/xcat/web" Options FollowSymLinks AllowOverride None diff --git a/xCAT/xcat.conf b/xCAT/xcat.conf index f2337580f..e7699f29f 100644 --- a/xCAT/xcat.conf +++ b/xCAT/xcat.conf @@ -1,5 +1,5 @@ # -# This configuration file allows the manual to be accessed at +# This configuration file allows the manual to be accessed at # http://localhost/manual/ # AliasMatch ^/install/(.*)$ "/install/$1" @@ -17,3 +17,11 @@ AliasMatch ^/tftpboot/(.*)$ "/tftpboot/$1" Order allow,deny Allow from all + +Alias /xcat-doc "/opt/xcat/share/doc" + + Options Indexes + AllowOverride None + Order allow,deny + Allow from all +