This directory contains a set of macros (position.dtx) which are useful for {src} -> LaTeX converters. The macros allow a vertical alignment using the roman font. The basic idea is to have a number of "should be" positions on the paper, for example .5em per (input) character. If two or more blanks or a tab character is found in the input text, we use this position for output; if there is only one blank, it is stretched (or shrinked) to get near the position (current values are 0.25em ... 0.55em). Another macro (\mpout) can be used to generate "leaders" between specific positions in the input text. This is fine for example for block comments etc. Two small converters are also included as example how to use these macros: - tiny_c2l is a C/C++/Java -> LaTeX converter. This converter does only a few very basic things: recognition of keywords, comments, strings etc; no reformatting of text is done; lex/yacc files are not (yet) understood (they may be converted as normal C files, but the patterns get no special treatment, as it should be). This may lead to erors if a pattern contains single " or ' without preceding \. - tiny_t2l is a general converter for other programming languages. No language specific patterns are recognized (as keywords, comments, strings etc.); only positioning and linebreaking of the text are done. The files are given as FLEX source (tiny_c2l.l, tiny_t2l.l), LX2L source (tiny_cvt2ltx.lx in the lx2l-src subdirectory) and as M$Dog exe file for convenience of these users. If you want to build tiny_c2l or tiny_t2l, you'll need flex 2.5x (available from many sites) and a C compiler. The converters were tested under DOS, UNIX and VMS; Compilation should be no problem on other platforms. If you want to so some development, you should grab the lx2l preprocessor (http://www.informatik.fh-mannheim.de/lx2l) to generate the files from the LX2l source. Because the main goal in writing tiny_cvt2ltx was testing the macros, it includes some "advanced" features that are AFAIK currently not found in any other converter: - vertical alignment (using roman font!) of text after two or more blanks or a tab - support for block comments: o leaders (characters recognized by the flex file are <>+$#%~*): If at least 10 characters (of one sort each) are found, they are replaced by a "leader" macro to fill the space between the two positions. o block comments: if a comment starts with /*\b (or with multiple stars, as in /*******************\b), it is interpreted as a block comment: # the used font is roman # the colon character (:) is aligned already after a single blank - "smart linebreaks": linebreaking is not done simply to the begin of the next line: rather a context-sensitive linebreak (according to the C language structure) is done: o if the linebreak occurs inside a normal code line, the continuation lines are indented 0.5em more than the starting line. o if the linebreak occurs inside a preprocessor command, a backslash is inserted at the end of the line, and the line is indented 1.5em more than the starting line. o if the linebreak occurs inside a string, it is done either after a blank or after a "\n" sequence in the string. In both cases a backslash is inserted at the end of the line and the continuation line begins at the start of the next line (without indentation). o If the linebreak occurs inside a C comment (using /* ... */), the continuation line gets a star to indicate the comment continuation. o If the linebreak occurs inside a comment after a command, the continuation lines are indented to the beginning of the comment (not to the beginning of the command in the start line). If the (ASCII) position of the comment start is greater than 50, the comment is indented like a normal code line. These lines get also a star at begin of the comment. o If the linebreak occurs inside a C++ comment (using //), the continuation lines get also the // comment characters. input text for some linebreaking examples: #define PP_STMTZ dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt();dummy_stmt();dummy_stmt();dummy_stmt();dummy_stmt();dummy_stmt();dummy_stmt(); dummy_stmt(); /* long comment long comment long comment long comment long comment */ dummy_stmt(); // long comment long comment long comment long comment long comment "This is a long string This is a long string This is a long string This is a long string" "This_is_a_long_string\nThis_is_a_long_string\nThis_is_a_long_string\nThis_is_a_long_string\n" output text for the above examples (using a very short linewidth): #define PP_STMTZ dummy_stmt(); dummy_stmt(); \ dummy_stmt(); dummy_stmt(); dummy_stmt(); \ dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt(); dummy_stmt();dummy_stmt();dummy_stmt(); dummy_stmt();dummy_stmt();dummy_stmt(); dummy_stmt(); dummy_stmt(); /* long comment long comment * long comment long comment * long comment */ dummy_stmt(); // long comment long comment // long comment long comment // long comment "This is a long string This is a long string \ This is a long string This is a long string" "This_is_a_long_string\nThis_is_a_long_string\n\ This_is_a_long_string\nThis_is_a_long_string\n" - support for embedded LaTeX comments: o If a comment starts with /*\a, processing mode switches to embedded LaTeX (append mode): everything inside this comment is copied verbatim to the (LaTeX) output file, without any processing. So you can include arbitrary LaTeX commands inside the text. When using this form, the output is surrounded by /* and */. o If a comment starts with /*\v, it is treated as "verbatim" embedded LaTeX comment. The processing mode is the same as for the /*a\a form, but the /* and */ comment delimiters are not copied. This form is useful, if you want to include \section{} or \index{} commands etc. into your file, that should not be included in /* */. - Parts of the code may be omitted from the output. This can be done silently or with notification of how many source lines were skipped. - special support for multiple file projects: This part is taken directly from the cvt2ltx family. You may use each generated file as standalone file or as include file without any modification; just include position in the list of style files, and everything else is done by the macros. A small example can be found in multiple.tex in this directory. Continuation lines and linebreaking are done by the TeX macros; so you can easily modify the flex file easily to build a converter for another language. Because tiny_c2ltx was intended mainly for testing the macros, it has a number of restrictions (and perhaps also many bugs): - lex/yacc files are not (yet) recognized; if you use single " characters (without \) in a pattern, the following code is treated as a string. - 8 bit support is done only by using the inputenc package - no line numbering - only 2 embedded LaTeX modes - no autoindent - ... The macros are intended to be used in another package (cvt2ltx); the converters of this family are much more powerful and don't have the above restrictions. The cvt2ltx family as well as tiny_c2ltx are distributed under the GNU General Public License. Read the file copying for details. The latest version of tiny_c2l and position.dtx can be found at ftp://axp3.sr.fh-mannheim.de/tiny_c2l/* The main reason for making public this test software is to get opinions and critics as well as additions of personal needs. The more feedback I will get, the faster cvt2ltx and tiny_c2ltx will come to a more useful state. So if you find a bug or if you have a suggestion about the macros or tiny_c2ltx, drop me a line: m.plugge@fh-mannheim.de Michael Plugge *********************************************************************** changes for tiny_c2l Version 1.2 (7-SEP-1999): - lots of bugfixes - some additional command-line options - support for stdin/stdout - header/footer text can be given as comand-line option - the fonts are defined in the style file - value of tab -> spc is can be given as comand-line option - options are no longer position dependend - additional comment mode /*\f ("fill" comment; see testfile.l - small help screen (use tiny_c2l -?) - some more bugfixes - support for Java - omit source code - linebreaking is done also after operators or `;' (without needing spaces) - the position macro package is now written as .dtx file - the file position.dtx includes a small manual for tiny_c2l known bugs: - Aignment of multiline comments may be incorrect - lex/yacc patterns includeing lonely double quotes generate false results ***********************************************************************