@setfilename info-file-name @settitle name-of-manual This produces: \input texinfo In some documentation styles, metasyntactic variables are shown with angle brackets, for example: ..., type rm <filename> However, that is not the style that Texinfo uses. (You can, of course, modify the sources to TeX and the Info formatting commands to output the ‘<...>’ format if you wish.) File: texi.info, Node: file, Next: dfn, Prev: var, Up: Indicating ‘@file’{FILE-NAME —————— Use the ‘@file’ command to indicate text that is the name of a file, buffer, or directory, or is the name of a node in Info. You can also use the command for file name suffixes. Do not use ‘@file’ for symbols in a programming language; use ‘@code’. Currently, ‘@file’ is equivalent to ‘@samp’ in its effects. For example, The ‘.el’ files are in the ‘/gnu/emacs/lisp’ directory. produces The ‘.el’ files are in the ‘/gnu/emacs/lisp’ directory. File: texi.info, Node: dfn, Next: cite, Prev: file, Up: Indicating ‘@dfn’{TERM ———— Use the ‘@dfn’ command to identify the introductory or defining use of a technical term. Use the command only in passages whose purpose is to introduce a term which will be used again or which the reader ought to know. Mere passing mention of a term for the first time does not deserve ‘@dfn’. The command generates italics in the printed manual, and double quotation marks in the Info file. For example: Getting rid of a file is called deleting it. produces Getting rid of a file is called "deleting" it. As a general rule, a sentence containing the defining occurrence of a term should be a definition of the term. The sentence does not need to say explicitly that it is a definition, but it should contain the information of a definition–it should make the meaning clear. File: texi.info, Node: cite, Prev: dfn, Up: Indicating ‘@cite’{REFERENCE —————— Use the ‘@cite’ command for the name of a book that lacks a companion Info file. The command produces italics in the printed manual, and quotation marks in the Info file. (If a book is written in Texinfo, it is better to use a cross reference command since a reader can easily follow such a reference in Info. *Note ‘@xref’: xref.) File: texi.info, Node: Emphasis, Prev: Indicating, Up: Marking Text Emphasizing Text ================ Usually, Texinfo changes the font to mark words in the text according to what category the words belong to; an example is the ‘@code’ command. Most often, this is the best way to mark words. However, sometimes you will want to emphasize text without indicating a category. Texinfo has two commands to do this. Also, Texinfo has several commands that specify the font in which TeX will typeset text. These commands have no affect on Info and only one of them, the ‘@r’ command, has any regular use. * Menu: * emph & strong:: How to emphasize text in Texinfo. * Smallcaps:: How to use the small caps font. * Fonts:: Various font commands for printed output. File: texi.info, Node: emph & strong, Next: Smallcaps, Up: Emphasis ‘@emph’{TEXT and ‘@strong’{TEXT ——————————— The ‘@emph’ and ‘@strong’ commands are for emphasis; ‘@strong’ is stronger. In printed output, ‘@emph’ produces *italics* and ‘@strong’ produces *bold*. For example,
Caution:
rm * .[^.]*
removes all files in the directory.
produces: *Caution*: ‘rm * .[^.]*’ removes *all* files in the directory. The ‘@strong’ command is seldom used except to mark what is, in effect, a typographical element, such as the word ‘Caution’ in the preceding example. In the Info file, both ‘@emph’ and ‘@strong’ put asterisks around the text. *Caution:* Do not use ‘@emph’ or ‘@strong’ with the word ‘Note’; Info will mistake the combination for a cross reference. Use a phrase such as *Please note* or *Caution* instead. File: texi.info, Node: Smallcaps, Next: Fonts, Prev: emph & strong, Up: Emphasis ‘@sc’{TEXT: The Small Caps Font ——————————– Use the ‘@sc’ command to set text in the printed output in a small caps font and set text in the Info file in upper case letters. Write the text between braces in lower case, like this: The ACM and IEEE are technical societies. This produces: The ACM and IEEE are technical societies. TeX typesets the small caps font in a manner that prevents the letters from ‘jumping out at you on the page’. This makes small caps text easier to read than text in all upper case. The Info formatting commands set all small caps text in upper case. If the text between the braces of an ‘@sc’ command is upper case, TeX typesets in full-size capitals. Use full-size capitals sparingly. You may also use the small caps font for a jargon word such as ATO (a NASA word meaning ‘abort to orbit’). There are subtleties to using the small caps font with a jargon word such as CDR, a word used in Lisp programming. In this case, you should use the small caps font when the word refers to the second and subsequent elements of a list (the CDR of the list), but you should use ‘@code’ when the word refers to the Lisp function of the same spelling. File: texi.info, Node: Fonts, Prev: Smallcaps, Up: Emphasis Fonts for Printing, Not Info —————————- Texinfo provides four font commands that specify font changes in the printed manual but have no effect in the Info file. ‘@i’ requests italic font (in some versions of TeX, a slanted font is used), ‘@b’ requests bold face, ‘@t’ requests the fixed-width, typewriter-style font used by ‘@code’, and ‘@r’ requests a roman font, which is the usual font in which text is printed. All four commands apply to an argument that follows, surrounded by braces. Only the ‘@r’ command has much use: in example programs, you can use the ‘@r’ command to convert code comments from the fixed-width font to a roman font. This looks better in printed output. For example,
(+ 2 2) ; Add two plus two.
produces (+ 2 2) ; Add two plus two. If possible, you should avoid using the other three font commands. If you need to use one, it probably indicates a gap in the Texinfo language. File: texi.info, Node: Quotations and Examples, Next: Lists and Tables, Prev: Marking Text, Up: Top Quotations and Examples *********************** Quotations and examples are blocks of text consisting of one or more whole paragraphs that are set off from the bulk of the text and treated differently. They are usually indented. In Texinfo, you always begin a quotation or example by writing an command at the beginning of a line by itself, and end it by writing an ‘@end’ command that is also at the beginning of a line by itself. For instance, you begin an example by writing ‘
' by itself at the beginning of a line and end the example by writing `
’on a line by itself, at the beginning of that line. * Menu: * Block Enclosing Commands:: Use different constructs for different purposes. * quotation:: How to write a quotation. * example:: How to write an example in a fixed-width font. * noindent:: How to prevent paragraph indentation. * Lisp Example:: How to illustrate Lisp code. * smallexample & smalllisp:: Forms for the ‘* display:: How to write an example in the current font. * format:: How to write an example that does not narrow the margins. * exdent:: How to undo the indentation of a line. * flushleft & flushright:: How to push text flushleft or flushright. * cartouche:: How to draw cartouches around examples. File: texi.info, Node: Block Enclosing Commands, Next: quotation, Up: Quotations and Examples The Block Enclosing Commands ============================ Here are commands for quotations and examples: ‘
’: Indicate text that is quoted. The text is filled, indented, and printed in a roman font by default. ‘
' Illustrate code, commands, and the like. The text is printed in a fixed-width font, and indented but not filled. `' Illustrate Lisp code. The text is printed in a fixed-width font, and indented but not filled. `' Illustrate code, commands, and the like. Similar to `', except that in TeX this command typesets text in a smaller font for the smaller ` format. `' Illustrate Lisp code. Similar to `', except that in TeX this command typesets text in a smaller font for the smaller ``' Display illustrative text. The text is indented but not filled, and no font is specified (so, by default, the font is roman). `' Print illustrative text. The text is not indented and not filled and no font is specified (so, by default, the font is roman). The `' command is used within the above constructs to undo the indentation of a line. The `' and `' commands are used to line up the left or right margins of unfilled text. The `' command may be used after one of the above constructs to prevent the following text from being indented as a new paragraph. You can use the `
' command within one of the above constructs to highlight the example or quotation by drawing a box with rounded corners around it. (The `
' command affects only the printed manual; it has no effect in the Info file; see *Note Drawing Cartouches Around Examples: cartouche.) File: texi.info, Node: quotation, Next: example, Prev: Block Enclosing Commands, Up: Quotations and Examples `': ============ The text of a quotation is processed normally except that: * the margins are closer to the center of the page, so the whole of the quotation is indented; * the first lines of paragraphs are indented no more than other lines; * in the printed output, interparagraph spacing is reduced. This is an example of text written between an `' command: and an `'command. An `' command is most: often used to indicate text that is excerpted from another (real or hypothetical) printed work. Write an `' command as text on a line by itself. This: line will disappear from the output. Mark the end of the quotation with a line beginning with and containing only `'. The `'line will likewise disappear from the output. Thus, the following,This is a foo.produces This is a foo. File: texi.info, Node: example, Next: noindent, Prev: quotation, Up: Quotations and Examples `' ========== The `' command is used to indicate an example that is not part of the running text, such as computer input or output. This is an example of text written between an `' command and an `'command. The text is indented but not filled. In the printed manual, the text is typeset in a fixed-width font, and extra spaces and blank lines are significant. In the Info file, an analogous result is obtained by indenting each line with five spaces. Write an `' command at the beginning of a line by itself. This line will disappear from the output. Mark the end of the example with an `'command, also written at the beginning of a line by itself. The `'will disappear from the output. For example,mv foo barproduces mv foo bar Since the lines containing `' and `'will disappear, you should put a blank line before the `' and another blank line after the `'. (Remember that blank lines between the beginning `' and the ending `'will appear in the output.) *Caution:* Do not use tabs in the lines of an example (or anywhere else in Texinfo, for that matter)! TeX treats tabs as single spaces, and that is not what they look like. This is a problem with TeX. (If necessary, in Emacs, you can use `M-x untabify' to convert tabs in a region to multiple spaces.) Examples are often, logically speaking, "in the middle" of a paragraph, and the text continues after an example should not be indented. The `' command prevents a piece of text from being indented as if it were a new paragraph. (*Note noindent::.) (The `@code' command is used for examples of code that are embedded within sentences, not set off from preceding and following text. *Note `@code': code.) File: texi.info, Node: noindent, Next: Lisp Example, Prev: example, Up: Quotations and Examples `' =========== An example or other inclusion can break a paragraph into segments. Ordinarily, the formatters indent text that follows an example as a new paragraph. However, you can prevent this by writing `' at the beginning of a line by itself preceding the continuation text. For example:This is an exampleThis line is not indented. As you can see, the beginning of the line is fully flush left with the line that follows after it. (This whole example is between@display
and@end display
.) produces This is an example This line is not indented. As you can see, the beginning of the line is fully flush left with the line that follows after it. (This whole example is between `' and `'.) To adjust the number of blank lines properly in the Info file output, remember that the line containing `' does not generate a blank line, and neither does the `'line. In the Texinfo source file for this manual, each line that says `produces' is preceded by a line containing `'. Do not put braces after an `' command; they are not necessary, since `' is a command used outside of paragraphs (*note Command Syntax::.). File: texi.info, Node: Lisp Example, Next: smallexample & smalllisp, Prev: noindent, Up: Quotations and Examples `' ======= The `' command is used for Lisp code. It is synonymous with the `' command. This is an example of text written between an `' command and an `'command. Use `' instead of `' so as to preserve information regarding the nature of the example. This is useful, for example, if you write a function that evaluates only and all the Lisp code in a Texinfo file. Then you can use the Texinfo file as a Lisp library.(1) Mark the end of `' with `'on a line by itself. ---------- Footnotes ---------- (1) It would be straightforward to extend Texinfo to work in a similar fashion for C, FORTRAN, or other languages. File: texi.info, Node: smallexample & smalllisp, Next: display, Prev: Lisp Example, Up: Quotations and Examples `' and `' ================================ In addition to the regular `' and `' commands, Texinfo has two other "example-style" commands. These are the `' and `' commands. Both these commands are designed for use with the `manual in a 7 by 9.25 inch format rather than the regular 8.5 by 11 inch format. In TeX, the `' and `' commands typeset text in a smaller font for the smaller `by 11 inch format. Consequently, many examples containing long lines fit in a narrower, `Both commands typeset in the normal font size when you format for the 8.5 by 11 inch size; indeed, in this situation, the `' and `' commands are defined to be the `' and `' commands. In Info, the `' and `' commands are equivalent to the `' and `' commands, and work exactly the same. Mark the end of `' or `' with `@end smallexample' or `',respectively. This is an example of text written between `' and `'. In Info and in an 8.5 by 11 inch manual, this text appears in its normal size; but in a 7 by 9.25 inch manual, this text appears in a smaller font. The `' and `' commands make it easier to prepare smaller format manuals without forcing you to edit examples by hand to fit them onto narrower pages. As a general rule, a printed document looks better if you write all the examples in a chapter consistently in `' or in `'. Only occasionally should you mix the two formats. *Note Printing "Small" Books: smallbook, for more information about the `File: texi.info, Node: display, Next: format, Prev: smallexample & smalllisp, Up: Quotations and Examples `' ========== The `' command begins a kind of example. It is like the `' command except that, in a printed manual, `' does not select the fixed-width font. In fact, it does not specify the font at all, so that the text appears in the same font it would have appeared in without the `' command. This is an example of text written between an `' command and an `'command. The `' command indents the text, but does not fill it. File: texi.info, Node: format, Next: exdent, Prev: display, Up: Quotations and Examples `' ========= The `' command is similar to `' except that, in the printed manual, `' does not select the fixed-width font and does not narrow the margins. This is an example of text written between an `' command and an `'command. As you can see from this example, the `' command does not fill the text. File: texi.info, Node: exdent, Next: flushleft & flushright, Prev: format, Up: Quotations and Examples `': Undoing a Line's Indentation ======================================= The `' command removes any indentation a line might have. The command is written at the beginning of a line and applies only to the text that follows the command that is on the same line. Do not use braces around the text. In a printed manual, the text on an `' line is printed in the roman font. `' is usually used within examples. Thus,This line follows an @example command. This line is exdented. This line follows the exdented line. The @end example comes on the next line.
produces This line follows an
command. This line is exdented. This line follows the exdented line. The
comes on the next line. In practice, the ‘’ command is rarely used. Usually, you un-indent text by ending the example and returning the page to its normal width. File: texi.info, Node: flushleft & flushright, Next: cartouche, Prev: exdent, Up: Quotations and Examples ‘
’ and ‘
’ ============================== The ‘
’ and ‘
’ commands line up the ends of lines on the left and right margins of a page, but do not fill the text. The commands are written on lines of their own, without braces. The ‘
’ and ‘
’ commands are ended by ‘@end flushleft’ and ‘
’commands on lines of their own. For example,
This text is written flushleft.
produces This text is written flushleft. Flushright produces the type of indentation often used in the return address of letters. For example,
Here is an example of text written
flushright. The
command
right justifies every line but leaves the
left end ragged.
produces Here is an example of text written flushright. The ‘
’ command right justifies every line but leaves the left end ragged. File: texi.info, Node: cartouche, Prev: flushleft & flushright, Up: Quotations and Examples Drawing Cartouches Around Examples ================================== In a printed manual, the ‘
’ command draws a box with rounded corners around its contents. You can use this command to further highlight an example or quotation. For instance, you could write a manual in which one type of example is surrounded by a cartouche for emphasis. The ‘
|
This document was generated on January 5, 2023 using texi2html 5.0.