Paths

Table of Contentst

Differential D59470

asmc.4: clean up/modernize manpage
Needs RevisionPublic
Actions

Authored by ngie on Sun, Sep 6, 10:28 PM.

Details

Reviewers

ziaee

Group Reviewers

manpages

Summary

sysutils/ataidle is no more: it was superseded by camcontrol(8).
Sort the models table alphabetically.
Use the SPDX License ID instead of the longhand licensing tort in the manpage header.
Note that the driver has been heavily modified in 15.1 and later to support additional platforms and functionality.
Trim down SYNOPSIS.

MFC after: 2 weeks

Diff Detail

Repository

rG FreeBSD src repository

Lint

Lint Skipped

Unit

Tests Skipped

Build Status

Buildable 76620
Build 73503: arc lint + arc unit

Event Timeline

ngie created this revision.Sun, Sep 6, 10:28 PM

Herald added subscribers: ziaee, imp. · View Herald TranscriptSun, Sep 6, 10:28 PM

ngie requested review of this revision.Sun, Sep 6, 10:28 PM

Harbormaster completed remote builds in B76616: Diff 186081.Sun, Sep 6, 10:28 PM

ngie added a reviewer: manpages.Sun, Sep 6, 10:28 PM

ngie added a subscriber: seuros.

ngie added inline comments.Sun, Sep 6, 11:54 PM

share/man/man4/asmc.4
34–35	I don't like this degree of handwaving in the documentation. I need to figure out a) why this doesn't work on my MacBookPro 13,1 (T1 Mac) and b) try running this on my MacBookPro 16,1 (T2 Mac) system.
116–117	typo: park

Fix typo (part -> park)

Harbormaster completed remote builds in B76619: Diff 186095.Mon, Sep 7, 2:38 AM

Use .Pa when describing ada0 to match other manpage examples

Harbormaster completed remote builds in B76620: Diff 186096.Mon, Sep 7, 2:41 AM

Be more direct in the hardware section, like requested in D59467

Harbormaster completed remote builds in B76621: Diff 186097.Mon, Sep 7, 2:51 AM

Ah, thank you so much for doing this! I've been fixing the SYNOPSIS and HARDWARE one at a time :P

share/man/man4/asmc.4
3	We can not remove or change existing text, unless @rpaulo approves the commit. The shortened license is the preferred text for new files only. Although sometimes I pester the authors for existing text because it has typos in the license and is causing me headaches :) I'll see if we can ping him while you're on vacation though, the short license form is quite beautiful and useful.
12	Nm and Nd are always rendered together, so asmc as an acronym is already established.
153	While here, macros in list width specifiers is cursed. It renders as -1 spaces in some implementations and circumstances.

This revision now requires changes to proceed.Mon, Sep 7, 10:02 PM

seuros added inline comments.Mon, Sep 7, 10:53 PM

share/man/man4/asmc.4
3	That not true . A License text ca be compacted at the maintainer's discretion, as long as the actual license terms are not changed. What you cannot do is remove copyright holders, change attribution requirements, or upgrade/downgrade the license without permission. The license was replaced by 'SPDX-License-Identifier: BSD-2-Clause' which is the same. There are also plenty of cases where asking the original author is simply impossible because they left the project, disappeared, or passed away. Requiring approval just to replace equivalent boilerplate with an SPDX identifier would make this kind of cleanup impossible forever. Source: I got my own verbose MIT/GPL license compacted in 20+ projects by other maintainers without anyone pinging me first.

ziaee added inline comments.Mon, Sep 7, 10:58 PM

share/man/man4/asmc.4
3	That sounds very obviously reasonable to me, however I have been advised by members of the current core team that I can not. In any case, Rui is around, I just saw him on IRC just the other day.

seuros added inline comments.Mon, Sep 7, 11:09 PM

share/man/man4/asmc.4
3	Fair. Maybe the reason for that rule is to avoid commits that only go around cleaning up license text everywhere, basically like running a linter over the whole source tree and creating noise. But when a file is already being rewritten, I think compacting the existing license to the equivalent SPDX identifier as part of that rewrite should be fine.

ngie marked 3 inline comments as done.Tue, Sep 8, 3:54 PM

ngie added inline comments.

share/man/man4/asmc.4
3	Fair. Maybe the reason for that rule is to avoid commits that only go around cleaning up license text everywhere, basically like running a linter over the whole source tree and creating noise. But when a file is already being rewritten, I think compacting the existing license to the equivalent SPDX identifier as part of that rewrite should be fine. I can just remove the "license compacting" from this change so this can land more easily/with less friction. I'll do that if @rpaulo doesn't respond to the review by the time I get back from my current trip to unblock the other changes.
12	Nm and Nd are always rendered together, so asmc as an acronym is already established. I think there's some value in keeping the acronym (somewhere in the manpage) given that "SMC" is widely used in the Apple hardware/software docs, can be easily found online (there are so many SMC software utilities out there..), etc. It doesn't have to be here though--and it might be better handled as a short blurb in the `DESCRIPTION`.
153	While here, macros in list width specifiers is cursed. It renders as -1 spaces in some implementations and circumstances. Eep. Good to know!

ziaee added inline comments.Tue, Sep 8, 7:45 PM

share/man/man4/asmc.4
12	Well, that's what I mean. The acronym is shown and defined in the manpage description already, just formatted differently than you're expecting. Instead of: ... apple system management controller (smc)... It says: asmc - apple system management controller... 8-)

I’m fine with the license clean up.

Revision Contents
Changeset List

Path

Size

share/

man/

man4/

asmc.4

112 lines

Diff 186096

View Options

asmc.4: clean up/modernize manpageNeeds RevisionPublicActions