Page MenuHomeFreeBSD

rewrite of intro(4) manpage
ClosedPublic

Authored by andrew_tao173.riddles.org.uk on Apr 2 2019, 6:01 PM.

Details

Summary

intro(4) was very obsolete; here is a proposed rewrite.

The general changes are:

  • Remove issues that no longer apply thanks to devfs
  • add language pointing out devfs's role and referencing its config
  • add a "historical notes" section and move discussion of block vs character devs to it, including pointing out the removal of block devs
  • modernize some examples

Diff Detail

Repository
rS FreeBSD src repository
Lint
Lint Skipped
Unit
Unit Tests Skipped

Event Timeline

Herald added a subscriber: imp. ยท View Herald Transcript
rpokala added a subscriber: rpokala.Apr 2 2019, 9:17 PM
rpokala added inline comments.
share/man/man4/intro.4
64

I think we're supposed to start a new line after ;.

106

To reduce the redundancy of devfs.conf, perhaps something like this:

But since device nodes are not stored persistently between reboots,
those file permissions are set from rules specified in
.Xr devfs.conf 5 ,
at boot time or dynamically, or else set manually using the
.Xr devfs 8
command.
share/man/man4/intro.4
64

why? I find many counter-examples.

106

redundancy of devfs.conf vs. devfs.rules?

rpokala added inline comments.Apr 2 2019, 9:52 PM
share/man/man4/intro.4
64

I'm pretty sure I've been told that by various manpage reviewers over the past few years.

I suggest you run the page through igor and mandoc -Tlint, and defer to their wisdom rather than mine. :-)

106

I clearly can't read today... ๐Ÿคฆโ€โ™‚๏ธ

So, never mind.

andrew_tao173.riddles.org.uk marked 4 inline comments as done.Apr 2 2019, 10:13 PM
andrew_tao173.riddles.org.uk added inline comments.
share/man/man4/intro.4
64

igor and mandoc complain about the missing linebreak for new sentence on line 187 below (which I had already noticed), but neither of them say anything about this semicolon. So I'll leave this as is.

187

Missing linebreak for new sentence here, I will fix in due course.

andrew_tao173.riddles.org.uk marked an inline comment as done.Apr 2 2019, 10:27 PM
0mp accepted this revision as: manpages, 0mp.Apr 3 2019, 8:45 AM
0mp added a subscriber: 0mp.

Looks good. Thanks for the contribution!

Minor nit: while here, could you replace Qq with Dq as per style.mdoc(5)?

This revision is now accepted and ready to land.Apr 3 2019, 8:45 AM

Qq? there are none of those, only Ql for inline literals (though on second reading some of those are wrong and should have been Dq - will fix).

Use Dq Li in place of most Ql uses, and use Dq alone in place of some uses of Ql that were not in fact literals.

Add missing sentence linebreak.

This revision now requires review to proceed.Apr 3 2019, 9:26 AM
0mp accepted this revision as: manpages, 0mp.Apr 3 2019, 9:37 AM
This revision is now accepted and ready to land.Apr 3 2019, 9:37 AM
bcr added a subscriber: bcr.Apr 3 2019, 1:16 PM

Who's gonna commit this?

ygy added a subscriber: ygy.Apr 3 2019, 6:29 PM
In D19799#424790, @bcr wrote:

Who's gonna commit this?

I can commit it if no one else is going to. Just took PR236970. :)

0mp added a comment.Apr 3 2019, 9:19 PM
In D19799#424885, @ygy wrote:
In D19799#424790, @bcr wrote:

Who's gonna commit this?

I can commit it if no one else is going to. Just took PR236970. :)

Go for it!

This revision was automatically updated to reflect the committed changes.