handbook: Update the first chunk of Linuxulator chapter

[trasz]

Summary

Sponsored By: EPSRC

[emaste]

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//

[trasz]

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

[emaste]

Let's embrace Unicode: "Linux®"

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

[trasz]

Bunch of updates.

[carlavilla]

Thanks for the update :)

[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.

[trasz]

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

[trasz]

In D33738#764600, @debdrup wrote:

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]

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".

[emaste]

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:"

[trasz]

Fixes from Pau.

[trasz]

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)

[trasz]

"Once enabled"

[debdrup]

In D33738#764635, @trasz wrote:

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.

[pauamma_gundo.com]

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.)

[pauamma_gundo.com]

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

[trasz]

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

[trasz]

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".

[debdrup]

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).

[pauamma_gundo.com]

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

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

97

119

[pauamma_gundo.com]

In D33738#765306, @debdrup wrote:

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.

[debdrup]

In D33738#765425, @pauamma_gundo.com wrote:

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.

[trasz]

Last two "the"s.

[trasz]

Sigh, igor.