diffman(1)

Hi!

I've developed a new program (actually, a bash script) that diffs manual pages. I find it quite useful for quickly seeing differences between a page as installed in the system, and the file I'm working on. The output is diff -u of formatted manual pages (suitable for less -R).

You can find it here:
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=fa4743c43762cc3be4af9672ce12a7ed58f9a500>
and soon in the <kernel.org> repo.

The script is just a fancy version of

	diff -u \
	       <(man -w "$1" | xargs groff -man -Tutf8) \
	       <(man -w "$2" | xargs groff -man -Tutf8);

I had to make it fancier for error handling, since process substitution doesn't propagate errors (not even with set -Eeo pipefail).

You may find it useful for development of manual pages. If so, please let me know any feedback you have for it. I was wondering if I should pipe to less -R, just like man(1) does. For now, having doubts, I kept it simple, which would allow wrapping this in fancier scripts that for exaple diff an entire repository of manual pages (although that maybe calls for running groff(1) and diff(1) directly).

Have a lovely day!
Alex

<https://www.alejandro-colomar.es/>

I've decided to keep it without piping to less(1). For piping, I'll let users write their own wrapper, since it's trivial. I've called mine duffman, which is like diffman(1), but with more fun. :-)

	$ which duffman | xargs cat
	#!/bin/bash

	set -Eeuo pipefail;

	diffman $@ | less -R;

duffman is not in the repo for now.

<https://www.alejandro-colomar.es/>

Hi Alejandro,

less simply pipes the data through if it's not at the end of a pipeline, so piping the diff's output to less -R shouldn't complicate use in scripts in any way (except perhaps for escape sequences if you use color).

  $ less -R /usr/include/stdio.h | grep -E '^#' | wc -l
  241
  $ sed -E "s/^/$(printf '\033[1m')/; s/\$/$(printf '\033[m')/" \
      /usr/include/stdio.h | less -R | wc -l
  985

~ onf

Hi onf,

I've seen less(1) cause issues when called in a while loop. And indeed, there's good reasons for calling this in a loop. Here's a useful wrapper I came up with after writing this email:

	$ tail -n19 scripts/bash_aliases 
	# diff all modified pages against the system ones.

	duffman()
	{
		cd $(git rev-parse --show-toplevel);

		git diff --name-only \
		| grep -E \
		   '(\.[[:digit:]]([[:alpha:]][[:alnum:]]*)?\>|\.man)+(\.man|\.in)*$' \
		| sortman \
		| while read f; do \
			local sys="$(basename "$f")";

			diffman "$sys" "$f";
		done \
		| less -R;

		cd -;
	}

Have a lovely day!
Alex

<https://www.alejandro-colomar.es/>

Hi!

I have added a duffman(1) program (script) to the Linux man-pages repo. It is similar to diffman(1), but it diffs the git working directory (or a commit, if specified).

Here are a couple of examples.

A change in the working directory:

	alx@devuan:~/src/linux/man-pages/man-pages/contrib$ git diff
	diff --git i/man/man3/printf.3 w/man/man3/printf.3
	index 2129e26dc..a379ae609 100644
	--- i/man/man3/printf.3
	+++ w/man/man3/printf.3
	@@ -24,7 +24,7 @@ .SH SYNOPSIS
	 .nf
	 .B #include <stdio.h>
	 .P
	-.BI "int printf(const char *restrict " format ", ...);"
	+.BI "int foo(const char *restrict " format ", ...);"
	 .BI "int fprintf(FILE *restrict " stream ,
	 .BI "            const char *restrict " format ", ...);"
	 .BI "int dprintf(int " fd ,
	alx@devuan:~/src/linux/man-pages/man-pages/contrib$ duffman 
	--- HEAD:man/man3/printf.3
	+++ man/man3/printf.3
	@@ -10,7 +10,7 @@
	 SYNOPSIS
	      #include <stdio.h>

- int printf(const char *restrict format, ...);
+ int foo(const char *restrict format, ...);
int fprintf(FILE *restrict stream,
const char *restrict format, ...);
int dprintf(int fd,

(The actual output includes bold and italics.)

And with an old commit:

	alx@devuan:~/src/linux/man-pages/man-pages/contrib$ git show 437e4afec6ca
	commit 437e4afec6cae16ba75587f835acee1e251f2e75
	Author: Alejandro Colomar <[email protected]>
	Date:   Sun Jan 5 13:44:32 2025 +0100

	    man/man3/sem_open.3: SYNOPSIS: This is a variadic function
	    
	    Specify the prototype consistently with open(2).
	    
	    Signed-off-by: Alejandro Colomar <[email protected]>

	diff --git a/man/man3/sem_open.3 b/man/man3/sem_open.3
	index 6a2aceb50..35275a024 100644
	--- a/man/man3/sem_open.3
	+++ b/man/man3/sem_open.3
	@@ -15,9 +15,8 @@ .SH SYNOPSIS
	 .BR "#include <sys/stat.h>" "        /* For mode constants */"
	 .B #include <semaphore.h>
	 .P
	-.BI "sem_t *sem_open(const char *" name ", int " oflag );
	-.BI "sem_t *sem_open(const char *" name ", int " oflag ,
	-.BI "                mode_t " mode ", unsigned int " value );
	+.BI "sem_t *sem_open(const char *" name ", int " oflag ", ..."
	+.BI "                \fR/*\fP mode_t " mode ", unsigned int " value " \fR*/\fP );"
	 .fi
	 .SH DESCRIPTION
	 .BR sem_open ()
	alx@devuan:~/src/linux/man-pages/man-pages/contrib$ duffman 437e4afec6ca
	--- 437e4afec6ca^:man/man3/sem_open.3
	+++ 437e4afec6ca:man/man3/sem_open.3
	@@ -11,9 +11,8 @@
	      #include <sys/stat.h>        /* For mode constants */
	      #include <semaphore.h>
	 
	-     sem_t *sem_open(const char *name, int oflag);
	-     sem_t *sem_open(const char *name, int oflag,
	-                     mode_t mode, unsigned int value);
	+     sem_t *sem_open(const char *name, int oflag, ...
	+                     /* mode_t mode, unsigned int value */ );
	 
	 DESCRIPTION
	      sem_open()  creates  a new POSIX semaphore or opens an existing semaphore.

I found this very useful for reviewing changes. Maybe you do too. :)

Have a lovely day!
Alex

<https://www.alejandro-colomar.es/>

Hi Alex,

Where? I don't see it here:
https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/tree/scripts
nor here:
https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/tree/src/bin
nor here:
https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/scripts
or here:
https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/src/bin

~ onf

Hi onf,

It's on the contrib branch still. I haven't pushed to main yet.

I renamed it to diffman-git yesterday, BTW.

<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/tree/src/bin/diffman-git?h=contrib>
Plain text:
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/plain/src/bin/diffman-git?h=contrib>

Have a lovely day!
Alex

<https://www.alejandro-colomar.es/>

Hi Alex,

Ah, I see. Thanks!

~ onf