Subject: Re: DVIDOC update
To: [email-masked].#Internet, [email-masked].#Internet
Cc: [email-masked].#Internet

I just discovered I had put the old DVIDOC.HLP file on the system
instead of my  new one.  I fixed that, and here it is:

File DVIDOC.HLP:
------------------------------------------------------------
         DVIDOC -- DVI to ASCII Print File Utility
                        [05-Oct-86]

The program DVIDOC will  convert a DVI file  into a ``DOC''  file
for  display  on  a  terminal  or  line  printer.   It  will  put
characters into  the  DOC  file  as  close  as  possible  to  the
positions specified by TeX, so without careful choice of font and
spacing, characters will obliterate others.

At Ohio State University where  DVIDOC was developed, there is  a
font called DOC that works fairly well in this mode.  To make use
of it  instead  of  the plain  format's  default  roman,  italic,
slanted, bold, and typewriter fonts, make the first line in  your
TeX file `\input docmac', or run TeX like

TeX \input docmac \input yourfile

Remember that if you do it  this way, the output files will  have
names ``docmac.*'' instead of ``yourfile.*''.

Math mode with DVIDOC will not be very readable, because most  of
the font characters do not have ordinary ASCII counterparts.

DVIDOC will prompt you for the names of the DVI file and the  DOC
file.  These you  should enter  with their  extensions.  It  then
will ask you for  five parameter values, one  at a time.  If  you
like the default values  given in the prompts,  you can reply  to
each question with just a carriage return.  The prompts are for:

    (1) the page number at which DVIDOC should start
        translating,
    (2) the maximum number of pages that should be translated,
    (3) the number of characters per inch horizontally of the
        ultimate output device,
    (4) the number of characters per inch vertically of the
        output device, and
    (5) the magnification factor to apply.

In response to the page number prompt, if you are using the plain
format with no tricks, just type the decimal integer page  number
where you want translation to start.  Actually, however,  DVIDOC,
will accept up to  ten fields separated  by periods.  The  fields
may be integers or asterisks, and DVIDOC looks for the first page
in  the  DVI  file  that  has  counter  values  that  meet   this
specification.  Integers must  match exactly,  and the  asterisks
are ``wild cards.''

The  resolutions  should  be  specified  as  explicit  ratios  of
integers, such as ``10/1'' for 10 characters per inch.

The magnification should be 1000  times the fraction you  choose.
Thus, a magnification of 2000  means increase all dimension by  a
factor of two.

The last three prompts  shoud be answered in  the default if  you
are using docmac.

Here is a  PHOTO log of  a sample DVIDOC  session, using its  own
DVIDOC.DVI file.  Only a single page is selected for output,  the
first time with default page resolution, and the second time with
a higher  resolution.  Then  TeX is  run again  using the  docmac
macros, and DVIDOC is run twice  more.  You can see by  comparing
these pairs  of output  that using  ``\input docmac''  makes  the
result much more readable.

[PHOTO:  Recording initiated  Mon 6-Oct-86 2:21PM]

 TOPS-20 Command processor 5(712)
@
@
@
@
@
@dvidoc
DVIFILE    : dvidoc.dvi
DOCFILE    : dvidoc.dvidoc
This is DVIDOC, TOPS-20 Version 1.1a
Starting page (default=*): 13
Maximum number of pages (default=1000000): 1
Horizontal resolution in characters per inch (default=10/1):

Vertical resolution in lines per inch (default=6/1):

New magnification (default=0 to keep the old one):

' TeX output 1986.10.06:1357'
Font 50: cmtex10---loaded at size 655360 DVI units

Font 47: cmtt10---loaded at size 943718 DVI units
 (this font is magnified 144%)

Font 46: cmr7---loaded at size 951451 DVI units
 (this font is magnified 207%)

Font 36: cmti10---loaded at size 655360 DVI units

Font 29: cmtt10---loaded at size 655360 DVI units

Font 23: cmbx10---loaded at size 655360 DVI units

Font 18: cmex10---loaded at size 655360 DVI units

Font 15: cmsy7---loaded at size 458752 DVI units

Font 12: cmsy10---loaded at size 655360 DVI units

Font 9: cmmi7---loaded at size 458752 DVI units

Font 6: cmmi10---loaded at size 655360 DVI units

Font 3: cmr7---loaded at size 458752 DVI units

Font 2: cmr8---loaded at size 524288 DVI units

Font 1: cmr9---loaded at size 589824 DVI units

Font 0: cmr10---loaded at size 655360 DVI units

Beginning of page 13
 warning: |h|>30785869! warning: |h|>30785870!

@type dvidoc.dvidoc
x33 DVDOC                               READNGTHEFONTNFORMATON  13

33. ADVreadngprogrusuayworkwthont?esnsteofTFM?essDVIDOs atypcnthat
respecFon?esshoudhowevecontaexactthsamecharacwdthdatathasoundn the
corresponTFs.n addtoont?esusuayasocontathwdthofcharactnpxes,sncthe
devcendependcharacwdthsoTFM?esargeneranoperecmutpesopxes.
 Thepxe-wdharracontanthnormatonwhenwdhk s thdevcendependwdthofsome
characneDVIuntspxewdhk]s thcorresponwdthofthacharacneanactuont.The
macrchapxe-wdhs seuptobeanaogotochawdh.
 de?nechapxewdh ()?pxe-wdh wdh-bas#]+chawdh-end
hGobasntheoutbock10i+?
pxewdh :arra0: maxwdhsof nege; factucharacwdthsnpxesg
horcon:rea; fconveDVIunttohorzonpxesg
vercon:re;lfconveDVIunttovertcpxesg
ruehorcon:rea;fconverunmagn?eDVuntstpxesg
ruevercon:re;lfconveunmagn?eDVIunttopxesg
numeradenomnaor:nege; fstatconversratog
mag:nege; fmagn?catactotmes1000g

34. TheoowngcodecomputpxewdthsbysmpyroundntheTFwdthstothnearenteger
numbeofpxesbaseonthconversactohorconvthaconveDVIunttopxes.
 de?nehorzpxerou(#)?run(horconv?()+05)
 de?neverpxeroun()?runc(vecon?(#+ 05)

hMovthewdthrom nwdh towdh,andappenpxewdh vaue3i?
 wdh-basnf? wdh-pr? on-bnf;
 f wp> 0then
   ork? wdh-prtowp?1 do
    begnwdh k]?n-wdh wdhk ;pxe-wdhk]? horpxeroun(wdhk);
    end
Thscoseuen econ28.
@
@! Notice that many characters are missing; they were overwritten
@! by other characters whose positions rounded to the same row
@! and column on the output page.
@!
@! Now let us repeat the exercise, using a higher resolution printer
@
@dvidoc
DVIFILE    : dvidoc.dvi
DOCFILE    : dvidoc.dvidoc
This is DVIDOC, TOPS-20 Version 1.1a
Starting page (default=*): 13
Maximum number of pages (default=1000000): 1
Horizontal resolution in characters per inch (default=10/1): 16/1
Vertical resolution in lines per inch (default=6/1): 8/1
New magnification (default=0 to keep the old one):

' TeX output 1986.10.06:1357'
Font 50: cmtex10---loaded at size 655360 DVI units

Font 47: cmtt10---loaded at size 943718 DVI units
 (this font is magnified 144%)

Font 46: cmr7---loaded at size 951451 DVI units
 (this font is magnified 207%)

Font 36: cmti10---loaded at size 655360 DVI units

Font 29: cmtt10---loaded at size 655360 DVI units

Font 23: cmbx10---loaded at size 655360 DVI units

Font 18: cmex10---loaded at size 655360 DVI units

Font 15: cmsy7---loaded at size 458752 DVI units

Font 12: cmsy10---loaded at size 655360 DVI units

Font 9: cmmi7---loaded at size 458752 DVI units

Font 6: cmmi10---loaded at size 655360 DVI units

Font 3: cmr7---loaded at size 458752 DVI units

Font 2: cmr8---loaded at size 524288 DVI units

Font 1: cmr9---loaded at size 589824 DVI units

Font 0: cmr10---loaded at size 655360 DVI units

Beginning of page 13
 warning: |h|>30785869! warning: |h|>30785870!
@type dvidoc.dvidoc
x33    DVIDOC                                                   READING  THE  FONT  INFO
RM ATION      13

33.   A DVI -readingprogram  usually w orksw ithfont ?lesinstead ofTFM ?les,so DVIDOC  i
satypicalin that
respect. Font  ?lesshould, how ever, contain exactly the sam echaracter w idth data that
 is found in the
corresponding TFM s.In addition, font?les usuallyalso contain the w idthsofcharacters in
 pixelssince the
device-independent character w idthsof TFM ?lesare generallynot perfect m ultipleof pixe
ls.

  T he pixelwidth array contains thisinform ation;w hen width[k] isthe device-independen
t w idth ofsom e
character in DVI units,pixelwidth [k]is the corresponding w idthof that character inan
actualfont. T he
m acro char-pixelwidth isset up to be analogous to char-width.

  de?ne   char-pixelwidth(#) ? pixelwidth  [width-base[#]+ char-width-end

hG lobalsin the outerblock 10 i+ ?
pixelwidth :array  [0::m ax-widths ]of integer;  factual character w idths,inpixelsg
horiz-conv: real; fconverts  DVI unitsto horizontalpixelsg

vert-conv: real; fconverts  DVI unitsto verticalpixelsg
true-horizconv : rea;  fconverts unm agni?ed  DVI units topixelsg
true-vertconv :real;  fconverts unm agni?ed  DVI units topixelsg

num erator;denom inator :integer;  fstated conversion ratiog
m ag: integer;  fm agni?cation factortim es1000g

34.   T hefollow ingcode com putes pixelw idths by sim plyrounding  theTFM  w idthsto th
e nearestinteger
num ber of pixelsbased  on theconversion factor horizconv  thatconverts DVI units to pix
els.

  de?ne   horizpixelround (#) ? trunc (horizconv ? (#)+ 0:5)
  de?ne   vertpixelround (#) ? trunc(vert-conv ? (#)+ 0:5)

hM ove the w idthsfrom in-width to width, and append  pixelwidth values 34i ?
  width-base[nf ]?  width-ptr? font-bc[nf];
  if wp > 0 then

    for k ?  width-ptr to wp ? 1 do
       begin width [k]?  inwidth [width[k]];pixelwidth[k]?  horiz-pixelround (width[k]);
       end

Thiscode isusedinsectio28.
@pop

[PHOTO:  Recording terminated  Mon 6-Oct-86 2:23PM]

[PHOTO:  Recording initiated  Mon 6-Oct-86 2:49PM]

 TOPS-20 Command processor 5(712)
@
@tex \input docmac \input dvidoc
This is TeX, Tops-20 Version 1.1 (preloaded format=plain 86.8.19)
(APS:<BEEBE.TEX.DVIDOC>DOCMAC.TEX.1) (APS:<BEEBE.TEX.DVIDOC>DVIDOC.TEX.6
(APS:<TEX.INPUTS>WEBMAC.TEX.1) *1 [2] [3] *8 [4] [5] *13 [6] *15 [7] [8]
[9] [10] *23 [11] [12] [13] [14] [15] [16] [17] *35 [18] [19] [20] [21]
[22] *50 [23] [24] [25] [26] *60 [27] [28] *65 [29] [30] [31] [32] [33]
[34] [35] [36] [37] *88 [38] *92 [39] [40] *95 [41] *98 [42] [43] *103 [44]
*104 Index:[45] [46] [47] [48] Section names: [49] [50] Table of contents:
(APS:<BEEBE.TEX.DVIDOC>CONTENTS.TEX.2) [1]
(see the transcript file for additional information)
Output written on APS:<BEEBE.TEX.DVIDOC>DOCMAC.DVI.1 (50 pages, 177392 bytes).
Transcript written on APS:<BEEBE.TEX.DVIDOC>DOCMAC.LST.1.
@
@
@dvidoc
DVIFILE    : docmac.dvi
DOCFILE    : dvidoc.dvidoc
This is DVIDOC, TOPS-20 Version 1.1a
Starting page (default=*): 17
Maximum number of pages (default=1000000): 1
Horizontal resolution in characters per inch (default=10/1):

Vertical resolution in lines per inch (default=6/1):

New magnification (default=0 to keep the old one):

' TeX output 1986.10.06:1449'
Font 51: cmtex10---loaded at size 655360 DVI units

Font 50: doc---loaded at size 902151 DVI units

Font 47: cmtt10---loaded at size 943718 DVI units
 (this font is magnified 144%)

Font 46: cmr7---loaded at size 951451 DVI units
 (this font is magnified 207%)

Font 18: cmex10---loaded at size 655360 DVI units

Font 15: cmsy7---loaded at size 458752 DVI units

Font 12: cmsy10---loaded at size 655360 DVI units

Font 2: cmr8---loaded at size 524288 DVI units

Font 1: cmr9---loaded at size 589824 DVI units

Font 0: cmr10---loaded at size 655360 DVI units

Beginning of page 17
 warning: |h|>30785864! warning: |h|>30785868!
@
@
@type dvidoc.dvidoc
x33 DVDOC                               READNGTHEFONTNFORMATON  17

33. A DVI-reading program usually  works with font  files instead
of TFM files, so DVIDOCis atypical in  that respect.   Font files
should, however,  contain exactly  the same character  width data
that  is found  in the  corresponding  TFs.    In addition,  font
files usually  also contain the  widths of characters  in pixels,
since the  device-independent character  widths of  TFM files are
generally not perfect multiples of pixels.
 The pixel-width array contains  this information;  when width[k]
is the  device-independent width of  some character in  DVIunits,
pixelwidth[k] is  the corresponding width of that character in an
actual font.  The macro charpixel-width is set up to be analogous
to charwidth.
 define charpixel-width(#) ? pixelwidth    [
      widthbase[#]+char-width-end

hGlobals in the outer block10i+?
pixelwidth:  array [0 ::max-widths] ofinteger;
    factual character widths, in pixelsg
horizconv:  real; fconverts DVI units to horizontal pixelsg
vertconv:  real; fconverts DVI units to vertical pixelsg
truehoriz-conv:  real; fconverts unmagnified DVIunits to pixelsg
truevert-conv:  real; fconverts unmagnified DVIunits to pixelsg
numerator;denominator:  integer; fstated conversion ratiog
mag:  integer; fmagnification factor times 1000g

34. The following code  computes pixel widths by  simply rounding
the TFM widths  to the  nearest integer number  of pixels,  based
on the  conversion factor  horizconv  that converts  DVI units to
pixels.
 define horizpixel-round(#)? trunc(horizconv?(#)+0:5)
 define vertpixel-round(#)? trunc(vertconv?(#)+0:5)
hMove the widths from  inwidth to width,  and append pixel-width
   values 3i?
 widthbase[nf] ? widthptr? fontbc[nf];
 if wp> 0 then
  for k? width-ptrtowp ?1 do

   begin width[k]? in-width[width[k]];
   pixelwidth[k] ? horizpixelround(width[k]);
   end
Thscoseuen econ28.
@
@
@dvidoc
DVIFILE    : docmac.dvi
DOCFILE    : dvidoc.dvidoc
This is DVIDOC, TOPS-20 Version 1.1a
Starting page (default=*): 17
Maximum number of pages (default=1000000): 1
Horizontal resolution in characters per inch (default=10/1): 16/1
Vertical resolution in lines per inch (default=6/1): 8/1
New magnification (default=0 to keep the old one):

' TeX output 1986.10.06:1449'
Font 51: cmtex10---loaded at size 655360 DVI units

Font 50: doc---loaded at size 902151 DVI units

Font 47: cmtt10---loaded at size 943718 DVI units
 (this font is magnified 144%)

Font 46: cmr7---loaded at size 951451 DVI units
 (this font is magnified 207%)

Font 18: cmex10---loaded at size 655360 DVI units

Font 15: cmsy7---loaded at size 458752 DVI units

Font 12: cmsy10---loaded at size 655360 DVI units

Font 2: cmr8---loaded at size 524288 DVI units

Font 1: cmr9---loaded at size 589824 DVI units

Font 0: cmr10---loaded at size 655360 DVI units

Beginning of page 17
 warning: |h|>30785864! warning: |h|>30785868!
@
@
@
@
@
@type dvidoc.dvidoc
x33    DVIDOC                                                   READING  THE  FONT  INFO
RM ATION      17

3 3 . A   DVI - r e a d i n gp r o g r a mu s u a l l yw o r k s  w i t h f o n t  f i l
 e s i n s t e a d
o f  TFM   f i l e s ,s o   DVIDOC   i s  a t y p i c a li n  t h a t r e s p e c t .
F o n t f i l e s
s h o u l d , h o w e v e r ,c o n t a i ne x a c t l yt h e  s a m e  c h a r a c t e w
 i d t h  d a t a

t h a t  i s   f o u n d i n   t h e  c o r r e s p o n d i n TFMs .       I n  a d d i
t i o n , f o n t
f i l e s u s u a l l ya l s o  c o n t a i nt h e  w i d t h s o f  c h a r a c t e r i
 n   p i x e l s ,
s i n c e t h e   d e v i c e - i n d e p e n d ecnhta r a c t e w i d t h s o f   TFM
 f i l e s a r e

g e n e r a l l n o t p e r f e c tm u l t i p l e o f  p i x e l s .
  T h e  p i x e w i d t h a r r a y c o n t a i n st h i s  i n f o r m a t i o n w h e
 n w i d t [ k]
i s  t h e  d e v i c e - i n d e p e n d ewnitd t h o f   s o m e c h a r a c t e ri n
 DVI  u n i t s ,

p i x e lw-i d t [ k]  i s  t h e  c o r r e s p o n d i w i d t h o f  t h a t c h a r
a c t e i n  a n
a c t u a lf o n t .   T h e m a c r o c h a rp-i x e w i d t h i s  s e t u p  t o  b e
  a n a l o g o u s

t o  c h a rw-i d t .
  d e f i n ec h a rp-i x e w i d t ( # )  ?  p i x e lw-i d t h     [

          w i d t b a s e[ #] + c h a rw-i d t he-n d
hG l o b a l si n  t h e o u t e r b l o c k10i+ ?

p i x e lw-i d t :   a r r a y [ 0 : : m a xw-i d t h ]  o f i n t e g e ;
      fa c t u a l c h a r a c t e w i d t h s ,i n  p i x e l s g
h o r i zc-o n :    r e a ;   fc o n v e r t DVI  u n i t s t o  h o r i z o n t apli x
e l s g

v e r tc-o n :    r e a l;  fc o n v e r t sDVI  u n i t st o  v e r t i c a lp i x e l
s g
t r u eh-o r i zc-o n :    r e a ;   fc o n v e r t u n m a g n i f i e DVI  u n i t st
o  p i x e l s g
t r u ev-e r tc-o n :    r e a l;  fc o n v e r t su n m a g n i f i eDVI  u n i t s t o
 p i x e l s g

n u m e r a t ; d e n o m i n a t : r  i n t e g e;r fs t a t e d c o n v e r s i o r a
t i o g
m a g:    i n t e g e;r fm a g n i f i c a t i ofna c t o rt i m e s 1 0 0 0 g

3 4 . T h e  f o l l o w i n gc o d e c o m p u t e sp i x e l w i d t h sb y   s i m p
l yr o u n d i n g
t h e  TFM   w i d t h s t o  t h e   n e a r e s ti n t e g e r n u m b e r o f  p i x
e l s , b a s e d
o n   t h e  c o n v e r s i o f a c t o r h o r i zc-o n v  t h a t c o n v e r t s DVI
  u n i t s  t o

p i x e l s .

  d e f i n eh o r i p i x e lr-o u n ( #) ?  t r u n ( h o r i c o n v? ( #) + 0 : 5 )
  d e f i n ev e r tp-i x e r o u n ( # ) ? t r u n ( v e r tc-o n v?( # ) + 0 : 5 )

hM o v e  t h e w i d t h s f r o m i n w i d t h t o  w i d t ,   a n d  a p p e n dp i
 x e lw-i d t h
     v a l u e 34 i?

  w i d t b a s e[ n f] ?  w i d t p t r ? f o n tb-c[ n f] ;
  i f w p >  0  t h e n
   f o r  k ?  w i d t p t r t o w p?  1  d o

     b e g i nw i d t [ k ] ?  i nw-i d t h[ w i d t[hk] ] ;
     p i x e w i d t [ k ] ?  h o r i p i x e lr-o u n ( w i d t [ k] ) ;

     e n d
Thiscode isusedinsectio28.
@pop

[PHOTO:  Recording terminated  Mon 6-Oct-86 2:58PM]

------------------------------------------------------------
-------