Re: Grammar and style edits to installation guide
On Mon, Jul 29, 2019 at 09:52:48PM -0700, Evan Silberman wrote:
> "T.J. Townsend" wrote:
> > > + You may individually select distribution sets to install
> > > + by entering their names or wildcards (e.g. `*.tgz' or
> > > + `base*|comp*'), or you may enter `all' to select all the
> > > + sets (which is what most users will want to do).
> >
> > > +You should create yourself an account, if you skipped this step during
> > > +installation, and protect it and the "root" account with good passwords.
> >
> > We're mixing these `these' quotes and "normal" ones. It would be great if
> > we could rid ourselves of `these' and ``these'' everywhere.
>
> In the updated patch attached, INSTALL and m4.common are standardized to
> use "ascii straight double quotes" in running text wherever any other
> convention was used. Double quotes are conventional in American English
> style guides.
>
> I haven't done this same pass on the arch-specific content blocks, but
> it should get done.
>
> As an aside, the file "packages" contains guidance that feels outdated.
> It doesn't place the same emphasis that
> https://www.openbsd.org/faq/faq15.html does on preferring the packages
> whenever possible, and the example given suggests the usually
> unnecessary approach of passing the complete path to a fixed version of
> a package to pkg_add. It's not even the current version of the emacs
> package!
>
> > > The installer runs dhclient(8) on the network interface the system
> > > booted from, or in case of multiple interfaces it will ask which one
> > > to use. Upon success it retrieves a response file via HTTP. If that
> >
> > Should there be a comma after success?
>
> There needn't be, but there certainly may be.
>
it;s in, tweaked a bit more. thanks for persevering evan!
jmc
> Index: INSTALL
> ===
> RCS file: /cvs/src/distrib/notes/INSTALL,v
> retrieving revision 1.53
> diff -u -p -r1.53 INSTALL
> --- INSTALL 24 Jun 2019 01:21:46 - 1.53
> +++ INSTALL 30 Jul 2019 04:54:35 -
> @@ -11,10 +11,10 @@ OpenBSD is a fully functional, multi-pla
> System based on Berkeley Networking Release 2 (Net/2) and 4.4BSD-Lite.
> There are several operating systems in this family, but OpenBSD
> differentiates itself by putting security and correctness first. The
> -OpenBSD team strives to achieve what is called a 'secure by default'
> +OpenBSD team strives to achieve what is called a "secure by default"
> status. This means that an OpenBSD user should feel safe that their
> -newly installed machine will not be compromised. This 'secure by
> -default' goal is achieved by taking a proactive stance on security.
> +newly installed machine will not be compromised. This "secure by
> +default" goal is achieved by taking a proactive stance on security.
>
> Since security flaws are essentially mistakes in design or implement-
> ation, the OpenBSD team puts as much importance on finding and fixing
> @@ -138,7 +138,7 @@ Using online OpenBSD documentation:
>
> Documentation is available if you first install the manual pages
> distribution set. Traditionally, the UN*X "man pages" (documentation)
> -are denoted by 'name(section)'. Some examples of this are
> +are denoted by "name(section)". Some examples of this are
>
> intro(1),
> man(1),
> @@ -151,8 +151,8 @@ The section numbers group the topics int
> are of primary interest: user commands are in section 1, file formats
> are in section 5, and administrative information is in section 8.
>
> -The 'man' command is used to view the documentation on a topic, and is
> -started by entering 'man [section] topic'. The brackets [] around the
> +The "man" command is used to view the documentation on a topic, and is
> +started by entering "man [section] topic". The brackets [] around the
> section should not be entered, but rather indicate that the section is
> optional. If you don't ask for a particular section, the topic with the
> least-numbered section name will be displayed. For instance, after
> @@ -175,7 +175,7 @@ where "subject-word" is your topic of in
> related man pages will be displayed.
>
>
> -Adding third party software; ``packages'' and ``ports'':
> +Adding third party software; "packages" and "ports":
>
>
> includeit(packages)
> @@ -194,7 +194,7 @@ netiquette is available at
>
> https://www.OpenBSD.org/mail.html
>
> -To report bugs, use the 'sendbug' command shipped with OpenBSD,
> +To report bugs, use the "sendbug" command shipped with OpenBSD,
> and fill in as much information about the problem as you can. Good
> bug reports {:-include-:} lots of details. Additionally, bug reports can
> be sent by mail to:
> Index: m4.common
> ===
> RCS file: /cvs/src/distrib/notes/m4.common,v
> retrieving revision
Re: Grammar and style edits to installation guide
"T.J. Townsend" wrote:
> > + You may individually select distribution sets to install
> > + by entering their names or wildcards (e.g. `*.tgz' or
> > + `base*|comp*'), or you may enter `all' to select all the
> > + sets (which is what most users will want to do).
>
> > +You should create yourself an account, if you skipped this step during
> > +installation, and protect it and the "root" account with good passwords.
>
> We're mixing these `these' quotes and "normal" ones. It would be great if
> we could rid ourselves of `these' and ``these'' everywhere.
In the updated patch attached, INSTALL and m4.common are standardized to
use "ascii straight double quotes" in running text wherever any other
convention was used. Double quotes are conventional in American English
style guides.
I haven't done this same pass on the arch-specific content blocks, but
it should get done.
As an aside, the file "packages" contains guidance that feels outdated.
It doesn't place the same emphasis that
https://www.openbsd.org/faq/faq15.html does on preferring the packages
whenever possible, and the example given suggests the usually
unnecessary approach of passing the complete path to a fixed version of
a package to pkg_add. It's not even the current version of the emacs
package!
> > The installer runs dhclient(8) on the network interface the system
> > booted from, or in case of multiple interfaces it will ask which one
> > to use. Upon success it retrieves a response file via HTTP. If that
>
> Should there be a comma after success?
There needn't be, but there certainly may be.
Index: INSTALL
===
RCS file: /cvs/src/distrib/notes/INSTALL,v
retrieving revision 1.53
diff -u -p -r1.53 INSTALL
--- INSTALL 24 Jun 2019 01:21:46 - 1.53
+++ INSTALL 30 Jul 2019 04:54:35 -
@@ -11,10 +11,10 @@ OpenBSD is a fully functional, multi-pla
System based on Berkeley Networking Release 2 (Net/2) and 4.4BSD-Lite.
There are several operating systems in this family, but OpenBSD
differentiates itself by putting security and correctness first. The
-OpenBSD team strives to achieve what is called a 'secure by default'
+OpenBSD team strives to achieve what is called a "secure by default"
status. This means that an OpenBSD user should feel safe that their
-newly installed machine will not be compromised. This 'secure by
-default' goal is achieved by taking a proactive stance on security.
+newly installed machine will not be compromised. This "secure by
+default" goal is achieved by taking a proactive stance on security.
Since security flaws are essentially mistakes in design or implement-
ation, the OpenBSD team puts as much importance on finding and fixing
@@ -138,7 +138,7 @@ Using online OpenBSD documentation:
Documentation is available if you first install the manual pages
distribution set. Traditionally, the UN*X "man pages" (documentation)
-are denoted by 'name(section)'. Some examples of this are
+are denoted by "name(section)". Some examples of this are
intro(1),
man(1),
@@ -151,8 +151,8 @@ The section numbers group the topics int
are of primary interest: user commands are in section 1, file formats
are in section 5, and administrative information is in section 8.
-The 'man' command is used to view the documentation on a topic, and is
-started by entering 'man [section] topic'. The brackets [] around the
+The "man" command is used to view the documentation on a topic, and is
+started by entering "man [section] topic". The brackets [] around the
section should not be entered, but rather indicate that the section is
optional. If you don't ask for a particular section, the topic with the
least-numbered section name will be displayed. For instance, after
@@ -175,7 +175,7 @@ where "subject-word" is your topic of in
related man pages will be displayed.
-Adding third party software; ``packages'' and ``ports'':
+Adding third party software; "packages" and "ports":
includeit(packages)
@@ -194,7 +194,7 @@ netiquette is available at
https://www.OpenBSD.org/mail.html
-To report bugs, use the 'sendbug' command shipped with OpenBSD,
+To report bugs, use the "sendbug" command shipped with OpenBSD,
and fill in as much information about the problem as you can. Good
bug reports {:-include-:} lots of details. Additionally, bug reports can
be sent by mail to:
Index: m4.common
===
RCS file: /cvs/src/distrib/notes/m4.common,v
retrieving revision 1.127
diff -u -p -r1.127 m4.common
--- m4.common 23 Aug 2017 02:59:45 - 1.127
+++ m4.common 30 Jul 2019 04:54:35 -
@@ -194,7 +194,7 @@ define({:-OpenBSDfloppydesc-:},
{:-Bootable installation/upgrade floppy image$3:
The $1 floppy image$3 can be copied to a floppy using
Re: Grammar and style edits to installation guide
"Theo de Raadt" wrote: > Evan Silberman wrote: > > > - You may now be given the opportunity to configure the time zone > > - your system will be using (this depends on the installation > > - media you are using). > > - > > - If the installation program skips this question, do not be > > - alarmed, the time zone will be configured at the end > > - of the installation. > > + Depending on the installation media you are using, you may now > > + be given the opportunity to configure the time zone your system > > + will use. If the installation program skips this question, do > > + not be alarmed: the time zone will be configured at the end of > > + the installation. > > This does not depend on the installation media. If anything, it depends > on the network environment (time comes from the attempt to fetch ftplist > from remote, which is always performed in the background). But I think > it is no longer true that it asks early, I think the manual time > adjustment is only at the end. This paragraph is referring to time _zone_ selection, and the dependency on installation media (as best I can tell from my first-ever read of install.sub and the ramdisk list files, mind you) appears to be that a time zone list is not included in the floppy images due to space constraints. The installation guides don't appear mention that the user might be asked to weigh in on adjusting the system time. Evan Silberman
Re: Grammar and style edits to installation guide
Evan Silberman wrote: > - You may now be given the opportunity to configure the time zone > - your system will be using (this depends on the installation > - media you are using). > - > - If the installation program skips this question, do not be > - alarmed, the time zone will be configured at the end > - of the installation. > + Depending on the installation media you are using, you may now > + be given the opportunity to configure the time zone your system > + will use. If the installation program skips this question, do > + not be alarmed: the time zone will be configured at the end of > + the installation. This does not depend on the installation media. If anything, it depends on the network environment (time comes from the attempt to fetch ftplist from remote, which is always performed in the background). But I think it is no longer true that it asks early, I think the manual time adjustment is only at the end.
Re: Grammar and style edits to installation guide
Jason McIntyre wrote:
> ok. so if i didn't comment on a change, i didn;t see any issue.
> if it's a rewording of an already ok text, i don;t see the point.
> i don;t see the point of Un*x->Unix, but some of our more, er,
> experienced, developers may want to chip in.
Hi Jason & tech@,
Below is my patch to the installation guide macros from a few weeks ago,
including only hunks jmc had no issues with, and without addressing the
UN*X/UNIX/Unix issue.
thanks!
Evan Silberman
Index: m4.common
===
RCS file: /cvs/src/distrib/notes/m4.common,v
retrieving revision 1.127
diff -u -p -r1.127 m4.common
--- m4.common 23 Aug 2017 02:59:45 - 1.127
+++ m4.common 27 Jul 2019 16:34:28 -
@@ -409,7 +409,7 @@ dnl install.sub (install) user_setup()
with a lowercase letter. If the login name matches this
criteria, and doesn't conflict with any of the administrative
user accounts (such as `root', `daemon' or `ftp'), you
- will be prompted with the users descriptive name, as well
+ will be prompted for the user's descriptive name, as well
as its password, twice.
As for the root password earlier, the install program will only
@@ -422,13 +422,11 @@ dnl install.sub (install) user_setup()
dnl install.sub (install) set_timezone
ifelse(MDTZ,,,
{:-
- You may now be given the opportunity to configure the time zone
- your system will be using (this depends on the installation
- media you are using).
-
- If the installation program skips this question, do not be
- alarmed, the time zone will be configured at the end
- of the installation.
+ Depending on the installation media you are using, you may now
+ be given the opportunity to configure the time zone your system
+ will use. If the installation program skips this question, do
+ not be alarmed: the time zone will be configured at the end of
+ the installation.
-:})dnl
dnl install.sh ask whether to use DUIDs before the md_prep_disklabel loop
The installation program will now tell you which disks it can
@@ -512,7 +510,7 @@ define({:-OpenBSDInstallPart5-:},
partition layout) and the `n' command (to change mount points)
are of particular interest.
- Although the partitions position and size are written in exact
+ Although the partitions' position and size are written in exact
sector values, you do not need a calculator to create your
partitions! Human-friendly units can be specified by adding `k',
`m' or `g' after any numbers to have them converted to kilobytes,
@@ -652,10 +650,10 @@ define({:-OpenBSDCommonInstall-:},
A list of available distribution sets found on the
given location will be listed.
- You may individually select distribution sets to install,
- by entering their name, or wildcards (e.g. `*.tgz' or
- `base*|comp*', or `all' to select all the sets (which
- is what most users will want to do).
+ You may individually select distribution sets to install
+ by entering their names or wildcards (e.g. `*.tgz' or
+ `base*|comp*'), or you may enter `all' to select all the
+ sets (which is what most users will want to do).
You may also enter `abort' to deselect everything and
restart the selection from scratch, or unselect sets
by entering their name prefixed with `-' (e.g. `-x*').
@@ -710,8 +708,8 @@ dnl
define({:-OpenBSDCongratulations-:},{:-
Congratulations, you have successfully installed OpenBSD OSREV. When you
reboot into OpenBSD, you should log in as "root" at the login prompt.
-You should create yourself an account and protect it and the "root"
-account with good passwords.
+You should create yourself an account, if you skipped this step during
+installation, and protect it and the "root" account with good passwords.
The install program leaves root an initial mail message. We recommend
you read it, as it contains answers to basic questions you might have
@@ -751,8 +749,8 @@ installation.
The installer runs dhclient(8) on the network interface the system
booted from, or in case of multiple interfaces it will ask which one
to use. Upon success it retrieves a response file via HTTP. If that
-fails, the installer asks for the response file location which can be
-either an url or a local path and retrieves the response file from
+fails, the installer asks for the response file location, which can be
+either a URL or a local path, and retrieves the response file from
there.
The "next-server" DHCP option specifies the hostname part of the URL,
Re: Grammar and style edits to installation guide
Ian McWilliam wrote: > Isn't Unix a trademark of the Open Group? Hence the usage of Unix-like or > Un*x.. That trademark is UNIX, all caps. According to [APUEv3]: "The Open Group owns the UNIX trademark and uses the Single UNIX Specification to define the interfaces an implementation must support to call itself a UNIX system. Vendors must file conformance statements, pass test suites to verify conformance, and license the right to use the UNIX trademark." For example, Mac OS X 10.5 and other big commercial brands have been [certified] and may call themselves a UNIX system (again, the all caps variant is significant here). [APUEv3] Advanced Programming in the UNIX Environment Third Edition p30 [certified] https://www.opengroup.org/certifications/unix
Re: Grammar and style edits to installation guide
On Mon, Jul 08, 2019 at 11:56:58PM -0700, Evan Silberman wrote:
> Jason McIntyre wrote:
> > On Tue, Jul 09, 2019 at 07:43:50AM +0200, Otto Moerbeek wrote:
> > > On Mon, Jul 08, 2019 at 10:26:57AM -0700, Evan Silberman wrote:
> > >
> > > I don't know our stance on Unix vs Un*x. I'll leave this to some
> > > native speaker, like jmc@ who knows all about commas (and much more)
> > > :-)
> > >
> > > -Otto
> > >
> >
> > hi.
> >
> > i'm fairly sure Un*x is meant to denote the various flavours of unix,
> > and is probably pretty widespread in our docs. however i haven;t checked
> > that. i don;t really see a reason to change it unless we've somehow
> > decided that it doesn;t make sense and we make such changes wholesale.
>
> I think it makes sense to write "Unix-like" instead of "Un*x-like" or
> "UN*X-like" wherever it appears in the general case; it is more legible
> to lay readers and conveys basically the same information. The homepage
> reads "UNIX-like". (I also would propose that the all-caps styling is at
> best something of a throwback and "Unix" should be preferred unless the
> developers are extremely fond of the caps, but that's neither here nor
> there.)
>
you might be right about Unix-like. i was thinking of pure un*x->unix.
but note that we have an awful lot of "UNIX" in our docs.
i guess i'm not the person to answer this either.
> > > > Index: m4.common
> > > > ===
> > > > RCS file: /cvs/src/distrib/notes/m4.common,v
> > > > retrieving revision 1.127
> > > > diff -u -p -r1.127 m4.common
> > > > --- m4.common 23 Aug 2017 02:59:45 - 1.127
> > > > +++ m4.common 8 Jul 2019 17:24:49 -
> > > > @@ -284,8 +284,8 @@ dnl Describes the boot of the ramdisk.
> > > > dnl Describes the serial terminal setup.
> > > > define({:-OpenBSDInstallPart3-:},
> > > > {:-Once the kernel has loaded, you will be presented with the
> > > > - OpenBSD kernel boot messages which contain information about
> > > > - the hardware that was detected and supported by OpenBSD.
> > > > + OpenBSD kernel boot messages, which contain information about
> > > > + detected and supported hardware.
> > > >
> >
> > well this is just saying one thing another way, isn;t it? i don;t see
> > the point. oh, but the comma before "which" is correct.
>
> Came to this line to add the comma, rephrased what came after mostly due
> to the needless echoing of "OpenBSD".
>
i don;t see it as an improvement, to be honest. though i agree with the
comma.
> >
> > > > dnl dot.profile
> > > > After the kernel is done initializing, you will be asked whether
> > > > @@ -327,9 +327,9 @@ dnl install.sub (install) hostname
> > > > dnl install.sub (install) donetconfig
> > > > You will now be given an opportunity to configure the network.
> > > > The network configuration you enter (if any) can then be used to
> > > > - do the install from another system using HTTP, and will also be
> > > > - the configuration used by the system after the installation is
> > > > - complete.
> > > > + obtain installation sets from another system using HTTP, and
> > > > + will also be the configuration used by the system after the
> > > > + installation is complete.
> > > >
> >
> > again, what was wrong with the text that's there? if anything, i'd be
> > tempted to remove "do the". but i don;t have an issue with what's there
> > now.
>
> "do the install" read imprecisely to me (do how?); I rewrote to match my
http
> understanding of what activity is actually done over HTTP when the
> network is configured.
>
> >
> > > > dnl XXX add a MDVLAN feature and document vlan setup
> > > > The install program will give you a list of network interfaces
> > > > you
> > > > @@ -409,10 +409,10 @@ dnl install.sub (install) user_setup()
> > > > with a lowercase letter. If the login name matches this
> > > > criteria, and doesn't conflict with any of the administrative
> > > > user accounts (such as `root', `daemon' or `ftp'), you
> > > > - will be prompted with the users descriptive name, as well
> > > > - as its password, twice.
> > > > + will be prompted for the user's descriptive name, then twice
> > > > + for its password.
> >
> > user->user's makes sense
> > the rewording doesn;t
>
> "prompted with the user's descriptive name" is not right; the prompt
> _asks for_ this name. The appendix ", twice" on the original sentence
"prompt with" is not incorrect
> reads like you might be prompted for each piece of information (long
> name, password) twice, and since I was here making other fixes I
> rephrased.
>
yes, i see that ambiguity now. but it's not one that is going to catch
anyone out, and i'd argue that your sentence structure is more
complicated.
> >
> > > >
> > > > - As for the root password earlier, the install program will
Re: Grammar and style edits to installation guide
Ian McWilliam wrote: > Isn't Unix a trademark of the Open Group? Hence the usage of Unix-like or > Un*x.. Yeah I have no complaint with "Unix-like". I'm happy to learn about the historical reasons for writing "Un*x". If it's to be suggestive of variants, that makes a little bit of sense, though if we interpret it as a shell glob I'm not sure what other extant system names other than "Unix" are matched by "Un*x". If it started as self-censorship of the word "Unix" in an attempt to avoid trademark infringement, that strikes me as unlikely to be a legally consequential maneuver. (But I am not a lawyer etc etc) Evan Silberman
Re: Grammar and style edits to installation guide
Jason McIntyre wrote:
> On Tue, Jul 09, 2019 at 07:43:50AM +0200, Otto Moerbeek wrote:
> > On Mon, Jul 08, 2019 at 10:26:57AM -0700, Evan Silberman wrote:
> >
> > I don't know our stance on Unix vs Un*x. I'll leave this to some
> > native speaker, like jmc@ who knows all about commas (and much more)
> > :-)
> >
> > -Otto
> >
>
> hi.
>
> i'm fairly sure Un*x is meant to denote the various flavours of unix,
> and is probably pretty widespread in our docs. however i haven;t checked
> that. i don;t really see a reason to change it unless we've somehow
> decided that it doesn;t make sense and we make such changes wholesale.
I think it makes sense to write "Unix-like" instead of "Un*x-like" or
"UN*X-like" wherever it appears in the general case; it is more legible
to lay readers and conveys basically the same information. The homepage
reads "UNIX-like". (I also would propose that the all-caps styling is at
best something of a throwback and "Unix" should be preferred unless the
developers are extremely fond of the caps, but that's neither here nor
there.)
>
> i'll try to comment on the rest of the diff inline..
>
> > I'll leave this to jmc or some other native speaker. S
> > > Otto Moerbeek wrote:
> > > > On Sun, Jul 07, 2019 at 10:44:42PM -0700, Evan Silberman wrote:
> > > >
> > > > > I noticed one thing that bothered me and decided to look for other
> > > > > things that bothered me. Changes were made without reference to the
> > > > > code
> > > > > of the installation program and without checking that the installer
> > > > > behaves as documented. I believe the included changes are harmless in
> > > > > that respect. I'm happy to provide explanations of any given line edit
> > > > > on request, but I hope they are self-explanatory. `make allarchs` ran
> > > > > without issues and I don't seem to have broken any formatting.
> > > > >
> > > > > Regards,
> > > > > Evan Silberman
> > > > >
> > > > >
> > > > > Index: m4.common
> > > > > ===
> > > > > RCS file: /cvs/src/distrib/notes/m4.common,v
> > > > > retrieving revision 1.127
> > > > > diff -u -p -r1.127 m4.common
> > > > > --- m4.common 23 Aug 2017 02:59:45 - 1.127
> > > > > +++ m4.common 8 Jul 2019 05:36:28 -
> > > > > @@ -284,8 +284,8 @@ dnl Describes the boot of the ramdisk.
> > > > > dnl Describes the serial terminal setup.
> > > > > define({:-OpenBSDInstallPart3-:},
> > > > > {:- Once the kernel has loaded, you will be presented with the
> > > > > - OpenBSD kernel boot messages which contain information about
> > > > > - the hardware that was detected and supported by OpenBSD.
> > > > > + OpenBSD kernel boot messages, which contain information about
> > > > > + the supported hardware that was detected by OpenBSD.
> > > >
> > > > This is not true. OpenBSD does print information about hardware
> > > > detected but not supported. e.g.:
> > > >
> > > > "usb3_phy0" at mainbus0 not configured
> > > >
> > > > -Otto
> > >
> > > Below version corrects this as well as changing a few remaining instances
> > > of
> > > 'UN*X' to 'Unix'.
> > >
> > >
> > > Index: INSTALL
> > > ===
> > > RCS file: /cvs/src/distrib/notes/INSTALL,v
> > > retrieving revision 1.53
> > > diff -u -p -r1.53 INSTALL
> > > --- INSTALL 24 Jun 2019 01:21:46 - 1.53
> > > +++ INSTALL 8 Jul 2019 17:24:49 -
> > > @@ -7,7 +7,7 @@ INSTALLATION NOTES for OpenBSD/MACHINE O
> > > What is OpenBSD?
> > >
> > >
> > > -OpenBSD is a fully functional, multi-platform UN*X-like Operating
> > > +OpenBSD is a fully functional, multi-platform Unix-like Operating
> > > System based on Berkeley Networking Release 2 (Net/2) and 4.4BSD-Lite.
> > > There are several operating systems in this family, but OpenBSD
> > > differentiates itself by putting security and correctness first. The
> > > @@ -137,7 +137,7 @@ Using online OpenBSD documentation:
> > > ---
> > >
> > > Documentation is available if you first install the manual pages
> > > -distribution set. Traditionally, the UN*X "man pages" (documentation)
> > > +distribution set. Traditionally, the Unix "man pages" (documentation)
> > > are denoted by 'name(section)'. Some examples of this are
> > >
> > > intro(1),
> > > Index: m4.common
> > > ===
> > > RCS file: /cvs/src/distrib/notes/m4.common,v
> > > retrieving revision 1.127
> > > diff -u -p -r1.127 m4.common
> > > --- m4.common 23 Aug 2017 02:59:45 - 1.127
> > > +++ m4.common 8 Jul 2019 17:24:49 -
> > > @@ -284,8 +284,8 @@ dnl Describes the boot of the ramdisk.
> > > dnl Describes the serial terminal setup.
> > > define({:-OpenBSDInstallPart3-:},
> > > {:- Once the kernel has loaded, you will be presented with the
> > > - OpenBSD kernel
Re: Grammar and style edits to installation guide
Isn't Unix a trademark of the Open Group? Hence the usage of Unix-like or Un*x..
Ian McWilliam
From: owner-t...@openbsd.org on behalf of Jason
McIntyre
Sent: Tuesday, 9 July 2019 4:14 PM
To: tech@openbsd.org
Subject: Re: Grammar and style edits to installation guide
On Tue, Jul 09, 2019 at 07:43:50AM +0200, Otto Moerbeek wrote:
> On Mon, Jul 08, 2019 at 10:26:57AM -0700, Evan Silberman wrote:
>
> I don't know our stance on Unix vs Un*x. I'll leave this to some
> native speaker, like jmc@ who knows all about commas (and much more)
> :-)
>
>-Otto
>
hi.
i'm fairly sure Un*x is meant to denote the various flavours of unix,
and is probably pretty widespread in our docs. however i haven;t checked
that. i don;t really see a reason to change it unless we've somehow
decided that it doesn;t make sense and we make such changes wholesale.
i'll try to comment on the rest of the diff inline..
> I'll leave this to jmc or some other native speaker. S
> > Otto Moerbeek wrote:
> > > On Sun, Jul 07, 2019 at 10:44:42PM -0700, Evan Silberman wrote:
> > >
> > > > I noticed one thing that bothered me and decided to look for other
> > > > things that bothered me. Changes were made without reference to the code
> > > > of the installation program and without checking that the installer
> > > > behaves as documented. I believe the included changes are harmless in
> > > > that respect. I'm happy to provide explanations of any given line edit
> > > > on request, but I hope they are self-explanatory. `make allarchs` ran
> > > > without issues and I don't seem to have broken any formatting.
> > > >
> > > > Regards,
> > > > Evan Silberman
> > > >
> > > >
> > > > Index: m4.common
> > > > ===
> > > > RCS file: /cvs/src/distrib/notes/m4.common,v
> > > > retrieving revision 1.127
> > > > diff -u -p -r1.127 m4.common
> > > > --- m4.common 23 Aug 2017 02:59:45 - 1.127
> > > > +++ m4.common 8 Jul 2019 05:36:28 -
> > > > @@ -284,8 +284,8 @@ dnl Describes the boot of the ramdisk.
> > > > dnl Describes the serial terminal setup.
> > > > define({:-OpenBSDInstallPart3-:},
> > > > {:-Once the kernel has loaded, you will be presented with the
> > > > - OpenBSD kernel boot messages which contain information about
> > > > - the hardware that was detected and supported by OpenBSD.
> > > > + OpenBSD kernel boot messages, which contain information about
> > > > + the supported hardware that was detected by OpenBSD.
> > >
> > > This is not true. OpenBSD does print information about hardware
> > > detected but not supported. e.g.:
> > >
> > > "usb3_phy0" at mainbus0 not configured
> > >
> > >-Otto
> >
> > Below version corrects this as well as changing a few remaining instances of
> > 'UN*X' to 'Unix'.
> >
> >
> > Index: INSTALL
> > ===
> > RCS file: /cvs/src/distrib/notes/INSTALL,v
> > retrieving revision 1.53
> > diff -u -p -r1.53 INSTALL
> > --- INSTALL 24 Jun 2019 01:21:46 - 1.53
> > +++ INSTALL 8 Jul 2019 17:24:49 -
> > @@ -7,7 +7,7 @@ INSTALLATION NOTES for OpenBSD/MACHINE O
> > What is OpenBSD?
> >
> >
> > -OpenBSD is a fully functional, multi-platform UN*X-like Operating
> > +OpenBSD is a fully functional, multi-platform Unix-like Operating
> > System based on Berkeley Networking Release 2 (Net/2) and 4.4BSD-Lite.
> > There are several operating systems in this family, but OpenBSD
> > differentiates itself by putting security and correctness first. The
> > @@ -137,7 +137,7 @@ Using online OpenBSD documentation:
> > ---
> >
> > Documentation is available if you first install the manual pages
> > -distribution set. Traditionally, the UN*X "man pages" (documentation)
> > +distribution set. Traditionally, the Unix "man pages" (documentation)
> > are denoted by 'name(section)'. Some examples of this are
> >
> > intro(1),
> > Index: m4.common
> > ===
> > RCS file: /cvs/src/distrib/notes/m4.common,v
> > retrieving revision 1.127
> > diff -u -p -r1.127 m4.common
> > --- m4.common 23 Aug 2017 02:59:45 -00
Re: Grammar and style edits to installation guide
On Tue, Jul 09, 2019 at 07:43:50AM +0200, Otto Moerbeek wrote:
> On Mon, Jul 08, 2019 at 10:26:57AM -0700, Evan Silberman wrote:
>
> I don't know our stance on Unix vs Un*x. I'll leave this to some
> native speaker, like jmc@ who knows all about commas (and much more)
> :-)
>
> -Otto
>
hi.
i'm fairly sure Un*x is meant to denote the various flavours of unix,
and is probably pretty widespread in our docs. however i haven;t checked
that. i don;t really see a reason to change it unless we've somehow
decided that it doesn;t make sense and we make such changes wholesale.
i'll try to comment on the rest of the diff inline..
> I'll leave this to jmc or some other native speaker. S
> > Otto Moerbeek wrote:
> > > On Sun, Jul 07, 2019 at 10:44:42PM -0700, Evan Silberman wrote:
> > >
> > > > I noticed one thing that bothered me and decided to look for other
> > > > things that bothered me. Changes were made without reference to the code
> > > > of the installation program and without checking that the installer
> > > > behaves as documented. I believe the included changes are harmless in
> > > > that respect. I'm happy to provide explanations of any given line edit
> > > > on request, but I hope they are self-explanatory. `make allarchs` ran
> > > > without issues and I don't seem to have broken any formatting.
> > > >
> > > > Regards,
> > > > Evan Silberman
> > > >
> > > >
> > > > Index: m4.common
> > > > ===
> > > > RCS file: /cvs/src/distrib/notes/m4.common,v
> > > > retrieving revision 1.127
> > > > diff -u -p -r1.127 m4.common
> > > > --- m4.common 23 Aug 2017 02:59:45 - 1.127
> > > > +++ m4.common 8 Jul 2019 05:36:28 -
> > > > @@ -284,8 +284,8 @@ dnl Describes the boot of the ramdisk.
> > > > dnl Describes the serial terminal setup.
> > > > define({:-OpenBSDInstallPart3-:},
> > > > {:-Once the kernel has loaded, you will be presented with the
> > > > - OpenBSD kernel boot messages which contain information about
> > > > - the hardware that was detected and supported by OpenBSD.
> > > > + OpenBSD kernel boot messages, which contain information about
> > > > + the supported hardware that was detected by OpenBSD.
> > >
> > > This is not true. OpenBSD does print information about hardware
> > > detected but not supported. e.g.:
> > >
> > > "usb3_phy0" at mainbus0 not configured
> > >
> > > -Otto
> >
> > Below version corrects this as well as changing a few remaining instances of
> > 'UN*X' to 'Unix'.
> >
> >
> > Index: INSTALL
> > ===
> > RCS file: /cvs/src/distrib/notes/INSTALL,v
> > retrieving revision 1.53
> > diff -u -p -r1.53 INSTALL
> > --- INSTALL 24 Jun 2019 01:21:46 - 1.53
> > +++ INSTALL 8 Jul 2019 17:24:49 -
> > @@ -7,7 +7,7 @@ INSTALLATION NOTES for OpenBSD/MACHINE O
> > What is OpenBSD?
> >
> >
> > -OpenBSD is a fully functional, multi-platform UN*X-like Operating
> > +OpenBSD is a fully functional, multi-platform Unix-like Operating
> > System based on Berkeley Networking Release 2 (Net/2) and 4.4BSD-Lite.
> > There are several operating systems in this family, but OpenBSD
> > differentiates itself by putting security and correctness first. The
> > @@ -137,7 +137,7 @@ Using online OpenBSD documentation:
> > ---
> >
> > Documentation is available if you first install the manual pages
> > -distribution set. Traditionally, the UN*X "man pages" (documentation)
> > +distribution set. Traditionally, the Unix "man pages" (documentation)
> > are denoted by 'name(section)'. Some examples of this are
> >
> > intro(1),
> > Index: m4.common
> > ===
> > RCS file: /cvs/src/distrib/notes/m4.common,v
> > retrieving revision 1.127
> > diff -u -p -r1.127 m4.common
> > --- m4.common 23 Aug 2017 02:59:45 - 1.127
> > +++ m4.common 8 Jul 2019 17:24:49 -
> > @@ -284,8 +284,8 @@ dnl Describes the boot of the ramdisk.
> > dnl Describes the serial terminal setup.
> > define({:-OpenBSDInstallPart3-:},
> > {:-Once the kernel has loaded, you will be presented with the
> > - OpenBSD kernel boot messages which contain information about
> > - the hardware that was detected and supported by OpenBSD.
> > + OpenBSD kernel boot messages, which contain information about
> > + detected and supported hardware.
> >
well this is just saying one thing another way, isn;t it? i don;t see
the point. oh, but the comma before "which" is correct.
> > dnl dot.profile
> > After the kernel is done initializing, you will be asked whether
> > @@ -327,9 +327,9 @@ dnl install.sub (install) hostname
> > dnl install.sub (install) donetconfig
> > You will now be given an opportunity to configure the network.
> > The network configuration you enter (if
Re: Grammar and style edits to installation guide
On Mon, Jul 08, 2019 at 10:26:57AM -0700, Evan Silberman wrote:
I don't know our stance on Unix vs Un*x. I'll leave this to some
native speaker, like jmc@ who knows all about commas (and much more)
:-)
-Otto
I'll leave this to jmc or some other native speaker. S
> Otto Moerbeek wrote:
> > On Sun, Jul 07, 2019 at 10:44:42PM -0700, Evan Silberman wrote:
> >
> > > I noticed one thing that bothered me and decided to look for other
> > > things that bothered me. Changes were made without reference to the code
> > > of the installation program and without checking that the installer
> > > behaves as documented. I believe the included changes are harmless in
> > > that respect. I'm happy to provide explanations of any given line edit
> > > on request, but I hope they are self-explanatory. `make allarchs` ran
> > > without issues and I don't seem to have broken any formatting.
> > >
> > > Regards,
> > > Evan Silberman
> > >
> > >
> > > Index: m4.common
> > > ===
> > > RCS file: /cvs/src/distrib/notes/m4.common,v
> > > retrieving revision 1.127
> > > diff -u -p -r1.127 m4.common
> > > --- m4.common 23 Aug 2017 02:59:45 - 1.127
> > > +++ m4.common 8 Jul 2019 05:36:28 -
> > > @@ -284,8 +284,8 @@ dnl Describes the boot of the ramdisk.
> > > dnl Describes the serial terminal setup.
> > > define({:-OpenBSDInstallPart3-:},
> > > {:- Once the kernel has loaded, you will be presented with the
> > > - OpenBSD kernel boot messages which contain information about
> > > - the hardware that was detected and supported by OpenBSD.
> > > + OpenBSD kernel boot messages, which contain information about
> > > + the supported hardware that was detected by OpenBSD.
> >
> > This is not true. OpenBSD does print information about hardware
> > detected but not supported. e.g.:
> >
> > "usb3_phy0" at mainbus0 not configured
> >
> > -Otto
>
> Below version corrects this as well as changing a few remaining instances of
> 'UN*X' to 'Unix'.
>
>
> Index: INSTALL
> ===
> RCS file: /cvs/src/distrib/notes/INSTALL,v
> retrieving revision 1.53
> diff -u -p -r1.53 INSTALL
> --- INSTALL 24 Jun 2019 01:21:46 - 1.53
> +++ INSTALL 8 Jul 2019 17:24:49 -
> @@ -7,7 +7,7 @@ INSTALLATION NOTES for OpenBSD/MACHINE O
> What is OpenBSD?
>
>
> -OpenBSD is a fully functional, multi-platform UN*X-like Operating
> +OpenBSD is a fully functional, multi-platform Unix-like Operating
> System based on Berkeley Networking Release 2 (Net/2) and 4.4BSD-Lite.
> There are several operating systems in this family, but OpenBSD
> differentiates itself by putting security and correctness first. The
> @@ -137,7 +137,7 @@ Using online OpenBSD documentation:
> ---
>
> Documentation is available if you first install the manual pages
> -distribution set. Traditionally, the UN*X "man pages" (documentation)
> +distribution set. Traditionally, the Unix "man pages" (documentation)
> are denoted by 'name(section)'. Some examples of this are
>
> intro(1),
> Index: m4.common
> ===
> RCS file: /cvs/src/distrib/notes/m4.common,v
> retrieving revision 1.127
> diff -u -p -r1.127 m4.common
> --- m4.common 23 Aug 2017 02:59:45 - 1.127
> +++ m4.common 8 Jul 2019 17:24:49 -
> @@ -284,8 +284,8 @@ dnl Describes the boot of the ramdisk.
> dnl Describes the serial terminal setup.
> define({:-OpenBSDInstallPart3-:},
> {:- Once the kernel has loaded, you will be presented with the
> - OpenBSD kernel boot messages which contain information about
> - the hardware that was detected and supported by OpenBSD.
> + OpenBSD kernel boot messages, which contain information about
> + detected and supported hardware.
>
> dnl dot.profile
> After the kernel is done initializing, you will be asked whether
> @@ -327,9 +327,9 @@ dnl install.sub (install) hostname
> dnl install.sub (install) donetconfig
> You will now be given an opportunity to configure the network.
> The network configuration you enter (if any) can then be used to
> - do the install from another system using HTTP, and will also be
> - the configuration used by the system after the installation is
> - complete.
> + obtain installation sets from another system using HTTP, and
> + will also be the configuration used by the system after the
> + installation is complete.
>
> dnl XXX add a MDVLAN feature and document vlan setup
> The install program will give you a list of network interfaces you
> @@ -409,10 +409,10 @@ dnl install.sub (install) user_setup()
> with a lowercase letter. If the login name matches this
> criteria, and doesn't conflict with any of the administrative
> user accounts (such as `root', `daemon' or
Re: Grammar and style edits to installation guide
Otto Moerbeek wrote:
> On Sun, Jul 07, 2019 at 10:44:42PM -0700, Evan Silberman wrote:
>
> > I noticed one thing that bothered me and decided to look for other
> > things that bothered me. Changes were made without reference to the code
> > of the installation program and without checking that the installer
> > behaves as documented. I believe the included changes are harmless in
> > that respect. I'm happy to provide explanations of any given line edit
> > on request, but I hope they are self-explanatory. `make allarchs` ran
> > without issues and I don't seem to have broken any formatting.
> >
> > Regards,
> > Evan Silberman
> >
> >
> > Index: m4.common
> > ===
> > RCS file: /cvs/src/distrib/notes/m4.common,v
> > retrieving revision 1.127
> > diff -u -p -r1.127 m4.common
> > --- m4.common 23 Aug 2017 02:59:45 - 1.127
> > +++ m4.common 8 Jul 2019 05:36:28 -
> > @@ -284,8 +284,8 @@ dnl Describes the boot of the ramdisk.
> > dnl Describes the serial terminal setup.
> > define({:-OpenBSDInstallPart3-:},
> > {:-Once the kernel has loaded, you will be presented with the
> > - OpenBSD kernel boot messages which contain information about
> > - the hardware that was detected and supported by OpenBSD.
> > + OpenBSD kernel boot messages, which contain information about
> > + the supported hardware that was detected by OpenBSD.
>
> This is not true. OpenBSD does print information about hardware
> detected but not supported. e.g.:
>
> "usb3_phy0" at mainbus0 not configured
>
> -Otto
Below version corrects this as well as changing a few remaining instances of
'UN*X' to 'Unix'.
Index: INSTALL
===
RCS file: /cvs/src/distrib/notes/INSTALL,v
retrieving revision 1.53
diff -u -p -r1.53 INSTALL
--- INSTALL 24 Jun 2019 01:21:46 - 1.53
+++ INSTALL 8 Jul 2019 17:24:49 -
@@ -7,7 +7,7 @@ INSTALLATION NOTES for OpenBSD/MACHINE O
What is OpenBSD?
-OpenBSD is a fully functional, multi-platform UN*X-like Operating
+OpenBSD is a fully functional, multi-platform Unix-like Operating
System based on Berkeley Networking Release 2 (Net/2) and 4.4BSD-Lite.
There are several operating systems in this family, but OpenBSD
differentiates itself by putting security and correctness first. The
@@ -137,7 +137,7 @@ Using online OpenBSD documentation:
---
Documentation is available if you first install the manual pages
-distribution set. Traditionally, the UN*X "man pages" (documentation)
+distribution set. Traditionally, the Unix "man pages" (documentation)
are denoted by 'name(section)'. Some examples of this are
intro(1),
Index: m4.common
===
RCS file: /cvs/src/distrib/notes/m4.common,v
retrieving revision 1.127
diff -u -p -r1.127 m4.common
--- m4.common 23 Aug 2017 02:59:45 - 1.127
+++ m4.common 8 Jul 2019 17:24:49 -
@@ -284,8 +284,8 @@ dnl Describes the boot of the ramdisk.
dnl Describes the serial terminal setup.
define({:-OpenBSDInstallPart3-:},
{:-Once the kernel has loaded, you will be presented with the
- OpenBSD kernel boot messages which contain information about
- the hardware that was detected and supported by OpenBSD.
+ OpenBSD kernel boot messages, which contain information about
+ detected and supported hardware.
dnl dot.profile
After the kernel is done initializing, you will be asked whether
@@ -327,9 +327,9 @@ dnl install.sub (install) hostname
dnl install.sub (install) donetconfig
You will now be given an opportunity to configure the network.
The network configuration you enter (if any) can then be used to
- do the install from another system using HTTP, and will also be
- the configuration used by the system after the installation is
- complete.
+ obtain installation sets from another system using HTTP, and
+ will also be the configuration used by the system after the
+ installation is complete.
dnl XXX add a MDVLAN feature and document vlan setup
The install program will give you a list of network interfaces you
@@ -409,10 +409,10 @@ dnl install.sub (install) user_setup()
with a lowercase letter. If the login name matches this
criteria, and doesn't conflict with any of the administrative
user accounts (such as `root', `daemon' or `ftp'), you
- will be prompted with the users descriptive name, as well
- as its password, twice.
+ will be prompted for the user's descriptive name, then twice
+ for its password.
- As for the root password earlier, the install program will only
+ As with the root password earlier, the install program will only
check that the two passwords match, but you should make
Re: Grammar and style edits to installation guide
On Sun, Jul 07, 2019 at 10:44:42PM -0700, Evan Silberman wrote:
> I noticed one thing that bothered me and decided to look for other
> things that bothered me. Changes were made without reference to the code
> of the installation program and without checking that the installer
> behaves as documented. I believe the included changes are harmless in
> that respect. I'm happy to provide explanations of any given line edit
> on request, but I hope they are self-explanatory. `make allarchs` ran
> without issues and I don't seem to have broken any formatting.
>
> Regards,
> Evan Silberman
>
>
> Index: m4.common
> ===
> RCS file: /cvs/src/distrib/notes/m4.common,v
> retrieving revision 1.127
> diff -u -p -r1.127 m4.common
> --- m4.common 23 Aug 2017 02:59:45 - 1.127
> +++ m4.common 8 Jul 2019 05:36:28 -
> @@ -284,8 +284,8 @@ dnl Describes the boot of the ramdisk.
> dnl Describes the serial terminal setup.
> define({:-OpenBSDInstallPart3-:},
> {:- Once the kernel has loaded, you will be presented with the
> - OpenBSD kernel boot messages which contain information about
> - the hardware that was detected and supported by OpenBSD.
> + OpenBSD kernel boot messages, which contain information about
> + the supported hardware that was detected by OpenBSD.
This is not true. OpenBSD does print information about hardware
detected but not supported. e.g.:
"usb3_phy0" at mainbus0 not configured
-Otto
>
> dnl dot.profile
> After the kernel is done initializing, you will be asked whether
> @@ -327,9 +327,9 @@ dnl install.sub (install) hostname
> dnl install.sub (install) donetconfig
> You will now be given an opportunity to configure the network.
> The network configuration you enter (if any) can then be used to
> - do the install from another system using HTTP, and will also be
> - the configuration used by the system after the installation is
> - complete.
> + obtain installation sets from another system using HTTP, and
> + will also be the configuration used by the system after the
> + installation is complete.
>
> dnl XXX add a MDVLAN feature and document vlan setup
> The install program will give you a list of network interfaces you
> @@ -409,10 +409,10 @@ dnl install.sub (install) user_setup()
> with a lowercase letter. If the login name matches this
> criteria, and doesn't conflict with any of the administrative
> user accounts (such as `root', `daemon' or `ftp'), you
> - will be prompted with the users descriptive name, as well
> - as its password, twice.
> + will be prompted for the user's descriptive name, then twice
> + for its password.
>
> - As for the root password earlier, the install program will only
> + As with the root password earlier, the install program will only
> check that the two passwords match, but you should make sure to
> use a strong password here as well.
>
> @@ -422,13 +422,11 @@ dnl install.sub (install) user_setup()
> dnl install.sub (install) set_timezone
> ifelse(MDTZ,,,
> {:-
> - You may now be given the opportunity to configure the time zone
> - your system will be using (this depends on the installation
> - media you are using).
> -
> - If the installation program skips this question, do not be
> - alarmed, the time zone will be configured at the end
> - of the installation.
> + Depending on the installation media you are using, you may now
> + be given the opportunity to configure the time zone your system
> + will use. If the installation program skips this question, do
> + not be alarmed: the time zone will be configured at the end of
> + the installation.
> -:})dnl
> dnl install.sh ask whether to use DUIDs before the md_prep_disklabel loop
> The installation program will now tell you which disks it can
> @@ -512,7 +510,7 @@ define({:-OpenBSDInstallPart5-:},
> partition layout) and the `n' command (to change mount points)
> are of particular interest.
>
> - Although the partitions position and size are written in exact
> + Although the partitions' position and size are written in exact
> sector values, you do not need a calculator to create your
> partitions! Human-friendly units can be specified by adding `k',
> `m' or `g' after any numbers to have them converted to kilobytes,
> @@ -652,10 +650,10 @@ define({:-OpenBSDCommonInstall-:},
> A list of available distribution sets found on the
> given location will be listed.
>
> - You may individually select distribution sets to install,
> - by entering their name, or wildcards (e.g. `*.tgz' or
> - `base*|comp*', or `all' to select all the sets (which
> - is what most users will want to do).
> + You may individually select
