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