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/tiny_c2l/README |
Initial commit
Diffstat (limited to 'support/tiny_c2l/README')
-rw-r--r-- | support/tiny_c2l/README | 231 |
1 files changed, 231 insertions, 0 deletions
diff --git a/support/tiny_c2l/README b/support/tiny_c2l/README new file mode 100644 index 0000000000..84382a4e18 --- /dev/null +++ b/support/tiny_c2l/README @@ -0,0 +1,231 @@ +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 +*********************************************************************** + |