On Wed, Oct 21, 2009 at 01:02:26AM +0200, Frank Lin PIAT wrote:
> On Tue, 2009-10-20 at 07:17 +0200, Frank Lin PIAT wrote:
> > I have written a small script to make it easy to submit manpage
> > improvements (it's attached).
> > I believe that it much more effective to submit a patch, rather than
> > explaining what needs to be improved. The tool works like quilt...
> [..]
> > There is one issue: most of the bugs will have to be forwarded
> > upstream.[..]
> >
> > I would get your opinions on how to make this useful/convenient.
1/ l10n:
The current script fails when the manpage is available in both english
and $LANG, because it doesn't keep track for the whole filename
while it could be an opportunity to get feedback no either of
the languages, hence a patch proposal attached, which lets the user
select the exact manpage he wants to patch.
In case of translated manpage, the report may be sent to the right l10n
list instead ?
2/ Format:
One has to remember that such a patch will almost never be
usable as is, because of the source format used to generated this
manpage, either groff directly, or perldoc, po4a, etc.
> I have received some feedback from a developer who is concerned about
> having to deal with the contribution from "nitpickers". I must admit
> that I am concern with bikeshedding and nitpicking too.
I don't think that nitpickers did wait for such a tool to nitpick.
> I had a few ideas... (so far)
>
> A. We could have a different work-flow for (non)-native package:
> - For non-native package, we could instruct people to submit the
> diff-file to the upstream maintainer.
I guess that such a behaviour should actually be a warning in reportbug,
if ever the ideas in thread "Per-package link to upstreams bugtracker" #551386
> - For native package, we could file a bug in Debian BTS.
Option A sound the better to me.
> B. We could provide a way so maintainer could declare whether
> the bug should be filed upstream or to the BTS.
>
> C. We could ship the tool in a package that is usually installed
> by developers only (shipping the script in a package like
> devscripts, rather than installing it by default)
>
> Option A and C looks interesting...
--
Simon Paillard
--- man-reportbug.orig 2009-10-21 22:21:25.000000000 +0200
+++ man-reportbug 2009-10-22 00:50:03.000000000 +0200
@@ -124,32 +124,50 @@
fi
# Parse argument(s)
-file=
-COUNT=0
-for file in $(man -a -w $section $page); do
- f="$(echo $file| xargs -r -n 1 basename | sed -e 's/\..z$//' -e's/\./|/')"
- basename=$(basename $file | sed -e 's/\..z$//')
- section=${f#*|}
- name=${f%|*}
- apropos -e -s $section $name | grep -E "^$name\>\s*\($section\)"
- COUNT=$(($COUNT + 1))
-done
+files=($(man -a -w $section $page))
+COUNT=(${#files[*]})
+
+LINE_INDEX=1
+if [ "$section" ]; then
+ man -f $page -s $section | while read LINE ;
+ do echo -e "Result $LINE_INDEX:\t $LINE" ;
+ LINE_INDEX=$(($LINE_INDEX + 1))
+ done
+else
+ man -f $page | while read LINE ;
+ do echo -e "Result $LINE_INDEX:\t $LINE" ;
+ LINE_INDEX=$(($LINE_INDEX + 1))
+ done
+fi
if [ $COUNT -eq 0 ]; then
# man would already print "No manual entry for XXXX"
quit 1
elif [ $COUNT -gt 1 ]; then
- echo "Aborting, there are more than one manpage matching your criteria." >&2
- quit 1
+ MANPAGE_INDEX=-1
+ # TODO: check that MANPAGE_INDEX is actually a number
+ while [ $MANPAGE_INDEX -ge $COUNT -o $MANPAGE_INDEX -lt 0 ] ;
+ do
+ echo "There are more than one manpage matching your criteria, select:"
+ read MANPAGE_INDEX
+ MANPAGE_INDEX=$(($MANPAGE_INDEX - 1))
+ done
fi
+echo ${files[*]}
+file=${files[$MANPAGE_INDEX]}
+basename=$(basename $file | sed -e 's/\..z$//')
+section=${f#*|}
+name=${f%|*}
# Searching for the package providing the manpage.
-if [ "$(dpkg-divert --listpackage $file)" ]; then
+if [ -e /usr/bin/dpkg-divert ]; then
+ if [ -a "$(dpkg-divert --listpackage $file)" ]; then
diverted=true
pkg=$(dpkg-divert --listpackage $file)
echo "This file is diverted by package $pkg"
+ fi
else
diverted= ###false###
printf "Searching which package ships the file $f\r"
@@ -188,8 +206,11 @@
MSG
(
cd $workdir
- reportbug --offline --no-query-source --no-config-files \
- -P 'Usertags: man-reportbug' --include=NOTE \
+ if [ ! $(dirname $(dirname $file)) = "/usr/share/man" ] ; then
+ tag="--tag=l10n"
+ fi
+ reportbug --offline --patch --no-query-source --no-config-files \
+ -P 'Usertags: man-reportbug' $tag --include=NOTE \
--attach=$diff --attach=$orig $pkg
)
else
#!/bin/sh
# man-reportbug - A simple to contribute manpage improvement
#
## Copyright (C) 2009 Frank Lin PIAT <fp...@klabs.be>
##
## All rights reserved.
##
## Redistribution and use in source and binary forms, with or without
## modification, are permitted provided that the following conditions
## are met:
## 1. Redistributions of source code must retain the above copyright
## notice, this list of conditions and the following disclaimer.
## 2. Redistributions in binary form must reproduce the above copyright
## notice, this list of conditions and the following disclaimer in the
## documentation and/or other materials provided with the distribution.
## 3. Neither the name of the Copyright holder nor the names of the
## contributors may be used to endorse or promote products derived
## from this software without specific prior written permission.
##
## THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
## ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
## LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
## PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
##Â HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
##Â SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
## TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
## PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
## LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
## NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
## SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
# ---------------------------- End of license ------------------------------
# TODO
# - handle alternatives
set -e
# ######################## FUNCTIONS ###########################
help() {
cat <<XXX
Usage: $progname [SECTION] MANPAGE
$progname [-h|-l|-V]
man-reportbug - A simple tool to contribute manpage improvement.
MANPAGE
The manual page you want to suggest improvements.
SECTION
The man section of the manpage. See (1)man.
Options:
-h Print this message and exit
-l Print the license and exit
-V Print version information.
See the $progname(1) manual page for more information.
XXX
}
# Display this script's license.
license() {
sed -n -e '/##/,/^#.*End of License/s/^## //p' $0
}
# Routine to cleanly exit
quit() {
[ "$2" ] && echo "$2" >&2
# Clean-up temp files
for x in $old $new $diff; do
[ -f $x ] && rm $x
done
[ -d "$workdir" ] && rmdir $workdir
exit $1
}
# ########################### MAIN ##############################
progname=$(basename $0)
version=0.02
old=
new=
diff=
workdir=
# Parse options
while getopts Vlh f;do
case $f in
h)
help
quit
;;
l)
license
quit
;;
V)
echo "$progname $version"
quit
;;
*)
quit 1 "Invalid option: '$f'"
esac
shift $(expr $OPTIND - 1)
done
# Parse arguments
[ "$3" ] && quit "Unexpected argument '$3'"
if [ "$2" ]; then
section=$1
shift
else
section=
fi
if [ "$1" ]; then
page=$1
else
quit 1 "No manpage specified"
fi
# Parse argument(s)
files=($(man -a -w $section $page))
COUNT=(${#files[*]})
LINE_INDEX=1
if [ "$section" ]; then
man -f $page -s $section | while read LINE ;
do echo -e "Result $LINE_INDEX:\t $LINE" ;
LINE_INDEX=$(($LINE_INDEX + 1))
done
else
man -f $page | while read LINE ;
do echo -e "Result $LINE_INDEX:\t $LINE" ;
LINE_INDEX=$(($LINE_INDEX + 1))
done
fi
if [ $COUNT -eq 0 ]; then
# man would already print "No manual entry for XXXX"
quit 1
elif [ $COUNT -gt 1 ]; then
MANPAGE_INDEX=-1
# TODO: check that MANPAGE_INDEX is actually a number
while [ $MANPAGE_INDEX -ge $COUNT -o $MANPAGE_INDEX -lt 0 ] ;
do
echo "There are more than one manpage matching your
criteria, select:"
read MANPAGE_INDEX
MANPAGE_INDEX=$(($MANPAGE_INDEX - 1))
done
fi
echo ${files[*]}
file=${files[$MANPAGE_INDEX]}
basename=$(basename $file | sed -e 's/\..z$//')
section=${f#*|}
name=${f%|*}
# Searching for the package providing the manpage.
if [ -e /usr/bin/dpkg-divert ]; then
if [ -a "$(dpkg-divert --listpackage $file)" ]; then
diverted=true
pkg=$(dpkg-divert --listpackage $file)
echo "This file is diverted by package $pkg"
fi
else
diverted= ###false###
printf "Searching which package ships the file $f\r"
pkg=$(dpkg -S $file | cut -d ':' -f 1)
echo "This file comes from package $pkg "
fi
# Let's edit the page
trap "quit 128 'exiting: signal caught.'" HUP INT QUIT BUS PIPE TERM
workdir=$(mktemp -d -t $progname.$basename.XXX) || {
echo "$progname: Unable to create temporary file; aborting" >&2
quit 1
}
orig=$workdir/$name.$section.orig
new=$workdir/$name.$section
diff=$workdir/$name.$section.diff
man -Tutf8 -l "$file" | sed -e 's/.//g'> $orig
cp $orig $new
editor $new
changed=
diff -u $orig $new > $diff || changed=true
# Let's file a bug
if [ -f $diff -a "$changed" ]; then
echo Invoking reportbug...
cat > $workdir/NOTE <<MSG
Please find attached a suggested improvement for the manpage:
$file
(The diff file [$(basename $diff)] was generated against the output
of 'man -Tutf8 $section $name', which is also attached for
referenced [$(basename $orig)]).
***
MSG
(
cd $workdir
if [ ! $(dirname $(dirname $file)) = "/usr/share/man" ] ; then
tag="--tag=l10n"
fi
reportbug --offline --patch --no-query-source --no-config-files \
-P 'Usertags: man-reportbug' $tag --include=NOTE \
--attach=$diff --attach=$orig $pkg
)
else
echo Canceled
fi
