Page MenuHomeFreeBSD

aw_rsb: Add man page for this driver
Needs ReviewPublic

Authored by manu on Dec 25 2017, 10:35 PM.
Tags
None
Referenced Files
Unknown Object (File)
Feb 3 2024, 4:13 PM
Unknown Object (File)
Jan 30 2024, 6:10 AM
Unknown Object (File)
Dec 20 2023, 7:24 AM
Unknown Object (File)
Dec 13 2023, 10:43 PM
Unknown Object (File)
Aug 4 2023, 6:49 PM
Unknown Object (File)
Jun 20 2023, 5:01 PM
Unknown Object (File)
May 2 2023, 8:10 AM
Unknown Object (File)
Feb 10 2023, 12:04 AM

Details

Reviewers
None
Group Reviewers
manpages
Summary

Add a driver for aw_rsb/aw_p2wi

Diff Detail

Lint
Lint Passed
Unit
No Test Coverage
Build Status
Buildable 14029
Build 14219: arc lint + arc unit

Event Timeline

bjk added inline comments.
share/man/man4/aw_rsb.4
35

Nd is a one-line description, so you can't wrap onto the next one.

43

Start a new line for new sentences, please.

48

The space before ":" is only needed on a line being interpreted in macro context, which this line is not -- you can just write "strings:".

50

IIRC mandoc -Tlint will complain about .Pp before .Bl, but don't hold me to that.

54

The "body text" of the item can be on the same line as the .It macro.

59

.Re closes a .Rs block, which does not seem present (so the .Re can be removed)

share/man/man4/aw_rsb.4
35

What do you mean ? can you provide an example please ?

48

but 'strings :' is prettier that 'strings:' no ?

50

I've just take samples from other manpages.

54

Text doesn't render this way for me.

59

Probably a bad copy/paste.

share/man/man4/aw_rsb.4
43

This give weird result for having two spaces between the dot and the first character.

assert some bjk@ comments.

share/man/man4/aw_rsb.4
35

I think that having "on some Allwinner SoCs." on the next line will be problematic; mdoc(7) has:

The Nd macro technically accepts child macros and terminates with a
subsequent Sh invocation.  Do not assume this behaviour: some whatis(1)
database generators are not smart enough to parse more than the line
arguments and will display macros verbatim.

So, I might go with ".Nd driver for the Reduced Serial Bus/Push-Pull Two Wire Interface" (all on one line) and maybe not mention the Allwinner SoCs in this stanza.

43

I am not sure I understand your reply, but yes, things render differently with 1 vs. 2 spaces after a period; this is why our style guide says to always start a new line instead of picking 1 or 2 spaces.

48

I guess that's a judgment call (I prefer "strings:"). I am not 100% sure if we have a definitive style/policy on this one.

50

Sure; it's not harmful and could be rolled into a hypothetical future cleanup sweep if needed.

54

My apologies, the .It syntax depends on the list type.

danfe added inline comments.
share/man/man4/aw_rsb.4
43

It's one of those strange French things: https://french.stackexchange.com/questions/8871/usage-of-spacing-between-punctuation-marks

Manu, since the Project language is English, please adhere to its rules. I'm sorry, but space before the colon in this case is wrong.

Correct some stuff based on comments and mandoc -Tlint

manu marked 16 inline comments as done.

I've only written the man page.

Just one nit, inline; otherwise this looks good.

share/man/man4/aw_rsb.4
35

The .Nd should not be on a line by itself; the "driver for ..." stuff should be on the same line, too.
Look at virtually any other man4 page for examples.

wblock added inline comments.
share/man/man4/aw_rsb.4
44

s/close to/similar to/

48

s/the following/these/

(Also: in English, we do not put whitespace before a colon.)

Correct man page and only install for arm/arm64

Put .Nd on the same line

manu marked 3 inline comments as done.Jan 1 2018, 2:12 PM
brueffer added inline comments.
share/man/man4/aw_rsb.4
28

We usually spell out the month, so January.

share/man/man4/aw_rsb.4
35

Is this correct? The man page is for aw_rsb, but to include the device it is just rsb?

Ping? I think we're getting close to approving this one...