Subject: Re: [9front] Re: man pages

From: qwx <[email-masked]>
Date: Tue, 24 Aug 2021 22:27:53 +0200

> Once again I am asking for your support
> 
> On 14/08/2021, Stuart Morrow <[email-masked]> wrote:
> > 'UTF' appears in small caps throughout the manual, so this makes
> > uhtml(1) consistent. It's relative to the uhtml earlier in this
> > thread.
> >
> > diffy /sys/man/1/uhtml
> > 24c24,26
> > < to convert it to UTF replacing HTML-entity forms
> > ---
> >> to convert it to
> >> .SM UTF
> >> replacing HTML-entity forms
> >

Hi,

I think this is ok, but I see plenty of other instances of this,
just run `grep -i utf /sys/man/*/*'.  I'd fix them as well all
at once.  I'm sure there are all of sorts of inconsistencies all
over the place, but expecting anyone to review and fix everything
at once is too much, it won't happen.  If you see any others
right now, it would be nice to fix them too, in my opinion.

Cheers,

qwx

---

From: Stuart Morrow <[email-masked]>
Date: Tue, 24 Aug 2021 22:02:29 +0100

I was referring to the first post in the thread, with the 12K attachment.

Those diffs were at that time already a month old and ignored.

---

From: hiro <[email-masked]>
Date: Tue, 24 Aug 2021 23:09:50 +0200

i don't think i ever received your first post in the thread

---

From: Humm <[email-masked]>
Date: Tue, 24 Aug 2021 23:20:08 +0200

> I'm sure there are all of sorts of inconsistencies all over the 
> place, but expecting anyone to review and fix everything at once is 
> too much, it won't happen.

Oh yes, there are.  What comes to mind immediately is citation style 
and handling of options in SYNOPSIS (sometimes all are listed and 
sometimes there is just “[options]”), as well as just bad troff.  
There are some checks for bad stuff (see for example `mk punccheck` in 
/sys/man).

-- 
Humm

---

From: qwx <[email-masked]>
Date: Tue, 24 Aug 2021 23:49:37 +0200

I pushed part of your changes.  Some I rejected on my own
accord.  My earlier point stands, there are many more
instances of UTF and other shit that you didn't touch.
Moreover, if we do this for `UTF', why not `HTML' or `USB'
or whatever?

Thanks for bumping this, and any further changes are
welcome.

> There are some checks for bad stuff (see for example `mk punccheck` in 

As always, patches welcome.

Thanks,

qwx

---

From: [email-masked]
Date: Tue, 24 Aug 2021 17:34:43 -0400

> Those diffs were at that time already a month old and ignored.

Thanks for pinging.

So, lots of these look like some bike-shedding
for the sake of bike-shedding, without really
improving the quality of the documentation.

For example, is 'foreign-character-set' really
an improvement over 'foreign character-set'?
Is character-set an improvement over character set?

I think both changes are worse.

On the other hand, there are actual fixes
for omissions, like:

	-.B "newdev {low|full|high} \fIport\fP
	+.B "newdev {low|full|high|super} \fIport\fP

and styling issues like:

	-.I str ,
	+.IR str ,

If I could have this without the bikeshedding,
that would have been ideal.

Anyways, I think qwx is looking at this patch,
so I'll let them handle it.

---

From: Stuart Morrow <[email-masked]>
Date: Wed, 25 Aug 2021 00:42:06 +0100

> Is character-set an improvement over character set?

There's no way I can respond to this without it being further bikeshedding.

---

From: Stuart Morrow <[email-masked]>
Date: Tue, 24 Aug 2021 18:21:08 +0100

---

From: Stuart Morrow <[email-masked]>
Date: Tue, 24 Aug 2021 22:33:09 +0100

http://okturing.com/src/11943/body

---

From: [email-masked]
Date: Tue, 24 Aug 2021 21:02:40 -0400

> There's no way I can respond to this without it being further bikeshedding.

Sure.

It'd be helpful to separate incorrect formatting
from wording tweaks, if you're willing to go to
that effort.

And, thanks for sending in the fixes.

---

From: [email-masked]
Date: Tue, 24 Aug 2021 23:18:49 -0400

> There are some checks for bad stuff (see for example `mk punccheck` in 

yes, for sure.

it helps me out if I get patches that focus on
one kind of issue: I have to keep less in mind
when reviewing, and format fixes are going to
get less debate than phrasing changes; I like it
when I can land fixes immediately.

---

From: hiro <[email-masked]>
Date: Wed, 25 Aug 2021 11:37:22 +0200

ori is probably right, but calling it all bikeshedding is also not
fair IMO. hopefully i missed the irony :)

there have been some changes that regard stylistic choices, where
neither option is more correct than the other,

to add further bikeshedding, some few changes are inconsistent.
e.g. SuperSpeed should be superspeed or super-speed IMO to fit into
the rest of the sentence.

---

From: Stuart Morrow <[email-masked]>
Date: Wed, 25 Aug 2021 13:05:32 +0100

> from wording tweaks, if you're willing to go to

You mean in the files that remain untouched after the last commit?
Those would be
2/ioproc
8/ndb
8/venti-backup
and in fact I only ever sent formatting fixes for them:

--- //.git/fs/object/be36c092ac061a04065720e98e5849130487be7f/tree//sys/man/2/ioproc
+++ /sys/man/2/ioproc
@@ -92,7 +92,7 @@
 .PP
 .I Closeioproc
 terminates the I/O proc and frees the associated
-.B Ioproc .
+.BR Ioproc .
 .PP
 .I Iocall
 is a primitive that may be used to implement
--- //.git/fs/object/be36c092ac061a04065720e98e5849130487be7f/tree//sys/man/8/ndb
+++ /sys/man/8/ndb
@@ -764,7 +764,7 @@
 .PP
 .I Ndb/dnsgetip
 resolves and prints A and AAAA records without consulting
-.I ndb/dns .
+.IR ndb/dns .
 By default,
 .I ndb/dnsgetip
 queries A records first and then AAAA records. As with
--- //.git/fs/object/be36c092ac061a04065720e98e5849130487be7f/tree//sys/man/8/venti-backup
+++ /sys/man/8/venti-backup
@@ -66,7 +66,7 @@
 (default
 .BR 0 )
 in
-.I arenafile .
+.IR arenafile .
 This is useful for reading directly from
 the Venti arena partition:
 .IP

---

From: [email-masked]
Date: Wed, 25 Aug 2021 18:50:43 -0400

> You mean in the files that remain untouched after the last commit?

I'm not sure if I'm missing something, but these
changes appear to be in the last commit:

	cd /dist/plan9front \
		&& git/export ad26f82e44a5f59383edfde5f4c3727c225f4b0a \
		| grep (ioproc|ndb|venti-backup)

---

From: Stuart Morrow <[email-masked]>
Date: Thu, 26 Aug 2021 11:02:13 +0100

On 25/08/2021, [email-masked] <[email-masked]> wrote:
>  ... these changes appear to be in the last commit:

Yeah, you're right. Not sure how I worked that out (either the website
or 9front-commits, but they're both right, just count the number of
'+++'s).

So for what files am I supposed to separate troff/informational
changes from grammar ones?

In any case your reason for wanting them separate is sound; a patch
should do one thing, preferably well.

---

From: [email-masked]
Date: Thu, 26 Aug 2021 10:26:20 -0400

> changes from grammar ones?

future patches, if you find more issues and improvements.
I'm not asking you to rework anything that's been sent.