| 1 |
#!perl |
| 2 |
# |
| 3 |
# Convert POD data to the HTML macro language thread. |
| 4 |
# |
| 5 |
# SPDX-License-Identifier: MIT |
| 6 |
|
| 7 |
use 5.024; |
| 8 |
use autodie; |
| 9 |
use warnings; |
| 10 |
|
| 11 |
use Getopt::Long qw(GetOptions); |
| 12 |
use Pod::Thread (); |
| 13 |
use Pod::Usage qw(pod2usage); |
| 14 |
|
| 15 |
# Insert -- into @ARGV before any single dash argument to hide it from |
| 16 |
# Getopt::Long; we want to interpret it as meaning stdin. |
| 17 |
my $stdin; |
| 18 |
local @ARGV = map { $_ eq q{-} && !$stdin++ ? (q{--}, $_) : $_ } @ARGV; |
| 19 |
|
| 20 |
# Parse our options. |
| 21 |
my @options = qw(contents|c help|h navbar|n style|s=s title|t=s); |
| 22 |
my %options; |
| 23 |
Getopt::Long::config('bundling'); |
| 24 |
GetOptions(\%options, @options) or exit 1; |
| 25 |
if ($options{help}) { |
| 26 |
pod2usage(1); |
| 27 |
} |
| 28 |
|
| 29 |
# Initialize and run the formatter. |
| 30 |
my $parser = Pod::Thread->new(%options); |
| 31 |
$parser->parse_from_file(@ARGV); |
| 32 |
|
| 33 |
__END__ |
| 34 |
|
| 35 |
=for stopwords |
| 36 |
Allbery STDIN STDOUT -chn --navbar subclasses MERCHANTABILITY NONINFRINGEMENT |
| 37 |
sublicense |
| 38 |
|
| 39 |
=head1 NAME |
| 40 |
|
| 41 |
pod2thread - Convert POD data to the HTML macro language thread. |
| 42 |
|
| 43 |
=head1 SYNOPSIS |
| 44 |
|
| 45 |
B<pod2thread> [B<-chn>] [B<-s> I<style>] [B<-t> I<title>] |
| 46 |
[I<input> [I<output>]] |
| 47 |
|
| 48 |
=head1 DESCRIPTION |
| 49 |
|
| 50 |
B<pod2thread> is a front-end for L<Pod::Thread>. It uses that module to |
| 51 |
generate thread source from POD source. |
| 52 |
|
| 53 |
I<input> is the file to read for POD source (the POD can be embedded in |
| 54 |
code). If I<input> isn't given, it defaults to STDIN. I<output>, if given, |
| 55 |
is the file to which to write the thread output. If I<output> isn't given, |
| 56 |
the output is written to STDOUT. |
| 57 |
|
| 58 |
=head1 OPTIONS |
| 59 |
|
| 60 |
=over 4 |
| 61 |
|
| 62 |
=item B<-c>, B<--contents> |
| 63 |
|
| 64 |
Generate a table of contents as the first section of the resulting thread |
| 65 |
file, with links to each top-level heading. |
| 66 |
|
| 67 |
=item B<-n>, B<--navbar> |
| 68 |
|
| 69 |
Generate a navigation bar at the top of the resulting thread file, with |
| 70 |
links to each top-level heading. |
| 71 |
|
| 72 |
=item B<-h>, B<--help> |
| 73 |
|
| 74 |
Print out usage information and exit. |
| 75 |
|
| 76 |
=item B<-s> I<style>, B<--style>=I<style> |
| 77 |
|
| 78 |
In the generated thread source, include a reference to the style sheet |
| 79 |
I<style>. If this option is not given, no style sheet reference will be |
| 80 |
included. |
| 81 |
|
| 82 |
=item B<-t> I<title>, B<--title>=I<title> |
| 83 |
|
| 84 |
Use I<title> as the title of the page rather than looking for a NAME section |
| 85 |
in the POD document. |
| 86 |
|
| 87 |
=back |
| 88 |
|
| 89 |
=head1 DIAGNOSTICS |
| 90 |
|
| 91 |
If B<pod2thread> fails with errors, see L<Pod::Thread> and L<Pod::Simple> |
| 92 |
for information about what those errors might mean. Internally, it can also |
| 93 |
produce the following diagnostic: |
| 94 |
|
| 95 |
=over 4 |
| 96 |
|
| 97 |
=item Unknown option: %s |
| 98 |
|
| 99 |
(F) An unknown command line option was given. |
| 100 |
|
| 101 |
=back |
| 102 |
|
| 103 |
In addition, other L<Getopt::Long> error messages may result from invalid |
| 104 |
command-line options. |
| 105 |
|
| 106 |
=head1 AUTHOR |
| 107 |
|
| 108 |
Russ Allbery <[email protected]> |
| 109 |
|
| 110 |
=head1 COPYRIGHT AND LICENSE |
| 111 |
|
| 112 |
Copyright 2002, 2013, 2021 Russ Allbery <[email protected]> |
| 113 |
|
| 114 |
Permission is hereby granted, free of charge, to any person obtaining a copy |
| 115 |
of this software and associated documentation files (the "Software"), to deal |
| 116 |
in the Software without restriction, including without limitation the rights |
| 117 |
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
| 118 |
copies of the Software, and to permit persons to whom the Software is |
| 119 |
furnished to do so, subject to the following conditions: |
| 120 |
|
| 121 |
The above copyright notice and this permission notice shall be included in all |
| 122 |
copies or substantial portions of the Software. |
| 123 |
|
| 124 |
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 125 |
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 126 |
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
| 127 |
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 128 |
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| 129 |
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE |
| 130 |
SOFTWARE. |
| 131 |
|
| 132 |
=head1 SEE ALSO |
| 133 |
|
| 134 |
L<Pod::Simple>, L<Pod::Thread> |
| 135 |
|
| 136 |
This program is part of the Pod-Thread distribution. The current version of |
| 137 |
Pod-Thread is available from CPAN, or directly from its web site at |
| 138 |
L<https://www.eyrie.org/~eagle/software/pod-thread/>. |
| 139 |
|
| 140 |
=cut |
| 141 |
|
| 142 |
# Local Variables: |
| 143 |
# copyright-at-end-flag: t |
| 144 |
# End: |