[Pkg-libburnia-devel] Bug#731023: xorriso: Missing info file

[Thomas Schmitt]

Hi,

i am the upstream programmer and ithus to blame for the
manual's state.

>  * No indication of default behavior for eash option.
>  Did I miss something hidden some where? Is the first one default?

The rule of thumb is that the core features of ISO 9660
are default and that xorriso specific add-ons are not.

Command -status tells the current state of any setting,
Default is what you get when staying away from start-up
files and executing no other commands before -status:

  $ xorriso -no_rc -status -md5
  GNU xorriso 1.3.3 : RockRidge filesystem manipulator, libburnia project.

  -md5 off
  $

>     -  -md5 "on"

I will ponder how to mark defaults without further inflating
the manual.

>     -  -xattr "on"

Default is "off".

>     -  -eject "in"
>     -  -commit_eject "in" (can not be both this and -eject "in")

These two commands are action commands and thus have no default
(as little as shell command "cp" has a default).

I guess there are more setting commands which do not explicitely
tell there default in the man page.
Adding to each a statement about the default value will make
the man page even bigger.
I need some shorter way of marking.


> * Too many acronyms without easily findable definitions.  

> - nwa: next write address ?
"       predicted_nwa  is  the block address where the add-on session of
        blind growing will finally end up."

> - msc: multi session subsector count?

"msc1" and "msc2" are shell variables used in an example.
One may use other names, of course.
(The combined usage model of mkisofs and cdrecord is ugly
 enough to justify the choice of ugly example variables.)

> (But what is sbsector? seen with -toc)

The term stems from man 8 mount: -o sbsector=<number> 
I assume it is an abbreviation of "super block sector".

It is explained with xorriso command -load:
"Usually all available sessions are shown  with  command -toc.
 [...]
 entity depicts the kind of addressing.
 [...]
 The following entities are defined:
 [...]
 "lba" or "sbsector" with a number as of a line "ISO ...", column
 "sbsector".
"
This needs some endurance with reading, i confess.

> - lba: ?

Logical Block Address. A concept from MMC specs which rule
the operation of optical drives and media. The smallest
addressable entity in the data area of an optical medium.
Also used by ECMA-119, which rules ISO 9660 filesystems.

Obviously i did not introduce this important concept
properly into the manual. I will fix this.


> this manulal is very difficunlt to understand.

Well, it has a lot to tell and grew during the last 6 years.
An overhaul is not easily done, because it needs to be
carefully checked with the factual properties of the program.

Experiments and source code study will be unavoidable.
I would advise -dialog mode, gdb and lots of editor windows
as exploration tools.

Anybody who contributes has to be prepared for the frustration
of nitpicking objections by my side, i have to warn in advance.
If the current state is hard to understand but correct, and
the proposal is better english but introduces mistakes, then
i will reject the change.
Nevertheless i am willing to spend substantial time with
contributors who want to improve the manual properly.


Have a nice day :)

Thomas