[9front] joystick support docs

[9front] joystick support docs

[qwx]

diff 6c9462710539bd35ae5c51de27e7894522683bd7 uncommitted
--- /tmp/diff100000014803
+++ b/rc/bin/joy
@@ -1,0 +1,39 @@
+#!/bin/rc
+# usage: nusb/joy epX.Y | joy [N]
+~ $#* 0 && *=''
+awk -safe -v 'joy='$1 '
+	/^axis 0 0/   { k[0] = "left " }
+	/^axis 0 255/ { k[0] = "right " }
+	/^axis 0 128/ { k[0] = "" }
+
+	/^axis 1 0/   { k[1] = "up " }
+	/^axis 1 255/ { k[1] = "down " }
+	/^axis 1 128/ { k[1] = "" }
+
+	/^down 1$/ { k[3] = "b " }
+	/^down 5$/ { k[2] = "a " }
+	/^down 6$/ { k[8] = "x " }
+	/^down 2$/ { k[9] = "y " }
+	/^down 3$/ { k[4] = "control " }
+	/^down 4$/ { k[5] = "start " }
+	/^down 7$/ { k[6] = "l1 " }
+	/^down 8$/ { k[7] = "r1 " }
+
+	/^up 1$/ { k[3] = "" }
+	/^up 5$/ { k[2] = "" }
+	/^up 6$/ { k[8] = "" }
+	/^up 2$/ { k[9] = "" }
+	/^up 3$/ { k[4] = "" }
+	/^up 4$/ { k[5] = "" }
+	/^up 7$/ { k[6] = "" }
+	/^up 8$/ { k[7] = "" }
+
+	{
+		if(joy != "")
+			printf "joy%s ", joy
+		for(i in k)
+			printf k[i]
+		printf "\n"
+		fflush
+	}
+'
--- a/sys/man/1/atari
+++ b/sys/man/1/atari
@@ -46,6 +46,9 @@
 .TP
 .B -x
 Scale the screen to a given factor regardless of the window's size.
+.PP
+A joystick may be used to play the emulator via
+.IR joy (1).
 .SH SOURCE
 .B /sys/src/games/2600
 .SH BUGS
--- /tmp/diff100000015479
+++ b//sys/man/1/joy
@@ -1,0 +1,45 @@
+.TH MUS 1
+.SH NAME
+joy \- joystick input for games
+.SH SYNOPSIS
+.B joy
+[
+.I player
+]
+.SH DESCRIPTION
+.I Joy
+interprets input from a USB joystick device
+(see
+.IR nusb (4))
+to pass it on to a console emulator
+as a string of controller keys
+which are pressed down.
+.PP
+The optional
+.B player
+argument specifies a player number
+for those emulators that support it.
+It should be an integer equal to 1 or greater.
+Currently only players 1 and 2 are supported.
+.PP
+Note that each USB controller has its own mappings
+and the program may have to be modified
+to use its own key id's.
+.SH EXAMPLES
+Use USB device 10 as a joystick
+for the player number 1's controller
+with the Nintendo Entertainment System (NES) emulator:
+.IP
+.EX
+% nusb/joy /dev/usb/ep10.0 | joy 1 | games/nes -a rom.nes
+.EE
+.SH "SEE ALSO"
+.IR atari (1),
+.IR nintendo (1),
+.IR sega (1),
+.IR nusb (4)
+.SH SOURCE
+.B /rc/bin/joy
+.SH HISTORY
+.I Joy
+first appeared in 9front (June, 2014).
--- a/sys/man/1/nintendo
+++ b/sys/man/1/nintendo
@@ -134,6 +134,11 @@
 .TP
 .B -m
 Enable mouse emulation using system mouse. Mouse button 1 (left button) engages the SNES left mouse button. Mouse button 3 (right button) engages the SNES right mouse button. Holding down mouse button 2 (middle button) disengages the SNES mouse entirely so that the Plan 9 cursor offset can be adjusted to align with the SNES cursor.
+.PP
+Each of these emulators support the use of joysticks via
+.IR joy (1).
+.I Nes
+also supports selecting the joystick for either player 1 or 2.
 .SH SOURCE
 .B /sys/src/games/gb
 .br
--- a/sys/man/1/sega
+++ b/sys/man/1/sega
@@ -44,6 +44,9 @@
 .TP
 .B -x
 Scale the screen to a given factor regardless of the window's size.
+.PP
+Each of these emulators support the use of joysticks via
+.IR joy (1).
 .SH SOURCE
 .B /sys/src/games/md
 .SH BUGS
--- a/sys/man/4/nusb
+++ b/sys/man/4/nusb
@@ -35,6 +35,12 @@
 ]
 .I devid
 .PP
+.B nusb/joy
+[
+.B -d
+]
+.I devid
+.PP
 .B nusb/serial
 [
 .B -d
@@ -135,6 +141,27 @@
 Mouse events are sent to
 .BR /dev/mousein
 in the same way.
+.SS Joysticks
+.I Joy
+parses data packets from a given endpoint and prints back
+any changes in the device's axes or buttons.
+Buttons are identified via an integer id.
+.PP
+Directional buttons are reported as axes
+with 3 positions:
+.IR 0 ,
+.IR 128 ,
+and
+.I 255
+for left (or up), center and right (or down) respectively.
+Messages are in the form \fIaxis id position\fR.
+.PP
+On/off buttons are reported as either
+.I down
+or
+.I up
+respectively.
+Messages are in the form \fIdown\fB|\fIup id\fR.
 .SS Disks
 .I Disk
 configures and manages USB mass storage devices. It
@@ -239,6 +266,7 @@
 .SH SOURCE
 .B /sys/src/cmd/nusb
 .SH "SEE ALSO"
+.IR joy (1),
 .IR audio (3),
 .IR ether (3),
 .IR mouse (3),
@@ -248,6 +276,9 @@
 .IR shr (3),
 .IR nusbrc (8),
 .IR kbdfs (8)
+.SH HISTORY
+.I Joy
+first appeared in 9front (March, 2014).
 .SH BUGS
 The various device drivers are generic USB drivers and
 may work only for certain devices of each class.
--- a/sys/src/games/nes/joynes
+++ /tmp/diff100000014822
@@ -1,33 +1,0 @@
-#!/bin/rc
-# run as "nusb/joy epX.Y | joynes N", where N=[1,2]
-
-awk -safe -v 'joy='$1 '
-	BEGIN { k[0] = "" }
-
-	/^axis 0 0/   { k[0] = "left " }
-	/^axis 0 255/ { k[0] = "right " }
-	/^axis 0 128/ { k[0] = "" }
-
-	/^axis 1 0/   { k[1] = "up " }
-	/^axis 1 255/ { k[1] = "down " }
-	/^axis 1 128/ { k[1] = "" }
-
-	/^down 7$/ { k[3] = "b " }
-	/^down 8$/ { k[2] = "a " }
-	/^down 1$/ { k[4] = "control " }
-	/^down 2$/ { k[5] = "start " }
-
-	/^up 7$/ { k[3] = "" }
-	/^up 8$/ { k[2] = "" }
-	/^up 1$/ { k[4] = "" }
-	/^up 2$/ { k[5] = "" }
-
-	{
-		if(joy != "")
-			printf "joy%s ", joy
-		for(i = 0; i <= 5; i++)
-			printf k[i]
-		printf "\n"
-		fflush
-	}
-'

Re: [9front] joystick support docs

[unobe]

Minor questions inline.

Quoth qwx <qwx@sciops.net>:
> ...
> --- /tmp/diff100000015479
> +++ b//sys/man/1/joy
> @@ -1,0 +1,45 @@
> +.TH MUS 1
> +.SH NAME
> +joy \- joystick input for games
> +.SH SYNOPSIS
> +.B joy
> +[
> +.I player
> +]
> +.SH DESCRIPTION
> +.I Joy
> +interprets input from a USB joystick device
> +(see
> +.IR nusb (4))
> +to pass it on to a console emulator
> +as a string of controller keys
> +which are pressed down.
> +.PP
> +The optional
> +.B player
> +argument specifies a player number
> +for those emulators that support it.
> +It should be an integer equal to 1 or greater.
> +Currently only players 1 and 2 are supported.
> +.PP
> +Note that each USB controller has its own mappings
> +and the program may have to be modified
> +to use its own key id's.

id's -> ids ?

> +.SH EXAMPLES
> +Use USB device 10 as a joystick
> +for the player number 1's controller
> +with the Nintendo Entertainment System (NES) emulator:
> +.IP
> +.EX
> +% nusb/joy /dev/usb/ep10.0 | joy 1 | games/nes -a rom.nes
> +.EE
> +.SH "SEE ALSO"
> +.IR atari (1),
> +.IR nintendo (1),
> +.IR sega (1),
> +.IR nusb (4)

I'm new to ths, but am wondering: should the SEE ALSO list be
alphabetized, or is it first by man page section, then alphabetized?
Same question for /sys/man/4/nusb diff below, so won't comment there.

> ...

Re: [9front] joystick support docs

[Stuart Morrow]

On 01/09/2021, unobe@cpan.org <unobe@cpan.org> wrote:
> id's -> ids ?

Nope - apostrophe is preferred for "awkward plurals".

Re: [9front] joystick support docs

[unobe]

Quoth Stuart Morrow <morrow.stuart@gmail.com>:
> On 01/09/2021, unobe@cpan.org <unobe@cpan.org> wrote:
> > id's -> ids ?
> 
> Nope - apostrophe is preferred for "awkward plurals".

Okay, why is "ids" an awkward plural?

Re: [9front] joystick support docs

[ori]

Quoth Stuart Morrow <morrow.stuart@gmail.com>:
> Nope - apostrophe is preferred for "awkward plurals".

The general rule is that apostrophes
indicate posession, not plurals.

Some style guides suggest putting it
after the word when things are ambiguous,
like so:

	ids => ids'
	as => as'

but as programmers, I'd rather quote
to remove any ambiguity at all, if
needed:

	'id's
	'a's

while it's not standard, it fits well
in a technical context.

Re: [9front] joystick support docs

[Lyndon Nerenberg (VE7TFX/VE6BBM)]

ori@eigenstate.org writes:

> The general rule is that apostrophes
> indicate posession, not plurals.

Amen.  The best book on this topic is:

  https://www.lynnetruss.com/books/eats-shoots-leaves/

It's a pleasant and fun read, even apart from the grammar and
punctuation arguments.  And in my view, nobody should be granted a
man page commit bit unless and until they own a copy and have read
it from cover to cover.  Twice!

At the very least, borrow a copy from the library.

--lyndon

Re: [9front] joystick support docs

[unobe]

Quoth Lyndon Nerenberg (VE7TFX/VE6BBM) <lyndon@orthanc.ca>:
> ori@eigenstate.org writes:
> 
> > The general rule is that apostrophes
> > indicate posession, not plurals.
> 
> Amen.  The best book on this topic is:
> 
>   https://www.lynnetruss.com/books/eats-shoots-leaves/
> 
> It's a pleasant and fun read, even apart from the grammar and
> punctuation arguments.  And in my view, nobody should be granted a
> man page commit bit unless and until they own a copy and have read
> it from cover to cover.  Twice!

Thanks for bringing up that book.  I remember when it came out but I
have yet to read it.  Fortunately, I don't have a commit bit.

Re: [9front] joystick support docs

[Stuart Morrow]

On 01/09/2021, ori@eigenstate.org <ori@eigenstate.org> wrote:
> The general rule is that apostrophes
> indicate posession, not plurals.
>
> Some style guides suggest putting it
> after the word when things are ambiguous,
> like so:
>
> 	ids => ids'
> 	as => as'

I can't say I've ever heard of this, or why disambiguation in
particular would be the use when apostrophe-at-the-end *already* has a
well-known use.

Re: [9front] joystick support docs

[Kurt H Maier]

On Wed, Sep 01, 2021 at 10:58:35AM +0000, Stuart Morrow wrote:
> On 01/09/2021, unobe@cpan.org <unobe@cpan.org> wrote:
> > id's -> ids ?
> 
> Nope - apostrophe is preferred for "awkward plurals".

Only by small business owners writing on cardboard sign's.

Chicago manual of style only permits pluralizing apostrophes in single
lower-case letters or abbreviations that combine cases (PhD) or contain
interior periods (Ph.D.).

I think Chicago manual of style is too forgiving.

khm

Re: [9front] joystick support docs

[qwx]

> id's -> ids ?

I agree with unobe that this is probably more correct.  I don't
see any real rules here, but from what I understand apostrophes
are used to avoid ambiguity more than anything, which I think is
unnecessary here.


> I'm new to ths, but am wondering: should the SEE ALSO list be
> alphabetized, or is it first by man page section, then alphabetized?
> Same question for /sys/man/4/nusb diff below, so won't comment there.

Again, there are no real rules for anything.  Personally I sort
by section, then alphabetically, but I avoid changing things
around in random manpages.  As with the rest, if a rule is made,
I think a big change should be done for all at once, instead of
doing random pikeshedding here and there.

Thanks,

qwx

Re: [9front] joystick support docs

[unobe]

Quoth qwx <qwx@sciops.net>:
> Again, there are no real rules for anything.  Personally I sort
> by section, then alphabetically, but I avoid changing things
> around in random manpages.

Thanks, that's helpful.

Re: [9front] joystick support docs

[Lyndon Nerenberg (VE7TFX/VE6BBM)]

Shouldn't that

  .TH MUS

be

  .TH JOY

?

--lyndon

Re: [9front] joystick support docs

[qwx]

> Shouldn't that
> 
>   .TH MUS
> 
> be
> 
>   .TH JOY
> 
> ?
> 
> --lyndon

Oops, good catch.

Thanks!

qwx