view release on metacpan or  search on metacpan

lib/App/ClusterSSH/Getopt.pm  view on Meta::CPAN

# generate valid POD from all the options and send to STDOUT
# so build process can create pod files for the distribution
sub _generate_pod {
    my ($self) = @_;

    output $/ , "=pod";
    output '=head1 ',    $self->loc('NAME');
    output "$Script - ", $self->loc("Cluster administration tool");
    output '=head1 ',    $self->loc('VERSION');
    output $self->loc( "This documentation is for version: [_1]",
        $self->parent->VERSION );
    output '=head1 ', $self->loc('SYNOPSIS');

    # build the synopsis
    print "$Script ";
    foreach my $longopt ( sort keys( %{ $self->{command_options} } ) ) {
        next if ( $self->{command_options}->{$longopt}->{hidden} );

        print '['
            . (    $self->{command_options}->{$longopt}->{option_short}
                || $self->{command_options}->{$longopt}->{option_long} )
            . '] ';
    }
    print $/, $/;

    output '=head1 ', $self->loc('DESCRIPTION');
    output $self->loc(
        q{The command opens an administration console and an xterm to all specified hosts.  Any text typed into the administration console is replicated to all windows.  All windows may also be typed into directly.

This tool is intended for (but not limited to) cluster administration where the same configuration or commands must be run on each node within the cluster.  Performing these commands all at once via this tool ensures all nodes are kept in sync.

Connections are opened using [_1] which must be correctly installed and configured.

Extra caution should be taken when editing files as lines may not necessarily be in the same order;  assuming line 5 is the same across all servers and modifying that is dangerous.  It's better to search for the specific line to be changed and double...
        $self->parent->config->{comms}
    );

    output '=head2 ', $self->loc('Further Notes');
    output $self->loc('Please also see "KNOWN BUGS".');
    output '=over';
    output '=item *';
    output $self->loc(
        q{The dotted line on any sub-menu is a tear-off, i.e. click on it and the sub-menu is turned into its own window.}
    );
    output '=item *';
    output $self->loc(
        q{Unchecking a hostname on the Hosts sub-menu will unplug the host from the cluster control window, so any text typed into the console is not sent to that host.  Re-selecting it will plug it back in.}
    );
    output '=item *';
    output $self->loc(
        q{If your window manager menu bars are obscured by terminal windows see the C<screen_reserve_XXXXX> options in the [_1] file (see [_2]).},
        'F<$HOME/.clusterssh/config>', 'L</"FILES">'
    );
    output '=item *';
    output $self->loc(
        q{If the terminals overlap too much see the C<terminal_reserve_XXXXX> options in the [_1] file (see [_2]).},
        'F<$HOME/.clusterssh/config>', 'L</"FILES">'
    );
    output '=item *';
    output $self->loc(
        q{When using ClusterSSH on a large number of systems to connect to a single system using an SSH utility (e.g. you issue a command to to copy a file using scp from the remote computers to a single host) and when these connections require authe...
        'F<~/.ssh/authorized_keys>'
    );
    output '=item *';
    output $self->loc(
        q{If client windows fail to open, try running:

[_1]

This will test the mechanisms used to open windows to hosts.  This could be due to either the [_2] terminal option which enables [_3] (some terminals do not require this option, other terminals have another method for enabling it - see your terminal ...
        "C<< $Script -e {single host name} >>", 'C<-xrm>',
        'C<AllowSendEvents>',
        'C<' . $self->parent->config->{comms} . '>',
    );
    output '=back';

    output '=head1 ' . $self->loc('OPTIONS');
    output $self->loc(
        "Some of these options may also be defined within the configuration file.  Default options are shown as appropriate."
    );

    output '=over';
    foreach my $longopt ( sort keys( %{ $self->{command_options} } ) ) {
        next if ( $self->{command_options}->{$longopt}->{hidden} );

        output '=item ', $self->{command_options}->{$longopt}->{option_desc};
        output $self->{command_options}->{$longopt}->{help} || 'No help';

        if ( $self->{command_options}->{$longopt}->{default} ) {
            output $self->loc('Default'), ': ',
                $self->{command_options}->{$longopt}->{default}, $/, $/;
        }
    }
    output '=back';

    output '=head1 ' . $self->loc('ARGUMENTS');
    output $self->loc('The following arguments are supported:');
    output '=over';
    output '=item [user@]<hostname>[:port] ...';
    output $self->loc(
        'Open an xterm to the given hostname and connect to the administration console.  The optional port number can be used if the server is not listening on the standard port.'
    );
    output '=item <tag> ...';
    output $self->loc(
        'Open a series of xterms defined by <tag> in one of the supplementary configuration files (see [_1]).

B<Note:> specifying a username on a cluster tag will override any usernames defined in the cluster.',
        'L</"FILES">'
    );
    output '=back';

    output '=head1 ' . $self->loc('KEY SHORTCUTS');
    output $self->loc(
        'The following key shortcuts are available within the console window, and all of them may be changed via the configuration files.'
    );
    output '=over';
    output '=item  ', $self->parent->config->{key_addhost};
    output $self->loc(
        q{Open the 'Add Host(s) or Cluster(s)' dialogue box.  Multiple host or cluster names can be entered, separated by spaces.}
    );
    output '=item ', $self->parent->config->{key_clientname};