libburnia/libisoburn
2
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Changed xorriso.texi according to proposals by Tony Mancill

Browse Source
This commit is contained in:
Thomas Schmitt
2012-03-05 10:32:03 +00:00
parent 9836165089
commit 2d52e9427d
4 changed files with 272 additions and 261 deletions
Download Patch File Download Diff File Expand all files Collapse all files

269
xorriso/xorriso.info
View File

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