From d2176216492038bce700bb8551810c7b70298f45 Mon Sep 17 00:00:00 2001 From: Nicholas De Nova Date: Wed, 15 Feb 2017 15:56:28 -0600 Subject: [PATCH] Correct manpage spacing per roff(7) convention. roff(7) dictates that "Each sentence should terminate at the end of an input line." Instead of doing this, Sortix manpages (incorrectly) used double-spaces to separate sentences. Additionally, fix a few small typos. --- carray/carray.1 | 59 ++++--- disked/disked.8 | 94 +++++----- editor/editor.1 | 12 +- editor/editor.5 | 10 +- init/init.8 | 66 ++++--- login/login.8 | 19 +- mkinitrd/initrdfs.8 | 3 +- mkinitrd/mkinitrd.8 | 41 +++-- sf/sf.1 | 19 +- sf/sfnc.1 | 3 +- sf/sfncd.1 | 4 +- share/man/man5/hostname.5 | 5 +- share/man/man5/kblayout.5 | 8 +- share/man/man5/upgrade.conf.5 | 32 ++-- share/man/man5/videomode.5 | 9 +- share/man/man7/cross-development.7 | 107 ++++++----- share/man/man7/development.7 | 151 +++++++++------- share/man/man7/following-development.7 | 55 +++--- share/man/man7/initrd.7 | 4 +- share/man/man7/installation.7 | 236 ++++++++++++++----------- share/man/man7/kernel.7 | 3 +- share/man/man7/serial-transfer.7 | 55 +++--- share/man/man7/upgrade.7 | 75 ++++---- share/man/man7/user-guide.7 | 34 ++-- sysinstall/sysinstall.8 | 5 +- sysinstall/sysmerge.8 | 35 ++-- sysinstall/sysupgrade.8 | 9 +- utils/chkblayout.1 | 3 +- utils/chroot.8 | 3 +- utils/pager.1 | 17 +- utils/unmount.8 | 15 +- 31 files changed, 680 insertions(+), 511 deletions(-) diff --git a/carray/carray.1 b/carray/carray.1 index 64673019..8e64ba2b 100644 --- a/carray/carray.1 +++ b/carray/carray.1 @@ -35,16 +35,15 @@ if the option is given. The default type is an array of .Sy unsigned char . -The array contents are indented with tabs -and the lines don't exceed 80 columns (tabs have the width of 8 spaces). +The array contents are indented with tabs and the lines don't exceed 80 columns +(tabs have the width of 8 spaces). .Pp -The default array name is the output path if set, or the path of the first -input file (if any), or otherwise +The default array name is the output path if set, or the path of the first input +file (if any), or otherwise .Sy carray . -The default array name has all file extensions removed (but a leading period -in the file name is kept). The default array name is converted to the -characters -a-z, A-Z, +The default array name has all file extensions removed (but a leading period in +the file name is kept). +The default array name is converted to the characters a-z, A-Z, .Sq _ , and 0-9. 0-9 cannot be the first character of an identifier. .Sq + @@ -59,15 +58,16 @@ A guard macro is optionally used by the .Fl g and .Fl G -options. The default guard macro is the output path if set, or the path of the -first input file (if any) followed by +options. +The default guard macro is the output path if set, or the path of the first +input file (if any) followed by .Sy _H , or otherwise .Sy CARRAY_H . The default guard macro is converted to the characters A-Z, .Sq _ , -and 0-9. 0-9 cannot be the first character of an identifier. The lower-case -a-z is converted to the upper-case A-Z. +and 0-9. 0-9 cannot be the first character of an identifier. +The lower-case a-z is converted to the upper-case A-Z. .Sq + is replaced by .Sq X . @@ -91,7 +91,8 @@ keyword. .It Fl e , Fl \-extern Declare the array with the .Sy extern -keyword. This option is mutually incompatible with the +keyword. +This option is mutually incompatible with the .Fl s option. .It Fl E , Fl \-extern-c @@ -99,25 +100,27 @@ Wrap the array in .Sy extern """C""" { } subject to a preprocessor check for C++. .It Fl f , Fl \-forward -Forward declare the array only, do not initialize it with contents. The input -files are not opened and the standard input is unused. This option is mutually -incompatible with the +Forward declare the array only, do not initialize it with contents. +The input files are not opened and the standard input is unused. +This option is mutually incompatible with the .Fl r option. .It Fl g , Fl \-use-guard Wrap the output in a preprocessor conditional checking the guard macro is not -set, and declare the macro if it is not set. This conditional is a classic C -include guard that ensures only the first inclusion of a header has any effect. +set, and declare the macro if it is not set. +This conditional is a classic C include guard that ensures only the first +inclusion of a header has any effect. .It Fl G , Fl \-guard Ar guard Sets the guard macro to .Ar guard and enables the guard macro check as if the .Fl g -option was set as well. The guard macro is unrestricted and untransformed and -will be be output verbatim. +option was set as well. +The guard macro is unrestricted and untransformed and will be output verbatim. .It Fl H , Fl \-headers -Output inclusions of all the prerequisite headers. By default, there are no -prerequisite headers, unless the array type is one of the +Output inclusions of all the prerequisite headers. +By default, there are no prerequisite headers, unless the array type is one of +the .In stdint.h types, in which case .In stdint.h @@ -129,15 +132,16 @@ is the only prerequisite header. .\" (End) Sets the name of the array to .Ar identifier . -The identifier is unrestricted and will be be output verbatim. +The identifier is unrestricted and will be output verbatim. .It Fl \-includes Ar include-statements Sets the C preprocessor statements .Ar include-statements as how to include all the prerequisite headers and enables inclusion of the prerequisite headers as if the .Fl H -option was set. The preprocessor statements are unrestricted and untransformed -and will be be output verbatim. +option was set. +The preprocessor statements are unrestricted and untransformed and will be +output verbatim. .It Fl o , Fl output Ar output Write the output to the .Ar output @@ -146,7 +150,8 @@ path rather than the standard output. Output only the hexadecimally encoded array contents, and the guard macro check if set by the .Fl g -option. This option is mutually incompatible with the +option. +This option is mutually incompatible with the .Fl f option. .It Fl s , Fl \-static @@ -156,7 +161,7 @@ keyword. .It Fl t , Fl \-type Ar type Declare the array as an array of the specified .Ar type . -The type is unrestricted and will be be output verbatim. +The type is unrestricted and will be output verbatim. .It Fl v , Fl \-volatile Declare the array with the .Sy volatile diff --git a/disked/disked.8 b/disked/disked.8 index 74c25a5f..c6996ad8 100644 --- a/disked/disked.8 +++ b/disked/disked.8 @@ -9,23 +9,26 @@ .Op Fl \-fstab Ns "=" Ns Ar path .Sh DESCRIPTION .Nm -is an interactive program that manages partition tables. It can create and -destroy partition tables on block devices. It can create partitions and destroy -them. It can format filesystems on partitions and configure mountpoints in +is an interactive program that manages partition tables. +It can create and destroy partition tables on block devices. +It can create partitions and destroy them. +It can format filesystems on partitions and configure mountpoints in .Xr fstab 5 . .Nm supports the Master Boot Record and GUID Partition Table partitioning schemes. .Pp .Nm -provides an interactive command line. Its prompt shows the currently selected -device (defaulting to the first device alphabetically) or +provides an interactive command line. +Its prompt shows the currently selected device (defaulting to the first device +alphabetically) or .Li (disked) -if none is selected. Commands perform their actions when run rather -than waiting for the user to write out changes. +if none is selected. +Commands perform their actions when run rather than waiting for the user to +write out changes. .Nm only creates partitions aligned to 1 MiB boundaries whose size is a multiple of -1 MiB. Unused regions are aligned and those smaller than the alignment are not -shown. +1 MiB. +Unused regions are aligned and those smaller than the alignment are not shown. .Pp The options are as follows: .Bl -tag -width "12345678" @@ -45,7 +48,8 @@ Switch to the device .Ar device-index as numbered by the .Sy devices -command. If no index is specified, show the name of the current device. +command. +If no index is specified, show the name of the current device. Alternatively you can write the absolute path to the device such as .Pa /dev/ahci0 or just its name @@ -54,7 +58,8 @@ or just its name List every available block device and show their indexes, device names (as found in .Pa /dev ) , -model names and serial numbers. Devices are counted from 0. +model names and serial numbers. +Devices are counted from 0. .It Sy exit Exit .Nm . @@ -67,30 +72,33 @@ on the current device. .It Sy help List available commands. .It Sy ls -Display the partition table of the current device. Partitions are counted from -1. +Display the partition table of the current device. +Partitions are counted from 1. .It Sy man Oo ... Oc Display this manual page if no operands are given, otherwise run .Xr man 1 with the given command line. .It Sy mkpart -Create a partition on the current device. If the partition table has multiple -unused regions +Create a partition on the current device. +If the partition table has multiple unused regions .Pq holes , .Nm -asks you which one to use. You need to specify the offset into the hole where -the partition is created and then the length of the partition. See +asks you which one to use. +You need to specify the offset into the hole where the partition is created and +then the length of the partition. +See .Sx QUANTITIES -below on the possible partition offset and length values. You will be asked if -you want to format a filesystem: +below on the possible partition offset and length values. +You will be asked if you want to format a filesystem: .Bl -tag -width "12345678" .It Sy biosdata (gpt only) Format a BIOS boot partition, which is required for booting with GRUB -from a root filesystem on a GPT partition. 1 MiB is sufficient for this kind of -partition. +from a root filesystem on a GPT partition. +1 MiB is sufficient for this kind of partition. .It Sy extended (mbr only) Create an extended partition, which can contain an arbitrary amount -logical partitions. You can only have a single extended partition. +logical partitions. +You can only have a single extended partition. .It Sy ext2 Format an ext2 filesystem. .It Sy no @@ -111,42 +119,48 @@ in .Xr fstab 5 , or if .Sy no -then remove any existing mountpoints. Conflicting mountpoints are removed. +then remove any existing mountpoints. +Conflicting mountpoints are removed. .It Sy quit Exit .Nm . .It Sy rmpart Ar partition-index Delete the partition .Ar partition-index -on the current device. The partition data is rendered inaccessible but is not -actually erased. The partition can technically be recovered using +on the current device. +The partition data is rendered inaccessible but is not actually erased. +The partition can technically be recovered using .Sy mkpart . The partition data no longer has the protections of being in a partition and -looks like regular unused space and can easily be overwritten. You should not -delete a partition unless you want its contents gone. Deleting an extended -partition deletes all the partitions it contains. +looks like regular unused space and can easily be overwritten. +You should not delete a partition unless you want its contents gone. +Deleting an extended partition deletes all the partitions it contains. .It Sy rmtable -Delete the partition table on the current device. The existing partitions are -rendered inaccessible but are not actually erased. The partitions can -technically be recovered using +Delete the partition table on the current device. +The existing partitions are rendered inaccessible but are not actually erased. +The partitions can technically be recovered using .Sy mktable and .Sy mkpart . The disk data no longer has the protections of being partitioned and looks like -regular unused space and can easily be overwritten. You should not delete the -partition table unless you want all the data on the disk gone. +regular unused space and can easily be overwritten. +You should not delete the partition table unless you want all the data on the +disk gone. .It Sy sh Run an interactive shell. .El .Sh QUANTITIES .Nm -allows useful expressions when describing disk offsets and lengths. Every -question needs an answer between 0 and a maximum. You can answer in percent -where 100% is the maximum. You can answer an integer value followed by a suffix -such as B, K, M, G, T, or P to signify bytes, KiB, MiB, GiB, TiB, and PiB -respectively. The value is in MiB by default if there is no suffix. The answer -is rounded to the 1 MiB alignment. If the expression is a negative value, then -the answer is the maximum minus the absolute value. For instance: +allows useful expressions when describing disk offsets and lengths. +Every question needs an answer between 0 and a maximum. +You can answer in percent where 100% is the maximum. +You can answer an integer value followed by a suffix such as B, K, M, G, T, or P +to signify bytes, KiB, MiB, GiB, TiB, and PiB respectively. +The value is in MiB by default if there is no suffix. +The answer is rounded to the 1 MiB alignment. +If the expression is a negative value, then the answer is the maximum minus the +absolute value. +For instance: .Bl -tag -width "12345678" .It 42% Use 42% of the maximum. diff --git a/editor/editor.1 b/editor/editor.1 index 95ffa17d..e28b4891 100644 --- a/editor/editor.1 +++ b/editor/editor.1 @@ -9,10 +9,12 @@ .Op Ar file .Sh DESCRIPTION .Nm -is a text editor with basic editing functionality. It generally behaves like -a GUI editor as opposed to common terminal editors. The file named by the +is a text editor with basic editing functionality. +It generally behaves like a GUI editor as opposed to common terminal editors. +The file named by the .Ar file -argument is loaded if specified. It quits when +argument is loaded if specified. +It quits when .Sy Ctrl-Q is typed. .Pp @@ -74,5 +76,5 @@ User configuration. .Sh BUGS .Nm lacks a number of crucial features, such as undo and redo, ability to open -multiple files at once, and so on. The syntax highlighting can occasionally be -inconsistent. +multiple files at once, and so on. +The syntax highlighting can occasionally be inconsistent. diff --git a/editor/editor.5 b/editor/editor.5 index 025ecfed..76ae70a8 100644 --- a/editor/editor.5 +++ b/editor/editor.5 @@ -10,11 +10,13 @@ .Sh DESCRIPTION .Xr editor 1 loads these files on startup and executes the commands therein as described in -.Xr editor 1 . Only commands applicable as global configuration are executed to -avoid undesirable side effects. For instance, +.Xr editor 1 . +Only commands applicable as global configuration are executed to avoid +undesirable side effects. +For instance, .Sy popen -isn't executed as that would open another file than the current one. Unknown -commands are silently ignored. +isn't executed as that would open another file than the current one. +Unknown commands are silently ignored. .Sh FILES .Bl -tag -width "$HOME/.editor" -compact .It Pa /etc/editor diff --git a/init/init.8 b/init/init.8 index ad3818b7..bdba1c00 100644 --- a/init/init.8 +++ b/init/init.8 @@ -20,24 +20,28 @@ The starts the system in a temporary environment with a root filesystem backed by system memory and extracts the .Xr initrd 7 -into it. The kernel runs the +into it. +The kernel runs the .Pa /sbin/init -program of the system memory root filesystem as the first process. If the -system is bootable cdrom, then the initrd will be a fully functional system and +program of the system memory root filesystem as the first process. +If the system is on bootable cdrom, then the initrd will be a fully functional +system and .Nm -will start a live environment or an operating system installer. If the -system is installed on a harddisk, then the initrd is a minimal system made with +will start a live environment or an operating system installer. +If the system is installed on a harddisk, then the initrd is a minimal system +made with .Xr update-initrd 8 -that will search for the actual root filesystem and chain init it. The next -stage init will recognize it as the intended system and complete the system -startup. +that will search for the actual root filesystem and chain init it. +The next stage init will recognize it as the intended system and complete the +system startup. .Ss Initialization Target .Nm first determines its target from the .Fl \-target option if specified or .Pa /etc/init/target -otherwise. Supported targets are: +otherwise. +Supported targets are: .Pp .Bl -tag -width "single-user" -compact -offset indent .It Sy chain @@ -69,12 +73,14 @@ boot to operating system upgrader (not secure). .El .Pp It is a full system compromise if unauthenticated users are able to boot the -wrong target. The kernel command line can specify the path to +wrong target. +The kernel command line can specify the path to .Nm -and its arguments. Unprivileged users can change the kernel command line from -the bootloader command line if it hasn't been password protected. Likewise -unprivileged users can use their own replacement bootloader by booting a -portable device under their control if the firmware configuration has not been +and its arguments. +Unprivileged users can change the kernel command line from the bootloader +command line if it hasn't been password protected. +Likewise unprivileged users can use their own replacement bootloader by booting +a portable device under their control if the firmware configuration has not been password protected. .Ss Partition Creation .Nm @@ -89,14 +95,16 @@ target mounts the root filesystem as in (see .Xr fstab 5) and runs the next .Nm -program. This is used by +program. +This is used by .Xr update-initrd 8 to make a bootstrap .Xr initrd 7 . .Pp Every block device and partition is scanned to determine if it is the root -filesystem. It is checked for consistency if nessesary. It is -mounted at +filesystem. +It is checked for consistency if necessary. +It is mounted at .Pa /tmp/fs.XXXXXX and the .Pa /dev @@ -133,8 +141,9 @@ will write 256 bytes of randomness to .Pa /boot/random.seed , which serves as the initial entropy for the .Xr kernel 7 -on the next boot. The file is also written on system shutdown where the -system has the most entropy. +on the next boot. +The file is also written on system shutdown where the system has the most +entropy. .Ss Merge The .Sy merge @@ -144,7 +153,8 @@ at .Pa /sysmerge/sbin/sysmerge with the .Ar --booting -option. If the upgrade succeeds, the temporary +option. +If the upgrade succeeds, the temporary .Nm deinitializes the system and invokes the real (now upgraded) .Nm @@ -152,15 +162,15 @@ which will restart system initialization in the normal fashion. .Ss Session Finally .Nm -will start the target program according to its initialization target. This will -be a login screen, a root shell, or something else. If the process exits -abnormally +will start the target program according to its initialization target. +This will be a login screen, a root shell, or something else. +If the process exits abnormally .Nm will automatically restart it. .Nm -will exit with the same exit status as the process if it exits -normally. The kernel decides whether to power off, reboot or halt based on this -exit status. +will exit with the same exit status as the process if it exits normally. +The kernel decides whether to power off, reboot or halt based on this exit +status. .Sh ENVIRONMENT .Nm sets the following environment variables. @@ -203,8 +213,8 @@ graphics resolution (see .Sh EXIT STATUS .Nm exits 0 if the kernel should power off, exits 1 if the kernel should reboot, or -exits 2 if the boot failed and the kernel should halt. Any other exit by the -initial +exits 2 if the boot failed and the kernel should halt. +Any other exit by the initial .Nm will trigger a kernel panic. .Nm diff --git a/login/login.8 b/login/login.8 index 6907ceaf..64db6b15 100644 --- a/login/login.8 +++ b/login/login.8 @@ -9,7 +9,8 @@ .Sh DESCRIPTION .Nm login interactively authenticates users by asking them to enter their username and -password. The passwords are checked against the password hashes in +password. +The passwords are checked against the password hashes in .Pa /etc/passwd as described in .Xr passwd 5 . @@ -18,10 +19,12 @@ creates a session as the requested user upon successful authentication. .Pp .Nm login has a graphical interface if the display is graphical and uses a textual -interface otherwise. The textual interface is forced if +interface otherwise. +The textual interface is forced if .Pa /etc/login.conf.textual -exists. The process remains running in the background and takes -over again when the user session exits. +exists. +The process remains running in the background and takes over again when the user +session exits. .Pp Type a special username to perform special options: .Pp @@ -35,8 +38,9 @@ exit asking for rebooting the computer .El .Sh SECURITY There is currently no method to confirm the login screen is in fact real other -than witnessing a pristine boot. Local users can log in and show a counterfeit -login screen that look and behave like the real +than witnessing a pristine boot. +Local users can log in and show a counterfeit login screen that look and behave +like the real .Nm login program and trick the next user into revealing their password. .Sh ENVIRONMENT @@ -72,4 +76,5 @@ reboot, or exits 2 on fatal failure and the boot should halt. .Xr login 8 .Sh BUGS .Nm login -only supports a single monitor. The mouse code is less than perfect. +only supports a single monitor. +The mouse code is less than perfect. diff --git a/mkinitrd/initrdfs.8 b/mkinitrd/initrdfs.8 index 3b66503a..e2ea83e2 100644 --- a/mkinitrd/initrdfs.8 +++ b/mkinitrd/initrdfs.8 @@ -52,4 +52,5 @@ will exit 0 on success and non-zero otherwise. .Sh BUGS .Nm is severely feature limited and doesn't actually let you extract an initrd or -view all the contained meta information. It's also not a filesystem driver. +view all the contained meta information. +It's also not a filesystem driver. diff --git a/mkinitrd/mkinitrd.8 b/mkinitrd/mkinitrd.8 index 10c13cec..e49b1fa7 100644 --- a/mkinitrd/mkinitrd.8 +++ b/mkinitrd/mkinitrd.8 @@ -26,14 +26,16 @@ format of files and directories. Every specified .Ar directory is used as a root directory and is recursively searched for files and -directories matching the filter. If multiple directories are specified, the -directories are merged together. In case two files with the same path conflict, -precedence is given to the file in the root directory specified first. +directories matching the filter. +If multiple directories are specified, the directories are merged together. +In case two files with the same path conflict, precedence is given to the file +in the root directory specified first. .Pp Hardlinks are detected and preserved to avoid data duplication. -Inode times are truncated to second precision due to format limitations. Inodes -are stored with uid 0 and gid 0 of the root user. The format is not compressed -but can be compressed externally if it is decompressed during bootloading. +Inode times are truncated to second precision due to format limitations. +Inodes are stored with uid 0 and gid 0 of the root user. +The format is not compressed but can be compressed externally if it is +decompressed during bootloading. .Pp .Xr initrdfs 8 can be used to view the files produced by @@ -48,8 +50,8 @@ rules in the in the format specified under .Sx FILTER RULES . .It Fl \-format Ns "=" Ns Ar format -Produce the archive in the specified format. This is for forward compatibility -and only +Produce the archive in the specified format. +This is for forward compatibility and only .Sy sortix-initrd-2 is supported. .Sy default @@ -70,12 +72,13 @@ at the specified .Ar destination . .El .Sh FILTER RULES -The rule format is line based and leading whitespace is skipped. Lines starting -with a +The rule format is line based and leading whitespace is skipped. +Lines starting with a .Li # -character are ignored as comments. The first word on a line must be one of -the following commands and the rest of the line is its parameter. Trailing -whitespace is not ignored. +character are ignored as comments. +The first word on a line must be one of the following commands and the rest of +the line is its parameter. +Trailing whitespace is not ignored. .Bl -tag -width "12345678" .It Sy default Ar boolean The @@ -85,8 +88,9 @@ parameter is either or .Sy false and determines whether a file or directory is included if no other rules match -it. This defaults to -.Sy true. +it. +This defaults to +.Sy true . .It Sy include Ar path Include the file or directory if it matches .Ar path . @@ -96,9 +100,10 @@ Exclude the file or directory if it matches .El .Pp The rules are checked on the paths relative to the root directories during the -recursive descent. The last rule to match a path decides whether it is -included or not. Directory are not descended into if they are excluded. The -pattern patch is simple and matches paths exactly. +recursive descent. +The last rule to match a path decides whether it is included or not. +Directory are not descended into if they are excluded. +The pattern patch is simple and matches paths exactly. .Sh EXIT STATUS .Nm will exit 0 on success and non-zero otherwise. diff --git a/sf/sf.1 b/sf/sf.1 index 3189dfc9..d55f688d 100644 --- a/sf/sf.1 +++ b/sf/sf.1 @@ -10,8 +10,8 @@ .Op Ar device .Sh DESCRIPTION .Nm -provides a simple scheme for framing a message over a byte stream. This is -useful in cases such as sockets, pipe, and serial devices where a real +provides a simple scheme for framing a message over a byte stream. +This is useful in cases such as sockets, pipe, and serial devices where a real end of file condition would require terminating the link, but it is important to transmit multiple messages and keeping the link open for an arbitrary amount of time. @@ -23,8 +23,8 @@ most bytes represent themselves, an escape byte sequence .Li ( 0xF7 0xFD ) , and an end of messsage byte sequence .Li ( 0xF7 0xFE ) . -UTF-8 encoded text will never need to be escaped. Data can be recursively -framed. +UTF-8 encoded text will never need to be escaped. +Data can be recursively framed. .Pp Exactly one of the .Fl i @@ -34,15 +34,18 @@ options must be set to control whether the program is in input or output mode. .Pp Input mode works by reading one byte at a time from stdin (or the .Ar device -if given). It discards all read bytes until it finds a valid start of message -byte sequence. It then decodes the body and writes the decoded bytes to stdout. +if given). +It discards all read bytes until it finds a valid start of message byte +sequence. +It then decodes the body and writes the decoded bytes to stdout. Finally it finds an end of message byte sequence and exits. .Pp Output mode works by reading bytes from stdin until an end of file condition. It emits a start of message byte sequence to stdout (or to the .Ar device -if given). It emits an encoded body with the contents of stdin. Finally it -emits an end of message byte sequence. +if given). +It emits an encoded body with the contents of stdin. +Finally it emits an end of message byte sequence. .Pp The .Ar device diff --git a/sf/sfnc.1 b/sf/sfnc.1 index 067defe8..feedfd50 100644 --- a/sf/sfnc.1 +++ b/sf/sfnc.1 @@ -32,7 +32,8 @@ The client transmits in one session, which contains two nested .Xr sf 1 connections (first host, then port), and then the actual body read from the -standard input. The server transmits in one +standard input. +The server transmits in one .Xr sf 1 session, which begins once the host and port has been received, and it contains the response. diff --git a/sf/sfncd.1 b/sf/sfncd.1 index 49f377ed..68d52152 100644 --- a/sf/sfncd.1 +++ b/sf/sfncd.1 @@ -24,8 +24,8 @@ environment variables set to the parameters). .Pp It receives bytes from .Ar receive-device -and sends them to the invoked program. It reads bytes from the invoked program -and transmits them through +and sends them to the invoked program. +It reads bytes from the invoked program and transmits them through .Ar transmit-device . .Pp The protocol is as described in diff --git a/share/man/man5/hostname.5 b/share/man/man5/hostname.5 index 666ceb2b..140eb2ca 100644 --- a/share/man/man5/hostname.5 +++ b/share/man/man5/hostname.5 @@ -11,8 +11,9 @@ The .Nm hostname file is read on boot by .Xr init 8 -and is used as the system hostname. No hostname is set if the file is missing -and the hostname remains the kernel default. +and is used as the system hostname. +No hostname is set if the file is missing and the hostname remains the kernel +default. .Sh FORMAT The file must contain a valid hostname and no whitespace on a single line. .Sh FILES diff --git a/share/man/man5/kblayout.5 b/share/man/man5/kblayout.5 index ffe771e3..43ed63f9 100644 --- a/share/man/man5/kblayout.5 +++ b/share/man/man5/kblayout.5 @@ -13,12 +13,12 @@ file is read on boot by .Xr init 8 and names a file in .Pa /share/kblayout -that is loaded and set as the keyboard layout. The default kernel US keyboard -layout is retained if the file is missing. +that is loaded and set as the keyboard layout. +The default kernel US keyboard layout is retained if the file is missing. .Pp The kernel translates the raw keyboard scancodes into unicode codepoints using -the keyboard layout table associated with the terminal. Keyboard layout -tables are compiled from a textual description with +the keyboard layout table associated with the terminal. +Keyboard layout tables are compiled from a textual description with .Xr kblayout-compiler 1 into compressed binary tables. .Sh FORMAT diff --git a/share/man/man5/upgrade.conf.5 b/share/man/man5/upgrade.conf.5 index c29a1e04..9a1e91b4 100644 --- a/share/man/man5/upgrade.conf.5 +++ b/share/man/man5/upgrade.conf.5 @@ -15,8 +15,9 @@ during a system upgrade as described in .Xr upgrade 7 . The file allows customizing whether the system itself is replaced, whether new ports are installed, whether the new source code is installed and what happens -to the old source code. It also records information about the system such as -how the system is booted. The file is created automatically by +to the old source code. +It also records information about the system such as how the system is booted. +The file is created automatically by .Xr sysinstall 8 as part of .Xr installation 7 @@ -24,27 +25,30 @@ to match what was installed. .Pp Developers may wish to customize what happens to .Pa /src -on a system upgrade. The new source code can be installed or not. If it is -installed, it can be installed in +on a system upgrade. +The new source code can be installed or not. +If it is installed, it can be installed in .Pa /newsrc or by default in .Pa /src . Any existing source code will be safely moved inside a subdirectory of .Pa /oldsrc . .Pp -It is possible to disable any upgrading whatsoever. If you do this, except the -new source code is installed, then you can upgrade to the new system manually as -described in +It is possible to disable any upgrading whatsoever. +If you do this, except the new source code is installed, then you can upgrade to +the new system manually as described in .Xr development 7 . Upgrading to the next release from source is not supported. .Sh FORMAT -The file is read line by line. The # character starts a comment and the rest of -the line is ignored. Lines are supposed to contain assignments to variables. An -assignment is the name of the variable, whitespace, an equal character, +The file is read line by line. +The # character starts a comment and the rest of the line is ignored. +Lines are supposed to contain assignments to variables. +An assignment is the name of the variable, whitespace, an equal character, whitespace, the value, whitespace, and then the end of the line. .Bl -tag -width "12345678" .It Sy grub Ns "=" Ns Oo Sy no "|" yes Oc (default Sy no ) . -States GRUB is used as the bootloader. If either the +States GRUB is used as the bootloader. +If either the .Sy system or .Sy ports @@ -63,7 +67,8 @@ into .Pa /oldsrc . This preserves the current .Pa /src -directory. This takes precedence over and disables the behavior described under +directory. +This takes precedence over and disables the behavior described under .Sy src . .It Sy ports Ns "=" Ns Oo Sy no "|" yes Oc (default Sy yes ) . Install the new ports. @@ -75,7 +80,8 @@ and move any existing into .Pa /oldsrc . .It Sy system Ns "=" Ns Oo Sy no "|" yes Oc (default Sy yes ) . -Install the new system. This will run +Install the new system. +This will run .Xr update-initrd 8 and if .Sy grub diff --git a/share/man/man5/videomode.5 b/share/man/man5/videomode.5 index 7a658847..bbfbbcfd 100644 --- a/share/man/man5/videomode.5 +++ b/share/man/man5/videomode.5 @@ -11,16 +11,17 @@ The .Nm videomode file is read on boot by .Xr init 8 -and is used as the initial graphics resolution on the primary monitor. The -resolution provided by the bootloader remains in effect if the file is missing. +and is used as the initial graphics resolution on the primary monitor. +The resolution provided by the bootloader remains in effect if the file is +missing. The resolution is usable only if the graphics card has a driver and the resolution is supported. .Sh FORMAT .Ar width Ns x Ns Ar height Ns x Ns Ar bits-per-pixel .Pp The file specifies a graphics resolution as a single line with three numeric -fields separated by x characters and no whitespace whatsoever. The first field -is used as the +fields separated by x characters and no whitespace whatsoever. +The first field is used as the .Ar width in pixels, the second field is used as the .Ar height diff --git a/share/man/man7/cross-development.7 b/share/man/man7/cross-development.7 index 1450bf70..efc2d59a 100644 --- a/share/man/man7/cross-development.7 +++ b/share/man/man7/cross-development.7 @@ -8,16 +8,18 @@ The .Xr development 7 manual page describes the primary way of building the operating system, which -is under itself. The secondary way is to cross-compile it from a sufficiently -similar operating system such as Linux with the GNU tools installed. The build -system assumes the presence of some GNU extensions in the standard command line -tools. This document will detail the process of bootstrapping a Sortix system -from another operating system. +is under itself. +The secondary way is to cross-compile it from a sufficiently similar operating +system such as Linux with the GNU tools installed. +The build system assumes the presence of some GNU extensions in the standard +command line tools. +This document will detail the process of bootstrapping a Sortix system from +another operating system. .Pp Be sure you are reading the latest version of this document, rather than an old copy installed on the system or on an online manual page viewer, if you want to -build the latest development code rather than the stable release. To view the -instructions for the latest source code using the command line: +build the latest development code rather than the stable release. +To view the instructions for the latest source code using the command line: .Bd -literal cd /latest/source/code && man share/man/man7/cross-development.7 @@ -34,9 +36,10 @@ xorriso (for iso creation) mtools (for iso creation) (if on UEFI systems) .El .Pp -GRUB with BIOS support is required. If you are on an UEFI system, you may need -to install further files to get BIOS support. For instance, on an apt-based -system you might install the +GRUB with BIOS support is required. +If you are on an UEFI system, you may need to install further files to get BIOS +support. +For instance, on an apt-based system you might install the .Sy grub-pc-bin package. .Pp @@ -73,50 +76,55 @@ You can find the latest Sortix binutils source code at You can find the latest Sortix gcc source code at .Lk https://sortix.org/toolchain/sortix-gcc-latest.tar.xz .Pp -This is a compiler toolchain that has been modified to support Sortix. The -toolchain is sometimes updated and you will need the latest toolchain to keep -building the latest code. +This is a compiler toolchain that has been modified to support Sortix. +The toolchain is sometimes updated and you will need the latest toolchain to +keep building the latest code. .Ss Variables This document will use meta-syntactic shell variables to denote where you have -choice. These are simply convenient shorthands that lets this document refer -to your choices. You shouldn't use real shell variables but just textually -replace them with your choices when you run commands. +choice. +These are simply convenient shorthands that lets this document refer to your +choices. +You shouldn't use real shell variables but just textually replace them with your +choices when you run commands. .Bl -tag -width "$SORTIX_PLATFORM" -offset indent .It Sy $SORTIX -The path to the directory containing the Sortix source code. This could for -instance be +The path to the directory containing the Sortix source code. +This could for instance be .Pa /home/user/sortix . .It Sy $SORTIX_PLATFORM -The Sortix target platform. This could for instance be +The Sortix target platform. +This could for instance be .Sy x86_64-sortix . .It Sy $CROSS_PREFIX -The directory path where the cross-toolchain will be installed. This could -for instance be +The directory path where the cross-toolchain will be installed. +This could for instance be .Pa /home/user/opt/x86_64-sortix . .El .Pp The following sections describe these variables in detail. .Ss Sortix Directory -You can put the Sortix source code wherever you'd like. It is typically git -cloned from your home directory and the source code will appear in +You can put the Sortix source code wherever you'd like. +It is typically git cloned from your home directory and the source code will +appear in .Pa ~/sortix . -This place will contain the operating system code. We'll refer to that location -as +This place will contain the operating system code. +We'll refer to that location as .Sy $SORTIX. .Pp Don't store the source code for the cross-toolchain (binutils and gcc) here. Store the source code for those programs somewhere else, such as in .Pa ~/src . It doesn't make any sense to store the cross toolchain within the Sortix -directory. The only toolchain that belongs here is the native toolchain that -runs on Sortix (and not on your current operating system). +directory. +The only toolchain that belongs here is the native toolchain that runs on Sortix +(and not on your current operating system). .Pp Don't make a sortix directory and git clone inside it, you redundantly get a .Pa ~/sortix/sortix directory instead. .Ss Target Platform -You need to decide what the platform your final Sortix system will run on. You -can currently decide between +You need to decide what the platform your final Sortix system will run on. +You can currently decide between .Sy i686-sortix and .Sy x86_64-sortix . @@ -129,7 +137,8 @@ You should install your cross-toolchain into a useful and isolated directory such as .Pa $HOME/opt/$SORTIX_PLATFORM . This allows you to easily dispose of the directory and keeps it isolated from -the rest of the system. We'll refer to that location as +the rest of the system. +We'll refer to that location as .Sy $CROSS_PREFIX. .Ss PATH You need to add @@ -145,16 +154,16 @@ variable: .Pp This will modify the .Ev PATH -variable in this particular shell session. You can make this permanent by -adding that line to your +variable in this particular shell session. +You can make this permanent by adding that line to your .Pa ~/.profile -or the applicable file for your shell and system. Consult your shell -documentation. Otherwise type it in all Sortix-related shells before doing -anything. +or the applicable file for your shell and system. +Consult your shell documentation. +Otherwise type it in all Sortix-related shells before doing anything. .Ss Build Tools You need to install some additional build tools as they are needed to build the -operating system. The installed build tools must be in sync with the source -code as described in +operating system. +The installed build tools must be in sync with the source code as described in .Xr development 7 . You can install the build utilities by running: .Bd -literal @@ -243,9 +252,9 @@ you can build gcc out-of-directory by running: .Pp You can remove the temporary .Pa ~/src/gcc-build -directory when finished. Notice how special make targets are used to -selectively build only parts of gcc. It is not possible or desirable to build -all of gcc here. +directory when finished. +Notice how special make targets are used to selectively build only parts of gcc. +It is not possible or desirable to build all of gcc here. .Ss Building Sortix With the build tools and cross-compiler in the .Ev PATH @@ -256,8 +265,8 @@ by setting to your value of .Sy $SORTIX_PLATFORM . This tells the build system you are cross-compiling and it will run the -appropriate cross-compiler. For instance, to build an bootable cdrom image -using a +appropriate cross-compiler. +For instance, to build an bootable cdrom image using a .Sy x86_64-sortix cross-compiler you can run: .Bd -literal @@ -273,15 +282,16 @@ The manual page documents how to develop Sortix and how to use the build system. This manual page only documents how to set up a cross-development environment and is not sufficient to develop Sortix, or to make a fully functional and -installable Sortix system. The above instructions only gives you a -cross-compilation of the base system without any of the nessesary ports of third -party software. +installable Sortix system. +The above instructions only gives you a cross-compilation of the base system +without any of the nessesary ports of third party software. .Pp The .Xr following-development 7 manual page documents what needs to be done to stay updated with the latest -developments. You will need to read the new version of that document whenever -you update the source code. +developments. +You will need to read the new version of that document whenever you update the +source code. .Ss Troubleshooting If producing a bootable cdrom with .Xr grub-mkrescue 1 @@ -289,7 +299,8 @@ gives the error .Pp .Dl xorriso : FAILURE : Cannot find path '/efi.img' in loaded ISO image .Pp -then your GRUB installation is defective. You need to install +then your GRUB installation is defective. +You need to install .Xr mformat 1 to use .Xr grub-mkrescue 1 diff --git a/share/man/man7/development.7 b/share/man/man7/development.7 index 15121cd4..762f6bf5 100644 --- a/share/man/man7/development.7 +++ b/share/man/man7/development.7 @@ -11,21 +11,23 @@ Releases come with the system source code in .Pa /src as a .Xr git 1 -repository. It can be modified, compiled and installed on the current system. +repository. +It can be modified, compiled and installed on the current system. The source code is built with a .Xr make 1 -build system. The source code can be located in any location, if so, simply -substitute +build system. +The source code can be located in any location, if so, simply substitute .Pa /src -with the real location. These instructions only apply to building the operating -system from within itself, those building it from another operating system needs -to follow +with the real location. +These instructions only apply to building the operating system from within +itself, those building it from another operating system needs to follow .Xr cross-development 7 instead. .Pp If you are building a new version of the operation system where build tools have -been added or changed, you first need to install the new tools. This is not -needed when building the matching release. To do so, run as root: +been added or changed, you first need to install the new tools. +This is not needed when building the matching release. +To do so, run as root: .Bd -literal cd /src make distclean # fully clean build directory @@ -44,10 +46,12 @@ system, run as root: The build system creates a minimal root filesystem structure in the .Pa /src/sysroot and builds each operating system component in turn, installing them into the -sysroot. If the source code for ports are placed in +sysroot. +If the source code for ports are placed in .Pa /src/ports -then they are automatically built as well. The result is a minimal system that -can be turned into working system by adding important configuration such as +then they are automatically built as well. +The result is a minimal system that can be turned into working system by adding +important configuration such as .Xr passwd 5 . .Pp The @@ -56,25 +60,29 @@ make target ensures a system is built in .Pa /src/sysroot and then runs the .Xr sysmerge 8 -program which installs the new system files onto the existing system. It -updates the system manifest as well all ports installed in the sysroot. The +program which installs the new system files onto the existing system. +It updates the system manifest as well all ports installed in the sysroot. +The .Xr initrd 7 is automatically regenerated using .Xr update-initrd 8 . The bootloader, if enabled in .Xr upgrade.conf 5 , -is reinstalled and configured as necessary. The new user-space is running on -completion, though existing processes will be running the old programs. -A reboot is needed to run the new kernel. If the ABI changed and the current -kernel isn't able to run the new programs, then the upgrade is delayed and will -be automatically completed on the next boot. The +is reinstalled and configured as necessary. +The new user-space is running on completion, though existing processes will be +running the old programs. +A reboot is needed to run the new kernel. +If the ABI changed and the current kernel isn't able to run the new programs, +then the upgrade is delayed and will be automatically completed on the next +boot. +The .Sy sysmerge-wait make target forces waiting until the next boot. .Ss Root Makefile The .Pa /src/Makefile -handles the high level build of the operating system. The important targets -are: +handles the high level build of the operating system. +The important targets are: .Bl -tag -width "12345678" .It Sy all (default) Build each component in turn and install them into the sysroot. @@ -119,26 +127,27 @@ Like but delay the upgrade until the next boot. .It Sy sysroot-base-headers Create the sysroot and install only the headers of the standard library and -kernel into it. This is useful when bootstrapping the runtime libraries of the -compiler that need to know about libc prior to building libc. +kernel into it. +This is useful when bootstrapping the runtime libraries of the compiler that +need to know about libc prior to building libc. .El .Pp The important environment variables influencing the Makefile are: .Bl -tag -width "12345678" .It Ev BUILD -The platform of the current operating system. This defaults to the current machine -and operating system. +The platform of the current operating system. +This defaults to the current machine and operating system. .It Ev HOST -Specifies platform on which the compiled code will run. This defaults to the -current machine and operating system. This is used when cross-compiling the -operating system. When cross-compiling the operating system, it must be set to -one of +Specifies platform on which the compiled code will run. +This defaults to the current machine and operating system. +This is used when cross-compiling the operating system. +When cross-compiling the operating system, it must be set to one of .Sy i686-sortix and .Sy x86_64-sortix . This must be unset when building the build tools as they run on the current -operating system. The compiler tools are prefixed with this variable if it does -not match +operating system. +The compiler tools are prefixed with this variable if it does not match .Ev BUILD. .It Ev OPTLEVEL Specifies compiler optimization options that gets added to @@ -146,8 +155,8 @@ Specifies compiler optimization options that gets added to and .Ev CXXFLAGS . .It Ev SORTIX_INCLUDE_SOURCE -Specifies whether the source code is included in the sysroot. This must be one -of +Specifies whether the source code is included in the sysroot. +This must be one of .Sy no, yes or .Sy git @@ -159,7 +168,8 @@ is installed and .Sy yes otherwise. .It Ev SORTIX_ISO_COMPRESSION -Specifies the compression algorithm used in iso files. This must be one of +Specifies the compression algorithm used in iso files. +This must be one of .Sy none , gzip or .Sy xz @@ -168,9 +178,10 @@ and defaults to .El .Ss Components The operating systems components, such as libc and the kernel, each have their -own directory by that name. It contains a makefile that can build and install -that component. This allows building and installing only that component onto -the current operating system. +own directory by that name. +It contains a makefile that can build and install that component. +This allows building and installing only that component onto the current +operating system. .Pp For instance, to build and install libc, run as root: .Bd -literal @@ -180,14 +191,15 @@ For instance, to build and install libc, run as root: .Ed .Pp System libraries are statically linked and you will have to relink programs with -the new library for changes to take effect. Building the whole operating system -from the root makefile ensures components are built in the right order such that -all programs use fresh libraries. +the new library for changes to take effect. +Building the whole operating system from the root makefile ensures components +are built in the right order such that all programs use fresh libraries. The root makefile invokes component makefiles with .Ev SYSROOT set to .Pa /src/sysroot -to force the compiler to locate files there. Likewise when installing, it sets +to force the compiler to locate files there. +Likewise when installing, it sets .Ev DESTDIR to .Pa /src/sysroot @@ -206,22 +218,25 @@ root makefile target creates this directory and populates it with a directory structure suitable for online publishing of a release. .It Pa /src/repository If ports are present, this directory is made when binary packages are built and -they are stored here. This works as a cache so ports don't have to be rebuilt -every time the operating system is. Packages are also copied from here rather -than the sysroot when making releases. +they are stored here. +This works as a cache so ports don't have to be rebuilt every time the operating +system is. +Packages are also copied from here rather than the sysroot when making releases. .It Pa /src/sysroot This directory is made when building the operating system and the freshly made -files are installed here. The build system uses this as the system root which -forces the compiler to look here for headers and libraries. This ensures a -clean bootstrap where files from the current operating system do not leak into -the new system. +files are installed here. +The build system uses this as the system root which forces the compiler to look +here for headers and libraries. +This ensures a clean bootstrap where files from the current operating system do +not leak into the new system. .It Pa /src/sysroot-overlay If this directory exists, it is added to the initrd of the produced iso and can contain additional system files. .El .Ss Build Tools -Some components are used to build the source code and must match the versions -in the source code being built. These are currently: +Some components are used to build the source code and must match the versions in +the source code being built. +These are currently: .Pp .Bl -bullet -compact .It @@ -237,15 +252,17 @@ tix .El .Pp If the currently installed versions of those tools are older than the ones in -the source code, you must update them. The +the source code, you must update them. +The .Sy clean-build-tools root makefile target cleans the applicable directories, the .Sy build-tools root makefile target builds them from the source code, and the .Sy install-build-tools -root makefile target installs the new version. You must clean the compiled -files from the source code afterwards because the compiled tools are intended to -run on the current system, and have not been built properly using +root makefile target installs the new version. +You must clean the compiled files from the source code afterwards because the +compiled tools are intended to run on the current system, and have not been +built properly using .Pa /src/sysroot . .Ss Ports You can place the source code for ports in @@ -255,8 +272,8 @@ format (has a file) in the .Pa /src/ports directory and they will get built automatically when and installed into the -sysroot when building the whole operating system. Installable binary packages -are created in the +sysroot when building the whole operating system. +Installable binary packages are created in the .Pa /src/repository/$HOST directory using .Xr tix-build 8 @@ -274,8 +291,8 @@ The ports system is described in detail in .Ss Patches The source code is managed as a .Xr git 1 -repository and you can make your own changes and commit them. A good approach -is to set up your own local development branch and work there: +repository and you can make your own changes and commit them. +A good approach is to set up your own local development branch and work there: .Bd -literal git checkout -b local git add utils/hello.c @@ -287,9 +304,10 @@ You can then easily prepare your a set of patches for upstream submission: git format-patch master..local .Ed .Pp -This will create a series of .patch files containing your changes. Review them -and rewrite git history as needed until they are of submittable quality. You can -then submit them for review at the official website. +This will create a series of .patch files containing your changes. +Review them and rewrite git history as needed until they are of submittable +quality. +You can then submit them for review at the official website. .Pp To transfer files out of the operating system, you can either mount the local root filesystem from another operating system with networking, or you transmit @@ -298,10 +316,12 @@ the patches over the serial connection as described in .Ss Releases CD-ROM release of the operating system can be built with the .Sy iso -root makefile target. This will build the whole operating system, if not done -already, and produce a bootable iso for the current architecture in the +root makefile target. +This will build the whole operating system, if not done already, and produce a +bootable iso for the current architecture in the .Pa /src/builds -directory. The +directory. +The .Sy sortix.iso root makefile target will do the above and place a .Pa sortix.iso @@ -319,8 +339,9 @@ formal online release. The .Xr following-development 7 manual page documents what needs to be done to stay updated with the latest -developments. You will need to read the new version of that document whenever -you update the source code. +developments. +You will need to read the new version of that document whenever you update the +source code. .Sh SEE ALSO .Xr git 1 , .Xr make 1 , diff --git a/share/man/man7/following-development.7 b/share/man/man7/following-development.7 index 575e26f6..ae155830 100644 --- a/share/man/man7/following-development.7 +++ b/share/man/man7/following-development.7 @@ -10,12 +10,13 @@ latest Sortix source code, when doing native .Xr development 7 or .Xr cross-development 7 . -The list is in reverse chronological order. The system has policies that handle -incompatible changes gracefully. +The list is in reverse chronological order. +The system has policies that handle incompatible changes gracefully. .Pp If you are updating to new source code, be sure you are reading the new version of this document, rather than an old copy installed on the system or on an -online manual page viewer. To view the new version from the command line: +online manual page viewer. +To view the new version from the command line: .Bd -literal cd /src # system source code location mandoc share/man/man7/following-development.7 | pager # natively @@ -27,8 +28,9 @@ The and .Xr sysupgrade 8 programs automatically handle compatibility issues when upgrading an existing -system to a new build. They can handle incompatible ABI changes and -automatically fix configuration files and other issues. +system to a new build. +They can handle incompatible ABI changes and automatically fix configuration +files and other issues. .Pp When building the system from source code, you must have the latest build tools installed as detailed in @@ -36,23 +38,29 @@ installed as detailed in and .Xr cross-development 7 . After upgrading to newer source code, you must first install the new build tools -before building. If this is needed, there will be a notice in this document. +before building. +If this is needed, there will be a notice in this document. Build tools will likely complain about missing options or invalid parameters if -they are not up to date. Automatic build scripts should use the +they are not up to date. +Automatic build scripts should use the .Sy install-build-tools target provided by the root makefile. .Pp Changes to the source code may rely on the newest build tools, but the build tools must retain the ability to build all the way back to the latest stable -release. The build tools of release N+1 must be able to build release N. The -build tools must be portable to the latest stable release and the supported +release. +The build tools of release N+1 must be able to build release N. +The build tools must be portable to the latest stable release and the supported .Xr cross-development 7 -systems. If a build tool needs an incompatible change, there must be added a -way to opt into the new behavior, and the build system must use that option and -not use the old behavior any more. This forward compatibility will allow the -removal of the old behavior after the next release. Temporary compatibility -must be mentioned with a condition for when it can be removed and it must have -instructions for what needs to be done. Use a comment in the format +systems. +If a build tool needs an incompatible change, there must be added a way to opt +into the new behavior, and the build system must use that option and not use the +old behavior any more. +This forward compatibility will allow the removal of the old behavior after the +next release. +Temporary compatibility must be mentioned with a condition for when it can be +removed and it must have instructions for what needs to be done. +Use a comment in the format "TODO: After .\" Line break so this occurrence doesn't make a false positive when I grep. releasing Sortix x.y, foo." to allow the maintainer to easily @@ -77,7 +85,8 @@ Otherwise the system is compatible except accessing Unix sockets fails with .Ss Add split packages and cross-bootstrapping support to tix-build(8) .Xr tix-build 8 has gained a number of features that will soon be required in order to build -certain ports. In particular, it now supports the +certain ports. +In particular, it now supports the .Sy pkg.use-bootstrap , .Sy pkg.source-package , and @@ -157,8 +166,8 @@ and the new build contains the new GRUB, or if upgrading with and the source system root contains the new GRUB. .Pp Users not using the included GRUB, but still using GRUB from another -installation, will need to reconfigure that bootloader installation. In the -boot commands of this system, add after the initrd load: +installation, will need to reconfigure that bootloader installation. +In the boot commands of this system, add after the initrd load: .Bd -literal module /boot/random.seed --random-seed .Ed @@ -184,8 +193,9 @@ and .Xr sysupgrade 8 will automatically create .Pa /boot/random.seed -if it doesn't exist. If using neither to upgrade, manually create that file -owned by user root and group root with mode 600 containing 256 bytes of entropy. +if it doesn't exist. +If using neither to upgrade, manually create that file owned by user root and +group root with mode 600 containing 256 bytes of entropy. .Ss Modernize carray(1) and fix missing allocation checks The .Xr carray 1 @@ -204,8 +214,9 @@ If not developing natively, set .Ev PREFIX to the desired location. .Ss Remove compatibility with Sortix 0.9 -Sortix 1.0 has been released. The build tools are no longer capable of building -anything prior to the Sortix 1.0 release. +Sortix 1.0 has been released. +The build tools are no longer capable of building anything prior to the Sortix +1.0 release. .Sh SEE ALSO .Xr cross-development 7 , .Xr development 7 , diff --git a/share/man/man7/initrd.7 b/share/man/man7/initrd.7 index ce6c90ea..8597a7c0 100644 --- a/share/man/man7/initrd.7 +++ b/share/man/man7/initrd.7 @@ -10,8 +10,8 @@ .Pa /boot/sortix.initrd is a achieve of a minimal userland loaded by the bootloader and passed to the .Xr kernel 7 -that extracts it into the initial kernel memory root filesystem. The kernel -invokes the +that extracts it into the initial kernel memory root filesystem. +The kernel invokes the .Xr init 8 extracted from the initrd as .Pa /sbin/init . diff --git a/share/man/man7/installation.7 b/share/man/man7/installation.7 index f848aedb..43949759 100644 --- a/share/man/man7/installation.7 +++ b/share/man/man7/installation.7 @@ -6,8 +6,10 @@ .Nd operating system installation instructions .Sh DESCRIPTION This document describes how to install Sortix on a computer from a cdrom -release. Please read it through carefully before beginning the installation so -you know what to expect and things you need to keep in mind. The +release. +Please read it through carefully before beginning the installation so you know +what to expect and things you need to keep in mind. +The .Xr upgrade 7 manual page covers upgrading an existing installation. .Ss Prerequisites @@ -28,8 +30,8 @@ A computer meeting the system requirements. 32-bit x86 CPU with SSE (i686 release), or 64-bit x86 CPU (x86_64 release). .It 1 GiB RAM (recommended) to run iso live environment (including installer) with -all ports loaded, or significantly less if unimportant ports are not loaded. An -installation on a harddisk will require very little RAM to run after +all ports loaded, or significantly less if unimportant ports are not loaded. +An installation on a harddisk will require very little RAM to run after installation. .It ATA or AHCI harddisk with at least 1 GiB of unpartitioned space. @@ -42,36 +44,38 @@ If you wish to dual boot, you need an existing operating system with a multiboot compliant bootloader such as GRUB. .El .Ss Preparation -Read this document through before beginning the installation. The installation -process is designed to be reasonable, but you need to patient and in an -emotionally stable place. It is important you understand the current -limitations of the system and carefully consider whether you want to go through -with the installation at this time. +Read this document through before beginning the installation. +The installation process is designed to be reasonable, but you need to patient +and in an emotionally stable place. +It is important you understand the current limitations of the system and +carefully consider whether you want to go through with the installation at this +time. .Pp Before installing any operating system, be sure to have backed up local data in -the event something goes wrong. This operating system comes without any -warranty at all (see the license). +the event something goes wrong. +This operating system comes without any warranty at all (see the license). .Pp -Consider the partitioning scheme and whether you wish to dual boot. Consult the -partitioning instructions below. If dual-booting and there isn't enough -unpartitioned space, use the native partition editor of the existing operating -system to shrink its installation. +Consider the partitioning scheme and whether you wish to dual boot. +Consult the partitioning instructions below. +If dual-booting and there isn't enough unpartitioned space, use the native +partition editor of the existing operating system to shrink its installation. .Pp -Determine how the target machine will boot the release. If the firmware -supports usb-iso hybrid images, you can use +Determine how the target machine will boot the release. +If the firmware supports usb-iso hybrid images, you can use .Xr dd 1 or such to copy the release physically onto a USB portable storage device. If the target machine has a cdrom drive, you can burn the release to a cdrom. -Insert the installation medium in the computer and power it on. If needed, -change the boot order in the firmware to prefer the installation medium over any -existing operating system installations. +Insert the installation medium in the computer and power it on. +If needed, change the boot order in the firmware to prefer the installation +medium over any existing operating system installations. .Pp After the installation is complete, remove the installation medium and restore -the firmware boot order to prioritize the local harddisk. Then power the -computer on normally to run the new operating system. +the firmware boot order to prioritize the local harddisk. +Then power the computer on normally to run the new operating system. .Ss Qemu -Virtual machines are a well-supported installation target. For instance, to -prepare a 1 GiB harddisk and install the operating system onto it, run something +Virtual machines are a well-supported installation target. +For instance, to prepare a 1 GiB harddisk and install the operating system onto +it, run something like: .Bd -literal qemu-img create sortix.raw 1G @@ -84,8 +88,8 @@ After the installation is complete, power off the computer and remove the .Pa sortix.iso option. .Ss Bootloader Menu -Booting the release will present you with a GRUB bootloader menu. You have -three primary options: +Booting the release will present you with a GRUB bootloader menu. +You have three primary options: .Pp .Bl -bullet -compact .It @@ -98,39 +102,45 @@ Upgrading an existing installation to this release .Xr ( sysupgrade 8 ) . .El .Pp -Each of these options are a live environment running exclusively in RAM. The -difference is only what program is run after the system has booted. The -bootloader will load the whole operating system and ports into memory from the -installation medium. This may take a moment. You need enough memory to store -the whole system and the runtime usage. If the system memory is really -insufficient, then the bootloader may have strange behavior, take a really long -time to load, or not complete the boot at all. +Each of these options are a live environment running exclusively in RAM. +The difference is only what program is run after the system has booted. +The bootloader will load the whole operating system and ports into memory from +the installation medium. +This may take a moment. +You need enough memory to store the whole system and the runtime usage. +If the system memory is really insufficient, then the bootloader may have +strange behavior, take a really long time to load, or not complete the boot at +all. .Pp -You can configure which ports gets loaded using the bootloader menu. The base -system is rather lean and can be made quite small. You need some ports to -complete an installation. +You can configure which ports gets loaded using the bootloader menu. +The base system is rather lean and can be made quite small. +You need some ports to complete an installation. .Ss Installer This guide assumes you selected the operating system installation option in the -bootloader. If not, you can run the installer by running the +bootloader. +If not, you can run the installer by running the .Xr sysinstall 8 command. .Pp The installer is an interactive command line program that asks you questions and -you answer them. It provides useful information you shouldn't accidentally -overlook. Before answering any question, read all output since your last -answer. +you answer them. +It provides useful information you shouldn't accidentally overlook. +Before answering any question, read all output since your last answer. .Pp -You should have this installation guide ready at all times. You can view this +You should have this installation guide ready at all times. +You can view this .Xr installation 7 page during the installation by answering .Sy '!man' -to any regular prompt (excluding password prompts). Likewise you can answer +to any regular prompt (excluding password prompts). +Likewise you can answer .Sy '!' -to get an interactive shell. Upon completion, you will be asked the question -again. +to get an interactive shell. +Upon completion, you will be asked the question again. .Ss Keyboard Layout -You need to choose the applicable keyboard layout. By default, a standard US -keyboard layout is used. You can view a list of keyboard layouts if you wish. +You need to choose the applicable keyboard layout. +By default, a standard US keyboard layout is used. +You can view a list of keyboard layouts if you wish. This layout is then loaded and the preference will be stored in .Xr kblayout 5 . .Ss Display Resolution @@ -143,56 +153,63 @@ The display will then use this resolution and your preference will be stored in The .Xr kernel 7 is a multiboot compatible binary that can be loaded by any multiboot -specification compatible bootloader such as GRUB. You need to use such a -bootloader to boot the operating system. You will be offered the choice of -installing GRUB as the bootloader. Note however that this GRUB is not able to -detect other operating systems and you will have to configure it manually if you -wish to use it in a dual boot scheme. The answer will default to yes if no -existing partitions are found, or if an existing Sortix installation is found -that uses the provided bootloader; and will otherwise default to no. +specification compatible bootloader such as GRUB. +You need to use such a bootloader to boot the operating system. +You will be offered the choice of installing GRUB as the bootloader. +Note however that this GRUB is not able to detect other operating systems and +you will have to configure it manually if you wish to use it in a dual boot +scheme. +The answer will default to yes if no existing partitions are found, or if an +existing Sortix installation is found that uses the provided bootloader; and +will otherwise default to no. .Pp The bootloader will be installed on the boot harddisk, which is the harddisk containing the .Pa /boot partition if any, and otherwise the harddisk containing the root filesystem. .Pp -Single-boot configurations should use the offered bootloader. Dual-boot -configurations should refuse it and arrange for bootloading by other means. The -installer will generate +Single-boot configurations should use the offered bootloader. +Dual-boot configurations should refuse it and arrange for bootloading by other +means. +The installer will generate .Pa /etc/grub.d/10_sortix.cache which is a fragment of GRUB configuration that offers the menu option of running -Sortix. You can splice that into +Sortix. +You can splice that into .Pa /etc/grub.d/40_custom of an existing GRUB installation and run .Xr update-grub 8 to add it as a boot option. .Pp If you accept the bootloader, you will be asked if you wish to password protect -the bootloader. If you don't, anyone able to use the keyboard during system -bootloading will be trivially able to gain root access using the bootloader -command line. If you use this, you should also password protect the firmware and -prohibit it from booting from anything but the harddisk. An attacker will then -need to tamper with the computer itself physically. The password will be hashed -and stored in +the bootloader. +If you don't, anyone able to use the keyboard during system bootloading will be +trivially able to gain root access using the bootloader command line. +If you use this, you should also password protect the firmware and prohibit it +from booting from anything but the harddisk. +An attacker will then need to tamper with the computer itself physically. +The password will be hashed and stored in .Xr grubpw 5 and is inserted into the GRUB configuration when .Xr update-grub 8 is run. .Ss Partitioning You will now need to set up a partition for the root filesystem and other -filesystems you wish to use. The installer will give you instructions and run -the +filesystems you wish to use. +The installer will give you instructions and run the .Xr disked 8 -partitioning program. You can view its man page by typing +partitioning program. +You can view its man page by typing .Sy man and you can view this man page by typing .Sy man 7 installation . .Pp .Nm disked -defaults to the first detected harddisk as the current harddisk. You can switch -to another harddisk using the +defaults to the first detected harddisk as the current harddisk. +You can switch to another harddisk using the .Sy device Ar device-name -command. You can view all devices with the +command. +You can view all devices with the .Sy devices command. .Pp @@ -217,11 +234,12 @@ The command lists all partitions and unused space on the current device. The .Sy mkpart -command creates a partition. You will be asked interactive questions to -determine its location. You will be asked if you wish to format a filesystem. +command creates a partition. +You will be asked interactive questions to determine its location. +You will be asked if you wish to format a filesystem. .Nm ext2 -is the native filesystem. If applicable, you will be asked if you wish to create -a mountpoint for it in +is the native filesystem. +If applicable, you will be asked if you wish to create a mountpoint for it in .Xr fstab 5 . The .Sy rmpart Ar partition-number @@ -231,8 +249,8 @@ partition. If you accepted the included bootloader, it will be installed on the boot harddisk, which is the harddisk containing the .Pa /boot -partition if any, and otherwise the harddisk containing the root filesystem. If -the boot harddisk uses the +partition if any, and otherwise the harddisk containing the root filesystem. +If the boot harddisk uses the .Xr gpt 7 partitioning scheme, then you must create a .Sy biosboot @@ -243,33 +261,37 @@ than sufficient. You need to make a partition containing the root filesystem mounted at .Pa / . A size of 1 GiB will be comfortable for the base system and ports and basic -usage. There is no inherent need for a +usage. +There is no inherent need for a .Pa /boot or a .Pa /home partition, so you are encouraged to make the root filesystem as large as you -wish. Operating systems upgrades will preserve the root filesystem and the -installer handles installing on top of an existing installation and preserves -user files and local configuration. +wish. +Operating systems upgrades will preserve the root filesystem and the installer +handles installing on top of an existing installation and preserves user files +and local configuration. .Pp Type .Sy exit -when you are done to continue the installation. If the installer detects a -problem with your partitioning, it will offer to run +when you are done to continue the installation. +If the installer detects a problem with your partitioning, it will offer to run .Xr disked 8 again. .Ss Installation The installer will show its installation intentions ask you to confirm the -installation. If you answer yes, then the installation will begin. +installation. +If you answer yes, then the installation will begin. .Pp The installer will copy the live environment into the target root filesystem according to the file lists in .Pa /tix/manifest -and create configuration files matching your earlier choices. It will write -256 bytes of randomness to +and create configuration files matching your earlier choices. +It will write 256 bytes of randomness to .Pa /boot/random.seed . -It will generate an initrd that locates and boots the root filesystem. It will -install the bootloader if desired. The installation will take a moment. +It will generate an initrd that locates and boots the root filesystem. +It will install the bootloader if desired. +The installation will take a moment. .Ss Configuration After the installation is complete, a bare system is installed but it lacks crucial configuration files and it will refuse to start when booted. @@ -278,21 +300,24 @@ You will be asked for the hostname of the new system which be stored in .Xr hostname 5 . This question is skipped if the file already exits. .Ss Root -You will be asked for the root password. A root account is made in +You will be asked for the root password. +A root account is made in .Xr passwd 5 and .Xr group 5 . This question is skipped if the root account already exists. .Ss Users -You will be asked in a loop if you wish to make another user. Answer +You will be asked in a loop if you wish to make another user. +Answer .Sy no -when you are done. Otherwise enter the name of the new account. If you wish to -create an account by the name of +when you are done. +Otherwise enter the name of the new account. +If you wish to create an account by the name of .Li no then simply add a space in front as leading spaces are trimmed. .Pp -You will then be asked for the full name and the password for the new user. A -user directory will be made in +You will then be asked for the full name and the password for the new user. +A user directory will be made in .Pa /home . The new user is added to .Xr passwd 5 @@ -302,23 +327,26 @@ and Please note that Sortix is not currently secure as a multi-user system and filesystem permissions are not enforced. .Ss Completion -This will complete the operating system installation. Upon reboot, the new -system will start normally. After powering off your system, you need to remove -the installation medium and if applicable restore boot priorities in your -firmware. If you did not accept the bootloader, you will need to manually -configure a bootloader to boot the new operating system. +This will complete the operating system installation. +Upon reboot, the new system will start normally. +After powering off your system, you need to remove the installation medium and +if applicable restore boot priorities in your firmware. +If you did not accept the bootloader, you will need to manually configure a +bootloader to boot the new operating system. .Pp You will be given the choice between powering off the system, rebooting it, or -directly booting the new system. The last option will directly boot the new -system in a chroot while the live environment remains in the background. If you -invoked +directly booting the new system. +The last option will directly boot the new system in a chroot while the live +environment remains in the background. +If you invoked .Xr sysinstall 8 -yourself, then you will be returned to your live environment shell. Otherwise -the computer will power off when the chroot environment terminates. +yourself, then you will be returned to your live environment shell. +Otherwise the computer will power off when the chroot environment terminates. .Pp Upon boot of the new system it will be configured in multi-user mode and you -will be presented with a login screen. Authenticate as one of the local users -and you will be given a shell. To power off the computer login as user +will be presented with a login screen. +Authenticate as one of the local users and you will be given a shell. +To power off the computer login as user .Sy poweroff and to reboot the computer login as user .Sy reboot . diff --git a/share/man/man7/kernel.7 b/share/man/man7/kernel.7 index 214292b0..bc3ee5fd 100644 --- a/share/man/man7/kernel.7 +++ b/share/man/man7/kernel.7 @@ -12,7 +12,8 @@ is the operating system .Nm kernel . It initializes and manages the hardware to provide a multitasking computing -environment. The kernel is a +environment. +The kernel is a .Xr multiboot 7 compatible executable loaded by the bootloader along with a companion .Xr initrd 7 diff --git a/share/man/man7/serial-transfer.7 b/share/man/man7/serial-transfer.7 index 8ed2d1a5..13d4494f 100644 --- a/share/man/man7/serial-transfer.7 +++ b/share/man/man7/serial-transfer.7 @@ -5,22 +5,24 @@ .Nm serial-transfer .Nd files over serial device .Sh DESCRIPTION -You can transfer data using the serial line. The +You can transfer data using the serial line. +The .Xr sf 1 -program provides simple framing which is useful to conduct advanced transfers -by combining with other tools such as +program provides simple framing which is useful to conduct advanced transfers by +combining with other tools such as .Xr tar 1 . .Pp The serial device will be available at the appropriate device after boot, such as .Pa /dev/com1 . Data written to it will be available to readers on the other end and likewise -data written on the other end will be available to local readers. Take care to -ensure that the reader is always reading before writing or you may lose data. +data written on the other end will be available to local readers. +Take care to ensure that the reader is always reading before writing or you may +lose data. .Pp -You get a byte stream between the guest and host using this interface. This is -powerful but often you want to transfer finite payloads and have the transfer -finish when done rather than needing to manually interrupt it. +You get a byte stream between the guest and host using this interface. +This is powerful but often you want to transfer finite payloads and have the +transfer finish when done rather than needing to manually interrupt it. .Pp The .Xr sf 1 @@ -31,12 +33,14 @@ sequence, then read from stdin and encode a body, and finally emit an end sequence. .Li sf -i will read bytes until it finds a start sequence, then it will decode the body -and emit it to stdout, and finally stop when it receives the end sequence. We -can use this to do transfers over the serial connection. +and emit it to stdout, and finally stop when it receives the end sequence. +We can use this to do transfers over the serial connection. .Pp .Xr sf 1 -is a Sortix specific program. Other operating systems don't come with it and you -need to build it from the Sortix source code. This is automatically done by the +is a Sortix specific program. +Other operating systems don't come with it and you need to build it from the +Sortix source code. +This is automatically done by the .Sy build-tools target during .Xr cross-development 7 . @@ -45,8 +49,9 @@ You can also just transfer its code from over the serial line. .Ss Virtual Machines This method is useful when running inside a virtual machine and you wish to -communicate with the host system. This is particularly useful if you connect -the serial line to a unix socket. In Qemu, this is done with: +communicate with the host system. +This is particularly useful if you connect the serial line to a unix socket. +In Qemu, this is done with: .Bd -literal -serial unix:/tmp/serial,server,nowait .Ed @@ -58,14 +63,15 @@ Let .Pa /dev/receiver mean the device on the receiving machine and let .Pa /dev/transmitter -mean the device on the transmitting machine. This will be devices such as +mean the device on the transmitting machine. +This will be devices such as .Pa /dev/com1 . If one end is the host of a virtual machine as described above, its device will be an unix socket such as .Pa /tmp/serial . .Ss Simple File Transfer -You can then transfer a file from this system to another. First run on the -receiving machine: +You can then transfer a file from this system to another. +First run on the receiving machine: .Bd -literal sf -i /dev/receiver > file.txt .Ed @@ -81,7 +87,8 @@ end when it has recognized an end sequence. You can transfer multiple files using .Xr tar 1 . This also allows you to preserve file meta data such as permissions and modified -time. First run on the receiving machine: +time. +First run on the receiving machine: .Bd -literal sf -i /dev/receiver | tar -xv .Ed @@ -100,9 +107,11 @@ It is possible to use the and .Xr sfncd 1 scripts to create a bidirectional communication channel using two serial ports, -one for each direction. The scripts use a protocol where +one for each direction. +The scripts use a protocol where .Xr sfnc 1 -sends a hostname, a port, and the body from stdin. Likewise the +sends a hostname, a port, and the body from stdin. +Likewise the .Xr sfncd 1 script receives the two parameters and invokes .Xr nc 1 @@ -120,9 +129,9 @@ And then run on the client: .Pp This will last for the duration of the connection. .Xr sfncd 1 -needs to be run again to start another connection. This scheme only allows one -connection at one given time, but with it is possible for custom programs on -either side to multiplex connections. +needs to be run again to start another connection. +This scheme only allows one connection at one given time, but with it is +possible for custom programs on either side to multiplex connections. .Sh SEE ALSO .Xr sf 1 , .Xr tar 1 , diff --git a/share/man/man7/upgrade.7 b/share/man/man7/upgrade.7 index b5a71d02..29f0ebef 100644 --- a/share/man/man7/upgrade.7 +++ b/share/man/man7/upgrade.7 @@ -6,7 +6,8 @@ .Nd operating system upgrade instructions .Sh DESCRIPTION This document describes how to upgrade an existing Sortix installation to a -newer release. The +newer release. +The .Xr installation 7 manual page covers creating a new installation. .Ss Prerequisites @@ -14,39 +15,44 @@ You need to prepare a bootable medium with the new release as described in .Xr installation 7 . Read all the instructions up to Bootloader Menu and continue with this document. .Pp -It is not possible to skip releases. If you want to upgrade to a release, you -must upgrade first to all releases before that one. If the existing installation -is a development snapshot, you must either upgrade to a newer development -snapshot of that version, or a the final release of that version. +It is not possible to skip releases. +If you want to upgrade to a release, you must upgrade first to all releases +before that one. +If the existing installation is a development snapshot, you must either upgrade +to a newer development snapshot of that version, or a the final release of that +version. .Ss Bootloader Menu Pick the .Li upgrade existing installation -option in the bootloader menu to begin the upgrade. This will load a live -environment set to automatically run the +option in the bootloader menu to begin the upgrade. +This will load a live environment set to automatically run the .Xr sysupgrade 8 program. .Ss Upgrader -This guide assumes you selected the upgrade option in the bootloader. If not, -you can run the installer by running the +This guide assumes you selected the upgrade option in the bootloader. +If not, you can run the installer by running the .Xr sysupgrade 8 command. .Pp The upgrader is an interactive command line program that asks you questions and -you answer them. It provides useful information you shouldn't accidentally -overlook. Before answering any question, read all output since your last -answer. +you answer them. +It provides useful information you shouldn't accidentally overlook. +Before answering any question, read all output since your last answer. .Pp -You should have this upgrade guide ready at all times. You can view this +You should have this upgrade guide ready at all times. +You can view this .Xr upgrade 7 page during the installation by answering .Sy '!man' -to any regular prompt (excluding password prompts). Likewise you can answer +to any regular prompt (excluding password prompts). +Likewise you can answer .Sy '!' -to get an interactive shell. Upon completion, you will be asked the question -again. +to get an interactive shell. +Upon completion, you will be asked the question again. .Ss Keyboard Layout -You need to choose the applicable keyboard layout. By default, a standard US -keyboard layout is used. You can view a list of keyboard layouts if you wish. +You need to choose the applicable keyboard layout. +By default, a standard US keyboard layout is used. +You can view a list of keyboard layouts if you wish. .Ss Display Resolution If a driver exists for your graphics card, then you will be asked for your preferred display resolution by @@ -55,30 +61,36 @@ preferred display resolution by The upgrader will search for existing Sortix installations by probing local filesystems for .Pa /etc/sortix-release . -You will be asked which installation you wish to upgrade. Enter the name of the -root filesystem device. If none are found, it asks if you want to run -.Xr sysinstall 8 . Filesystems will be repaired by +You will be asked which installation you wish to upgrade. +Enter the name of the root filesystem device. +If none are found, it asks if you want to run +.Xr sysinstall 8 . +Filesystems will be repaired by .Xr fsck 8 as needed. .Ss Confirmation The upgrader will warn you if it detects you are not following proper upgrade procedure either by downgrading or by skipping a release, neither of which is -supported. It will also warn you if it detects an ABI downgrade. +supported. +It will also warn you if it detects an ABI downgrade. .Pp The upgrade will load the upgrade preferences from .Pa /etc/upgrade.conf file of the target system as described in .Xr upgrade.conf 5 . .Pp -The new release may have a new ABI. A major ABI change means the new kernel -will be unable to properly execute old programs. A minor ABI change means the -new kernel has new compatible features and will be able to run older programs, -but older kernels will not be able to run programs using the new ABI. +The new release may have a new ABI. +A major ABI change means the new kernel will be unable to properly execute old +programs. +A minor ABI change means the new kernel has new compatible features and will be +able to run older programs, but older kernels will not be able to run programs +using the new ABI. .Pp A confirmation screen will tell you what actions the upgrader plan on doing. Answer .Sy yes -to proceed with the upgrade. Otherwise you can escape to a shell, edit +to proceed with the upgrade. +Otherwise you can escape to a shell, edit .Xr upgrade.conf 5 , return and answer .Sy no @@ -99,10 +111,11 @@ Updating the initrd. Updating the bootloader. .El .Ss Completion -The upgrade is now complete. The new system will run after a reboot. The -upgrader will give you an overview of what it has done. If you upgraded across -a major ABI change, then you will be told that you need to recompile all local -programs to use the new ABI. +The upgrade is now complete. +The new system will run after a reboot. +The upgrader will give you an overview of what it has done. +If you upgraded across a major ABI change, then you will be told that you need +to recompile all local programs to use the new ABI. .Pp Congratulations on your freshly upgraded Sortix system. .Sh SEE ALSO diff --git a/share/man/man7/user-guide.7 b/share/man/man7/user-guide.7 index 76a52c2f..ba1247fa 100644 --- a/share/man/man7/user-guide.7 +++ b/share/man/man7/user-guide.7 @@ -18,10 +18,11 @@ You will be presented a with standard Unix command line environment upon login o booting the live environment. .Ss Shutdown .Xr init 8 -spawns a session after boot. This is +spawns a session after boot. +This is .Xr login 8 -if the system is booted in multi-user mode. This is a root shell if booted in -single-user mode. +if the system is booted in multi-user mode. +This is a root shell if booted in single-user mode. .Pp To power off from the login screen, login as user .Sy poweroff . @@ -30,7 +31,8 @@ To reboot, login as user .Pp To power off from a single-user boot root shell, run .Sy exit 0 -in the shell. To reboot, run +in the shell. +To reboot, run .Sy exit 1 in the shell. .Ss Keyboard Layout @@ -64,9 +66,11 @@ to change the video mode after boot. .Ss Manual The system manual can be viewed with the .Xr man 1 -program. Sortix is currently in the process of being documented and many manual -pages are missing. The current priority is to document areas specific to Sortix -and assume standard knowledge from other operating system. +program. +Sortix is currently in the process of being documented and many manual pages are +missing. +The current priority is to document areas specific to Sortix and assume standard +knowledge from other operating systems. .Ss Editor .Xr editor 1 is the standard text file editor. @@ -82,7 +86,8 @@ The .Xr memstat 1 command shows the current memory usage. .Ss Third Party Software -Releases come with useful third party software installed. The +Releases come with useful third party software installed. +The .Pa /tix/installed.list file lists all currently installed ports. .Ss Source Code @@ -90,8 +95,8 @@ Releases come full with the system source code in .Pa /src as a .Xr git 1 -repository along with the tools to build it and develop it. The build -process is covered in +repository along with the tools to build it and develop it. +The build process is covered in .Xr development 7 . .Ss Mounting You can mount ext2 partitions using @@ -111,13 +116,14 @@ driver only supports the .Sy large_file and .Sy filetype -ext2 extensions. You can make a compatible filesystem with: +ext2 extensions. +You can make a compatible filesystem with: .Pp .Dl $ mkfs.ext2 -O none,large_file,filetype .Ss Networking -Sortix does not have networking at this time. Unix sockets have a basic -implementation incapable of advanced features. The standard library and -kernel provides stubs for many network interfaces. +Sortix does not have networking at this time. +Unix sockets have a basic implementation incapable of advanced features. +The standard library and kernel provides stubs for many network interfaces. .Ss Serial Transfer It is possible to transfer files over serial devices as described in .Xr serial-transfer 7 . diff --git a/sysinstall/sysinstall.8 b/sysinstall/sysinstall.8 index 04a53acb..25f08363 100644 --- a/sysinstall/sysinstall.8 +++ b/sysinstall/sysinstall.8 @@ -9,8 +9,9 @@ .Sh DESCRIPTION .Nm is an interactive command line program that creates a new installation of the -operating system. It asks basic questions, prepares a new root filesystem, -makes a copy of the current operating system there and configures it for usage. +operating system. +It asks basic questions, prepares a new root filesystem, makes a copy of the +current operating system there and configures it for usage. The installation proceeds as described in .Xr installation 7 . .Pp diff --git a/sysinstall/sysmerge.8 b/sysinstall/sysmerge.8 index c72c6251..68577596 100644 --- a/sysinstall/sysmerge.8 +++ b/sysinstall/sysmerge.8 @@ -16,8 +16,9 @@ upgrades the current operating system by copying the system files from the specified .Ar source -directory (usually a sysroot) onto the current root filesystem. This is meant -to be used when building the operating system from source as described in +directory (usually a sysroot) onto the current root filesystem. +This is meant to be used when building the operating system from source as +described in .Xr development 7 . .Pp .Nm @@ -25,7 +26,8 @@ installs the .Sy system manifest from the tix repository in the .Ar source -directory, as well as all the ports found. The +directory, as well as all the ports found. +The .Xr initrd 7 is regenerated using .Xr update-initrd 8 . @@ -34,8 +36,10 @@ If grub is enabled in then the bootloader is reinstalled and reconfigured as needed. .Pp .Nm -is an automatic and non-interactive upgrade. It is meant to be used as part of -the development process to upgrade to locally built versions. The +is an automatic and non-interactive upgrade. +It is meant to be used as part of the development process to upgrade to locally +built versions. +The .Xr sysupgrade 8 program is by contrast an interactive program, meant to help upgrading across much larger development distances. @@ -43,33 +47,35 @@ much larger development distances. The options are as follows: .Bl -tag -width "12345678" .It Fl \-booting -It's boot time, complete the system upgrade that was delayed. This is meant to -be used by +It's boot time, complete the system upgrade that was delayed. +This is meant to be used by .Xr init 8 through the .Sy merge -boot target. This installs the +boot target. +This installs the .Pa /sysmerge directory onto the root filesystem and removes the .Pa /sysmerge directory. .It Fl c , Fl \-cancel -Cancel a pending upgrade that would trigger on the next boot. Remove the +Cancel a pending upgrade that would trigger on the next boot. +Remove the .Pa /sysmerge directory and restore the old .Xr kernel 7 and .Xr initrd 7 . .It Fl \-hook-finalize -Run the pre-installation compatibility hooks. This is meant to be used by the -old +Run the pre-installation compatibility hooks. +This is meant to be used by the old .Nm when it invokes the new .Nm during a non-waiting upgrade. .It Fl \-hook-prepare -Run the post-prepare compatibility hooks. This is meant to be used by the -old +Run the post-prepare compatibility hooks. +This is meant to be used by the old .Nm when it invokes the new .Nm @@ -88,7 +94,8 @@ with an initrd that runs on boot through the .Sy chain-merge .Xr init 8 -boot target. Backups are made of the +boot target. +Backups are made of the .Xr kernel 7 and .Xr initrd 7 diff --git a/sysinstall/sysupgrade.8 b/sysinstall/sysupgrade.8 index f6c50fb6..94bb33b3 100644 --- a/sysinstall/sysupgrade.8 +++ b/sysinstall/sysupgrade.8 @@ -9,11 +9,12 @@ .Sh DESCRIPTION .Nm is an interactive command line program that upgrades another installation to the -current operating system. It asks basic questions, searches for existing -installations, verifies the upgrade makes sense, and upgrades the target system -according to +current operating system. +It asks basic questions, searches for existing installations, verifies the +upgrade makes sense, and upgrades the target system according to .Xr upgrade.conf 5 -of the target system. The upgrade proceeds as described in +of the target system. +The upgrade proceeds as described in .Xr upgrade 7 . .Pp .Nm diff --git a/utils/chkblayout.1 b/utils/chkblayout.1 index 56582c76..510b54ab 100644 --- a/utils/chkblayout.1 +++ b/utils/chkblayout.1 @@ -11,7 +11,8 @@ .Fl l .Sh DESCRIPTION .Nm -changes the current keyboard layout. Changes do not persist across reboots. +changes the current keyboard layout. +Changes do not persist across reboots. The keyboard layout applied on boot can be configured in .Pa /etc/kblayout (see diff --git a/utils/chroot.8 b/utils/chroot.8 index 851efe15..dd30053f 100644 --- a/utils/chroot.8 +++ b/utils/chroot.8 @@ -41,7 +41,8 @@ inside .Ar newroot . The mountpoint is removed when .Ar command -completes. This option is useful for running installations. +completes. +This option is useful for running installations. .El .Sh ENVIRONMENT The environment is preserved. diff --git a/utils/pager.1 b/utils/pager.1 index edd584e3..76195187 100644 --- a/utils/pager.1 +++ b/utils/pager.1 @@ -10,9 +10,9 @@ .Ar file ... .Sh DESCRIPTION .Nm -displays the input one page at a time. The input is the concatenation of the -input files, or the standard input if no files were specified and the -standard input is not a terminal. +displays the input one page at a time. +The input is the concatenation of the input files, or the standard input if no +files were specified and the standard input is not a terminal. .Pp The options are as follows: .Bl -tag -width "12345678" @@ -20,11 +20,12 @@ The options are as follows: Output only escape sequences that change font properties such as color and boldness. .It Fl r -Causes raw control characters to be dumped directly onto the terminal. Usage -of this option may cause output to be misleading for suspicious files, as the -escape codes in the file are rendered and can be used to hide parts of the -input. Avoid the -r option if you want to see the actual bytes in the file, -or use -R to show only selected escape codes. +Causes raw control characters to be dumped directly onto the terminal. +Usage of this option may cause output to be misleading for suspicious files, as +the escape codes in the file are rendered and can be used to hide parts of the +input. +Avoid the -r option if you want to see the actual bytes in the file, or use -R +to show only selected escape codes. .El .Sh COMMANDS .Nm diff --git a/utils/unmount.8 b/utils/unmount.8 index 5a566f1f..a6345095 100644 --- a/utils/unmount.8 +++ b/utils/unmount.8 @@ -10,8 +10,8 @@ .Ar directory ... .Sh DESCRIPTION .Nm -unmounts the specified paths. The mountpoint is removed so that it cannot be -opened further, and +unmounts the specified paths. +The mountpoint is removed so that it cannot be opened further, and .Nm waits until no files on the filesystem are open, after which the filesystem is shut off cleanly. @@ -20,12 +20,13 @@ The options are as follows: .Bl -tag -width "12345678" .It Fl f, Fl \-force Shut off the filesystem immediately, further operations to any open files will -fail. The filesystem will be consistent, but processes may be stopped in the -middle of file operations. +fail. +The filesystem will be consistent, but processes may be stopped in the middle of +file operations. .It Fl l, Fl \-lazy -Do not wait for the filesystem to be unused, and shut off the filesystem in -the background. It is not safe to shut down the computer directly after using -this option. +Do not wait for the filesystem to be unused, and shut off the filesystem in the +background. +It is not safe to shut down the computer directly after using this option. .El .Sh EXIT STATUS .Nm