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
***********************************************************************