Page MenuHomeFreeBSD
Differential D19799

rewrite of intro(4) manpage
ClosedPublic
Actions

Authored by andrew_tao173.riddles.org.uk on Apr 2 2019, 6:01 PM.
Tags
Referenced Files
Unknown Object (File)
Wed, Jan 22, 10:49 AM
Unknown Object (File)
Tue, Jan 14, 11:27 PM
Unknown Object (File)
Dec 13 2024, 3:08 AM
Unknown Object (File)
Nov 28 2024, 6:08 AM
Unknown Object (File)
Nov 25 2024, 1:49 PM
Unknown Object (File)
Nov 24 2024, 4:07 AM
Unknown Object (File)
Nov 23 2024, 9:40 PM
Unknown Object (File)
Nov 22 2024, 3:07 PM
View All 59 Files
Subscribers
0mp
bcr
imp
rpokala
ygy

Details

Reviewers
0mp
Group Reviewers
docs
manpages
Commits
rS346111: MFC r345887:
rS345887: Rewrite intro(4) man page.
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 - subversion
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

andrew_tao173.riddles.org.uk created this revision.Apr 2 2019, 6:01 PM
Herald added a reviewer: manpages. · View Herald TranscriptApr 2 2019, 6:01 PM
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 ↗(On Diff #55740)

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

106 ↗(On Diff #55740)

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.
andrew_tao173.riddles.org.uk added inline comments.Apr 2 2019, 9:35 PM
share/man/man4/intro.4
64 ↗(On Diff #55740)

why? I find many counter-examples.

106 ↗(On Diff #55740)

redundancy of devfs.conf vs. devfs.rules?

rpokala added inline comments.Apr 2 2019, 9:52 PM
share/man/man4/intro.4
64 ↗(On Diff #55740)

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 ↗(On Diff #55740)

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 ↗(On Diff #55740)

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 ↗(On Diff #55740)

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
andrew_tao173.riddles.org.uk added a comment.Apr 3 2019, 8:57 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).

andrew_tao173.riddles.org.uk updated this revision to Diff 55768.Apr 3 2019, 9:26 AM

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
andrew_tao173.riddles.org.uk edited the summary of this revision. (Show Details)Apr 3 2019, 9:46 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!

Closed by commit rS345887: Rewrite intro(4) man page. (authored by ygy). · Explain WhyApr 4 2019, 6:52 PM
This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

PathSize
head/
share/
man/
man4/
184 lines

Diff 55812

View Options

head/share/man/man4/intro.4

Loading...