Bug#1120550: RFP: manpages-utils -- Various scripts provided by the Linux man-pages project
Package: wnpp
Severity: wishlist
X-Debbugs-Cc: Marcos Fouces <marcos@debian.org>, "Dr. Tobias Quathamer" <toddy@debian.org>
* Package name : manpages-utils
Version : 6.16
Upstream Contact: Alejandro Colomar <alx@kernel.org>
* URL : <https://www.kernel.org/doc/man-pages/>
* License : GPL-3.0-or-later
Programming Lang: sh(1), bash(1)
Description : Various scripts provided by the Linux man-pages project
These scripts are useful for anyone maintaining manual pages. For
example, they would help projects that have one or a few manual pages
for their program, but also helps maintainers of large documentation
projects.
Other scripts are more related to programming in general, rather than
just documentation.
At the moment, there are the following scripts:
diffman-git (1) - compare changes to manual pages line by line
grepc (1) - find declarations, definitions, and uses in source code
grepc_c (1) - print PCRE patterns for searching C code
mansect (1) - print the source code of sections of manual pages
pdfman (1) - render a manual page in PDF
sortman (1) - sort manual-page path names
(And there's also grepc_mk, which is yet undocumented, an is
an experimental driver for grepc(1).)
why is this package useful/relevant?
diffman-git(1) is very useful for verifying patches to manual
pages.
mansect(1) is useful to read specific sections of one or more
manual pages. I find it especially useful when unifying the
language of a section in a large number of manual pages, so I
can see the same section of the different pages together.
pdfman(1) opens a manual page in a PDF viewer, for those who
prefer to read it as a PDF (or for maintainers of manual pages,
to make sure their pages look good as a PDF).
sortman(1) is similar to sort(1), but it sorts manual page file
names in the order that they should appear in the manual. That
is, the intro(x) manual page is the first manual page in
section x, and then the rest of the pages of a section are
sorted alphabetically.
grepc(1) is similar to grep(1) --actually, more similar to
pcre2grep(1)--, but finds source code. For example:
alx@devuan:/usr/include$ grepc -n strcpy .
./string.h:141:extern char *strcpy (char *__restrict __dest, const char *__restrict __src)
__THROW __nonnull ((1, 2));
./mes/string.h:45:char *strcpy (char *dest, char const *src);
grepc_c(1) produces the PCRE2 patterns that grepc(1) uses for
finding C code. For example:
$ grepc_c -tfp strcpy
(?s)^[\w[](?:[\w\s\(,\)[\]*]|::)+[\w\s\)*\]]\s+\**\(?strcpy\)?\s*(?<params>\((?:[\w\s,;[\]*\?:+-]|(?¶ms))*(?:\.\.\.)?\))(?:[\w\s\(,\)[\]]|::)*;
It's necessary to implement grepc(1). (And it's useful to debug
grepc(1) when there's a bug in a regex.)
alx@devuan:/usr/include$ find . -type f \
| xargs pcre2grep -nM "$(grepc_c -tfp strcpy)";
./string.h:141:extern char *strcpy (char *__restrict __dest, const char *__restrict __src)
__THROW __nonnull ((1, 2));
./mes/string.h:45:char *strcpy (char *dest, char const *src);
is it a dependency for another package?
No.
do you use it?
Every day.
if there are other packages providing similar functionality, how does
it compare?
The only program that has something comparable is grepc(1).
ctags is something similar to it. However, grepc(1) is more
useful than ctags because it's a Unix filter. It gets input
from stdin or regular files, and produces output on stdout. You
can use it directly from the command line, in a pipeline.
grepc(1) also doesn't need to create and update an index, which
makes it possible to use it in a recently downloaded source code
directory. It can also be used in a pipeline combined with
git(1) to find out the definition of a function some years ago,
or even use diff(1) to compare a definition from some years ago
with now.
alx@devuan:~/src/shadow/shadow/master$ diff -u \
<(git show 3049bef9c3:lib/alloc/realloc.h | grepc -h REALLOC) \
<(cat lib/alloc/realloc.h | grepc -h REALLOC);
--- /dev/fd/63 2025-10-31 22:20:17.098318929 +0100
+++ /dev/fd/62 2025-10-31 22:20:17.098318929 +0100
@@ -1,4 +1,4 @@
-#define REALLOC(ptr, n, type) \
+#define REALLOC(p, n, type) \
( \
- _Generic(ptr, type *: (type *) reallocarray(ptr, n, sizeof(type))) \
+ _Generic(p, type *: (type *) reallocarray(p, (n) ?: 1, sizeof(type))) \
)
This is something I use every now and then while understanding
old bugs, and has proved very useful.
Here are a few example of links to shadow-utils discussions
where grepc(1) was helpful:
<https://github.com/shadow-maint/shadow/pull/1266#issue-3126573666>
<https://github.com/shadow-maint/shadow/pull/1116#issue-2649006344>
how do you plan to maintain it? inside a packaging team
(check list at https://wiki.debian.org/Teams)? are you
looking for co-maintainers? do you need a sponsor?
These scripts are part of the Linux man-pages project. Since
that is already packaged as src:manpages, I expect it would be
easy to just add a binary package in the same source package,
called manpages-utils.
I'd help as an upstream maintainer, but not directly as a
maintainer of the Debian package (although I want to help with
the packaging of the Debian packages of src:manpages
eventually), but never find the time. We'll see.
Have a lovely day!
Alex
Reply to: