diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/txt2tex/t2t_readme.tex |
Initial commit
Diffstat (limited to 'support/txt2tex/t2t_readme.tex')
-rw-r--r-- | support/txt2tex/t2t_readme.tex | 666 |
1 files changed, 666 insertions, 0 deletions
diff --git a/support/txt2tex/t2t_readme.tex b/support/txt2tex/t2t_readme.tex new file mode 100644 index 0000000000..e46ef966c2 --- /dev/null +++ b/support/txt2tex/t2t_readme.tex @@ -0,0 +1,666 @@ +\documentclass[a4paper,10pt,twocolumn]{article} + +\batchmode + +\setlength{\oddsidemargin}{0in} +\setlength{\textwidth}{\paperwidth} +\addtolength{\textwidth}{-2in} +\setlength{\marginparwidth}{.7in} + +\setlength{\headheight}{0in} +\setlength{\headsep}{0in} +\setlength{\textheight}{\paperheight} +\addtolength{\textheight}{-2in} +\setlength{\topmargin}{0in} + +\let\olddospecials=\dospecials +\def\dospecials{\catcode`|=11 \olddospecials} + +\let\leftangle=< +\let\rightangle=> +\let\doublequote=" +\let\dollar=\$ +\catcode`\_=\active +\catcode`\<=\active +\catcode`\>=\active +\catcode`\|=\active +\catcode`\"=\active +\catcode`\$=\active +\def<{\mbox{\(\leftangle\)}} +\def>{\mbox{\(\rightangle\)}} +\def|{\mbox{\(\mid\)}} +\def"{\mbox{\texttt{\doublequote}}} +\def${\dollar} +\catcode`\%=11 +\catcode`\#=11 +\catcode`\&=11 +\catcode`\^=11 +\catcode`\~=11 + +\setlength{\parindent}{0em} +\setlength{\parskip}{2ex} + +\begin{document} + +\iffalse +Converted from plain text with txt2tex 4.0 +on Wed Jun 4 14:45 2008 GMT. + +$Id: txt2tex.pl 4051 2007-07-01 07:38:34Z kalvis $ +\fi + +\section*{TXT2TeX Copyright (C) 1998 --- 2008 Kalvis M. Jansons}\label{sec1} + + 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. + + 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. + + You should have received a copy of the GNU General Public License + along with this program. If not, see <http://www.gnu.org/licenses/>. + + 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 \LaTeX{}ed + 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). + + Written by Kalvis M. Jansons (email address \texttt{k@kalvis.com}), but based on + txt2html by Seth Golub (email address \texttt{seth@aigeek.com}). 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). + + 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 ``\(\backslash\)'', which is often the + safest setting for ``unknown'' document formats. + +\subsubsection*{DO YOU WANT A DEMONSTRATION? IF SO, SEE BELOW.} + +\begin{itemize} + + \item For a trivial demo of txt2tex, type ``txt2tex --info |txt2tex -ec''. + \begin{itemize} + \item For a nicer copy of this readme file, try + ``txt2tex --info |txt2tex -ec -ns -10pt''. + \item Or maybe you will like the look of this better: + ``txt2tex --info |txt2tex -tf -ec -ns -10pt''. + \begin{itemize} + \item 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''. + \end{itemize} + + \item On a unix or linux system try ``txt2tex --demo''. + \end{itemize} + + \item The best test is clearly to try it on one of your own plain text files. +\end{itemize} + +\subsection*{Paper size}\label{sec1.1} + + 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. + +\subsection*{Tag syntax}\label{sec1.2} + + 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\{\(\backslash\)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\(\backslash\)section*\{\(\backslash\)center''. Also + remember when using tags on a command line, you must take account of the + normal shell escaping conventions. + +\subsection*{Some important command line options}\label{sec1.3} + + 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 ``--''. + +\subsubsection*{\textit{[(-dt|--doctype) <doctype>]}} + + 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. + +\subsubsection*{\textit{[-10pt|-11pt|-12pt]}} + + Used to set the \LaTeX{} font size. The default is 12pt. The ``pt'' can + be dropped. + +\subsubsection*{\textit{[(-up|--usepackage) <name>|off]}} + + Sets a \LaTeX{} ``usepackage'' definition. No default packages loaded. + +\subsubsection*{\textit{[(-lh|--latexhooks) <name|mode>]}} + + 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 ``\(\backslash\)jobname'' is used as the name. Hooks are off by default. + + Remember in \LaTeX{} the basename of the \LaTeX{} file is stored in the \LaTeX{} + variable ``\(\backslash\)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. + +\subsubsection*{\textit{[(-ec|--escapechars) [<mode>]]}} + + Used to set the escape mode. The options (which can be bitwise ORed) are: + +\begin{verbatim} + 1 --- escape \ + 2 --- escape $ + 4 --- escape ^ and _ + 8 --- escape < and > + 16 --- escape & + 32 --- escape | + 64 --- escape # + 128 --- escape ~ + 512 --- escape % + 1024 --- escape " +\end{verbatim} + + (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. + +\subsubsection*{\textit{[-bm|--batchmode]}} + + Makes \LaTeX{} run in its non-stopping mode, i.e.\ ignores any \LaTeX{} + warnings about over-full boxes etc.. Off by default. + +\subsubsection*{\textit{[-nv|--noverbatim]}} + + 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. + +\subsubsection*{\textit{[-sv|--splitverbatim]}} + + Use this if verbatim blocks can be split by page breaks; the default is + that they cannot. + +\subsubsection*{\textit{[(-pb|--prebegin) <num>]}} + + Sets the number of preformatted-looking lines (2 by default) needed + to begin a verbatim block. The options are: + +\begin{itemize} + \item 0 --- put the entire document in a verbatim block. + \item 1 --- one trigger line, so even a single line can be put in verbatim. + \item 2 --- two trigger lines. + \item 3 --- same as 1, but verbatim blocks can start only after a + blank line. +\end{itemize} + + Less than 0 is set to 0 and more than 3 is set to 3. + +\subsubsection*{\textit{[(-pe|--preend) <num>]}} + + 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. + + 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. + +\subsubsection*{\textit{[(-p|--preformat) <num[,num[,num]]>]}} + + This option sets the values of the following variables: + +\begin{itemize} + \item $verbatim_white_min (6), + \item $verbatim_min (6), + \item $verbatim_post_min (3), +\end{itemize} + + where the numbers in () are the defaults. If only one number is given, + it sets $verbatim_white_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_white_min spaces after + the start of the line and the line contains a non-space character + followed by $verbatim_post_min non-word characters. + + Note that tabs are expanded before these tests. + +\subsubsection*{\textit{[-ns|--nosectionnumbers]}} + + 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. + +\subsubsection*{\textit{[-np|--nopagenumbers]}} + + Do not number \LaTeX{} pages, i.e.\ set the pagestyle to empty. + +\subsubsection*{\textit{[(-lm|--listmode) <mode>]}} + + Sets the list mode; the bitwise ORed options are: + +\begin{itemize} + \item 0 --- automatically number and label lists, renumbering what appear + to be lists with errors. Use standard \LaTeX{} numbering and labelling. + \item 1 --- keep the original numbers (or letters) on enumerated lists, but + put standard labels on itemized lists. + \item 2 --- turn itemized lists into enumerated lists. + \item 4 --- hrules end all active lists. + \item 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. + \item 16 --- turn \LaTeX{} description environments into enumerate; this may + sound a strange thing to do, but leads to nice results. Try it! + \item 32 --- do not nest description environments. Normally a new + description starts for every new level of indentation, but this mode + switches this feature off. +\end{itemize} + + Using ``-lm'' without a following number sets the default mode 0. + +\subsubsection*{\textit{[(-de|--description) <regexp>|off]}} + + 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. + +\subsubsection*{\textit{[(-s|--shortline) <[-]num>]}} + + 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. + +\subsubsection*{\textit{[(-ss|--shortlineskip) <length>]}} + + 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''. + +\subsubsection*{\textit{[(-r|--hrule) <num>|off]}} + + 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. + +\subsubsection*{\textit{[(-sm|--smallmargins) [<mode>]]}} + + \LaTeX{} defaults to large margins, but I like small (1in) margins. The + bitwise ORed options are: + +\begin{itemize} + \item 0 --- standard \LaTeX{} margins. + \item 1 --- 1in X margins. + \item 2 --- 1in Y margins. + \item 3 --- 1in X and Y margins. +\end{itemize} + + The default is 0. If ``-sm'' is not followed by a valid number, then + option 3 is set. + +\subsubsection*{\textit{[(-t|--title) <title>]}} + + You can specify a title to be placed at the top of the document. + +\subsubsection*{\textit{[(-tt|--titletag) <tag>]}} + + Used to set the title tag. The default tag is ``centerline\{\(\backslash\)LARGE\(\backslash\)bf''. + +\subsubsection*{\textit{[-tf/+tf] | [--titlefirst/--notitlefirst]}} + + Use the first non-blank line as the title of the document. Off by default. + +\subsubsection*{\textit{[(-pi|--parindent) <num>]}} + + 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. + +\subsubsection*{\textit{[(-c|--caps) <num>]}} + + 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. + +\subsubsection*{\textit{[(-ct|--capstag) <tag>|off]}} + + 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*''. + +\subsubsection*{\textit{[(-st|--solotag) <tag>|off]}} + + 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*\{\(\backslash\)textit''. Set it to ``off'' for no solo lines. + +\subsubsection*{\textit{[(-m|--mail) [<mode>]]}} + + Used to set the mail mode. The bitwise ORed options are: + +\begin{itemize} + \item 1 --- deal with mail headers and mail quoted text. + \item 2 --- add half-line width right-flushed hrules at the beginning of + new messages. Strange, but easy to see! + \item 4 --- add a \LaTeX{} ``clearpage'' before each new message. + \item 8 --- do not print the mail header. +\end{itemize} + + ``-m'' without a following number sets the default mail mode of 1. (Any + non-zero option also includes option 1.) + +\subsubsection*{\textit{[-u/+u] | [--unhyphenate/--nounhyphenate]}} + + Enables unhyphenation of the raw text, so we can leave hyphenation to + \LaTeX{}. On by default. + +\subsubsection*{\textit{[(-ul|--ulength) <num>]}} + + 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. + +\subsubsection*{\textit{[(-uo|--uoffset) <num>]}} + + Sets the offset tolerance for underlines of plain text headings. The + default is 1. + +\subsubsection*{\textit{[(-tw|--tabwidth) <num>]}} + + Sets the width of a tab. The default is 8. + +\subsubsection*{\textit{[-e/+e] | [--extract/--noextract]}} + + Sets extract mode for making inserts for other \LaTeX{} documents. Off + by default. + +\subsubsection*{\textit{[(-rs|--ruleset) <file>]}} + +\subsubsection*{\textit{[+rs|--noruleset]}} + + 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. + +\subsubsection*{\textit{[-ro/+ro] | [--rulesetonly/--norulesetonly]}} + + 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. + +\subsubsection*{\textit{[(-H|--heading) <regexp>]}} + + 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: + + -H '^ *\(\backslash\)d+\(\backslash\). \(\backslash\)w+' -H '^ *\(\backslash\)d+\(\backslash\).\(\backslash\)d+\(\backslash\). \(\backslash\)w+' -H '^ *\(\backslash\)d+\(\backslash\).\(\backslash\)d+\(\backslash\).\(\backslash\)d+\(\backslash\). \(\backslash\)w+' + + Then lines like: + + 2. Examples\\ + 2.1. More Examples\\ + 2.1.1. Even More Examples + + 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''). + +\subsubsection*{\textit{[(-HT|--headingtags) <tag1[,tag2...]>|shift|number]}} + +\subsubsection*{\textit{[(-TH|--trimheadings) <regexp>]}} + + 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''. + +\subsubsection*{\textit{[-EH/+EH] | [--explicitheadings/--noexplicitheadings]}} + + 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. + +\subsubsection*{\textit{[(-db|--debug) <num>]}} + + Debug mode for ruleset dictionaries. Bitwise OR what you want to see: + +\begin{itemize} + \item 1 --- the parsing of the dictionary. + \item 2 --- the code that will make the ruleset. +\end{itemize} + +\subsubsection*{\textit{[(-tr|--trim) <num|regexp>]}} + + 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. + +\subsubsection*{\textit{[(-sw|--switch) <keyword>]}} + + 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. + +\subsubsection*{\textit{[-tc|--twocolumn]}} + + 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. + +\subsubsection*{\textit{[-ls|--landscape]}} + + Sets \LaTeX{}'s ``landscape'' option. Off by default. + +\subsubsection*{\textit{[-sp|--sloppy]}} + + Sets \LaTeX{}'s ``sloppy'' option, which is particularly useful for slides. + Off by default. + +\subsubsection*{\textit{[-d|--draft]}} + + Save the output in a file called draft.tex. Off by default. + +\subsubsection*{\textit{[(-h|--help)/--info/--demo]}} + + --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 \LaTeX{}ed version of the ``readme'' file; note that + the ``demo'' makes t2t_readme.txt, .tex, .dvi, .aux, and .log. + +\subsubsection*{\textit{[-v|--version]}} + + Prints the txt2tex version number. + +\subsection*{Option sets}\label{sec1.4} + + Below the ``__END__'' 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 ``\(\backslash\)'' is a continuation + character, so long options can be put on several lines. These include: + +\begin{description} + \item[remind] --- turns the output of the unix remind program into nice \LaTeX{}; + call remind using ``rem -n |sort''. + \item[num] --- picks out simple numbered headings. + \item[n] --- a variant of the above. + \item[plain] --- a very plain style, which is good for university work! + \item[trim] --- removes leading spaces before txt2tex processes the line. + \item[lynx] --- for lynx browser output. + \item[noL] --- normally \(\backslash\)014 produces a \LaTeX{} ``clearpage'', but this option + removes \(\backslash\)014 before txt2tex sees the line. + \item[HH] --- this is what I use to print the ``Happy Hacker'' newsletter. + \item[man] --- useful for dealing with unix man pages, but could be better! + \item[pagesec] --- each new section starts on a new page. + \item[pagesubsec] --- each subsection starts on a new page. + \item[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. + \item[handout] --- used for student handouts. + \item[letter] --- used for writing letters, but you need to define your own + letter-hook files with your address etc. + \item[preview] --- not for \LaTeX{}ing, 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 [:-)] + \item[dict] --- turns a list of the form `word: text' into a \LaTeX{} description + environment. + \item[phone] --- turns a list of the form `phrase: text' into a \LaTeX{} description + environment. I use this for a personal phone book. + \item[fn] --- turns fancy numbered lists, with numbers like 1.1.1, into \LaTeX{} + description environments. Often useful for printing contracts off the net! + \item[lpr] --- used as part of a fancy plain text printer filter. + \item[lpn] --- used by the Lockpicker Network. + \item[netrc] --- used to print a .netrc file. +\end{description} + +\subsection*{A sample ruleset}\label{sec1.5} + + 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. + + 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. + +\subsubsection*{\textit{/<<(.*?)>>/ -f-> $1}} + + 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\(\backslash\)footnote\{Mathematics, UCL\}'' in the \LaTeX{} output. + +\subsubsection*{\textit{Kalvis M. Jansons -Fo-> Email: kalvis\(\backslash\)@jansons.org}} + + 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. + +\subsubsection*{\textit{/txt2tex/ -oi-> TXT2TeX \(\backslash\)\(\backslash\)emph\{(written by Kalvis)\}}} + +\subsubsection*{\textit{/pheonix/ ---> phoenix}} + + 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). + +\subsubsection*{\textit{/tagad/ -ie-> my $time = localtime(time); $time =~ s/\(\backslash\):\(\backslash\)d\(\backslash\)d\(\backslash\)s.*//; $time}} + + 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. + +\subsubsection*{\textit{/\(\backslash\)*([a-z][a-z ]*[a-z])\(\backslash\)*/ -ti-> emph}} + +\subsubsection*{\textit{/\(\backslash\)*([a-z])\(\backslash\)*/ -ti-> emph}} + + 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. + +\subsubsection*{\textit{/<\(\backslash\)*(.*?)\(\backslash\)*>/ -tfi-> textbf}} + + 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. + +\subsubsection*{Saving the sample ruleset}\label{sec1.5.1} + + If you want to save this sample ruleset to adapt for your own use, type + ``txt2tex -sampleruleset > ~/.txt2tex-ruleset'', + + or direct it into a different file if you do not want it to be the default. + +\subsection*{Getting help}\label{sec1.6} + + Please contact me (Kalvis) with any problems or suggestions. + +\subsection*{Bugs}\label{sec1.7} + + 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. + + Ensure that you are using the latest version, which can be obtained from + any CTAN site. + +\subsubsection*{\textit{\texttt{Kalvis@Jansons.org}}} + +\end{document} |