Debian Bug report logs - #379829
manpages: regex(7) is practically unreadable - offer of rewrite

version graph

Package: manpages; Maintainer for manpages is Martin Schulze <joey@debian.org>; Source for manpages is src:manpages.

Reported by: Paul LeoNerd Evans <leonerd@leonerd.org.uk>

Date: Tue, 25 Jul 2006 19:49:21 UTC

Severity: normal

Found in version manpages/2.34-1

Fixed in version manpages/2.71-1

Done: Martin Schulze <joey@infodrom.org>

Bug is archived. No further changes may be made.

Toggle useless messages

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#379829; Package manpages. Full text and rfc822 format available.

Acknowledgement sent to Paul LeoNerd Evans <leonerd@leonerd.org.uk>:
New Bug report received and forwarded. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

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

From: Paul LeoNerd Evans <leonerd@leonerd.org.uk>
To: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: manpages: regex(7) is practically unreadable - offer of rewrite
Date: Tue, 25 Jul 2006 19:58:44 +0100
Package: manpages
Version: 2.34-1
Severity: normal

I have been using regexps for about 4 years now, and even I can't
understand regex(7). 

I therefore propose a rewrite, to be much longer, a much gentler
introduction for people who don't understand them, to include plenty of
examples to illustrate, and generally improve the whole thing.

I've not done a great amount of manpage writing before, other than lots
of POD in perl code, that gets translated. But I have a far amount of
experience at writing documentation on code (API docs), and lots of
experience at using REs. People I meet on IRC say they've learned more
from a 30second 5line rant of mine than in the entire manpage.

Perhaps I could write a replacement for debian?

-- System Information:
Debian Release: testing/unstable
  APT prefers testing
  APT policy: (990, 'testing'), (500, 'unstable')
Architecture: i386 (i686)
Shell:  /bin/sh linked to /bin/bash
Kernel: Linux 2.6.16-mh3.nim
Locale: LANG=en_GB.UTF-8, LC_CTYPE=en_GB.UTF-8 (charmap=UTF-8)

-- no debconf information



Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#379829; Package manpages. Full text and rfc822 format available.

Acknowledgement sent to Martin Schulze <joey@infodrom.org>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

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

From: Martin Schulze <joey@infodrom.org>
To: Paul LeoNerd Evans <leonerd@leonerd.org.uk>
Cc: Debian Bug Tracking System <379829@bugs.debian.org>, Michael Kerrisk <mtk-manpages@gmx.net>
Subject: Re: manpages: regex(7) is practically unreadable - offer of rewrite
Date: Wed, 26 Jul 2006 17:29:28 +0200
Paul LeoNerd Evans wrote:
> I have been using regexps for about 4 years now, and even I can't
> understand regex(7). 
> 
> I therefore propose a rewrite, to be much longer, a much gentler
> introduction for people who don't understand them, to include plenty of
> examples to illustrate, and generally improve the whole thing.
> 
> I've not done a great amount of manpage writing before, other than lots
> of POD in perl code, that gets translated. But I have a far amount of
> experience at writing documentation on code (API docs), and lots of
> experience at using REs. People I meet on IRC say they've learned more
> from a 30second 5line rant of mine than in the entire manpage.
> 
> Perhaps I could write a replacement for debian?

I'd rather like you to get in touch with Michael Kerrisk, so that
the resulting page will pass his quality checks and can be included
in the upstream man-pages package as well instead of a local Debian
version.

Regards,

	Joey

-- 
GNU does not eliminate all the world's problems, only some of them.
                                                -- The GNU Manifesto

Please always Cc to me when replying to me on the lists.



Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#379829; Package manpages. Full text and rfc822 format available.

Acknowledgement sent to "Michael Kerrisk" <mtk-manpages@gmx.net>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

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

From: "Michael Kerrisk" <mtk-manpages@gmx.net>
To: Martin Schulze <joey@infodrom.org>, leonerd@leonerd.org.uk
Cc: 379829@bugs.debian.org
Subject: Re: Bug#379829: manpages: regex(7) is practically unreadable - offer of rewrite
Date: Thu, 27 Jul 2006 08:17:33 +0200
Datum: Wed, 26 Jul 2006 17:29:28 +0200
Von: Martin Schulze <joey@infodrom.org>
An: Paul LeoNerd Evans <leonerd@leonerd.org.uk>
Betreff: Bug#379829: manpages: regex(7) is practically unreadable - offer of rewrite

> Paul LeoNerd Evans wrote:
> > I have been using regexps for about 4 years now, and even I can't
> > understand regex(7). 
> > 
> > I therefore propose a rewrite, to be much longer, a much gentler
> > introduction for people who don't understand them, to include plenty of
> > examples to illustrate, and generally improve the whole thing.
> > 
> > I've not done a great amount of manpage writing before, other than lots
> > of POD in perl code, that gets translated. But I have a far amount of
> > experience at writing documentation on code (API docs), and lots of
> > experience at using REs. People I meet on IRC say they've learned more
> > from a 30second 5line rant of mine than in the entire manpage.
> > 
> > Perhaps I could write a replacement for debian?
> 
> I'd rather like you to get in touch with Michael Kerrisk, so that
> the resulting page will pass his quality checks and can be included
> in the upstream man-pages package as well instead of a local Debian
> version.

Paul, Joey,

I agree that regex(7) could use a lot of improvement.  I'd 
be prepared to accept a well written replacement.  (While
doing this, it would be a good idea to read the POSIX regex
specification closely.)

Cheers,

Michael
-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 

Want to help with man page maintenance?  
Grab the latest tarball at
ftp://ftp.win.tue.nl/pub/linux-local/manpages/, 
read the HOWTOHELP file and grep the source 
files for 'FIXME'.



Message sent on to Paul LeoNerd Evans <leonerd@leonerd.org.uk>:
Bug#379829. Full text and rfc822 format available.

Message #18 received at 379829-submitter@bugs.debian.org (full text, mbox):

From: Justin Pryzby <justinpryzby@users.sourceforge.net>
To: 282726-done@bugs.debian.org, 379829-submitter@bugs.debian.org, 348552@bugs.debian.org
Cc: manpages@packages.qa.debian.org
Subject: backwards bug: grep.1 and regex.7
Date: Thu, 19 Oct 2006 11:08:46 -0400
retitle 348552 Please make regex(3) reference grep(1)
thanks

I'm afraid this bug was backwards, and I didn't notice until just now.
grep(1) has an excellent introduction to regexs.  Manpages already has a
couple bugs about regex(7); I would suggest that regex(7) SEE ALSO
grep(1), (satisfying #348552), and providing an arguably better
high-level-first introduction to the concept (addressing #379829).  I
found that regex(7) is more easily digested when read backwards.

Paul, is the grep(1) manpage section on regexs more to your liking?

Justin

An additional suggested text for regex(7):

Regular expressions are implemented and utilized by many programs,
including
.BR grep (1),
.BR ed (1),
.BR sed (1),
.BR perl (1).
(This might also mention that grep and sed are [mostly] line-based).



Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#379829; Package manpages. Full text and rfc822 format available.

Acknowledgement sent to Pascal MALAISE <malaise@magic.fr>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #23 received at 379829@bugs.debian.org (full text, mbox):

From: Pascal MALAISE <malaise@magic.fr>
To: 379829@bugs.debian.org
Subject: regex(7) inacurate
Date: Sun, 25 Nov 2007 12:57:08 +0100
The manpage regex(7) is probably not user friendly, but generally
speaking it is precise and accurate.

However, one point is wrong or at least misleading:
The last section of the DESCRIPTION describes all together the "basic"
regex and the concept of back reference, suggesting that back reference
is specific to basic regex.
I don't know the POSIX specification but on Linux/Debian/Ubuntu, the
back reference is also valid in extended regex.

I suggest to move the section on "back reference" section just before
the section on basic regex.

Regards

-- 
Pascal MALAISE
(priv) mailto:malaise@magic.fr
(prof) mailto:pascal.malaise@thalesgroup.com




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#379829; Package manpages. Full text and rfc822 format available.

Acknowledgement sent to Michael Kerrisk <mtk.manpages@googlemail.com>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #28 received at 379829@bugs.debian.org (full text, mbox):

From: Michael Kerrisk <mtk.manpages@googlemail.com>
To: Pascal MALAISE <malaise@magic.fr>, 379829@bugs.debian.org
Subject: Re: Bug#379829: regex(7) inacurate
Date: Mon, 03 Dec 2007 18:40:29 +0100
tags 379829 fixed-upstream
thanks

Changes made for upstream 2.71.

Pascal MALAISE wrote:
> The manpage regex(7) is probably not user friendly, but generally
> speaking it is precise and accurate.
> 
> However, one point is wrong or at least misleading:
> The last section of the DESCRIPTION describes all together the "basic"
> regex and the concept of back reference, suggesting that back reference
> is specific to basic regex.
> I don't know the POSIX specification but on Linux/Debian/Ubuntu, the
> back reference is also valid in extended regex.
> 
> I suggest to move the section on "back reference" section just before
> the section on basic regex.

Pascal, I agree that the text is misleading, but I've gone for a simpler
fix: I made the text on back references into it's own paragraph.  That is,
I simply split the paragraph into two parts.  I think that should be
sufficient to indicate that basig REs and Back References are unrelated.

Cheers,

Michael

-- 
Michael Kerrisk
Maintainer of the Linux man-pages project
http://www.kernel.org/doc/man-pages/





Reply sent to Martin Schulze <joey@infodrom.org>:
You have taken responsibility. Full text and rfc822 format available.

Notification sent to Paul LeoNerd Evans <leonerd@leonerd.org.uk>:
Bug acknowledged by developer. Full text and rfc822 format available.

Message #33 received at 379829-close@bugs.debian.org (full text, mbox):

From: Martin Schulze <joey@infodrom.org>
To: 379829-close@bugs.debian.org
Subject: Bug#379829: fixed in manpages 2.71-1
Date: Sun, 20 Jan 2008 17:32:09 +0000
Source: manpages
Source-Version: 2.71-1

We believe that the bug you reported is fixed in the latest version of
manpages, which is due to be installed in the Debian FTP archive:

manpages-dev_2.71-1_all.deb
  to pool/main/m/manpages/manpages-dev_2.71-1_all.deb
manpages_2.71-1.diff.gz
  to pool/main/m/manpages/manpages_2.71-1.diff.gz
manpages_2.71-1.dsc
  to pool/main/m/manpages/manpages_2.71-1.dsc
manpages_2.71-1_all.deb
  to pool/main/m/manpages/manpages_2.71-1_all.deb
manpages_2.71.orig.tar.gz
  to pool/main/m/manpages/manpages_2.71.orig.tar.gz



A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 379829@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Martin Schulze <joey@infodrom.org> (supplier of updated manpages package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@debian.org)


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Format: 1.7
Date: Sun, 20 Jan 2008 18:06:22 +0100
Source: manpages
Binary: manpages manpages-dev
Architecture: source all
Version: 2.71-1
Distribution: unstable
Urgency: low
Maintainer: Martin Schulze <joey@debian.org>
Changed-By: Martin Schulze <joey@infodrom.org>
Description: 
 manpages   - Manual pages about using a GNU/Linux system
 manpages-dev - Manual pages about using GNU/Linux for development
Closes: 379829
Changes: 
 manpages (2.71-1) unstable; urgency=low
 .
   * New upstream version
     . Improvement of regex(7) (closes: Bug#379829)
Files: 
 756652db9a57ab76c0e7f3a46ce4777a 584 doc important manpages_2.71-1.dsc
 e28b219163d9844a98aa179c83c94355 1270440 doc important manpages_2.71.orig.tar.gz
 e5e650f581b12377fa0afe3f118ff29e 53788 doc important manpages_2.71-1.diff.gz
 3e6b34cf3b0bb157a3f1355ba2c96844 543530 doc important manpages_2.71-1_all.deb
 bcdafcd25c7f5398f86594640b8830f5 1371956 doc optional manpages-dev_2.71-1_all.deb

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)

iD8DBQFHk4HSW5ql+IAeqTIRAstFAJ95/3A8bbo8QV6HWAyDrAbmjflguQCgpoNr
cfc93Zd9ULL7kl4bqsxUwI8=
=+SBT
-----END PGP SIGNATURE-----





Bug archived. Request was from Debbugs Internal Request <owner@bugs.debian.org> to internal_control@bugs.debian.org. (Mon, 18 Feb 2008 07:28:25 GMT) Full text and rfc822 format available.

Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Fri Apr 18 06:28:53 2014; Machine Name: beach.debian.org

Debian Bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.