Page MenuHomeFreeBSD

handbook: Update the first chunk of Linuxulator chapter
ClosedPublic

Authored by trasz on Jan 4 2022, 5:32 PM.
Tags
None
Referenced Files
Unknown Object (File)
Sun, Jul 7, 7:13 PM
Unknown Object (File)
Sat, Jul 6, 6:21 PM
Unknown Object (File)
Sun, Jun 23, 4:55 AM
Unknown Object (File)
Sat, Jun 22, 5:39 PM
Unknown Object (File)
Fri, Jun 21, 1:48 AM
Unknown Object (File)
May 29 2024, 2:00 AM
Unknown Object (File)
May 23 2024, 12:21 PM
Unknown Object (File)
May 5 2024, 8:02 AM

Details

Summary

Sponsored By: EPSRC

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

trasz requested review of this revision.Jan 4 2022, 5:32 PM
trasz created this revision.

Let's embrace Unicode: "Linux®"
But we should probably leave it off throughout the text, and have a footer "Linux® is a registered trademark of ..."

documentation/content/en/books/handbook/linuxemu/_index.adoc
54

I'm not sure the 32-bit example helps much, I'd probably just leave it out. Being able to run 32-bit binaries on 64-bit host seems "obvious".

113

s/of the//

Okay, let's fix the "(R)" sillyness first, since it's a mechanical change: https://reviews.freebsd.org/D33750

Let's embrace Unicode: "Linux®"

Ah nevermind that part, (R) is rendered as ®.

This revision is now accepted and ready to land.Jan 10 2022, 1:05 PM
debdrup requested changes to this revision.Jan 10 2022, 1:49 PM
debdrup added a subscriber: debdrup.

I just noticed one other thing:
The document goes from using one line per sentence to splitting sentences in the middle, which as far as I know causes problems.

This revision now requires changes to proceed.Jan 10 2022, 1:49 PM

Fix formatting, as suggested by debdrup@, and fix a few other nits.

I just noticed one other thing:
The document goes from using one line per sentence to splitting sentences in the middle, which as far as I know causes problems.

Thanks! I wonder, should perhaps igor(1) warn about this, or am I using the wrong tool?

pauamma_gundo.com added inline comments.
documentation/content/en/books/handbook/linuxemu/_index.adoc
54–55

Did you leave (R) here deliberately?

56

I think this should be "for the".

84

~% sudo service linux start
Password:
Cannot 'start' linux. Set linux_enable to YES in /etc/rc.conf or use 'onestart' instead of 'start'.

So, "start" is only correct if you meant "To start it without rebooting after enabling it". Otherwise (eg, to start it just to run that one program once) use "onestart".

87–97
93
95–96

"an existing Linux installation using the same architecture" or "existing Linux installations using the same architecture". Maybe also mention that Linux uses different names for architectures? Not sure.

96
112

Don't know whether man; can be used in headers, but if it can, use it here (man:debootstrap[8])

120

"You" is still strongly discouraged in the FDP primer (https://docs.freebsd.org/en/books/fdp-primer/writing-style/#writing-style-tips section 11.1.1)

138–139

Also, 1 sentence per line.

141
144
152

Taste.

160

Feel for audience tells me that saying which version this change happened in is more important than the feature(s) that came at the same time or that are the cause for the change. So maybe "Starting with 2.71828" or whichever FreeBSD version introduced that change?

167

Also, would the average reader know what a userspace is?

323

Since you're touching nearby lines; "toolchain" (singular) contradicts "all".

documentation/content/en/books/handbook/linuxemu/_index.adoc
54–55

Yes, common guidelines (as well as the LF's specific ones for use of Linux) suggest using the R or TM on first use.

56

Yeah "for the i386, ..."

84

"To start it without rebooting after enabling it" seems awkward to me, but I agree it's worth some sort of mention.

What do you think about something like "Once enabled, it can be started without rebooting by running:"

documentation/content/en/books/handbook/linuxemu/_index.adoc
54–55

Yes, this "(R)" is the first occurence of "Linux".

160

This might be either FreeBSD 14.0, whenever it's released, or 13.1, if MFC-ed before then, but to be honest I'm not sure if we want to keep this paragraph. From my understanding this is something that's been broken anyway.

167

"Userspace" is probably the wrong word here, but I can't figure out a better one. "Bootstrapped instance" maybe? "Linux userspace installation"? Suggestions welcome :-)

323

To me this reads like a short version of "all the components of Linux toolchain can run".

(And honestly, I'm not particularly sure this section should stay here either, it's kind of obsolete, so for now I've just pushed it to the end)

Thanks! I wonder, should perhaps igor(1) warn about this, or am I using the wrong tool?

I think so, but I'm not sure how one would match things that don't follow one line per sentence.

Since you've fixed the thing I pointed out, I'm good with this now - I'll leave it up to someone else to accept as docs unless everyone else has had their feedback responded to/fixed.

documentation/content/en/books/handbook/linuxemu/_index.adoc
84

What do you think about something like "Once enabled, it can be started without rebooting by running:"

It's correct, so I would accept it. (I'm not sure how often "onestart" is useful, and a quick check of the handbook says it's only mentioned for 2 specific services, so I can live with not mentioning it here.)

Other than my 2 extra nitpicks, LGTM now.

documentation/content/en/books/handbook/linuxemu/_index.adoc
167

"userland" maybe? May not be familiar to Linux users (just asked that as a straw poll question elseIRC), but I think would be readily understood by a FreeBSD user.

230–231

One more fix from Pau, also use "base system".

trasz added inline comments.
documentation/content/en/books/handbook/linuxemu/_index.adoc
167

Hm, Google shows 2M hits for "userland", and 10M for "userspace"... how about "base system"? This also fits the package name: "linux_base".

Is this ready for approval so it can land? It looks to me like it is.

documentation/content/en/books/handbook/linuxemu/_index.adoc
167

Hm, Google shows 2M hits for "userland", and 10M for "userspace"... how about "base system"? This also fits the package name: "linux_base".

I think it makes a lot of sense to use this verbiage, since in FreeBSD we also talk about the base system all the time. :)

Userspace refers to the opposite of kernelspace, and generally has more to do with virtual memory and what privilege a process is running in (because the kernel runs in a different privilege mode than userspace).

Other than these 2 missing "the"s, LGTM.

documentation/content/en/books/handbook/linuxemu/_index.adoc
97
119

Is this ready for approval so it can land? It looks to me like it is.

With my final 2 nitpicks, I think it is. Approve at will once they're addressed.

With my final 2 nitpicks, I think it is. Approve at will once they're addressed.

That's a minor enough change that @trasz can fix it when commiting and pushing the final version.

This revision is now accepted and ready to land.Jan 11 2022, 5:34 PM
trasz marked an inline comment as done.

Last two "the"s.

This revision now requires review to proceed.Jan 12 2022, 2:26 PM
This revision was not accepted when it landed; it landed in state Needs Review.Jan 12 2022, 2:32 PM
This revision was automatically updated to reflect the committed changes.