summaryrefslogtreecommitdiff
path: root/support/vvcode/doc/vvport.tex
blob: a385c5644d3d2764ab16ce01b2f64959785a2847 (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
@c *************************************************************************
@c CHAPTER: How to port VVcode to a new environment
@c *************************************************************************
@c    node-name, next, previous,  up
@node Porting Guide, Porting Guide, Top, Top
@chapter How to port VVcode to a new environment

This chapter introduces the facilities provided for porting VVcode to a new
environment and recommends the approach that should be taken for particular
examples.

@itemize @bullet
  @item introduction and philosophy
  @item @file{machine.h}
  @item @file{specific.h} and @file{xxx.c}
  @item local.h
@end itemize




@c =========================================================================
@c SECTION: The @file{os.h} header file
@c =========================================================================
@c    node-name, next, previous,  up
@section The @file{os.h} header file

The @file{os.h} file contains tests to identify the environment on which
VVcode is being built.  Once the environment has been identified the file
defines preprocessor macros to define the environment in the format
expected by VVcode.  Environments are defined as the operating system and
variants due to dialects of the operating system or the compiler.  

@itemize @bullet
  @item explain the @samp{OS_xxxx} macros, including the operating systems
        currently supported
  @item explain the @samp{UNIX_yyyy} and related macros
@end itemize



@c =========================================================================
@c SECTION: The @file{machine.h} header file
@c =========================================================================
@c    node-name, next, previous,  up
@section The @file{machine.h} header file

The header file @file{machine.h} 

@itemize @bullet
  @item defines macros to control the behaviour and compilation of VVcode
  @item several categories of definition required:

  @itemize @bullet
    @item environment
    @item command line interface
    @item file specifications
    @item file formats
  @end itemize
@end itemize


@c -------------------------------------------------------------------------
@c SUBSECTION: VVcode environment
@c -------------------------------------------------------------------------
@subsection VVcode Environment

@itemize @bullet
  @item definitions for the environment in which VVcode is built
@end itemize

@subsubsection @code{VV_OPERATING_SYSTEM}

A string recording the operating system for which this version of VVcode
has been implemented.  This value is recorded in the VVE file and used by
VVdecode to detect whether the original file was encoded on a different
operating system.  For example:

@example
#define VV_OPERATING_SYSTEM "MS-DOS"
@end example


@subsubsection @code{VV_IMPLEMENTATION}

A string describing the implementation of VVcode.  Displayed when VVcode
programs are started and recorded in log and VVE files.  For example:

@example
#define VV_IMPLEMENTATION "MS-DOS Turbo-C version 09.1-001 (31 May 1992)"
@end example


@subsubsection @code{ANSI_SYNTAX}

Define as @code{TRUE} if the compiler supports the draft ANSI standard for
C syntax (it shouldn't matter if the run time library is not fully ANSI
compliant).  Define as @code{FALSE} if this syntax is not supported.  The
macro is used to control the declaration of functions and the use of new
ANSI keywords such as @samp{const}.  If your compiler requires old-style
function declarations like:

@example
char *allocate_buffer ();  /* Declaration */
...
char *allocate_buffer (buf_len, buf_name)  /* Function code */
    size_t           buf_len;
    char            *buf_name;
@{
...
@}
@end example

you should define @code{ANSI_SYNTAX} to @code{FALSE}.  Many Unix systems
have compilers that fall into this category, though the GNU C compiler is a
notable exception.  If you have a modern compiler that accepts ANSI style
function declarations like:

@example
char *allocate_buffer (const size_t buf_len,  /* Declaration */
                       const char *buf_name);
...
char *allocate_buffer (const size_t buf_len,  /* Function code */        
                       const char *buf_name)
@{
...
@}
@end example

you should define @code{ANSI_SYNTAX} to @code{TRUE}.  The GNU C compiler
and most of the PC compilers support the ANSI standard.


@c -------------------------------------------------------------------------
@c SECTION: VVcode Command Line Interface
@c -------------------------------------------------------------------------
@subsection{VVcode Command Line Interface}

@itemize @bullet
 @item  defines how to start VVcode and how it interprets the command line
 @item  explain concepts of @dfn{parameters} and @dfn{qualifiers}
 @item  @dfn{parameters} - 
 @item  @dfn{qualifiers} - modify the behaviour of a command#
 @item  give an example and compare the commands @code{rm -i foo} and
        @code{delete /confirm foo}
 @item  this does not preclude implementations that may not usually use
        a command line interface (e.g. Mac).  For example VMS does use a
        CLI but provides a set of system services to handle the CL.  Under
        these circumstances these definitions will only be used to display
        help text in the correct format
@end itemize
    
@subsubsection @code{QUAL_INTRO}

A string containing a set of characters, each of which may be used to
introduce a command line qualifier.  For example:

@example
#define QUAL_INTRO "/-" /* MS-DOS */
#define QUAL_INTRO "-"  /* Unix */
@end example

The examples above indicate that on a Unix system @samp{-} would be used to
introduce a command qualifier, whereas on MS-DOS either @samp{-} or
@samp{/} could be used.


@subsubsection @code{QUAL_SEP}

A string containing a set of characters, each of which may be used to
separate a command line qualifier from its value.  For example:
    
@example
#define QUAL_SEP "=:-" /* MS-DOS */
#define QUAL_SEP " "   /* Unix */    
#define QUAL_SEP " "   /* Unix */    
@end example

The examples above indicate that on an MS-DOS system the qualifier value is
separated from the qualifier by one of the characters @samp{=}, @samp{:} or
@samp{-}.  The Unix example indicates that the value is separated from the
qualifier by a space, i.e. it is the next command line parameter.


@subsubsection @code{OPTIONAL_QUALIFIER_VALUES}

Define as @code{TRUE} if the operating system convention can handle command
line qualifiers with optional values.  On systems such as MS-DOS, VAX/VMS
and VM/CMS the qualifiers are separated from each other by spaces and from
their values by another character such as an equals sign (@samp{=}).  In
the following example it is obvious whether the optional value for the
@samp{log} qualifier is present:

@example
    vvencode /overwrite /log=log-file  ip-file op-file
    vvencode /overwrite /log           ip-file op-file
@end example

On Unix, the convention is to separate qualifiers from each other by spaces
and from their qualifiers by spaces.  In the following example it is
difficult if not impossible to determine whether the @samp{log} qualifier
value is present:

@example
    vvencode -overwrite -log log-file  ip-file op-file
    vvencode -overwrite -log           ip-file op-file
@end example

This problem could be overcome by forcing Unix users to use a different
character like @samp{=} to introduce the qualifier value or by imposing
strict rules on the ordering of parameters and qualifiers.  Neither of
these approaches is likely to be popular so we take the easy way out and
specify whether such optional qualifier values are supported.  If they are
not supported, the qualifiers which could take optional values are modified
either to require a value or to take no value.

Example:

@example
    #define OPTIONAL_QUALIFIER_VALUES TRUE   /* MS-DOS, VMS */
    #define OPTIONAL_QUALIFIER_VALUES FALSE  /* Unix */
@end example


@subsubsection @code{STICKY_DEFAULTS}

Define as @code{TRUE} if the VVcode programs should apply default file
names when determining output file specifications.  For example, on Unix
the definition would usually be:

@example
    #define STICKY_DEFAULTS FALSE  /* Unix */
@end example

and the commands:
   
@example
    vvencode one
    vvencode one two
    vvencode one two -log three
@end example

would create the files @file{one.vve}, @file{two}, and @file{two} plus a
log file @file{three} respectively.  On other systems such as MS-DOS and
VAX/VMS where default file names are customary the definition would usually
be 

@example
    #define STICKY_DEFAULTS TRUE  /* MS-DOS, VMS */
@end example

and the commands:
   
@example
    vvencode one
    vvencode one two
    vvencode one two -log three
@end example

would create the files @file{one.vve}, @file{two.vve} and @file{two.vve}
plus a log file @file{three.log} respectively. 


@subsubsection @code{STDOUT_OUTPUT}

Define as @code{TRUE} if the VVencode program should write to standard
output if an output file is not explicitly specified on the command line.
The command:

@example
    vvencode ip-file
@end example

would write the VVE file to standard output if @code{STDOUT_OUTPUT} is defined
as @code{TRUE} or to @file{ip-file.vve} if it is defined as @code{FALSE}.

Examples:

@example
    #define STDOUT_OUTPUT TRUE  /* Unix */
    #define STDOUT_OUTPUT FALSE /* MS-DOS, VMS */
@end example


@subsubsection @code{SUPPORT_PIPING}

Define as @code{TRUE} if the VVcode programs should support reading from
standard input and/or writing to standard output so that they may be used
as filters.  The programs do not behave as true filters since an input file
must always be specified, but specifying a certain string (e.g. @samp{-})
as the input file specification will cause the program to read from
standard input.  The string used is defined by the macro
@code{STDIO_SYMBOL}.

Examples:

@example
    #define SUPPORT_PIPING TRUE   /* Unix, MS-DOS */
    #define SUPPORT_PIPING FALSE  /* VMS, VM/CMS */
@end example

@subsubsection @code{STDIO_SYMBOL}

A string which when used as a file specification will cause the VVcode
programs to read/write to standard input/output depending on whether that
file is an input or output file.  This string is only used if the macro
@code{SUPPORT_PIPING} is defined as @code{TRUE}.  If it is unused, define
it as "".

On a Unix system, the following definitions would be usual:

@example
    #define SUPPORT_PIPING TRUE
    #define STDIO_SYMBOL   "-"  /* Unix, MS-DOS */
@end example

and piping a binary file into VVencode to could be achieved with the shell
command:

@example
    cat binary-file | vvencode - - | mail kempson@@TeX.Ac.Uk
@end example        


@c -------------------------------------------------------------------------
@c SECTION: File Specifications
@c -------------------------------------------------------------------------
@subsection File Specifications

explain here the VVcode file specification model and how it is used


@subsubsection @code{MAX_PATH}

The maximum number of characters allowed in a file specification.

Example:

@example
    #define MAX_PATH 80   /* MS-DOS */
    #define MAX_PATH 255  /* BSD Unix */
    #define MAX_PATH 255  /* VAX/VMS, some Unix */
@end example


@subsubsection @code{MAX_PREAMBLE}

The maximum number of characters in the preamble component of a file
specification.  If the system does not support a preamble component, define
as zero.
    
Example:

@example
    #define MAX_PREAMBLE 64   /* MS-DOS */
    #define MAX_PREAMBLE 255  /* BSD Unix */
    #define MAX_PREAMBLE 255  /* VAX/VMS */
@end example


@subsubsection @code{MAX_NAME}

The maximum number of characters in the name component of a file
specification.

Example:

@example
    #define MAX_NAME 8    /* MS-DOS */
    #define MAX_NAME 255  /* BSD Unix */
    #define MAX_NAME 39   /* VAX/VMS */
@end example


@subsubsection @code{MAX_EXT}

The maximum number of characters in the extension component of a file
specification.  If the system does not support an extension component,
define as zero.
    
Example: 

@example
    #define MAX_EXT 3    /* MS-DOS */
    #define MAX_EXT 255  /* BSD Unix */
    #define MAX_EXT 39   /* VAX/VMS */
@end example


@subsubsection @code{MAX_POSTAMBLE}

The maximum number of characters in the postamble component of a file
specification.  If the system does not support a postamble component,
define as zero.
    
Example:

@example
    #define MAX_POSTAMBLE 0  /* MS-DOS */
    #define MAX_POSTAMBLE 0  /* BSD Unix */
    #define MAX_POSTAMBLE 5  /* VAX/VMS */
@end example


@subsubsection @code{PREAMBLE_END}

A string containing a set of characters, each of which may be used to
denote the end of the preamble component of a file specification.  If the
system does not support a preamble component, define as "".
        
Example:

@example
    #define PREAMBLE_END ":\\"  /* MS-DOS */
    #define PREAMBLE_END ":/"   /* BSD Unix */
    #define PREAMBLE_END ":>]"  /* VAX/VMS */
@end example


@subsubsection @code{EXTENSION_BEGIN}

The single character that may be used to denote the start of the extension
component of a file specification.  If the system does not support an
extension component, define as @samp{\000}.
        
Example:

@example
    #define EXTENSION_BEGIN '.'  /* MS-DOS */
    #define EXTENSION_BEGIN '.'  /* BSD Unix */
    #define EXTENSION_BEGIN '.'  /* VAX/VMS */
@end example


@subsubsection @code{POSTAMBLE_BEGIN}

A string containing a set of characters, each of which may be used to denote
the start of the postamble component of a file specification.  If the system
does not support a postamble component, define as "".
        
Example:

@example
    #define POSTAMBLE_BEGIN ""   /* MS-DOS */
    #define POSTAMBLE_BEGIN ""   /* BSD Unix */
    #define POSTAMBLE_BEGIN ";"  /* VAX/VMS */
@end example    


@subsubsection @code{UPPERCASE_FILESYSTEM}

Define as @code{TRUE} if the file system is case insensitive.  For the
benefit of file systems that do care (where lower case names are usual),
VVencode will convert file specifications to lower case before recording
them in the VVE file.

Example:

@example
    #define UPPERCASE_FILESYSTEM TRUE   /* MS-DOS, VAX/VMS */
    #define UPPERCASE_FILESYSTEM FALSE  /* Unix */
@end example


@c -------------------------------------------------------------------------
@c SECTION: File Formats
@c -------------------------------------------------------------------------
@subsection{File Formats}

explain the different file formats and provide a small table showing how
they are used for different operating systems


@subsubsection @code{SUPPORT_FIXED_FMT}

Define as @code{TRUE} if the file system supports fixed length record
format  files.  

Example:

@example
    #define SUPPORT_FIXED_FORMAT TRUE   /* VAX/VMS, VM/CMS */
    #define SUPPORT_FIXED_FORMAT FALSE  /* MS-DOS, Unix */    
@end example    


@subsubsection @code{SUPPORT_STREAM_FMT}

Define as @code{TRUE} if the file system supports stream format files.  
    
Example:

@example
    #define SUPPORT_STREAM_FILES TRUE   /* MS-DOS, Unix, VAX/VMS */
    #define SUPPORT_STREAM_FILES FALSE  /* VM/CMS */
@end example


@subsubsection @code{SUPPORT_VARIABLE_FMT}

Define as @code{TRUE} if the file system supports variable length record
format files.  

Example:

@example
    #define SUPPORT_VARIABLE_FORMAT TRUE   /* VAX/VMS, VM/CMS */
    #define SUPPORT_VARIABLE_FORMAT FALSE  /* MS-DOS, Unix */    
@end example


@subsubsection @code{TEXT_LINE_OVERHEAD}

The extra number of characters written by the file system when writing
lines to text files.  For example, when writing to text files MS-DOS
converts @samp{\n} to @samp{\r\n} and therefore has an overhead of 1.

Example:

@example
    #define TEXT_LINE_OVERHEAD 1  /* MS-DOS, VAX/VMS */
    #define TEXT_LINE_OVERHEAD 0  /* Unix */
@end example


@subsubsection @code{DEF_MODE}

Define as the default mode for file encoding & decoding to be used if the
mode is not specified on the command line and cannot be determined from the
input file.  It must be @code{MODE_BINARY} or @code{MODE_TEXT}.
    
Example:

@example
    #define DEF_MODE MODE_BINARY  /* most systems */
@end example


@subsubsection @code{DEF_TEXT_FMT}

Define as the default file format for text files.  It must be one of
@code{FMT_FIXED}, @code{FMT_STREAM} and @code{FMT_VARIABLE} and only a
supported format may be specified.
    
Example:

@example
    #define DEF_TEXT_FMT FMT_STREAM    /* MS-DOS, Unix */
    #define DEF_TEXT_FMT FMT_VARIABLE  /* VAX/VMS */
@end example


@subsubsection @code{DEF_BINARY_FMT}

Define as the default file format for text files.  It must be one of
@code{FMT_FIXED}, @code{FMT_STREAM} and @code{FMT_VARIABLE} and only a
supported format may be specified.

Example:

@example
    #define DEF_BINARY_FMT FMT_STREAM  /* MS-DOS, Unix */
    #define DEF_BINARY_FMT FMT_FIXED   /* VAX/VMS */
@end example


@subsubsection @code{MIN_VARIABLE_RECORD_LEN}

The minimum record length in bytes supported by the file system for
variable length record format files.  Must be within the VVcode limits of 0
to 65535.  If the system doesn't support variable length record format files
define as @code{INV_RECORD_LEN}.

Example:

@example
    #define MIN_VARIABLE_RECORD_LEN INV_RECORD_LEN  /* MS-DOS, Unix */
    #define MIN_VARIABLE_RECORD_LEN 0               /* VAX/VMS */
@end example


@subsubsection @code{MAX_VARIABLE_RECORD_LEN}

The maximum record length in bytes supported by the file system for
variable length record format files.  Must be within the VVcode limits of 0
to 65535.  If the system doesn't support variable length record format files
define as @code{INV_RECORD_LEN}.

Example:

@example
    #define MAX_VARIABLE_RECORD_LEN INV_RECORD_LEN  /* MS-DOS, Unix */
    #define MAX_VARIABLE_RECORD_LEN 32765           /* VAX/VMS */
    #define MAX_VARIABLE_RECORD_LEN 65535           /* VM/CMS */
@end example


@subsubsection @code{DEF_VARIABLE_RECORD_LEN}

The default maximum record length in bytes supported by the file system for
variable length record format files.  Must be in the range defined by
@code{MIN_VARIABLE_RECORD_LEN} and @code{MAX_VARIABLE_RECORD_LEN}.  If the
system doesn't support variable length record format files define as
@code{INV_RECORD_LEN}.

Example:

@example
    #define DEF_VARIABLE_RECORD_LEN INV_RECORD_LEN  /* MS-DOS, Unix */
    #define DEF_VARIABLE_RECORD_LEN 512             /* VAX/VMS */
    #define DEF_VARIABLE_RECORD_LEN 255             /* VM/CMS */
@end example


@subsubsection @code{MIN_FIXED_RECORD_LEN}

The minimum record length in bytes supported by the file system for fixed
length record format files.  Must be within the VVcode limits of 0 to
65535.  If the system doesn't support fixed length record format files
define as @code{INV_RECORD_LEN}.

Example:

@example
    #define MIN_FIXED_RECORD_LEN INV_RECORD_LEN  /* MS-DOS, Unix */
    #define MIN_FIXED_RECORD_LEN 0               /* VAX/VMS */
@end example


@subsubsection @code{MAX_FIXED_RECORD_LEN}

The maximum record length in bytes supported by the file system for fixed
length record format files.  Must be within the VVcode limits of 0 to
65535.  If the system doesn't support fixed length record format files
define as @code{INV_RECORD_LEN}.

Example:

@example
    #define MAX_FIXED_RECORD_LEN INV_RECORD_LEN  /* MS-DOS, Unix */
    #define MAX_FIXED_RECORD_LEN 32765           /* VAX/VMS */
    #define MAX_FIXED_RECORD_LEN 65535           /* VM/CMS */
@end example


@subsubsection @code{DEF_FIXED_RECORD_LEN}

The default record length in bytes supported by the file system for fixed
length record format files.  Must be in the range defined by
@code{MIN_FIXED_RECORD_LEN} and @code{MAX_FIXED_RECORD_LEN}.  If the system
doesn't support fixed length record format files define as
@code{INV_RECORD_LEN}.

Example:

@example
    #define DEF_FIXED_RECORD_LEN INV_RECORD_LEN  /* MS-DOS, Unix */
    #define DEF_FIXED_RECORD_LEN 512             /* VAX/VMS */
    #define DEF_FIXED_RECORD_LEN 255             /* VM/CMS */
@end example


@subsubsection @code{DEF_TEXT_PADCHAR}

Define as the default character used to pad out short records in text fixed
length record format files.  Must be a valid character constant and will
usually be a space character.  If the system doesn't support fixed length
record format files, define as @samp{\000}.

Example:

@example
    #define DEF_TEXT_PADCHAR '\000' /* MS-DOS, Unix */
    #define DEF_TEXT_PADCHAR ' '   /* VAX/VMS, VM/CMS */
@end example


@subsubsection @code{DEF_BINARY_PADCHAR}

Define as the default character used to pad out short records in binary
fixed length record format files.  Must be a valid character constant and
will usually be a null character.  If the system doesn't support fixed
length record format files, define as '\000'.

Example:

@example
    #define DEF_BINARY_PADCHAR '\000'  /* MS_DOS, Unix */
    #define DEF_BINARY_PADCHAR '\000'  /* VAX/VMS, VM/CMS */
@end example                 



@c =========================================================================
@c SECTION: The @file{xxx.c} operating system specific module
@c =========================================================================
@section The @file{xxx.c} operating system specific module



@c =========================================================================
@c SECTION: Porting VVcode - an example
@c =========================================================================
@section Porting VVcode - an example