Reopening:
1. This feature would really simplify maintaining manual pages.
2. there are fair number of packages whose upstream is not (for various
reasons) shipping manual pages.
3. Taking gover maintenance of a Debian package that contains raw
debain/*.1 manual pages is not really comfortable.
4. contributing patches to manual pages (in docbook or raw *.1) is not
easy. There is a steep learning curve to understand nroff format whereas
for POD, the learning curve is easier. Plus editing POD pages for patches
is easier.
| 1. There are plenty of other formats, such as docbook that can be used.
See bug thread: none are good, or easy to use, hardly maintenance friendly.
POD is native to Perl, and it would be natural to debhelper ecosystem. It
requires no extra dependencies; unlike docbook. Perl is always there in
Debian.
| (Especially when you consider the aggregate complexity of various
| options that can be passed when building them. For example, pod2man
| needs --release and --section and often --center.)
Debhelper could simply provide defaults and read further information
embedded from *.pod files. something like this:
The debhelper can read and install manual pages in POD format stored in
debian/*.pod. Further options for page generataion can be be specified
at the beginning of file, inside Perl comments. These options are
passed verbatim to pod2man(1) program. each <option name> corresponds
to --<option> in pod2man(1). Further options that do not take arguments
can be specified in "pod2man_options". The generic syntax is:
# pod2man_<option name> = VALUE
Whitespaces around equal(=) sign and at EOL are ignored.
An example (these are the defaults):
# pod2man_center = User Command
# pod2man_date = <ISO 8601 date: YYYY-MM-DD>
# pod2man_name = <file name without suffixes>
# pod2man_section = <the <section> part from file name>
# pod2man_options = --utf8
The file name format for POD files is:
<name>.<section>.pod
Examples:
program.1.pod
program-config.5.pod
If you can point me where to start at debhelper code, I might be able to
help to get this implemented.
Jari
--
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
