git: e812dc9a23 - main - handbook: Further tweaks to Linuxulator chapter

The branch main has been updated by trasz:

URL: https://cgit.FreeBSD.org/doc/commit/?id=e812dc9a2340d565258b32b94143d08e3c0c934d

commit e812dc9a2340d565258b32b94143d08e3c0c934d
Author:     Edward Tomasz Napierala <[email protected]>
AuthorDate: 2022-01-17 08:33:43 +0000
Commit:     Edward Tomasz Napierala <[email protected]>
CommitDate: 2022-01-17 08:33:56 +0000

    handbook: Further tweaks to Linuxulator chapter
    
    Point to Sublime 4, as that's the current version; change misleading
    paragraph ordering; mention path translation; mention potential
    problems with 32-bit
    
    Reviewed By:    debdrup
    Sponsored By:   EPSRC
    Differential Revision:  https://reviews.freebsd.org/D33909
---
 .../content/en/books/handbook/linuxemu/_index.adoc | 26 ++++++++++++++--------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/documentation/content/en/books/handbook/linuxemu/_index.adoc b/documentation/content/en/books/handbook/linuxemu/_index.adoc
index 672a4d74dd..ff7b75b739 100644
--- a/documentation/content/en/books/handbook/linuxemu/_index.adoc
+++ b/documentation/content/en/books/handbook/linuxemu/_index.adoc
@@ -94,6 +94,11 @@ There are several ways of providing those libraries: one can copy them over from
 [[linuxemu-packages]]
 == CentOS Base System from FreeBSD Packages
 
+[NOTE]
+====
+This method is not yet available for arm64.
+====
+
 The easiest way to install Linux libraries is to install package:emulators/linux_base-c7[] package or port, which places the CentOS 7-derived base system into [.filename]#/compat/linux#:
 
 [source,shell]
@@ -102,10 +107,10 @@ The easiest way to install Linux libraries is to install package:emulators/linux
 ....
 
 FreeBSD provides packages for some Linux binary applications.
-For example, to install Sublime Text, run this command:
+For example, to install Sublime Text 4, along all the Linux libraries it depends on, run this command:
 [source,shell]
 ....
-# pkg install linux-sublime
+# pkg install linux-sublime-text4
 ....
 
 [[linuxemu-debootstrap]]
@@ -115,6 +120,14 @@ An alternative way of providing Linux shared libraries is by using package:sysut
 This has the advantage of providing a full Debian or Ubuntu distribution.
 To use it, follow the instructions at FreeBSD Wiki: https://wiki.freebsd.org/LinuxJails[FreeBSD Wiki - Linux Jails].
 
+After deboostrapping, chroot(8) into the newly created directory and install software in a way typical for the Linux distribution inside, for example:
+
+[source,shell]
+....
+# chroot /compat/ubuntu /bin/bash
+root@hostname:/# apt update
+....
+
 It is possible to debootstrap into [.filename]#/compat/linux#, but it is discouraged to avoid collisions with files installed from FreeBSD ports and packages.
 Instead, derive the directory name from the distribution or version name, e.g., [.filename]#/compat/ubuntu#.
 If the bootstrapped instance is intended to provide Linux shared libraries without having to explicitly use chroot or jails, one can point the kernel at it by updating the `compat.linux.emul_path` sysctl and adding a line like this to [.filename]#/etc/sysctl.conf#:
@@ -124,13 +137,8 @@ If the bootstrapped instance is intended to provide Linux shared libraries witho
 compat.linux.emul_path="/compat/ubuntu"
 ....
 
-Afterwards chroot(8) into the newly created directory and install software in a way typical for the Linux distribution you have debootstrapped, for example:
-
-[source,shell]
-....
-# chroot /compat/ubuntu /bin/bash
-root@hostname:/# apt update
-....
+This sysctl controls kernel's path translation mechanism; see the man:linux[4] man page for details.
+Please note that changing it might cause trouble for Linux applications installed from FreeBSD packages; one reason is that many of those applications are still 32-bit, while Ubuntu seems to be deprecating 32-bit library support.
 
 [[linuxemu-advanced]]
 == Advanced Topics