JezK
Edit File: Conventions.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ --> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <!-- This manual is for GNU Texinfo (version 6.8, 8 June 2021), a documentation system that can produce both online information and a printed manual from a single source using semantic markup. Copyright (C) 1988, 1990-1993, 1995-1999, 2001-2021 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". --> <title>Conventions (GNU Texinfo 6.8)</title> <meta name="description" content="Conventions (GNU Texinfo 6.8)"> <meta name="keywords" content="Conventions (GNU Texinfo 6.8)"> <meta name="resource-type" content="document"> <meta name="distribution" content="global"> <meta name="Generator" content="texi2any"> <meta name="viewport" content="width=device-width,initial-scale=1"> <link href="index.html" rel="start" title="Top"> <link href="Command-and-Variable-Index.html" rel="index" title="Command and Variable Index"> <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> <link href="Writing-a-Texinfo-File.html" rel="up" title="Writing a Texinfo File"> <link href="Comments.html" rel="next" title="Comments"> <style type="text/css"> <!-- a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em} a.summary-letter {text-decoration: none} blockquote.indentedblock {margin-right: 0em} div.display {margin-left: 3.2em} div.example {margin-left: 3.2em} kbd {font-style: oblique} pre.display {font-family: inherit} pre.format {font-family: inherit} pre.menu-comment {font-family: serif} pre.menu-preformatted {font-family: serif} span.nolinebreak {white-space: nowrap} span.roman {font-family: initial; font-weight: normal} span.sansserif {font-family: sans-serif; font-weight: normal} span:hover a.copiable-anchor {visibility: visible} ul.no-bullet {list-style: none} --> </style> </head> <body lang="en"> <div class="section" id="Conventions"> <div class="header"> <p> Next: <a href="Comments.html" accesskey="n" rel="next">Comments</a>, Up: <a href="Writing-a-Texinfo-File.html" accesskey="u" rel="up">Writing a Texinfo File</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html" title="Index" rel="index">Index</a>]</p> </div> <hr> <span id="General-Syntactic-Conventions"></span><h3 class="section">2.1 General Syntactic Conventions</h3> <span id="index-General-syntactic-conventions"></span> <span id="index-Syntactic-conventions"></span> <span id="index-Conventions_002c-syntactic"></span> <span id="index-Characters_002c-basic-input"></span> <span id="Formatting-Commands"></span> <p>This section describes the general conventions used in all Texinfo documents. </p> <ul> <li> <span id="index-Source-files_002c-characters-used"></span> All printable ASCII characters except ‘<samp>@</samp>’, ‘<samp>{</samp>’ and ‘<samp>}</samp>’ can appear in a Texinfo file and stand for themselves. ‘<samp>@</samp>’ is the escape character which introduces commands, while ‘<samp>{</samp>’ and ‘<samp>}</samp>’ are used to surround arguments to certain commands. To put one of these special characters into the document, put an ‘<samp>@</samp>’ character in front of it, like this: ‘<samp>@@</samp>’, ‘<samp>@{</samp>’, and ‘<samp>@}</samp>’. </li><li> <span id="index-at_0040_002dcommands"></span> <span id="index-Formatting-commands"></span> In a Texinfo file, the commands you write to describe the contents of the manual are preceded by an ‘<samp>@</samp>’ character; they are called <em>@-commands</em>. (The ‘<samp>@</samp>’ in Texinfo has the same meaning that ‘<samp>\</samp>’ has in plain TeX.) <span id="index-Braces_002c-when-to-use"></span> <p>Depending on what they do or what arguments they take, you need to write @-commands on lines of their own, or as part of sentences. As a general rule, a command requires braces if it mingles among other text; but it does not need braces if it is on a line of its own. For more details of Texinfo command syntax, see <a href="Command-Syntax.html">@-Command Syntax</a>. </p> </li><li> Whitespace following an @-command name is optional and (usually) ignored if present. The exceptions are contexts when whitespace is significant, e.g., an <code>@example</code> environment. </li><li> Texinfo supports the usual quotation marks used in English and in other languages; see <a href="Inserting-Quotation-Marks.html">Inserting Quotation Marks</a>. </li><li> <span id="index-Multiple-dashes-in-source"></span> <span id="index-Dashes-in-source"></span> <span id="index-Hyphens-in-source_002c-two-or-three-in-a-row"></span> <span id="index-Em-dash_002c-producing"></span> <span id="index-En-dash_002c-producing"></span> Use three hyphens in a row, ‘<samp>---</samp>’, to produce a long dash—like this (called an <em>em dash</em>), used for punctuation in sentences. Use two hyphens, ‘<samp>--</samp>’, to produce a medium dash (called an <em>en dash</em>), used primarily for numeric ranges, as in “June 25–26”. Use a single hyphen, ‘<samp>-</samp>’, to produce a standard hyphen used in compound words. For display on the screen, Info reduces three hyphens to two and two hyphens to one (not transitively!). Of course, any number of hyphens in the source remain as they are in literal contexts, such as <code>@code</code> and <code>@example</code>. </li><li> Do not use tab characters in a Texinfo file! (Except perhaps in verbatim modes.) TeX uses variable-width fonts, which means that it is impractical at best to define a tab to work in all circumstances. Consequently, TeX treats tabs like single spaces, and that is not what they look like in the source. Furthermore, <code>makeinfo</code> does nothing special with tabs, and thus a tab character in your input file will usually have a different appearance in the output. <p>To avoid this problem, Texinfo mode in GNU Emacs inserts multiple spaces when you press the <tt class="key">TAB</tt> key. Also, you can run <code>untabify</code> in Emacs to convert tabs in a region to multiple spaces, or use the <code>unexpand</code> command from the shell. </p> </li><li> <span id="index-Form-feed-characters"></span> <span id="index-CTRL_002dl"></span> Lastly, form feed (<kbd>CTRL-l</kbd>) characters in the input are handled as follows: <dl compact="compact"> <dt><span>PDF/DVI</span></dt> <dd><p>In normal text, treated as ending any open paragraph; essentially ignored between paragraphs. </p> </dd> <dt><span>Info</span></dt> <dd><p>Output as-is between paragraphs (their most common use); in other contexts, they may be treated as regular spaces (and thus consolidated with surrounding whitespace). </p> </dd> <dt><span>HTML</span></dt> <dd><p>Written as a numeric entity except contexts where spaces are ignored; for example, in ‘<samp>@footnote{ ^L foo}</samp>’, the form feed is ignored. </p> </dd> <dt><span>XML</span></dt> <dd><p>Keep them everywhere; in attributes, escaped as ‘<samp>\f</samp>’; also, ‘<samp>\</samp>’ is escaped as ‘<samp>\\</samp>’ and newline as ‘<samp>\n</samp>’. </p> </dd> <dt><span>DocBook</span></dt> <dd><p>Completely removed, as they are not allowed. </p></dd> </dl> <p>As you can see, because of these differing requirements of the output formats, it’s not possible to use form feeds completely portably. </p> </li></ul> </div> <hr> <div class="header"> <p> Next: <a href="Comments.html">Comments</a>, Up: <a href="Writing-a-Texinfo-File.html">Writing a Texinfo File</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html" title="Index" rel="index">Index</a>]</p> </div> </body> </html>