Debian Codegraph @

README

raw
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.