:: MacCVSClient :: User Guide
  RBL Specification
 

The RBL storage format is a text based alternative to the resource fork of a Mac OS file. Its primary purpose is storage of Mac OS resource on CVS servers.

RBL can be used in other ways as well. As its structure is very simple, one could create RBL files on UNIX or other foreign platforms and convert them to real resource forks on the Mac. This would e.g. be a much easier approach than implementing tools to manipulate a resource fork's binary image directly.

  Concept
 

The idea behind RBL is to be able to store resource forks as text files in CVS repositories. Also the files should be diffable and mergeable with the built in text file handling mechanisms of CVS.

Therefore, the resulting structure of RBL files has two main aspects:

It is line based.
Hence its name — RBL stands for Resource By Line. Lines are terminated by the standard UNIX NEWLINE character 0x0a. Lines can be very long. Their length can easily amount to several kilobytes or more.
It is a text file.
The data in RBL files is 8-bit-text. Binary data is RBL7 converted and thus data characters are all inbetween and including SPACE and ('?' + 127).

An RBL file consists of two major blocks:

  1. the file header and
  2. the resource block.
  Line Types
 

A line in an RBL file can have one of a few different types. The type of an arbitrary line can be detected examining the line's first character. Every line (the last line as well) in an RBL file is terminated by UNIX NEWLINE characer(ASCII 0x0a).

The magic line starts with !
  The very first line in an RBL file is the magic line. It starts with an exclamation mark followed by a fixed string. This string is use to identify the file format as RBL. See also File Header.
A comment line starts with #
  The contents of a comment line — including the line terminating NEWLINE character — is ignored. Note that the first line in an RBL file cannot be a comment line because it needs to be the magic line used to identify the file as an RBL file. Find details about the recommended usage of comment lines in File Header and Resource Block.
A resource line starts with 0x3f ... 0x3f + 0x7f
  This line stores resource data for one single Mac OS resource. See also Resource Block. Note the difference between a resource line and the resource block though.
CVS conflict markers start with <, =, or >
  The CVS conflict markers are part of the RBL specification as well. RBL reading utilities should be able to recognize CVS conflict markers. MacCVSClient has to handle and interpret them because it might get conflict ridden files sent back from the CVS server.
  Binary Data Encoding RBL7
 

Mac OS resource data in general is binary data. All byte values from 0x00 to 0xff can be used. As mentioned above, RBL is a text based file format. So, before storage, the resource data needs to be converted from binary data to text data.

The conversion scheme is quite simple. Suppose you want to encode a block of n raw data bytes. Step one is to chop the data block into 7 bit wide chunks.

The lower significant 7 bits of the first byte are the first chunk. The highest significant bit is carried on to the next chunk. All further seven bit wide chunks are built by taking the carried bits from the previous byte, shifting them to the right (down to lower significance), and filling them on the left (on the side of high significance) to the width of 7 with the lower significant bits of the current byte. Leftover high significant bits are carried on. This goes on until there are no data bits left. The high significant bits of the last seven bit chunk might stay unused and default to zero.

Now we have a row of seven bit chunks in the range of 0x00 to 0x7f — still binary. Step two is to fold every 7 bit raw data chunk to 8 bit text by adding 0x3f (character '?').

Let's call this data encoding scheme RBL7.

RBL7 encoding is robust to everything CVS might do to it. All RBL7 encoded bytes have codes equal to or higher than 0x3f (character '?'). The '$' sign does not show up there, so we're safe against CVS keyword substitution. The characters '>', '=', and '<' don't show up in RBL7 encoded data. Thus, CVS conflict markers can be recognized and do not interfere with RBL7 encoded data.

If it turns out that using 8 bit text is a problem, the RBL7 conversion can optionally be replaced by a similar RBL6 conversion which groups 6 bit chunks. Doing that results in 7 bit encoded text (pure ASCII). Here, the file size increases. At this moment, only the RBL7 encoding is supported in MacCVSClient.

  File Header
 
!RBLCVSc 0x0a
The magic line. Used to recognize RBL files.
# 0x0a
An empty comment line.
*VER: xxxx 0x0a
The RBL version. The current RBL version is 0, so xxxx equals 0000.
*TC: tttttttt : cccccccc 0x0a
The file type and file creator information of the Mac OS resource fork. Here tttttttt and cccccccc stand for the eight digit hex representation of the unsigned long integers the Mac OS uses to identify the file's type and creator application.
# 0x0a
An empty comment line.

Note that in this description of the RBL file header, two comment lines have been inserted. As mentioned earlier, these comment lines do not add any information to the file — their contents is ignored when the file is read.

They do have a purpose though. In MacCVSClient, RBL is used to store resource forks as text files in CVS repositories. In the CVS environment, it is useful to have file formats that are easily mergeable. The CVS merge mechanism is based on diff3. That one is creating better and more reliable results, if changed parts of the input texts (like e.g. three revisions of a CVSed RBL file) are clearly interspersed by unchanged portions of text.

When inserting a few empty comment lines inbetween data lines in the RBL file, we make diff3's job during a CVS merge easier.

  Resource Block
 

The resource block of the RBL file consists of one resource line for each resource. The resource lines are sorted by increasing pairs of resource type and index. Inbetween two resource lines, a single empty comment line is inserted. See part File Header above for an explanation of the empty comments.

head name 0x09 data 0x0a
head
It consists of the resource type (four bytes, big endian), the resource index (two bytes, big endian), the resource attributes (one byte). These seven data bytes are RBL7 encoded and thus result in the eight byte wide head part.
name
This is the resource name in clear text. Normally, no conversion is performed on it. If the resource name contains characters below SPACE though these are replaced by SPACE characters.
data
The RBL7 converted raw resource data.
Rev. 1.20 LegalCopyright © 1998 Fontworks Ltd., © 2000 Jörg Bullmann