etc/BABYL

   1 Format of Version 5 Babyl Files:
   2
   3 (Babyl was the storage format used by Rmail before Emacs 23.1.
   4 Since then it uses mbox format.)
   5
   6 Warning:
   7
   8     This was written Tuesday, 12 April 1983 (by Eugene Ciccarelli),
   9 based on looking at a particular Babyl file and recalling various
  10 issues.  Therefore it is not guaranteed to be complete, but it is a
  11 start, and I will try to point the reader to various Babyl functions
  12 that will serve to clarify certain format questions.
  13
  14     Also note that this file will not contain control-characters,
  15 but instead have two-character sequences starting with Uparrow.
  16 Unless otherwise stated, an Uparrow <character> is to be read as
  17 Control-<character>, e.g. ^L is a Control-L.
  18
  19 Versions:
  20
  21     First, note that each Babyl file contains in its BABYL OPTIONS
  22 section the version for the Babyl file format.  In principle, the
  23 format can be changed in any way as long as we increment the format
  24 version number; then programs can support both old and new formats.
  25
  26     In practice, version 5 is the only format version used, and the
  27 previous versions have been obsolete for so long that Emacs does not
  28 support them.
  29 \f
  30
  31 Overall Babyl File Structure:
  32
  33     A Babyl file consists of a BABYL OPTIONS section followed by
  34 0 or more message sections.  The BABYL OPTIONS section starts
  35 with the line "BABYL OPTIONS:".  Message sections start with
  36 Control-Underscore Control-L Newline.  Each section ends
  37 with a Control-Underscore.  (That is also the first character
  38 of the starter for the next section, if any.)  Thus, a three
  39 message Babyl file looks like:
  40
  41 BABYL OPTIONS:
  42 ...the stuff within the Babyl Options section...
  43 ^_^L
  44 ...the stuff within the 1st message section...
  45 ^_^L
  46 ...the stuff within the 2nd message section...
  47 ^_^L
  48 ...the stuff within the last message section...
  49 ^_
  50
  51     Babyl is tolerant about some whitespace at the end of the
  52 file -- the file may end with the final ^_ or it may have some
  53 whitespace, e.g. a newline, after it.
  54 \f
  55
  56 The BABYL OPTIONS Section:
  57
  58     Each Babyl option is specified on one line (thus restricting
  59 string values these options can currently have).  Values are
  60 either numbers or strings.  The format is name, colon, and the
  61 value, with whitespace after the colon ignored, e.g.:
  62
  63 Mail: ~/special-inbox
  64
  65     Unrecognized options are ignored.
  66
  67     Here are those options and the kind of values currently expected:
  68
  69     MAIL                Filename, the input mail file for this
  70                         Babyl file.  You may also use several file names
  71                         separated by commas.
  72     Version             Number.  This should always be 5.
  73     Labels              String, list of labels, separated by commas.
  74 \f
  75
  76 Message Sections:
  77
  78     A message section contains one message and information
  79 associated with it.  The first line is the "status line", which
  80 contains a bit (0 or 1 character) saying whether the message has
  81 been reformed yet, and a list of the labels attached to this
  82 message.  Certain labels, called basic labels, are built into
  83 Babyl in a fundamental way, and are separated in the status line
  84 for convenience of operation.  For example, consider the status
  85 line:
  86
  87 1, answered,, zval, bug,
  88
  89     The 1 means this message has been reformed.  This message is
  90 labeled "answered", "zval", and "bug".  The first, "answered", is
  91 a basic label, and the other two are user labels.  The basic
  92 labels come before the double-comma in the line.  Each label is
  93 preceded by ", " and followed by ",".  (The last basic label is
  94 in fact followed by ",,".)  If this message had no labels at all,
  95 it would look like:
  96
  97 1,,
  98
  99     Or, if it had two basic labels, "answered" and "deleted", it
 100 would look like:
 101
 102 1, answered, deleted,, zval, bug,
 103
 104     The & Label Babyl Message knows which are the basic labels.
 105 Currently they are:  deleted, unseen, recent, and answered.
 106
 107     After the status line comes the original header if any.
 108 Following that is the EOOH line, which contains exactly the
 109 characters "*** EOOH ***" (which stands for "end of original
 110 header").  Note that the original header, if a network format
 111 header, includes the trailing newline.  And finally, following the
 112 EOOH line is the visible message, header and text.  For example,
 113 here is a complete message section, starting with the message
 114 starter, and ending with the terminator:
 115
 116 ^_^L
 117 1,, wordab, eccmacs,
 118 Date: 11 May 1982 21:40-EDT
 119 From: Eugene C. Ciccarelli <ECC at MIT-AI>
 120 Subject: notes
 121 To: ECC at MIT-AI
 122
 123 *** EOOH ***
 124 Date: Tuesday, 11 May 1982  21:40-EDT
 125 From: Eugene C. Ciccarelli <ECC>
 126 To:   ECC
 127 Re:   notes
 128
 129 Remember to pickup check at cashier's office, and deposit it
 130 soon.  Pay rent.
 131 ^_
 132 \f
 133 ;;; Babyl File BNF:
 134
 135 ;;; Overall Babyl file structure:
 136
 137
 138 Babyl-File      ::= Babyl-Options-Section  (Message-Section)*
 139
 140
 141 ;;; Babyl Options section:
 142
 143
 144 Babyl-Options-Section
 145                 ::= "BABYL OPTIONS:" newline (Babyl-Option)* Terminator
 146
 147 Babyl-Option    ::= Option-Name ":" Horiz-Whitespace BOptValue newline
 148
 149 BOptValue       ::= Number | 1-Line-String
 150
 151
 152
 153 ;;; Message section:
 154
 155
 156 Message-Section ::= Message-Starter  Status-Line  Orig-Header
 157                     EOOH-Line  Message  Terminator
 158
 159 Message-Starter ::= "^L" newline
 160
 161 Status-Line     ::= Bit-Char  ","  (Basic-Label)* "," (User-Label)* newline
 162
 163 Basic-Label     ::= Space  BLabel-Name  ","
 164
 165 User-Label      ::= Space  ULabel-Name  ","
 166
 167 EOOH-Line       ::= "*** EOOH ***" newline
 168
 169 Message         ::= Visible-Header  Message-Text
 170
 171
 172 ;;; Utilities:
 173
 174 Terminator      ::= "^_"
 175
 176 Horiz-Whitespace
 177                 ::= (Space | Tab)*
 178
 179 Bit-Char        ::= "0" | "1"