/usr/share/doc/lire/dev-manual/ch21s02.html is in lire-devel-doc 2:2.1.1-2.1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Perl's Plain Old Documentation: maintaining manpages</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="Lire Developer's Manual"><link rel="up" href="ch21.html" title="Chapter 21. Writing Documentation"><link rel="prev" href="ch21.html" title="Chapter 21. Writing Documentation"><link rel="next" href="ch21s03.html" title="Docbook XML: Reference Books and Extensive User Manuals"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Perl's Plain Old Documentation: maintaining manpages</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch21.html">Prev</a> </td><th width="60%" align="center">Chapter 21. Writing Documentation</th><td width="20%" align="right"> <a accesskey="n" href="ch21s03.html">Next</a></td></tr></table><hr></div><div class="section" title="Perl's Plain Old Documentation: maintaining manpages"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect:manpages-pod"></a>Perl's Plain Old Documentation: maintaining manpages</h2></div></div></div><p>We use Perl's pod (plain old documentation) for manpages. Every
file installed with <span class="application">Lire</span> in <code class="filename">/usr/bin/</code> must have a manpage. Every file
installed in <code class="filename">/usr/share/perl5/Lire/</code> and <code class="filename">/usr/lib/lire/</code> should have a manpage. It
would be nice if the files in <code class="filename">/etc/lire/</code> were documented in manpages
too. And perhaps for some files in <code class="filename">/usr/share/lire/xml/</code>, <code class="filename">/usr/share/lire/reports/</code>, <code class="filename">/usr/share/lire/filters/</code> and <code class="filename">/usr/share/lire/schemas/</code> manpages could be
useful.</p><p>Since the files in <code class="filename">/usr/bin/</code> are commands, ran by <span class="application">Lire</span>
users, the manpages describing these should focus on the user
perspective. Describing the inner workings and implementations of the
commands is less important than describing why someone would want to
run the specific command. If there's need to make some remarks on the
internals of these scripts, a section called DEVELOPERS could be added
to the manpage. The perl modules installed in <code class="filename">/usr/share/perl5/Lire/</code> and the commands in
<code class="filename">/usr/lib/lire/</code> are not intended
as interfaces for the user. Only people wanting to change or study the
operation of <span class="application">Lire</span> itself will interact with these files; therefore,
the manpages should explain the inner workings and implementations of
these files. The configuration files in <code class="filename">/etc/lire/</code> might be changed by users.
These should be properly documented: in manpages or in the
<em class="citetitle"><span class="application">Lire</span> User's Manual</em>.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch21.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch21.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch21s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 21. Writing Documentation </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Docbook XML: Reference Books and Extensive User Manuals</td></tr></table></div></body></html>
|