Package: wnpp Severity: wishlist X-Debbugs-Cc: Marcos Fouces <[email protected]>, "Dr. Tobias Quathamer" <[email protected]>
* Package name : manpages-utils Version : 6.16 Upstream Contact: Alejandro Colomar <[email protected]> * 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
