@Section @Title { Verbatim and piped text } @Tag { verbatim } @Begin @PP The @Code "@Verbatim" symbol @FootNote { Prior to Version 3.13 the @Code "@Verbatim" symbol was restricted to Unix systems only. This restriction no longer applies to @Code "@Verbatim" and {@Code "@RawVerbatim"}, but it does apply to {@Code "@Pipe"}, {@Code "@PipeVerbatim"}, and {@Code "@PipeRawVerbatim"}. } prints the following object exactly as verbatim.sym @Index @Code "@Verbatim" it appears in the input file. All special meanings for characters, symbols, etc. are turned off; there is one result line for each input line. For example, @ID @Code @Verbatim { @IndentedDisplay @Verbatim { A line of "verbatim" text Another line, with a \ character } } has result @IndentedDisplay @Verbatim { A line of "verbatim" text Another line, with a \ character } Use @Code "@F @Verbatim { ... }" to get the result in a fixed-width font. @PP If the verbatim text contains @Code "{" or @Code "}" characters, then they should either be balanced or else you need to use the alternative form @ID @Code { "@Verbatim @Begin" "..." "@End @Verbatim" } so that there is no doubt about where the verbatim text ends. Although we have said that there are no special meanings, there is one exception to this rule: @Code "@Include" and @Code "@SysInclude" commands are recognized, allowing all or part of the verbatim text to come from some other file. Braces do not have to be balanced in that file. @PP Occasionally the first line of some verbatim text begins with some spaces that have to be preserved. This is a problem for @Code "@Verbatim" because it ignores all white spaces following the opening brace and all white spaces preceding the closing brace. However, the alternative @Code "@RawVerbatim" symbol stops ignoring white spaces at the opening raw.verbatim.sym @Index @Code "@RawVerbatim" as soon as a newline character is reached; in other words, it will preserve all white spaces following the first newline. @PP The @Code "@Pipe" symbol (available on Unix-style systems only) may be pipe.sym @Index @Code "@Pipe" used to pipe some text through a Unix command. For example, @ID @Code lines @Break @Verbatim { @ID lines @Break "sort" @Pipe { Gaskell, Elizabeth Lawrence, D. H. Austen, Jane Dickens, Charles } } will cause the object between braces following @Code "@Pipe" to be piped without interpretation through the Unix @Code "sort" command; its output is the result of the @Code "@Pipe" command, here made into a display preserving the line breaks in the output. The final result will be the four authors, one per line, in alphabetical order. We can't show this result to you because that would make this manual not compilable on non-Unix systems. @PP The double quotes around @Code sort are not necessary in this example, but may be in more complex ones. For example, one can see just the first few lines of the sorted result using @ID @Code @Verbatim { "sort | head" @Pipe ... } and here the quotes are necessary because @Code "|" is one of the special characters that need quoting, according to Section {@NumberOf characters}. The quotes also serve to group the command into a single Lout object. @PP Some Unix commands don't need any input, and then the object following @Code "@Pipe" may be empty. For example, @ID @Code @Verbatim { "ls" @Pipe {} } will list the files of the current directory. @PP Any Lout symbols in the result of the @Code "@Pipe" symbol, such as {@Code "@PP"}, {@Code "@Box"}, and so on, will be interpreted in the usual way. This is convenient because it allows you to write your own Unix commands that include Lout symbols in their output. However, sometimes it is preferable if the output is treated verbatim. For example, @ID @Code @Verbatim { "pwd" @Pipe {} } attempts to print the current working directory, but this will not come out well because the output contains {@Code "/"} symbols, which Lout will then attempt to interpret as Lout symbols. To avoid this problem, use @Code "@PipeVerbatim" instead of {@Code "@Pipe"}: pipeverbatim.sym @Index @Code "@PipeVerbatim" piperawverbatim.sym @Index @Code "@PipeRawVerbatim" @ID @Code @Verbatim { "pwd" @PipeVerbatim {} } This causes the output of the command to be enclosed in @Code "@Verbatim @Begin" and {@Code "@End @Verbatim"}. There is also a @Code "@PipeRawVerbatim" symbol which encloses the output in @Code "@RawVerbatim" rather than the ordinary {@Code "@Verbatim"}. @End @Section