This is Info file literate.info, produced by Makeinfo-1.47 from the input file literate.texi.  File: literate.info, Node: Top, Up: (dir) This guide introduces a suite of programs for literate programming. They support documentation as a natural part of programming; a program's organization focusses on understanding by humans. If you installing this system as a standalone entity, please see section *Note lit-install::, near the end. This document begins with a few words about literate programming, the objectives of this system, and the Neat Stuff that this system is supposed to do for you (i.e., cheap, tasteless self-promotion). See section *Note Highlights::. The real goods come next, most notably: * an alleged "tutorial" on the LaTeX-like markup language in which documents/programs are written (section *Note notation-tut::); * a "reference manual" about the same markup language; this tends to be what you consult once you are using the system (section *Note Command_reference::); * the programs/tools to mangle your documents/programs into useful forms (section *Note Programs-and-options::). There are other sections, too, in greater-or-less states of usefulness. It would be a good idea to understand the rudiments of GNU Info files before reading much further -- type `info info' at your favourite Unix prompt. Or you could just ignore all mention of Info files... YOUR SUGGESTIONS FOR IMPROVING THIS SYSTEM ARE MOST WELCOME. DISCLAIMER: "Literate programming" is not my(WDP)/our area of expertise. This system has been developed mainly to suit our needs and has evolved on a grease-the-squeaky-wheel principle. However, we wouldn't bother to document it if we didn't think there was something to it! APRIL91 PROPOSALS: I am thinking about some changes to the system, NOT YET IMPLEMENTED. Discussion about most (all?) of them is gathered together in section *Note april91-proposals::. (You can find all discussion of proposed changes by grepping for "APRIL91".) SEPT92 THOUGHTS: Still haven't really worked on this system. I have typed a few further thoughts at the obvious place. I have fixed one or two bugs, and I have incorporated Adriaan Joubert's (adriaan@dcs.qmw.ac.uk) stuff for "literate Fortran," for which I am most grateful. (See, it really is easy to extend :-) For more information about "real" literate programming, the bibliography of literate programming in the (approx: ToDo) March 1991 SIGPLAN Notices may be of use. * Menu: * Highlights:: Literate programming, Glasgow style. * notation-tut:: A LaTeX-like document markup language (tutorial-ish). * Command_reference:: LaTeX-like markup commands: reference. * Language_specific:: Language-specific processing. * Habits:: A checklist of good literate habits. * Caveats:: Caveats: bugs and foibles. * Programs-and-options:: Programs to process literate documents. * Info_etc:: Using your processed literate documents. * april91-proposals:: APRIL91 PROPOSALS. * sept92-thoughts:: SEPT92 THOUGHTS. * lit-install:: Standalone installation of Glasgow literate programming. * Index:: Index.  File: literate.info, Node: Highlights, Next: notation-tut, Prev: Top, Up: Top Literate programming, Glasgow style =================================== Literate programming is a style that tries to maximise humans' understanding of programs by full-scale use the tools of the description trade (typesetting, indexing, etc.) to say what a program does and how it works. The power of literate programming is in the synergy between writing code and documentation in a unified framework. So, for example, in Knuth's original WEB system [ToDo: add reference(s)] "code" and "text" may be intermingled as much as you like, the pieces of "code" may appear in any order (even though it's only glorified Pascal), and quite substantial cross-referencing and indexing (not to mention TeX-based typesetting) is built in. Programs are just documents for people to read and enjoy which happen to have machine-manipulable code "buried" in them. * Menu: * Glasgow-objectives:: Objectives of our Glasgow system. * Glasgow-NON-objectives:: NON-Objectives of our system. * Other-Glasgow-features:: Other features of our Glasgow system. * Glasgow-NON-features:: Shortcomings of our system.  File: literate.info, Node: Glasgow-objectives, Next: Glasgow-NON-objectives, Prev: Highlights, Up: Highlights Objectives of our Glasgow system -------------------------------- With our Glasgow system, your "program" is a LaTeX-like document, with the compilable/executable code marked off by a `\begin{code}' ... `\end{code}' pair (or equivalent shortcut notation). From there, your "program" may be (a) compiled/interpreted [by extracting the embedded code and feeding it to a "normal" compiler/interpreter]; (b) turned into a beautiful typeset document to be smeared onto dead trees, or (c) turned into an on-line viewable/jump-aroundable document. Here are the specific (distinctive?) objectives of the Glasgow system. * Menu: * on-line-form:: Programs/documents in an on-line form. * medium-scale:: Programming on a medium scale. * language-independence:: Programming language independence. * code-verissimilitude:: Program code written exactly as in illiterate programs. * ASCII-declarative-markup:: Use of ASCII-based files, "declarative" markup. * hierarchical-structure:: Use of hierarchical structure. * separate-compilation:: "Separate compilation" for large programs/documents. * one-file-many-purposes:: Using one file in several ways.  File: literate.info, Node: on-line-form, Next: medium-scale, Prev: Glasgow-objectives, Up: Glasgow-objectives Programs/documents in an on-line form ..................................... The people-oriented documents produced by literate-programming systems are usually on paper (this system provides those, too). For working programmers, their good properties are largely overshadowed by one fact: paper documents go stale quickly. Also, large programs turn into not-so-navigable large piles of dead trees. Surely we can do better! Note our emphasis on presenting work-in-progress, as opposed to a system that emphasises the presentation of the final perfect programming gem. Our goal is that these on-line documents should be the medium of choice for programmers' daily reference. (APRIL91: See the note about "literate Para mode" in section *Note literate-para-mode::.) Our choice for an on-line format is the GNU Info format, a primitive ASCII-only sort-of hypertext system. The main reason for this choice is to let the GNU people do as much of our programming for us as possible! The program `info' can display Info files on just about any kind of terminal; `xinfo' works with the X Window System; the ubiquitous GNU Emacs has an ever-improving Info mode.  File: literate.info, Node: medium-scale, Next: language-independence, Prev: on-line-form, Up: Glasgow-objectives Programming on a medium scale ............................. We aren't really interested in programming-in-the-small (one person, a few hundred lines of code), and we don't know about programming in the large (hundreds of programmers, millions of lines of code); our target audience is five-person projects working on programs the size of, say, a Haskell compiler :-)  File: literate.info, Node: language-independence, Next: code-verissimilitude, Prev: medium-scale, Up: Glasgow-objectives Programming language independence ................................. The system may be used for literate programming with any programming language. However, the quality of the indexing, typesetting, etc., support will vary, depending on whether that language is "supported" or not. Fortunately, the current implementation, while clunky (see section *Note clunky-implementation::, makes it easy to add better support for a given programming language. See section *Note reordering-unemphasis:: for a related comment about code re-ordering.  File: literate.info, Node: code-verissimilitude, Next: ASCII-declarative-markup, Prev: language-independence, Up: Glasgow-objectives Program code written exactly as in illiterate programs ...................................................... You put executable/compilable code into your literate programs by inserting it in a `\begin{code}/\end{code}' environment (or the "Bird-track" equivalent); for example: \begin{code} main _ = [ AppendChan stdout "Hello, world!\n" ] \end{code} The principle is: you can write code inside a `\begin{code}/\end{code}' environment *exactly* as you would in an illiterate program in the same language. This brings up a dichotomy that pervades literate programs: everything in the program is either *code* (stuff in a code environment, or equivalent) or *text* (everything else).  File: literate.info, Node: ASCII-declarative-markup, Next: hierarchical-structure, Prev: code-verissimilitude, Up: Glasgow-objectives Use of ASCII-based files, "declarative" markup .............................................. ASCII-based files (as opposed to some weird binary "internal format"): so you can read the files directly and e-mail them to your friends. Insisting on ASCII files means some kind of markup commands buried in the text. We want the markup to be "declarative," that is, to say "what you want" rather than "how to produce what you want." Section numbering, generation of a table of contents, much indexing work, cross referencing, creating of the Info "node" structure, etc., etc., is done automagically. Our starting-point choice for a "declarative" markup notation was LaTeX, because that's what we know (and so do a lot of other people). You could make the case that GNU's Texinfo format would've been better, esp. given some of our other objectives. Or: you could argue that we should've chosen a completely different notation, because some people look at our literate files and think they *are* LaTeX, which they are not. The most important parts of our LaTeX-like notation are introduced in section *Note notation-tut::, and the whole mess is exhaustively described in section *Note Command_reference::.  File: literate.info, Node: hierarchical-structure, Next: separate-compilation, Prev: ASCII-declarative-markup, Up: Glasgow-objectives Use of hierarchical structure ............................. That is: programs/documents divided into sections, subsections within sections, subsubsections... Hierarchy is a very powerful structuring tool, but its utility for wading around a large sea of code is not apparent. APRIL91: See the comments about a "literate Para mode" in section *Note literate-para-mode::. See also section *Note sectioning-large-documents::.  File: literate.info, Node: separate-compilation, Next: one-file-many-purposes, Prev: hierarchical-structure, Up: Glasgow-objectives "Separate compilation" for large programs/documents ................................................... This really follows from the size of project we're trying to support; it's just *too slow* to have to slurp in the *whole* program text and do anything... (It's pretty slow as it is :-) Separate compilation of the embedded code: Use the normal mechanisms of your programming language. For example, if you have a literate C file, `foo.lc', then you would extract the code into `foo.c' (command: `lit2pgm foo.lc') and compile as normal (`gcc -c foo.c'). "Separate compilation" of the (LaTeX and (Tex)info) document-generating tasks: this is harder and quite a lot of work *has* to be done at "link time". What happens: the initial "separate compilations" of all the individual files in a program/document (e.g., `lit2texi -c foo.lc' or `lit2latex -c foo.lc') produce intermediate files (`*.itxi' and `*.itex' files, respectively). These are then consulted when a "link" is done (e.g., `lit2latex root.lit', where `root.lit' `\inputs' the other files). (It's complicated: use Makefiles!)  File: literate.info, Node: one-file-many-purposes, Prev: separate-compilation, Up: Glasgow-objectives Using one file in several ways .............................. Say you're writing a Haskell compiler :-), which includes the source code for a typechecker. On the one hand, you want this to be included in "the book" (document) that is the whole compiler. However, you may also want to have a "typechecker document" that is itself self-contained (if only because the "book" is so big). Going further: perhaps one module of your typechecker is so amazing that you want to publish it as a paper. You could make copies of files, edit them, etc., but that's tacky, and against a most deeply-held principle of literate programming: that you are looking at *the* source code for the program being described. As it stands, this system lets you put `\begin{onlystandalone}' and `\end{onlystandalone}' around pieces of your files that only apply in the "do this as a standalone document" case; similarly, `\begin{onlypartofdoc}' and `\end{onlypartofdoc}' for stuff that only applies in the "the glorious whole" case. APRIL91: I am fairly convinced I got this *wrong* and believe that this stuff would be much better handled with a pseudo-"C pre-preprocessor" (one that does not look inside code blocks [see deeply-held principle above; section *Note code-verissimilitude::]); see section *Note pseudo-C-preprocessor::.  File: literate.info, Node: Glasgow-NON-objectives, Next: Other-Glasgow-features, Prev: Glasgow-objectives, Up: Highlights NON-Objectives of our system ---------------------------- * Menu: * not-reinvent-LaTeX:: Not to reinvent LaTeX (or any other extensible notation). * reordering-unemphasis:: An un-emphasis on code-reordering.  File: literate.info, Node: not-reinvent-LaTeX, Next: reordering-unemphasis, Prev: Glasgow-NON-objectives, Up: Glasgow-NON-objectives Not to reinvent LaTeX (or any other extensible notation) ........................................................ Just as with Texinfo, our markup notation has a *fixed* set of commands. We don't have a `\define' command that let's you define new macros in terms of old ones. This is for simplicity, I suppose. APRIL91: see the note about fake "C pre-processing" in section *Note pseudo-C-preprocessor::.  File: literate.info, Node: reordering-unemphasis, Prev: not-reinvent-LaTeX, Up: Glasgow-NON-objectives An un-emphasis on code-reordering ................................. Some programming languages have a narrow-minded idea about what order the pieces of a program must be presented (e.g., COBOL: identification division, then file division, then data division [how many of you knew this :-]), and some literate-programming systems provide lots of machinery to get around this orderly intransigence. We write in Haskell, which is relatively open-minded about the order in which functions, etc., are presented. Re-splicing together code from dispersed program fragments doesn't buy you much -- and we think the same is true for most modern or semi-modern programming languages. Therefore, this system has only primitive support for reordering code.  File: literate.info, Node: Other-Glasgow-features, Next: Glasgow-NON-features, Prev: Glasgow-NON-objectives, Up: Highlights Other features of our Glasgow system ------------------------------------ * Menu: * sectioning-large-documents:: Sectioning support for large documents. * automatic-indexing:: Automatic indexing of your code. * manual-indexing:: Indexing by hand. * automatic-cross-referencing:: Automatic cross-referencing of your code. * shortcut-notations:: Shortcut notations. * TeX-to-ASCII:: The great "LaTeX to ASCII" problem solved!.  File: literate.info, Node: sectioning-large-documents, Next: automatic-indexing, Prev: Other-Glasgow-features, Up: Other-Glasgow-features Sectioning support for large documents ...................................... The main thing we've done here is *change* the sectioning commands (vs LaTeX) so it's easy to re-arrange chunks of the hierarchy. Also, a default Info "node" structure is worked out, based on the sectioning information. (Veteran Texinfo hackers will appreciate the joys of not typing error-prone `@menu's.) Sectioning in an individual file should *always* begins at `\section'; such files should then glued together in a "root file" with `\input' commands interspersed with `\upsection' and `\downsection' commands. `lit2latex'/`lit2texi' combine your files, putting appropriate real-LaTeX/Texinfo sectioning commands (`\part', `\chapter', etc.) in the right places. A side-effect of diverging from LaTeX sectioning is that we can support deeper nesting of sectioning commands. It's also neat to be able to change your mind about whether you want to start with (LaTeX-speak...) parts, chapters, sections, or whatever... Please see section *Note Sectioning:: for further details about this whole mess.  File: literate.info, Node: automatic-indexing, Next: manual-indexing, Prev: sectioning-large-documents, Up: Other-Glasgow-features Automatic indexing of your code ............................... An attempt is made to index all the "interesting things" in the code parts of your program. The success of this enterprise depends on the degree to which the language you are using is supported. In a paper manifestation, you'll get nice neat indexes, like we're used to. In an on-line manifestation, you would like to use the information to "point and jump" (our Info-based implementation does this, perhaps clumsily). APRIL91: See section *Note multiple-indexes:: for latest thoughts about indexing. Also, I've put some comment about free-text retrieval in section *Note free-text-index::.  File: literate.info, Node: manual-indexing, Next: automatic-cross-referencing, Prev: automatic-indexing, Up: Other-Glasgow-features Indexing by hand ................ Indexing your text (vs your code) is not automatic. You do it by hand with `\index{}' commands. The format of the `\index' commands is a simplified (?) form of `makeindex' commands. Section *Note Indexing:: gives the details.  File: literate.info, Node: automatic-cross-referencing, Next: shortcut-notations, Prev: manual-indexing, Up: Other-Glasgow-features Automatic cross-referencing of your code ........................................ Your code may also be automatically cross-referenced; again, it's based on finding "interesting things" in your code; furthermore, it depends on distinguishing between "definitions" and "uses", because the main purpose of cross-referencing is to let you move quickly from a "use" (e.g., of a function) to its "definition". APRIL91: Sometimes you would really like to be able to go from a definition to all of its uses. Perhaps this should be an option. Cross-referencing is automatically OFF when producing LaTeX documents (we found it mainly cluttered) and ON when producing Info files (which lets you jump to the definitions through a node's menu).  File: literate.info, Node: shortcut-notations, Next: TeX-to-ASCII, Prev: automatic-cross-referencing, Up: Other-Glasgow-features Shortcut notations .................. Within non-code parts of documents, code snippets may be included between `at' signs; e.g., `@f x y = y@' -- appropriate formatting, indexing, etc., will be done. APRIL91 COMMENT: I need to clarify the proper use of these `@'s. I also need to figure what to do when `@'s are not the right thing! (I think Texinfo has an over-proliferation of commands for marking off this and that in the text.) See section *Note code-in-text-formatting::. For the ordinary text to be shown in a typewriter font (much used in user's guides, for example), you may use the `\tr{}' command; the only restriction on `' is that braces must be balanced. The same trick for "plain" (roman) font is `\pl{}'. [APRIL91: See section *Note diff-fonts-in-text:: for further thoughts about fonts in your text.] APRIL91: See also: section *Note BNF-grammars::.  File: literate.info, Node: TeX-to-ASCII, Prev: shortcut-notations, Up: Other-Glasgow-features The great "LaTeX to ASCII" problem solved! .......................................... (Well, not quite...) A literate program looks an awful lot like a LaTeX document. If you convert the program to an Info file, then run the `info2ascii' script [which I haven't written yet :-] over it, you'll have a quite-reasonable all-ASCII nicely-formatted version of your LaTeX-ish input.  File: literate.info, Node: Glasgow-NON-features, Prev: Other-Glasgow-features, Up: Highlights Shortcomings of our system -------------------------- * Menu: * texinfo-limits:: Limits because of the Texinfo intermediate representation. * clumsy-node-namespace:: Node namespace is not "neat". * clunky-implementation:: A clunky implementation.  File: literate.info, Node: texinfo-limits, Next: clumsy-node-namespace, Prev: Glasgow-NON-features, Up: Glasgow-NON-features Limits because of the Texinfo intermediate representation ......................................................... We produce our on-line viewable GNU Info files by going through their Texinfo format. If something cannot be represented easily in Texinfo (which doesn't do things not easily representable in character-only ASCII), it ain't in our system. This leads to the following *very notable* shortcomings: 1. No graphics, pictures, or sound. 2. No fancy mathematical stuff of the sort TeX/LaTeX is so good at. Note: we would like to provide enough *basic* mathematical stuff so you aren't hamstrung by this restriction.  File: literate.info, Node: clumsy-node-namespace, Next: clunky-implementation, Prev: texinfo-limits, Up: Glasgow-NON-features Node namespace is not "neat" ............................ For all practical purposes, it's *your problem* to make sure that you don't get nodename clashes. This is really uncool. APRIL91: Some ideas for partial alleviation of making-up-nodenames weariness, see section *Note revised-sectioning::. Barring that, a good discipline for making up unique nodenames would be helpful (I haven't found one yet).  File: literate.info, Node: clunky-implementation, Prev: clumsy-node-namespace, Up: Glasgow-NON-features A clunky implementation ....................... The principle has been: do as little work as possible. (What do you expect from the proponents of lazy functional programming?) The implementation is the Perl Script From Hell, with a supporting cast of the Flex Program From Hell, and a whole bunch of exceedingly useful programs written by other people, mainly the GNU Info/Texinfo-related programs and `tgrind' (by Van Jacobsen). [We can pass along the source to all of these programs.]  File: literate.info, Node: notation-tut, Next: Command_reference, Prev: Highlights, Up: Top A LaTeX-like document markup language (tutorial-ish) ==================================================== Here is a simple silly literate Haskell program: \documentstyle[literate]{report} \rootsectiontype{\part} \begin{document} Here is my \Haskell{} program to send a message to my friends: \begin{code} main _ = [ AppendChan stdout (message ++ " to " ++ my_friends) ] \end{code} \section[message]{The Message} \begin{code} message = "Hello" \end{code} \subsection{Comments about the message and its implementation} \begin{enumerate} \item The message is given as a top-level pattern binding. \item The @message@ binding does not violate the monomorphic restriction; its type is \tr{[Char]}, which is not overloaded. \end{enumerate} \section[friends]{My friends} \begin{code} my_friends = ( \ y -> "Bob and Joe" ) 3 \end{code} \printindex \end{document} Here are some things to see in this example (don't worry if it doesn't make sense first time): * The compilable program (the parts between `\begin{code}'s and `\end{code}'s) is simply contained in marked-off parts of your document, and the code therein is completely ordinary (no special programming notation). Such *code* is one "kind of stuff" in your literate program; *text* is the other. * The overall document is arranged hierarchically (`\section', `\subsection', etc.) and looks an awful lot like a LaTeX document. * There is quite a bit about *what* makes up your document (sections, code, enumerated lists) and very little about *how* your document should be formatted (e.g., "skip 2 lines"). This is "declarative" markup. * Your program code will be indexed automatically; the `\printindex' command is how you say where you want the index included. * You can refer to things-in-your-code in the text parts of your document, by enclosing the reference in `@''s, as in `@message@'. The reference will be suitably indexed. * The sectioning commands (e.g., `\section') are odd (if you are used to LaTeX). Most important, a sectioning command gives a *relative* position in the hierarchy; this means that commands like `\rootsectiontype' can be used to adjust the absolute sectioning in the final document. In this example, the topmost section would be a LaTeX `\chapter' by default, but it's been changed to be a `\part'. * More not-LaTeX trivia: the optional argument to `\section' serves both as a label name (for `\ref', etc.) and as a node name for GNU Info files. The following sections describe the more interesting parts of our LaTeX-like notation, illustrated in the example above. (Before that is a micro-tutorial on LaTeX conventions, in section *Note micro-latex::.) * As the example above showed, the sectioning commands diverge quite significantly from LaTeX. Section *Note Sectioning:: gives the full details about sectioning. * The example shows how program code is included in a document in the simplest way: just begin `\begin{code}' and `\end{code}' around it. Section *Note code-in-doc:: describes the more involved uses of this feature. * Section *Note Cross_references:: and Section *Note Indexing:: describe how to take full advantage of the cross-referencing and indexing facilities in your literate programs. * Section *Note Examples:: is supposed to include several complete examples of literate programs but IT IS NOT FINISHED YET. Remember: Section *Note Command_reference:: is (supposed to be) a complete reference document about the LaTeX-like commands you may safely use. * Menu: * micro-latex:: A micro-tutorial on our LaTeX-like conventions. * Sectioning:: Sectioning commands. * code-in-doc:: Including program code in your document. * Cross_references:: Cross-referencing. * Indexing:: Indexing. * Examples:: Some complete examples [NOT FINISHED]. * Shortcuts:: Helpful short-cut notations.  File: literate.info, Node: micro-latex, Next: Sectioning, Prev: notation-tut, Up: notation-tut A micro-tutorial on our LaTeX-like conventions ---------------------------------------------- LaTeX is a document preparation system (described in a book of almost that name, by Leslie Lamport), and its notation is the basis of that used in this literate programming system. Unsurprisingly, one thing you can do with your literate programs is turn them into real LaTeX documents (for typesetting), using the program `lit2latex'. A few things to know about our literate-programming markup notation: * Backslash (`\') is the starts-a-command character. Therefore, `\item' and `\/' are commands, but `dog' and `(+)' are just plain text. * *Mandatory* arguments to a command are given inside curly braces. So, we would use `\foo{bar}' to pass one argument to the command `\foo'; we would use `\bar{hey1}{hey2}' to pass two arguments to the command `\bar'. * *Optional* arguments to a command are given in square brackets and come before mandatory arguments. So, for example, `\help[everyone]{lunch}' passes one optional and one mandatory argument to the command `\help'. * `\foo' is a *command* called "foo", while `\begin{foo}' `\end{foo}' is an *environment* called "foo" with being inside that environment. * The above isn't everything you need to know.  File: literate.info, Node: Sectioning, Next: code-in-doc, Prev: micro-latex, Up: notation-tut Sectioning commands ------------------- [APRIL91: After you read this, you may want to see some proposed changes in section *Note revised-sectioning::.] * Menu: * section:: The `\section' command. * How_to_section:: How to use `\section'. * sectiontype-and-ref:: The `\sectiontype' and `\sectionref' commands. * Node_specifications:: GNU Info node specifications with `\section'.  File: literate.info, Node: section, Next: How_to_section, Prev: Sectioning, Up: Sectioning The `\section' command ......................... There is really just one sectioning command: \section[Info-node-name]{Section heading} where `' is a positive integer, the sectioning depth. For example, you might have: \documentstyle[literate]{book} \rootsectiontype{\chapter} \begin{document} \section1[Node-1]{The top} \section2[Node-2]{The next level} \section3[Node-3]{The bottom level} \section3[Node-4]{More on the bottom level} \section2[Node-5]{Second part of the middle level} \section3[Node-6]{Bottom level, next section} \section3[Node-7]{Last section on bottom level} \end{document} As a convenience, the following synonyms are supported: \section \section1 \subsection \section2 \subsubsection \section3 \subsubsubsection \section4 Saying `\rootsectiontype{\chapter}' causes `\section1', `\section2', and `\section3' to be translated into the LaTeX/Texinfo commands `\chapter', `\section', and `\subsection', respectively. This system supports deeper section nesting than LaTeX (12 levels vs. 7). If you want a section heading but don't want anything to appear in the table of contents, put a `*' after the command name (just like LaTeX); for example: \subsection*[\pageref]{\pl{\pageref{}}} If you want something that looks like a section heading but really isn't (no table-of-contents entry, no Info node), you probably want the `\heading{}' command. [Support your local creaky implementation: you must put sectioning commands on lines of their own.] In making an Info file, the hierarchy of `\section<n>' commands will be turned into a corresponding hierarchy of Info nodes. With `info', you navigate along one level of the hierarchy with `Next'- and `Prev'-node links; you move up the hierarchy with `Up'-node links; and you move down the hierarchy (e.g., from a `\section<n>' to its `\section<n+1>'s) by choosing from an (automatically-generated) Info menu.  File: literate.info, Node: How_to_section, Next: sectiontype-and-ref, Prev: section<n>, Up: Sectioning How to use `\section<n>' ........................ The presumption is that *every file in a literate document will begin its sectioning with a `\section'* (equivalently, `\section1') and further sectioning will reflect a reasonable hierarchical structure *within* the file. You usually know this when you are typing in a particular file. What you often do *not* know is how the file fits into the larger document, and it is most annoying (as happens sometimes with LaTeX) to have to rename all `\chapter's to `\section's, or some such. The information on how things go together is usually in a "root file," which sticks things together with `\input', `\downsection' and `\upsection'; this example is typical: \section[Desugar_match]{@match@: compiling out pattern-matching} \downsection % each of the following files would start with a \section \input{Match.lhs} \input{DeTwiddle.lhs} \input{MatchCon.lhs} \input{MatchLit.lhs} \upsection The `\upsection's and `\downsection's determine what actual LaTeX/Texinfo sectioning command is generated for a particular `\section<n>' command. Unfortunately, the desired LaTeX/Texinfo sectioning command for the *top* section in your hierarchy depends on the kind of document you are producing. For example, should it be a `\part' or a `\chapter'? The solution here is to let you choose, with the `\rootsectiontype{\foo}' command. It says that `\section1's at the "top level" should be typeset as LaTeX/Texinfo `\foo''s. The defaults based on the `\documentstyle' should usually be adequate: \documentstyle \rootsectiontype article \section report \chapter book \chapter For a report, a useful variant might be `\rootsectiontype{\part}'.  File: literate.info, Node: sectiontype-and-ref, Next: Node_specifications, Prev: How_to_section, Up: Sectioning The `\sectiontype' and `\sectionref' commands ............................................. Another annoying thing with LaTeX sectioning is to type `Section~\ref{foo}' only to have `foo' turn out to be a "chapter" (not a "section"). In this system, you can type `\sectiontype{Node-name}' and the type of the sectioning command at node `Node-name' (e.g., "chapter," "section") will be inserted [any unit below sections will be called "section"]. To have the inserted text be capitalised, use `\Sectiontype{Node-name}'. For the common idiom, `\sectiontype{Node-name}~\ref{Node-name}', you may use `\sectionref{Node-name}' (similarly for `\Sectionref'). [I use this all the time. --WDP]  File: literate.info, Node: Node_specifications, Prev: sectiontype-and-ref, Up: Sectioning GNU Info node specifications with `\section<n>' ............................................... [APRIL91: Don't overlook the new ideas in section *Note revised-sectioning::.] When making an on-line Info document from a literate program, the text between two sectioning commands is turned into an Info node. Moreover, the sectioning commands are used to determine how the nodes should be linked together -- almost always in the hierarchical structure implied by the sectioning. However, you can tweak the process as much as you wish (almost no-one ever wishes...). Each `\section<n>' command may have an optional "node specification", with which you may specify the name of the Info node and how it should be linked to other nodes. For common practice, I recommend giving a (unique) node name and enjoying the default links; for example: \section[Foo-Sem]{Foo Semantics} Besides serving as the node name, `Foo-Sem' will also be a LaTeX `\label' and may be `\ref''d or `\pageref''d: for example, you could say, "The semantics are given in section~\ref{Foo_Sem}". (This is more likely to work than introducing a `\label' of your own and `\ref''ing that.) Node names must not contain commas (and other unpleasant characters I don't want to think about) and spaces are probably asking for trouble. The next example shows the *general* form for a node specification, in which you want to specify all of a node's links by hand:(1) \section1[This-Node,Next-Node,Prev-Node,Up-Node]{Bar Semantics} A `?' may be given for any of the four node-names; then the default is used: 1. The default node-name is the section number. 2. The default next-node is the one associated with the next same-level sectioning command (i.e., the next `\section<n>' command if this is a `\section<n>' command. 3. Analogously for the default previous-node... 4. The default up-node is the last-seen next-level-up sectioning command, e.g., if at a `\section<n>', then the last `\section<n-1>' command seen. Any text before the first `\section' command goes in node `Top', which has node specification "`Top,,,(dir)'". The recommended form `\section[Foo-Sem]{Foo Semantics}' is just short for `\section1[Foo-Sem,?,?,?]{Foo Semantics}'. Additional Info nodes that are unrelated to sectioning commands may be added with the `\node' command. [Note: not well tested.] If you want a LaTeX-style sectioning command (e.g., to specify a table-of-contents entry), use `onlyinfo' and `onlylatex' environments. ---------- Footnotes ---------- (1) Ignore the rest of this section unless you enjoy pain -- it presumes some familiarity with Texinfo/Info specifics; see `info info' and/or `info texinfo'.  File: literate.info, Node: code-in-doc, Next: Cross_references, Prev: Sectioning, Up: notation-tut Including program code in your document --------------------------------------- Central to literate programming is having program code in your document that can be directly extracted and compiled/executed. * Menu: * usual-code-in-doc:: The usual ways to put code in a documents. * ribbons-details:: Code ribbons: the fancy stuff. * reordering-with-insertribbon:: Code reordering with `\insertribbon'. * pseudocode:: Stuff that looks like code but isn't. * magic-things-in-code:: Magic things you can put in your code.  File: literate.info, Node: usual-code-in-doc, Next: ribbons-details, Prev: code-in-doc, Up: code-in-doc The usual ways to put code in a documents ......................................... The most straightforward way to do this is to put all the code in a file in one or more `\begin{code}' ... `\end{code}' environments -- the code can then be extracted (in the order it appears in the text) and fed to your favourite compiler/interpreter/whatever. An equivalent notation preferred by some is "Bird tracks", so-called because it started with Richard Bird (and because Cordy calls them that); lines starting with a `>' are extracted; for example: >main _ = [AppendChan stdout "hello, world\n"] is equivalent to: \begin{code} main _ = [AppendChan stdout "hello, world\n"] \end{code} A block of Bird-tracked code lines must have a blank line before and after (not having one usually indicates a typo). COMMENT:---------------------- ToDo: Simon wants to know how code looks in (a) a LaTeX'd document and (b) an Info'd document. ------------------------------  File: literate.info, Node: ribbons-details, Next: reordering-with-insertribbon, Prev: usual-code-in-doc, Up: code-in-doc Code ribbons: the fancy stuff ............................. Both of the above are shorthand notation for messier stuff going on underneath... Strictly speaking, the code in a particular document is made up of one or more *ribbons* of code. For example, A common thing to say to the world is ``Hello, world!'' \begin{code}[hello-goodbye] void HELLO() { printf("HELLO, WORLD!\n"); } \end{code} However, you might want to be less exuberant: \begin{code}[wimp] void hello() { printf("hello, world!\n"); } \end{code} And perhaps you are trying to tune out, not tune in. \begin{code}[hello-goodbye] void goodbye() { printf("Good-bye, cruel world...\n"); } \end{code} As always, code to be extracted goes inside a `\begin{code}'...`\end{code}'; the *optional* argument after `\begin{code}' is the name of the code-ribbon to which the program-text belongs. The example above has two ribbons, `hello-goodbye' and `wimp'. You can extract any code-ribbon(s) you wish [see `lit2pgm''s -r option]; the disjoint pieces of a particular ribbon (e.g., `hello-goodbye' above) are catenated together in the order seen. Usually, this ribbon-business is just a bother, so there is the good ol' default ribbon, `main'. For example, the way-you-normally-write-things: \begin{code} void adieu() { printf("Adieu, cruel world...\n"); } \end{code} is actually short for: \begin{code}[main] void adieu() { printf("Adieu, cruel world...\n"); } \end{code} Unsurprisingly, `main' is the default code-ribbon when one is in the ribbon-extraction business. Similarly, code included with `>' signs in the leftmost column ("Bird tracks") is just tacked onto the `main' ribbon, too: >void >adieu() >{ printf("Adieu, cruel world...\n"); }  File: literate.info, Node: reordering-with-insertribbon, Next: pseudocode, Prev: ribbons-details, Up: code-in-doc Code reordering with `\insertribbon' .................................... If you are feeling particularly notorious, one piece of code may be appended to several ribbons (a comma-separated list of ribbon names, please -- spaces are significant except for beside the commas): \begin{code}[ribbon1, ribbon2, ribbon3] void adieu() { printf("Bon soir, cru\\'el world...\n"); } \end{code} To get the effect of WEB-like parameterless macros, one ribbon may use `\insertribbon' to include a copy of another one, as in: \begin{code} void adieu() \insertribbon{message} \end{code} \begin{code}[message] { printf("Adieu, cruel world...\n"); } \end{code} ToDo: CHANGE `\insertribbon' SO IT'S OUTSIDE OF code ENVIRONMENT. I don't recommend `\insertribbon'. You can make a terrible mess with it. I haven't tested it for months.  File: literate.info, Node: pseudocode, Next: magic-things-in-code, Prev: reordering-with-insertribbon, Up: code-in-doc Stuff that looks like code but isn't .................................... If you want to include alternate versions of code (for illustrative purposes, presumably), to be typeset as code but *not* subject to extraction by `lit2pgm', put the extra versions in `pseudocode' environments.  File: literate.info, Node: magic-things-in-code, Prev: pseudocode, Up: code-in-doc Magic things you can put in your code ..................................... Generally speaking, you enter your program code inside a `code' environment *exactly* as you would otherwise (the principle discussed in section *Note code-verissimilitude::), and it will appear in your documents as shown (nicely typeset, we hope). There are two magic things that you can put in your code that do not appear in your document (directly): Index entries: Code is automagically indexed, but you may wish additional index entries of your own choosing. Hidden comments: You will sometimes want comments in your actual code that you do not want printed. An example: you might want to record next to each code block the names of the the test files used to exercise it. This is *really boring* information to all but the most dedicated reader. In both cases, the information *could* be provided outside the code environment (i.e., without any special construct), but it could quite easily get lost (code blocks can be big, even if they shouldn't be :-). In all cases, these annotations are in a form recognised as a comment by the compiler/whatever for that language. Please see section *Note Language_specific:: for the exact form used for the language you are interested in. A Haskell example of both magic bits might be: \begin{code} main _ = [AppendChan stdout "Hello, world...?\n"] --idx:: world, state of --hide:: use testfile093.hs \end{code} [APRIL91: Yell if you really dislike (or like) these two forms of "magic things in code".]  File: literate.info, Node: Cross_references, Next: Indexing, Prev: code-in-doc, Up: notation-tut Cross-referencing ----------------- For cross-referencing, the normal thing is to use node-names on sectioning commands as labels, and to `\ref{<label>}' and `\pageref{<label>}' them, as is the LaTeX custom. `\pageref's are discouraged, as there is no concept of page numbers in Info files. Similarly, if you heave in a `\label{<some text>}', the Info side of things will assume that `<some text>' is just another label for the current node [NOT IMPLEMENTED (ToDo)]. APRIL91: Cross-referencing is normally used to help you move from a *use* of a code-thing to its *definition*. There should probably be an option to let you get cross-referencing that will also let you move from a definition to all of its uses.  File: literate.info, Node: Indexing, Next: Examples, Prev: Cross_references, Up: notation-tut Indexing -------- [APRIL91: changes are envisaged; see section *Note multiple-indexes::.] Indexing is assumed to work with the program `makeindex', so you should put a a `\printindex' command where you want the index to appear (almost always just before `\end{document}'). (A LaTeX `\makeindex' command is supplied automagically before `\begin{document}'.) Roughly speaking, code portions of your document are *automatically* indexed, and then you index the text portion *manually*, with `\index' commands. `\index{<entry text>}' is the basic indexing command and offers a simplified `makeindex' interface. * If you want just plain simple "foo" to appear in the index, use `\index{foo}'. * If you want subitems in an index entry, separate them with `!'s [useful]. * If you want separate text for sorting and printing an index entry, put the two texts in that order, separated by an unescaped `@'. * To put a `!' or `@' in your index entry, escape it with a backslash `\'. * All other (semi-normal) characters work as is. I don't encourage trying to have index entries pop out in different fonts -- it doesn't work in plain Info files. You can write devious LaTeX/`makeindex' code on your own... Code-stuff in text (stuff inside `@...@') is indexed automatically, just like "real code". What actually happens depends on the support for your programming language -- section *Note Language_specific:: gives all the language-specific indexing idiosyncracies. The *default* bare-bones mechanism is that whitespace-free code-in-text over three characters long (e.g., `@typecheck@') will generate an index entry. To suppress automatic indexing of a piece of code-in-text, put a `\noindex' immediately following, as in `@typecheck@\noindex'. As mentioned in section *Note magic-things-in-code::, you can add index entries for your code by inserting specially-formatted comments (this depends on how well your programming language is supported). For example, for Haskell, you might use [NB: NOT IMPLEMENTED YET (ToDo?)]: f x y z = (y z) x -- the next line is a comment that will cause an index entry -- equivalent to: \index{foo-bar-baz} --#idx::foo-bar-baz For a chunk of code, a mini-index pointing to the definitions of the things it refers to (one possible definition of "things:" top-level functions) will be produced right after the code. (For the Info file, as part of the menu for that node.) COMMENT:---------------------- The Info part is done; I'm still thinking about what should be done for LaTeX. ------------------------------ [APRIL91: this is one of the things contemplated in section *Note multiple-indexes::.] At least some provision has been made for "stop lists" for the automagical indexing (I'm not sure how well it works...). You put words/strings that are normally picked up by the indexing into a file, then tell the system this is your "stop list file" (`-s' option, I think), meaning "Don't index these things -- I'm not interested."  File: literate.info, Node: Examples, Next: Shortcuts, Prev: Indexing, Up: notation-tut Some complete examples [NOT FINISHED] ------------------------------------- NOT FINISHED YET. Some day... Meanwhile, you will find some reasonable not-over-huge examples in the `literate/tests' directory in the source. * Menu: * Simple_example:: A simple example. * Typical_example:: A typical example. * Hairy_example:: A hairy example.  File: literate.info, Node: Simple_example, Next: Typical_example, Prev: Examples, Up: Examples A simple example ................  File: literate.info, Node: Typical_example, Next: Hairy_example, Prev: Simple_example, Up: Examples A typical example .................  File: literate.info, Node: Hairy_example, Prev: Typical_example, Up: Examples A hairy example ...............  File: literate.info, Node: Shortcuts, Prev: Examples, Up: notation-tut Helpful short-cut notations --------------------------- APRIL91: There is discussion about these sorts of things scattered through the "new ideas" in section *Note april91-new-ideas::. * Menu: * code-in-text:: Referring to code things in your text. * fonts-in-text:: Using different "fonts" in your text.  File: literate.info, Node: code-in-text, Next: fonts-in-text, Prev: Shortcuts, Up: Shortcuts Referring to code things in your text ..................................... In the text part of a literate program, one often wishes to refer to things in the code (e.g., function names) or have code expressions in the running text, and so forth. One would like this code-in-text to be typeset just like the real-code-parts (currently verbatim, but that could change). To mark off code-in-text, surround it with `at' signs: as in `@code in text@'; to put an `at' sign in in-line code, you've got to put in two `ats': `@x @@ (y, z)@'. Line-breaks are prevented inside "attified" code-text. Because things inside `at' signs are so often just what you want to be indexed, the rule is: if the at-signed thing contains no whitespace, an index entry is generated. (How to prevent indexing and how to do fancier things about indexing and cross-referencing are given section *Note Indexing::.) APRIL91: see comments in section *Note text-in-code::.  File: literate.info, Node: fonts-in-text, Prev: code-in-text, Up: Shortcuts Using different "fonts" in your text .................................... [APRIL91: Be sure to see section *Note diff-fonts-in-text::.] The `\tr{<text>}' command sets `<text>' in typewriter font, with no need for escape characters or anything -- provided the braces nest properly. The same trick using a "plain" (roman) font is `\pl{<text>}', to produce <text>.  File: literate.info, Node: Command_reference, Next: Language_specific, Prev: notation-tut, Up: Top LaTeX-like markup commands: reference ===================================== This section assumes you are familiar with the tutorial-ish material in section *Note notation-tut::. It also assumes some familiarity with LaTeX, in that I may say say, "It works as in LaTeX". The lists below catalog the environments (`\begin{...}/\end{...}' things) and commands (backslashed `\things') of our Glasgow literate-programming notation. [For this clunky implementation, the `\begin{...}' and `\end{...}' delimiters should be on lines by themselves, beginning in the leftmost column.] Occasional mention is made of the main programs used to process literate files: `lit2pgm', which extracts the code from a file; `lit2latex', which creates real LaTeX source from a file; and `lit2texi', which creates Texinfo source from a file (from which Info files can be made with `makeinfo'). Little things first: * In text, you should use the TeX style of double quotes: ```foo'''. * In text, backslashed magic characters, e.g., `\& \_ \# \$', will produce the self-same de-backslashed magic characters in the output. * Accents on characters (e.g., `\'e') are fine; they are tossed from Info files. * You may safely use the italic correction `\/'. * At least the font-fiddling declarations `\sc' and `\tt' will work; they are heartily unrecommended. APRIL91: see the comments in section *Note diff-fonts-in-text::. Also, make them commands, not declarations? Commands and environments (in alphabetical order): * Menu: * \appendix:: \appendix. * \author:: \author{<text>}. * center_environment:: center environment. * \centerline:: \centerline{<text>}. * \caption:: \caption{<text>}. * \clearpage-etc:: \clearpage and \cleardoublepage. * code_environment:: code environment. * comment_environment:: comment environment. * \date:: \date{<text>}. * \define:: \define{<command>}{<replacement>}. * description_environment:: description environment. * display_environment:: display environment. * \documentstyle:: \documentstyle[<style-options>]{<doc-type>}. * \em:: {\em <text>}. * enumerate_environment:: enumerate environment. * figure_environment:: figure environment. * flushdisplay_environment:: flushdisplay environment. * flushverbatim_environment:: flushverbatim environment. * \footnote:: \footnote{<text>}. * \heading:: \heading{<title>}. * \index:: \index{<entry>}. * \input:: \input{<filename>}. * \inputnow:: \inputnow{<filename>}. * \insertribbon:: \insertribbon{<ribbon-name>}. * itemize_environment:: itemize environment. * \label:: \label. * \listoffigures-etc:: \listoffigures and \listoftables. * \makeindex:: \makeindex. * \maketitle:: \maketitle. * menu_environment:: menu environment. * \menuentry:: \menuentry{<tag>}{<description>}. * \node:: \node{<node-spec>}. * \pounds:: \pounds<something-like-a-number>. * onlyinfo_environment:: onlyinfo environment. * onlylatex_environment:: onlylatex environment. * onlypartofdoc_environment:: onlypartofdoc environment. * onlystandalone_environment:: onlystandalone environment. * \pageref:: \pageref{<label-or-node-name>}. * \pl:: \pl. * \printindex:: \printindex. * pseudocode_environment:: pseudocode environment. * quotation_environment:: quotation environment. * rawlatex_environment:: rawlatex environment. * \ref:: \ref{<label-or-node-name>}. * \rootsectiontype:: \rootsectiontype{<real-sectioning-command>}. * \sectiontype:: \sectiontype{<nodename>}. * \sectionref:: \sectionref{<nodename>}. * \standaloneornot:: \standaloneornot{<ifso>}{<ifnot>}. * \suppresscomments:: \suppresscomments. * table_environment:: table environment. * \tableofcontents:: \tableofcontents. * tabular_environment:: tabular environment. * \title:: \title{<text>}. * \tr:: \tr. * verbatim_environment:: verbatim environment.  File: literate.info, Node: \appendix, Next: \author, Prev: Command_reference, Up: Command_reference \appendix Section numbering after this command is for appendices. (Has no effect on Info files. ToDo: it probably should.)  File: literate.info, Node: \author, Next: center_environment, Prev: \appendix, Up: Command_reference \author{<text>} Please see under `\maketitle'.  File: literate.info, Node: center_environment, Next: \centerline, Prev: \author, Up: Command_reference center environment As for LaTeX. [APRIL91: Not implemented (and not sure how to do it easily on the Texinfo side), but I need to do something because Simon keeps using it.]  File: literate.info, Node: \centerline, Next: \caption, Prev: center_environment, Up: Command_reference \centerline{<text>} As for LaTeX.  File: literate.info, Node: \caption, Next: \clearpage-etc, Prev: \centerline, Up: Command_reference \caption{<text>} As for LaTeX; likely to be unsatisfactory for Info files because the latter doesn't do figures.  File: literate.info, Node: \clearpage-etc, Next: code_environment, Prev: \caption, Up: Command_reference \clearpage and \cleardoublepage As in LaTeX; no effect on Info files.  File: literate.info, Node: code_environment, Next: comment_environment, Prev: \clearpage-etc, Up: Command_reference code environment See section *Note code-in-doc::. Also, don't forget the `pseudocode' environment. You cannot nest other environments inside code environments.  File: literate.info, Node: comment_environment, Next: \date, Prev: code_environment, Up: Command_reference comment environment Text in a `comment' environment will be output (perhaps with extra indentation, smaller font, etc.) if a `\suppresscomments' command hasn't yet been encountered. [NB: `\suppresscomments' doesn't work with `lit2texi'.] A comment environment cannot include another comment environment.  File: literate.info, Node: \date, Next: \define, Prev: comment_environment, Up: Command_reference \date{<text>} As for LaTeX; please see under `\maketitle' for exact details.  File: literate.info, Node: \define, Next: description_environment, Prev: \date, Up: Command_reference \define{<command>}{<replacement>} Ultra-simple macro substitution, NOT LIKE LaTeX. The text for `<command>' will be replaced with `<replacement>'; no nesting, no funny characters, nothing fancy. Don't `\define' the same `<command>' twice, for example. Intended for customising documents; please see the note under `\input'. Defaults are provided for `Haskell', `LaTeX', `TeX' and `...'. More defaults on request. APRIL91: see section *Note pseudo-C-preprocessor:: for what I would REALLY like to do about "defining".  File: literate.info, Node: description_environment, Next: display_environment, Prev: \define, Up: Command_reference description environment As in LaTeX.  File: literate.info, Node: display_environment, Next: \documentstyle, Prev: description_environment, Up: Command_reference display environment Similar to `verbatim' (line-breaks are obeyed) but formatted in the prevailing font (not necessarily typewriter). There is a `flushdisplay' environment as well. You can't nest one display environment inside another.  File: literate.info, Node: \documentstyle, Next: \em, Prev: display_environment, Up: Command_reference \documentstyle[<style-options>]{<doc-type>} You do not have to the `literate' LaTeX style option; e.g., `\documentstyle[literate]{report}', but it is probably a good idea so people don't think you're writing real LaTeX. `\documentstyle' has two magical actions: (1) the type of document (report, article, etc.) determines the default value for `\rootsectiontype', and (2) it indicates that a standalone document is being generated (not just a part of one). [APRIL91: bear in mind that this standalone business is in jeopardy.]  File: literate.info, Node: \em, Next: enumerate_environment, Prev: \documentstyle, Up: Command_reference {\em <text>} The \em (emphasize) declaration works just as in LaTeX. APRIL91: make it a command, not a declaration, i.e., \em{<text>}?  File: literate.info, Node: enumerate_environment, Next: figure_environment, Prev: \em, Up: Command_reference enumerate environment As in LaTeX.  File: literate.info, Node: figure_environment, Next: flushdisplay_environment, Prev: enumerate_environment, Up: Command_reference figure environment Goes straight through for LaTeX; ignored for Info files, meaning that whatever is inside won't "float." (Remember: we don't really do figures; see section *Note texinfo-limits::.)  File: literate.info, Node: flushdisplay_environment, Next: flushverbatim_environment, Prev: figure_environment, Up: Command_reference flushdisplay environment Same as the `display' environment, except it is not indented relative to the left margin. You can't nest one flushdisplay environment inside another.  File: literate.info, Node: flushverbatim_environment, Next: \footnote, Prev: flushdisplay_environment, Up: Command_reference flushverbatim environment Same as the `verbatim' environment except that text is not indented relative to the left margin. You can't nest other environments inside a flushverbatim environment; see the note in section *Note verbatim_environment::.  File: literate.info, Node: \footnote, Next: \heading, Prev: flushverbatim_environment, Up: Command_reference \footnote{<text>} Footnotes work! NB: with `makeinfo', you may choose one of two ways of doing footnotes in an Info file. By default, they will be at the bottom of the node (style BN), as opposed to in a node of their own (style MN). [ToDo: update the makeinfo info]  File: literate.info, Node: \heading, Next: \index, Prev: \footnote, Up: Command_reference \heading{<title>} A pseudo-sectioning command that formats `title' as if it were a section heading (no numbering or any of that rot), but it doesn't put anything in the table of contents, no Info node, no anything weird.  File: literate.info, Node: \index, Next: \input, Prev: \heading, Up: Command_reference \index{<entry>} Roughly as for LaTeX with `makeindex'. Don't try anything too weird: for example, `\index{<mumble>}' inside a footnote doesn't work. Warning: full-blown `makeindex'-style indexing has been "simplified": please see section *Note Indexing:: for the full gory (but wonderful!) details.  File: literate.info, Node: \input, Next: \inputnow, Prev: \index, Up: Command_reference \input{<filename>} Be sure these are on lines by themselves and start in column 1. The argument should be the full filename -- no implied suffix. Files will be searched for along the `LITINPUTS' path, specified by an environment variable of the same name. The default path includes only your current working directory. `\input's are only followed at link time; if that's not what you want, either give the appropriate command-line flag (`-n') or use `\inputnow'. APRIL91: see section *Note pseudo-C-preprocessor:: for some thoughts about how inputting may be changed.  File: literate.info, Node: \inputnow, Next: \insertribbon, Prev: \input, Up: Command_reference \inputnow{<filename>} These are `\input's that are followed always, no matter what. Otherwise, they are the same. APRIL91: `\inputnow' may go away at any second.  File: literate.info, Node: \insertribbon, Next: itemize_environment, Prev: \inputnow, Up: Command_reference \insertribbon{<ribbon-name>} Used to insert the text of one code-ribbon into another; see section *Note code-in-doc::. Must share a line with nothing but whitespace. Not recommended. ToDo: needs to be made to work *outside* of code environments, rather than inside them. DOES NOT WORK WITH `lit2pgm -q'! (which is what we often use.)  File: literate.info, Node: itemize_environment, Next: \label, Prev: \insertribbon, Up: Command_reference itemize environment As in LaTeX. British spelling ("itemise") also accepted.  File: literate.info, Node: \label, Next: \listoffigures-etc, Prev: itemize_environment, Up: Command_reference \label Free-standing `\label's [supposedly] work as expected in LaTeX; in Info files, a `\label' is taken as just another name for the node the `\label' is in. Determining which node it's in doesn't take account of `\input's -- it's the one it "appears" to be in -- which may not be what you want. You *really should* use node-names as labels (see section *Note Node_specifications::)... Labels (and, therefore, nodenames) shouldn't have weird characters in them. Such labels (nodenames) will be studiously ignored.  File: literate.info, Node: \listoffigures-etc, Next: \makeindex, Prev: \label, Up: Command_reference \listoffigures and \listoftables As for LaTeX; has no effect on Info files, which don't do lists of figures or tables.  File: literate.info, Node: \makeindex, Next: \maketitle, Prev: \listoffigures-etc, Up: Command_reference \makeindex Not necessary even for LaTeX -- one is inserted automagically just before `\begin{document}'; has no effect on `lit2texi'.  File: literate.info, Node: \maketitle, Next: menu_environment, Prev: \makeindex, Up: Command_reference \maketitle Will work as in LaTeX for simple cases, using values provided by `\author{<author-stuff>}', `\title{<title-stuff>}', and `\date{<date-stuff>}'. The `\\' line-breaker works. You die if you try anything weird. For better or worse, if you use the `-g' option (to "grab" a subtree of text for printing), then it *does* matter if the `\maketitle' is in the pre-amble (before `\begin{document}') or not. Please see section *Note Programs-and-options:: for the sorry details.  File: literate.info, Node: menu_environment, Next: \menuentry, Prev: \maketitle, Up: Command_reference menu environment In producing an Info file, text in a `menu' environment is copied verbatim to create an Info menu. You must provide something that Texinfo can grok. This whole mess might be used in conjunction with `\suppressmenu' [if `\suppressmenu' were implemented yet]. APRIL91: this should probably be nuked if the rawtexinfo environment comes online.  File: literate.info, Node: \menuentry, Next: \node, Prev: menu_environment, Up: Command_reference \menuentry{<tag>}{<description>} Requests that an extra menu entry be put at the *beginning* of this section's menu.  File: literate.info, Node: \node, Next: \pounds, Prev: \menuentry, Up: Command_reference \node{<node-spec>} (Ignored for LaTeX.) Makes an extra node in the Texinfo file; the `<node-spec>' is copied straight through to the output, so it's your problem to include something sensible. APRIL91: nuked if rawtexinfo environment comes in?  File: literate.info, Node: \pounds, Next: onlyinfo_environment, Prev: \node, Up: Command_reference \pounds<something-like-a-number> The \pounds must be followed by: zero or more whitespace characters, a digit or a question mark, zero or more digits/question-marks/commas/full-stops/the-letters-K-or-M, and a digit/question-mark/the-letter-K-or-M. The Ks or Ms may be in lower-case. The mind boggles.  File: literate.info, Node: onlyinfo_environment, Next: onlylatex_environment, Prev: \pounds, Up: Command_reference onlyinfo environment Only the Texinfo/Info extraction program(s) pay attention to stuff inside. Don't put code in here! APRIL91: this stuff is in jeopardy of disappearing.  File: literate.info, Node: onlylatex_environment, Next: onlypartofdoc_environment, Prev: onlyinfo_environment, Up: Command_reference onlylatex environment Only the LaTeX extraction program(s) pay attention to stuff inside. Don't put code in here! APRIL91: this stuff is in jeopardy of disappearing.  File: literate.info, Node: onlypartofdoc_environment, Next: onlystandalone_environment, Prev: onlylatex_environment, Up: Command_reference onlypartofdoc environment The extraction programs pay attention to stuff inside only if they believe this is just a piece of a document (i.e., "separate compilation" is going on). As always, don't put code in here! See the `\standaloneornot' command for a shortcut. APRIL91: this stuff is in jeopardy of disappearing.  File: literate.info, Node: onlystandalone_environment, Next: \pageref, Prev: onlypartofdoc_environment, Up: Command_reference onlystandalone environment The extraction programs pay attention to stuff inside only if they believe that a standalone document is in the works (i.e., a `\documentstyle' command has been seen or the `-S' flag given). As always, don't put code in here! See the `\standaloneornot' command for a shortcut. APRIL91: this stuff is in jeopardy of disappearing.  File: literate.info, Node: \pageref, Next: \pl, Prev: onlystandalone_environment, Up: Command_reference \pageref{<label-or-node-name>} In making LaTeX documents, works as usual. In making Info files, treated as a `\ref' (there is no concept of "page" in an Info document).  File: literate.info, Node: \pl, Next: \printindex, Prev: \pageref, Up: Command_reference \pl Plain text, set in a roman font; equivalent to `\mbox{\rm #1}', except that the argument can include any old printable ASCII characters, including properly-nested braces (escaping them is irrelevant). If you want to do something weird, do it another way. Note that linebreaks within the `\pl' are prevented. The equivalent typewriter thing is `\tr'. APRIL91: see possible changes in section *Note diff-fonts-in-text::.  File: literate.info, Node: \printindex, Next: pseudocode_environment, Prev: \pl, Up: Command_reference \printindex Should be just before `\end{document}'. In Info mode, generates a node `Index' at the same sectioning depth as your top-level sectioning commands. APRIL91: see possible changes in section *Note multiple-indexes::.  File: literate.info, Node: pseudocode_environment, Next: quotation_environment, Prev: \printindex, Up: Command_reference pseudocode environment Format the same way as in a `code' environment, but the enclosed stuff is not subject to extraction by `lit2pgm'. Other environments do not nest inside a pseudocode environment.  File: literate.info, Node: quotation_environment, Next: rawlatex_environment, Prev: pseudocode_environment, Up: Command_reference quotation environment As in LaTeX.  File: literate.info, Node: rawlatex_environment, Next: \ref, Prev: quotation_environment, Up: Command_reference rawlatex environment If lit2latexing, copies the body of the environment straight through. Otherwise, discard it. One trick you may need: because of the feeble implementation, the system may still try to "follow" an `\input' inside a rawlatex environment (which it shouldn't). The solution is to "hide" the `\input' so it isn't first on a line: \begin{rawlatex} \begin{figure} {}\input{weird-fig.ps} \caption{Weird Figure} \end{figure} \end{rawlatex}  File: literate.info, Node: \ref, Next: \rootsectiontype, Prev: rawlatex_environment, Up: Command_reference \ref{<label-or-node-name>} As for LaTeX.  File: literate.info, Node: \rootsectiontype, Next: \sectiontype, Prev: \ref, Up: Command_reference \rootsectiontype{<real-sectioning-command>} Please see section *Note Sectioning::.  File: literate.info, Node: \sectiontype, Next: \sectionref, Prev: \rootsectiontype, Up: Command_reference \sectiontype{<nodename>} Please see section *Note sectiontype-and-ref::.  File: literate.info, Node: \sectionref, Next: \standaloneornot, Prev: \sectiontype, Up: Command_reference \sectionref{<nodename>} Please see section *Note sectiontype-and-ref::.  File: literate.info, Node: \standaloneornot, Next: \suppresscomments, Prev: \sectionref, Up: Command_reference \standaloneornot{<ifso>}{<ifnot>} If doing standalone-document processing (i.e., a `\documentstyle' seen or `-S' flag given), use text `<ifso>'; otherwise, use text `<ifnot>'. Keep this on one line *by itself*, OK?; for longer things, use the `onlystandalone' and `onlypartofdoc' environments. APRIL91: this stuff is in SEVERE jeopardy of being nuked; see section *Note pseudo-C-preprocessor::.  File: literate.info, Node: \suppresscomments, Next: table_environment, Prev: \standaloneornot, Up: Command_reference \suppresscomments Best put in the preamble of your overall document (i.e., before `\begin{document}'). Causes text in all subsequent `comment' environments to be ignored. NB: only works in producing LaTeX documents. (ToDo: fix this)  File: literate.info, Node: table_environment, Next: \tableofcontents, Prev: \suppresscomments, Up: Command_reference table environment Goes straight through for LaTeX; ignored for Info files, meaning that whatever is inside won't "float."  File: literate.info, Node: \tableofcontents, Next: tabular_environment, Prev: table_environment, Up: Command_reference \tableofcontents As for LaTeX; adds extra stuff to the top-level menu in an Info file.  File: literate.info, Node: tabular_environment, Next: \title, Prev: \tableofcontents, Up: Command_reference tabular environment Same format as LaTeX, but anything magical beyond `&', `\\', and `\hline' will probably get you in trouble. Other environments don't nest inside a tabular environment.  File: literate.info, Node: \title, Next: \tr, Prev: tabular_environment, Up: Command_reference \title{<text>} Please see under `\maketitle'.  File: literate.info, Node: \tr, Next: verbatim_environment, Prev: \title, Up: Command_reference \tr Set in typewriter font; equivalent to `\mbox{\tt #1}', except that the argument can include any old printable ASCII characters, including properly-nested braces (escaping them is irrelevant). If you want to do something weird, do it another way. Note that linebreaks within the `\tr' are prevented. The equivalent non-typewriter thing is `\pl'. APRIL91: see section *Note diff-fonts-in-text:: for further comment on this stuff.  File: literate.info, Node: verbatim_environment, Prev: \tr, Up: Command_reference verbatim environment As in LaTeX -- line-breaks are obeyed and everything is in typewriter font. See also: the `flushverbatim' and `display' environments. You can't nest other environments inside verbatim environments. A trick (hack) you can use to put a verbatim environment inside another is to indent the inner one by one space, as in: \begin{verbatim} ... \begin{verbatim} ... \end{verbatim} ... \end{verbatim}  File: literate.info, Node: Language_specific, Next: Habits, Prev: Command_reference, Up: Top Language-specific processing ============================ This section describes the processing of code in documents that is done in a language-specific way. This is mainly to do with indexing, typesetting, and similar matters. First, however, we give the default rules used when the programming language used is unsupported or unknown. * Menu: * Default_rules:: Rules for unknown or unsupported languages. * Haskell_rules:: Language-specific rules for Haskell. * Perl_rules:: Language-specific rules for `perl'. * C_rules:: Language-specific rules for `C'. * Fortran_rules:: Language-specific rules for `FORTRAN'.  File: literate.info, Node: Default_rules, Next: Haskell_rules, Prev: Language_specific, Up: Language_specific Rules for unknown or unsupported languages ------------------------------------------ [Not finished yet.] No hidden comments or explicit index entries in code.  File: literate.info, Node: Haskell_rules, Next: Perl_rules, Prev: Default_rules, Up: Language_specific Language-specific rules for Haskell ----------------------------------- [This section is not finished yet.] An explicit code index entry comment is of the form: `--idx::<whatever>', on a line of its own. A hidden comment is of the form: `--hide::<whatever>', on a line of its own.  File: literate.info, Node: Perl_rules, Next: C_rules, Prev: Haskell_rules, Up: Language_specific Language-specific rules for `perl' ---------------------------------- [This section is not finished yet.] An explicit code index entry comment is of the form: `#idx::<whatever>', on a line of its own. A hidden comment is of the form: `#hide::<whatever>', on a line of its own.  File: literate.info, Node: C_rules, Next: Fortran_rules, Prev: Perl_rules, Up: Language_specific Language-specific rules for `C' ------------------------------- [This section is not finished yet.]  File: literate.info, Node: Fortran_rules, Prev: C_rules, Up: Language_specific Language-specific rules for `FORTRAN' ------------------------------------- [This section is not finished yet.] The FORTRAN-specific support was provided by Adriaan Joubert (adriaan@dcs.qmw.ac.uk).  File: literate.info, Node: Habits, Next: Caveats, Prev: Language_specific, Up: Top A checklist of good literate habits =================================== [Suggestions welcome. Haven't worked on this in a while.] * Express your ideas in a way amenable to plain ASCII representation, as well as that of full-blown TeX typesetting. For example, serious TeX math-mode stuff is not really on (even if you can get it past `lit2latex'). If you find this constraint a big problem, you may well be using the wrong tool for the job. * If you test your document first as an Info file (i.e., use `lit2texi' to process it), once that is right then it is very likely that the LaTeX side of things (using `lit2latex') will come out right as well. The reverse is not true. * Follow the convention that the sectioning in every file begins with a `\section'. For details on how to do sectioning, please see section *Note How_to_section::. * Arrange your document so that your Info nodes come out no more than two screenfuls' long. Very long nodes obviate the whole point of Info documents. * It's hard to make up good sets of Info node names. First, they must be unique! Second, it's best if the uniqueness is in the first few characters, so that nodename completion may be used to most advantage.  File: literate.info, Node: Caveats, Next: Programs-and-options, Prev: Habits, Up: Top Caveats: bugs and foibles ========================= As mentioned in section *Note clunky-implementation::, the initial implementation of this literate-programming system is delicate at best. 1. Environment-commands should be on lines of their own, and preferably start in column 1; the latter is especially important for verbatim environments. 2. The line numbers reported with errors stand a fair chance of being wrong or even laughably irrelevant. LaTeX doesn't report errors in terms of their original source anyway at all... (urgh) 3. `\Define'-itions (incl. the built-in ones for Haskell, LaTeX, etc.) are expanded inside `\tr' and friends. 4. You can get confused `\items' (in enumerations, etc.) if you have: \item[... stuff here... ] ...................... ] right bracket on the same line -------------------^ The solution (and it's better style anyway) is to put `\items' on lines of their own. This is a vestige of the implementation... 5. Don't put `\index' commands inside footnotes. There are probably some other related restrictions... (ToDo) 6. Tabs in code will be expanded to spaces. This matters only if you have tabs in string constants, or some such (which you shouldn't, because it's hard for the reader of your code to see what you've done; use `\t' or the equivalent). 7. If you use the cross-referencing (`-D', I think), you have the annoying feature of cross-referencing to things very near by, even on the same page. I don't know how to stop this.  File: literate.info, Node: Programs-and-options, Next: Info_etc, Prev: Caveats, Up: Top Programs to process literate documents ====================================== In this incarnation, the programs `lit2pgm', `lit2latex', and `lit2texi' (to extract program, LaTeX, or GNU Texinfo fodder) are just three ways of invoking one killer `perl' script, `lit2stuff'. [Actually, this same script may be invoked as `mkdependlit', to build a set of `make' dependencies for a literate document, as `lit2text', to extract just the non-code text (perhaps for spell-checking), or as `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 section *Note revised-pgm-options::. For all three programs, their invocation takes the form `lit2<whatever> [options] [input-file]'. Usually, output is to a file determined from the input-file's suffix (e.g., a `.hs' file from a `.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 `-i' and `-o' options. Known file suffixes and what they mean: .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 The suffixes `.itex' and `.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 `foo' in file `foo.lc', one would hope that the following simple invocations would suffice: 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) 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. * Menu: * A_option:: -A <pgm-name> option. * c_option:: -c option. * d_option:: -d option. * capital_D_option:: -D option. * f_option:: -f <nodename-suffix> option. * g_option:: -g <node-name> option. * H_option:: -H <dir1>:<dir2> option. * i_option:: -i <input-file> option. * capital_I_option:: -I <directories> option. * capital_L_option:: -L option. * l_option:: -l <language> option. * n_option:: -n option. * capital_N_option:: -N <info-filename> option. * o_option:: -o <output-file> option. * capital_O_option:: -O option. * p_option:: -p <pagebreak-hints> option. * q_option:: -q option. * r_option:: -r <ribbons-to-get> option. * s_option:: -s <stop-list-file> option. * capital_S_option:: -S option. * t_option:: -t <typesetting-hints> option. * v_option:: -v option. * x_option:: -x <xref-hints> option.  File: literate.info, Node: A_option, Next: c_option, Prev: Programs-and-options, Up: Programs-and-options -A <pgm-name> option (For hackers only.) Assume the program was invoked as `<pgm-name>'. must be the first option given. Still has to be either `lit2pgm', `lit2texi', or `lit2latex'.  File: literate.info, Node: c_option, Next: d_option, Prev: A_option, Up: Programs-and-options -c option (Not `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 `-c' option to a C compiler...  File: literate.info, Node: d_option, Next: capital_D_option, Prev: c_option, Up: Programs-and-options -d option Print debugging information. I will be monumentally surprised if this is of any use to you!  File: literate.info, Node: capital_D_option, Next: f_option, Prev: d_option, Up: Programs-and-options -D option (`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 section *Note pseudo-C-preprocessor::.  File: literate.info, Node: f_option, Next: g_option, Prev: capital_D_option, Up: Programs-and-options -f <nodename-suffix> option (`lit2texi' only.) Append the string `<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 section *Note clumsy-node-namespace::.  File: literate.info, Node: g_option, Next: H_option, Prev: f_option, Up: Programs-and-options -g <node-name> option (`lit2latex' only.) Grab the sub-tree of text for which node `<node-name>' is the root. Used when you want to print a whole chapter or section or something, rather than just one Info node. *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 `\section' command -- not quite what you want), the subtree you asked for, and `\end{document}'. Your section will be numbered `1' no matter what.  File: literate.info, Node: H_option, Next: i_option, Prev: g_option, Up: Programs-and-options -H <dir1>:<dir2> option (For hackers only.) Used by villanous people to override the hardwired directories (`<dir1>' for platform-specific files and `<dir2>' for platform-independent `perl' libraries) where the literate-programming system finds its stuff. Also see the `-A' flag.  File: literate.info, Node: i_option, Next: capital_I_option, Prev: H_option, Up: Programs-and-options -i <input-file> option Specify a specific input file. If not specified with `-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 `-i -'.  File: literate.info, Node: capital_I_option, Next: capital_L_option, Prev: i_option, Up: Programs-and-options -I <directories> option Add (colon-separated) `<directories>' to the front of the default path used to follow `\input' commands (just `.' at the moment). Only give one `-I' option; I cannot promise what will happen if you give more than one. Slight magic: the `.' in the path means: first, look in the directory where the file doing the `\input''ing is; if not there, look in the current working directory. (This is usually what you want.)  File: literate.info, Node: capital_L_option, Next: l_option, Prev: capital_I_option, Up: Programs-and-options -L option (`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 `makeinfo' issues warnings about it. APRIL91: newer version of some Info readers achieve the same effect using additional moving-around-the-tree commands.]  File: literate.info, Node: l_option, Next: n_option, Prev: capital_L_option, Up: Programs-and-options -l <language> option (Not `lit2pgm'.) Assume that any code in the input file is written in <language> and process accordingly (automatic indexing, etc.). The <language> is normally intuited from the input-file suffix (e.g., `.lhs' suggests Haskell code). The `-x', `-p', and `-t' options may be used to tweak cross-referencing, page-breaking, and typesetting of code, respectively.  File: literate.info, Node: n_option, Next: capital_N_option, Prev: l_option, Up: Programs-and-options -n option Follow `\input' commands.  File: literate.info, Node: capital_N_option, Next: o_option, Prev: n_option, Up: Programs-and-options -N <info-filename> option (`lit2texi' only.) Arrange for the Info file to be called `<infofilename>'. By default, for input file `foo.xxx', the Info file will be called `foo.info'. For a multi-file document, the Info filename will be derived from the name of the first file encountered.  File: literate.info, Node: o_option, Next: capital_O_option, Prev: capital_N_option, Up: Programs-and-options -o <output-file> option Specify a specific output file. If not specified with `-o', then it's determined by puzzling over the input file's suffix (see the `-i <input-file>' option). When in doubt, it reverts to the standard output. You may also specify standard output as the "output file" with `-o -'. (For hackers only.) If the first character to the `-o' argument is a `|', then the output is piped through the shell command(s) that presumably follow.  File: literate.info, Node: capital_O_option, Next: p_option, Prev: o_option, Up: Programs-and-options -O option (`lit2texi' and `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 section *Note recording-who-to-blame::.]  File: literate.info, Node: p_option, Next: q_option, Prev: capital_O_option, Up: Programs-and-options -p <pagebreak-hints> option (`lit2latex' only.) The (language-specific) code for typesetting the code in the document is passed the <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 (Section *Note Language_specific::). [NOT IMPLEMENTED FOR ANY LANGUAGE]  File: literate.info, Node: q_option, Next: r_option, Prev: p_option, Up: Programs-and-options -q option (`lit2pgm' only.) Take quick shortcut. This will work if you are only using ribbon `main' (i.e., the usual recommended practice). Should be much faster than the plain `lit2pgm'. The `-q' option will be the *default* in the Glorious new Haskell compiler.  File: literate.info, Node: r_option, Next: s_option, Prev: q_option, Up: Programs-and-options -r <ribbons-to-get> option (`lit2pgm' only.) Extract code-ribbons `<ribbons-to-get>' (comma-separated), instead of the default ribbon, `main'. An artifact of the implementation is that `-r ''' gets you `main'; use `-r junkName' to extract nothing.  File: literate.info, Node: s_option, Next: capital_S_option, Prev: r_option, Up: Programs-and-options -s <stop-list-file> option (`lit2texi' and `lit2latex' only.) The file <stop-list-file> provides extra information for the automatic code-indexing about words that should *not* be indexed. One hacker's dross is another's gold. [I'm not sure this is used for any language yet. ToDo: check]  File: literate.info, Node: capital_S_option, Next: t_option, Prev: s_option, Up: Programs-and-options -S option (Not `lit2pgm'.) Process the input as if it is a standalone document. It is so processed if a `\documentstyle' command is seen, `-S' option or not. APRIL91: in jeopardy of going away; see section *Note pseudo-C-preprocessor::.  File: literate.info, Node: t_option, Next: v_option, Prev: capital_S_option, Up: Programs-and-options -t <typesetting-hints> option The (language-specific) routines for typesetting (really: outputting) the code in the document is passed the <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 (Section *Note Language_specific::). Available hints: `-t tgrind': Typeset code blocks by passing them through the `tgrind' program. `-t ruled': Put lines (rules) above and below blocks of code. (The default may vary with other outputting options.) `-t unruled': Do *not* put lines (rules) above and below blocks of code. `-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. `-t nobird': Format all code without Bird-tracks.  File: literate.info, Node: v_option, Next: x_option, Prev: t_option, Up: Programs-and-options -v option Be verbose. This is really a debugging thing, too.  File: literate.info, Node: x_option, Prev: v_option, Up: Programs-and-options -x <xref-hints> option The (language-specific) code for indexing and/or cross-referencing the code in the document is passed the <xref-hints> to further control how things are done. A general one you can use is `-x noindex', to turn off code indexing. These hints, if any, will be mentioned in the documentation of language-specific processing (Section *Note Language_specific::). An example might be using `-l cpp -x extra:make' on the configuration files for `jmake'. These files have both C pre-processor and `make' things worthy of indexing/cross-referencing, and these options would ensure that the code was put through the appropriate routines for both languages.  File: literate.info, Node: Info_etc, Next: april91-proposals, Prev: Programs-and-options, Up: Top Using your processed literate documents ======================================= This section not written yet. It's supposed to be about all the neat ways to use your LaTeX- and Info-ised programs/documents.  File: literate.info, Node: april91-proposals, Next: sept92-thoughts, Prev: Info_etc, Up: Top APRIL91 PROPOSALS ================= * Menu: * april91-new-ideas:: New ideas. * april91-old-ideas:: Old ideas that still haven't gone anywhere.  File: literate.info, Node: april91-new-ideas, Next: april91-old-ideas, Prev: april91-proposals, Up: april91-proposals New ideas --------- These ideas have piled up over the past six months. NONE OF THEM ARE IMPLEMENTED. And some are TINY little things (and some are BIG). JULY91: I have fleshed out the section *Note literate-para-mode:: and section *Note lit2lit:: comments, as these directions piqued the interest of some fellow GRASPers. * Menu: * delatexify-commands:: Make the commands look less like LaTeX. * multiple-indexes:: Multiple indexes. * better-Haskell-indexing:: Better Haskell indexing. * revised-sectioning:: Revisions to the sectioning commands. * BNF-grammars:: A "BNF grammar" environment. * pseudo-C-preprocessor:: Fake "C pre-processing". * invisible-code:: Invisible code. * text-in-code:: Plain text in your code. * diff-fonts-in-text:: Using many "fonts" in text. * code-in-text-formatting:: Formatting code-ish things in text. * interface-with-papers:: Interface with plain LaTeX papers. * literate-para-mode:: A literate Para mode. * lit2lit:: A `lit2lit' program (to help implement a Para system). * xtex-options:: Generating LaTeX documents especially for `xtex'. * free-text-index:: A free-text "index". * magic-Info-nodes:: Other "magic" Info nodes.... * revised-pgm-options:: Revise the way options are fed to `lit2*' programs. * mixing-Bird-code-and-other:: Mixing code in "Bird tracks" with other code. * code-reading-and-printing:: Decouple code reading and printing styles.  File: literate.info, Node: delatexify-commands, Next: multiple-indexes, Prev: april91-new-ideas, Up: april91-new-ideas Make the commands look less like LaTeX ...................................... The biggest practical problem that has arisen among the (few) users of the literate programming stuff is that they think they're writing LaTeX files and are surprised/disappointed when LaTeX fails to grok their files. We have been too successful in making the notation "LaTeX-like!" One way to make the notation less LaTeX-like while maintaining the notation's familiarity is to switch to mixed-case names, used in a consistent manner; for example: CURRENTLY WOULD BECOME ... \documentstyle \documentStyle \printindex \printIndex \begin{flushleft} \begin{flushLeft} Command/environment names that are one word (e.g., `\begin{enumerate}') would be unchanged. Alternatively, we could make the literate-system case-insensitive where command names are concerned and merely make it our *convention* to use mixed-case names.  File: literate.info, Node: multiple-indexes, Next: better-Haskell-indexing, Prev: delatexify-commands, Up: april91-new-ideas Multiple indexes ................ Having one index for a pretty-big program is a dubious proposition; you get a *huge* index. I think you need multiple indexes -- in the case of a compiler, you might then have a separate index for: parser, typechecker, syntactic desugarer, optimiser, etc. Let's assume you index all the pieces of a compiler (as above) as self-contained units. PROBLEM: it is the uses of functions, etc., that *cross* such boundaries that you would MOST like to have your attention drawn to. That problem aside, I think this is the basic solution: \defineindex{<index-tag-string>}: Says that <index-tag-string> is "legal" hereafter. Requiring/encouraging these `\defineindex' will help to catch typos. \index[<index-tag-string>]{<entry>}: The `\index' command has an optional <index-tag-string> with which this <entry> should be tagged. The default tag string is `main' (unless reset with `\setindex...'; below). \printindex[<index-tag-strings>]: Print an index here, made up from all the entries that have one of the <index-tag-strings>. The default tag string is (same caveats...) `main'. \setcurrentindex{<index-tag-string>}: Set the default tag string for `\index' commands in text. I think you could use the mechanism above to come close to Texinfo's idea about multiple indexes.  File: literate.info, Node: better-Haskell-indexing, Next: revised-sectioning, Prev: multiple-indexes, Up: april91-new-ideas Better Haskell indexing ....................... (The idea probably carries over to other languages.) Stick the whole literate-program Haskell source into an "interesting-thing finder" (call it `htags' :-), getting back (source-location, index-entry) pairs. Then the only trick is to tack each index-entry onto the code block nearest to the reported source-location.  File: literate.info, Node: revised-sectioning, Next: BNF-grammars, Prev: better-Haskell-indexing, Up: april91-new-ideas Revisions to the sectioning commands .................................... The main thing that is a pain about the current sectioning (see section *Note Sectioning::) is making up unique node names all the time. I propose the following "system" for the optional arg to `\section<n>'; shown by example: \section{<title>}: (As currently.) A default node name, made from the section number. No `\label' created. \section[]{<title>}: No node name, no node, no `\label'. Not recommended :-) \section[<the-usual>]{<title>}: (As currently.) Arguably, the stuff to let you specific next/prev/up explicitly should be dropped (to partly de-Info-ise the notation). \section["]{<title>}: (The new one.) The node name should be the same as the <title> ("ditto"). No `\label' would be generated. Some massaging would be required to remove nodename-hostile characters from the title (e.g., colons).  File: literate.info, Node: BNF-grammars, Next: pseudo-C-preprocessor, Prev: revised-sectioning, Up: april91-new-ideas A "BNF grammar" environment ........................... This would work like the `verbatim' program used with the Haskell report; you could say: \begin{grammar} exp -> aexp | exp aexp | exp_1 op exp_2 | @-@ aexp | @\@ apat_1 ... apat_n [gd] @->@ exp | @if@ exp_1 @then@ exp_2 @else@ exp_3 | exp @where@ @{@ decls @}@ | @case@ exp @of@ @{@ alts @}@ | exp @::@ [context @=>@] atype \end{grammar} and respectable BNF-looking stuff would appear in your output. Index entries for the definitions of nonterminals would be generated; possibly a `[noindex]' option to suppress that. I'd also like to do something for inference rules, but I'm fairly baffled about what that might be. (They can be mightily complicated, and it's not clear that a plain-ASCII form is possible.)  File: literate.info, Node: pseudo-C-preprocessor, Next: invisible-code, Prev: BNF-grammars, Up: april91-new-ideas Fake "C pre-processing" ....................... Change things so that literate documents are first put through a "fake C pre-processor" (this section assumes you know what a C pre-processor does). Notes: 1. The relevant commands would start with `##' (to avoid confusion w/ the real thing); hence, `##if', `##endif', `##define', `##include', etc. 2. (Very important.) This pseudo-C-preprocessor does NOTHING inside: * Code environments (and the Bird-track equivalent). * Verbatim environments. * `\tr' and `\pl' commands (and any friends they may have). * `rawlatex' environments (next section). 3. All of the current dubious `only<this-or-that>' environments and so on would go away; what you currently write as: \begin{onlystandalone} \documentstyle[11pt,literate]{article} \begin{document} \title{Glasgow Literate Programming\\ User's Guide} \date{April 1991} \maketitle \begin{onlylatex} \tableofcontents \end{onlylatex} \clearpage \end{onlystandalone} would be re-written as: ##if defined(STANDALONE) \documentstyle[11pt,literate]{article} \begin{document} \title{Glasgow Literate Programming\\ User's Guide} \date{April 1991} \maketitle ##if defined(MK_LATEX) \tableofcontents ##endif /* MK_LATEX */ \clearpage ##endif /* STANDALONE */ 4. `##include' would take the place of the current bogosity `\inputnow'. 5. `##define' would take over from the current emasculated `\define' and would emphasise the point that this literate notation is a fixed notation, lacking general macros. 6. Running this or that program would pre-##define certain symbols (e.g., MK_LATEX), but I don't know exactly which just yet. 7. Using ##defines and ##ifdef'ing easily generalises the "standalone/partofdoc" dichotomy (which badly needs generalising).  File: literate.info, Node: invisible-code, Next: text-in-code, Prev: pseudo-C-preprocessor, Up: april91-new-ideas Invisible code .............. I am wondering if we shouldn't have a code environment of the form: \begin{invisiblecode} main (int argc, char **argv) { printf("Hello, Seaworld!\n"); } \end{invisiblecode} for code that *should* be extracted (`lit2pgm') but that *should not* be displayed in `lit2latex/lit2texi' documents. This would probably be used when you want to include most, but not all, of a program's code -- in a paper for publication, for example. My only fear is that it is too easily subject to abuse. Perhaps the C-pre-processing stuff is a better idea... (section *Note pseudo-C-preprocessor::).  File: literate.info, Node: text-in-code, Next: diff-fonts-in-text, Prev: invisible-code, Up: april91-new-ideas Plain text in your code ....................... In Knuth's WEB, you can refer to code-things in the text parts of the document/program *and* to text-things in your code. (As I recall, putting `|' around text switches it to whatever-you're-not-doing-now (code or text)). We have the first (the `@...@' shorthand to refer to code things while in text), but not the second: what's in a code environment is code just like you would see in an illiterate program in the same language. I guess the right solution is to have specially-marked comments (again, language-dependent) that say, "Don't treat this as just a comment in this programming language, but extract it and mangle/massage it as if it were literate-document text." A pain to implement. Not worth it?  File: literate.info, Node: diff-fonts-in-text, Next: code-in-text-formatting, Prev: text-in-code, Up: april91-new-ideas Using many "fonts" in text .......................... I find the `\tr' ("typewriter font") and `\pl' ("plain font") commands quite useful. (Yes, I know they go against the intensional markup principle (section *Note ASCII-declarative-markup::), but they are *so* convenient...) I'm inclined to make up notations for italics, small caps, and bold (and their ASCII-only "equivalents") and then try to systematize their use. Hmmm.... I've found the Texinfo attempt to have a command for every different kind of thing you might want to talk about in a document to be too much and also unsatisfying.  File: literate.info, Node: code-in-text-formatting, Next: interface-with-papers, Prev: diff-fonts-in-text, Up: april91-new-ideas Formatting code-ish things in text .................................. Right now, the `@...@' shortcut notation means: Format this and automagically index it as for the code parts of the document. Strictly speaking then, I think the `@...@' notation should only be used to refer to things that *actually exist* in the code parts of the document, and *not* for code snippets, fragments, and other things mentioned along the way. For this latter task, perhaps a `\code[<language>]{<text>}' command is in order. This says: format this <text> as for <language>, but don't index it or pretend that it actually has anything to do with the real code in the program.  File: literate.info, Node: interface-with-papers, Next: literate-para-mode, Prev: code-in-text-formatting, Up: april91-new-ideas Interface with plain LaTeX papers ................................. At least in our setting, it is likely we've written one or more papers about some interesting part of the literate program we're writing. The paper is likely to be: * relatively polished (so you'd like to re-use that effort); * either a decent introduction to some part of the program, or a succinct synopsis of some part; * in straight LaTeX, but using features quite beyond our literate markup, and including figures, etc.; * not to be changed in any way. At the least, I'd like to be able to include the paper in toto, and have pointers into it (refs to its labels). More/better ideas welcome.  File: literate.info, Node: literate-para-mode, Next: lit2lit, Prev: interface-with-papers, Up: april91-new-ideas A literate Para mode .................... [See also section *Note lit2lit::.] The sad fact is that, at the moment, these literate programs/documents are typed in as just plain files and manipulated as such. They are only processed into LaTeX/Info documents after the fact (and only occasionally). Para mode is a GNU emacs mode that (roughly...) lets you both edit Texinfo files *and* jump around in them like Info files, based on the node structure. Either edit-as-normal or navigate-as-Info. I think there are possibilities for doing the same thing with these literate documents/programs. Then you'd get the benefits of navigation, following indexery, etc., *as you create the files*. One major problem (?): the literate sectioning makes it quite easy to navigate *within* a file, but, for it to be worth it, you'd like the "literate Para mode" (in navigation mode) to be able to carry you to the right place when you, e.g., want to go "up" from the first `\section' in a file. Implementation: my first cut would be: run something over all the literate files in a program to collect "Para-useful" information; save this somewhere -- this is the moral equivalent of a TAGS file. Then the navigation commands, etc., would use the pseudo-TAGS info to do their thing. Because the info would get out of date as you hack on your program, you'd re-make the pseudo-TAGS stuff whenever you stepped out for coffee, lunch, or sleep.  File: literate.info, Node: lit2lit, Next: xtex-options, Prev: literate-para-mode, Up: april91-new-ideas A `lit2lit' program (to help implement a Para system) ..................................................... [This might be a better way to implement a literate Para ...] Have a program that takes a set of `.lit' files, munges them to do all the usual cross-referencing, etc., etc., and then writes out *versions of the original files* with all the linking info, etc., etc., inserted as *comments*. Call the program `lit2lit'... If you took the `lit2lit' output and re-ran it through one of the other programs, e.g., `lit2latex', it would produce *exactly* the same output. The purpose of the information stored in comments would be to provide an Emacs mode (or something) enough information to help you jump around in a large program or generally do useful stuff. For example, it might insert links and things for something like Bob Weiner's Hyperbole system. I'm thinking that `lit2lit' would be re-run over a system's sources every night by `cron(1)'.  File: literate.info, Node: xtex-options, Next: free-text-index, Prev: lit2lit, Up: april91-new-ideas Generating LaTeX documents especially for `xtex' ................................................ `Xtex' is a (free) DVI previewer with some hypertext-ish features; in particular, if you click on a reference to a label, then it takes you to the page where that label is defined. By generating a "LaTeX" document with all the linking info explicit (in the form of labels and references to them), `xtex' would do almost all the jumping-around stuff that `info' and `xinfo' do for you. *And you don't lose the font information.*  File: literate.info, Node: free-text-index, Next: magic-Info-nodes, Prev: xtex-options, Up: april91-new-ideas A free-text "index" ................... OK, even with all the automagical indexing, cross-referencing, etc., occasions will arise when you say, "Help! I need to look absolutely everywhere for <foo>!" (Like you do with grep/tags, but preferably nicer -- all the tricks of the free-text indexing trade.) It would be great to have a "free text index" button or pseudo-node (an Info "node" that, when you jump to it, puts you in a free-text-search mode. Of course, the free-text-search should be able to plunk you down in the Info node you finally select). I really don't want to implement this myself :-)  File: literate.info, Node: magic-Info-nodes, Next: revised-pgm-options, Prev: free-text-index, Up: april91-new-ideas Other "magic" Info nodes... ........................... The "free text index" magic Info node makes me wish for *other* nodes-that-do-weird-things when you jump to them... You jump to it and... it starts up a PostScript previewer and shows me a picture... or sound... or my text editor so I can send a gripe to the maintainer of foo... and so on.  File: literate.info, Node: revised-pgm-options, Next: mixing-Bird-code-and-other, Prev: magic-Info-nodes, Up: april91-new-ideas Revise the way options are fed to `lit2*' programs .................................................. Using getopt(3)-style one-letter options is getting messy -- there are too many of them. Perhaps time for something more complicated...  File: literate.info, Node: mixing-Bird-code-and-other, Next: code-reading-and-printing, Prev: revised-pgm-options, Up: april91-new-ideas Mixing code in "Bird tracks" with other code ............................................ When you put something in a code environment, e.g., \begin{code} main _ = [ AppendChan stdout "Hi, Mom!\n" ] \end{code} there is no doubt about what should be considered the "first column". On the other hand, if you see a "Bird track" equivalent: > main _ = [ AppendChan stdout "Hi, Mom!\n" ] obviously the initial `>' should be stripped, but what about the space following? This matters if the code is to be put through, e.g., a C pre-processor, which looks for #'s in column 1. The solution I lean to is to have an option that says how much whitespace should be stripped off the front of Bird-track style code lines.  File: literate.info, Node: code-reading-and-printing, Prev: mixing-Bird-code-and-other, Up: april91-new-ideas Decouple code reading and printing styles ......................................... Code may come in either in code environments or in Bird-tracks. At present, it is printed in the same style as it came. This should remain the default. However, it would be nice to be able to say (with options), "OK, print *all* the code as if it were in Bird-track form" (or vice versa). This allows uniform presentation, while preserving programmers' preference for typing in one style rather than the other.  File: literate.info, Node: april91-old-ideas, Prev: april91-new-ideas, Up: april91-proposals Old ideas that still haven't gone anywhere ------------------------------------------ These are ideas that have been around for a long time, HAVE NOT BEEN IMPLEMENTED, and no-one seems to have minded much. * Menu: * recording-who-to-blame:: \owner{<name>}. * test-burying:: Burying test cases in your document. * recording-changes:: Recording changes to your documents.  File: literate.info, Node: recording-who-to-blame, Next: test-burying, Prev: april91-old-ideas, Up: april91-old-ideas \owner{<name>} .............. (Not `lit2pgm'.) Give the "name" that should be listed as the "owner" of a section. If no `\owner' command has been seen, then the owner of the source file in which the first piece of text in the section was found is used. [I haven't really decided how this should work.]  File: literate.info, Node: test-burying, Next: recording-changes, Prev: recording-who-to-blame, Up: april91-old-ideas Burying test cases in your document ................................... The idea is that you can say: \begin{test}{foo} <Weird stuff in here> \end{test} For this test `foo', the `<weird stuff in here>' would somehow say how to run the test, what should be fed to standard input (etc.), and what results to expect on standard output, standard error, and perhaps certain output files. The idea is to put the (simple?) test cases right next to the code that will be exercised. The problem is: tests can do pretty arbitrary things, and I don't see any neat way to encode that fact. Simply bunging full-blown shell scripts into the middle of your literate program hardly seems the solution. Hmmm..... If we had them: test environments don't nest. See ????? (ToDo) for a note on using hidden comments to highlight test information.  File: literate.info, Node: recording-changes, Prev: test-burying, Up: april91-old-ideas Recording changes to your documents ................................... Vaguely like the test case stuff, you might say: \begin{change} <who> & <when> & <tag> & <description of first change> \\ <who> & <when> & <tag> & <description of second change> \\ ... and so on ... \end{change} This is intended to be like the ChangeLog stuff supported in Emacs (`C-x 4 a'). It really only makes sense to use it after software is no longer undergoing cataclysmic change (after it is released perhaps?). Anyway, the idea is to record your change notes right next to where you make them. [The program(s) to extract these notes and to collate them in the manner of your choice are not written yet.] These change environments don't nest.  File: literate.info, Node: sept92-thoughts, Next: lit-install, Prev: april91-proposals, Up: Top SEPT92 THOUGHTS =============== These are further ruminations, having had another year to watch how people do and do not use this system. Death to `ribbons' and code re-ordering: No-one uses it, and it's pretty clunky in this system, both conceptually and implementationally. Suppressable `detail': Be able to mark sections as `detail', as well as to be able to put `\begin{detail}/\end{detail}' around arbitrary stuff. Obviously, you then want to format with/without the details in. A minimally-extensible notation? Texinfo now supports setting and testing of variables, and the using the values thereof. Support "all non-code is raw XXX": Something like: given a flag `-r latex', then all non-code would be taken to be pure LaTeX and wouldn't be mangled *at all*. Another likely possibility: a `-r verbatim', to support the dubious `verbatim' script that's popular in some circles. Stop automagic indexing of code-in-text: I'm not sure it's useful. Throw out tree-grabbing (`-g <node>' option): Too hacky, not used, probably inadequate.  File: literate.info, Node: lit-install, Next: Index, Prev: sept92-thoughts, Up: Top Standalone installation of Glasgow literate programming ======================================================= NOT DONE PROPERLY YET. Here are some short notes; they should work on a Sun4: 1. If you don't have `perl', go get it. 2. If you don't have `makeindex' (normally with the TeX distribution) and/or `tgrind', go get them, if you wish. You can easily get by without them, especially `tgrind'. 3. Customise for your local configuration, by creating a suitable `mkworld/site.jm' file. We supply a `site.dist' file that you can copy and work from. Setting `PerlCmd' correctly is *vital*. All the Haskell-compiler stuff isn't important for the literate-programming system. Setting `TgrindHelperCmd' is important if you're going to try the tgrind-ing stuff. Setting the things for installation (near the end) is *vital*. You will almost certainly need to set `InstRootDir', and perhaps some others. If you don't set anything, the literate-programming system will be installed (on a Sun4) in... /usr/local/bin/sun4 things for the user to invoke (lit2mumble) /usr/local/lib/literate/sun4 machine-specific support stuff /usr/local/lib/literate machine-independent support stuff 4. OK, you should be ready to go! From the top of the distribution... % cd lit2xxx-X.YY % ./STARTUP-literate >& startup.log Everything should proceed to an obviously-successful conclusion (check the log to see...). 5. Test the system enough to see that it's not totally broken. Invoke `lit2pgm', `lit2latex', or `lit2texi' directly from the `literate/' directory, on some small test file of your choice, even something as simple as...: \section[test]{Test section} This is a small test. Then try, perhaps: % literate/lit2latex -v -c test.lit 6. If things seem basically happy, you can safely install the system. % cd literate % make -n install # trial run, just to see if it looks "right" % make install # for real! 7. To make the documentation (some pre-built stuff is in the distrib): % cd literate % make literate.dvi # or ... % make literate.info # or ... % make docs # to do both In the unlikely event you wanted to install it, continue with: % make install-docs 8. You can now either delete the source or just clean up: % make clean 9. Save a copy of your configuration file `mkworld/site.jm' for next time. If you have problems, please report them to me, partain@dcs.glasgow.ac.uk.  File: literate.info, Node: Index, Prev: lit-install, Up: Top Index ===== * Menu: * -D option: capital_D_option. * -A <pgm-name> option: A_option. * \appendix: \appendix. * \author: \author. * -c option: c_option. * \caption: \caption. * center environment: center_environment. * \centerline: \centerline. * \cleardoublepage: \clearpage-etc. * \clearpage: \clearpage-etc. * code (vs text): code-verissimilitude. * code (vs text)_2: notation-tut. * code environment: code_environment. * code index entries, extra: magic-things-in-code. * code ribbons: ribbons-details. * command: Command_reference. * comment environment: comment_environment. * comments, hidden: magic-things-in-code. * -d option: d_option. * \date: \date. * \define: \define. * description environment: description_environment. * display environment: display_environment. * \documentstyle: \documentstyle. * \em: \em. * enumerate environment: enumerate_environment. * environment: Command_reference. * -f <nodename-suffix> option: f_option. * figure environment: figure_environment. * flushdisplay environment: flushdisplay_environment. * flushverbatim environment: flushverbatim_environment. * \footnote: \footnote. * -g <node-name> option: g_option. * -H <dir1>:<dir2> option: H_option. * \heading: \heading. * hidden comments: magic-things-in-code. * -I <directories> option: capital_I_option. * -i <input-file> option: i_option. * index entries, extra ones in code: magic-things-in-code. * \index: \index. * \input: \input. * \inputnow: \inputnow. * \insertribbon: \insertribbon. * itemize environment: itemize_environment. * -L option: capital_L_option. * -l <language> option: l_option. * \label: \label. * LaTeX-like markup language: notation-tut. * \listoffigures: \listoffigures-etc. * \listoftables: \listoffigures-etc. * lit2text: Programs-and-options. * makeindex: Indexing. * \makeindex: Indexing. * \makeindex_2: \makeindex. * \maketitle: \maketitle. * menu environment: menu_environment. * \menuentry: \menuentry. * mkdependlit: Programs-and-options. * -N <info-filename> option: capital_N_option. * -n option: n_option. * node specification: Node_specifications. * \node: \node. * \noindex: Indexing. * -O option: capital_O_option. * -o <output-file> option: o_option. * onlyinfo environment: onlyinfo_environment. * onlylatex environment: onlylatex_environment. * onlypartofdoc environment: onlypartofdoc_environment. * onlystandalone environment: onlystandalone_environment. * \owner: recording-who-to-blame. * -p <pagebreak-hints> option: p_option. * \pageref: \pageref. * \pl: \pl. * \pounds: \pounds. * \printindex: Indexing. * \printindex_2: \printindex. * pseudocode environment: pseudocode_environment. * -q option: q_option. * quotation environment: quotation_environment. * -r <ribbons-to-get> option: r_option. * rawlatex environment: rawlatex_environment. * \ref: \ref. * ribbons, code: ribbons-details. * \rootsectiontype: How_to_section. * \rootsectiontype_2: \rootsectiontype. * -S option: capital_S_option. * -s <stop-list-file> option: s_option. * sectioning: Sectioning. * \Sectionref: sectiontype-and-ref. * \sectionref: \sectionref. * \sectionref_2: sectiontype-and-ref. * \sectiontype: \sectiontype. * \sectiontype_2: sectiontype-and-ref. * \standaloneornot: \standaloneornot. * \suppresscomments: \suppresscomments. * -t <typesetting-hints> option: t_option. * table environment: table_environment. * \tableofcontents: \tableofcontents. * tabular environment: tabular_environment. * text (vs code): code-verissimilitude. * text (vs code)_2: notation-tut. * \title: \title. * \tr: \tr. * -v option: v_option. * verbatim environment: verbatim_environment. * -x <xref-hints> option: x_option.  Tag Table: Node: Top96 Node: Highlights3235 Node: Glasgow-objectives4426 Node: on-line-form5734 Node: medium-scale7013 Node: language-independence7502 Node: code-verissimilitude8172 Node: ASCII-declarative-markup9013 Node: hierarchical-structure10364 Node: separate-compilation10933 Node: one-file-many-purposes12171 Node: Glasgow-NON-objectives13594 Node: not-reinvent-LaTeX13939 Node: reordering-unemphasis14489 Node: Other-Glasgow-features15348 Node: sectioning-large-documents15959 Node: automatic-indexing17191 Node: manual-indexing17991 Node: automatic-cross-referencing18401 Node: shortcut-notations19278 Node: TeX-to-ASCII20306 Node: Glasgow-NON-features20788 Node: texinfo-limits21148 Node: clumsy-node-namespace21925 Node: clunky-implementation22467 Node: notation-tut23069 Node: micro-latex27347 Node: Sectioning28813 Node: section<n>29328 Node: How_to_section31469 Node: sectiontype-and-ref33368 Node: Node_specifications34176 Node: code-in-doc36990 Node: usual-code-in-doc37673 Node: ribbons-details38777 Node: reordering-with-insertribbon40734 Node: pseudocode41737 Node: magic-things-in-code42151 Node: Cross_references43836 Node: Indexing44658 Node: Examples47802 Node: Simple_example48246 Node: Typical_example48383 Node: Hairy_example48527 Node: Shortcuts48644 Node: code-in-text49033 Node: fonts-in-text50082 Node: Command_reference50530 Node: \appendix55179 Node: \author55413 Node: center_environment55571 Node: \centerline55858 Node: \caption56006 Node: \clearpage-etc56229 Node: code_environment56414 Node: comment_environment56702 Node: \date57125 Node: \define57310 Node: description_environment57944 Node: display_environment58107 Node: \documentstyle58478 Node: \em59121 Node: enumerate_environment59372 Node: figure_environment59526 Node: flushdisplay_environment59866 Node: flushverbatim_environment60186 Node: \footnote60569 Node: \heading60958 Node: \index61279 Node: \input61677 Node: \inputnow62348 Node: \insertribbon62616 Node: itemize_environment63072 Node: \label63265 Node: \listoffigures-etc63905 Node: \makeindex64135 Node: \maketitle64384 Node: menu_environment64981 Node: \menuentry65456 Node: \node65681 Node: \pounds66025 Node: onlyinfo_environment66437 Node: onlylatex_environment66736 Node: onlypartofdoc_environment67047 Node: onlystandalone_environment67517 Node: \pageref68012 Node: \pl68296 Node: \printindex68822 Node: pseudocode_environment69162 Node: quotation_environment69495 Node: rawlatex_environment69670 Node: \ref70275 Node: \rootsectiontype70433 Node: \sectiontype70625 Node: \sectionref70814 Node: \standaloneornot71002 Node: \suppresscomments71520 Node: table_environment71882 Node: \tableofcontents72131 Node: tabular_environment72347 Node: \title72654 Node: \tr72805 Node: verbatim_environment73347 Node: Language_specific73903 Node: Default_rules74638 Node: Haskell_rules74918 Node: Perl_rules75313 Node: C_rules75698 Node: Fortran_rules75904 Node: Habits76190 Node: Caveats77578 Node: Programs-and-options79262 Node: A_option82659 Node: c_option82960 Node: d_option83257 Node: capital_D_option83472 Node: f_option83810 Node: g_option84290 Node: H_option84930 Node: i_option85315 Node: capital_I_option85668 Node: capital_L_option86231 Node: l_option86947 Node: n_option87442 Node: capital_N_option87590 Node: o_option87991 Node: capital_O_option88570 Node: p_option88934 Node: q_option89524 Node: r_option89894 Node: s_option90246 Node: capital_S_option90648 Node: t_option90998 Node: v_option91990 Node: x_option92156 Node: Info_etc92917 Node: april91-proposals93232 Node: april91-new-ideas93480 Node: delatexify-commands95184 Node: multiple-indexes96273 Node: better-Haskell-indexing97769 Node: revised-sectioning98270 Node: BNF-grammars99339 Node: pseudo-C-preprocessor100331 Node: invisible-code102536 Node: text-in-code103304 Node: diff-fonts-in-text104187 Node: code-in-text-formatting104915 Node: interface-with-papers105714 Node: literate-para-mode106544 Node: lit2lit108098 Node: xtex-options109171 Node: free-text-index109809 Node: magic-Info-nodes110535 Node: revised-pgm-options111011 Node: mixing-Bird-code-and-other111387 Node: code-reading-and-printing112265 Node: april91-old-ideas112882 Node: recording-who-to-blame113373 Node: test-burying113804 Node: recording-changes114778 Node: sept92-thoughts115626 Node: lit-install116843 Node: Index119654  End Tag Table