summaryrefslogtreecommitdiff
path: root/support/ltxdiff/README
blob: cf1cf9747d070904fbd79cd5cb3a3379821526b6 (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
ltxdiff 0.9.0 (beta)
Copyright (c) 2005 by Bernd Becker
(ltxdiff is public domain, but GNU Diff is GPL'd software.
Should you want to get the source code for GNU Diff you could go
to http://www.gnu.org/software/diffutils/
or, if I haven't put it up on my site 'til then, send an e-mail my way)

A Win32 program(me) that compares tokens in two .tex files
(or directories [+subdirectories] containing .tex files) and may mark
differences according to the options set by using GNU Diff to find tokens
to be marked.
An other diff program(me) may be used if it has the switches
"-b", "-B", "-d", and "-E" and they are compatible to GNU Diff's.

It was written when there were complains that changes in the game
design weren't marked, making it hard to know what exactly was
modified between revisions.

For this reason the program(me) only knows those commands/environments
I use in my game design; including the ones I used that are in my own
style file and packages, which might lead to unwanted results if someone
uses the same name but defined them differently(number of arguments,
type of argument, etc.).
This is also led to the decision to not mark deleted tokens inside columns
as my tabulars have lots of small columns and text would spill over
if the deleted/older tokens would be written as well as added/current
tokens. Another reason is that writing deleted columns may lead to tabulars
wider than the page. This not only looks ugly but there also might be
columns not visible any more that should be.

It was written to use as few memory as possible, but still be fast. This
led to compromises and some odd looking lines of code and even though there
may still be room for optimizations I'm satisfied with it (see also the
section "Missing stuff" below).

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

A. Installation:
Copy the .exes into your path - your TeX's binary directory would probably
be just fine - and copy ltxdiff.sty file into your local packages directory
and add "ltxdiff" to the list of packages loaded by your text, or
define the commands/environments inside the file(s) to see any differences.
The provided ltxdiff.sty file contains example definitions not exactly
useful for every situation or for everyones taste, in fact they are not
even the ones I use personally. Therefore it would be a good idea to
redefine them to your own needs and taste before compiling the marked text.

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

B. Notes:
1:
	If only one file name is given it is assumed the second file has the
same name as the first and either '-m' or '-o' is used as well !
Example: ltxdiff -o old 1.tex
	-> compare .\1.tex with .\old\1.tex

2:
	If the passed file name(s) do not have an extension it is assumed
the files have the '.tex' extension !
Example: ltxdiff -o old 1
	-> compare .\1.tex with .\old\1.tex

3:
	If the -a switch is used any file names passed are ignored, but both
-o and -m must be passed and be different or you will get nothing but
an error message !
Example: ltxdiff -a -r -o d:\docs\old -m d:\docs\current
	-> compare all .tex files in d:\docs\old and its subdirectories with
all .tex files in d:\docs\current and its subdirectories

4:
	CTRL+C ends the program(me) prematurely but not without cleaning up
first ! (freeing used memory, deleting temporary files)

5:
	It checks for commands/environments it knows and only marks
added/deleted tokens if the code says it's okay; unknown means it will
always mark tokens !

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

C. Usage:
	ltxdiff [OPTIONS]... [ORG_FILE] [MOD_FILE]

Options:
	-1
don't write deleted words into output file
	-2
don't write new words into output file
	-3
don't write common words into output file
	-a
compare all '.tex' files with the same name in two directories.
	-b
if -c is used create a backup of the original
	-c
copy modified to original, and output file to modified
	-d
delete output file afterwards -1, -2, -3 and -c have no effect
	-h
print help text
	-l
write log info into 'ltxdiff.log' file
	-m DIR
DIR is the directory containing the modified text(s)
	-o DIR
DIR is the directory containing the original text(s)
	-r
if -a is used recursively check all subdirectories as well
	-s
print statistics (number of words deleted, inserted etc.)
	-v
print program version

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

D. Missing stuff and ideas:
1. external text file defining (La)TeX commands/environments and special
commands only available inside them (like tabbing).
2. To make 1. work the special commands ought to be defined as a list of
strings checked by a function, instead of a function that checks all the
'strings'; a generalization of read_tex_tabbing_commands() using this list
would do.
3. add a list of files/directories with their status to cut down the time
used in the functions to find all files of a pattern, and mark as new or
deleted, or compare them.
4. if 3. is implemented the file name inside of \input{} of files that are
new/were changed can be changed to their .new/.dif counterpart making 5.
unnecessary. But it will certainly use more code, time and memory than 5.
5. compile a version with "-b" and "-c" functionality, so that can be
tested as well; it's just a matter of a #define set to 1 but... ;-)
6. check files with the .ltx extension as well
7. dig out MO disk on which GNU Diff's source code hides and upload it
or something.
8. get rid of debugging switches -1, -2, -3, -d

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

E. Contact:
If you think you found a bug, or want a command/environment added, or...
send an e-mail to munin@munin.inka.de. TIA.