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 11-18-2007, 12:40 AM
Colin Watson
 
Default Bug#377392: Bug#450432: ... and even more bugs like this?

On Fri, Nov 16, 2007 at 12:32:26AM +0600, Ivan Shmakov wrote:
> In a recent thread in debian-devel, it was suggested that
> lintian could call man(1) in such a way that the groff(1),
> called by `man', will emit warnings for every undefined macro,
> which is useful in catching the bugs like this:
>
> .B foo
> . Note: ...
>
> Below is the patch that implements the suggestion. Since `man'
> doesn't allow the `-wmac' option to be passed to `groff' by any
> other means, I've had to introduce two new files -- `mdoc.local'
> and `man.local' (to override the files in groff/site-tmac/), and
> the ${LINTIAN_ROOT}/groff-hack directory to hold them.

While I haven't reviewed the code in detail, the general approach seems
largely reasonable to me. However, the error the developer sees will
just be "manpage-has-errors-from-man", which in fact is no longer really
true in this case; you're specifically enabling warnings that man
doesn't show. Perhaps it would be best to turn these warnings from groff
into a different lintian warning which can have a more informative
description, and ideally a way for the developer to reproduce the
problem.

Cheers,

--
Colin Watson [cjwatson@debian.org]


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 11-18-2007, 01:50 AM
Russ Allbery
 
Default Bug#377392: Bug#450432: ... and even more bugs like this?

Colin Watson <cjwatson@debian.org> writes:

> .IX is probably from pod2man, which does:

> ." If the F register is turned on, we'll generate index entries on stderr for
> ." titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
> ." entries marked with X<> in POD. Of course, you'll have to process the
> ." output yourself in some meaningful fashion.
> .if
F {
> . de IX
> . tm Index:$1
% "$2"
> ..
> . nr % 0
> . rr F
> .}

> Russ, perhaps this should be something like this instead to suppress the
> warning?

> ." If the F register is turned on, we'll generate index entries on stderr for
> ." titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
> ." entries marked with X<> in POD. Of course, you'll have to process the
> ." output yourself in some meaningful fashion.
> .ie
F {
> . de IX
> . tm Index:$1
% "$2"
> ..
> . nr % 0
> . rr F
> .}
> .el {
> . de IX
> ..
> .}

Sure, that seems reasonable.

>> W: dpkg-dev: manpage-has-errors-from-man usr/share/man/man1/dpkg-architecture.1.gz 104: warning: `C`' not defined

> I'm not entirely sure what all this line noise is trying to achieve.
> Looks to me like stuff like f(CW*(C`-c*(C' should just be -c;

It's intentional in general. I don't know why it's not defined, though.
f(CW sets a fixed-width font, and *(C` and *(C' add "" when fonts
aren't supported but suppress the quotes when fonts are supported.
pod2man has done this for eons.

I haven't looked at this particular usage, but there are places where this
is exactly the desired markup.

Maybe there's some missing logic for defining empty strings?

--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 11-18-2007, 11:00 AM
Colin Watson
 
Default Bug#377392: Bug#450432: ... and even more bugs like this?

On Sat, Nov 17, 2007 at 06:50:18PM -0800, Russ Allbery wrote:
> Colin Watson <cjwatson@debian.org> writes:
> >> W: dpkg-dev: manpage-has-errors-from-man usr/share/man/man1/dpkg-architecture.1.gz 104: warning: `C`' not defined
>
> > I'm not entirely sure what all this line noise is trying to achieve.
> > Looks to me like stuff like f(CW*(C`-c*(C' should just be -c;
>
> It's intentional in general. I don't know why it's not defined, though.
> f(CW sets a fixed-width font, and *(C` and *(C' add "" when fonts
> aren't supported but suppress the quotes when fonts are supported.
> pod2man has done this for eons.

In pod2man's case, it's almost fine. I think it would be helpful if it
.ds'ed C` and C' to the empty string in the troff branch, though.

However, dpkg-architecture.1 isn't a pod2man-generated page, and it
seems to have cribbed the use of these strings without also cribbing
their definitions. In this case, I don't think quotes would be desirable
anyway - the context is:

CC=i386-gnu-gcc dpkg-architecture f(CW*(C`-c*(C'fR debian/rules build

eval `dpkg-architecture f(CW*(C`-u*(C'fR`

One problem that seems to crop up a lot with inexperienced *roff users
is that they crib from other example pages without understanding which
facilities are effectively built into the language and which are
provided by bits at the top of the page. I've tried to provide examples
in /usr/share/doc/man-db/examples/ which should be good enough for many
people.

Personally I like to use the mdoc macros, which form a logical markup
language rather than a physical markup language, so you don't spend time
mucking about with font selections and can just say "this is a flag" or
"this is a program argument" or whatever instead. However, I think I
would echo Russ' recommendation to use POD if you don't know *roff well
and just want to write a manual page without the formatting getting in
your way.

Cheers,

--
Colin Watson [cjwatson@debian.org]


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 11-21-2007, 02:33 PM
Ivan Shmakov
 
Default Bug#377392: Bug#450432: ... and even more bugs like this?

>>>>> Colin Watson <cjwatson@debian.org> writes:

>> In a recent thread in debian-devel, it was suggested that lintian
>> could call man(1) in such a way that the groff(1), called by `man',
>> will emit warnings for every undefined macro, which is useful in
>> catching the bugs like this:

>> .B foo
>> . Note: ...

>> Below is the patch that implements the suggestion. Since `man'
>> doesn't allow the `-wmac' option to be passed to `groff' by any
>> other means, I've had to introduce two new files -- `mdoc.local' and
>> `man.local' (to override the files in groff/site-tmac/), and the
>> ${LINTIAN_ROOT}/groff-hack directory to hold them.

> While I haven't reviewed the code in detail, the general approach
> seems largely reasonable to me. However, the error the developer sees
> will just be "manpage-has-errors-from-man", which in fact is no
> longer really true in this case; you're specifically enabling
> warnings that man doesn't show. Perhaps it would be best to turn
> these warnings from groff into a different lintian warning which can
> have a more informative description, and ideally a way for the
> developer to reproduce the problem.

A helper script, `lintian-man', could be introduced to hide all
the hackery, and to provide a way for the developer to reproduce
the problem. Then, Tag: may be changed to, e. g.,
`manpage-has-messages-from-lintian-man'. (Or should this script
be called `man-lintian'?)

I still hope that either `groff' or `man' will offer a way to
specify `-w'-options for `groff' in a more clean way. The
helper script could then be modified, or eliminated entirely.

The patch is as follows. (TODO: newly introduced lintian-man
script demands a man page on its own.) This new version of the
patch suppresses `.IX'-related warnings. (TODO: the generator
is to be fixed.)

--- lintian-1.23.36/checks/manpages 2007-10-16 10:40:04.000000000 +0700
+++ lintian-1.23.36-groff-hack/checks/manpages 2007-11-21 21:16:29.000000000 +0600
@@ -253,10 +253,11 @@
# processed properly. (Yes, there are man pages that include other
# pages with .so but aren't simple links; rbash, for instance.)
my $cmd;
+ my $man_cmd = "lintian-man -l";
if ($file =~ m,^(.*)/(mand/.*)$,) {
- $cmd = "cd unpacked/Q$1E && man -l Q$2E";
+ $cmd = "cd unpacked/Q$1E && $man_cmd Q$2E";
} else {
- $cmd = "man -l unpacked/Q$fileE";
+ $cmd = "$man_cmd unpacked/Q$fileE";
}
my $pid = open MANERRS, '-|';
if (not defined $pid) {
@@ -282,7 +283,7 @@
}
chomp;
s/^[^:]+://o;
- tag "manpage-has-errors-from-man", "$file", "$_";
+ tag "manpage-has-messages-from-lintian-man", "$file", "$_";
last;
}
close(MANERRS);
--- lintian-1.23.36/checks/manpages.desc 2007-06-21 15:48:26.000000000 +0700
+++ lintian-1.23.36-groff-hack/checks/manpages.desc 2007-11-21 21:16:26.000000000 +0600
@@ -120,9 +120,12 @@
Please double-check the manual page and replace the template language
with specific information about this program.

-Tag: manpage-has-errors-from-man
+Tag: manpage-has-messages-from-lintian-man
Type: warning
-Info: This man page provokes warnings or errors from man.
+Info: This man page provokes warnings or errors from lintian-man.
+ .
+ lintian-man is a helper script which behaves like man, but with Groff
+ warnings (-wman) explicitly enabled.
.
"cannot adjust" or "can't break" are trouble with paragraph filling,
usually related to long lines. Adjustment can be helped by left
--- lintian-1.23.36/debian/rules 2006-11-19 07:11:32.000000000 +0600
+++ lintian-1.23.36-groff-hack/debian/rules 2007-11-21 21:18:13.000000000 +0600
@@ -43,9 +43,12 @@
install -m 755 frontend/lintian $(tmp)/usr/bin/
sed -i 's/<VERSION>/$(VER)/' $(tmp)/usr/bin/lintian
install -m 755 frontend/lintian-info $(tmp)/usr/bin/
+# helper scripts
+ @echo .... install helper scripts ....
+ install -m 755 frontend/lintian-man $(tmp)/usr/bin/
# library files
@echo .... install library files ....
- for d in checks collection lib unpack; do
+ for d in checks collection lib unpack groff-hacks; do
install -d $(usl)/$$d;
find $$d -type f ! -path '*/CVS/*' ! -path '*/.svn/*'
| xargs -iFILE cp -p FILE $(usl)/$$d/;
--- lintian-1.23.36/frontend/lintian-man 1970-01-01 07:00:00.000000000 +0700
+++ lintian-1.23.36-groff-hack/frontend/lintian-man 2007-11-21 21:16:48.000000000 +0600
@@ -0,0 +1,5 @@
+#!/bin/sh
+: ${LINTIAN_ROOT:=/usr/share/lintian}
+export
+ GROFF_TMAC_PATH="${LINTIAN_ROOT}${GROFF_TMAC_PATH: +:}${GROFF_TMAC_PATH}"
+exec man "$@"
--- lintian-1.23.36/groff-hacks/man.local 1970-01-01 07:00:00.000000000 +0700
+++ lintian-1.23.36-groff-hack/groff-hacks/man.local 2007-11-21 21:27:56.000000000 +0600
@@ -0,0 +1,4 @@
+.warn 512
+.mso /usr/share/groff/site-tmac/man.local
+.de IX
+..
--- lintian-1.23.36/groff-hacks/mdoc.local 1970-01-01 07:00:00.000000000 +0700
+++ lintian-1.23.36-groff-hack/groff-hacks/mdoc.local 2007-11-21 21:27:45.000000000 +0600
@@ -0,0 +1,4 @@
+.warn 512
+.mso /usr/share/groff/site-tmac/mdoc.local
+.de IX
+..


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 11-21-2007, 03:36 PM
David Weinehall
 
Default Bug#377392: Bug#450432: ... and even more bugs like this?

On Wed, Nov 21, 2007 at 09:33:49PM +0600, Ivan Shmakov wrote:
[snip]
> A helper script, `lintian-man', could be introduced to hide all
> the hackery, and to provide a way for the developer to reproduce
> the problem. Then, Tag: may be changed to, e. g.,
> `manpage-has-messages-from-lintian-man'. (Or should this script
> be called `man-lintian'?)

[snip]

Sounds like a great idea in general. But: correct manual pages is not
something that is specific to debian packages, so maybe manlint would be
a better idea, also having it as a part of the man-db package instead
might be an idea. lintian already depends on man-db, so the
dependencies wouldn't change, and it would also mean that linda can use
the same check without code duplication.


Regards: David
--
/) David Weinehall <tao@debian.org> /) Rime on my window (
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ // Diamond-white roses of fire //
) http://www.acc.umu.se/~tao/ (/ Beautiful hoar-frost (/


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 11-23-2007, 12:16 PM
Ivan Shmakov
 
Default Bug#377392: Bug#450432: ... and even more bugs like this?

>>>>> David Weinehall <tao@debian.org> writes:

>> A helper script, `lintian-man', could be introduced to hide all
>> the hackery, and to provide a way for the developer to reproduce
>> the problem. Then, Tag: may be changed to, e. g.,
>> `manpage-has-messages-from-lintian-man'. (Or should this script
>> be called `man-lintian'?)

> [snip]

> Sounds like a great idea in general. But: correct manual pages is
> not something that is specific to debian packages, so maybe manlint
> would be a better idea, also having it as a part of the man-db
> package instead might be an idea.

Well, one might then implement a generic method of passing Groff
options via `man', thus obviating the need to override the
`man.local' and `mdoc.local'. How about an environment variable
(say, `MANROFFOPT' or `MANGROFFOPT')?

> lintian already depends on man-db, so the dependencies wouldn't
> change, and it would also mean that linda can use the same check
> without code duplication.


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
 
Old 11-23-2007, 08:36 PM
Ivan Shmakov
 
Default Bug#377392: Bug#450432: ... and even more bugs like this?

>>>>> Ivan Shmakov <ivan@theory.asu.ru> writes:
>>>>> David Weinehall <tao@debian.org> writes:

>>> A helper script, `lintian-man', could be introduced to hide all the
>>> hackery, and to provide a way for the developer to reproduce the
>>> problem. Then, Tag: may be changed to, e. g.,
>>> `manpage-has-messages-from-lintian-man'. (Or should this script be
>>> called `man-lintian'?)

>> [snip]

>> Sounds like a great idea in general. But: correct manual pages is
>> not something that is specific to debian packages, so maybe manlint
>> would be a better idea, also having it as a part of the man-db
>> package instead might be an idea.

Since the tool should behave like *man* with *w*arnings
*e*nabled, I'd call it `manwe'...

I've just submitted a patch for Bug#451187.

> Well, one might then implement a generic method of passing Groff
> options via `man', thus obviating the need to override the
> `man.local' and `mdoc.local'. How about an environment variable
> (say, `MANROFFOPT' or `MANGROFFOPT')?

Done as well.

>> lintian already depends on man-db, so the dependencies wouldn't
>> change, and it would also mean that linda can use the same check
>> without code duplication.


--
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 01:39 AM.

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