summaryrefslogtreecommitdiff
path: root/web/glasgow/lit2x-0.16/literate/doc/programs.lit
diff options
context:
space:
mode:
Diffstat (limited to 'web/glasgow/lit2x-0.16/literate/doc/programs.lit')
-rw-r--r--web/glasgow/lit2x-0.16/literate/doc/programs.lit300
1 files changed, 300 insertions, 0 deletions
diff --git a/web/glasgow/lit2x-0.16/literate/doc/programs.lit b/web/glasgow/lit2x-0.16/literate/doc/programs.lit
new file mode 100644
index 0000000000..10ffb283b5
--- /dev/null
+++ b/web/glasgow/lit2x-0.16/literate/doc/programs.lit
@@ -0,0 +1,300 @@
+\section[Programs-and-options]{Programs to process literate documents}
+
+In this incarnation, the programs \tr{lit2pgm}, \tr{lit2latex}, and
+\tr{lit2texi} (to extract program, \LaTeX{}, or GNU Texinfo fodder)
+are just three ways of invoking one killer \tr{perl} script,
+\tr{lit2stuff}.
+%\begin{comment}
+%A shell script \tr{lit2info}, to run
+%\tr{lit2texi} and then \tr{makeinfo} is not yet implemented. A script
+%\tr{lit2dvi} to run \tr{lit2latex} and then some sequence of
+%\tr{latex} and \tr{makeindex} invocations is also not out of the
+%question.
+%\end{comment}
+
+[Actually, this same script may be invoked as
+\tr{mkdependlit},\index{mkdependlit} to
+build a set of \tr{make} dependencies for a literate document, as
+\tr{lit2text}\index{lit2text}, to extract just the non-code text
+(perhaps for spell-checking), or as \tr{lit2changelog}, which is the
+(mainly unimplemented) interface to the changelog-slurping code. I
+ignore these details herein.]
+
+APRIL91: there are starting to be enough options that getopt-style
+one-letter names aren't enough/too obtuse. Some revision may be in
+order there... See \sectionref{revised-pgm-options}.
+
+For all three programs, their invocation takes the form
+\tr{lit2<whatever> [options] [input-file]}.
+Usually, output is to a file determined from the input-file's suffix
+(e.g., a \tr{.hs} file from a \tr{.lhs} file); if no input file is
+provided or life becomes confused, output is to the standard output.
+You can control input and output explicitly with the \tr{-i} and
+\tr{-o} options.
+
+Known file suffixes and what they mean:
+
+\begin{tabular}{ll}
+.lit & a literate-document file with no code in it (e.g., this one) \\
+.lhs & literate \Haskell{} source \\
+.lprl & literate Perl source \\
+.llex & literate Lex source \\
+.lc & literate C source \\
+.lh & literate C header source \\
+.ltex & literate \TeX{} macros \\
+.lf & literate FORTRAN \\
+\end{tabular}
+
+The suffixes \tr{.itex} and \tr{.itxi} indicate the intermediate files
+from ``separate compilation'' (to \LaTeX{} and Texinfo, respectively)
+of parts of a larger document.
+
+In ordinary life, given a literate C program \tr{foo} in file
+\tr{foo.lc}, one would hope that the following simple invocations
+would suffice:
+\begin{verbatim}
+lit2pgm foo.lc
+gcc -o foo foo.c
+
+lit2latex foo.lc
+latex foo.tex
+
+lit2texi foo.lc
+makeinfo foo.texi
+# (and if you really want to make things right, use the script...
+postmakeinfo foo.info
+# as well)
+\end{verbatim}
+
+What follows are the options to control these programs (and to
+complicate your life [and mine, too]). Not all command-line options
+make sense for all three programs; they are so noted. Options may be
+glopped together in the best getopt(3) style.
+
+\subsection*[A_option]{\pl{-A <pgm-name>} option}
+\index{a option@-A <pgm-name> option}
+(For hackers only.) Assume the program was invoked as \tr{<pgm-name>}.
+must be the first option given. Still has to be either \tr{lit2pgm},
+\tr{lit2texi}, or \tr{lit2latex}.
+
+\subsection*[c_option]{\pl{-c} option}
+\index{c option@-c option}
+(Not \tr{lit2pgm}.) Produce Texinfo or \LaTeX{} output (as
+appropriate) but don't try to ``link'' together with other parts of
+the same document. Think of the \tr{-c} option to a C compiler...
+
+\subsection*[d_option]{\pl{-d} option}
+\index{d option@-d option}
+Print debugging information. I will be monumentally surprised if this
+is of any use to you!
+
+\subsection*[capital_D_option]{\pl{-D} option}
+\index{D option@-D option}
+(\tr{lit2latex} only.) Print cross-references to code
+definitions in the text.
+
+APRIL91: this option stands some chance of being renamed if the
+pseudo-C-preprocessor comes in; see
+\sectionref{pseudo-C-preprocessor}.
+
+\subsection*[f_option]{\pl{-f <nodename-suffix>} option}
+\index{f option@-f <nodename-suffix> option}
+(\tr{lit2texi} only.) Append the string \tr{<nodename-suffix>} to
+every nodename in a file. This can be useful if you're trying to
+avoid nodename clashes between nodes in different parts of a big
+document (two of which might, for example, have nodes named
+``Introduction'').
+
+APRIL91: A feeble solution; see \sectionref{clumsy-node-namespace}.
+
+\subsection*[g_option]{\pl{-g <node-name>} option}
+\index{g option@-g <node-name> option}
+(\tr{lit2latex} only.) Grab the sub-tree of text for which node
+\tr{<node-name>} is the root. Used when you want to print a whole chapter
+or section or something, rather than just one Info node.
+
+{\em At this time, this option is only suitable for printing drafts.}
+
+What is actually done: the output \LaTeX{}-file consists of the
+pre-amble (really: everything before the first \tr{\section}
+command---not quite what you want), the subtree you asked for, and
+\tr{\end{document}}. Your section will be numbered \tr{1} no matter
+what.
+
+\subsection*[H_option]{\pl{-H <dir1>:<dir2>} option}
+\index{h option@-H <dir1>:<dir2> option}
+(For hackers only.) Used by villanous people to override the hardwired
+directories (\tr{<dir1>} for platform-specific files and \tr{<dir2>} for
+platform-independent \tr{perl} libraries) where the
+literate-programming system finds its stuff. Also see the \tr{-A}
+flag.
+
+\subsection*[i_option]{\pl{-i <input-file>} option}
+\index{i option@-i <input-file> option}
+Specify a specific input file. If not specified with \tr{-i}, then
+the first non-option command-line argument; if no such thing, then
+standard input. You may also specify standard input as the ``input
+file'' with \tr{-i -}.
+
+\subsection*[capital_I_option]{\pl{-I <directories>} option}
+\index{i option@-I <directories> option}
+Add (colon-separated) \tr{<directories>} to the front of the
+default path used to follow \tr{\input} commands (just \tr{.} at the
+moment). Only give one \tr{-I} option; I cannot promise what will
+happen if you give more than one.
+
+Slight magic: the \tr{.} in the path means: first, look in the
+directory where the file doing the \tr{\input}'ing is; if not there,
+look in the current working directory. (This is usually what you
+want.)
+
+\subsection*[capital_L_option]{\pl{-L} option}
+\index{l option@-L option}
+(\tr{lit2texi} only.) Alternate style of node linking---puts in more
+defaults for ``next'' and ``previous'' nodes. If a node doesn't have
+a ``next'' [``previous''] at its level (e.g., it's the last section in
+a chapter), then its ``next'' [``previous''] node will be the
+physically-next [-previous] one, regardless of sectioning level. (The
+default is for such nodes to have no next [previous] node.)
+
+[I like the -L node-linking scheme but \tr{makeinfo} issues warnings
+about it. APRIL91: newer version of some Info readers achieve the
+same effect using additional moving-around-the-tree commands.]
+
+\subsection*[l_option]{\pl{-l <language>} option}
+\index{l option@-l <language> option}
+(Not \tr{lit2pgm}.) Assume that any code in the input file is written in
+\pl{<language>} and process accordingly (automatic indexing, etc.).
+The \pl{<language>} is normally intuited from the input-file suffix
+(e.g., \tr{.lhs} suggests \Haskell{} code). The \tr{-x},
+\tr{-p}, and \tr{-t} options may be used to tweak cross-referencing,
+page-breaking, and typesetting of code, respectively.
+
+\subsection*[n_option]{\pl{-n} option}
+\index{n option@-n option}
+Follow \tr{\input} commands.
+
+\subsection*[capital_N_option]{\pl{-N <info-filename>} option}
+\index{n option@-N <info-filename> option}
+(\tr{lit2texi} only.) Arrange for the Info file to
+be called \tr{<infofilename>}. By default, for input file \tr{foo.xxx}, the
+Info file will be called \tr{foo.info}. For a multi-file
+document, the Info filename will be derived from the name of the
+first file encountered.
+
+\subsection*[o_option]{\pl{-o <output-file>} option}
+\index{o option@-o <output-file> option}
+Specify a specific output file. If not specified with \tr{-o}, then
+it's determined by puzzling over the input file's suffix (see the
+\tr{-i <input-file>} option). When in doubt, it reverts to the
+standard output. You may also specify standard output as the ``output
+file'' with \tr{-o -}.
+
+(For hackers only.) If the first character to the \tr{-o} argument is
+a \tr{|}, then the output is piped through the shell command(s) that
+presumably follow.
+
+\subsection*[capital_O_option]{\pl{-O} option}
+\index{o option@-O option}
+(\tr{lit2texi} and \tr{lit2latex} only.) At the beginning of each
+section, list the owner of the source file from which it was extracted.
+
+[APRIL91: There is some doubt just how this option would work; see
+\sectionref{recording-who-to-blame}.]
+
+\subsection*[p_option]{\pl{-p <pagebreak-hints>} option}
+\index{p option@-p <pagebreak-hints> option}
+(\tr{lit2latex} only.) The (language-specific) code for typesetting
+the code in the document is passed the \pl{<pagebreak-hints>} to
+further control how it is determined where pagebreaks are allowed.
+This is because it is not always obvious where to do pagebreaks in
+long stretches of code.
+
+These hints, if any, will be mentioned in the documentation of
+language-specific processing (\Sectionref{Language_specific}).
+
+[NOT IMPLEMENTED FOR ANY LANGUAGE]
+
+\subsection*[q_option]{\pl{-q} option}
+\index{q option@-q option}
+(\tr{lit2pgm} only.) Take quick shortcut. This will work if you are
+only using ribbon \tr{main} (i.e., the usual recommended practice).
+
+Should be much faster than the plain \tr{lit2pgm}.
+The \tr{-q} option will be the {\em default} in the Glorious new
+\Haskell{} compiler.
+
+\subsection*[r_option]{\pl{-r <ribbons-to-get>} option}
+\index{r option@-r <ribbons-to-get> option}
+(\tr{lit2pgm} only.) Extract code-ribbons \tr{<ribbons-to-get>}
+(comma-separated), instead of the default ribbon, \tr{main}.
+An artifact of the implementation is that \tr{-r ''} gets you
+\tr{main}; use \tr{-r junkName} to extract nothing.
+
+\subsection*[s_option]{\pl{-s <stop-list-file>} option}
+\index{s option@-s <stop-list-file> option}
+(\tr{lit2texi} and \tr{lit2latex} only.) The file
+\pl{<stop-list-file>} provides extra information for the automatic
+code-indexing about words that should {\em not} be indexed.
+One hacker's dross is another's gold.
+
+[I'm not sure this is used for any language yet. ToDo: check]
+
+\subsection*[capital_S_option]{\pl{-S} option}
+\index{s option@-S option}
+(Not \tr{lit2pgm}.) Process the input as if it is a standalone document.
+It is so processed if a \tr{\documentstyle} command is seen,
+\tr{-S} option or not.
+
+APRIL91: in jeopardy of going away; see
+\sectionref{pseudo-C-preprocessor}.
+
+\subsection*[t_option]{\pl{-t <typesetting-hints>} option}
+\index{t option@-t <typesetting-hints> option}
+The (language-specific) routines for
+typesetting (really: outputting) the code in the document is passed the
+\pl{<typesetting-hints>} to further control how typesetting is done.
+
+These (comma-separated) hints, if any, will be mentioned in the
+documentation of language-specific processing
+(\Sectionref{Language_specific}). Available hints:
+\begin{description}
+\item[\tr{-t tgrind}:]
+Typeset code blocks by passing them through the \tr{tgrind} program.
+%
+\item[\tr{-t ruled}:]
+Put lines (rules) above and below blocks of code.
+(The default may vary with other outputting options.)
+%
+\item[\tr{-t unruled}:]
+Do {\em not} put lines (rules) above and below blocks of code.
+%
+\item[\tr{-t bird}:]
+Format all code (but not pseudocode) with Bird-tracks in the first
+column. By default, only code input with Bird-tracks is so formatted.
+%
+\item[\tr{-t nobird}:]
+Format all code without Bird-tracks.
+\end{description}
+
+\subsection*[v_option]{\pl{-v} option}
+\index{v option@-v option}
+Be verbose. This is really a debugging thing, too.
+
+\subsection*[x_option]{\pl{-x <xref-hints>} option}
+\index{x option@-x <xref-hints> option}
+The (language-specific) code for indexing
+and/or cross-referencing the code in the document is passed the
+\pl{<xref-hints>} to further control how things are done.
+
+A general one you can use is \tr{-x noindex}, to turn off code
+indexing.
+
+These hints, if any, will be mentioned in the documentation of
+language-specific processing (\Sectionref{Language_specific}).
+
+An example might be using \tr{-l cpp -x extra:make} on the
+configuration files for \tr{jmake}. These files have both C
+pre-processor and \tr{make} things worthy of
+indexing/cross-referencing, and these options would ensure that the
+code was put through the appropriate routines for both languages.