From 2d52e9427d3b431317d0eb314f50da200c8368de Mon Sep 17 00:00:00 2001 From: Thomas Schmitt Date: Mon, 5 Mar 2012 10:32:03 +0000 Subject: [PATCH] Changed xorriso.texi according to proposals by Tony Mancill --- xorriso/man_xorriso_to_html.sh | 2 +- xorriso/xorriso.1 | 125 +++++++-------- xorriso/xorriso.info | 269 +++++++++++++++++---------------- xorriso/xorriso.texi | 137 +++++++++-------- 4 files changed, 272 insertions(+), 261 deletions(-) diff --git a/xorriso/man_xorriso_to_html.sh b/xorriso/man_xorriso_to_html.sh index a9a0d3b3..14953732 100755 --- a/xorriso/man_xorriso_to_html.sh +++ b/xorriso/man_xorriso_to_html.sh @@ -62,7 +62,7 @@ then -e 's/Command processing:<\/b>/\ 
<\/A>Command processing:<\/b>/' \ -e 's/Dialog, Readline, Result pager:<\/b>/\ 
<\/ADialog, Readline, Result pager:<\/b>/' \ -e 's/Execution order of program arguments:<\/b>/\ 
<\/A>Execution order of program arguments:<\/b>
\ 
/' \ - -e 's/Aquiring source and target drive:<\/b>/\ 
<\/A>Aquiring source and target drive:<\/b>
\ 
/' \ + -e 's/Acquiring source and target drive:<\/b>/\ 
<\/A>Acquiring source and target drive:<\/b>
\ 
/' \ -e 's/Influencing the behavior of image/\ 
<\/A>Influencing the behavior of image/' \ -e 's/Inserting files into ISO image:<\/b>/\ 
<\/A>Inserting files into ISO image:<\/b>
\ 
/' \ -e 's/Settings for file insertion:<\/b>/\ 
<\/A>Settings for file insertion:<\/b>
\ 
/' \ diff --git a/xorriso/xorriso.1 b/xorriso/xorriso.1 index cefaade1..b2cff449 100644 --- a/xorriso/xorriso.1 +++ b/xorriso/xorriso.1 @@ -454,70 +454,71 @@ is among them. .br Commands consist of a command word, followed by zero or more parameter words. If the list of parameter words -is of variable length (indicated by "[...]" or "[***]") then it has to be -terminated by either the \fBlist delimiter\fR, or the end of argument list, -or an end of an input line. +is of variable length (indicated by "[...]" or "[***]") then it must be +terminated by either the \fBlist delimiter\fR, occur at the end of +the argument list, or occur at the end of an input line. .PP -At program start the list delimiter is the word "\-\-". -This may be changed by option \-list_delimiter in order to allow -"\-\-" as parameter in a list of variable length. -It is advised to reset the delimiter to "\-\-" immediately -afterwards. +At program start the list delimiter is the string "\-\-". +This may be changed with the \-list_delimiter option in order to allow +"\-\-" as parameter in a variable length list. +However, it is advised to reset the delimiter to "\-\-" +immediately afterwards. .br For brevity the list delimiter is referred as "\-\-" throughout this text. .br -The list delimiter is silently tolerated if it appears after the parameters of +The list delimiter is silently ignored if it appears after the parameters of a command with a fixed list length. It is handled as normal text if it appears among the parameters of such a command. .PP \fBPattern expansion\fR converts a list of pattern words into a list of existing file addresses. -Unmatched pattern words appear themselves in that result list, though. +Unmatched pattern words will appear unaltered in that result list. .br Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]' -and respects '/' as separator which may only be matched literally. +and respects '/' as the path separator, which may only be matched literally. .br -It is a property of some particular commands and not a general -feature. It gets controlled by commands \-iso_rr_pattern and \-disk_pattern. -Commands which may use pattern expansion all have variable parameter -lists which are marked in this man page by "[***]" rather than "[...]". +Pattern expansion is a property of some particular commands and not a general +feature. It is controlled by commands \-iso_rr_pattern and \-disk_pattern. +Commands which use pattern expansion all have variable parameter +lists which are specified in this text by "[***]" rather than "[...]". .br Some other commands perform pattern matching unconditionally. .PP -Command and parameter words are either read from program arguments, where one -argument is one word, or from quoted input lines where words are recognized +Command and parameter words are either read from the program arguments, where +one argument is one word, or from quoted input lines where words are recognized similar to the quotation rules of a shell parser. .br -\fBxorriso\fR is not a shell, although it might appear so on first glimpse. +\fBxorriso\fR is not a shell, although it might appear so at first glimpse. Be aware that the interaction of quotation marks and pattern symbols like "*" differs from the usual shell parsers. In \fBxorriso\fR, a quotation mark does not make a pattern symbol literal. .PP \fBQuoted input\fR -converts whitespace separated text pieces into words. +converts whitespace\-separated text into words. The double quotation mark " and the single quotation mark ' can be used to enclose whitespace and make it part of words (e.g. of file names). Each mark type can enclose the marks of the other type. A trailing backslash \\ outside quotations or an open quotation cause the next input line to be appended. .br -Quoted input accepts any ASCII character except NUL (0) as content of quotes. +Quoted input accepts any ASCII character except NUL (0) as the content of +the quotes. Nevertheless it can be cumbersome for the user to produce those characters -at all. Therefore quoted input and program arguments allow optional +directly. Therefore quoted input and program arguments allow optional \fBBackslash Interpretation\fR -which can represent all ASCII characters except NUL (0) by backslash codes +which can represent all ASCII characters except NUL (0) via backslash codes as in $'...' of bash. .br -It is not enabled by default. See option \-backslash_codes. +This is not enabled by default. See option \-backslash_codes. .PP When the program starts then it first looks for argument \-no_rc. If this is not present then it looks for its startup files and reads their content as command input lines. Then it interprets the program arguments as commands and parameters. Finally it enters -dialog mode if command \-dialog "on" was executed up to then. +dialog mode if command \-dialog "on" has been executed by this point. .PP The program ends either by command \-end, or by the end of program arguments -if not dialog was enabled up to that moment, or by a problem +if dialog mode has not been enabled at that point, or by a problem event which triggers the threshold of command \-abort_on. .SS .B Dialog, Readline, Result pager: @@ -526,39 +527,39 @@ Dialog mode prompts for a quoted input line, parses it into words, and performs them as commands with their parameters. It provides assisting services to make dialog more comfortable. .PP -Readline is an enhancement for the input line. You may know it already from +Readline is an enhancement for the input line. You may already know it from the bash shell. Whether it is available in \fBxorriso\fR depends on the availability of package readline\-dev at the time when \fBxorriso\fR was built from its sourcecode. .br -It allows to move the cursor over the text in the line by help of the -Leftward and the Rightward arrow key. +Readline allows to move the cursor over the text in the line by help of the +Left and the Right arrow keys. Text may be inserted at the cursor position. The Delete key removes the -character under the cursor. Upward and Downward arrow keys navigate through +character under the cursor. Up and Down arrow keys navigate through the history of previous input lines. .br See man readline for more info about libreadline. .PP Option \-page activates a built\-in result text pager which may be convenient in -dialog. After an action has put out the given number of terminal lines, +dialog mode. After an action has output the given number of terminal lines, the pager prompts the user for a line of input. .br -An empty line lets \fBxorriso\fR resume work until the next page is put out. +An empty line lets \fBxorriso\fR resume work until the next page is output. .br The single character "@" disables paging for the current action. .br -"@@@", "x", "q", "X", or "Q" urge the current action to abort and suppress -further result output. +"@@@", "x", "q", "X", or "Q" request that the current action aborts and +suppress further result output. .br -Any other line will be interpreted as new dialog line. The current action -is urged to abort. Afterwards, the input line is executed. +Any other line input will be interpreted as new dialog line. The current action +is requested to abort. Afterwards, the input line is executed. .PP Some actions apply paging to their info output, too. .br -The urge to abort may or may not be obeyed by the current action. All actions -try to abort as soon as possible. +The request to abort may or may not be obeyed by the current action. +All actions try to abort as soon as possible. .br .SH OPTIONS .br @@ -576,35 +577,37 @@ sequence of commands which get performed exactly in the given order. This requires the user to write commands for desired settings before the commands which shall be influenced by those settings. .br -Many other programs allow to hand over options as program arguments -in an arbitrary sequence and perform settings and actions in a sequence -of their own discretion. xorriso provides an option to enable such a behavior -at the cost of losing freedom of expression. +Many other programs support program arguments in an arbitrary ordering +and perform settings and actions in a sequence at their own discretion. +xorriso provides an option to enable such a behavior +at the cost of loss of expressivity. .TP \fB\-x\fR -Enable automatic sorting of program arguments to a sequence that most likely -makes some sense. This command may be given at any position among the commands +Enable automatic sorting of program arguments into a sequence that +(most likely) is sensible. +This command may be given at any position among the commands which are handed over as program arguments. .br -It works only if it is given as program argument, and with a single dash. -I.e. not in startup files, not with \-options_from_file, not in dialog mode, -not as "x" and not as "\-\-x". It affects only the commands given -as program arguments. +Note: It works only if it is given as program argument and +with a single dash (i.e. "\-x"). It will not work in startup files, nor with +\-options_from_file, nor in dialog mode, nor as "x" and finally not as +"\-\-x". +It affects only the commands given as program arguments. .TP \fB\-list_arg_sorting\fR List all xorriso commands in the order which applies if option \-x is in effect. .br -This list may also be helpful without \-x, for a user who ponders over the -sequence in which to put commands. Deviations from the sorting order may +This list may also be helpful without \-x for a user who ponders over the +sequence in which to put commands. Deviations from the listed sorting order may well make sense, though. .PP .TP -.B Aquiring source and target drive: +.B Acquiring source and target drive: .PP -The effect of aquiring a drive may depend on several options in the +The effect of acquiring a drive may depend on several options in the next paragraph "Influencing the behavior of image loading". If desired, their enabling commands have to be performed before the -commands which aquire the drive. +commands which acquire the drive. .TP \fB\-dev\fR address Set input and output drive to the same address and load an ISO image if it @@ -620,7 +623,7 @@ Special address string "\-" means standard output, to which several restrictions apply. See above paragraph "Libburn drives". .br An empty address string "" gives up the current device -without aquiring a new one. +without acquiring a new one. .TP \fB\-indev\fR address Set input drive and load an ISO image if present. @@ -644,7 +647,7 @@ Special address string "\-" means standard output, to which several restrictions apply. See above paragraph "Libburn drives". .br An empty address string "" gives up the current output drive -without aquiring a new one. No writing is possible without an output drive. +without acquiring a new one. No writing is possible without an output drive. .TP \fB\-grow_blindly\fR "off"|predicted_nwa If predicted_nwa is a non\-negative number then perform blind growing rather @@ -664,7 +667,7 @@ begins. The output drive is given up when writing is done. .B Influencing the behavior of image loading: .PP The following options should normally be performed before loading an image -by aquiring an input drive. In rare cases it is desirable to activate +by acquiring an input drive. In rare cases it is desirable to activate them only after image loading. .TP \fB\-load\fR entity id @@ -700,7 +703,7 @@ for which the image was prepared. This affects only loading of ISO images and reading of their files. The multi\-session method of growing is not allowed as long as \-displacement is non\-zero. I.e. \-indev and \-outdev must be different. The displacement gets reset to 0 before the drive -gets re\-aquired after writing. +gets re\-acquired after writing. .br Examples: .br @@ -910,7 +913,7 @@ can hamper reading of partly damaged media. Setting "off:emul_off" disables the elsewise trustworthy table\-of\-content scan for those media. .br To be in effect, the \-rom_toc_scan setting has to be made before the \-*dev -command which aquires drive and medium. +command which acquires drive and medium. .TP \fB\-calm_drive\fR "in"|"out"|"all"|"revoke"|"on"|"off" Reduce drive noise until it is actually used again. Some drives stay alert @@ -2153,7 +2156,7 @@ and eventually override the list of other speed offers. Try to close the upcomming track and session if the drive reported the medium as damaged. This may apply to CD\-R, CD\-RW, DVD\-R, DVD\-RW, DVD+R, DVD+R DL, or BD\-R media. It is indicated by warning messages when the drive gets -aquired, and by a remark "but next track is damaged" with the line +acquired, and by a remark "but next track is damaged" with the line "Media status :" of command \-toc. .br The setting of option \-close determines whether the medium stays appendable. @@ -3922,7 +3925,7 @@ The scope is only a single data track per session to be written to blank, overwriteable, or appendable media. The medium gets closed if closing is applicable and not option \-multi is present. .br -If an input drive was aquired, then it is given up. +If an input drive was acquired, then it is given up. This is only allowed if no image changes are pending. .br dev= must be given as \fBxorriso\fR device address. Addresses like 0,0,0 @@ -4269,7 +4272,7 @@ $ xorriso \-device_links 2 \-dev '/dev/cdrw3' rwrw\-\- : 'HL\-DT\-ST' 'BDDVDRW_GGC\-H20L' .SS .B Blank medium and compose a new ISO image as batch run -Aquire drive /dev/sr2, make medium ready for writing a new image, +Acquire drive /dev/sr2, make medium ready for writing a new image, fill the image with the files from hard disk directories /home/me/sounds and /home/me/pictures. .br @@ -4404,7 +4407,7 @@ $ xorriso \-dev /dev/sr2 \\ .SS .B Copy modified ISO image from one medium to another Load image from input drive. Do the same manipulations as in the previous -example. Aquire output drive and blank it. Burn the modified image as +example. Acquire output drive and blank it. Burn the modified image as first and only session to the output drive. .br $ xorriso \-indev /dev/sr2 \\ diff --git a/xorriso/xorriso.info b/xorriso/xorriso.info index 3866bbec..a7e9971e 100644 --- a/xorriso/xorriso.info +++ b/xorriso/xorriso.info @@ -396,60 +396,64 @@ influence following actions. So their sequence does matter, unless they are given as program arguments and option *-x* is among them. Commands consist of a command word, followed by zero or more parameter words. If the list of parameter words is of variable length (indicated -by "[...]" or "[***]") then it has to be terminated by either the *list -delimiter*, or the end of argument list, or an end of an input line. +by "[...]" or "[***]") then it must be terminated by either the *list +delimiter*, occur at the end of the argument list, or occur at the end +of an input line. - At program start the list delimiter is the word "--". This may be -changed by option -list_delimiter in order to allow "--" as parameter -in a list of variable length. It is advised to reset the delimiter to -"--" immediately afterwards. + At program start the list delimiter is the string "--". This may be +changed with the -list_delimiter option in order to allow "--" as +parameter in a variable length list. However, it is advised to reset +the delimiter to "--" immediately afterwards. For brevity the list delimiter is referred as "--" throughout this text. -The list delimiter is silently tolerated if it appears after the +The list delimiter is silently ignored if it appears after the parameters of a command with a fixed list length. It is handled as normal text if it appears among the parameters of such a command. *Pattern expansion* converts a list of pattern words into a list of -existing file addresses. Unmatched pattern words appear themselves in -that result list, though. +existing file addresses. Unmatched pattern words will appear unaltered +in that result list. Pattern matching supports the usual shell parser wildcards '*' '?' -'[xyz]' and respects '/' as separator which may only be matched -literally. -It is a property of some particular commands and not a general feature. -It gets controlled by commands -iso_rr_pattern and -disk_pattern. -Commands which may use pattern expansion all have variable parameter -lists which are marked in this man page by "[***]" rather than "[...]". +'[xyz]' and respects '/' as the path separator, which may only be +matched literally. +Pattern expansion is a property of some particular commands and not a +general feature. It is controlled by commands -iso_rr_pattern and +-disk_pattern. Commands which use pattern expansion all have variable +parameter lists which are specified in this text by "[***]" rather than +"[...]". Some other commands perform pattern matching unconditionally. - Command and parameter words are either read from program arguments, -where one argument is one word, or from quoted input lines where words -are recognized similar to the quotation rules of a shell parser. -`xorriso' is not a shell, although it might appear so on first glimpse. + Command and parameter words are either read from the program +arguments, where one argument is one word, or from quoted input lines +where words are recognized similar to the quotation rules of a shell +parser. +`xorriso' is not a shell, although it might appear so at first glimpse. Be aware that the interaction of quotation marks and pattern symbols like "*" differs from the usual shell parsers. In `xorriso', a quotation mark does not make a pattern symbol literal. - *Quoted input* converts whitespace separated text pieces into words. -The double quotation mark " and the single quotation mark ' can be used -to enclose whitespace and make it part of words (e.g. of file names). -Each mark type can enclose the marks of the other type. A trailing -backslash \ outside quotations or an open quotation cause the next -input line to be appended. -Quoted input accepts any ASCII character except NUL (0) as content of -quotes. Nevertheless it can be cumbersome for the user to produce -those characters at all. Therefore quoted input and program arguments -allow optional *Backslash Interpretation* which can represent all ASCII -characters except NUL (0) by backslash codes as in $'...' of bash. -It is not enabled by default. See option -backslash_codes. + *Quoted input* converts whitespace-separated text into words. The +double quotation mark " and the single quotation mark ' can be used to +enclose whitespace and make it part of words (e.g. of file names). Each +mark type can enclose the marks of the other type. A trailing backslash +\ outside quotations or an open quotation cause the next input line to +be appended. +Quoted input accepts any ASCII character except NUL (0) as the content +of the quotes. Nevertheless it can be cumbersome for the user to +produce those characters directly. Therefore quoted input and program +arguments allow optional *Backslash Interpretation* which can represent +all ASCII characters except NUL (0) via backslash codes as in $'...' of +bash. +This is not enabled by default. See option -backslash_codes. When the program starts then it first looks for argument -no_rc. If this is not present then it looks for its startup files and reads their content as command input lines. Then it interprets the program arguments as commands and parameters. Finally it enters dialog mode if -command -dialog "on" was executed up to then. +command -dialog "on" has been executed by this point. The program ends either by command -end, or by the end of program -arguments if not dialog was enabled up to that moment, or by a problem -event which triggers the threshold of command -abort_on. +arguments if dialog mode has not been enabled at that point, or by a +problem event which triggers the threshold of command -abort_on.  File: xorriso.info, Node: Dialog, Next: Options, Prev: Processing, Up: Top @@ -461,30 +465,30 @@ Dialog mode prompts for a quoted input line, parses it into words, and performs them as commands with their parameters. It provides assisting services to make dialog more comfortable. - Readline is an enhancement for the input line. You may know it -already from the bash shell. Whether it is available in `xorriso' -depends on the availability of package readline-dev at the time when -`xorriso' was built from its sourcecode. -It allows to move the cursor over the text in the line by help of the -Leftward and the Rightward arrow key. Text may be inserted at the -cursor position. The Delete key removes the character under the cursor. -Upward and Downward arrow keys navigate through the history of previous -input lines. + Readline is an enhancement for the input line. You may already know +it from the bash shell. Whether it is available in `xorriso' depends on +the availability of package readline-dev at the time when `xorriso' was +built from its sourcecode. +Readline allows to move the cursor over the text in the line by help of +the Left and the Right arrow keys. Text may be inserted at the cursor +position. The Delete key removes the character under the cursor. Up and +Down arrow keys navigate through the history of previous input lines. See info readline for more info about libreadline. Option -page activates a built-in result text pager which may be -convenient in dialog. After an action has put out the given number of -terminal lines, the pager prompts the user for a line of input. -An empty line lets `xorriso' resume work until the next page is put out. +convenient in dialog mode. After an action has output the given number +of terminal lines, the pager prompts the user for a line of input. +An empty line lets `xorriso' resume work until the next page is output. The single character "@" disables paging for the current action. -"@@@", "x", "q", "X", or "Q" urge the current action to abort and +"@@@", "x", "q", "X", or "Q" request that the current action aborts and suppress further result output. -Any other line will be interpreted as new dialog line. The current -action is urged to abort. Afterwards, the input line is executed. +Any other line input will be interpreted as new dialog line. The +current action is requested to abort. Afterwards, the input line is +executed. Some actions apply paging to their info output, too. -The urge to abort may or may not be obeyed by the current action. All -actions try to abort as soon as possible. +The request to abort may or may not be obeyed by the current action. +All actions try to abort as soon as possible.  File: xorriso.info, Node: Options, Next: Examples, Prev: Dialog, Up: Top @@ -501,7 +505,7 @@ inner dashes are interpreted as underscores. * Menu: * ArgSort:: Execution order of program arguments -* AqDrive:: Aquiring source and target drive +* AqDrive:: Acquiring source and target drive * Loading:: Influencing the behavior of image loading * Insert:: Inserting files into ISO image * SetInsert:: Settings for file insertion @@ -533,38 +537,39 @@ By default the program arguments of a xorriso run are interpreted as a sequence of commands which get performed exactly in the given order. This requires the user to write commands for desired settings before the commands which shall be influenced by those settings. -Many other programs allow to hand over options as program arguments in -an arbitrary sequence and perform settings and actions in a sequence of -their own discretion. xorriso provides an option to enable such a -behavior at the cost of losing freedom of expression. +Many other programs support program arguments in an arbitrary ordering +and perform settings and actions in a sequence at their own discretion. +xorriso provides an option to enable such a behavior at the cost of +loss of expressivity. -x - Enable automatic sorting of program arguments to a sequence that - most likely makes some sense. This command may be given at any + Enable automatic sorting of program arguments into a sequence that + (most likely) is sensible. This command may be given at any position among the commands which are handed over as program arguments. - It works only if it is given as program argument, and with a - single dash. I.e. not in startup files, not with - -options_from_file, not in dialog mode, not as "x" and not as - "--x". It affects only the commands given as program arguments. + Note: It works only if it is given as program argument and with a + single dash (i.e. "-x"). It will not work in startup files, nor + with -options_from_file, nor in dialog mode, nor as "x" and + finally not as "--x". It affects only the commands given as + program arguments. -list_arg_sorting List all xorriso commands in the order which applies if option -x is in effect. - This list may also be helpful without -x, for a user who ponders + This list may also be helpful without -x for a user who ponders over the sequence in which to put commands. Deviations from the - sorting order may well make sense, though. + listed sorting order may well make sense, though.  File: xorriso.info, Node: AqDrive, Next: Loading, Prev: ArgSort, Up: Options -9.2 Aquiring source and target drive -==================================== +9.2 Acquiring source and target drive +===================================== -The effect of aquiring a drive may depend on several options in the +The effect of acquiring a drive may depend on several options in the next paragraph "Influencing the behavior of image loading". If desired, their enabling commands have to be performed before the -commands which aquire the drive. +commands which acquire the drive. -dev address Set input and output drive to the same address and load an ISO @@ -576,7 +581,7 @@ commands which aquire the drive. Special address string "-" means standard output, to which several restrictions apply. See above paragraph "Libburn drives". An empty address string "" gives up the current device without - aquiring a new one. + acquiring a new one. -indev address Set input drive and load an ISO image if present. If the new @@ -597,7 +602,7 @@ commands which aquire the drive. Special address string "-" means standard output, to which several restrictions apply. See above paragraph "Libburn drives". An empty address string "" gives up the current output drive - without aquiring a new one. No writing is possible without an + without acquiring a new one. No writing is possible without an output drive. -grow_blindly "off"|predicted_nwa @@ -622,7 +627,7 @@ File: xorriso.info, Node: Loading, Next: Insert, Prev: AqDrive, Up: Options ============================================= The following options should normally be performed before loading an -image by aquiring an input drive. In rare cases it is desirable to +image by acquiring an input drive. In rare cases it is desirable to activate them only after image loading. -load entity id @@ -655,7 +660,7 @@ activate them only after image loading. images and reading of their files. The multi-session method of growing is not allowed as long as -displacement is non-zero. I.e. -indev and -outdev must be different. The displacement gets reset - to 0 before the drive gets re-aquired after writing. + to 0 before the drive gets re-acquired after writing. Examples: If a track of a CD starts at block 123456 and gets copied to a disk file where it begins at block 0, then this copy can be loaded @@ -847,7 +852,7 @@ activate them only after image loading. Setting "off:emul_off" disables the elsewise trustworthy table-of-content scan for those media. To be in effect, the -rom_toc_scan setting has to be made before - the -*dev command which aquires drive and medium. + the -*dev command which acquires drive and medium. -calm_drive "in"|"out"|"all"|"revoke"|"on"|"off" Reduce drive noise until it is actually used again. Some drives @@ -1921,7 +1926,7 @@ File: xorriso.info, Node: Writing, Next: SetWrite, Prev: Filter, Up: Options Try to close the upcomming track and session if the drive reported the medium as damaged. This may apply to CD-R, CD-RW, DVD-R, DVD-RW, DVD+R, DVD+R DL, or BD-R media. It is indicated by warning - messages when the drive gets aquired, and by a remark "but next + messages when the drive gets acquired, and by a remark "but next track is damaged" with the line "Media status :" of command -toc. The setting of option -close determines whether the medium stays appendable. @@ -3453,7 +3458,7 @@ said programs trigger comparable actions. The scope is only a single data track per session to be written to blank, overwriteable, or appendable media. The medium gets closed if closing is applicable and not option -multi is present. - If an input drive was aquired, then it is given up. This is only + If an input drive was acquired, then it is given up. This is only allowed if no image changes are pending. dev= must be given as `xorriso' device address. Addresses like 0,0,0 or ATA:1,1,0 are not supported. @@ -3757,7 +3762,7 @@ File: xorriso.info, Node: ExCreate, Next: ExDialog, Prev: ExDevices, Up: Exa 10.2 Blank medium and compose a new ISO image as batch run ========================================================== -Aquire drive /dev/sr2, make medium ready for writing a new image, fill +Acquire drive /dev/sr2, make medium ready for writing a new image, fill the image with the files from hard disk directories /home/me/sounds and /home/me/pictures. Because no -dialog "on" is given, the program will then end by writing @@ -3862,7 +3867,7 @@ File: xorriso.info, Node: ExModifying, Next: ExBootable, Prev: ExGrowing, Up ======================================================= Load image from input drive. Do the same manipulations as in the -previous example. Aquire output drive and blank it. Burn the modified +previous example. Acquire output drive and blank it. Burn the modified image as first and only session to the output drive. $ xorriso -indev /dev/sr2 \ @@ -4362,7 +4367,7 @@ File: xorriso.info, Node: CommandIdx, Next: ConceptIdx, Prev: Legal, Up: Top * -cpr inserts like with cp -r: Insert. (line 152) * -cpx copies files to disk: Restore. (line 92) * -cut_out inserts piece of data file: Insert. (line 126) -* -dev aquires one drive for input and output: AqDrive. (line 12) +* -dev acquires one drive for input and output: AqDrive. (line 12) * -device_links gets list of drives: Inquiry. (line 18) * -devices gets list of drives: Inquiry. (line 7) * -dialog enables dialog mode: DialogCtl. (line 7) @@ -4406,11 +4411,11 @@ File: xorriso.info, Node: CommandIdx, Next: ConceptIdx, Prev: Legal, Up: Top * -hide excludes file names from directory trees: Manip. (line 171) * -history brings text into readline history: Scripting. (line 44) * -in_charset sets input character set: Loading. (line 91) -* -indev aquires a drive for input: AqDrive. (line 24) +* -indev acquires a drive for input: AqDrive. (line 24) * -iso_rr_pattern controls pattern expansion: Manip. (line 10) * -jigdo clears JTE or or adds parameter to JTE: Jigdo. (line 33) * -joliet enables production of Joliet tree: SetWrite. (line 10) -* -list_arg_sorting prints sorting order of -x: ArgSort. (line 26) +* -list_arg_sorting prints sorting order of -x: ArgSort. (line 27) * -list_delimiter replaces '--': Scripting. (line 60) * -list_extras lists compile time extra features: Scripting. (line 26) @@ -4446,7 +4451,7 @@ File: xorriso.info, Node: CommandIdx, Next: ConceptIdx, Prev: Legal, Up: Top * -options_from_file reads commands from file: Scripting. (line 12) * -osirrox enables ISO-to-disk copying: Restore. (line 18) * -out_charset sets output character set: SetWrite. (line 189) -* -outdev aquires a drive for output: AqDrive. (line 31) +* -outdev acquires a drive for output: AqDrive. (line 31) * -overwrite enables overwriting in ISO: SetInsert. (line 127) * -pacifier controls pacifier text form: Emulation. (line 158) * -padding sets amount or mode of image padding: SetWrite. (line 272) @@ -4539,7 +4544,7 @@ File: xorriso.info, Node: ConceptIdx, Prev: CommandIdx, Up: Top * Appendable media, _definition: Media. (line 38) * Appended Filesystem Image, -append_partition: Bootable. (line 199) * Automatic execution order, of options, -x: ArgSort. (line 16) -* Backslash Interpretation, _definition: Processing. (line 49) +* Backslash Interpretation, _definition: Processing. (line 52) * Backup, enable fast incremental, -disk_dev_ino: Loading. (line 189) * Backup, enable features, -for_backup: Loading. (line 184) * Backup, scdbackup checksum tag, -scdbackup: Emulation. (line 168) @@ -4689,7 +4694,7 @@ File: xorriso.info, Node: ConceptIdx, Prev: CommandIdx, Up: Top * Partition offset, _definiton: Bootable. (line 146) * Partition table, _definiton: Bootable. (line 128) * Pathspec, _definition: SetInsert. (line 120) -* Pattern expansion, _definition: Processing. (line 23) +* Pattern expansion, _definition: Processing. (line 24) * Pattern expansion, for disk paths, -disk_pattern: Insert. (line 31) * Pattern expansion, for ISO paths, -iso_rr_pattern: Manip. (line 10) * Permissions, in ISO image, -chmod: Manip. (line 58) @@ -4724,7 +4729,7 @@ File: xorriso.info, Node: ConceptIdx, Prev: CommandIdx, Up: Top * Program, show current settings, -status: Scripting. (line 47) * Program, status history, -status_history_max: Scripting. (line 56) * Program, wait a time span, -sleep: Scripting. (line 114) -* Quoted input, _definiton: Processing. (line 43) +* Quoted input, _definiton: Processing. (line 46) * Recovery, retrieve blocks, -check_media: Verify. (line 21) * Rename, in ISO image, -mv: Manip. (line 35) * Restore, copy file into disk file, -paste_in: Restore. (line 121) @@ -4745,7 +4750,7 @@ File: xorriso.info, Node: ConceptIdx, Prev: CommandIdx, Up: Top * Session, mount command line, -mount_cmd: Inquiry. (line 41) * Session, mount parameters, -mount_opts: Inquiry. (line 57) * Session, select as input, -load: Loading. (line 11) -* Sorting order, for -x, -list_arg_sorting: ArgSort. (line 26) +* Sorting order, for -x, -list_arg_sorting: ArgSort. (line 27) * SUN Disk Label, production: Bootable. (line 187) * SUN SPARC boot images, activation: Bootable. (line 220) * System area, _definiton: Bootable. (line 121) @@ -4797,52 +4802,52 @@ Node: Methods8817 Node: Drives11386 Node: Extras14699 Node: Processing18417 -Node: Dialog21964 -Node: Options23627 -Node: ArgSort25296 -Node: AqDrive26771 -Node: Loading29808 -Node: Insert44077 -Node: SetInsert53787 -Node: Manip62358 -Node: CmdFind71091 -Node: Filter83198 -Node: Writing87753 -Node: SetWrite96712 -Node: Bootable111017 -Node: Jigdo124238 -Node: Charset128484 -Node: Exception131243 -Node: DialogCtl137356 -Node: Inquiry139951 -Node: Navigate144814 -Node: Verify153074 -Node: Restore161741 -Node: Emulation168647 -Node: Scripting178446 -Node: Frontend185598 -Node: Examples186898 -Node: ExDevices188075 -Node: ExCreate188734 -Node: ExDialog190017 -Node: ExGrowing191280 -Node: ExModifying192085 -Node: ExBootable192588 -Node: ExCharset193140 -Node: ExPseudo193960 -Node: ExCdrecord194858 -Node: ExMkisofs195175 -Node: ExGrowisofs196515 -Node: ExException197650 -Node: ExTime198104 -Node: ExIncBackup198563 -Node: ExRestore202549 -Node: ExRecovery203509 -Node: Files204079 -Node: Seealso205377 -Node: Bugreport206100 -Node: Legal206681 -Node: CommandIdx207611 -Node: ConceptIdx222926 +Node: Dialog22034 +Node: Options23710 +Node: ArgSort25380 +Node: AqDrive26869 +Node: Loading29912 +Node: Insert44184 +Node: SetInsert53894 +Node: Manip62465 +Node: CmdFind71198 +Node: Filter83305 +Node: Writing87860 +Node: SetWrite96820 +Node: Bootable111125 +Node: Jigdo124346 +Node: Charset128592 +Node: Exception131351 +Node: DialogCtl137464 +Node: Inquiry140059 +Node: Navigate144922 +Node: Verify153182 +Node: Restore161849 +Node: Emulation168755 +Node: Scripting178555 +Node: Frontend185707 +Node: Examples187007 +Node: ExDevices188184 +Node: ExCreate188843 +Node: ExDialog190127 +Node: ExGrowing191390 +Node: ExModifying192195 +Node: ExBootable192699 +Node: ExCharset193251 +Node: ExPseudo194071 +Node: ExCdrecord194969 +Node: ExMkisofs195286 +Node: ExGrowisofs196626 +Node: ExException197761 +Node: ExTime198215 +Node: ExIncBackup198674 +Node: ExRestore202660 +Node: ExRecovery203620 +Node: Files204190 +Node: Seealso205488 +Node: Bugreport206211 +Node: Legal206792 +Node: CommandIdx207722 +Node: ConceptIdx223037  End Tag Table diff --git a/xorriso/xorriso.texi b/xorriso/xorriso.texi index 9fd70bdf..7432aa2b 100644 --- a/xorriso/xorriso.texi +++ b/xorriso/xorriso.texi @@ -50,7 +50,7 @@ @c man .\" First parameter, NAME, should be all caps @c man .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection @c man .\" other parameters are allowed: see man(7), man(1) -@c man .TH XORRISO 1 "Version 1.2.1, Feb 03, 2012" +@c man .TH XORRISO 1 "Version 1.2.1, Feb 05, 2012" @c man .\" Please adjust this date whenever revising the manpage. @c man .\" @c man .\" Some roff macros, for reference: @@ -599,21 +599,21 @@ is among them. @cindex List delimiter, _definiton Commands consist of a command word, followed by zero or more parameter words. If the list of parameter words -is of variable length (indicated by "[...]" or "[***]") then it has to be -terminated by either the @strong{list delimiter}, or the end of argument list, -or an end of an input line. +is of variable length (indicated by "[...]" or "[***]") then it must be +terminated by either the @strong{list delimiter}, occur at the end of +the argument list, or occur at the end of an input line. @c man .PP @sp 1 -At program start the list delimiter is the word "@minus{}@minus{}". -This may be changed by option -list_delimiter in order to allow -"@minus{}@minus{}" as parameter in a list of variable length. -It is advised to reset the delimiter to "@minus{}@minus{}" immediately -afterwards. +At program start the list delimiter is the string "@minus{}@minus{}". +This may be changed with the -list_delimiter option in order to allow +"@minus{}@minus{}" as parameter in a variable length list. +However, it is advised to reset the delimiter to "@minus{}@minus{}" +immediately afterwards. @* For brevity the list delimiter is referred as "@minus{}@minus{}" throughout this text. @* -The list delimiter is silently tolerated if it appears after the parameters of +The list delimiter is silently ignored if it appears after the parameters of a command with a fixed list length. It is handled as normal text if it appears among the parameters of such a command. @c man .PP @@ -621,24 +621,24 @@ appears among the parameters of such a command. @cindex Pattern expansion, _definition @strong{Pattern expansion} converts a list of pattern words into a list of existing file addresses. -Unmatched pattern words appear themselves in that result list, though. +Unmatched pattern words will appear unaltered in that result list. @* Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]' -and respects '/' as separator which may only be matched literally. +and respects '/' as the path separator, which may only be matched literally. @* -It is a property of some particular commands and not a general -feature. It gets controlled by commands -iso_rr_pattern and -disk_pattern. -Commands which may use pattern expansion all have variable parameter -lists which are marked in this man page by "[***]" rather than "[...]". +Pattern expansion is a property of some particular commands and not a general +feature. It is controlled by commands -iso_rr_pattern and -disk_pattern. +Commands which use pattern expansion all have variable parameter +lists which are specified in this text by "[***]" rather than "[...]". @* Some other commands perform pattern matching unconditionally. @c man .PP @sp 1 -Command and parameter words are either read from program arguments, where one -argument is one word, or from quoted input lines where words are recognized +Command and parameter words are either read from the program arguments, where +one argument is one word, or from quoted input lines where words are recognized similar to the quotation rules of a shell parser. @* -@command{xorriso} is not a shell, although it might appear so on first glimpse. +@command{xorriso} is not a shell, although it might appear so at first glimpse. Be aware that the interaction of quotation marks and pattern symbols like "*" differs from the usual shell parsers. In @command{xorriso}, a quotation mark does not make a pattern symbol literal. @@ -646,32 +646,33 @@ does not make a pattern symbol literal. @sp 1 @cindex Quoted input, _definiton @strong{Quoted input} -converts whitespace separated text pieces into words. +converts whitespace-separated text into words. The double quotation mark " and the single quotation mark ' can be used to enclose whitespace and make it part of words (e.g. of file names). Each mark type can enclose the marks of the other type. A trailing backslash \ outside quotations or an open quotation cause the next input line to be appended. @* @cindex Backslash Interpretation, _definition -Quoted input accepts any ASCII character except NUL (0) as content of quotes. +Quoted input accepts any ASCII character except NUL (0) as the content of +the quotes. Nevertheless it can be cumbersome for the user to produce those characters -at all. Therefore quoted input and program arguments allow optional +directly. Therefore quoted input and program arguments allow optional @strong{Backslash Interpretation} -which can represent all ASCII characters except NUL (0) by backslash codes +which can represent all ASCII characters except NUL (0) via backslash codes as in $'...' of bash. @* -It is not enabled by default. See option -backslash_codes. +This is not enabled by default. See option -backslash_codes. @c man .PP @sp 1 When the program starts then it first looks for argument -no_rc. If this is not present then it looks for its startup files and reads their content as command input lines. Then it interprets the program arguments as commands and parameters. Finally it enters -dialog mode if command -dialog "on" was executed up to then. +dialog mode if command -dialog "on" has been executed by this point. @c man .PP @sp 1 The program ends either by command -end, or by the end of program arguments -if not dialog was enabled up to that moment, or by a problem +if dialog mode has not been enabled at that point, or by a problem event which triggers the threshold of command -abort_on. @c man .SS @node Dialog, Options, Processing, top @@ -683,16 +684,16 @@ them as commands with their parameters. It provides assisting services to make dialog more comfortable. @c man .PP @sp 1 -Readline is an enhancement for the input line. You may know it already from +Readline is an enhancement for the input line. You may already know it from the bash shell. Whether it is available in @command{xorriso} depends on the availability of package readline-dev at the time when @command{xorriso} was built from its sourcecode. @* -It allows to move the cursor over the text in the line by help of the -Leftward and the Rightward arrow key. +Readline allows to move the cursor over the text in the line by help of the +Left and the Right arrow keys. Text may be inserted at the cursor position. The Delete key removes the -character under the cursor. Upward and Downward arrow keys navigate through +character under the cursor. Up and Down arrow keys navigate through the history of previous input lines. @* @c man-ignore-lines 1 @@ -702,24 +703,24 @@ for more info about libreadline. @c man .PP @sp 1 Option -page activates a built-in result text pager which may be convenient in -dialog. After an action has put out the given number of terminal lines, +dialog mode. After an action has output the given number of terminal lines, the pager prompts the user for a line of input. @* -An empty line lets @command{xorriso} resume work until the next page is put out. +An empty line lets @command{xorriso} resume work until the next page is output. @* The single character "@@" disables paging for the current action. @* -"@@@@@@", "x", "q", "X", or "Q" urge the current action to abort and suppress -further result output. +"@@@@@@", "x", "q", "X", or "Q" request that the current action aborts and +suppress further result output. @* -Any other line will be interpreted as new dialog line. The current action -is urged to abort. Afterwards, the input line is executed. +Any other line input will be interpreted as new dialog line. The current action +is requested to abort. Afterwards, the input line is executed. @c man .PP @sp 1 Some actions apply paging to their info output, too. @* -The urge to abort may or may not be obeyed by the current action. All actions -try to abort as soon as possible. +The request to abort may or may not be obeyed by the current action. +All actions try to abort as soon as possible. @node Options, Examples, Dialog, top @chapter Options @c man .br @@ -733,7 +734,7 @@ Normally any number of leading dashes is ignored with command words and inner dashes are interpreted as underscores. @menu * ArgSort:: Execution order of program arguments -* AqDrive:: Aquiring source and target drive +* AqDrive:: Acquiring source and target drive * Loading:: Influencing the behavior of image loading * Insert:: Inserting files into ISO image * SetInsert:: Settings for file insertion @@ -765,49 +766,51 @@ sequence of commands which get performed exactly in the given order. This requires the user to write commands for desired settings before the commands which shall be influenced by those settings. @* -Many other programs allow to hand over options as program arguments -in an arbitrary sequence and perform settings and actions in a sequence -of their own discretion. xorriso provides an option to enable such a behavior -at the cost of losing freedom of expression. +Many other programs support program arguments in an arbitrary ordering +and perform settings and actions in a sequence at their own discretion. +xorriso provides an option to enable such a behavior +at the cost of loss of expressivity. @table @asis @sp 1 @c man .TP @item -x @kindex -x enables automatic execution order of options @cindex Automatic execution order, of options, -x -Enable automatic sorting of program arguments to a sequence that most likely -makes some sense. This command may be given at any position among the commands +Enable automatic sorting of program arguments into a sequence that +(most likely) is sensible. +This command may be given at any position among the commands which are handed over as program arguments. @* -It works only if it is given as program argument, and with a single dash. -I.e. not in startup files, not with -options_from_file, not in dialog mode, -not as "x" and not as "@minus{}@minus{}x". It affects only the commands given -as program arguments. +Note: It works only if it is given as program argument and +with a single dash (i.e. "-x"). It will not work in startup files, nor with +-options_from_file, nor in dialog mode, nor as "x" and finally not as +"@minus{}@minus{}x". +It affects only the commands given as program arguments. @c man .TP @item -list_arg_sorting @kindex -list_arg_sorting prints sorting order of -x @cindex Sorting order, for -x, -list_arg_sorting List all xorriso commands in the order which applies if option -x is in effect. @* -This list may also be helpful without -x, for a user who ponders over the -sequence in which to put commands. Deviations from the sorting order may +This list may also be helpful without -x for a user who ponders over the +sequence in which to put commands. Deviations from the listed sorting order may well make sense, though. @end table @c man .PP @c man .TP @node AqDrive, Loading, ArgSort, Options -@section Aquiring source and target drive -@c man .B Aquiring source and target drive: +@section Acquiring source and target drive +@c man .B Acquiring source and target drive: @c man .PP -The effect of aquiring a drive may depend on several options in the +The effect of acquiring a drive may depend on several options in the next paragraph "Influencing the behavior of image loading". If desired, their enabling commands have to be performed before the -commands which aquire the drive. +commands which acquire the drive. @table @asis @sp 1 @c man .TP @item -dev address -@kindex -dev aquires one drive for input and output +@kindex -dev acquires one drive for input and output @cindex Drive, for input and output, -dev Set input and output drive to the same address and load an ISO image if it is present. @@ -822,10 +825,10 @@ Special address string "-" means standard output, to which several restrictions apply. See above paragraph "Libburn drives". @* An empty address string "" gives up the current device -without aquiring a new one. +without acquiring a new one. @c man .TP @item -indev address -@kindex -indev aquires a drive for input +@kindex -indev acquires a drive for input @cindex Drive, for input, -indev Set input drive and load an ISO image if present. If the new input drive differs @@ -834,7 +837,7 @@ It depends on the setting of -grow_blindly which of both gets activated. The same rules and restrictions apply as with -dev. @c man .TP @item -outdev address -@kindex -outdev aquires a drive for output +@kindex -outdev acquires a drive for output @cindex Drive, for output, -outdev Set output drive and if it differs from the input drive then switch from growing to modifying or to blind growing. Unlike -dev and -indev this action @@ -850,7 +853,7 @@ Special address string "-" means standard output, to which several restrictions apply. See above paragraph "Libburn drives". @* An empty address string "" gives up the current output drive -without aquiring a new one. No writing is possible without an output drive. +without acquiring a new one. No writing is possible without an output drive. @c man .TP @item -grow_blindly "off"|predicted_nwa @kindex -grow_blindly overides next writeable address @@ -875,7 +878,7 @@ begins. The output drive is given up when writing is done. @section Influencing the behavior of image loading @c man .PP The following options should normally be performed before loading an image -by aquiring an input drive. In rare cases it is desirable to activate +by acquiring an input drive. In rare cases it is desirable to activate them only after image loading. @table @asis @sp 1 @@ -917,7 +920,7 @@ for which the image was prepared. This affects only loading of ISO images and reading of their files. The multi-session method of growing is not allowed as long as -displacement is non-zero. I.e. -indev and -outdev must be different. The displacement gets reset to 0 before the drive -gets re-aquired after writing. +gets re-acquired after writing. @* Examples: @* @@ -1149,7 +1152,7 @@ can hamper reading of partly damaged media. Setting "off:emul_off" disables the elsewise trustworthy table-of-content scan for those media. @* To be in effect, the -rom_toc_scan setting has to be made before the -*dev -command which aquires drive and medium. +command which acquires drive and medium. @c man .TP @item -calm_drive "in"|"out"|"all"|"revoke"|"on"|"off" @kindex -calm_drive reduces drive activity @@ -2581,7 +2584,7 @@ and eventually override the list of other speed offers. Try to close the upcomming track and session if the drive reported the medium as damaged. This may apply to CD-R, CD-RW, DVD-R, DVD-RW, DVD+R, DVD+R DL, or BD-R media. It is indicated by warning messages when the drive gets -aquired, and by a remark "but next track is damaged" with the line +acquired, and by a remark "but next track is damaged" with the line "Media status :" of command -toc. @* The setting of option -close determines whether the medium stays appendable. @@ -4614,7 +4617,7 @@ The scope is only a single data track per session to be written to blank, overwriteable, or appendable media. The medium gets closed if closing is applicable and not option -multi is present. @* -If an input drive was aquired, then it is given up. +If an input drive was acquired, then it is given up. This is only allowed if no image changes are pending. @* dev= must be given as @command{xorriso} device address. Addresses like 0,0,0 @@ -5059,7 +5062,7 @@ $ xorriso -device_links @c man .B Blank medium and compose a new ISO image as batch run @node ExCreate, ExDialog, ExDevices, Examples @section Blank medium and compose a new ISO image as batch run -Aquire drive /dev/sr2, make medium ready for writing a new image, +Acquire drive /dev/sr2, make medium ready for writing a new image, fill the image with the files from hard disk directories /home/me/sounds and /home/me/pictures. @* @@ -5233,7 +5236,7 @@ $ xorriso -dev /dev/sr2 \ @node ExModifying, ExBootable, ExGrowing, Examples @section Copy modified ISO image from one medium to another Load image from input drive. Do the same manipulations as in the previous -example. Aquire output drive and blank it. Burn the modified image as +example. Acquire output drive and blank it. Burn the modified image as first and only session to the output drive. @* @sp 1