Re: [Libcdio-devel] CD-TEXT documentation

[Thomas Schmitt]

Hi,

i pulled the current git and read over libcdio.texi and cdtext.texi.
(Now at: efc5ebd30cbc0a88001b701bb7b9cb69275a0941)

---------------------------------------------------------------------------
doc/libcdio.texi:

To my eyes, the splitting of paragraphs still suggests that the format
statement applies to program area only.

Meanwhile i understand the CD+G statement as a reference to pre-CD-TEXT
usage of R-W sub-channels. This matches well Leon's opinion about the
de-facto non-existence of CD-TEXT in the program area.

So i would now rather state:
"
 The second place the information can be recorded is in the R-W sub
 codes in the program area of the CD giving a data capacity of roughly
 31MB. But there are no audio CDs known, which make use of this.

 CD Text information is stored in a format that follows the
 Interactive Text Transmission System (ITTS) which is the same data
 transmission standard used by such things as Digital Audio
 Broadcasting (DAB), and virtually the same as the data standard for
 the MiniDisc.

 R-W sub codes may also be used for other formats which represent
 text and graphics in applications such as CD+G (CD w/graphics).
"

(Replacing the two paragraphs:
 "The second place the information ... MiniDisc."
 "Traditionally the R-W sub codes have been ...  not at all."
)

-----

The following paragraph still needs some update for the 21st century:

"The methods for reading this data from a CD-ROM drive is covered by
 the programming specs from the individual drive manufacturers. In the
 case of ATAPI drives, the SFF8020 spec covers the reading of the RW
 subcodes."

If the reference to pre-MMC ATAPI drives shall stay, then it should
at least be mentioned that MMC offers standard commands for retrieving
CD-TEXT from both mentioned storage locations: READ TOC/PMA/ATIP and READ CD.

-----

"There is a separate document in this distribution describing CD-Text
 information and how it is encoded."

Shouldn't one mention the name cd-text.texi resp. cd-text.info here ?


---------------------------------------------------------------------------
doc/cd-text.tex:

Some meaning is lost here - at least to my german understanding of english:

"@item Codes @kbd{0x86},@kbd{0x87}, @kbd{0x88}, @kbd{0x89}, @kbd{0x8d}
 apply to the whole disc."

You removed the word "only" from "whole disc only".
The meaning of my original statement is:
- these codes apply to the whole disc.
- they cannot be attributed to particular tracks.

-----

"Pack types @kbd{0x80} (Title) and
 @kbd{0x85} (Message Area) and are encoded according to their block's
 Character Code."

The first "and" is "to" in my text. Meant is that 0x80, 0x81, 0x82, 0x83,
0x84, 0x85 are encoded according to the Character Code (of 0x8f).

There is a surplus "and" after "(Message Area)".

-----

"The two bytes constitute a 16-bit Big-endian number are decoded as follows:"

Some glue text seems to be missing between "number" and "are".

-----

"The 12 payload bytes contain pieces of NULL- or @code{\0}-terminated texts"

Is it appropriate to use "NULL" with two "L" here ?

-----

"       3 : libcdio source states: "cd-text information copyright byte"
            Probably 3 means "copyrighted", 0 means "not copyrighted"."

Is it appropriate to quote the own source code ?
I.e. shouldn't "libcdio source states" be omitted ?

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


As for importing cd-text.texi into libburn, i first have to ponder about the
intended audience of libburn's current cdtext.txt.

It is originally intended as background information for libburn development.
Not so much for the programmers of applications which use libburn. But the
libburn API specs and the cdrskin man page already mention it.
So i will probably have to restructure this part of libburn documenation.

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


Have a nice day :)

Thomas