Debian Codegraph @

texmf-dist/doc/man/man1/dviasm.1

raw
1 .TH DVIASM 1
2 .SH NAME
3 DVIasm \- a TeX utility program for editing DVI files directly
4 .SH SYNOPSIS
5 \fBdviasm\fR [<\fIoptions\fR>] <\fIdvi_file\fR>|<\fIdvi_dump_file\fR>
6 .SH DESCRIPTION
7 \fBDVIasm\fR is a TeX utility program which is
8 designed for editing DeVice-Independent (DVI) files directly.
9 It consists of a single Python script, dviasm.py,
10 in a human readable text format.
11 It runs on any platform in which Python 3 is installed.
12 .TP 2
13 Features of \fBDVIasm\fR includes:
14 .IP
15 1) Disassemble a DVI file (or XeTeX XDV file) into
16 a human-readable text file, the contents of which are easy to modify.
17 .IP
18 2) Assembles the output text file back to the binary format.
19 .TP 2
20 There are several alternatives for dumping and editing DVI files:
21 .IP
22 1) \fBDVItype\fR developed by Donald E. Knuth supports
23 one-way conversion from DVI to a text format.
24 There are also some derivatives: \fBpDVItype\fR for pTeX,
25 \fBupDVItype\fR for upTeX, \fBODVItype\fR for Omega.
26 .IP
27 2) The programs \fBdv2dt\fR and \fBdt2dv\fR can be used
28 in pairs to allow two-way conversion between DVI and
29 the DVI Text Language (DTL).
30 .IP
31 3) The program \fBdvispc\fR (part of DVIOUT previewer)
32 also has an ability to convert between DVI and text.
33 .PP
34 Among those, \fBDVIasm\fR is designed to allow users to edit
35 DVI files easily, for example by unifying
36 ``right1''\-``right4'' to a single command ``right''
37 which can be used regardless of the amount of move.
38 .SH OPTIONS
39 .PP
40 .TP 10
41 \fB--version\fR
42 Show program's version number and exit.
43 .TP 10
44 \fB-h\fR, \fB--help\fR
45 Show this help message and exit.
46 .TP 10
47 \fB-u\fR <\fISTR\fR>, \fB--unit=\fR<\fISTR\fR>
48 Set unit [default: `pt'].
49 Allowed values are: `sp', `pt', `bp', `mm', `cm' and `in'.
50 .TP 10
51 \fB-o\fR <\fIFILE\fR>, \fB--output=\fR<\fIFILE\fR>
52 Set filename for output instead of stdout.
53 .TP 10
54 \fB-e\fR <\fISTR\fR>, \fB--encoding=\fR<\fISTR\fR>
55 Set encoding for input/output of dumped text [default: `utf8'].
56 Allowed values are: `ascii', `latin1', `utf8', `sjis' and `eucjp'.
57 When used with the option \fB-p\fR (or \fB--ptex\fR),
58 allowed values are only `utf8', `sjis' and `eucjp'.
59 .RS 10
60 # NOTE: This feature does not support dumping through stdout.
61 .RE
62 .TP 10
63 \fB-x\fR <\fISTR\fR>, \fB--xxx-encoding=\fR<\fISTR\fR>
64 Set encoding for interpreting `xxx:' strings [default: `none'].
65 Allowed values are: `none', `utf8', `sjis' and `eucjp'.
66 .RS 10
67 This option allows users to specify the correct encoding for
68 dumping/compiling the contents of \\special.
69 .TP 2
70 Typical usages are as follows:
71 .IP
72 1) By default, the contents of \\special are dumped/compiled
73 as byte-to-byte escape sequences in `\\x..' format.
74 This would suffice when you don't need to read/edit
75 the contents of \\special.
76 .IP
77 3) For XeTeX and upTeX users, `\fB-x utf8\fR' would be useful
78 since these engines use UTF-8 to encode strings inside
79 \\special commands.
80 .IP
81 2) For pTeX users with ISO-2022-JP-encoded DVI,
82 it would be helpful to select the appropriate option
83 `\fB-x eucjp\fR' (for Unix) or `\fB-x sjis\fR' (for Windows)
84 to be consistent with the internal Kanji encoding used by
85 pTeX engine.
86 .RE
87 .TP 10
88 \fB-t\fR <\fIINT\fR>, \fB--tabsize=\fR<\fIINT\fR>
89 Set tab size for push/pop [default: 2].
90 .TP 10
91 \fB-p\fR, \fB--ptex\fR
92 Dump and compile ISO-2022-JP-encoded DVI for Japanese pTeX.
93 This option is required to decode or encode Japanese characters
94 being typeset (using `set2' or `put2') properly.
95 .TP 10
96 \fB-s\fR <\fISTR\fR>, \fB--subfont=\fR<\fISTR\fR>
97 Specify the list of fonts with UCS2 subfont scheme
98 in the comma-separated format.
99 If <\fISTR\fR> is empty, the pre-defined internal subfont list
100 is disabled.
101 .RS 10
102 This option would be useful for example when using CJK package.
103 .RE
104 .SH EXAMPLE
105 Documentation of
106 .B DVIasm
107 by the original author Jin-Hwan Cho is published as:
108 https://tug.org/TUGboat/Articles/tb28-2/tb89cho.pdf (TUGboat)
109 http://ajt.ktug.kr/assets/2008/5/1/0201cho.pdf (Asian Journal of TeX)
110 .SH AUTHORS
111 The first version was written in Python 2 by Jin-Hwan Cho in 2007.
112 Khaled Hosny started to support dumping/compiling XeTeX XDV format in 2014.
113 Arthur Reutenauer ported the script to Python 3 in 2019.
114 Current maintainer of \fBDVIasm\fR is Hironobu Yamashita, since 2020.
115 .SH BUG REPORT
116 Please visit the GitHub repository <https://github.com/aminophen/dviasm>.
117 .SH SEE ALSO
118 .BR dvitype (1),
119 .BR dv2dt (1),
120 .BR dt2dv (1),
121 .BR dvispc (1).