Updated the FAQ book's Chapter 15 about serial communicators

[emaste]

Summary

the FAQ page has an outdated tutorial on how to detect serial devices. Built-in serial buses enumerate differently in dmesg now and they start with uart, not sio.

[emaste]

Looks good to me, but needs someone with a doc commit bit to approve.

[emaste]

book.xml

6323

Although we need to change this text too - has a 16550 compatible UART chip probably

[arshankhanifar_gmail.com]

Added another example for the cases where users use a usb-to-serial converter.

[emaste]

book.xml

6330–6331

We should keep these for a separate commit - i.e., address all of the sio cases first, then add this change in a separate review.

(I did not realize there were so many other instances of sio in this file.)

[bcr]

A few comments. Don't be discouraged, you're on the right track.
One more thing though: next time when you create the diff, do it from the top level of your doc directory. That will include the full path to the file in the diff/review header and not just book.xml. We have many book.xml files, so having the path in there helps determining what file the patch is for.

Thanks!

book.xml

6331

A few comments in addition to what Ed said here (having separate commits).

• The use of "you" is discouraged. Instead, use: When using USB to serial converter cables, it will show up ("be displayed" might be better here) as a difference device.
• Two spaces after a sentence stop
• no space after the colon and the closing </para>

6351

I would rephrase this to not have the comma (which usually produces a mental pause when reading) to make the sentence more readable:

"The first &man.dmesg.8; output above is before the device was connected."

• Two spaces again (yes, there is a pattern. ;-))

• Avoid the "we" in the next sentence:

Then the USB device is connected and the second &man.dmesg.8; shows the device is detected.

• Next sentence: no space between the 5 and the </command>

Also, I would abbreviate the sentence to:
"The output was limited to 5 lines using tail."
You could also leave out that sentence completely as users can see what is going on.

[arshankhanifar_gmail.com]

removed all the usb-to-uart tutorial, to save it for a future review.

[arshankhanifar_gmail.com]

This whole paragraph talks about the third serial port, sio2 or COM3, which is supposed to be on /dev/cuad2 for dial-out devices and /dev/ttyd2 for dial-in devices. when I do ls /dev/cua* I get these files:

/dev/cuaU0
/dev/cuaU0.init
/dev/cuaU0.lock
/dev/cuau0
/dev/cuau0.init
/dev/cuau0.lock
/dev/cuau2
/dev/cuau2.init
/dev/cuau2.lock

also when I do ls dev/tty* I get this:

/dev/ttyU0
/dev/ttyU0.init
/dev/ttyU0.lock
/dev/ttyu0
/dev/ttyu0.init
/dev/ttyu0.lock
/dev/ttyu2
/dev/ttyu2.init
/dev/ttyu2.lock
/dev/ttyv0
/dev/ttyv1
/dev/ttyv2
/dev/ttyv3
/dev/ttyv4
/dev/ttyv5
/dev/ttyv6
/dev/ttyv7
/dev/ttyv8
/dev/ttyv9
/dev/ttyva
/dev/ttyvb

[arshankhanifar_gmail.com]

book.xml

6351

Thank you for all these tips, will take note of them in the next review.

6353

This whole paragraph talks about the third serial port, sio2 or COM3, which is supposed to be on /dev/cuad2 for dial-out devices and /dev/ttyd2 for dial-in devices. I see these in my terminal instead:

$ ls /dev/cua*
/dev/cuaU0
/dev/cuaU0.init
/dev/cuaU0.lock
/dev/cuau0
/dev/cuau0.init
/dev/cuau0.lock
/dev/cuau2
/dev/cuau2.init
/dev/cuau2.lock

so I'm guessing cuad2 is cuau2 , and ttyd2 is ttyv2 now?

6370

could it be possible that cuad has changed to cuau, and ttyd has changed to ttyv? In that case I guess we can keep the text and change all the cuadX to cuauX and also all the ttyd to ttyv.

[arshankhanifar_gmail.com]

updated the diff with -U999999

[arshankhanifar_gmail.com]

book.xml

6323

I think we should say "16550 or 16550-compatible" UART chip:
Wikipedia's page on 16550UART says:

is an integrated circuit designed for implementing the interface for serial communications.

so I think here, what the output of dmesg suggests is that it's either 16550 or an 16550-compatible chip.

[arshankhanifar_gmail.com]

updated the dial-in and dial-out serial enumerations on dev:
ttyd to ttyv
cuad to cuau

[arshankhanifar_gmail.com]

book.xml

6351

@bcr I applied your suggested changes here.

[bcr]

The indentation seems a bit off, so I refer you to Dr. igor. ;-)

book.xml.moresio

6321 ↗

(On Diff #38173)

The indentation in this paragprah seems wrong. If you install textproc/igor from ports/packages and run it on the xml file that this patch is based on, it will tell you where the errors are.

[arshankhanifar_gmail.com]

corrected whitespaces

book.xml.moresio

6321 ↗

(On Diff #38173)

I think I already had Dr Igor installed :P,
when moving around files I'd renamed it to book.xml.moreiso... that's why vim wasn't showing me all the whitespaces...

[bcr]

Just one more fix to the indentation level...

book.xml

6323–6328

The indentation here is still off by one level. It should all align below the first "a" of the <para> (like the other lines above).

[arshankhanifar_gmail.com]

the direction of the diff was backwards... my bad

[bcr]

I found one more typo.

book.xml

6326

except that they

[arshankhanifar_gmail.com]

fixed typo

[bcr]

Approved, thanks for working on it!

[emaste]

Asciidoc conversion, also update snippet to include "console" output

[ygy]

LGTM :)