summaryrefslogtreecommitdiff
path: root/support/vvcode/doc/vvfiles.tex
blob: bf019f4ddbb1a6633031305a1f9679c1038390f2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
@c *************************************************************************
@c CHAPTER: Definition of VVcode-related file formats
@c *************************************************************************
@c    node-name, next, previous,  up
@node File Formats, File Formats, Top, Top
@chapter Definition of VVcode-related file formats


@c =========================================================================
@c SECTION: Format of the VVE file
@c =========================================================================
@section Format of the VVE file

A VVE file consists of three logical sections in the following logical
format:

@example
<VVE file> ::= <initial preamble>
               <encoded data lines> 
               <terminal postamble>
@end example

The @code{<initial preamble>} and @code{<terminal postamble>} sections
contain VVE "header" lines used to record and control the characteristics
of the encoding/decoding process.  The @code{<encoded data lines>} section
contains the data from the original file, encoded using the VVcode scheme.

It is sometimes desirable to transmit the VVE file in more than one part,
so the logical format is extended to cater for multi-part files:

@example
<first part> ::=  <initial preamble>
                  <encoded data lines> 
                  <continuation postamble>

<middle part> ::= <continuation preamble>
                  <encoded data lines> 
                  <continuation postamble>

<last part> ::=   <continuation preamble>
                  <encoded data lines> 
                  <terminal postamble>
@end example

There is always one @code{<first part>} and one @code{<last part>} part in
a multi-part VVE file.  There may be zero (for a two part file) or more
@code{<middle part>} parts.

The sections are described in more detail below.


@c -------------------------------------------------------------------------
@c SUBSECTION: Line Prefix and Suffix
@c -------------------------------------------------------------------------
@subsection Line Prefix and Suffix
@itemize @bullet
  @item each line has a "Vv" prefix and "V" suffix

  @item prefix - elimination of mailer lines

  @item postfix - avoid space stripping by certain mailers
@end itemize


@c -------------------------------------------------------------------------
@c SUBSECTION: Preamble Sections
@c -------------------------------------------------------------------------
@subsection Preamble Sections
The preamble sections are used to initialize VVdecode before it starts to
decode the encoded file data.  Each preamble consists of a set of VVE
header lines, each specifying a particular parameter relevant to the
encoding/decoding operation.  Each preamble section comprises a set of
optional header lines followed by the set of required header lines.  the
syntax and use of the header lines is described in section 1.4.


@subsubsection Preamble
The initial preamble is used to initialize VVdecode parameters before it
starts to decode the encoded file (e.g. the file mode and timestamp).  The
logical format of this section  is:

@example
<initial preamble> ::= <optional initialization headers>
                       <begin header>
@end example

The @code{mode}, @code{format} and optional headers may be in any order,
but the @code{begin} header must be the last header in this preamble
section.  None, any or all of the following optional headers may be present
in the initial preamble section:

@example
<optional initializiation headers> ::= <characterset header>
                                       <comment header>
                                       <decodeversion header>
                                       <format header>
                                       <mode header>
                                       <operatingsystem header>
                                       <recordlength header>
                                       <table header>
                                       <timestamp header>
@end example

Note that only the @code{comment} header line may appear more than once in
this section.

@subsubsection Continuation Preamble

The initial preamble is used to reset certain VVdecode parameters before it
starts to decode the next section of the VVE file. The logical format of
this section is:

@example
<continuation preamble> ::= <optional continuation headers>
                            <skipfrom header>
@end example

The optional headers may be in any order, but the @code{skipfrom} header
must be the last header in this preamble section.  None, any or all of the
following optional headers may be present in this section:

@example
<optional initializiation headers> ::= <comment header>
                                       <table header>
@end example

Note that only the @code{comment} header line may appear more than once in
this section.


@c -------------------------------------------------------------------------
@c SUBSECTION: Postamble Sections
@c -------------------------------------------------------------------------
@subsection Postamble Sections
The preamble sections are used to initialize VVdecode before it starts to
decode the encoded file data.  Each preamble consists of a set of VVE
header lines, each specifying a particular parameter relevant to the
encoding/decoding operation.  Each preamble section comprises a set of
optional header lines followed by the set of required header lines.

@subsubsection Postamble
[TODO] put in some text here
@example
<continuation postamble> ::= <skipto header>
                             <comment header>
@end example

The @code{comment} header line is optional and may appear more than once in
this section.

@subsubsection Terminal Postamble
[TODO] put in some text here
@example
<continuation preamble> ::= <end header>
                            <optional terminal headers>

<optional initializiation headers> ::= <bytecount header>
                                       <comment header>
                                       <crc32 header>
@end example


@c -------------------------------------------------------------------------
@c SUBSECTION: Encoded Data Lines
@c -------------------------------------------------------------------------
@subsection Encoded Data Lines
[TODO] put in some text here
@itemize @bullet
  @item describe what these lines are used for

  @item format of the encoded line

  @item termination of each section of encoded data (zero length line)

  @item describe the different underlying data formats for fixed, stream
        and variable format records
@end itemize


@c =========================================================================
@c SECTION: VVE Header Lines
@c =========================================================================
@section VVE Header Lines

A VVE header line takes the form

@example
<header-name> <parameter-1> <parameter-2> ... <parameter-N>
@end example

Most headers take only one parameter and parameters are normally separated
by whitespace, though certain headers (e.g. @code{begin}) take more than one
parameter and can include whitespace in the parameters.  The format of each
of the VVE header lines is described below.  Two important symbols used in
the description are:

@table @code
  @item <WS>
        used to denote whitespace which may include spaces, tabs but not
        the end of the line.  The syntax

        @example
        xyz <WS> parameter <WS> <EOL>
        @end example
        
        states that header @code{xyz} takes a parameter which starts at the
        first non-whitespace character after the @code{xyz} header name and
        is terminated by the first whitespace character after that or the
        end of line.  This syntax is used to specify parameters which do
        not contain whitespace.

  @item <EOL>
        used to denote the end of the line.  The syntax
        
        @example
        xyz <WS> parameter <EOL>
        @end example

        states that header @code{xyz} takes a parameter which starts at the
        first non-whitespace character after the @code{xyz} header name and
        is terminated by the end of the line.  This format would be used to
        specify that parameters can include whitespace.

  @item <NXT-HDR>
        used to denote the next VVE header in the file.  The syntax
    
        @example
        xyz <WS> parameter <NXT-HDR>
        @end example
        
        states that the header @code{xyz} takes a parameter which starts at
        the first non-whitespace character after the @code{xyz} header
        name and is terminated by the start of the next VVE header.  This
        format would be used to specify that parameters can span several
        lines.

        NOTE: the @code{<EOL>} characters are removed when the contents of
              the lines are joined together.
@end table

Following is a detailed description of each VVE header.  For each header
there is a set of headings in the format shown below for the @code{example}
header.

@c -------------------------------------------------------------------------
@c SUBSECTION: @code{example}
@c -------------------------------------------------------------------------
@page
@subsection @code{example}

@table @strong 
  @item Purpose:
        Brief summary of the purpose of this header.

  @item Location:
        Describe where in the VVE file that this header will be found. The
        locations are:

        @itemize @bullet
          @item initial preamble
          @item continuation preamble
          @item continuation postamble
          @item terminal postamble
        @end itemize
        
        Also indicated is whether the header is required or optional.  

  @item Syntax:
        @code{example <WS> parameter <WS> <EOL>}
        
        This part shows the syntax of the header including the header name,
        the number of parameters and the delimiters used to separate the
        parameters.

  @item Remarks:
        This part provides extra information on the use of the header and
        includes any limits that are imposed on the parameter value.

  @item VVencode:
        The header will be written to the VVE file by Vvencode and this
        part describes the circumstances under which VVencode will write
        the header line.

  @item VVdecode:
        This part describes how VVdecode should behave when it encounters
        the header in a VVE file.  In addition, specific processing rules
        are documented for specific cases, namely:

        @table @code
          @item OK
                what VVdecode should do if a valid header line is found in
                the VVE file.

          @item MISSING
                what VVdecode should do if the header line was not found in
                the VVE file.

          @item INVALID
                what VVdecode should do if the header line was found, but
                with missing or invalid parameter values.
        @end table

  @item Example:
        @code{example parameter}

        Here you'll find a simple example of a valid example header line.
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{begin}
@c -------------------------------------------------------------------------
@page
@subsection @code{begin}
@table @strong
  @item Purpose:
        Signifies the absolute start of the VVencoded data.

  @item Location:
        Initial preamble (required).

  @item Syntax:
        @code{begin <WS> file-specification <EOL>}
        
  @item Remarks:
        The file specification may include spaces, though leading and
        trailing spaces will be lost.  There is no restriction on the
        characters used in the file specification, but characters outside
        the VVcode default encoding table may be corrupted when passing
        through mail gateways or systems with differing character sets.

  @item VVencode:
        The file specification recorded in the VVE file is usually derived
        from the input file specification stripped of any preamble or
        postamble components and will therefore consist only of a name
        and/or extension component.  The value recorded can be explicitly
        specified with the @code{header_filespec} command qualifier.

  @item VVdecode:
        VVdecode will use the file specification recorded to construct the
        default file specification for the output file.  If the output file
        is specified on the VVdecode command line, the value specified on
        the @code{begin} header will only be used if the implementation of
        VVcode for the operating system has been defined to use "sticky
        defaults".

        The file specification may have been derived from a different
        operating system and may therefore be invalid on the local system.
        Before it is used VVdecode will convert the file specification to
        one that is valid.

        Processing rules:

        @table @code
          @item OK
                If required, convert the file specification so that it is
                legal on the local operating system and use the legal value
                as the default file specification for the output file.

          @item MISSING
                Issue a fatal error message and stop.

          @item INVALID
                Issue a fatal error message and stop.
        @end table

  @item Example:
        @code{begin input-file.txt}@*
        @code{begin input file name with spaces}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{bytecount}
@c -------------------------------------------------------------------------
@page
@subsection @code{bytecount}
@table @strong
  @item Purpose:
        Records the total number of bytes read by VVencode.

  @item Location:
        Final postamble (optional).

  @item Syntax:
        @code{bytecount <WS> total-bytes-read <WS> <EOL>}

  @item Remarks:
        The total is a positive signed 32 decimal bit number and must
        therefore be in the range 0 - 2147483647.  On systems which
        differentiate between binary and text files, this number is likely
        to be dependent on the mode (i.e. binary/text) used to read and
        encode the file.

  @item VVencode:
        VVencode keeps a cumulative total of the bytes read and record this
        total in the terminal postamble of VVE file.

  @item VVdecode:
        VVdecode keeps a cumulative total of the bytes decoded and written
        and compare it with the VVE recorded value as a confidence check.

        Processing rules:

        @table @code
          @item OK
                Compare the VVE recorded value with the total bytes written
                by VVdecode.  Issue a warning if the two totals are
                different.
                
          @item MISSING
                Don't attempt the comparison.

          @item INVALID
                Issue a non-fatal error message and assume that the header
                is missing.
        @end table

  @item Example:
        @code{bytecount 8388608}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{characterset}
@c -------------------------------------------------------------------------
@page
@subsection @code{characterset}
@table @strong
  @item Purpose:
        Records the character set of the VVencoded data.

  @item Location:
        Initial preamble (optional).

  @item Syntax:
        @code{characterset <WS> charset-string <WS> <EOL>}

  @item Remarks:
        The parameter string records the character set of the encoded data
        in the VVE file.  There are no formal controls on the string to use
        for a particular character set, the string is simply compared
        against a local value.  Eventually, an informal directory of
        character set strings may evolve.

  @item VVencode:
        VVencode will record the character set of the encoded data which
        under normal circumstances the character set will be the local
        character set for the operating system.  If the
        @code{translation_file} command line qualifier is specified,
        VVencode will translate the original data from the local character
        set to a new character set specified by the translation file.  In
        this case, VVencode will record the new character set.

  @item VVdecode:
        VVdecode uses this header to determine whether the encoded data in
        the VVE file is of the same character set as that used on the local
        operating system.  If the character sets are different, a warning
        will be issued.  

        If the @code{translation_file} command line qualifier is specified,
        VVdecode will translate the VVE encoded data to a new character set
        specified by the translation file.  In this case, VVdecode will
        compare the VVE file character set with the "from" character set
        expected by the translation file.

        Processing rules:

        @table @code
          @item OK
                Compare the VVE character set with the local operating
                system character set (or the translation file "from"
                character set if appropriate).  Issue a warning message if
                the two character sets are different.

          @item MISSING
                Assume that the VVE character set is the same as the local
                operating system character set.

          @item INVALID
                Issue a non-fatal error message and assume that the header
                is missing.
        @end table

  @item Example:
        @code{characterset ASCII}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{comment}
@c -------------------------------------------------------------------------
@page
@subsection @code{comment}
@table @strong
  @item Purpose:
        Records commentary information deemed to be of sufficient
        importance to warrant displaying it when VVdecoding the file.

  @item Location:
        Initial preamble, continuation preamble, continuation postamble,
        final postamble (optional).

  @item Syntax:
        @code{comment <WS> comment-string <EOL>}

  @item Remarks:
        The comment string is free form text, but care should be taken not
        to use characters that may be corrupted by mail gateways or when
        passing through systems with different character sets.

  @item VVencode:
        VVencode will record information deemed (by the programmer) to be
        important and worth flagging to the VVdecode user.  Currently this
        facility is only used to record the original character set when
        VVencode has been invoked with @code{translation_file} command line
        qualifier to convert the original data to a new character set
        before VVencoding.

  @item VVdecode:
        Generally VVdecode will display any comments encountered on the log
        file.

        Processing rules:

        @table @code
          @item OK
                If the @code{log} command line qualifier was specified,
                display the comment on the log file, otherwise ignore the
                comment.

          @item MISSING
                No action.

          @item INVALID
                Issue a non-fatal error message and ignore the comment.
        @end table

  @item Example:
        @code{comment This file is only useful on Unix systems}@*
        @code{Original character set was `EBCDIC'}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{crc32}
@c -------------------------------------------------------------------------
@page
@subsection @code{crc32}
@table @strong
  @item Purpose:
        Records the 32 bit CRC of the bytes read by VVencode.

  @item Location:
        Final postamble (optional).

  @item Syntax:
        @code{crc32 <WS> input-file-crc32 <WS> <EOL>}

  @item Remarks:
        The CRC value is an unsigned 32 bit hexadecimal number and must
        therefore be in the range 0 - FFFFFFFF.  On systems which
        differentiate between binary and text files, this number is likely
        to be dependent on the mode (i.e. binary/text) used to read and
        encode the file.

        The CRC polynomial used is the same as that used by the popular ZIP
        and ARJ archiving programs.  When encoding in binary mode, the CRC
        recorded should be identical to that computed by ARJ and ZIP.

  @item VVencode:
        VVencode computes a 32 bit CRC of the bytes read and record this
        CRC in the terminal postamble of VVE file.

  @item VVdecode:
        VVdecode computes a 32 bit CRC of the bytes decoded and written and
        compare it with the VVE recorded value as a confidence check.

        Processing rules:

        @table @code
          @item OK
                Compare the VVE recorded value with the total bytes written
                by VVdecode.  Issue a warning if the two CRCs are
                different.

          @item MISSING
                Don't attempt the comparison.

          @item INVALID
                Issue a non-fatal error message and assume that the header
                is missing.
        @end table


  @item Example:
        @code{crc32 1e0cb8a7}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{decodeversion}
@c -------------------------------------------------------------------------
@page
@subsection @code{decodeversion}
@table @strong
  @item Purpose:
        Records the minimum major version number of VVcode required to
        decode the VVE file.

  @item Location:
        Initial preamble (optional).

  @item Syntax:
        @code{decodeversion <WS> min-decode-version <WS> <EOL>}

  @item Remarks:
        The minimum decode version is a positive integer and records the
        minimum major version of VVcode required to decode the VVE file.

        The VVcode version number has a "major" and "minor" version.  For
        example, VVcode version 1.2 has a major version of 1 and a minor
        version of 2 and the header

        @example
        decodeversion 2
        @end example
        
        signifies that VVdecode version 2.0 or later is required to decode
        the file.

        Whenever a change is made to the VVE file format that is not
        backwards compatible, the major version number of VVcode will be
        incremented.

  @item VVencode:
        VVencode records the minimum major version number required to
        decode the VVE file in the initial preamble of the VVE file.

  @item VVdecode:
        VVdecode uses the recorded value to check whether it can decode the
        file.

        Processing rules:

        @table @code
          @item OK
                Check that the major version of VVdecode is not less than
                the recorded value.  If it is, issue a fatal error message
                and stop.

          @item MISSING
                Assume that the current version of VVdecode is OK and
                proceed.

          @item INVALID
                Issue a non-fatal error message and assume that the header
                is missing.
        @end table

  @item Example:
        @code{decodeversion 1}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{end}
@c -------------------------------------------------------------------------
@page
@subsection @code{end}
@table @strong
  @item Purpose:
        Signifies the absolute end of the VVencoded data.

  @item Location:
        Final postamble (required).

  @item Syntax:
        @code{end <WS> <EOL>}

  @item Remarks:
        This header signifies that there are no more encoded data lines to
        process and that the terminal preamble is about to start.

  @item VVencode:
        After the complete input file has been encoded, VVencode will write
        a "zero length" encoded line followed by the @code{end} header line
        and the terminal postamble section.

  @item VVdecode:
        After reading this header, VVdecode will cease decoding the encoded
        data bytes and start to read the terminal postamble.

        Processing rules:

        @table @code
          @item OK
                Cease decoding the encoded data bytes and start to read the
                terminal postamble.

          @item MISSING
                Issue a fatal error message and stop.
     
          @item INVALID
                This shouldn't be possible, but if so issue a fatal error
                message and stop.
        @end table

  @item Example:
        @code{end}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{format}
@c -------------------------------------------------------------------------
@page
@subsection @code{format}
@table @strong
  @item Purpose:
        Records the file organization format of the VVencoded file.

  @item Location:
        Initial preamble (optional).

  @item Syntax:
        @code{format <WS> format-string <WS> <EOL>}

  @item Remarks:
        The format string must be one of "fixed", "stream" or "variable",
        though the value may be lower, upper or mixed case.  VVcode
        supports these three type of file organization, though not all
        operating systems will support all three.  Note that the internal
        format of the encoded data will depend on the file organization.

  @item VVencode:
        VVencode records the organization of the encoded file.  Note that
        this is the format used by VVencode to read the file which may not
        necessarily be the real format of the original file.

  @item VVdecode:
        VVdecode will use this header to identify the internal format of
        the encoded data to enable it to be decoded correctly.  The format
        will also be used as the default format to create the output file.

        If the VVE file format is not supported by the local operating
        system, VVdecode will create the output file using the default file
        format for the operating system.  The @code{format} command line
        qualifier may be used to override the format of the output file.

        Processing rules:

        @table @code
          @item OK
                Use the header value to decode the encoded data bytes and
                to determine the default format of the output file.

          @item MISSING
                Issue a fatal error message and stop.

          @item INVALID
                Issue a fatal error message and stop.
        @end table

  @item Example:
        @code{format stream}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{mode}
@c -------------------------------------------------------------------------
@page
@subsection @code{mode}
@table @strong
  @item Purpose:
        Records the mode of the VVencoded file.

  @item Location:
        Initial preamble (optional).

  @item Syntax:
        @code{mode <WS> mode-string <WS> <EOL>}

  @item Remarks:
        The format string must be one of "binary" or "text", though the
        value may be lower, upper or mixed case.  VVcode supports both
        binary and text mode files, though not all operating systems will
        support both modes.  The mode will often influence the default file
        format used by the operating system.  Most operating systems
        distinguish between text and binary files, though Unix is a notable
        exception.

  @item VVencode:
        VVencode records the mode of the encoded file.  Note that this is
        the mode used by VVencode to read the file which may not
        necessarily be the real mode of the original file.

  @item VVdecode:
        VVdecode will use this header to mode of the encoded file.  The
        mode will also be used as the default mode for the output file.

        If the VVE file mode is not supported by the local operating
        system, VVdecode will create the output file using the default file
        mode for the operating system.  The @code{mode} command line
        qualifier may be used to override the mode of the output file.

        Processing rules:

        @table @code
          @item OK
                Use the header value to determine the default mode of the
                output file.

          @item MISSING
                Issue a fatal error message and stop.

          @item INVALID
                Issue a fatal error message and stop.
        @end table

  @item Example:
        @code{mode binary}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{operatingsystem}
@c -------------------------------------------------------------------------
@page
@subsection @code{operatingsystem}
@table @strong
  @item Purpose:
        Records the operating system on which the file was VVencoded.

  @item Location:
        Initial preamble (optional).

  @item Syntax:
        @code{operatingsystem <WS> operating-system-name <WS> <EOL>}

  @item Remarks:
        The parameter string records the operating system on which the
        version of VVencode used to create the VVE file was running. There
        are no formal controls on the string to use for a particular
        character set, the string is simply compared against a local value.
        The string is coded into the VVcode machine dependent header file
        so this shouldn't be too much of a problem.

        It is useful for the decoder to know whether the file was encoded
        on the same operating system to influence the decoding process.
        For example, if the original operating system is different any
        private data would usually be ignored.

  @item VVencode:
        VVencode will record the string for the local operating system as
        coded in the machine dependent header file (machine.h).

  @item VVdecode:
        VVdecode will compare the header value with that recorded for the
        local operating system in the machine dependent header file
        (machine.h) to determine whether the original file was encoded on
        the same operating system.

        Processing rules:

        @table @code
          @item OK
                Compare the header value with the local operating system
                string to determine whether the two operating systems are
                different.  Parts of the decoding process will be affected
                by this decision.

          @item MISSING
                Assume that the operating system on which the file was
                encoded is the same as the local operating system.

          @item INVALID
                Issue a non-fatal error message and assume that the header
                is missing.
        @end table

  @item Example:
        @code{operatingsystem MS-DOS}@*
        @code{operatingsystem Unix}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{recordlength}
@c -------------------------------------------------------------------------
@page
@subsection @code{recordlength}
@table @strong
  @item Purpose:
        Records the maximum and longest length records in the VVencoded
        file.

  @item Location:
        Initial preamble (optional).

  @item Syntax:
        @code{recordlength <WS> max-rec-len <WS> long-rec-len <WS> <EOL>}

  @item Remarks:
        Both versions of the record length must be either a decimal number
        within the VVcode supported range of 0 - 65535 or -1.  The value -1
        has a special meaning for each of the record lengths:
  
        max-rec-len the maximum record length is unknown or there is no
                         explicit maximum record length for this file
                         (this usually defaults to the maximum record
                         length supported by the operating system).

        lng-rec-len the length of the longest record in the file is
                    unknown.

        The record length is usually relevant only for fixed and variable
        length record format files.  The maximum record length is that
        allowed by the operating system for the file, whereas the longest
        is the length of the longest record in the file.  For variable
        length record files the longest length must be less than or equal
        to the maximum record length, whereas for fixed length record
        files, the longest record length should be equal to the maximum
        record length.

  @item VVencode:
        Where possible, VVencode will attempt to determine these parameters
        and record them in the VVE file.  Note that the @code{recordlength}
        header is in the initial preamble so these parameters must be
        determined before the file is opened for encoding.  The value may
        be overridden by the @code{record_length} command line qualifier.

  @item VVdecode:
        If the output file format is fixed or variable length records,
        Vvdecode will use these values to create a file of the correct
        type.  The parameter values will be checked, even if they will not
        be used during the subsequent decoding activities.  If the
        parameter values are unknown or invalid, VVdecode will use default
        values appropriate to the file format and the local operating
        system.

        Note that the record length might be valid for the VVE file (i.e.
        in the range 0 - 65535), but be invalid for the file format and
        local operating system.

        Processing rules:

        @table @code
          @item OK
                Use the values to create a file of the correct type and
                format.

          @item MISSING
                Use appropriate default values for the file format and
                local operating system.

          @item INVALID
                Issue a non-fatal error message and assume that the header
                is missing.
        @end table

  @item Example:
        @code{recordlength    -1   132}@*
        @code{recordlength   255    -1}@*
        @code{recordlength 32256 32256}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{skipfrom}
@c -------------------------------------------------------------------------
@page
@subsection @code{skipfrom}
@table @strong
  @item Purpose:
        Signifies the start of a segment of VVencoded data.

  @item Location:
        Continuation preamble (required).

  @item Syntax:
        @code{skipfrom <WS> part-number <WS> file-specification <EOL>}

  @item Remarks:
        The @code{skipfrom} header is used when VVencode creates a
        multi-part VVE file and is analogous to the @code{begin} header in
        the first part.  The part-number parameter records the number of
        the previous VVE file part.  Both parameters are included in the
        header to provide a reasonable degree of confidence that the wanted
        part of the encoded file has been found.

  @item VVencode:
        A @code{skipfrom} header will only be written if VVencode was
        invoked with the @code{split_size} command line qualifier and the
        VVE file is long enough to require more than one part.  The file
        specification recorded in the VVE file is the same as that in the
        @code{begin} header.  The number of the previous VVE file part is
        also recorded.

  @item VVdecode:
        VVdecode will check that the file specification and part number
        match those expected for the next part.  If both do not match,
        VVdecode will continue to look for the wanted VVE file part.

        Processing rules:

        @table @code
          @item OK
                If the wanted part has been found, start to decode the next
                section of encoded data lines.  If this @code{skipfrom}
                does not correspond to the wanted part, continue to search
                for the correct @code{skipfrom} header.

          @item MISSING
                Issue a fatal error message and stop.

          @item INVALID
                Issue a non-fatal error message and ignore the header.
        @end table

  @item Example:
        @code{skipfrom 2 input-file.txt}@*
        @code{skipfrom 2 file name with spaces}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{skipto}
@c -------------------------------------------------------------------------
@page
@subsection @code{skipto}
@table @strong
  @item Purpose:
        Signifies the end of a segment of VVencoded data with more data
        still to come.

  @item Location:
        Continuation postamble (required).

  @item Syntax:
        @code{skipto <WS> part-number <WS> <EOL>}

  @item Remarks:
        The @code{skipto} is used when VVencode creates a multi-part VVE
        file and is analogous to the @code{end} header in the last part.
        The parameter records the number of the next VVE file part.

  @item VVencode:
        A @code{skipto} header will only be written if VVencode was invoked
        with the @code{split_size} command line qualifier and the VVE file
        is long enough to require more than one part.  The number of the
        next VVE file part is recorded.

        After the section of encoded files has been completed, VVencode
        will write a "zero length" encoded line followed by the @code{skipto}
        header line.

  @item VVdecode:
        After reading this header, VVdecode will check that the part number
        recorded is correct.  If it is, VVdecode will start to search for
        the next VVE file part.

        Processing rules:

        @table @code
          @item OK
                Start to search for the next VVE file part.

          @item MISSING
                Issue a fatal error message and stop.

          @item INVALID
                Issue a fatal error message and stop.
        @end table

  @item Example:
        @code{skipto 2}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{table}
@c -------------------------------------------------------------------------
@page
@subsection @code{table}
@table @strong
  @item Purpose:
        Records the character table used to encode the file data bytes.

  @item Location:
        Initial preamble, continuation preamble (optional).

  @item Syntax:
        @code{table <WS> table-contents <NXT-HDR>}

  @item Remarks:
        The encoding table is recorded along with the data to enable the
        decoding program to detect any simple character translations or
        corruptions that may have occurred during the transmission of the
        VVE file.  There is no restriction on the characters that may be
        used in the encoding table, but it is sensible to use characters
        that are normally immune to network corruptions.

        The table comprises 64 characters which are used to represent the
        codes 0 - 63 of the VVcode encoding character set.  The table
        contents may be presented on the same line as the @code{table}
        header or preferably split over several lines to avoid the wrapping
        of long lines performed by some mail gateways.  If the table
        contents are split over several lines, the newline characters are
        removed before the lines are concatenated.  The next valid header
        line encountered will terminate the reading of the table contents.

        Note that whitespace characters at the end of a line may be removed
        in transmission by certain systems that strip trailing whitespace
        from files.  It is strongly recommended that whitespace characters
        are not used in encoding tables.

  @item VVencode:
        VVencode will record the contents of the encoding table used to
        encode the original file.

  @item VVdecode:
        VVdecode will use the contents of the encoding table to construct
        (by inversion) the table to decode the VVE file data.  The table
        contents will be checked for length and repeated characters which
        would prevent the construction of a valid decoding table.

        Processing rules:

        @table @code
          @item OK
                Use the table contents to construct the decoding table and
                thus decode the VVE file.

          @item MISSING
                Assume the default VVcode table.

          @item INVALID
                Issue a fatal error message and stop.
        @end table

  @item Example:
        @code{table}@*
        @code{+-0123456789}@*
        @code{abcdefghijklmnopqrstuvwxyz}@*
        @code{ABCDEFGHIJKLMNOPQRSTUVWXYZ}@*
        @code{begin file-specification}
@end table



@c -------------------------------------------------------------------------
@c SUBSECTION: @code{timestamp}
@c -------------------------------------------------------------------------
@page
@subsection @code{timestamp}
@table @strong
  @item Purpose:
        Records the modification time of the VVencoded file.

  @item Location:
        Initial preamble (optional).

  @item Syntax:
        @code{timestamp <WS> VVcode-timestamp <WS> <EOL>}

  @item Remarks:
        This header is used to record the modification time of the encoded
        file so that it can be preserved when the file is decoded.  The
        timestamp is recorded in the format:

        @example
        YYYY.MM.DD-HH:MM:SS
        @end example
        
        where each of the components are defined as:

        @table @code
          @item YYYY 
                year (range: 1970 - 2037)
          @item MM
                month (range: 01 -12)
          @item DD
                day of month (range: 01 - 31)
          @item HH
                hour (range: 00 - 23)
          @item MM
                minutes (range: 00 - 59)
          @item SS
                seconds (range: 00 - 59)
        @end table
        
        The time is based on the Unix internal time format which represents
        the time as a signed 32 bit integer recording the number of seconds
        since 1-Jan-1970 00:00 GMT.  The VVE timestamp recorded must be in
        the range:

            1970.01.01-00:00:00  to  2037.12.31-23:59:59 GMT

        Some operating systems support a wider range of system times (e.g.
        VAX/VMS) and some support only a narrower range (e.g. MS-DOS) but
        implementations of VVcode for these systems must ensure that
        timestamps in the VVcode range can be handled when encoding and
        decoding.
          
        Note: The timestamp is always recorded as a GMT (or Coordinated
              Universal Time) time.

  @item VVencode:
        VVencode will record the modification time of the encoded file or
        that specified with the @code{timestamp} command line qualifier.
        If VVencode cannot determine the modification time of the encoded
        file and the time is not specified using the @code{timestamp}
        command line qualifier, the @code{timestamp} VVE header line will
        not be recorded.  If the timestamp of the file is outside the range
        of times supported by the VVE file, VVencode should either
        "truncate" the time value to a value that is within the range or
        not record the timestamp.  In either case, a warning should be
        issued.

  @item VVdecode:
        VVdecode will use the @code{timestamp} header value to set the
        modification of the decoded file to that recorded.  If the
        implementation of VVdecode is unable to do this, it should issue a
        warning.

        If the timestamp recorded in the VVE file is outside the range of
        times supported by the operating system, VVdecode should either
        "truncate" the time value to a value that is within the range or
        not set the file timestamp.  In either case, a warning should be
        issued.

        Processing rules:

        @table @code
          @item OK
                Use the header value to set the modification time of the
                decoded file.

          @item MISSING
                Do not attempt to set the modification time of the output
                file (it will probably be created with a timestamp of the
                current date and time).

          @item INVALID
                Issue a non-fatal error message and assume that the header
                is missing.
        @end table

  @item Example:
        @code{timestamp 1991.12.01-12:10:34 GMT}
@end table


@c =========================================================================
@c SECTION: VVE encoded data format
@c =========================================================================
@section VVE encoded data format


@c =========================================================================
@c SECTION: XLT translation file format
@c =========================================================================
@section XLT translation file format


@c =========================================================================
@c SECTION: TBL encoding table file format
@c =========================================================================
@section TBL encoding table file format