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
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
|
<HTML>
<HEAD>
</HEAD>
<BODY>
<A NAME="section-1"><H1>TXT2TeX Copyright (C) 1998 --- 2008 Kalvis M. Jansons</H1></A>
<P>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
<P>
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
<P>
You should have received a copy of the GNU General Public License
along with this program. If not, see <<A HREF="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</A>>.
<P>
This perl script (which is part of the KalTeX package) converts plain text
into something with a little LaTeX formatting. If you are reading a LaTeXed
version of this ``readme'' file, it was made from the comments in the code
of txt2tex using txt2tex to format them; if you are reading the plain text
version, try running it through txt2tex (you can use ``txt2tex --demo'' for
this on a unix system).
<P>
Written by Kalvis M. Jansons (email address <A HREF="mailto:k@kalvis.com">k@kalvis.com</A>), but based on
<A HREF="http://www.cs.wustl.edu/~seth/txt2html/">txt2html</A> by <A HREF="http://www.cs.wustl.edu/~seth/">Seth Golub</A> (email address <A HREF="mailto:seth@aigeek.com">seth@aigeek.com</A>). So if you like it,
send an email to both of us, but thank Seth the most; if you have any
problems or suggestions send an email to me (Kalvis).
<P>
By default, much of LaTeX's fine structure is disabled by definitions in the
.tex file header. If you need to edit the LaTeX you may need to remove
or change some of these statements; or you may need to rerun txt2tex in a
lower escaping mode, to add more complex structures, like tables and
complex equations. I did it this way as I will use txt2tex myself mainly
for non-mathematical documents, and for those, I like to be able to type %
for percent etc., and paste in emails without worrying too much about all
the strange symbols. Set the ``-ec'' flag if you want to ``escape'' all
of LaTeX's special functions, and kill the ``\'', which is often the
safest setting for ``unknown'' document formats.
<P>
<STRONG>DO YOU WANT A DEMONSTRATION? IF SO, SEE BELOW.</STRONG>
<UL>
<LI> For a trivial demo of txt2tex, type ``txt2tex --info |txt2tex -ec''.
<UL>
<LI> For a nicer copy of this readme file, try
``txt2tex --info |txt2tex -ec -ns -10pt''.
<LI> Or maybe you will like the look of this better:
``txt2tex --info |txt2tex -tf -ec -ns -10pt''.
<UL>
<LI> Remember, to see the nice output, type something like:
``txt2tex --info |txt2tex -tf -ec -r off > readme.tex''
followed by ``latex readme.tex; xdvi readme.dvi''.
</UL>
<LI> On a unix or linux system try ``txt2tex --demo''.
</UL>
<LI> The best test is clearly to try it on one of your own plain text files.
</UL>
<A NAME="section-1.1"><H2>Paper size</H2></A>
<P>
The paper size is set to ``a4paper'', but if you would like a different
paper size I suggest finding the line with ``a4paper'' in txt2tex and
changing it once and for all. This can also be changed using the
``--doctype'' option.
<A NAME="section-1.2"><H2>Tag syntax</H2></A>
<P>
In the options in the next section, the term ``tag'' is often used. I
have used this term for many types of LaTeX mark-up instruction. The
syntax for using tags with txt2tex is easy. For a simple tag, which
puts a heading into a LaTeX subsection form, the tag is just ``subsection''.
For more complex, or nested, tags the syntax is a little more complex. If,
for example, you wanted all section headings to be centered, the tag to do
it with would be ``section{\center''. You could also add a ``clearpage''
so each section is on a new page, and a ``*'' so the sections are not
numbered; the tag would then be ``clearpage\section*{\center''. Also
remember when using tags on a command line, you must take account of the
normal shell escaping conventions.
<A NAME="section-1.3"><H2>Some important command line options</H2></A>
<P>
Note that any command line option name can contain any number of ``_'' to
make the command line more readable, and, in fact, you only need a single
``-'' for any of the names listed with ``--''.
<P>
[(-dt|--doctype) <doctype>]
<P>
Used to set the LaTeX documentclass or documentstyle. It can be set to
``null'' for no doctype, which is useful if you want to add some LaTeX
definitions above the definitions in the txt2tex header. For an example,
see the definition of ``--switch slides'' at the end of txt2tex.
<P>
[-10pt|-11pt|-12pt]
<P>
Used to set the LaTeX font size. The default is 12pt. The ``pt'' can
be dropped.
<P>
[(-up|--usepackage) <name>|off]
<P>
Sets a LaTeX ``usepackage'' definition. No default packages loaded.
<P>
[(-lh|--latexhooks) <name|mode>]
<P>
Used to add LaTeX instructions from files. Given a ``name'', it tells LaTeX
to read (if they exist) the files name-HeadB, name-HeadE, name-BodyB,
name-BodyE (with or without a suffix .tex); these files are read in to the
beginning and end of the HEAD and the beginning and end of the BODY.
Given a number, it sets the ``latex-hook'' mode, which controls which LaTeX
input statements are added; these are 1,2,4,8 for the above files, which
are bitwise ORed. If a new LaTeX-hook name is given, the mode is set to 15,
i.e. all bits set. If a mode is given, and no name has been set, the
default name ``\jobname'' is used as the name. Hooks are off by default.
<P>
Remember in LaTeX the basename of the LaTeX file is stored in the LaTeX
variable ``\jobname'', so by using this as the base part of your LaTeX
hooks, you would not have to change the LaTeX itself if you wanted to
use a different set of hook files, as you would need only to change the
name of the main LaTeX file.
<P>
[(-ec|--escapechars) [<mode>]]
<P>
Used to set the escape mode. The options (which can be bitwise ORed) are:
<PRE>
1 --- escape \
2 --- escape $
4 --- escape ^ and _
8 --- escape < and >
16 --- escape &
32 --- escape |
64 --- escape #
128 --- escape ~
512 --- escape %
1024 --- escape "
</PRE>
<P>
(The above list shows what txt2tex does with complex formatting in the
plain text document, namely puts it in a LaTeX verbatim block, at least
in the LaTeX version of the documentation.)
The default mode is 2046, so the LaTeX backslash is still active. Using
``-ec'' without a following number will escape everything, and ``-ec 0''
will escape nothing. Note that mode 1 also fixes a problem with a line
that begins with white space and has ``['' as the first non-space
character.
<P>
[-bm|--batchmode]
<P>
Makes LaTeX run in its non-stopping mode, i.e. ignores any LaTeX
warnings about over-full boxes etc.. Off by default.
<P>
[-nv|--noverbatim]
<P>
Stops any output being put in verbatim blocks even if it looks like it
is ``preformatted''. This sometimes gives other subroutines a chance
to format the data. Off by default.
<P>
[-sv|--splitverbatim]
<P>
Use this if verbatim blocks can be split by page breaks; the default is
that they cannot.
<P>
[(-pb|--prebegin) <num>]
<P>
Sets the number of preformatted-looking lines (2 by default) needed
to begin a verbatim block. The options are:
<UL>
<LI> 0 --- put the entire document in a verbatim block.
<LI> 1 --- one trigger line, so even a single line can be put in verbatim.
<LI> 2 --- two trigger lines.
<LI> 3 --- same as 1, but verbatim blocks can start only after a
blank line.
</UL>
<P>
Less than 0 is set to 0 and more than 3 is set to 3.
<P>
[(-pe|--preend) <num>]
<P>
Sets the number of non-preformatted-looking lines (2 by default) needed
to end a verbatim block. The options are from 0 to 3, with less than
0 set to 0 and more than 3 set to 3. Option 3 has the special meaning
of ending the verbatim block on a blank line.
<P>
NOTE for --prebegin and --preend: If only one is zero, the other is ignored.
If both are zero, the entire document is put in a verbatim block.
<P>
[(-p|--preformat) <num[,num[,num]]>]
<P>
This option sets the values of the following variables:
<UL>
<LI> $verbatim<U>white</U>min (6),
<LI> $verbatim_min (6),
<LI> $verbatim<U>post</U>min (3),
</UL>
<P>
where the numbers in () are the defaults. If only one number is given,
it sets $verbatim<U>white</U>min and $verbatim_min to this value, otherwise it
sets the variables in order. A line is considered to be preformatted if
either there is a non-space character followed by $verbatim_min non-word
characters, or if there are at least $verbatim<U>white</U>min spaces after
the start of the line and the line contains a non-space character
followed by $verbatim<U>post</U>min non-word characters.
<P>
Note that tabs are expanded before these tests.
<P>
[-ns|--nosectionnumbers]
<P>
Do not number LaTeX sections. They may already have numbers, for example,
or you may feel that the document looks better without them. In fact, all
this really does is add a ``*'' at the end of the headings tags, so if you
have changed these tags, be sure that ``-ns'' still makes sense for your
tags.
<P>
[-np|--nopagenumbers]
<P>
Do not number LaTeX pages, i.e. set the pagestyle to empty.
<P>
[(-lm|--listmode) <mode>]
<P>
Sets the list mode; the bitwise ORed options are:
<UL>
<LI> 0 --- automatically number and label lists, renumbering what appear
to be lists with errors. Use standard LaTeX numbering and labelling.
<LI> 1 --- keep the original numbers (or letters) on enumerated lists, but
put standard labels on itemized lists.
<LI> 2 --- turn itemized lists into enumerated lists.
<LI> 4 --- hrules end all active lists.
<LI> 8 --- easy start. Enumerated lists need not start with 1, A, etc.,
which is useful for documents that have headings, diagrams etc. in
lists. You would normally use this with list mode 1, to avoid
renumbering.
<LI> 16 --- turn LaTeX description environments into enumerate; this may
sound a strange thing to do, but leads to nice results. Try it!
<LI> 32 --- do not nest description environments. Normally a new
description starts for every new level of indentation, but this mode
switches this feature off.
</UL>
<P>
Using ``-lm'' without a following number sets the default mode 0.
<P>
[(-de|--description) <regexp>|off]
<P>
Sets the regular expressions to identify lines that should be put in a LaTeX
``description'' environment. Only the ``first match'' in the regular
expression will be used as the ``name'' in the ``description'', and the
rest is deleted. So, if you do not want to delete anything, put your
regular expression in ``()''. This is off by default, and the default
can be reset with the command line option ``-de off''. See the definitions
of ``-sw remind'' and ``-sw dict'' for examples.
<P>
[(-s|--shortline) <[-]num>]
<P>
Sets the upper bound of the length of a ``short line'' (40 by default),
which is assumed to be intentionally this short, so must be kept broken.
If the number given is negative, leading spaces are not ignored when
determining if a line is ``short''. The default is that leading spaces
are ignored.
<P>
[(-ss|--shortlineskip) <length>]
<P>
Sets the vertical skip after a ``short line'', for example try ``-ss 1ex''.
The default is a normal line break. The default can be restored by setting
it to ``null''.
<P>
[(-r|--hrule) <num>|off]
<P>
If given a number, sets the minimum number of ``==='' etc. for a horizontal
rule. The default is 4. If given ``off'', sets $hrules_on = 0, and any
hrules found are not printed.
<P>
[(-sm|--smallmargins) [<mode>]]
<P>
LaTeX defaults to large margins, but I like small (1in) margins. The
bitwise ORed options are:
<UL>
<LI> 0 --- standard LaTeX margins.
<LI> 1 --- 1in X margins.
<LI> 2 --- 1in Y margins.
<LI> 3 --- 1in X and Y margins.
</UL>
<P>
The default is 0. If ``-sm'' is not followed by a valid number, then
option 3 is set.
<P>
[(-t|--title) <title>]
<P>
You can specify a title to be placed at the top of the document.
<P>
[(-tt|--titletag) <tag>]
<P>
Used to set the title tag. The default tag is ``centerline{\LARGE\bf''.
<P>
[-tf/+tf] | [--titlefirst/--notitlefirst]
<P>
Use the first non-blank line as the title of the document. Off by default.
<P>
[(-pi|--parindent) <num>]
<P>
Sets the minumum number of spaces indented in first line of a paragraph.
This is used only when there's no blank line preceding the paragraph.
The default is 3.
<P>
[(-c|--caps) <num>]
<P>
Sets the minimum sequential CAPS for a ``caps line'', which is then put
in a special font. For the full definition of a caps line, see the code.
The default is 3.
<P>
[(-ct|--capstag) <tag>|off]
<P>
Sets the tag to put around ``caps lines''. Set it to ``off'' for no
caps lines, but note that some of these lines could then be marked as solo
lines; if you want to avoid this, set it to ``null'', which is turned into
the empty tag. The default tag is ``subsubsection*''.
<P>
[(-st|--solotag) <tag>|off]
<P>
Sets the tag for ``solo lines'', i.e. lines that have a blank line before
and after, and have the ``right'' important-looking ending (see
``sub solo'' for the full definition). The default tag for solo lines is
``subsubsection*{\textit''. Set it to ``off'' for no solo lines.
<P>
[(-m|--mail) [<mode>]]
<P>
Used to set the mail mode. The bitwise ORed options are:
<UL>
<LI> 1 --- deal with mail headers and mail quoted text.
<LI> 2 --- add half-line width right-flushed hrules at the beginning of
new messages. Strange, but easy to see!
<LI> 4 --- add a LaTeX ``clearpage'' before each new message.
<LI> 8 --- do not print the mail header.
</UL>
<P>
``-m'' without a following number sets the default mail mode of 1. (Any
non-zero option also includes option 1.)
<P>
[-u/+u] | [--unhyphenate/--nounhyphenate]
<P>
Enables unhyphenation of the raw text, so we can leave hyphenation to
LaTeX. On by default.
<P>
[(-ul|--ulength) <num>]
<P>
Sets the underline tolerance for plain text headings, i.e. how much longer
or shorter than the text can underlines be and still be underlines. The
default is 1.
<P>
[(-uo|--uoffset) <num>]
<P>
Sets the offset tolerance for underlines of plain text headings. The
default is 1.
<P>
[(-tw|--tabwidth) <num>]
<P>
Sets the width of a tab. The default is 8.
<P>
[-e/+e] | [--extract/--noextract]
<P>
Sets extract mode for making inserts for other LaTeX documents. Off
by default.
<P>
[(-rs|--ruleset) <file>]
<P>
[+rs|--noruleset]
<P>
By default reads the ruleset in ``.txt2tex-ruleset'' (if it exists),
but a different file can be given. When looking for a specified ruleset
file, if it fails to find a direct match, it will then try ``file-ruleset''
and last of all ``~/.txt2tex-file'', where ``file'' is the given file name.
<P>
[-ro/+ro] | [--rulesetonly/--norulesetonly]
<P>
Do no escaping or marking up at all, except for processing the ruleset
dictionary file and applying it. This is useful if you want to use
txt2tex's rulesetting feature on a LaTeX document. If the LaTeX is a
complete document (includes HEAD and BODY) then you will need to use
the --extract option also. Off by default.
<P>
[(-H|--heading) <regexp>]
<P>
Used to set regular expressions to pick out custom headings in the plain
text. For examples, see the ``switch'' options at the end of txt2tex,
in particular ``num''. Header levels are assigned by regexp in the order
seen; when a line matches a custom header regexp, it is tagged as
a header. If it is the first time that particular regexp has matched,
the next available header level is associated with it and applied to
the line. Any later matches of that regexp will use the same header level.
Therefore, if you want to match numbered header lines, you could use
something like this:
<P>
-H '^ *\d+\. \w+' -H '^ *\d+\.\d+\. \w+' -H '^ *\d+\.\d+\.\d+\. \w+'
<P>
Then lines like:
<P>
2. Examples<BR>
2.1. More Examples<BR>
2.1.1. Even More Examples
<P>
would be marked as section, subsection, etc., assuming they were found in
that order, and that no other header styles were found. If you prefer
that the first heading specified always becomes ``section'', the second
always becomes ``subsection'' etc., then use the --explicitheadings option.
Also you would probably want the --nosectionnumbers option, to avoid getting
two sets of numbers; this could also be fixed using the --trimheadings
option (see the definition of ``--switch n'').
<P>
[(-HT|--headingtags) <tag1[,tag2...]>|shift|number]
<P>
[(-TH|--trimheadings) <regexp>]
<P>
The sequence of tags for the section headings can be set by something like:
``-HT something,anotherthing,...'' and the headings can be trimmed using
``-TH <regexp>'', i.e. whatever matches ``regexp'' is removed. Note that
all headings are trimmed using the same regular expression and that the
regular expression is applied after the heading tag and label have been
added. The argument of ``-HT'' can also be ``shift'', which shifts the
sequence of heading tags down by one, or ``number'', which tells txt2tex
(rather than LaTeX) to number the headings (off by default). Remember not
to ask LaTeX to number the headings too, if you use ``number''.
<P>
[-EH/+EH] | [--explicitheadings/--noexplicitheadings]
<P>
This tells txt2tex not to try to find any headings except the custom ones
specified. Also, the custom headings will not be assigned levels in the
order they are encountered in the document, but in the order they are
specified on the command line. Off by default.
<P>
[(-db|--debug) <num>]
<P>
Debug mode for ruleset dictionaries. Bitwise OR what you want to see:
<UL>
<LI> 1 --- the parsing of the dictionary.
<LI> 2 --- the code that will make the ruleset.
</UL>
<P>
[(-tr|--trim) <num|regexp>]
<P>
Used to trim ``n'' characters from the beginning of each line longer than
``n'', or to trim using a regular expression. The default is 0.
<P>
[(-sw|--switch) <keyword>]
<P>
Used to add sets of command line options that are kept at the bottom
of this file. For example ``-sw num'' will help pick out numbered
section headings, and ``-sw lynx'' cleans up text files from the lynx
browser. Take a look at the definition of ``-sw num'', and see if you
can work out what all the options do. Then add some ``-sw'' options
of your own. Also see the section on option sets below.
<P>
[-tc|--twocolumn]
<P>
Sets LaTeX's ``twocolumn'' option. Off by default. To see what this looks
like with 1in margins, take a look at this ``readme'' file in this format
by typing ``txt2tex --demo'' on a unix or linux machine.
<P>
[-ls|--landscape]
<P>
Sets LaTeX's ``landscape'' option. Off by default.
<P>
[-sp|--sloppy]
<P>
Sets LaTeX's ``sloppy'' option, which is particularly useful for slides.
Off by default.
<P>
[-d|--draft]
<P>
Save the output in a file called draft.tex. Off by default.
<P>
[(-h|--help)/--info/--demo]
<P>
--help gives a short help message listing the options, --info gives a
plain text version of the ``readme'' file, and --demo (on a standard
unix or linux system) will run the plain text from --info through
txt2tex to give a nice LaTeXed version of the ``readme'' file; note that
the ``demo'' makes t2t_readme.txt, .tex, .dvi, .aux, and .log.
<P>
[-v|--version]
<P>
Prints the txt2tex version number.
<A NAME="section-1.4"><H2>Option sets</H2></A>
<P>
Below the ``_<U>END</U>_'' in txt2tex you can put lists of command line
options after a ``keyword''; these can then be loaded by putting
``-sw keyword'' on the command line. Note that ``\'' is a continuation
character, so long options can be put on several lines. These include:
<UL>
<LI> remind --- turns the output of the unix remind program into nice LaTeX;
call remind using ``rem -n |sort''.
<LI> num --- picks out simple numbered headings.
<LI> n --- a variant of the above.
<LI> plain --- a very plain style, which is good for university work!
<LI> trim --- removes leading spaces before txt2tex processes the line.
<LI> lynx --- for lynx browser output.
<LI> noL --- normally \014 produces a LaTeX ``clearpage'', but this option
removes \014 before txt2tex sees the line.
<LI> HH --- this is what I use to print the ``Happy Hacker'' newsletter.
<LI> man --- useful for dealing with unix man pages, but could be better!
<LI> pagesec --- each new section starts on a new page.
<LI> pagesubsec --- each subsection starts on a new page.
<LI> slides --- turns plain text into (very) simple slides. You might also
want to set ``noverbatim''. Note that many of the standard options will
not work with switch ``slides'' set.
<LI> handout --- used for student handouts.
<LI> letter --- used for writing letters, but you need to define your own
letter-hook files with your address etc.
<LI> preview --- not for LaTeXing, but marks up the file in a manner to show
you what txt2tex was thinking; this can help in choosing the right tags
etc. for the print run. It can be followed by other options, so you can
see how that changes the mark up. It is also useful for debugging, but that
is probably my job [:-)]
<LI> dict --- turns a list of the form `word: text' into a LaTeX description
environment.
<LI> phone --- turns a list of the form `phrase: text' into a LaTeX description
environment. I use this for a personal phone book.
<LI> fn --- turns fancy numbered lists, with numbers like 1.1.1, into LaTeX
description environments. Often useful for printing contracts off the net!
<LI> lpr --- used as part of a fancy plain text printer filter.
<LI> lpn --- used by the Lockpicker Network.
<LI> netrc --- used to print a .netrc file.
</UL>
<A NAME="section-1.5"><H2>A sample ruleset</H2></A>
<P>
Txt2tex by default tries to load a file called ``.txt2tex-ruleset'' from
your home directory (assuming you are using a unix system). This file, if
it exists, contains transformation rules that are executed AFTER all other
txt2tex subroutines with the exception of ``tidy'' (which does a little
cleaning up) and the escaping of ``funny'' characters. Strange behaviour
can result from not keeping the time of execution in mind.
<P>
I most often use ``rulesets'' for writing my own documents in plain text, to
be transformed later by txt2tex into LaTeX. So let us look at rules
that help in such tasks. Each rule must be on a single line in the ruleset
file.
<P>
/<<(.*?)>>/ -f-> $1
<P>
The ``-f->'' type rule, when the regular expression on the left matches,
takes the expression on the right and turns it into a footnote, then
removes the triggering text. So the above example transforms
``Kalvis M. Jansons<<Mathematics, UCL>>'' into
``Kalvis M. Jansons\footnote{Mathematics, UCL}'' in the LaTeX output.
<P>
Kalvis M. Jansons -Fo-> Email: kalvis\@jansons.org
<P>
The ``-F->'' type rules are the same as the ``-f->'' ones, but do not
remove the triggering text. So the above rule adds a footnote with my email
address to my name. So that this happens once only per document, I have
added the ``o'' (for once) in the rule.
<P>
/txt2tex/ -oi-> TXT2TeX \\emph{(written by Kalvis)}
<P>
/pheonix/ ---> phoenix
<P>
The above rules are simple transformations, the first is case insensitive,
hence the ``i'', and is executed once only. The second corrects a common
spelling error (every time it occurs).
<P>
/tagad/ -ie-> my $time = localtime(time); $time =~ s/\:\d\d\s.*//; $time
<P>
The ``e'' option means evaluate the righthand side as a perl expression.
So the above expression turns ``tagad'' (the Latvian for ``now'') into the
current date and time (and removes ``tagad''). The ``e'' option can also
be used to change the value of txt2tex parameters while running, by setting
them when certain patterns are first encountered.
<P>
/\*([a-z][a-z ]*[a-z])\*/ -ti-> emph
<P>
/\*([a-z])\*/ -ti-> emph
<P>
The ``t'' option is used to tag the text in (), so leads to a shorter
rule than could be obtained using the above rules to do this job.
The above rules put any sequence of letters and spaces which are between
two stars in the LaTeX ``emph'' style. This use of ``*'' is often seen
in plain text ``readme'' files.
<P>
/<\*(.*?)\*>/ -tfi-> textbf
<P>
Putting a few bits together, we can turn anything in <* ... *> into a
``textbf'' footnote, but I am sure you can think of a better application.
<A NAME="section-1.5.1"><H3>Saving the sample ruleset</H3></A>
<P>
If you want to save this sample ruleset to adapt for your own use, type
``txt2tex -sampleruleset > ~/.txt2tex-ruleset'',
<P>
or direct it into a different file if you do not want it to be the default.
<A NAME="section-1.6"><H2>Getting help</H2></A>
<P>
Please contact me (Kalvis) with any problems or suggestions.
<A NAME="section-1.7"><H2>Bugs</H2></A>
<P>
Send any bug reports to me, and I will do my best to fix them, but note that
there is a limit to what txt2tex can be expected to do on poorly formatted
text files. For such files, it is often better to fix the worst features
before giving them to txt2tex; then there should not be the need to do much
work, if any, on the LaTeX file produced.
<P>
Ensure that you are using the latest version, which can be obtained from
any CTAN site.
<P>
<A HREF="mailto:Kalvis@Jansons.org">Kalvis@Jansons.org</A>
</BODY>
</HTML>
|
