Polished documentation

16 years ago · 33938c20eb
parent 71c490d0ae
commit 33938c20eb
3 changed files with 41 additions and 25 deletions
--- a/cdrskin/cdrskin.1
+++ b/cdrskin/cdrskin.1
@ -58,6 +58,8 @@ See section EXAMPLES at the end of this text.
 .br
 Track recording model
 .br
+Write mode selection
+.br
 Recordable CD Media
 .br
 Sequentially Recordable DVD Media
@ -108,6 +110,16 @@ have been developed for magnetic tapes. Only formats which mark a detectable
 end-of-archive in their data are suitable, though. Well tested are
 the archivers afio and star. Not suitable seems GNU tar.
 .PP
+.B Write mode selection:
+.br
+If none of the options -dao, -tao or -sao is given then the program will
+try to choose a write mode which matches the defined recording job,
+the capabilities of the drive and the state of the present media.
+.br
+So the mentioning of write modes in the following paragraphs and in the
+examples is not so much a demand that the user shall choose one explicitely,
+but rather an illustration of what to expect with particular media types.
+.PP
 .B Recordable CD Media:
 .br
 CD-R can be initially written only once and eventually extended until they
@ -454,8 +466,8 @@ then behave strange or even go bad for the next few attempts to burn a CD.
 One should use it only if inavoidable.
 .TP
 .BI \-sao
-Write CD in Session At Once mode, resp. a sequential DVD-R[W] in Disc-at-once
-(DAO) mode.
+Write CD in Session At Once mode, a sequential DVD-R[W] in Disc-at-once
+(DAO) mode, or a DVD+R.
 .br
 With CD this mode is able to put several audio tracks on media without
 producing audible gaps between them.
@ -463,6 +475,9 @@ producing audible gaps between them.
 With DVD-R[W] this mode can only write a single track.
 No -multi is allowed with DVD-R[W] -sao.
 .br
+-sao is permissible with overwriteable DVD and with DVD+R but actually only
+imposes restrictions without providing known advantages. 
+.br
 -sao can only be used for tracks of fixely predicted size. This implies that
 track arguments which depict stdin or named pipes need to be preceeded by
 option tsize= or by option tao_to_sao_tsize=.
@ -497,8 +512,9 @@ Less guesswork is needed if track sources are in format MS-WAVE in a file with
 suffix ".wav".
 .TP
 .BI \-tao
-Write CD in Track At Once (TAO) mode, resp. sequential DVD-R[W] in Incremental
-Streaming mode. This mode also applies pro-forma to overwriteable DVD media.
+Write CD in Track At Once (TAO) mode, sequential DVD-R[W] in Incremental
+Streaming mode, or DVD+R without traditional -sao restrictions.
+This mode also applies pro-forma to overwriteable DVD media.
 .br
 Mode -tao can be used with track sources of unpredictable size, like standard
 input or named pipes. It is also the only mode that can be used for writing
--- a/cdrskin/convert_man_to_html.sh
+++ b/cdrskin/convert_man_to_html.sh
@ -43,12 +43,15 @@ then
  -e 's/<h1 align=center>CDRSKIN<\/h1>/<h1 align=center>man 1 cdrskin<\/h1>/' \
  -e 's/<body>/<body BGCOLOR="#F5DEB3" TEXT=#000000 LINK=#0000A0 VLINK=#800000>/' \
  -e 's/<b>Overview of features:<\/b>/\&nbsp;<BR><b>Overview of features:<\/b>/' \
+  -e 's/<b>General information paragraphs:<\/b>/\&nbsp;<BR><b>General information paragraphs:<\/b>/' \
  -e 's/<b>Track recording model:<\/b>/\&nbsp;<BR><b>Track recording model:<\/b>/' \
  -e 's/In general there are two types of tracks: data and audio./\&nbsp;<BR>In general there are two types of tracks: data and audio./' \
  -e 's/While audio tracks just contain a given/\&nbsp;<BR>While audio tracks just contain a given/' \
+  -e 's/<b>Write mode selection:<\/b>/\&nbsp;<BR><b>Write mode selection:<\/b>/' \
  -e 's/<b>Recordable CD Media:<\/b>/\&nbsp;<BR><b>Recordable CD Media:<\/b>/' \
  -e 's/<b>Overwriteable DVD Media:<\/b>/\&nbsp;<BR><b>Overwriteable DVD Media:<\/b>/' \
  -e 's/<b>Sequentially Recordable DVD Media:<\/b>/\&nbsp;<BR><b>Sequentially Recordable DVD Media:<\/b>/' \
+  -e 's/The write modes for DVD+R/\&nbsp;<BR>The write modes for DVD+R/' \
  -e 's/<b>Drive preparation and addressing:<\/b>/\&nbsp;<BR><b>Drive preparation and addressing:<\/b>/' \
  -e 's/If you only got one CD capable drive/\&nbsp;<BR>If you only got one CD capable drive/' \
  -e 's/^Alphabetical list of options/\&nbsp;<BR>Alphabetical list of options/' \
@ -60,7 +63,7 @@ then

  chmod u+rw,go+r,go-w "$htmlpage"
  echo "Emerged file:"
-  ls -l "$htmlpage"
+  ls -lL "$htmlpage"

 else

--- a/cdrskin/wiki_plain.txt
+++ b/cdrskin/wiki_plain.txt
@ -10,8 +10,9 @@ Schilling's cdrtools. cdrskin strives to be a second source for the services
 traditionally provided by cdrecord. Currently it does CD-R and CD-RW this way.
 Overwriteable media DVD-RAM, DVD+RW and DVD-RW are handled differently than 
 with cdrecord-ProDVD in order to offer TAO-like single track recording.
-Sequential DVD-R[W] are handled like CD-R[W] with TAO and multi-session.
-Additionally cdrskin offers cdrecord-ProDVD-like mode DAO with DVD-R[W].
+Sequential DVD-R[W] and DVD+R are handled like CD-R[W] with TAO and
+multi-session. Additionally cdrskin offers cdrecord-ProDVD-like mode DAO
+with DVD-R[W].

 cdrskin does not contain any bytes copied from cdrecord's sources.
 Many bytes have been copied from the message output of cdrecord
@ -22,13 +23,9 @@ About libburn API for burning CD: http://libburnia-api.pykix.org

 --------------------------------------------------------------------------

-Appending sessions to an unclosed CD or DVD-R[W] is restricted to write mode
-TAO. (Users who have a burner which succeeds with a follow-up session on CD via
-cdrecord -sao : please contact us.)
-
-For DVD types other than DVD-RAM, DVD+RW, DVD-RW, DVD-R and for appending
-sessions to ISO filesystems on DVD other than DVD-RW, DVD-R see the advise
-to use dvd+rw-tools at the end of this text.
+For dual layer DVD types and for appending sessions to ISO filesystems on
+DVD other than DVD-RW, DVD-R, DVD+R see the advise to use dvd+rw-tools at
+the end of this text.

 --------------------------------------------------------------------------

@ -86,10 +83,9 @@ has to offer both, r- and w-permission.
 --------------------------------------------------------------------------

 The DVD capabilities of cdrskin differ from those of cdrecord-ProDVD. cdrskin
-lacks of support for DVD+R and for dual layer DVD media. On the other hand it
-offers TAO-like multi-session with DVD-R[W] and TAO-like single session with
-overwriteable DVD media. It also offers DAO on DVD-R[W] which is probably the
-same as the traditional cdrecord-ProDVD write mode.
+offers TAO-like multi-session with DVD-R[W], DVD+R and TAO-like single session
+with overwriteable DVD media. It also offers DAO on DVD-R[W] which is probably
+the same as the traditional cdrecord-ProDVD write mode.

 Non-cdrecord blank mode blank=format_overwrite brings a DVD-RW
 disc from its initial profile "Sequential Recording" into profile state
@ -209,10 +205,10 @@ for an illustrated example with K3b 0.10 .

 DVD advise:

-For burning of DVD media other than DVD-RAM, DVD+RW, DVD-RW, DVD-R, the cdrskin
-project currently advises to use Andy Polyakov's dvd+rw-tools which despite
-their historic name burn for me on above burner: DVD-RAM, DVD+RW, DVD+R,
-DVD-RW, DVD-R and are also capable of dual layer and even BD discs. 
+For burning of DVD media other than DVD-RAM, DVD+RW, DVD+R, DVD-RW, DVD-R,
+the cdrskin project currently advises to use Andy Polyakov's dvd+rw-tools
+which despite their historic name are capable of all the media above 
+and also do dual layer and even BD discs. 

 http://fy.chalmers.se/~appro/linux/DVD+RW/tools

@ -228,9 +224,10 @@ So for growable ISO filesystems on DVD-RAM or DVD+RW growisofs is the only
 choice, currently.


-cdrskin can offer DVD multi-session only with sequential DVD-R[W]. Associated
-options blank=, -multi, -msinfo and -toc are available in this case. Thus
-sequential DVD-RW behave much like large CD-RW with possibly more than 99
+cdrskin can offer DVD multi-session only with sequential DVD-R[W] and with
+DVD+R.
+Associated options blank=, -multi, -msinfo and -toc are available in this case.
+Thus sequential DVD-RW behave much like large CD-RW with possibly more than 99
 tracks.

 --------------------------------------------------------------------------