aw_rsb: Add man page for this driver
Needs ReviewPublic

Authored by manu on Dec 25 2017, 10:35 PM.

Details

Reviewers
None
Group Reviewers
manpages
Summary

Add a driver for aw_rsb/aw_p2wi

Diff Detail

Lint
Lint OK
Unit
No Unit Test Coverage
Build Status
Buildable 14029
Build 14219: arc lint + arc unit
manu created this revision.Dec 25 2017, 10:35 PM
manu updated this revision to Diff 37018.Dec 25 2017, 10:39 PM

s/developped/developed/

bjk added a subscriber: bjk.Dec 25 2017, 10:44 PM
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)

manu added inline comments.Dec 25 2017, 10:55 PM
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.

manu added inline comments.Dec 25 2017, 10:58 PM
share/man/man4/aw_rsb.4
43

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

manu updated this revision to Diff 37019.Dec 25 2017, 11:06 PM

assert some bjk@ comments.

manu marked 2 inline comments as done.Dec 25 2017, 11:06 PM
bjk added inline comments.Dec 26 2017, 3:10 AM
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 a subscriber: danfe.Dec 26 2017, 7:31 AM
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.

manu updated this revision to Diff 37035.Dec 26 2017, 10:37 AM

Correct some stuff based on comments and mandoc -Tlint

manu updated this revision to Diff 37036.Dec 26 2017, 10:38 AM
manu marked 16 inline comments as done.

I've only written the man page.

manu updated this revision to Diff 37037.Dec 26 2017, 10:41 AM

Rebase on latest head

bjk added a comment.Dec 26 2017, 11:32 PM

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 a subscriber: wblock.Dec 29 2017, 12:24 PM
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.)

manu updated this revision to Diff 37349.Jan 1 2018, 2:10 PM

Correct man page and only install for arm/arm64

manu updated this revision to Diff 37350.Jan 1 2018, 2:11 PM

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.

wblock added inline comments.Feb 2 2018, 6:17 PM
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?