Debian Bug report logs - #328113
[FIXED 4.0.13] man page improvements for passwd.5

Toggle useless messages

Message #5 received at submit@bugs.debian.org (full text, mbox, reply):

From: Greg Wooledge <greg@wooledge.org>

To: Debian Bug Tracking System <submit@bugs.debian.org>

Subject: man page improvements for passwd.5

Date: Tue, 13 Sep 2005 11:01:19 -0400

[Message part 1 (text/plain, inline)]

Package: passwd
Version: 1:4.0.3-30
Severity: wishlist
Tags: patch


This probably needs to go upstream, but I'm not even sure who's in charge
of this documentation, if *anyone* at all is....  Nor am I sure who's in
charge of arranging the translations, etc.

-- System Information:
Debian Release: 3.1
  APT prefers unstable
  APT policy: (500, 'unstable')
Architecture: i386 (i686)
Shell:  /bin/sh linked to /bin/bash
Kernel: Linux 2.4.31
Locale: LANG=en_US.ISO8859-1, LC_CTYPE=en_US.ISO8859-1 (charmap=ISO-8859-1)

Versions of packages passwd depends on:
ii  libc6                         2.3.5-6    GNU C Library: Shared libraries an
ii  libpam-modules                0.76-22    Pluggable Authentication Modules f
ii  libpam0g                      0.76-22    Pluggable Authentication Modules l
ii  login                         1:4.0.3-30 System login tools

passwd recommends no packages.

-- debconf information excluded

[passwd.5.diff (text/plain, attachment)]

Message #10 received at 328113@bugs.debian.org (full text, mbox, reply):

From: Christian Perrier <bubulle@debian.org>

To: Greg Wooledge <greg@wooledge.org>, 328113@bugs.debian.org

Cc: Tomasz Kłoczko <kloczek@zie.pg.gda.pl>

Subject: Re: [Pkg-shadow-devel] Bug#328113: man page improvements for passwd.5

Date: Wed, 14 Sep 2005 07:18:13 +0200

Quoting Greg Wooledge (greg@wooledge.org):
> Package: passwd
> Version: 1:4.0.3-30
> Severity: wishlist
> Tags: patch
> 
> 
> This probably needs to go upstream, but I'm not even sure who's in charge
> of this documentation, if *anyone* at all is....  Nor am I sure who's in
> charge of arranging the translations, etc.

upstream is...

We are currently in the process of resyncing with upstream
versions. In current upstream versions, all documentation is using
DocBook XML and man pages are generated from these XML files.

This means that the patch, as is, is not likely to be applied.

On the other hand, I'm pretty convinced that upstream documentation
needs a big general overview. Neither the upstream author (Tomasz
K~oczko), nor the Debian maintainers (with only one exception) are
native English speakers and there are probably a lot of mistakes lying
in the documentation.

So, help would be greatly welcomed here, actually.

I don't really know what to do with your bug report. We ca n't apply
it and I don't want to reject help. Would you be OK if I sent you the
passwd.5.xml file so that you can make the suggested changes there
(and review it while you're at it)�?

Message #15 received at 328113@bugs.debian.org (full text, mbox, reply):

From: Greg Wooledge <greg@wooledge.org>

To: Christian Perrier <bubulle@debian.org>

Cc: 328113@bugs.debian.org, Tomasz K??oczko <kloczek@zie.pg.gda.pl>

Subject: Re: [Pkg-shadow-devel] Bug#328113: man page improvements for passwd.5

Date: Wed, 14 Sep 2005 10:50:37 -0400

[Message part 1 (text/plain, inline)]

Christian Perrier (bubulle@debian.org) wrote:

> I don't really know what to do with your bug report. We ca n't apply
> it and I don't want to reject help. Would you be OK if I sent you the
> passwd.5.xml file so that you can make the suggested changes there
> (and review it while you're at it)????

Well, it can't hurt to look at it.  Go ahead and send it, but I can't
promise anything until I see it.

-- 
Greg Wooledge                  |   "Truth belongs to everybody."
greg@wooledge.org              |    - The Red Hot Chili Peppers
http://wooledge.org/~greg/     |

[signature.asc (application/pgp-signature, inline)]

Message #20 received at 328113@bugs.debian.org (full text, mbox, reply):

From: Greg Wooledge <greg@wooledge.org>

To: 328113@bugs.debian.org

Subject: Re: [Pkg-shadow-devel] Bug#328113: man page improvements for passwd.5

Date: Wed, 14 Sep 2005 19:08:40 -0400

[Message part 1 (text/plain, inline)]

Christian Perrier (bubulle@kheops.frmug.org) wrote:

> (reply set to the bug report)
> 
> Here it is. Thanks for any comment you can make.

All right.  It looks like it was translated directly from the existing man
page, which makes applying the changes simple, except for trying to figure
out what XML tags to use for various purposes.

Is there a definitive list of the tags, all in one place, which matches
the actual set used for the man page?  For example,
<http://www.lodestar2.com/people/dyork/talks/2002/ols/docbook-tutorial/frames/foil35.html>
shows

  <emphasis role="bold">This is some bold text.</emphasis>

and <http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/docbooksys/segmentedhtml/ch09s01.html>
uses

  <emphasis role="strong">A different type of emphasis</emphasis>

but the man page you sent uses

  <emphasis remap='B'>Login</emphasis>

Also, <http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/docbooksys/segmentedhtml/ch09s01.html>
says that apostrophes must be converted into &apos; but the man page has
the word "user's" in it, with a raw apostrophe.

I'm unclear how to put in a quoted literal character, as in:

  with seven fields delimited by colons (`:')

Is <quote>:</quote> the proper markup for that?  It seems right, based on
<http://www.docbook.org/tdg/en/html/quote.html>, but I'm not sure how
closely you're following that set of tags.

Finally, what command should I use to render the XML into its "man page
format", so that I can check that what I've done is correct?  (In other
words, the Docbook XML equivalent of "nroff -man passwd.5 | less", or a
command to convert passwd.5.xml into passwd.5.)  I'd be happy to help out
with documentation for more than just this one man page, but I can't seem
to find the right starting point.

I'm attaching what I've got so far.

-- 
Greg Wooledge                  |   "Truth belongs to everybody."
greg@wooledge.org              |    - The Red Hot Chili Peppers
http://wooledge.org/~greg/     |

[passwd.5.xml (text/plain, attachment)]

[signature.asc (application/pgp-signature, inline)]

Message #25 received at 328113@bugs.debian.org (full text, mbox, reply):

From: Christian Perrier <bubulle@debian.org>

To: Greg Wooledge <greg@wooledge.org>, 328113@bugs.debian.org

Subject: Re: Bug#328113: [Pkg-shadow-devel] Bug#328113: man page improvements for passwd.5

Date: Thu, 15 Sep 2005 07:01:42 +0200

> Finally, what command should I use to render the XML into its "man page
> format", so that I can check that what I've done is correct?  (In other

Either Tomasz (upstream author), or one of my fellow co-maintainers
(probably Nicolas François), will answer you on that matter.


> words, the Docbook XML equivalent of "nroff -man passwd.5 | less", or a
> command to convert passwd.5.xml into passwd.5.)  I'd be happy to help out
> with documentation for more than just this one man page, but I can't seem
> to find the right starting point.
> 
> I'm attaching what I've got so far.


Thanks a lot, Greg. The work is deeply appreciated. Tomasz, would you
please review this and consider commiting it to your CVS?

Message #30 received at 328113-done@bugs.debian.org (full text, mbox, reply):

From: Tomasz Kłoczko <kloczek@zie.pg.gda.pl>

To: Christian Perrier <bubulle@debian.org>, 328113-done@bugs.debian.org

Subject: Re: Bug#328113: [Pkg-shadow-devel] Bug#328113: man page improvements for passwd.5

Date: Thu, 15 Sep 2005 18:38:20 +0200 (CEST)

[Message part 1 (text/plain, inline)]

On Thu, 15 Sep 2005, Christian Perrier wrote:
[..]
> Thanks a lot, Greg. The work is deeply appreciated. Tomasz, would you
> please review this and consider commiting it to your CVS?

Looks good.

[man]$ grep emphasis passwd.5.xml
      <emphasis>any</emphasis> access at all if the
      <emphasis>password</emphasis> field is blank.)
      If the <emphasis>password</emphasis> field is a lower-case
      there <emphasis remap='B'>must</emphasis> be a corresponding line
      If the <emphasis>password</emphasis> field is any other string,
      The <emphasis remap='B'>login</emphasis> program uses this
      The <emphasis remap='B'>login</emphasis> program uses this

Seems last two <emphasis> can be replaced by <command>
and all <emphasis remap='B'> can be replaced by <emphasis>.

I'm just finish this and commit to CVS tree.

Greg .. thank you.

kloczek
-- 
-----------------------------------------------------------
*Ludzie nie mają problemów, tylko sobie sami je stwarzają*
-----------------------------------------------------------
Tomasz Kłoczko, sys adm @zie.pg.gda.pl|*e-mail: kloczek@rudy.mif.pg.gda.pl*

Message #41 received at 328113-done@bugs.debian.org (full text, mbox, reply):

From: Christian Perrier <bubulle@debian.org>

To: 328113-done@bugs.debian.org

Subject: This bug is fixed

Date: Thu, 13 Oct 2005 21:12:46 +0200

Version: 4.0.13-1

This bug has been fixed in 4.0.13-1 but the changelog entry was
forgotten.


-- 

Send a report that this bug log contains spam.