Re: Example of proposed pod usage (with patch)
On 2011-08-12 22:34, Jeremiah C. Foster wrote:
> Here is an example of how I think pod might work;
Hey,
I appreciate the idea of improving the documentation and making
(htmlified-version of) README.developers appear on lintian.d.o was a
very nice idea. :)
I thinking we can (ab)use some headings in the README.developers. My
attachment is an example, I am not sure how well it works (I am mostly
used to do pod as a part of perl scripts/modules).
BTW, I committed your original README.developers with a few
changes[1], so your patch would probably not apply cleanly.
For the frontend/* files, what would we want in the pod? Personally I
am used to embed the "manpage"-pod in that file, but we have it (and
partly need it to be) in a separate file (man/*). So what are we
looking for here?
Personally I would probably skip the "LEGAL" part; if anything I would
include a 2-3 line "LICENSE" in the bottom[2]. Otherwise I think it
would just be "in the way".
~Niels
[1] minor stuff like "---" became a "======"-thingy as was used in the
other README
[2] E.g. something like:
"""
This script/module is free software and is available under the GNU
General Public License version 2, or (at your option) any later version.
"""
or even
"""License: GPL version 2, or (at your option) any later version."""
> ---
> README.developers | 6 ++++-
> frontend/lintian | 60 ++++++++++++++++++++++++++++++++++------------------
> 2 files changed, 44 insertions(+), 22 deletions(-)
>
> diff --git a/README.developers b/README.developers
> index dc1edd0..ca4b206 100644
> --- a/README.developers
> +++ b/README.developers
> @@ -1,4 +1,6 @@
> -README.Developers for the Lintian tool
> +=pod
> +
> +Readme.Developers for the Lintian tool
> ---
>
> Lintian dissects Debian packages and tries to find bugs and policy
> @@ -13,3 +15,5 @@ directory "frontend." This directory holds the "lintian" executable.
> This is what gets called when a user calls lintian. The frontend
> then calls the lintian checks which run over the Debian package
> that Lintian is checking.
> +
> +=end
> diff --git a/frontend/lintian b/frontend/lintian
> index 0625b61..907e747 100755
> --- a/frontend/lintian
> +++ b/frontend/lintian
> @@ -1,27 +1,45 @@
> #!/usr/bin/perl -w
> -# {{{ Legal stuff
> -# Lintian -- Debian package checker
> -#
> -# Copyright (C) 1998 Christian Schwarz and Richard Braakman
> -#
> -# This program is free software. It is distributed under the terms of
> -# the GNU General Public License as published by the Free Software
> -# Foundation; either version 2 of the License, or (at your option) any
> -# later version.
> -#
> -# This program is distributed in the hope that it will be useful,
> -# but WITHOUT ANY WARRANTY; without even the implied warranty of
> -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> -# GNU General Public License for more details.
> -#
> -# You should have received a copy of the GNU General Public License
> -# along with this program. If not, you can find it on the World Wide
> -# Web at http://www.gnu.org/copyleft/gpl.html, or write to the Free
> -# Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
> -# MA 02110-1301, USA.
> -# }}}
> +
> +=head1 NAME
> +
> +Lintian -- Debian package checker
> +
> +=over 2
> +
> +=item ./frontend/lintian
> +
> +=back
> +
> +=head1 LEGAL
> +
> +=over 2
> +
> +Copyright (C) 1998 Christian Schwarz and Richard Braakman
> +
> +This program is free software. It is distributed under the terms of
> +the GNU General Public License as published by the Free Software
> +Foundation; either version 2 of the License, or (at your option) any
> +later version.
> +
> +This program is distributed in the hope that it will be useful,
> +but WITHOUT ANY WARRANTY; without even the implied warranty of
> +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> +GNU General Public License for more details.
> +
> +You should have received a copy of the GNU General Public License
> +along with this program. If not, you can find it on the World Wide
> +Web at http://www.gnu.org/copyleft/gpl.html, or write to the Free
> +Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
> +MA 02110-1301, USA.
> +
> +=back
> +
> +=cut
> +
> +
>
> # {{{ libraries and such
> +
> use strict;
> use warnings;
>
>
diff --git a/doc/README.developers b/doc/README.developers
index 1cb3007..5a66336 100644
--- a/doc/README.developers
+++ b/doc/README.developers
@@ -1,5 +1,16 @@
-README file for developers of Lintian
-=====================================
+=head1 NAME
+
+README.developers -- README file for developers of Lintian
+
+=head1 SYNOPSIS
+
+This document aims to give an overview of the Lintian internals
+and is intended for people, who wants to develop or work on Lintian.
+
+For how to use Lintian, please refer to the (other) README, the manual
+pages lintian(1) and lintian-info(1) or the User Manual.
+
+=head1 DESCRIPTION
Lintian dissects Debian packages and tries to find bugs and policy
violations. It contains automated checks for many aspects of Debian
@@ -13,3 +24,7 @@ directory "frontend". This directory holds the "lintian" executable.
This is what gets called when a user calls lintian. The frontend
then calls the lintian checks which run over the Debian package
that Lintian is checking.
+
+=cut
+
+
Reply to: