FAQ Search Today's Posts Mark Forums Read
» Video Reviews

» Linux Archive

Linux-archive is a website aiming to archive linux email lists and to make them easily accessible for linux users/developers.


» Sponsor

» Partners

» Sponsor

Go Back   Linux Archive > Debian > Debian Development

 
 
LinkBack Thread Tools
 
Old 03-02-2009, 09:22 AM
Simon Josefsson
 
Default Requirement for a “proper manpage” for every command

Ben Finney <ben+debian@benfinney.id.au> writes:

> I'm having a conversation with a Debian packager regarding a manpage
> that, currently, is a mere placeholder saying “please see foocommand
> --help”, giving none of the useful information normally found in a
> manpage.
...
> I have submitted a manpage as a patch. However, that response pretty
> much guarantees that the maintainer won't be taking the initiative to
> keep the manpage up to date.

How about submitting a patch to use help2man instead?

http://www.gnu.org/software/help2man/

Then the man page will be kept up to date with --help output.

Possibly the document around the man page requirement could point to
help2man as a quick solution in case there is useful --help output but
no man page.

/Simon


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 03-02-2009, 06:29 PM
Gunnar Wolf
 
Default Requirement for a “proper manpage” for every command

Simon Josefsson dijo [Mon, Mar 02, 2009 at 11:22:52AM +0100]:
> How about submitting a patch to use help2man instead?
>
> http://www.gnu.org/software/help2man/
>
> Then the man page will be kept up to date with --help output.
>
> Possibly the document around the man page requirement could point to
> help2man as a quick solution in case there is useful --help output but
> no man page.

Hmh, this could even be promoted as a "best packaging practice". Many
authors do ship properly-formatted --help entries, and our
hand-generated manpages can often linger behind the truth. Any strong
opinions against?

--
Gunnar Wolf - gwolf@gwolf.org - (+52-55)5623-0154 / 1451-2244
PGP key 1024D/8BB527AF 2001-10-23
Fingerprint: 0C79 D2D1 2C4E 9CE4 5973 F800 D80E F35A 8BB5 27AF


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 03-02-2009, 06:45 PM
"brian m. carlson"
 
Default Requirement for a “proper manpage” for every command

On Mon, Mar 02, 2009 at 11:22:52AM +0100, Simon Josefsson wrote:

How about submitting a patch to use help2man instead?

http://www.gnu.org/software/help2man/

Then the man page will be kept up to date with --help output.


help2man is a fine starting point for a manpage, but unless the help
messages are very verbose, it is not sufficient. A manpage needs to
explain all the possibilities and interactions between different
options that are usually not provided by --help output.

An excellent example is gpg(1). help2man could provide a very basic
starting point, but the resulting manpage would be woefully incomplete.


Possibly the document around the man page requirement could point to
help2man as a quick solution in case there is useful --help output but
no man page.


My concern is that people will solely use help2man instead of providing
a real manpage. Debian requires manpages for a reason: to provide
adequate documentation on how to use installed programs.

--
brian m. carlson / brian with sandals: Houston, Texas, US
+1 713 440 7475 | http://crustytoothpaste.ath.cx/~bmc | My opinion only
troff on top of XML: http://crustytoothpaste.ath.cx/~bmc/code/thwack
OpenPGP: RSA v4 4096b 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187
 
Old 03-02-2009, 06:56 PM
Adeodato Simó
 
Default Requirement for a “proper manpage” for every command

* brian m. carlson [Mon, 02 Mar 2009 19:45:22 +0000]:

> help2man is a fine starting point for a manpage, but unless the help
> messages are very verbose, it is not sufficient. A manpage needs to
> explain all the possibilities and interactions between different
> options that are usually not provided by --help output.

> An excellent example is gpg(1). help2man could provide a very basic
> starting point, but the resulting manpage would be woefully incomplete.

This is true.

>> Possibly the document around the man page requirement could point to
>> help2man as a quick solution in case there is useful --help output but
>> no man page.

> My concern is that people will solely use help2man instead of providing
> a real manpage. Debian requires manpages for a reason: to provide
> adequate documentation on how to use installed programs.

Many times the problem is that upstreams do provide such adequate
documentation... in other formats than man pages. What should the
packager do in that case? Create a dummy man page pointing out to eg.
/usr/share/doc/foopkg/html/fooprog.html? Copy over the contents of
fooprog.html to fooprog.1? Other?

--
Adeodato Simó dato at net.com.org.es
Debian Developer adeodato at debian.org

Listening to: Ana Torroja - Les Murs


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 03-02-2009, 07:19 PM
Manoj Srivastava
 
Default Requirement for a “proper manpage” for every command

On Mon, Mar 02 2009, Adeodato Simó wrote:


> Many times the problem is that upstreams do provide such adequate
> documentation... in other formats than man pages. What should the
> packager do in that case? Create a dummy man page pointing out to eg.
> /usr/share/doc/foopkg/html/fooprog.html? Copy over the contents of
> fooprog.html to fooprog.1? Other?

What I have done in the past is to create a good, current man
page with the contents of the upstream provided manual, and add in a
caveat that the primary documentation lies elsewhere, and ask users to
refer to it for completeness. I submitted the man page upstream (and
have had some upstreams reject it).

Then, every few revisions, I would resync the man page. I
consider this just one of the things that Debian maintainedrs
ought to do -- I mean, we are not just glorified packagers.

manoj
--
Parkinson's Fifth Law: If there is a way to delay in important decision,
the good bureaucracy, public or private, will find it.
Manoj Srivastava <srivasta@debian.org> <http://www.debian.org/~srivasta/>
1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 03-02-2009, 07:22 PM
Manoj Srivastava
 
Default Requirement for a “proper manpage” for every command

On Mon, Mar 02 2009, Gunnar Wolf wrote:

> Simon Josefsson dijo [Mon, Mar 02, 2009 at 11:22:52AM +0100]:
>> How about submitting a patch to use help2man instead?
>>
>> http://www.gnu.org/software/help2man/>
>> Then the man page will be kept up to date with --help output.
>>
>> Possibly the document around the man page requirement could point to
>> help2man as a quick solution in case there is useful --help output but
>> no man page.
>
> Hmh, this could even be promoted as a "best packaging practice". Many
> authors do ship properly-formatted --help entries, and our
> hand-generated manpages can often linger behind the truth. Any strong
> opinions against?

I would not call it best. Barely adequate, perhaps. Could do
better, certainly. Best practrice would be to write up a real man
page, perhaps using the help2man as a starting point.

manoj
--
Loan-department manager: "There isn't any fine print. At these interest
rates, we don't need it."
Manoj Srivastava <srivasta@debian.org> <http://www.debian.org/~srivasta/>
1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 03-02-2009, 09:32 PM
Ben Finney
 
Default Requirement for a “proper manpage” for every command

(Gunnar, and others, please don't send individual responses that you
also send to the mailing list.)

Gunnar Wolf <gwolf@gwolf.org> writes:

> Hmh, this could even be promoted as a "best packaging practice".
> Many authors do ship properly-formatted --help entries, and our
> hand-generated manpages can often linger behind the truth. Any
> strong opinions against?

The information appropriate for a man page (separate “description”,
“options”, “examples”, “files”, “environment variables”, “see
also”, etc.) is not appropriate for cramming into a ‘--help’ output,
so shouldn't be expected to be there.

I don't know how many ‘--help’ outputs actually provide all that
information in such a form that ‘help2man’ can extract it; I think the
number would be quite few. I would expect that any which do are rather
bloated as a result.

--
“I bought a dog the other day. I named him Stay. It's fun to |
` call him. ‘Come here, Stay! Come here, Stay!’ He went insane. |
_o__) Now he just ignores me and keeps typing.” —Steven Wright |
Ben Finney


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 03-02-2009, 11:10 PM
Roger Leigh
 
Default Requirement for a “proper manpage” for every command

On Mon, Mar 02, 2009 at 09:04:39PM +1100, Ben Finney wrote:

> The response from the maintainer (who is also the upstream author) so
> far is, essentially, “Patches welcome, but I'm not interested in
> maintaining manpages”.
>
> I have submitted a manpage as a patch. However, that response pretty
> much guarantees that the maintainer won't be taking the initiative to
> keep the manpage up to date. Am I right in thinking that it is
> nevertheless the maintainer's responsibility to do so?

IMO, yes. That's part and parcel of what a package maintainer
should be doing.

> I don't like Debian policy being used as a blunt instrument, but I
> must admit my mental reaction to the maintainer's response was along
> the lines of “Too bad; in accepting the role of package maintainer,
> you accepted the ongoing task of maintaining manpages for every
> command, utility, and function in the package”.
>
> Wording and tone aside, is that expectation reasonable?

Again IMO, yes. We require manual pages, and it's the maintainer's
responsibility to make sure that they are provided and up to date.
It's not like it's a major chore to write a manual page, so any
maintainer outright refusing to do so is a crap maintainer, as well
as being bloody lazy.


Regards,
Roger

--
.'`. Roger Leigh
: :' : Debian GNU/Linux http://people.debian.org/~rleigh/
`. `' Printing on GNU/Linux? http://gutenprint.sourceforge.net/
`- GPG Public Key: 0x25BFB848 Please GPG sign your mail.
 
Old 03-03-2009, 12:14 AM
Gunnar Wolf
 
Default Requirement for a “proper manpage” for every command

Manoj Srivastava dijo [Mon, Mar 02, 2009 at 02:22:57PM -0600]:
> > Hmh, this could even be promoted as a "best packaging practice". Many
> > authors do ship properly-formatted --help entries, and our
> > hand-generated manpages can often linger behind the truth. Any strong
> > opinions against?
>
> I would not call it best. Barely adequate, perhaps. Could do
> better, certainly. Best practrice would be to write up a real man
> page, perhaps using the help2man as a starting point.

I agree - But at least its output is equivalent in quality to a couple
of manpages I have hand-generated (i.e. documenting a somewhat-obscure
command or one for which the --help output is just enough). For one of
them I have already ditched my man page for a call to help2man in
debian/rules' install - It will at least make sure I don't skip any
changes introduced upstream.

Greetings,

--
Gunnar Wolf - gwolf@gwolf.org - (+52-55)5623-0154 / 1451-2244
PGP key 1024D/8BB527AF 2001-10-23
Fingerprint: 0C79 D2D1 2C4E 9CE4 5973 F800 D80E F35A 8BB5 27AF


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 03-03-2009, 01:40 AM
Lars Wirzenius
 
Default Requirement for a “proper manpage” for every command

ma, 2009-03-02 kello 14:19 -0600, Manoj Srivastava kirjoitti:
> Then, every few revisions, I would resync the man page. I
> consider this just one of the things that Debian maintainedrs
> ought to do -- I mean, we are not just glorified packagers.

We could aid this process by having a tool to detect when a manpage and
--help don't document the same options. I have one for a pet project of
mine, but it's pretty specific to that. Anyone want to whip up some perl
for a reasonably generic one?


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 

Thread Tools




All times are GMT. The time now is 03:57 AM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.
Copyright 2007 - 2008, www.linux-archive.org