summaryrefslogtreecommitdiff
path: root/support/tiny_c2l/README
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/tiny_c2l/README
Initial commit
Diffstat (limited to 'support/tiny_c2l/README')
-rw-r--r--support/tiny_c2l/README231
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
+***********************************************************************
+