From: Michal Sojka Date: Wed, 18 May 2016 15:09:16 +0000 (+0200) Subject: doc: More grammar fixes X-Git-Tag: 20170423~6 X-Git-Url: https://rtime.felk.cvut.cz/gitweb/novaboot.git/commitdiff_plain/31a66c39b7472abea18fa823869ad6672213b3f1 doc: More grammar fixes --- diff --git a/README.pod b/README.pod index 537232d..324a400 100644 --- a/README.pod +++ b/README.pod @@ -34,9 +34,10 @@ Novaboot uses configuration files to, among other things, define command line options needed for different targets. Users typically use only the B<-t>/B<--target> command line option to select the target. Internally, this option expands to the pre-configured options. -Configuration files are searched at multiple places, which allows to -have per-system, per-user or per-project configurations. Configuration -file syntax is described in section L. +Novaboot searches configuration files at multiple places, which allows +having per-system, per-user or per-project configurations. +Configuration file syntax is described in section L. Simple examples of using C: @@ -44,7 +45,7 @@ Simple examples of using C: =item 1. -Run an OS in Qemu. This can be specified with the B<--qemu> option. +Running an OS in Qemu can be accomplished by giving the B<--qemu> option. Thus running novaboot --qemu myos @@ -55,7 +56,7 @@ boot the configuration specified in the F script. =item 2. Create a bootloader configuration file (currently supported -bootloaders are GRUB, GRUB2, ISOLINUX, Pulsar and U-Boot) and copy it +bootloaders are GRUB, GRUB2, ISOLINUX, Pulsar, and U-Boot) and copy it with all other files needed for booting to a remote boot server. Then use a TCP/IP-controlled relay/serial-to-TCP converter to reset the target and receive its serial output. @@ -74,7 +75,7 @@ from it. ./myos --dhcp-tftp -This is useful when no network infrastructure is in place and +This usage is useful when no network infrastructure is in place, and the target is connected directly to developer's box. =item 4. @@ -83,7 +84,7 @@ Create bootable ISO image. novaboot --iso -- script1 script2 -The created ISO image will have ISOLINUX bootloader installed on it +The created ISO image will have ISOLINUX bootloader installed on it, and the boot menu will allow selecting between I and I configurations. @@ -91,9 +92,9 @@ I configurations. =head1 PHASES AND OPTIONS -Novaboot performs its work in several phases. Each phase can be -influenced by several command line options, certain phases can be -skipped. The list of phases (in the execution order) is as follows. +Novaboot performs its work in several phases. Command like options +described bellow influence the execution of each phase or allow their +skipping. The list of phases (in the execution order) is as follows. =over @@ -122,9 +123,9 @@ command line options that control it. =head2 Configuration reading phase -After starting, novaboot reads configuration files. Their content is -described in section L. By default, -the configuration is read from multiple locations. First from the system +After starting, novaboot reads zero or more configuration files. We +describe their content in section L. By default, the +configuration is read from multiple locations. First from the system configuration directory (F), second from the user configuration file (F<~/.config/novaboot>) and third from F<.novaboot> files along the path to the current directory. Alternatively, a single @@ -146,15 +147,15 @@ Finally, novaboot searches for files named F<.novaboot> starting from the directory of the novaboot script (or working directory, see bellow) and continuing upwards up to the root directory. The found configuration files are then read in the opposite order (i.e. from the -root directory downwards). This allows having, for example, a project +root directory downwards). This ordering allows having, for example, a project specific configuration in F<~/project/.novaboot>. Note the difference between F<~/.config/novaboot> and F<~/.novaboot>. -The former one is read always, whereas the latter only when novaboot +The former one is always read, whereas the latter only when novaboot script or working directory is under the C<$HOME> directory. In certain cases, the location of the novaboot script cannot be -determined in this early phase. This happens either when the script is +determined in this early phase. This situation happens either when the script is read from the standard input or when novaboot is invoked explicitly as in the example L above. In this case, the current working directory is used as a starting point for configuration file search @@ -189,7 +190,7 @@ options stored in the C<%targets> configuration variable under key I. See also L. When this option is not given, novaboot tries to determine the target -to use from either B environment variable or from +to use from either B environment variable or B<$default_target> configuration file variable. =back @@ -203,13 +204,13 @@ used in the later phases. =item -a, --append=I -Append a string to the first C line in the novaboot script. This +Append a string to the first C line in the novaboot script. This option can be used to append parameters to the kernel's or root task's command line. This option can appear multiple times. =item -b, --bender -Use L +Use L chainloader. Bender scans the PCI bus for PCI serial ports and stores the information about them in the BIOS data area for use by the kernel. @@ -233,7 +234,7 @@ script with F. =item --scriptmod=I -When novaboot script is read, I is executed for every +When novaboot reads the script, I is executed for every line (in $_ variable). For example, C replaces every occurrence of I in the script with I. @@ -251,7 +252,7 @@ In this phase, files needed for booting are generated in a so-called I (see L). In most cases configuration for a bootloader is generated automatically by novaboot. It is also possible to generate other files using I or I<"<"> syntax in -novaboot scripts. Finally, binaries can be generated in this phases by +novaboot scripts. Finally, novaboot can generate binaries in this phases by running C or C. =over 8 @@ -302,7 +303,7 @@ specified F is used. The content of the menu entry can be customized with B<--grub-preamble>, B<--grub2-prolog> or B<--grub_prefix> options. -In order to use the generated menu entry on your development +To use the generated menu entry on your development machine that uses GRUB2, append the following snippet to F file and regenerate your grub configuration, i.e. run update-grub on Debian/Ubuntu. @@ -313,7 +314,7 @@ i.e. run update-grub on Debian/Ubuntu. =item --grub2-prolog=I -Specifies text that is put at the beginning of the GRUB2 menu entry. +Specifies the text that novaboot puts at the beginning of the GRUB2 menu entry. =item -m, --make[=make command] @@ -328,7 +329,7 @@ server directory where the boot files are copied to. =item --no-file-gen Do not run external commands to generate files (i.e. "<" syntax and -C keyword). This switch does not influence generation of files +C keyword). This switch does not influence the generation of files specified with "< parameter. If +The hostname or (IP address) is given by the I parameter. If the I is not specified, environment variable AMT_PASSWORD is used. The I specifies a TCP port for SOL. If not specified, the -default is 16992. Default I is admin. +default is 16992. The default I is admin. =item --iprelay=I Use TCP/IP relay and serial port to access the target's serial port -and powercycle it. The IP address of the relay is given by I -parameter. If I is not specified, it defaults to 23. +and powercycle it. The I parameter specifies the IP address of +the relay. If I is not specified, it defaults to 23. Note: This option is supposed to work with HWG-ER02a IP relays. @@ -400,7 +401,9 @@ example C. =item --remote-expect=I Wait for reception of I after establishing the remote -connection. +connection. This option is needed when novaboot should wait for +confirmation before deploying files to the target, e.g. to not +overwrite other user's files when they are using the target. =item --remote-expect-silent=I @@ -428,7 +431,7 @@ directly connected by a plain Ethernet cable to your workstation. The DHCP and TFTP servers require root privileges and C uses C command to obtain those. You can put the following to I to allow running the necessary commands without asking -for password. +for a password. Cmnd_Alias NOVABOOT = /bin/ip a add 10.23.23.1/24 dev eth0, /bin/ip l set dev eth0 up, /usr/sbin/dhcpd -d -cf dhcpd.conf -lf dhcpd.leases -pf dhcpd.pid, /usr/sbin/in.tftpd --listen --secure -v -v -v --pidfile tftpd.pid *, /usr/bin/touch dhcpd.leases, /usr/bin/pkill --pidfile=dhcpd.pid, /usr/bin/pkill --pidfile=tftpd.pid your_login ALL=NOPASSWD: NOVABOOT @@ -440,7 +443,7 @@ B<--dhcp-tftp> except that DHCP server is not started. The TFTP server requires root privileges and C uses C command to obtain those. You can put the following to I -to allow running the necessary commands without asking for password. +to allow running the necessary commands without asking for a password. Cmnd_Alias NOVABOOT = /usr/sbin/in.tftpd --listen --secure -v -v -v --pidfile tftpd.pid *, /usr/bin/pkill --pidfile=tftpd.pid your_login ALL=NOPASSWD: NOVABOOT @@ -451,8 +454,8 @@ Port to run the TFTP server on. Implies B<--tftp>. =item --netif=I -Network interface used to deploy files to the target. Default value is -I. This influences the configuration of the DHCP server started +Network interface used to deploy files to the target. The default value is +I. This option influences the configuration of the DHCP server started by B<--dhcp-tftp> and the value that B<$NB_MYIP> get replaced with during U-Boot conversation. @@ -471,7 +474,7 @@ novaboot script (see also B<--name>). =item --rsync-flags=I -Specifies which I are appended to F command line when +Specifies I to append to F command line when copying files as a result of I<--server> option. =item --concat @@ -525,7 +528,7 @@ Replace the default qemu flags (QEMU_FLAGS variable or C<-cpu coreduo =item --reset-cmd=I -Command that resets the target. +Runs command I to reset the target. =item --reset-send=I @@ -630,7 +633,7 @@ sequence to exit novaboot. =item --no-interaction, --interaction Skip resp. force target interaction phase. When skipped, novaboot exits -immediately when boot is initiated. +immediately after the boot is initiated. =item --expect=I diff --git a/novaboot b/novaboot index ff17e71..f98a836 100755 --- a/novaboot +++ b/novaboot @@ -1275,9 +1275,10 @@ Novaboot uses configuration files to, among other things, define command line options needed for different targets. Users typically use only the B<-t>/B<--target> command line option to select the target. Internally, this option expands to the pre-configured options. -Configuration files are searched at multiple places, which allows to -have per-system, per-user or per-project configurations. Configuration -file syntax is described in section L. +Novaboot searches configuration files at multiple places, which allows +having per-system, per-user or per-project configurations. +Configuration file syntax is described in section L. Simple examples of using C: @@ -1285,7 +1286,7 @@ Simple examples of using C: =item 1. -Run an OS in Qemu. This can be specified with the B<--qemu> option. +Running an OS in Qemu can be accomplished by giving the B<--qemu> option. Thus running novaboot --qemu myos @@ -1296,7 +1297,7 @@ boot the configuration specified in the F script. =item 2. Create a bootloader configuration file (currently supported -bootloaders are GRUB, GRUB2, ISOLINUX, Pulsar and U-Boot) and copy it +bootloaders are GRUB, GRUB2, ISOLINUX, Pulsar, and U-Boot) and copy it with all other files needed for booting to a remote boot server. Then use a TCP/IP-controlled relay/serial-to-TCP converter to reset the target and receive its serial output. @@ -1315,7 +1316,7 @@ from it. ./myos --dhcp-tftp -This is useful when no network infrastructure is in place and +This usage is useful when no network infrastructure is in place, and the target is connected directly to developer's box. =item 4. @@ -1324,7 +1325,7 @@ Create bootable ISO image. novaboot --iso -- script1 script2 -The created ISO image will have ISOLINUX bootloader installed on it +The created ISO image will have ISOLINUX bootloader installed on it, and the boot menu will allow selecting between I and I configurations. @@ -1332,9 +1333,9 @@ I configurations. =head1 PHASES AND OPTIONS -Novaboot performs its work in several phases. Each phase can be -influenced by several command line options, certain phases can be -skipped. The list of phases (in the execution order) is as follows. +Novaboot performs its work in several phases. Command like options +described bellow influence the execution of each phase or allow their +skipping. The list of phases (in the execution order) is as follows. =over @@ -1363,9 +1364,9 @@ command line options that control it. =head2 Configuration reading phase -After starting, novaboot reads configuration files. Their content is -described in section L. By default, -the configuration is read from multiple locations. First from the system +After starting, novaboot reads zero or more configuration files. We +describe their content in section L. By default, the +configuration is read from multiple locations. First from the system configuration directory (F), second from the user configuration file (F<~/.config/novaboot>) and third from F<.novaboot> files along the path to the current directory. Alternatively, a single @@ -1387,15 +1388,15 @@ Finally, novaboot searches for files named F<.novaboot> starting from the directory of the novaboot script (or working directory, see bellow) and continuing upwards up to the root directory. The found configuration files are then read in the opposite order (i.e. from the -root directory downwards). This allows having, for example, a project +root directory downwards). This ordering allows having, for example, a project specific configuration in F<~/project/.novaboot>. Note the difference between F<~/.config/novaboot> and F<~/.novaboot>. -The former one is read always, whereas the latter only when novaboot +The former one is always read, whereas the latter only when novaboot script or working directory is under the C<$HOME> directory. In certain cases, the location of the novaboot script cannot be -determined in this early phase. This happens either when the script is +determined in this early phase. This situation happens either when the script is read from the standard input or when novaboot is invoked explicitly as in the example L above. In this case, the current working directory is used as a starting point for configuration file search @@ -1430,7 +1431,7 @@ options stored in the C<%targets> configuration variable under key I. See also L. When this option is not given, novaboot tries to determine the target -to use from either B environment variable or from +to use from either B environment variable or B<$default_target> configuration file variable. =back @@ -1444,13 +1445,13 @@ used in the later phases. =item -a, --append=I -Append a string to the first C line in the novaboot script. This +Append a string to the first C line in the novaboot script. This option can be used to append parameters to the kernel's or root task's command line. This option can appear multiple times. =item -b, --bender -Use L +Use L chainloader. Bender scans the PCI bus for PCI serial ports and stores the information about them in the BIOS data area for use by the kernel. @@ -1474,7 +1475,7 @@ script with F. =item --scriptmod=I -When novaboot script is read, I is executed for every +When novaboot reads the script, I is executed for every line (in $_ variable). For example, C replaces every occurrence of I in the script with I. @@ -1492,7 +1493,7 @@ In this phase, files needed for booting are generated in a so-called I (see L). In most cases configuration for a bootloader is generated automatically by novaboot. It is also possible to generate other files using I or I<"<"> syntax in -novaboot scripts. Finally, binaries can be generated in this phases by +novaboot scripts. Finally, novaboot can generate binaries in this phases by running C or C. =over 8 @@ -1543,7 +1544,7 @@ specified F is used. The content of the menu entry can be customized with B<--grub-preamble>, B<--grub2-prolog> or B<--grub_prefix> options. -In order to use the generated menu entry on your development +To use the generated menu entry on your development machine that uses GRUB2, append the following snippet to F file and regenerate your grub configuration, i.e. run update-grub on Debian/Ubuntu. @@ -1554,7 +1555,7 @@ i.e. run update-grub on Debian/Ubuntu. =item --grub2-prolog=I -Specifies text that is put at the beginning of the GRUB2 menu entry. +Specifies the text that novaboot puts at the beginning of the GRUB2 menu entry. =item -m, --make[=make command] @@ -1569,7 +1570,7 @@ server directory where the boot files are copied to. =item --no-file-gen Do not run external commands to generate files (i.e. "<" syntax and -C keyword). This switch does not influence generation of files +C keyword). This switch does not influence the generation of files specified with "< parameter. If +The hostname or (IP address) is given by the I parameter. If the I is not specified, environment variable AMT_PASSWORD is used. The I specifies a TCP port for SOL. If not specified, the -default is 16992. Default I is admin. +default is 16992. The default I is admin. =item --iprelay=I Use TCP/IP relay and serial port to access the target's serial port -and powercycle it. The IP address of the relay is given by I -parameter. If I is not specified, it defaults to 23. +and powercycle it. The I parameter specifies the IP address of +the relay. If I is not specified, it defaults to 23. Note: This option is supposed to work with HWG-ER02a IP relays. @@ -1641,7 +1642,9 @@ example C. =item --remote-expect=I Wait for reception of I after establishing the remote -connection. +connection. This option is needed when novaboot should wait for +confirmation before deploying files to the target, e.g. to not +overwrite other user's files when they are using the target. =item --remote-expect-silent=I @@ -1669,7 +1672,7 @@ directly connected by a plain Ethernet cable to your workstation. The DHCP and TFTP servers require root privileges and C uses C command to obtain those. You can put the following to I to allow running the necessary commands without asking -for password. +for a password. Cmnd_Alias NOVABOOT = /bin/ip a add 10.23.23.1/24 dev eth0, /bin/ip l set dev eth0 up, /usr/sbin/dhcpd -d -cf dhcpd.conf -lf dhcpd.leases -pf dhcpd.pid, /usr/sbin/in.tftpd --listen --secure -v -v -v --pidfile tftpd.pid *, /usr/bin/touch dhcpd.leases, /usr/bin/pkill --pidfile=dhcpd.pid, /usr/bin/pkill --pidfile=tftpd.pid your_login ALL=NOPASSWD: NOVABOOT @@ -1681,7 +1684,7 @@ B<--dhcp-tftp> except that DHCP server is not started. The TFTP server requires root privileges and C uses C command to obtain those. You can put the following to I -to allow running the necessary commands without asking for password. +to allow running the necessary commands without asking for a password. Cmnd_Alias NOVABOOT = /usr/sbin/in.tftpd --listen --secure -v -v -v --pidfile tftpd.pid *, /usr/bin/pkill --pidfile=tftpd.pid your_login ALL=NOPASSWD: NOVABOOT @@ -1692,8 +1695,8 @@ Port to run the TFTP server on. Implies B<--tftp>. =item --netif=I -Network interface used to deploy files to the target. Default value is -I. This influences the configuration of the DHCP server started +Network interface used to deploy files to the target. The default value is +I. This option influences the configuration of the DHCP server started by B<--dhcp-tftp> and the value that B<$NB_MYIP> get replaced with during U-Boot conversation. @@ -1712,7 +1715,7 @@ novaboot script (see also B<--name>). =item --rsync-flags=I -Specifies which I are appended to F command line when +Specifies I to append to F command line when copying files as a result of I<--server> option. =item --concat @@ -1766,7 +1769,7 @@ Replace the default qemu flags (QEMU_FLAGS variable or C<-cpu coreduo =item --reset-cmd=I -Command that resets the target. +Runs command I to reset the target. =item --reset-send=I @@ -1871,7 +1874,7 @@ sequence to exit novaboot. =item --no-interaction, --interaction Skip resp. force target interaction phase. When skipped, novaboot exits -immediately when boot is initiated. +immediately after the boot is initiated. =item --expect=I