3rdparty/dtl/dv2dt.man

   1 .\" This file is public domain.
   2 .\" Originally written 1995, Geoffrey Tobin.
   3 .\" The author has expressed the hope that any modification will retain enough content to remain useful. He would also appreciate being acknowledged as the original author in the documentation.
   4 .\" This declaration added 2008/11/14 by Clea F. Rees with the permission of Geoffrey Tobin.
   5 .\" ====================================================================
   6 .\"  @Troff-man-file{
   7 .\"     author          = "Nelson H. F. Beebe and Geoffrey Tobin",
   8 .\"     version         = "0.6.0",
   9 .\"     date            = "08 March 1995",
  10 .\"     time            = "19:52:00 GMT +11",
  11 .\"     filename        = "dv2dt.man",
  12 .\"     address         = "Center for Scientific Computing
  13 .\"                        Department of Mathematics
  14 .\"                        University of Utah
  15 .\"                        Salt Lake City, UT 84112
  16 .\"                        USA",
  17 .\"     telephone       = "+1 801 581 5254",
  18 .\"     FAX             = "+1 801 581 4148",
  19 .\"     checksum        = "32328 715 2191 12898",
  20 .\"     email           = "beebe@math.utah.edu (Internet)",
  21 .\"     codetable       = "ISO/ASCII",
  22 .\"     keywords        = "DVI, TeX",
  23 .\"     supported       = "no",
  24 .\"     docstring       = "This file contains the UNIX manual pages
  25 .\"                        for the dv2dt utility, a program for
  26 .\"                        converting a binary TeX DVI file to an
  27 .\"                        editable text representation in DTL (DVI Text
  28 .\"                        Language).  The companion dt2dv utility can
  29 .\"                        convert the output DTL file back to a binary
  30 .\"                        DVI file.
  31 .\"
  32 .\"                        The checksum field above contains a CRC-16
  33 .\"                        checksum as the first value, followed by the
  34 .\"                        equivalent of the standard UNIX wc (word
  35 .\"                        count) utility output of lines, words, and
  36 .\"                        characters.  This is produced by Robert
  37 .\"                        Solovay's checksum utility.",
  38 .\"  }
  39 .\" ====================================================================
  40 .if t .ds Te T\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X
  41 .if n .ds Te TeX
  42 .if t .ds Xe X\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'T
  43 .if n .ds Xe XeT
  44 .TH DV2DT 1 "08 March 1995" "Version 0.6.0"
  45 .\"======================================================================
  46 .SH NAME
  47 dv2dt \- convert a binary TeX DVI file to DTL text representation
  48 .\"======================================================================
  49 .SH SYNOPSIS
  50 .B dv2dt
  51 .I input-DVI-file
  52 .I output-DTL-file
  53 .PP
  54 If the filenames are omitted, then
  55 .I stdin
  56 and
  57 .I stdout
  58 are assumed.
  59 .\"======================================================================
  60 .SH DESCRIPTION
  61 .B dv2dt
  62 converts a binary \*(Te\& DVI file to an editable
  63 text file in DTL
  64 .RI ( "DVI Text Language" )
  65 format.  The companion
  66 .BR dt2dv (1)
  67 utility can convert the DTL file back to a binary
  68 DVI file.
  69 .\"======================================================================
  70 .SH "DVI COMMAND DESCRIPTION"
  71 \*(Te\& DVI files contain a compact binary
  72 description of typeset pages, as a stream of
  73 operation code bytes, each immediately followed by
  74 zero or more parameter bytes.  The format of DVI
  75 files is fully described in Donald E. Knuth,
  76 .IR "\*(Te\&: The Program" ,
  77 Addison-Wesley (1986), ISBN 0-201-13437-3, as well
  78 as in the
  79 .BR dvitype (1)
  80 literate program source code.
  81 .PP
  82 For convenience, we provide a summary of DVI
  83 commands here.  In the following list, operation
  84 code bytes are given as unsigned decimal values,
  85 followed by their symbolic names (not present in
  86 the DVI file), and a short description.  A
  87 designation like
  88 .I b[+n]
  89 means that the operation code byte is followed by
  90 a parameter
  91 .I b
  92 which uses
  93 .I n
  94 bytes, and is signed.  Without the plus sign, the
  95 parameter is unsigned.  Signed integer parameter
  96 values are always represented in two's complement
  97 arithmetic, which is the system followed by most
  98 computers manufactured today, including all
  99 personal computers and workstations.
 100 .if n .TP \w'\fI128_set1__c[1]\fP'u+3n
 101 .if t .TP \w'\fI243_fnt_def1__k[1]_c[4]_s[4]_d[4]_a[1]_l[1]_n[a+l]\fP'u+3n
 102 .I "0 set_char_0"
 103 Set character 0 from current font.
 104 .TP
 105 .I .\|.\|.
 106 .TP
 107 .I "127 set_char_127"
 108 Set character 127 from current font.
 109 .TP
 110 .I "128 set1  c[1]"
 111 Set 1-byte unsigned character (uchar) number
 112 .IR c .
 113 .TP
 114 .I "129 set2  c[2]"
 115 Set 2-byte uchar number
 116 .IR c .
 117 .TP
 118 .I "130 set3  c[3]"
 119 Set 3-byte uchar number
 120 .IR c .
 121 .TP
 122 .I "131 set4  c[+4]"
 123 Set 4-byte signed character (schar) number
 124 .IR c .
 125 .TP
 126 .I "132 set_rule  a[+4]  b[+4]"
 127 Set rule, height
 128 .IR a ,
 129 width
 130 .IR b .
 131 .TP
 132 .I "133 put1  c[1]"
 133 Put 1-byte uchar
 134 .IR c .
 135 .TP
 136 .I "134 put2  c[2]"
 137 Put 2-byte uchar
 138 .IR c .
 139 .TP
 140 .I "135 put3  c[3]"
 141 Put 3-byte uchar
 142 .IR c .
 143 .TP
 144 .I "136 put4  c[+4]"
 145 Put 4-byte schar
 146 .IR c .
 147 .TP
 148 .I "137 put_rule  a[+4]  b[+4]"
 149 Put rule, height
 150 .IR a ,
 151 width
 152 .IR b .
 153 .TP
 154 .I "138 nop"
 155 Do nothing.
 156 .TP
 157 .I "139 bop  c0[+4]  .\|.\|.  c9[+4]  p[+4]"
 158 Beginning of page.  The parameters
 159 .I "c0  .\|.\|.  c9"
 160 are the \*(Te\& page counters, the contents of
 161 \*(Te\& count registers
 162 .IR "\ecount0  .\|.\|.  \ecount9" .
 163 The parameter
 164 .I p
 165 is the byte offset from the beginning of the DVI
 166 file of the previous
 167 .I bop
 168 operation code byte.  The first such command in
 169 the file has
 170 .IR "p = \-1" .
 171 .TP
 172 .I "140 eop"
 173 End of page.
 174 .TP
 175 .I "141 push"
 176 Push
 177 .RI ( h,v,w,x,y,z )
 178 onto stack.
 179 .TP
 180 .I "142 pop"
 181 Pop
 182 .RI ( h,v,w,x,y,z )
 183 from stack.
 184 .TP
 185 .I "143 right1  b[+1]"
 186 Move right
 187 .I b
 188 units.
 189 .TP
 190 .I "144 right2  b[+2]"
 191 Move right
 192 .I b
 193 units.
 194 .TP
 195 .I "145 right3  b[+3]"
 196 Move right
 197 .I b
 198 units.
 199 .TP
 200 .I "146 right4  b[+4]"
 201 Move right
 202 .I b
 203 units.
 204 .TP
 205 .I "147 w0"
 206 Move right
 207 .I w
 208 units.
 209 .TP
 210 .I "148 w1  b[+1]"
 211 Move right
 212 .I b
 213 units, and set
 214 .IR "w = b" .
 215 .TP
 216 .I "149 w2  b[+2]"
 217 Move right
 218 .I b
 219 units, and set
 220 .IR "w = b" .
 221 .TP
 222 .I "150 w3  b[+3]"
 223 Move right
 224 .I b
 225 units, and set
 226 .IR "w = b" .
 227 .TP
 228 .I "151 w4  b[+4]"
 229 Move right
 230 .I b
 231 units, and set
 232 .IR "w = b" .
 233 .TP
 234 .I "152 x0"
 235 Move right
 236 .I x
 237 units.
 238 .TP
 239 .I "153 x1  b[+1]"
 240 Move right
 241 .I b
 242 units, and set
 243 .IR "x = b" .
 244 .TP
 245 .I "154 x2  b[+2]"
 246 Move right
 247 .I b
 248 units, and set
 249 .IR "x = b" .
 250 .TP
 251 .I "155 x3  b[+3]"
 252 Move right
 253 .I b
 254 units, and set
 255 .IR "x = b" .
 256 .TP
 257 .I "156 x4  b[+4]"
 258 Move right
 259 .I b
 260 units, and set
 261 .IR "x = b" .
 262 .TP
 263 .I "157 down1  a[+1]"
 264 Move down
 265 .I a
 266 units.
 267 .TP
 268 .I "158 down2  a[+2]"
 269 Move down
 270 .I a
 271 units.
 272 .TP
 273 .I "159 down3  a[+3]"
 274 Move down
 275 .I a
 276 units.
 277 .TP
 278 .I "160 down4  a[+4]"
 279 Move down
 280 .I a
 281 units.
 282 .TP
 283 .I "161 y0"
 284 Move right
 285 .I y
 286 units.
 287 .TP
 288 .I "162 y1  a[+1]"
 289 Move right
 290 .I a
 291 units, and set
 292 .IR "y = a" .
 293 .TP
 294 .I "163 y2  a[+2]"
 295 Move right
 296 .I a
 297 units, and set
 298 .IR "y = a" .
 299 .TP
 300 .I "164 y3  a[+3]"
 301 Move right
 302 .I a
 303 units, and set
 304 .IR "y = a" .
 305 .TP
 306 .I "165 y4  a[+4]"
 307 Move right
 308 .I a
 309 units, and set
 310 .IR "y = a" .
 311 .TP
 312 .I "166 z0"
 313 Move right
 314 .I z
 315 units.
 316 .TP
 317 .I "167 z1  a[+1]"
 318 Move right
 319 .I a
 320 units, and set
 321 .IR "z = a" .
 322 .TP
 323 .I "168 z2  a[+2]"
 324 Move right
 325 .I a
 326 units, and set
 327 .IR "z = a" .
 328 .TP
 329 .I "169 z3  a[+3]"
 330 Move right
 331 .I a
 332 units, and set
 333 .IR "z = a" .
 334 .TP
 335 .I "170 z4  a[+4]"
 336 Move right
 337 .I a
 338 units, and set
 339 .IR "z = a" .
 340 .TP
 341 .I "171 fnt_num_0"
 342 Set current font number
 343 .IR "(f) = 0" .
 344 .TP
 345 .I .\|.\|.
 346 .TP
 347 .I "234 fnt_num_63"
 348 Set
 349 .IR "f = 63" .
 350 .TP
 351 .I "235 fnt1  k[1]"
 352 Set
 353 .IR "f = k" .
 354 .TP
 355 .I "236 fnt2  k[2]"
 356 Set
 357 .IR "f = k" .
 358 .TP
 359 .I "237 fnt3  k[3]"
 360 Set
 361 .IR "f = k" .
 362 .TP
 363 .I "238 fnt4  k[+4]"
 364 Set
 365 .IR "f = k" .
 366 .TP
 367 .I "239 xxx1  k[1]  x[k]"
 368 Special string
 369 .I x
 370 with
 371 .I k
 372 bytes.
 373 .TP
 374 .I "240 xxx2  k[2]  x[k]"
 375 Special string
 376 .I x
 377 with
 378 .I k
 379 bytes.
 380 .TP
 381 .I "241 xxx3  k[3]  x[k]"
 382 Special string
 383 .I x
 384 with
 385 .I k
 386 bytes.
 387 .TP
 388 .I "242 xxx4  k[4]  x[k]"
 389 Special string
 390 .I x
 391 with (unsigned)
 392 .I k
 393 bytes.
 394 .TP
 395 .I "243 fnt_def1  k[1] c[4] s[4] d[4] a[1] l[1] n[a+l]"
 396 Define font
 397 .IR k .
 398 The parameters are:
 399 .RS
 400 .TP \w'\fIm\fP'u+3n
 401 .I c
 402 Checksum for TFM file.
 403 .TP
 404 .I s
 405 Scale factor, in DVI units.
 406 .TP
 407 .I d
 408 Design size, in DVI units.
 409 .TP
 410 .I a
 411 Length of the ``area'' or directory.
 412 .TP
 413 .I l
 414 Length of the font name.
 415 .TP
 416 .I n
 417 Area and font name string(s).
 418 .RE
 419 .TP
 420 .I "244 fnt_def2  k[2] c[4] s[4] d[4] a[1] l[1] n[a+l]"
 421 Define font
 422 .IR k .
 423 .TP
 424 .I "245 fnt_def3  k[3] c[4] s[4] d[4] a[1] l[1] n[a+l]"
 425 Define font
 426 .IR k .
 427 .TP
 428 .I "246 fnt_def4  k[+4] c[4] s[4] d[4] a[1] l[1] n[a+l]"
 429 Define font
 430 .IR k .
 431 .TP
 432 .I "247 pre  i[1]  num[4]  den[4]  mag[4]  k[1]  x[k]"
 433 Begin preamble.  The parameters are:
 434 .RS
 435 .TP \w'\fInum\fP'u+3n
 436 .I i
 437 DVI format.  Standard \*(Te\& has
 438 .IR "ID = 2" ,
 439 and \*(Te\&-\*(Xe\& has
 440 .IR "ID = 3" .
 441 .TP
 442 .I num
 443 Numerator of 100 nm / DVI unit.
 444 .TP
 445 .I den
 446 Denominator of 100 nm / DVI unit.
 447 .TP
 448 .I mag
 449 1000 * magnification.
 450 .TP
 451 .I k
 452 Comment length.
 453 .TP
 454 .I x
 455 Comment string.
 456 .RE
 457 .TP
 458 .I "248 post  p[4] num[4] den[4] mag[4] l[4] u[4] s[2] t[2]"
 459 Begin postamble.  The parameters are:
 460 .RS
 461 .TP \w'\fInum\fP'u+3n
 462 .I p
 463 Pointer to final bop.
 464 .TP
 465 .I "num, den, mag"
 466 Duplicates of values in preamble.
 467 .TP
 468 .I l
 469 Height-plus-depth of tallest page, in DVI units.
 470 .TP
 471 .I u
 472 Width of widest page, in DVI units.
 473 .TP
 474 .I s
 475 Maximum stack depth needed to process this DVI file.
 476 .TP
 477 .I t
 478 Total number of pages
 479 .RI ( bop
 480 commands) present.
 481 .RE
 482 .TP
 483 .I "249 post_post  q[4] i[1] 223 .\|.\|. 223"
 484 End postamble.  The parameters are:
 485 .RS
 486 .TP \w'\fI223\fP'u+3n
 487 .I q
 488 Byte offset from the beginning of the DVI file to
 489 the
 490 .I post
 491 command that started the postamble.
 492 .TP
 493 .I i
 494 DVI format ID, as in the preamble.
 495 .TP
 496 .I
 497 223
 498 At least four
 499 .I 223
 500 bytes.
 501 .RE
 502 .TP
 503 .I "250"
 504 Undefined.
 505 .TP
 506 .I .\|.\|.
 507 .TP
 508 .I "255"
 509 Undefined.
 510 .\"======================================================================
 511 .SH "DTL COMMAND DESCRIPTION"
 512 A DTL file contains one line per command, with a
 513 limit of 1024 characters per line.  Each command
 514 contains a symbolic operation name, followed by
 515 zero or more parameter values.  The parameter
 516 value descriptions are not repeated here; they can
 517 be found in the previous section.
 518 .TP \w'\fIw0,_w1,_w2,_w3,_w4\fP'u+3n
 519 variety <variety-name>
 520 This command specifies the name of the DTL file
 521 type; it has no DVI file equivalent.
 522 .TP
 523 .I (text)
 524 Series of set_char commands, for printable ASCII text.
 525 .TP
 526 .I \e(
 527 Literal ASCII left parenthesis in (text).
 528 .TP
 529 .I \e)
 530 Literal ASCII right parenthesis in (text).
 531 .TP
 532 .I \e\e
 533 Literal ASCII backslash in (text).
 534 .TP
 535 .I \e"
 536 Literal ASCII double quote in (text).
 537 .TP
 538 .I \eXY
 539 Set_char for character with hexadecimal code XY,
 540 not in parentheses, but by itself for readability.
 541 .TP
 542 .I "s1, s2, s2, s3"
 543 Set, with (1,2,3,4)-byte charcodes.
 544 .TP
 545 .I sr
 546 .IR set_rule .
 547 .TP
 548 .I "p1, p2, p2, p3"
 549 Put, with (1,2,3,4)-byte charcodes.
 550 .TP
 551 .I pr
 552 .IR put_rule .
 553 .TP
 554 .I nop
 555 .I nop
 556 (do nothing).
 557 .TP
 558 .I bop
 559 .I bop
 560 (beginning of page).
 561 .TP
 562 .I eop
 563 .I eop
 564 (end of page).
 565 .TP
 566 .I [
 567 Push.
 568 .TP
 569 .I ]
 570 Pop.
 571 .TP
 572 .I "r1, r2, r3, r4"
 573 Right, with (1,2,3,4)-byte argument.
 574 .TP
 575 .I "w0, w1, w2, w3, w4"
 576 As in DVI.
 577 .TP
 578 .I "x0, x1, x2, x3, x4"
 579 As in DVI.
 580 .TP
 581 .I "d1, d2, d3, d4"
 582 Down, with (1,2,3,4)-byte argument.
 583 .TP
 584 .I "y0, y1, y2, y3, y4"
 585 As in DVI.
 586 .TP
 587 .I "z0, z1, z2, z3, z4"
 588 As in DVI.
 589 .TP
 590 .I fn
 591 .I fnt_num
 592 (set current font to font number in 0 to 63).
 593 .TP
 594 .I "f1, f2, f3, f4"
 595 .I fnt
 596 (set current font to (1,2,3,4)-byte font number).
 597 .TP
 598 .I special
 599 .I xxx
 600 (special commands with (1,2,3,4)-byte string length).
 601 .TP
 602 .I fd
 603 .I fnt_def
 604 (assign a number to a named font).
 605 .TP
 606 .I pre
 607 Preamble.
 608 .TP
 609 .I post
 610 .I post
 611 (begin postamble).
 612 .TP
 613 .I post_post
 614 .I post_post
 615 (end postamble).
 616 .TP
 617 .I opcode
 618 Undefined DVI command (250 to 255).
 619 .\"======================================================================
 620 .SH "SAMPLE DTL FILE"
 621 The following 2-line \*(Te\& file
 622 .RS
 623 .nf
 624 Hello.
 625 \ebye
 626 .fi
 627 .RE
 628 when processed with the commands
 629 .RS
 630 .nf
 631 tex hello.tex
 632 dv2dt hello.dvi hello.dtl
 633 .fi
 634 .RE
 635 produces this DTL file:
 636 .RS
 637 .nf
 638 variety sequences-6
 639 pre 2 25400000 473628672 1000 27 ' TeX output 1995.03.02:2334'
 640 bop 1 0 0 0 0 0 0 0 0 0 -1
 641 [
 642 d3 -917504
 643 ]
 644 d4 42152922
 645 [
 646 d4 -41497562
 647 [
 648 r3 1310720
 649 fd1 0 11374260171 655360 655360 0 5 '' 'cmr10'
 650 fn0
 651 (Hello.)
 652 ]
 653 ]
 654 d3 1572864
 655 [
 656 r4 15229091
 657 (1)
 658 ]
 659 eop
 660 post 42 25400000 473628672 1000 43725786 30785863 2 1
 661 fd1 0 11374260171 655360 655360 0 5 'cmr10'
 662 post_post 152 2 223 223 223 223
 663 .fi
 664 .RE
 665 The command
 666 .RS
 667 .nf
 668 dt2dv hello.dtl hello.dvi
 669 .fi
 670 .RE
 671 will reconstruct the original DVI file.
 672 .\"======================================================================
 673 .SH "SEE ALSO"
 674 .BR dt2dv (1),
 675 .BR dvitype (1),
 676 .BR tex (1).
 677 .\"======================================================================
 678 .SH FILES
 679 .TP \w'\fI*.dvi\fP'u+3n
 680 .I *.dvi
 681 binary \*(Te\& DVI file.
 682 .TP
 683 .I *.dtl
 684 text representation of a \*(Te\& DVI file in
 685 .I "DVI Text Language"
 686 format.
 687 .\"======================================================================
 688 .SH AUTHOR
 689 .B dv2dt
 690 and
 691 .BR dt2dv (1)
 692 were written by
 693 .RS
 694 .nf
 695 Geoffrey Tobin
 696 Department of Electronic Engineering
 697 La Trobe University
 698 Bundoora, Victoria 3083
 699 Australia
 700 Tel: +61 3 479 3736
 701 FAX: +61 3 479 3025
 702 Email: <G.Tobin@ee.latrobe.edu.au>
 703 .fi
 704 .RE
 705 .PP
 706 These manual pages were primarily written by
 707 .RS
 708 .nf
 709 Nelson H. F. Beebe, Ph.D.
 710 Center for Scientific Computing
 711 Department of Mathematics
 712 University of Utah
 713 Salt Lake City, UT 84112
 714 Tel: +1 801 581 5254
 715 FAX: +1 801 581 4148
 716 Email: <beebe@math.utah.edu>
 717 .fi
 718 .RE
 719 .\"==============================[The End]==============================