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 ↗

(On Diff #38112)

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 ↗

(On Diff #38115)

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 ↗

(On Diff #38115)

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 ↗

(On Diff #38115)

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

6353 ↗

(On Diff #38153)

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 ↗

(On Diff #38153)

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.

6351 ↗

(On Diff #38115)

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

[arshankhanifar_gmail.com]

updated the diff with -U999999

[arshankhanifar_gmail.com]

book.xml

6323 ↗

(On Diff #38112)

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 ↗

(On Diff #38115)

@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 ↗

(On Diff #38318)

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

6327 ↗

(On Diff #38323)

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 :)