| 1 |
Pod::Thread 3.01 |
| 2 |
(Format POD source into thread, an HTML macro language) |
| 3 |
Maintained by Russ Allbery <[email protected]> |
| 4 |
|
| 5 |
Copyright 2002, 2008-2009, 2013, 2021 Russ Allbery <[email protected]>. This |
| 6 |
software is distributed under a BSD-style license. Please see the |
| 7 |
section LICENSE below for more information. |
| 8 |
|
| 9 |
BLURB |
| 10 |
|
| 11 |
Pod::Thread translates POD source into thread, a macro language |
| 12 |
processed by DocKnot. It supports optionally adding a table of contents |
| 13 |
and a navigation bar to the genenerated file. This package also |
| 14 |
includes the pod2thread driver script for easy command-line access to |
| 15 |
the converter. |
| 16 |
|
| 17 |
DESCRIPTION |
| 18 |
|
| 19 |
This package contains a module to translate POD into thread, an HTML |
| 20 |
macro language. As such, it is primarily intended to support DocKnot |
| 21 |
[1], the static site generator that converts thread into HTML. |
| 22 |
Pod::Thread provides the POD formatting for DocKnot. |
| 23 |
|
| 24 |
[1] https://www.eyrie.org/~eagle/software/docknot/ |
| 25 |
|
| 26 |
DocKnot and this module were written for my personal needs and may not |
| 27 |
be suitable for more general use. |
| 28 |
|
| 29 |
The conversion done by this module is mostly straightforward. The only |
| 30 |
notable parts are the optional generation of a table of contents or a |
| 31 |
navigation bar at the top of the generated file. |
| 32 |
|
| 33 |
REQUIREMENTS |
| 34 |
|
| 35 |
Perl 5.24 or later. As mentioned above, it's also not particularly |
| 36 |
useful without DocKnot. |
| 37 |
|
| 38 |
BUILDING AND INSTALLATION |
| 39 |
|
| 40 |
Pod::Thread uses Module::Build and can be installed using the same |
| 41 |
process as any other Module::Build module: |
| 42 |
|
| 43 |
perl Build.PL |
| 44 |
./Build |
| 45 |
./Build install |
| 46 |
|
| 47 |
You will have to run the last command as root unless you're installing |
| 48 |
into a local Perl module tree in your home directory. |
| 49 |
|
| 50 |
TESTING |
| 51 |
|
| 52 |
Pod::Thread comes with a test suite, which you can run after building |
| 53 |
with: |
| 54 |
|
| 55 |
./Build test |
| 56 |
|
| 57 |
If a test fails, you can run a single test with verbose output via: |
| 58 |
|
| 59 |
./Build test --test_files <path-to-test> |
| 60 |
|
| 61 |
Perl6::Slurp is required by the test suite. The following additional |
| 62 |
Perl modules will be used by the test suite if present: |
| 63 |
|
| 64 |
* Devel::Cover |
| 65 |
* Perl::Critic::Freenode |
| 66 |
* Test::CPAN::Changes (part of CPAN-Changes) |
| 67 |
* Test::MinimumVersion |
| 68 |
* Test::Perl::Critic |
| 69 |
* Test::Pod |
| 70 |
* Test::Spelling |
| 71 |
* Test::Strict |
| 72 |
* Test::Synopsis |
| 73 |
|
| 74 |
All are available on CPAN. Those tests will be skipped if the modules |
| 75 |
are not available. |
| 76 |
|
| 77 |
To enable tests that don't detect functionality problems but are used to |
| 78 |
sanity-check the release, set the environment variable RELEASE_TESTING |
| 79 |
to a true value. To enable tests that may be sensitive to the local |
| 80 |
environment or that produce a lot of false positives without uncovering |
| 81 |
many problems, set the environment variable AUTHOR_TESTING to a true |
| 82 |
value. |
| 83 |
|
| 84 |
SUPPORT |
| 85 |
|
| 86 |
The Pod::Thread web page at: |
| 87 |
|
| 88 |
https://www.eyrie.org/~eagle/software/pod-thread/ |
| 89 |
|
| 90 |
will always have the current version of this package, the current |
| 91 |
documentation, and pointers to any additional resources. |
| 92 |
|
| 93 |
For bug tracking, use the issue tracker on GitHub: |
| 94 |
|
| 95 |
https://github.com/rra/pod-thread/issues |
| 96 |
|
| 97 |
However, please be aware that I tend to be extremely busy and work |
| 98 |
projects often take priority. I'll save your report and get to it as |
| 99 |
soon as I can, but it may take me a couple of months. |
| 100 |
|
| 101 |
SOURCE REPOSITORY |
| 102 |
|
| 103 |
Pod::Thread is maintained using Git. You can access the current source |
| 104 |
on GitHub at: |
| 105 |
|
| 106 |
https://github.com/rra/pod-thread |
| 107 |
|
| 108 |
or by cloning the repository at: |
| 109 |
|
| 110 |
https://git.eyrie.org/web/pod-thread.git |
| 111 |
|
| 112 |
or view the repository via the web at: |
| 113 |
|
| 114 |
https://git.eyrie.org/?p=web/pod-thread.git |
| 115 |
|
| 116 |
The eyrie.org repository is the canonical one, maintained by the author, |
| 117 |
but using GitHub is probably more convenient for most purposes. Pull |
| 118 |
requests are gratefully reviewed and normally accepted. |
| 119 |
|
| 120 |
LICENSE |
| 121 |
|
| 122 |
The Pod::Thread package as a whole is covered by the following copyright |
| 123 |
statement and license: |
| 124 |
|
| 125 |
Copyright 2002, 2008-2009, 2013, 2021 Russ Allbery <[email protected]> |
| 126 |
|
| 127 |
Permission is hereby granted, free of charge, to any person obtaining |
| 128 |
a copy of this software and associated documentation files (the |
| 129 |
"Software"), to deal in the Software without restriction, including |
| 130 |
without limitation the rights to use, copy, modify, merge, publish, |
| 131 |
distribute, sublicense, and/or sell copies of the Software, and to |
| 132 |
permit persons to whom the Software is furnished to do so, subject to |
| 133 |
the following conditions: |
| 134 |
|
| 135 |
The above copyright notice and this permission notice shall be |
| 136 |
included in all copies or substantial portions of the Software. |
| 137 |
|
| 138 |
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, |
| 139 |
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF |
| 140 |
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. |
| 141 |
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY |
| 142 |
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, |
| 143 |
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE |
| 144 |
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| 145 |
|
| 146 |
Some files in this distribution are individually released under |
| 147 |
different licenses, all of which are compatible with the above general |
| 148 |
package license but which may require preservation of additional |
| 149 |
notices. All required notices, and detailed information about the |
| 150 |
licensing of each file, are recorded in the LICENSE file. |
| 151 |
|
| 152 |
Files covered by a license with an assigned SPDX License Identifier |
| 153 |
include SPDX-License-Identifier tags to enable automated processing of |
| 154 |
license information. See https://spdx.org/licenses/ for more |
| 155 |
information. |
| 156 |
|
| 157 |
For any copyright range specified by files in this package as YYYY-ZZZZ, |
| 158 |
the range specifies every single year in that closed interval. |