9front - general discussion about 9front
 help / color / mirror / Atom feed
* [9front] Re: man pages
       [not found] <CABB-WO9mMVTigW9s96s88nPvA8fEijD6m-K_aR-=cMvDG363dQ@mail.gmail.com>
@ 2021-08-14 16:56 ` Stuart Morrow
  2021-08-24 17:21   ` Stuart Morrow
  0 siblings, 1 reply; 18+ messages in thread
From: Stuart Morrow @ 2021-08-14 16:56 UTC (permalink / raw)
  To: 9front

'UTF' appears in small caps throughout the manual, so this makes
uthml(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

^ permalink raw reply	[flat|nested] 18+ messages in thread

* [9front] Re: man pages
  2021-08-14 16:56 ` [9front] Re: man pages Stuart Morrow
@ 2021-08-24 17:21   ` Stuart Morrow
  2021-08-24 20:27     ` qwx
  0 siblings, 1 reply; 18+ messages in thread
From: Stuart Morrow @ 2021-08-24 17:21 UTC (permalink / raw)
  To: 9front

Once again I am asking for your support

On 14/08/2021, Stuart Morrow <morrow.stuart@gmail.com> 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
>

^ permalink raw reply	[flat|nested] 18+ messages in thread

* Re: [9front] Re: man pages
  2021-08-24 17:21   ` Stuart Morrow
@ 2021-08-24 20:27     ` qwx
  2021-08-24 21:02       ` Stuart Morrow
  2021-08-24 21:20       ` Humm
  0 siblings, 2 replies; 18+ messages in thread
From: qwx @ 2021-08-24 20:27 UTC (permalink / raw)
  To: 9front

> Once again I am asking for your support
> 
> On 14/08/2021, Stuart Morrow <morrow.stuart@gmail.com> 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

^ permalink raw reply	[flat|nested] 18+ messages in thread

* Re: [9front] Re: man pages
  2021-08-24 20:27     ` qwx
@ 2021-08-24 21:02       ` Stuart Morrow
  2021-08-24 21:09         ` hiro
                           ` (2 more replies)
  2021-08-24 21:20       ` Humm
  1 sibling, 3 replies; 18+ messages in thread
From: Stuart Morrow @ 2021-08-24 21:02 UTC (permalink / raw)
  To: 9front

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.

^ permalink raw reply	[flat|nested] 18+ messages in thread

* Re: [9front] Re: man pages
  2021-08-24 21:02       ` Stuart Morrow
@ 2021-08-24 21:09         ` hiro
  2021-08-24 21:13           ` Stuart Morrow
  2021-08-24 21:33           ` Stuart Morrow
  2021-08-24 21:34         ` ori
  2021-08-24 21:49         ` qwx
  2 siblings, 2 replies; 18+ messages in thread
From: hiro @ 2021-08-24 21:09 UTC (permalink / raw)
  To: 9front

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

On 8/24/21, Stuart Morrow <morrow.stuart@gmail.com> wrote:
> 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.
>

^ permalink raw reply	[flat|nested] 18+ messages in thread

* Re: [9front] Re: man pages
  2021-08-24 21:09         ` hiro
@ 2021-08-24 21:13           ` Stuart Morrow
  2021-08-24 21:33           ` Stuart Morrow
  1 sibling, 0 replies; 18+ messages in thread
From: Stuart Morrow @ 2021-08-24 21:13 UTC (permalink / raw)
  To: 9front

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



[-- Attachment #2: diff --]
[-- Type: application/octet-stream, Size: 11970 bytes --]

^ permalink raw reply	[flat|nested] 18+ messages in thread

* Re: [9front] Re: man pages
  2021-08-24 20:27     ` qwx
  2021-08-24 21:02       ` Stuart Morrow
@ 2021-08-24 21:20       ` Humm
  2021-08-25  3:18         ` ori
  1 sibling, 1 reply; 18+ messages in thread
From: Humm @ 2021-08-24 21:20 UTC (permalink / raw)
  To: 9front

> 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

^ permalink raw reply	[flat|nested] 18+ messages in thread

* Re: [9front] Re: man pages
  2021-08-24 21:09         ` hiro
  2021-08-24 21:13           ` Stuart Morrow
@ 2021-08-24 21:33           ` Stuart Morrow
  1 sibling, 0 replies; 18+ messages in thread
From: Stuart Morrow @ 2021-08-24 21:33 UTC (permalink / raw)
  To: 9front

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

^ permalink raw reply	[flat|nested] 18+ messages in thread

* Re: [9front] Re: man pages
  2021-08-24 21:02       ` Stuart Morrow
  2021-08-24 21:09         ` hiro
@ 2021-08-24 21:34         ` ori
  2021-08-24 23:42           ` Stuart Morrow
  2021-08-24 21:49         ` qwx
  2 siblings, 1 reply; 18+ messages in thread
From: ori @ 2021-08-24 21:34 UTC (permalink / raw)
  To: 9front

Quoth Stuart Morrow <morrow.stuart@gmail.com>:
> 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.
> 

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.


^ permalink raw reply	[flat|nested] 18+ messages in thread

* Re: [9front] Re: man pages
  2021-08-24 21:02       ` Stuart Morrow
  2021-08-24 21:09         ` hiro
  2021-08-24 21:34         ` ori
@ 2021-08-24 21:49         ` qwx
  2 siblings, 0 replies; 18+ messages in thread
From: qwx @ 2021-08-24 21:49 UTC (permalink / raw)
  To: 9front

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.

> 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

As always, patches welcome.

Thanks,

qwx

^ permalink raw reply	[flat|nested] 18+ messages in thread

* Re: [9front] Re: man pages
  2021-08-24 21:34         ` ori
@ 2021-08-24 23:42           ` Stuart Morrow
  2021-08-25  1:02             ` ori
  0 siblings, 1 reply; 18+ messages in thread
From: Stuart Morrow @ 2021-08-24 23:42 UTC (permalink / raw)
  To: 9front

> 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?

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

^ permalink raw reply	[flat|nested] 18+ messages in thread

* Re: [9front] Re: man pages
  2021-08-24 23:42           ` Stuart Morrow
@ 2021-08-25  1:02             ` ori
  2021-08-25 12:05               ` Stuart Morrow
  0 siblings, 1 reply; 18+ messages in thread
From: ori @ 2021-08-25  1:02 UTC (permalink / raw)
  To: 9front

Quoth Stuart Morrow <morrow.stuart@gmail.com>:
> > 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?
> 
> 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.


^ permalink raw reply	[flat|nested] 18+ messages in thread

* Re: [9front] Re: man pages
  2021-08-24 21:20       ` Humm
@ 2021-08-25  3:18         ` ori
  2021-08-25  9:37           ` hiro
  0 siblings, 1 reply; 18+ messages in thread
From: ori @ 2021-08-25  3:18 UTC (permalink / raw)
  To: 9front

Quoth Humm <hummsmith42@gmail.com>:
> > 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).

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.


^ permalink raw reply	[flat|nested] 18+ messages in thread

* Re: [9front] Re: man pages
  2021-08-25  3:18         ` ori
@ 2021-08-25  9:37           ` hiro
  0 siblings, 0 replies; 18+ messages in thread
From: hiro @ 2021-08-25  9:37 UTC (permalink / raw)
  To: 9front

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.

On 8/25/21, ori@eigenstate.org <ori@eigenstate.org> wrote:
> Quoth Humm <hummsmith42@gmail.com>:
>> > 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).
>
> 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.
>
>

^ permalink raw reply	[flat|nested] 18+ messages in thread

* Re: [9front] Re: man pages
  2021-08-25  1:02             ` ori
@ 2021-08-25 12:05               ` Stuart Morrow
  2021-08-25 22:50                 ` ori
  0 siblings, 1 reply; 18+ messages in thread
From: Stuart Morrow @ 2021-08-25 12:05 UTC (permalink / raw)
  To: 9front

On 25/08/2021, ori@eigenstate.org <ori@eigenstate.org> wrote:
> It'd be helpful to separate incorrect formatting
> from wording tweaks, if you're willing to go to
> that effort.

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

^ permalink raw reply	[flat|nested] 18+ messages in thread

* Re: [9front] Re: man pages
  2021-08-25 12:05               ` Stuart Morrow
@ 2021-08-25 22:50                 ` ori
  2021-08-26 10:02                   ` Stuart Morrow
  0 siblings, 1 reply; 18+ messages in thread
From: ori @ 2021-08-25 22:50 UTC (permalink / raw)
  To: 9front

Quoth Stuart Morrow <morrow.stuart@gmail.com>:
> On 25/08/2021, ori@eigenstate.org <ori@eigenstate.org> wrote:
> > It'd be helpful to separate incorrect formatting
> > from wording tweaks, if you're willing to go to
> > that effort.
> 
> You mean in the files that remain untouched after the last commit?
> Those would be

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)


^ permalink raw reply	[flat|nested] 18+ messages in thread

* Re: [9front] Re: man pages
  2021-08-25 22:50                 ` ori
@ 2021-08-26 10:02                   ` Stuart Morrow
  2021-08-26 14:26                     ` ori
  0 siblings, 1 reply; 18+ messages in thread
From: Stuart Morrow @ 2021-08-26 10:02 UTC (permalink / raw)
  To: 9front

On 25/08/2021, ori@eigenstate.org <ori@eigenstate.org> 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.

^ permalink raw reply	[flat|nested] 18+ messages in thread

* Re: [9front] Re: man pages
  2021-08-26 10:02                   ` Stuart Morrow
@ 2021-08-26 14:26                     ` ori
  0 siblings, 0 replies; 18+ messages in thread
From: ori @ 2021-08-26 14:26 UTC (permalink / raw)
  To: 9front

Quoth Stuart Morrow <morrow.stuart@gmail.com>:
> On 25/08/2021, ori@eigenstate.org <ori@eigenstate.org> 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?
> 

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


^ permalink raw reply	[flat|nested] 18+ messages in thread

end of thread, other threads:[~2021-08-26 14:48 UTC | newest]

Thread overview: 18+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
     [not found] <CABB-WO9mMVTigW9s96s88nPvA8fEijD6m-K_aR-=cMvDG363dQ@mail.gmail.com>
2021-08-14 16:56 ` [9front] Re: man pages Stuart Morrow
2021-08-24 17:21   ` Stuart Morrow
2021-08-24 20:27     ` qwx
2021-08-24 21:02       ` Stuart Morrow
2021-08-24 21:09         ` hiro
2021-08-24 21:13           ` Stuart Morrow
2021-08-24 21:33           ` Stuart Morrow
2021-08-24 21:34         ` ori
2021-08-24 23:42           ` Stuart Morrow
2021-08-25  1:02             ` ori
2021-08-25 12:05               ` Stuart Morrow
2021-08-25 22:50                 ` ori
2021-08-26 10:02                   ` Stuart Morrow
2021-08-26 14:26                     ` ori
2021-08-24 21:49         ` qwx
2021-08-24 21:20       ` Humm
2021-08-25  3:18         ` ori
2021-08-25  9:37           ` hiro

9front - general discussion about 9front

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://inbox.vuxu.org/9front

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 9front 9front/ https://inbox.vuxu.org/9front \
		9front@9front.org
	public-inbox-index 9front

Example config snippet for mirrors.
Newsgroup available over NNTP:
	nntp://inbox.vuxu.org/vuxu.archive.9front


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git