infog/test-infodir/texinfo_html/Tips.html - texinfo - Git at Google

 <!DOCTYPE html>
 <html>
 <!-- Created by Texinfo 6.8dev+dev, http://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.8dev, 23 February 2022),
 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-2022 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>Tips (GNU Texinfo 6.8dev)</title>

 <meta name="description" content="Tips (GNU Texinfo 6.8dev)">
 <meta name="keywords" content="Tips (GNU Texinfo 6.8dev)">
 <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="index.html" rel="up" title="Top">
 <link href="Sample-Texinfo-Files.html" rel="next" title="Sample Texinfo Files">
 <link href="_0040_002dCommand-Details.html" rel="prev" title="@-Command Details">
 <style type="text/css">
 <!--
 div.example {margin-left: 3.2em}
 ul.mark-bullet {list-style-type: disc}
 -->
 </style>


 </head>

 <body lang="en">
 <div class="appendix-level-extent" id="Tips">
 <div class="nav-panel">
 <p>
 Next: <a href="Sample-Texinfo-Files.html" accesskey="n" rel="next">Sample Texinfo Files</a>, Previous: <a href="_0040_002dCommand-Details.html" accesskey="p" rel="prev">@-Command Details</a>, Up: <a href="index.html" accesskey="u" rel="up">Texinfo</a> &nbsp; [<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>
 <h2 class="appendix" id="Tips-and-Hints">Appendix B Tips and Hints</h2>

 <p>Here are some tips for writing Texinfo documentation:
 </p>
 <a class="index-entry-id" id="index-Tips"></a>
 <a class="index-entry-id" id="index-Usage-tips"></a>
 <a class="index-entry-id" id="index-Hints"></a>
 <ul class="itemize mark-bullet">
 <li>Write in the present tense, not in the past or the future.

 </li><li>Write actively!  For example, write &ldquo;We recommend that &hellip;&rdquo; rather
 than &ldquo;It is recommended that &hellip;&rdquo;.

 </li><li>Use 70 or 72 as your fill column.  Longer lines are hard to read.

 </li><li>Include a copyright notice and copying permissions.
 </li></ul>


 <h4 class="subsubheading" id="Index_002c-Index_002c-Index_0021">Index, Index, Index!</h4>

 <p>Write many index entries, in different ways.
 Readers like indices; they are helpful and convenient.
 </p>
 <p>Although it is easiest to write index entries as you write the body of
 the text, some people prefer to write entries afterwards.  In either
 case, write an entry before the paragraph to which it applies.  This
 way, an index entry points to the first page of a paragraph that is
 split across pages.
 </p>
 <p>Here are more index-related hints we have found valuable:
 </p>
 <ul class="itemize mark-bullet">
 <li>Write each index entry differently, so each entry refers to a different
 place in the document.

 </li><li>Write index entries only where a topic is discussed significantly.  For
 example, it is not useful to index &ldquo;debugging information&rdquo; in a
 chapter on reporting bugs.  Someone who wants to know about debugging
 information will certainly not find it in that chapter.

 </li><li>Consistently capitalize the first word of every concept index entry,
 or else consistently use lowercase.  Terse entries often call for
 lowercase; longer entries for capitalization.  Whichever case
 convention you use, please use one or the other consistently!  Mixing
 the two styles looks bad.

 </li><li>Always capitalize or use uppercase for those words in an index for
 which this is proper, such as names of countries or acronyms.  Always
 use the appropriate case for case-sensitive names, such as those in C or
 Lisp.

 </li><li>Write the indexing commands that refer to a whole section immediately
 after the section command, and write the indexing commands that refer to
 a paragraph before that paragraph.

 <p>In the example that follows, a blank line comes after the index
 entry for &ldquo;Leaping&rdquo;:
 </p>
 <div class="example">
 <div class="group"><pre class="example-preformatted">@section The Dog and the Fox
 @cindex Jumping, in general
 @cindex Leaping

 @cindex Dog, lazy, jumped over
 @cindex Lazy dog jumped over
 @cindex Fox, jumps over dog
 @cindex Quick fox jumps over dog
 The quick brown fox jumps over the lazy dog.
 </pre></div></div>

 <p>(Note that the example shows entries for the same concept that are
 written in different ways&mdash;&lsquo;<samp class="samp">Lazy dog</samp>&rsquo;, and &lsquo;<samp class="samp">Dog, lazy</samp>&rsquo;&mdash;so
 readers can look up the concept in different ways.)
 </p></li></ul>


 <h4 class="subsubheading" id="Blank-Lines">Blank Lines</h4>

 <ul class="itemize mark-bullet">
 <li>Insert a blank line between a sectioning command and the first following
 sentence or paragraph, or between the indexing commands associated with
 the sectioning command and the first following sentence or paragraph, as
 shown in the tip on indexing.  It makes the source easier to read.

 </li><li>Always insert a blank line before a <code class="code">@table</code> command and after an
 <code class="code">@end table</code> command; but never insert a blank line after an
 <code class="code">@table</code> command.

 <p>For example,
 </p>
 <div class="example">
 <div class="group"><pre class="example-preformatted">Types of fox:

 @table @samp
 @item Quick
 Jump over lazy dogs.
 </pre></div><pre class="example-preformatted">

 </pre><div class="group"><pre class="example-preformatted">@item Brown
 Also jump over lazy dogs.
 @end table

 </pre></div><div class="group"><pre class="example-preformatted">@noindent
 On the other hand, &hellip;
 </pre></div></div>

 <p>Insert blank lines before and after <code class="code">@itemize</code> &hellip; <code class="code">@end
 itemize</code> and <code class="code">@enumerate</code> &hellip; <code class="code">@end enumerate</code> in the
 same way.
 </p></li></ul>


 <h4 class="subsubheading" id="Complete-Phrases">Complete Phrases</h4>

 <p>Complete phrases are easier to read than &hellip;
 </p>
 <ul class="itemize mark-bullet">
 <li>Write entries in an itemized list as complete sentences; or at least, as
 complete phrases.  Incomplete expressions &hellip; awkward &hellip; like
 this.

 </li><li>Write the prefatory sentence or phrase for a multi-item list or table as
 a complete expression.  Do not write &ldquo;You can set:&rdquo;; instead, write
 &ldquo;You can set these variables:&rdquo;.  The former expression sounds cut off.
 </li></ul>


 <h4 class="subsubheading" id="Editions_002c-Dates-and-Versions">Editions, Dates and Versions</h4>

 <p>Include edition numbers, version numbers, and dates in the
 <code class="code">@copying</code> text (for people reading the Texinfo file, and for the
 legal copyright in the output files).  Then use <code class="code">@insertcopying</code>
 in the <code class="code">@titlepage</code> section for people reading the printed
 output (see <a class="pxref" href="Short-Sample-Texinfo-File.html#Short-Sample">Short Sample</a>).
 </p>
 <p>It is easiest to handle such version information using <code class="code">@set</code>
 and <code class="code">@value</code>.  See <a class="xref" href="_0040value-Example.html"><code class="code">@value</code> Example</a>, and <a class="ref" href="GNU-Sample-Texts.html">GNU Sample Texts</a>.
 </p>

 <h4 class="subsubheading" id="Definition-Commands-2">Definition Commands</h4>

 <p>Definition commands are <code class="code">@deffn</code>, <code class="code">@defun</code>,
 <code class="code">@defmac</code>, and the like, and enable you to write descriptions in
 a uniform format.
 </p>
 <ul class="itemize mark-bullet">
 <li>Write just one definition command for each entity you define with a
 definition command.  The automatic indexing feature creates an index
 entry that leads the reader to the definition.

 </li><li>Use <code class="code">@table</code> &hellip; <code class="code">@end table</code> in an appendix that
 contains a summary of functions, not <code class="code">@deffn</code> or other definition
 commands.
 </li></ul>


 <h4 class="subsubheading" id="Capitalization">Capitalization</h4>

 <ul class="itemize mark-bullet">
 <li>Capitalize &ldquo;Texinfo&rdquo;; it is a name.  Do not write the &lsquo;<samp class="samp">x</samp>&rsquo; or
 &lsquo;<samp class="samp">i</samp>&rsquo; in uppercase.

 </li><li>Capitalize &ldquo;Info&rdquo;; it is a name.

 </li><li>Write TeX using the <code class="code">@TeX{}</code> command.  Note the uppercase
 &lsquo;<samp class="samp">T</samp>&rsquo; and &lsquo;<samp class="samp">X</samp>&rsquo;.  This command causes the formatters to
 typeset the name according to the wishes of Donald Knuth, who wrote
 TeX.  (Likewise <code class="code">@LaTeX{}</code> for LaTeX.)
 </li></ul>


 <h4 class="subsubheading" id="Spaces">Spaces</h4>

 <p>Do not use spaces to format a Texinfo file, except inside of
 <code class="code">@example</code> &hellip; <code class="code">@end example</code> and other literal
 environments and commands.
 </p>
 <p>For example, TeX fills the following:
 </p>
 <div class="example">
 <div class="group"><pre class="example-preformatted">   @kbd{C-x v}
    @kbd{M-x vc-next-action}
       Perform the next logical operation
       on the version-controlled file
       corresponding to the current buffer.
 </pre></div></div>

 <p>so it looks like this:
 </p>
 <blockquote class="quotation">
 <p>&lsquo;C-x v&rsquo; &lsquo;M-x vc-next-action&rsquo; Perform the next logical operation on the
 version-controlled file corresponding to the current buffer.
 </p></blockquote>

 <p>In this case, the text should be formatted with
 <code class="code">@table</code>, <code class="code">@item</code>, and <code class="code">@itemx</code>, to create a table.
 </p>

 <h4 class="subsubheading" id="g_t_0040code_002c-_0040samp_002c-_0040var_002c-and-_002d_002d_002d">@code, @samp, @var, and &lsquo;<samp class="samp">---</samp>&rsquo;</h4>

 <ul class="itemize mark-bullet">
 <li>Use <code class="code">@code</code> around Lisp symbols, including command names.
 For example,

 <div class="example">
 <pre class="example-preformatted">The main function is @code{vc-next-action}, &hellip;
 </pre></div>

 </li><li>Avoid putting letters such as &lsquo;<samp class="samp">s</samp>&rsquo; immediately after an
 &lsquo;<samp class="samp">@code</samp>&rsquo;.  Such letters look bad.

 </li><li>Use <code class="code">@var</code> around meta-variables.  Do not write angle brackets
 around them.

 </li><li>Use three hyphens in a row, &lsquo;<samp class="samp">---</samp>&rsquo;, to indicate a long dash.  TeX
 typesets these as a long dash and the Info formatters reduce three
 hyphens to two.
 </li></ul>


 <h4 class="subsubheading" id="Periods-Outside-of-Quotes">Periods Outside of Quotes</h4>

 <p>Place periods and other punctuation marks <em class="emph">outside</em> of quotations,
 unless the punctuation is part of the quotation.  This practice goes
 against some publishing conventions in the United States, but enables the
 reader to distinguish between the contents of the quotation and the
 whole passage.
 </p>
 <p>For example, you should write the following sentence with the period
 outside the end quotation marks:
 </p>
 <div class="example">
 <pre class="example-preformatted">Evidently, &lsquo;<samp class="samp">au</samp>&rsquo; is an abbreviation for ``author''.
 </pre></div>

 <p>since &lsquo;<samp class="samp">au</samp>&rsquo; does <em class="emph">not</em> serve as an  abbreviation for
 &lsquo;<samp class="samp">author.</samp>&rsquo; (with a period following the word).
 </p>

 <h4 class="subsubheading" id="Introducing-New-Terms">Introducing New Terms</h4>

 <ul class="itemize mark-bullet">
 <li>Introduce new terms so that a reader who does not know them can
 understand them from context; or write a definition for the term.

 <p>For example, in the following, the terms &ldquo;check in&rdquo;, &ldquo;register&rdquo; and
 &ldquo;delta&rdquo; are all appearing for the first time; the example sentence should be
 rewritten so they are understandable.
 </p>
 <blockquote class="quotation">
 <p>The major function assists you in checking in a file to your
 version control system and registering successive sets of changes to
 it as deltas.
 </p></blockquote>

 </li><li>Use the <code class="code">@dfn</code> command around a word being introduced, to indicate
 that the reader should not expect to know the meaning already, and
 should expect to learn the meaning from this passage.
 </li></ul>


 <h4 class="subsubheading" id="Program-Invocation-Nodes">Program Invocation Nodes</h4>

 <p>You can invoke programs such as Emacs, GCC, and <code class="code">gawk</code> from a
 shell.  The documentation for each program should contain a section that
 describes this.  Unfortunately, if the node names and titles for these
 sections are all different, they are difficult for users to find.
 </p>
 <p>So, there is a convention to name such sections with a phrase beginning
 with the word &lsquo;Invoking&rsquo;, as in &lsquo;Invoking Emacs&rsquo;; this way, users can
 find the section easily.
 </p>

 <h4 class="subsubheading" id="ANSI-C-Syntax">ANSI C Syntax</h4>

 <p>When you use <code class="code">@example</code> to describe a C function&rsquo;s calling
 conventions, use the ANSI C syntax, like this:
 </p>
 <div class="example">
 <pre class="example-preformatted">void dld_init (char *@var{path});
 </pre></div>

 <p>And in the subsequent discussion, refer to the argument values by
 writing the same argument names, again highlighted with
 <code class="code">@var</code>.
 </p>
 <p>Avoid the obsolete style that looks like this:
 </p>
 <div class="example">
 <pre class="example-preformatted">#include &lt;dld.h&gt;

 dld_init (path)
   char *path;
 </pre></div>

 <p>Also, it is best to avoid writing <code class="code">#include</code> above the
 declaration just to indicate that the function is declared in a
 header file.  The practice may give the misimpression that the
 <code class="code">#include</code> belongs near the declaration of the function.  Either
 state explicitly which header file holds the declaration or, better
 yet, name the header file used for a group of functions at the
 beginning of the section that describes the functions.
 </p>
 <a class="anchor" id="texi_002delements_002dby_002dsize"></a><h4 class="subsubheading" id="Node-Length">Node Length</h4>

 <p>Keep nodes (sections) to a reasonable length, whatever reasonable
 might be in the given context.  Don&rsquo;t hesitate to break up long nodes
 into subnodes and have an extensive tree structure; that&rsquo;s what it&rsquo;s
 there for.  Many times, readers will probably try to find a single
 specific point in the manual, using search, indexing, or just plain
 guessing, rather than reading the whole thing from beginning to end.
 </p>
 <p>You can use the <code class="command">texi-elements-by-size</code> utility to see a list
 of all nodes (or sections) in the document, sorted by size (either
 lines or words), to find candidates for splitting.  It&rsquo;s in the
 <samp class="file">util/</samp> subdirectory of the Texinfo sources.
 </p>

 <h4 class="subsubheading" id="Bad-Examples">Bad Examples</h4>

 <p>Here are several examples of bad writing to avoid:
 </p>
 <p>In this example, say, &ldquo; &hellip; you must <code class="code">@dfn</code>{check
 in} the new version.&rdquo;  That flows better.
 </p>
 <blockquote class="quotation">
 <p>When you are done editing the file, you must perform a
 <code class="code">@dfn</code>{check in}.
 </p></blockquote>

 <p>In the following example, say, &ldquo;&hellip; makes a unified interface such as VC
 mode possible.&rdquo;
 </p>
 <blockquote class="quotation">
 <p>SCCS, RCS and other version-control systems all perform similar
 functions in broadly similar ways (it is this resemblance which makes
 a unified control mode like this possible).
 </p></blockquote>

 <p>And in this example, you should specify what &lsquo;it&rsquo; refers to:
 </p>
 <blockquote class="quotation">
 <p>If you are working with other people, it assists in coordinating
 everyone&rsquo;s changes so they do not step on each other.
 </p></blockquote>


 <h4 class="subsubheading" id="And-Finally-_2026">And Finally &hellip;</h4>

 <ul class="itemize mark-bullet">
 <li>Pronounce TeX as if the &lsquo;<samp class="samp">X</samp>&rsquo; were a Greek &lsquo;chi&rsquo;, as the last
 sound in the name &lsquo;Bach&rsquo;.  But pronounce Texinfo as in &lsquo;speck&rsquo;:
 &ldquo;teckinfo&rdquo;.

 </li><li>Write notes for yourself at the very end of a Texinfo file after the
 <code class="code">@bye</code>.  None of the formatters process text after the
 <code class="code">@bye</code>; it is as if the text were within <code class="code">@ignore</code> &hellip;
 <code class="code">@end ignore</code>.
 </li></ul>


 </div>
 <hr>
 <div class="nav-panel">
 <p>
 Next: <a href="Sample-Texinfo-Files.html">Sample Texinfo Files</a>, Previous: <a href="_0040_002dCommand-Details.html">@-Command Details</a>, Up: <a href="index.html">Texinfo</a> &nbsp; [<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>
	<!DOCTYPE html>
	<html>
	<!-- Created by Texinfo 6.8dev+dev, http://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.8dev, 23 February 2022),
	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-2022 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>Tips (GNU Texinfo 6.8dev)</title>

	<meta name="description" content="Tips (GNU Texinfo 6.8dev)">
	<meta name="keywords" content="Tips (GNU Texinfo 6.8dev)">
	<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="index.html" rel="up" title="Top">
	<link href="Sample-Texinfo-Files.html" rel="next" title="Sample Texinfo Files">
	<link href="_0040_002dCommand-Details.html" rel="prev" title="@-Command Details">
	<style type="text/css">
	<!--
	div.example {margin-left: 3.2em}
	ul.mark-bullet {list-style-type: disc}
	-->
	</style>


	</head>

	<body lang="en">
	<div class="appendix-level-extent" id="Tips">
	<div class="nav-panel">
	<p>
	Next: <a href="Sample-Texinfo-Files.html" accesskey="n" rel="next">Sample Texinfo Files</a>, Previous: <a href="_0040_002dCommand-Details.html" accesskey="p" rel="prev">@-Command Details</a>, Up: <a href="index.html" accesskey="u" rel="up">Texinfo</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>
	<h2 class="appendix" id="Tips-and-Hints">Appendix B Tips and Hints</h2>

	<p>Here are some tips for writing Texinfo documentation:
	</p>
	<a class="index-entry-id" id="index-Tips"></a>
	<a class="index-entry-id" id="index-Usage-tips"></a>
	<a class="index-entry-id" id="index-Hints"></a>
	<ul class="itemize mark-bullet">
	<li>Write in the present tense, not in the past or the future.

	</li><li>Write actively! For example, write “We recommend that …” rather
	than “It is recommended that …”.

	</li><li>Use 70 or 72 as your fill column. Longer lines are hard to read.

	</li><li>Include a copyright notice and copying permissions.
	</li></ul>


	<h4 class="subsubheading" id="Index_002c-Index_002c-Index_0021">Index, Index, Index!</h4>

	<p>Write many index entries, in different ways.
	Readers like indices; they are helpful and convenient.
	</p>
	<p>Although it is easiest to write index entries as you write the body of
	the text, some people prefer to write entries afterwards. In either
	case, write an entry before the paragraph to which it applies. This
	way, an index entry points to the first page of a paragraph that is
	split across pages.
	</p>
	<p>Here are more index-related hints we have found valuable:
	</p>
	<ul class="itemize mark-bullet">
	<li>Write each index entry differently, so each entry refers to a different
	place in the document.

	</li><li>Write index entries only where a topic is discussed significantly. For
	example, it is not useful to index “debugging information” in a
	chapter on reporting bugs. Someone who wants to know about debugging
	information will certainly not find it in that chapter.

	</li><li>Consistently capitalize the first word of every concept index entry,
	or else consistently use lowercase. Terse entries often call for
	lowercase; longer entries for capitalization. Whichever case
	convention you use, please use one or the other consistently! Mixing
	the two styles looks bad.

	</li><li>Always capitalize or use uppercase for those words in an index for
	which this is proper, such as names of countries or acronyms. Always
	use the appropriate case for case-sensitive names, such as those in C or
	Lisp.

	</li><li>Write the indexing commands that refer to a whole section immediately
	after the section command, and write the indexing commands that refer to
	a paragraph before that paragraph.

	<p>In the example that follows, a blank line comes after the index
	entry for “Leaping”:
	</p>
	<div class="example">
	<div class="group"><pre class="example-preformatted">@section The Dog and the Fox
	@cindex Jumping, in general
	@cindex Leaping

	@cindex Dog, lazy, jumped over
	@cindex Lazy dog jumped over
	@cindex Fox, jumps over dog
	@cindex Quick fox jumps over dog
	The quick brown fox jumps over the lazy dog.
	</pre></div></div>

	<p>(Note that the example shows entries for the same concept that are
	written in different ways—‘<samp class="samp">Lazy dog</samp>’, and ‘<samp class="samp">Dog, lazy</samp>’—so
	readers can look up the concept in different ways.)
	</p></li></ul>


	<h4 class="subsubheading" id="Blank-Lines">Blank Lines</h4>

	<ul class="itemize mark-bullet">
	<li>Insert a blank line between a sectioning command and the first following
	sentence or paragraph, or between the indexing commands associated with
	the sectioning command and the first following sentence or paragraph, as
	shown in the tip on indexing. It makes the source easier to read.

	</li><li>Always insert a blank line before a <code class="code">@table</code> command and after an
	<code class="code">@end table</code> command; but never insert a blank line after an
	<code class="code">@table</code> command.

	<p>For example,
	</p>
	<div class="example">
	<div class="group"><pre class="example-preformatted">Types of fox:

	@table @samp
	@item Quick
	Jump over lazy dogs.
	</pre></div><pre class="example-preformatted">

	</pre><div class="group"><pre class="example-preformatted">@item Brown
	Also jump over lazy dogs.
	@end table

	</pre></div><div class="group"><pre class="example-preformatted">@noindent
	On the other hand, …
	</pre></div></div>

	<p>Insert blank lines before and after <code class="code">@itemize</code> … <code class="code">@end
	itemize</code> and <code class="code">@enumerate</code> … <code class="code">@end enumerate</code> in the
	same way.
	</p></li></ul>


	<h4 class="subsubheading" id="Complete-Phrases">Complete Phrases</h4>

	<p>Complete phrases are easier to read than …
	</p>
	<ul class="itemize mark-bullet">
	<li>Write entries in an itemized list as complete sentences; or at least, as
	complete phrases. Incomplete expressions … awkward … like
	this.

	</li><li>Write the prefatory sentence or phrase for a multi-item list or table as
	a complete expression. Do not write “You can set:”; instead, write
	“You can set these variables:”. The former expression sounds cut off.
	</li></ul>


	<h4 class="subsubheading" id="Editions_002c-Dates-and-Versions">Editions, Dates and Versions</h4>

	<p>Include edition numbers, version numbers, and dates in the
	<code class="code">@copying</code> text (for people reading the Texinfo file, and for the
	legal copyright in the output files). Then use <code class="code">@insertcopying</code>
	in the <code class="code">@titlepage</code> section for people reading the printed
	output (see <a class="pxref" href="Short-Sample-Texinfo-File.html#Short-Sample">Short Sample</a>).
	</p>
	<p>It is easiest to handle such version information using <code class="code">@set</code>
	and <code class="code">@value</code>. See <a class="xref" href="_0040value-Example.html"><code class="code">@value</code> Example</a>, and <a class="ref" href="GNU-Sample-Texts.html">GNU Sample Texts</a>.
	</p>

	<h4 class="subsubheading" id="Definition-Commands-2">Definition Commands</h4>

	<p>Definition commands are <code class="code">@deffn</code>, <code class="code">@defun</code>,
	<code class="code">@defmac</code>, and the like, and enable you to write descriptions in
	a uniform format.
	</p>
	<ul class="itemize mark-bullet">
	<li>Write just one definition command for each entity you define with a
	definition command. The automatic indexing feature creates an index
	entry that leads the reader to the definition.

	</li><li>Use <code class="code">@table</code> … <code class="code">@end table</code> in an appendix that
	contains a summary of functions, not <code class="code">@deffn</code> or other definition
	commands.
	</li></ul>


	<h4 class="subsubheading" id="Capitalization">Capitalization</h4>

	<ul class="itemize mark-bullet">
	<li>Capitalize “Texinfo”; it is a name. Do not write the ‘<samp class="samp">x</samp>’ or
	‘<samp class="samp">i</samp>’ in uppercase.

	</li><li>Capitalize “Info”; it is a name.

	</li><li>Write TeX using the <code class="code">@TeX{}</code> command. Note the uppercase
	‘<samp class="samp">T</samp>’ and ‘<samp class="samp">X</samp>’. This command causes the formatters to
	typeset the name according to the wishes of Donald Knuth, who wrote
	TeX. (Likewise <code class="code">@LaTeX{}</code> for LaTeX.)
	</li></ul>


	<h4 class="subsubheading" id="Spaces">Spaces</h4>

	<p>Do not use spaces to format a Texinfo file, except inside of
	<code class="code">@example</code> … <code class="code">@end example</code> and other literal
	environments and commands.
	</p>
	<p>For example, TeX fills the following:
	</p>
	<div class="example">
	<div class="group"><pre class="example-preformatted"> @kbd{C-x v}
	@kbd{M-x vc-next-action}
	Perform the next logical operation
	on the version-controlled file
	corresponding to the current buffer.
	</pre></div></div>

	<p>so it looks like this:
	</p>
	<blockquote class="quotation">
	<p>‘C-x v’ ‘M-x vc-next-action’ Perform the next logical operation on the
	version-controlled file corresponding to the current buffer.
	</p></blockquote>

	<p>In this case, the text should be formatted with
	<code class="code">@table</code>, <code class="code">@item</code>, and <code class="code">@itemx</code>, to create a table.
	</p>

	<h4 class="subsubheading" id="g_t_0040code_002c-_0040samp_002c-_0040var_002c-and-_002d_002d_002d">@code, @samp, @var, and ‘<samp class="samp">---</samp>’</h4>

	<ul class="itemize mark-bullet">
	<li>Use <code class="code">@code</code> around Lisp symbols, including command names.
	For example,

	<div class="example">
	<pre class="example-preformatted">The main function is @code{vc-next-action}, …
	</pre></div>

	</li><li>Avoid putting letters such as ‘<samp class="samp">s</samp>’ immediately after an
	‘<samp class="samp">@code</samp>’. Such letters look bad.

	</li><li>Use <code class="code">@var</code> around meta-variables. Do not write angle brackets
	around them.

	</li><li>Use three hyphens in a row, ‘<samp class="samp">---</samp>’, to indicate a long dash. TeX
	typesets these as a long dash and the Info formatters reduce three
	hyphens to two.
	</li></ul>


	<h4 class="subsubheading" id="Periods-Outside-of-Quotes">Periods Outside of Quotes</h4>

	<p>Place periods and other punctuation marks <em class="emph">outside</em> of quotations,
	unless the punctuation is part of the quotation. This practice goes
	against some publishing conventions in the United States, but enables the
	reader to distinguish between the contents of the quotation and the
	whole passage.
	</p>
	<p>For example, you should write the following sentence with the period
	outside the end quotation marks:
	</p>
	<div class="example">
	<pre class="example-preformatted">Evidently, ‘<samp class="samp">au</samp>’ is an abbreviation for ``author''.
	</pre></div>

	<p>since ‘<samp class="samp">au</samp>’ does <em class="emph">not</em> serve as an abbreviation for
	‘<samp class="samp">author.</samp>’ (with a period following the word).
	</p>

	<h4 class="subsubheading" id="Introducing-New-Terms">Introducing New Terms</h4>

	<ul class="itemize mark-bullet">
	<li>Introduce new terms so that a reader who does not know them can
	understand them from context; or write a definition for the term.

	<p>For example, in the following, the terms “check in”, “register” and
	“delta” are all appearing for the first time; the example sentence should be
	rewritten so they are understandable.
	</p>
	<blockquote class="quotation">
	<p>The major function assists you in checking in a file to your
	version control system and registering successive sets of changes to
	it as deltas.
	</p></blockquote>

	</li><li>Use the <code class="code">@dfn</code> command around a word being introduced, to indicate
	that the reader should not expect to know the meaning already, and
	should expect to learn the meaning from this passage.
	</li></ul>


	<h4 class="subsubheading" id="Program-Invocation-Nodes">Program Invocation Nodes</h4>

	<p>You can invoke programs such as Emacs, GCC, and <code class="code">gawk</code> from a
	shell. The documentation for each program should contain a section that
	describes this. Unfortunately, if the node names and titles for these
	sections are all different, they are difficult for users to find.
	</p>
	<p>So, there is a convention to name such sections with a phrase beginning
	with the word ‘Invoking’, as in ‘Invoking Emacs’; this way, users can
	find the section easily.
	</p>

	<h4 class="subsubheading" id="ANSI-C-Syntax">ANSI C Syntax</h4>

	<p>When you use <code class="code">@example</code> to describe a C function’s calling
	conventions, use the ANSI C syntax, like this:
	</p>
	<div class="example">
	<pre class="example-preformatted">void dld_init (char *@var{path});
	</pre></div>

	<p>And in the subsequent discussion, refer to the argument values by
	writing the same argument names, again highlighted with
	<code class="code">@var</code>.
	</p>
	<p>Avoid the obsolete style that looks like this:
	</p>
	<div class="example">
	<pre class="example-preformatted">#include <dld.h>

	dld_init (path)
	char *path;
	</pre></div>

	<p>Also, it is best to avoid writing <code class="code">#include</code> above the
	declaration just to indicate that the function is declared in a
	header file. The practice may give the misimpression that the
	<code class="code">#include</code> belongs near the declaration of the function. Either
	state explicitly which header file holds the declaration or, better
	yet, name the header file used for a group of functions at the
	beginning of the section that describes the functions.
	</p>
	<a class="anchor" id="texi_002delements_002dby_002dsize"></a><h4 class="subsubheading" id="Node-Length">Node Length</h4>

	<p>Keep nodes (sections) to a reasonable length, whatever reasonable
	might be in the given context. Don’t hesitate to break up long nodes
	into subnodes and have an extensive tree structure; that’s what it’s
	there for. Many times, readers will probably try to find a single
	specific point in the manual, using search, indexing, or just plain
	guessing, rather than reading the whole thing from beginning to end.
	</p>
	<p>You can use the <code class="command">texi-elements-by-size</code> utility to see a list
	of all nodes (or sections) in the document, sorted by size (either
	lines or words), to find candidates for splitting. It’s in the
	<samp class="file">util/</samp> subdirectory of the Texinfo sources.
	</p>

	<h4 class="subsubheading" id="Bad-Examples">Bad Examples</h4>

	<p>Here are several examples of bad writing to avoid:
	</p>
	<p>In this example, say, “ … you must <code class="code">@dfn</code>{check
	in} the new version.” That flows better.
	</p>
	<blockquote class="quotation">
	<p>When you are done editing the file, you must perform a
	<code class="code">@dfn</code>{check in}.
	</p></blockquote>

	<p>In the following example, say, “… makes a unified interface such as VC
	mode possible.”
	</p>
	<blockquote class="quotation">
	<p>SCCS, RCS and other version-control systems all perform similar
	functions in broadly similar ways (it is this resemblance which makes
	a unified control mode like this possible).
	</p></blockquote>

	<p>And in this example, you should specify what ‘it’ refers to:
	</p>
	<blockquote class="quotation">
	<p>If you are working with other people, it assists in coordinating
	everyone’s changes so they do not step on each other.
	</p></blockquote>


	<h4 class="subsubheading" id="And-Finally-_2026">And Finally …</h4>

	<ul class="itemize mark-bullet">
	<li>Pronounce TeX as if the ‘<samp class="samp">X</samp>’ were a Greek ‘chi’, as the last
	sound in the name ‘Bach’. But pronounce Texinfo as in ‘speck’:
	“teckinfo”.

	</li><li>Write notes for yourself at the very end of a Texinfo file after the
	<code class="code">@bye</code>. None of the formatters process text after the
	<code class="code">@bye</code>; it is as if the text were within <code class="code">@ignore</code> …
	<code class="code">@end ignore</code>.
	</li></ul>


	</div>
	<hr>
	<div class="nav-panel">
	<p>
	Next: <a href="Sample-Texinfo-Files.html">Sample Texinfo Files</a>, Previous: <a href="_0040_002dCommand-Details.html">@-Command Details</a>, Up: <a href="index.html">Texinfo</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>