Re: [PATCH v1 08/11] man/man3type/stat.3type: HISTORY: Specify first POSIX appearance of st_{rdev,blksize,blocks}

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 3578 bytes --]

Hi Seth,

On Fri, Jan 09, 2026 at 03:31:46AM +0000, Seth McDonald wrote:
> On Thursday, 8 January 2026 at 21:48, Alejandro Colomar <alx@kernel.org> wrote:
> > On Thu, Jan 08, 2026 at 01:03:14PM +1000, Seth McDonald wrote:
> > I think this would be simpler like this:
> >
> > 	@@ -135,7 +135,14 @@ .SH DESCRIPTION
> > 	.SH STANDARDS
> > 	POSIX.1-2024.
> > 	.SH HISTORY
> > 	+.TP
> > 	+.I stat
> > 	POSIX.1-1988.
> > 	+.TP
> > 	+.I .st_rdev
> > 	+.I .st_blksize
> > 	+.I .st_blocks
> > 	+SUSv1, POSIX.1-2001 XSI.

Apart from the TQs, I forgot to use one line for each.

> > 	.P
> > 	Old kernels and old standards did not support nanosecond timestamp fields.
> > 	Instead, there were three timestamp fields
> >
> > What do you think?
> 
> That would certainly work.  I initially thought about doing that, but
> decided against it since I hadn't at the time seen any other pages that
> list individual structure members in their history section.  But if
> you're on board with it, then I'll send in a v2 with this fixup.

You're right that I can't find any existing pages documenting individual
field members in STANDARDS or HISTORY, but I think it's fine and
desirable.

> Btw, I'll want to add in some '.TQ's between the listed members, as
> without it the formatting looks a little funny.

Sure; I forgot about them.  :-)

> 	$ MANWIDTH=64 man ./man3type/stat.3type | sed -n '/^HISTORY$/,+5p'
> 	HISTORY
> 	       stat   POSIX.1-1988.
> 
> 	       .st_rdev
> 	              .st_blksize .st_blocks SUSv1, POSIX.1-2001 XSI.

You may be interested in diffman-git(1).  I think it would help
reviewing your diffs.  Here's some example of how it works:

Considering the following diff:

	$ git diff
	diff --git i/man/man3type/stat.3type w/man/man3type/stat.3type
	index 44d45b4a5..1a99d1d0a 100644
	--- i/man/man3type/stat.3type
	+++ w/man/man3type/stat.3type
	@@ -135,7 +135,15 @@ .SH DESCRIPTION
	 .SH STANDARDS
	 POSIX.1-2024.
	 .SH HISTORY
	+.TP
	+.I stat
	 POSIX.1-1988.
	+.TP
	+.I .st_rdev
	+.I .st_blksize
	+.I .st_blocks
	+SUSv1,
	+POSIX.1-2001 XSI.
	 .P
	 Old kernels and old standards did not support nanosecond timestamp fields.
	 Instead, there were three timestamp fields

You can check the exact changes to the manual page:

	$ diffman-git 
	--- HEAD:man/man3type/stat.3type
	+++ ./man/man3type/stat.3type
	@@ -105,7 +105,10 @@ STANDARDS
	      POSIX.1‐2024.
	 
	 HISTORY
	-     POSIX.1‐1988.
	+     stat   POSIX.1‐1988.
	+
	+     .st_rdev
	+            .st_blksize .st_blocks SUSv1, POSIX.1‐2001 XSI.
	 
	      Old kernels and old standards did not support nanosecond timestamp fields.  In‐
	      stead, there were three timestamp fields ——.st_atime, .st_mtime, and .st_ctime——

For more documentation, see diffman-git(1), of course.  :)
It's provided in the repository, in case your distro doesn't provide it
yet.  You can install it with the usual

	$ make -R -j4 && sudo make -R -j4 install;

Or just run it from the repo, since it's a bash(1) script.  It's here:

	$ find * | grep diffman-git
	man/man1/diffman-git.1
	src/bin/diffman-git


> I'll also send in the next set of man3type patches with chronological
> ordering, at least as far as I can tell. :)

Thanks!

> 
> ----
> Seth McDonald.
> sethmcmail at pm dot me (mailing lists)
> 2336 E8D2 FEB1 5300 692C  62A9 5839 6AD8 9243 D369

I have a question: do you use mutt(1) or neomutt(1) by chance?


Have a lovely day!
Alex

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]