networking.7 : create network quickstart guide #833
Conversation
https://bugs.freebsd.org/273530#c3 PR: 273530 Fixes: 08c9016 Add a manpage for the urndis driver. Closes: #4 Closes: freebsd#833
https://bugs.freebsd.org/273530#c3 PR: 273530 Fixes: 08c9016 Add a manpage for the urndis driver. Signed-off-by: Graham Perrin <grahamperrin@gmail.com> Pull-request: #4 Closes: #4 Pull-request: freebsd#833 Closes: freebsd#833
|
Sorry, ignore the urndis(4) pollution above. A consequence of me attempting to work with a PR in a fork in advance of a simple PR hereabouts. |
share/man/man7/networking.7
Outdated
| .Sh NAME | ||
| .Nm networking , | ||
| .Nm wifi | ||
| .Nd quickstart guide to connecting to a network | ||
| .Sh EXAMPLES |
There was a problem hiding this comment.
From https://man.freebsd.org/cgi/man.cgi?query=mdoc&sektion=7&manpath=freebsd-release#MANUAL_STRUCTURE in mdoc(7):
… convention dictates specifying at least the SYNOPSIS and DESCRIPTION sections, although this varies between manual sections. …
There was a problem hiding this comment.
I didn't feel SYNOPSIS was relevant, most pages in section 7 didn't have them. My latest commit adds a description attempting to explain the nomenclature of interfaces
EDIT: s/relevant/appropriate
No, that's beautiful. I completely forgot about USB tethering. It should be mentioned here. |
|
I think it's less legible, but I rewrote the examples to format accordingly to style.mdoc(5), except without the depreciated Li macro. The guideline laid out there breaks a lot of mdoc conventions. The It macro is stated in mdoc(7) to be for individual commands and explicitly not entire lines. Also, subsections have their own macro, and I think they're appropriate for this use case. I have a copy with all the changes but the earlier formatting. Thoughts? |
|
This commit needs to have a real email, not the noreply github one, |
@concussious this is still not addressed |
I'm sorry, I thought that I did, and I don't understand. |
|
you need to set the commit email in your git cli, then go back rewrite the author: https://stackoverflow.com/questions/750172/how-do-i-change-the-author-and-committer-name-email-for-multiple-commits#1320317 |
Now that the handbook has been moved to ports, I think it's very nice to have a network quickstart guide in-band, in base, in the system manual.
If the user uses any of the following terms "man -k {network,networking,wifi,quickstart}" this page will come up, which is I think a very common use case for new users.
Currently, this document explains connecting to a basic Ethernet network, a basic wifi network, scanning for wifi networks, and airplane mode, as well as linking to other sections, including the handbook
Co-authored-by: Graham Perrin <grahamperrin@gmail.com>
Co-authored-by: Graham Perrin <grahamperrin@gmail.com>
Co-authored-by: Graham Perrin <grahamperrin@gmail.com>
Co-authored-by: Graham Perrin <grahamperrin@gmail.com>
concussious
force-pushed
the
networking.7
branch
from
7735473
to
094cb4d
Compare
|
Should I squash all these commits down to one like I was instructed to in the other thread? If so, will that negatively impact the commits coauthored with grahamperrin? |
|
I asked @grahamperrin to chime in on whether he minds getting squashed. meanwhile, you can credit yourself as the author of this man page, if you so desire, on the bottom in an |
|
In such a case should we add him to the copyright at the top? |
if you want, sure. your call |
|
@bsdbcr Can you review this in more detail. It seems OK to me, but I'm not sure it belongs here. Thanks! |
I've reviewed the changes. That looks solid and would be a good addition to our docs. Nothing to change, add, or complain about. |
|
I'd like it to say something better about turning wifi off. "Service netif stop" stops all networking, so local services that use networking as an ipc, such as musicpd, will also break. Musicpd is maybe a bad example because you can configure it with a unix socket instead. |
|
I'm also concerned about I don't want to mislead anyone. The first step of connecting to a network is configuring a firewall, unless the entire machine is already behind a firewall, which I think is kind of an advanced use case. |
|
EDIT: Sorry for the noise, it occurred to me that these files cannot be listed in intro(7) because they're all made conditionally. I have reverted the commit described in this comment below. I just discovered intro(7) lists all the pages in section seven. Therefore, I have added this and everything else my 14.0-R-p3 machine has in /usr/share/man/man7/ to intro(7). While there, I also zapped old tags, added spdx, and updated the history section to the same format used in the new hier(7). |
concussious
force-pushed
the
networking.7
branch
from
b0247ee
to
b42f72d
Compare
Is it appropriate for |
|
OK. This isn't getting any better, and hans't for a while. It looks good as is. I'll leave the intro issue for others. |
Now that the handbook has been moved to ports, I think it's very nice to
have a network quickstart guide in-band, in base, in the system manual.
If the user uses any of the following terms "man -k
{network,networking,wifi,quickstart}" this page will come up, which is I
think a very common use case for new users.
Currently, this document explains connecting to a basic Ethernet
network, a basic wifi network, scanning for wifi networks, and airplane
mode, as well as linking to other sections, including the handbook
Co-authored-by: Graham Perrin <grahamperrin@gmail.com>
Reviewed by: imp, bcr, freebsd@igalic.co
Pull Request: #833
Now that the handbook has been moved to ports, I think it's very nice to have a network quickstart guide in-band, in base, in the system manual. If the user uses any of the following terms "man -k {network,networking,wifi,quickstart}" this page will come up, which is I think a very, very common use case for new users.
FreeBSD is the server star, but new users will need to play with it on their laptops before trying to use it in production, right?
Currently, this document explains connecting to a basic Ethernet network, USB tethering, a basic wifi network, scanning for wifi networks, and airplane mode, as well as linking to a few other relevant pages and sections, including the handbook.