@ciao-lang/ts-ciao-interface

Version:

Simple Ciao interface for node.

23 lines (22 loc) • 28 kB

HTML

<!DOCTYPE HTML><html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><meta name="theme-color" content="#273f79"/><link rel="stylesheet" href="lpdoc.css" type="text/css"/><script type="text/javascript" src="lpdoc.js"></script><title>Writing documentation — The lpdoc Documentation Generator v3.5</title></head><body><div class="lpdoc-page fixleftbar"><a href="#" id="sidebar-toggle-button" class="lpdoc-navbutton"><span id="sidebar-button-arrow">☰</span></a><div id="sidebar" class="lpdoc-sidebar"><div style="height: 40px; margin-left: auto; margin-right: auto"><img src="lpdoc-logo-128_autofig.png" width=auto height=100%></div><div class="lpdoc-nav"><span class="lpdoc-on-right"><a class="lpdoc-navbutton" href="lpdoc_ref_man.html">↑</a><a class="lpdoc-navbutton" href="Generating.html">←</a><a class="lpdoc-navbutton" href="doccfg_doc.html">→</a><a class="lpdoc-navbutton" href="lpdoc_ref_mansearch.html">🔍</a></span><span><a href="lpdoc_ref_manfulltoc.html">TOC</a></span></div><hr></hr><ul class="lpdoc-itemize-sectpath"><li><a href="lpdoc_ref_man.html">The lpdoc Documentation Generator</a> »<br/> </li><li><a href=""><strong>Writing documentation</strong></a> ▾<ul><li><a href="doccfg_doc.html">Documentation configuration options</a></li><li><a href="doccfg_props.html">Admissible values for the documentation configuration options</a></li></ul></li></ul><hr></hr><em>ON THIS PAGE</em><ul><li><a href="#Documenting source files">Documenting source files</a></li><li><a href="#More complex manuals">More complex manuals</a></li><li><a href="#Advanced usage tips">Advanced usage tips</a></li><ul><li><a href="#Documenting libraries and/or applications">Documenting libraries and/or applications</a></li><li><a href="#Documenting files which are not modules">Documenting files which are not modules</a></li><li><a href="#Splitting large documents into parts">Splitting large documents into parts</a></li><li><a href="#Documenting reexported predicates">Documenting reexported predicates</a></li><li><a href="#Separating the documentation from the source file">Separating the documentation from the source file</a></li><li><a href="#Generating README files">Generating README files</a></li><li><a href="#Documenting version/patch changes">Documenting version/patch changes</a></li></ul><li><a href="#Troubleshooting with texinfo-based targets">Troubleshooting with texinfo-based targets</a></li></ul></div><div class="lpdoc-main"><div id=""><h1>Writing documentation</h1> <strong>Author(s):</strong> <a class="lpdoc-idx-anchor" id="Manuel Hermenegildo" href="lpdoc_ref_mansearch.html#Manuel Hermenegildo">Manuel Hermenegildo</a>, <a class="lpdoc-idx-anchor" id="Jose F. Morales" href="lpdoc_ref_mansearch.html#Jose F. Morales">Jose F. Morales</a>.<p> This section includes some details for writing proper documentation in <a class="lpdoc-idx-anchor" id="0" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a>, improving the layout of manuals, <a class="lpdoc-idx-anchor" id="1" href="lpdoc_ref_mansearch.html#usage tips">usage tips</a>, and <a class="lpdoc-idx-anchor" id="2" href="lpdoc_ref_mansearch.html#troubleshooting">troubleshooting</a> advice.<p><div id="Documenting source files"><h2>Documenting source files</h2> <p>While <a class="lpdoc-idx-anchor" id="3" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> can produce useful documentation from the interface of the source file, the quality of the documentation generated can be greatly enhanced by including within the program text:<p><ul> <p><li><em>assertions</em>, and<p><li><em>machine-readable comments</em>.<p></ul> <p><strong>Assertions</strong> are declarations which are included in the source program and provide the compiler with information regarding properties of the code. Typical assertions include type declarations, modes, computational properties (such as nonfailure or determinacy), many compiler directives (such as <a class="lpdoc-idx-anchor" id="4" href="lpdoc_ref_mansearch.html#dynamic/1"><tt>dynamic/1</tt></a>, <a class="lpdoc-idx-anchor" id="5" href="lpdoc_ref_mansearch.html#op/3"><tt>op/3</tt></a>, <a class="lpdoc-idx-anchor" id="6" href="lpdoc_ref_mansearch.html#meta_predicate/1"><tt>meta_predicate/1</tt></a>...), etc. When documenting a module, <a class="lpdoc-idx-anchor" id="7" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> will use the assertions associated with the module interface to construct a textual description of this interface. In principle, only the exported predicates are documented, although any predicate can be included in the documentation by explicitly requesting it (see the documentation for the <a class="lpdoc-idx-anchor" id="8" href="comments.html#doc/2"><tt>doc/2</tt></a> declaration). Judicious use of these assertions allows at the same time documenting the program code, documenting the external use of the module, and greatly improving program debugging and allowing program verification. The latter is possible because the assertions provide the compiler with information on the intended meaning or behaviour of the program (i.e., the specification) which can be checked at compile-time (by a suitable preprocessor/static analyzer) and/or at run-time (via checks inserted by a preprocessor). See <a href="assertions_doc.html">The Ciao assertion language</a> for more details.<p><strong>Machine-readable comments</strong> are also declarations included in the source program which contain additional information intended to be read by humans (i.e., this is an instantiation of the <a class="lpdoc-idx-anchor" id="9" href="lpdoc_ref_mansearch.html#literate programming"><em>literate programming</em></a> style of Knuth [<a class="lpdoc-idx-anchor" id="10" href="lpdoc_ref_manrefs.html#knuth-lit">Knu84</a>]). Typical such comments include title, author(s), summary, bugs, changelog, etc. Judicious use of these comments allows enhancing at the same time the documentation of the program text and the manuals generated from it. See <a href="comments.html">Documentation mark-up language and doc declarations</a> for more details. These declarations can also be writtten in wiki (<a class="lpdoc-idx-anchor" id="11" href="lpdoc_ref_mansearch.html#mark-down"><em>mark-down</em></a>) style -- see <a class="lpdoc-idx-anchor" id="12" href="doccomments_doc.html"><tt>doccomments</tt></a>.<p><a class="lpdoc-idx-anchor" id="13" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> requires these <strong>assertions</strong> and <strong>machine-readable</strong> comments to be written using the <a class="lpdoc-idx-anchor" id="14" href="lpdoc_ref_mansearch.html#Ciao"><tt>Ciao</tt></a> <em>assertion language</em>. While <a class="lpdoc-idx-anchor" id="15" href="lpdoc_ref_mansearch.html#Ciao"><tt>Ciao</tt></a> has core support for this language, it is however quite straightforward in most Prolog and (C)LP systems to define a library with dummy declarations so that the assertions and comments meant for <a class="lpdoc-idx-anchor" id="16" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> are simply ignored by the compiler, making it possible to compile programs documented using assertions and comments in such systems and at the same time generate documentation using <a class="lpdoc-idx-anchor" id="17" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> (as well as making other uses of the assertions such as checking tehm statically and/or dynamically).<p><p><p></div><div id="More complex manuals"><h2>More complex manuals</h2> <p>Writing and generating more complex manuals involves writing a <a class="lpdoc-idx-anchor" id="18" href="lpdoc_ref_mansearch.html#documentation configuration"><em>documentation configuration</em></a> (<a class="lpdoc-idx-anchor" id="19" href="doccfg_doc.html"><tt>doccfg</tt></a>) file (e.g, <tt>SETTINGS.pl</tt>) with this basic structure:<p><pre class="lpdoc-codeblock"> :- module(_, [], [doccfg]). doc_structure := '<MAIN MODULE>'-[ '<COMP1>', ... '<COMPn>' ].</pre> <p>The first line indicates that this is a module implementing a <a class="lpdoc-idx-anchor" id="20" href="doccfg_doc.html"><tt>doccfg</tt></a>. The second line defines through <a class="lpdoc-idx-anchor" id="21" href="doccfg_doc.html#doc_structure/1"><tt>doc_structure/1</tt></a> the <a class="lpdoc-idx-anchor" id="22" href="lpdoc_ref_mansearch.html#document structure"><em>document structure</em></a>, specifying in a tree the main file and (optional) component files. When documenting complex manuals with more than one source files, the main file is the one that will provide the general title, author, date, summary, and the introduction. The component files will appear as separate chapters.<p>Any option not directly specified will use the default values indicated in <a class="lpdoc-idx-anchor" id="23" href="doccfg_doc.html"><tt>doccfg</tt></a>. You may however want to change several of these:<p><ul> <p><li><a class="lpdoc-idx-anchor" id="24" href="doccfg_doc.html#filepath/1"><tt>filepath/1</tt></a>: option to include all additional directories where the files to be documented can be found (<a class="lpdoc-idx-anchor" id="25" href="lpdoc_ref_mansearch.html#alias path">alias path</a>s for libraries are included automatically).<p><li><a class="lpdoc-idx-anchor" id="26" href="doccfg_doc.html#doc_mainopts/1"><tt>doc_mainopts/1</tt></a>: control what is included in the documentation for the main file.<p><li><a class="lpdoc-idx-anchor" id="27" href="doccfg_doc.html#doc_compopts/1"><tt>doc_compopts/1</tt></a>: sets options for the component files.<p><li><a class="lpdoc-idx-anchor" id="28" href="doccfg_doc.html#docformat/1"><tt>docformat/1</tt></a>: determines the set of formats (<tt>pdf</tt>, <tt>ascii</tt>, <tt>html</tt>, <tt>info</tt>, <tt>manl</tt>, ...) in which the documentation should be generated by default.<p><li><a class="lpdoc-idx-anchor" id="29" href="doccfg_doc.html#output_name/1"><tt>output_name/1</tt></a>: determines the base file name of the main documents generated by <a class="lpdoc-idx-anchor" id="30" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a>.<p><li><a class="lpdoc-idx-anchor" id="31" href="doccfg_doc.html#index/1"><tt>index/1</tt></a>: determines the list of indices to be included at the end of the document.<p><li><a class="lpdoc-idx-anchor" id="32" href="doccfg_doc.html#bibfile/1"><tt>bibfile/1</tt></a>: determines a list of <a class="lpdoc-idx-anchor" id="33" href="lpdoc_ref_mansearch.html#.bib files"><em>.bib files</em></a> containing <a class="lpdoc-idx-anchor" id="34" href="lpdoc_ref_mansearch.html#bibliographic entries"><em>bibliographic entries</em></a> for <a class="lpdoc-idx-anchor" id="35" href="lpdoc_ref_mansearch.html#using citations">using citations</a>.<p><li><a class="lpdoc-idx-anchor" id="36" href="doccfg_doc.html#startpage/1"><tt>startpage/1</tt></a>: allows changing the page number of the first page of the manual.<p><li><a class="lpdoc-idx-anchor" id="37" href="doccfg_doc.html#papertype/1"><tt>papertype/1</tt></a>: allows select several paper sizes for the printable outputs (<tt>pdf</tt>).<p></ul> <p>See <a class="lpdoc-idx-anchor" id="38" href="doccfg_doc.html"><tt>doccfg</tt></a> for other options.<p></div><div id="Advanced usage tips"><h2>Advanced usage tips</h2> <a class="lpdoc-idx-anchor" id="39" href="lpdoc_ref_mansearch.html#usage tips"></a> <p>This section contains additional suggestions on the use of <a class="lpdoc-idx-anchor" id="40" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a>.<p><div id="Documenting libraries and/or applications"><h3>Documenting libraries and/or applications</h3> <p>For each a <tt>.pl</tt> file, <a class="lpdoc-idx-anchor" id="41" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> tries to determine whether it is a <a class="lpdoc-idx-anchor" id="42" href="lpdoc_ref_mansearch.html#library"><em>library</em></a> or an <a class="lpdoc-idx-anchor" id="43" href="lpdoc_ref_mansearch.html#application"><em>application</em></a> (exporting <a class="lpdoc-idx-anchor" id="44" href="lpdoc_ref_mansearch.html#main/0"><tt>main/0</tt></a> or <a class="lpdoc-idx-anchor" id="45" href="lpdoc_ref_mansearch.html#main/1"><tt>main/1</tt></a>), and documents it accordingly.<p>The generated documentation for libraries will contain information on the interface (e.g., the predicates exported by the file, the name of the module and usage if it is a module, etc.), in addition to any other machine readable comments included in the file. The interface information is omitted in for applications by default.<p>Any combination of libraries and/or main files of applications can be used arbitrarily as components or main files of a <a class="lpdoc-idx-anchor" id="46" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> manual. Some typical combinations are:<p><ul> <p><li><em>Main file is a library, no components:</em> A manual of a simple library, which appears externally as a single module. The manual describes the purpose of the library and its interface.<p><li><em>Main file is an application, no components:</em> A manual of a simple application.<p><li><em>Main file is a library, components are also libraries:</em> This can be used for example for generating an <a class="lpdoc-idx-anchor" id="47" href="lpdoc_ref_mansearch.html#internals manual">internals manual</a> of a library. The main file describes the purpose and use of the library, while the components describe the internal modules of the library.<p><li><em>Main file is an application, components are libraries:</em> This can be used similarly for generating an <a class="lpdoc-idx-anchor" id="48" href="lpdoc_ref_mansearch.html#internals manual">internals manual</a> of an application. The main file describes the purpose and use of the application, while the components describe the internal modules which compose the application.<p><li><em>Main file is a (pseudo-)application, components are libraries:</em> A manual of a complex library made up of smaller libraries (for example, the <a class="lpdoc-idx-anchor" id="49" href="lpdoc_ref_mansearch.html#Prolog"><tt>Prolog</tt></a> library). The (pseudo-)application file contains the introductory material (title, version, etc.). Each chapter describes a particular library.<p><li><em>Main file is a (pseudo-)application, components are applications:</em> This can be used to generate a manual of a set of applications (e.g., a set of utilities). The (pseudo-)application file contains the introductory material (title, version, etc.). Each chapter describes a particular component application.<p></ul> <p></div><div id="Documenting files which are not modules"><h3>Documenting files which are not modules</h3> <p>Sometimes it is difficult for <a class="lpdoc-idx-anchor" id="50" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> to distinguish <a class="lpdoc-idx-anchor" id="51" href="lpdoc_ref_mansearch.html#include files">include files</a> and Ciao <a class="lpdoc-idx-anchor" id="52" href="lpdoc_ref_mansearch.html#packages">packages</a> from normal <em>user</em> files (i.e., normal code files but which are not modules). The distinction is important because the former are quite different in their form of use (they are loaded via <a class="lpdoc-idx-anchor" id="53" href="lpdoc_ref_mansearch.html#include/1"><tt>include/1</tt></a> or <a class="lpdoc-idx-anchor" id="54" href="lpdoc_ref_mansearch.html#use_package/1"><tt>use_package/1</tt></a> declarations instead of <a class="lpdoc-idx-anchor" id="55" href="lpdoc_ref_mansearch.html#ensure_loaded/1"><tt>ensure_loaded/1</tt></a>) and effect (since they are included, they 'export' operators, declarations, etc.), and should typically be documented differently. There is a special <a class="lpdoc-idx-anchor" id="56" href="comments.html#doc/2"><tt>doc/2</tt></a> declaration (<tt>:- doc(filetype,...).</tt>) which provides a way of defining the intended use of the file. This declaration is normally not needed in modules, include files, or packages, but should be added in user files (i.e., those meant to be loaded using <a class="lpdoc-idx-anchor" id="57" href="lpdoc_ref_mansearch.html#ensure_loaded/1"><tt>ensure_loaded/1</tt></a>). Adding this declaration will, for example, avoid spurious documentation of the declarations in the <a class="lpdoc-idx-anchor" id="58" href="assertions_doc.html"><tt>assertions</tt></a> package themselves when this package is included in a user file.<p></div><div id="Splitting large documents into parts"><h3>Splitting large documents into parts</h3> <p>In large documents, it is sometimes convenient to build a super-structure of parts, each of which groups several components. There is a special value of the second argument of the <tt>:- doc(filetype,...).</tt> declaration mentioned above designed for this purpose. The special <em>filetype</em> value <tt>part</tt> can be used to flag that the file in which it appears should be documented as the start of one of the major <a class="lpdoc-idx-anchor" id="59" href="lpdoc_ref_mansearch.html#parts in a large document"><em>parts in a large document</em></a>. In order to introduce such a part, a <tt>.pl</tt> file with a declaration <tt>:- doc(filetype,part).</tt> should be inserted in the sequence of files that make up the <tt>components</tt> variable of the <a class="lpdoc-idx-anchor" id="60" href="lpdoc_ref_mansearch.html#documentation configuration"><em>documentation configuration</em></a> file at each point in which a major part starts. The <tt>:- doc(title,"...").</tt> declaration of this file will be used as the part title, and the <tt>:- doc(module,"...").</tt> declaration text will be used as the introduction to the part.<p></div><div id="Documenting reexported predicates"><h3>Documenting reexported predicates</h3> <p>Reexported predicates, i.e., predicates which are exported by a module <tt>m1</tt> but defined in another module <tt>m2</tt> which is used by <tt>m1</tt>, are normally not documented in the original module, but instead a simple reference is included to the module in which it is defined. This can be changed, so that the documentation is included in the original module, by using a <a class="lpdoc-idx-anchor" id="61" href="comments.html#doc/2"><tt>doc/2</tt></a> declaration with <tt>doinclude</tt> in the first argument (see the <a class="lpdoc-idx-anchor" id="62" href="comments.html"><tt>comments</tt></a> library). This is often useful when documenting a library made of several components. For a simple user's manual, it is often sufficient to include in the <a class="lpdoc-idx-anchor" id="63" href="lpdoc_ref_mansearch.html#documentation configuration"><em>documentation configuration</em></a> file the principal module, which is the one which users will do a <a class="lpdoc-idx-anchor" id="64" href="lpdoc_ref_mansearch.html#use_module/1"><tt>use_module/1</tt></a> of, in the manual. This module typically exports or reexports all the predicates which define the library's user interface. Note, however, that currently, due to limitations in the implementation, only the comments inside <a class="lpdoc-idx-anchor" id="65" href="lpdoc_ref_mansearch.html#assertions">assertions</a> (but not those in <a class="lpdoc-idx-anchor" id="66" href="comments.html#doc/2"><tt>doc/2</tt></a> declarations) are included for reexported predicates.<p></div><div id="Separating the documentation from the source file"><h3>Separating the documentation from the source file</h3> <p>Sometimes one would not like to include long introductory comments in the module itself but would rather have them in a different file. This can be done quite simply by using the @include command. For example, the following declaration:<p><pre class="lpdoc-codeblock"> :- doc(module,"@@include{Intro.lpdoc}").</pre> <p>will include the contents of the file <tt>Intro.lpdoc</tt> as the module description.<p>Alternatively, sometimes one may want to generate the documentation from a completely different file. Assuming that the original module is <tt>mod.pl</tt>, this can be done by calling the module containing the documentation <tt>mod_doc.pl</tt>. This <tt>mod_doc.pl</tt> file is the one that will be included in the <a class="lpdoc-idx-anchor" id="67" href="lpdoc_ref_mansearch.html#documentation configuration"><em>documentation configuration</em></a> file, instead of <tt>mod.pl</tt>. <a class="lpdoc-idx-anchor" id="68" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> recognizes and treats such <tt>_doc</tt> files specially so that the name without the <tt>_doc</tt> part is used in the different parts of the documentation, in the same way as if the documentation were placed in file <tt>mod</tt>.<p></div><div id="Generating README files"><h3>Generating README files</h3> <p>Using <a class="lpdoc-idx-anchor" id="69" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> it is often possible to use a common source for documentation text which should appear in several places. For example, assume a file <a class="lpdoc-idx-anchor" id="70" href="lpdoc_ref_mansearch.html#INSTALLATION.lpdoc"><tt>INSTALLATION.lpdoc</tt></a> contains text describing an application. This text can be included in a section of the main file documentation as follows:<p><pre class="lpdoc-codeblock"> :- doc(module," ... @@section{Installation instructions} @@include{INSTALLATION.lpdoc} ... ").</pre> <p>At the same time, this text can be used to generate a nicely formatted <tt>INSTALLATION</tt> file in ascii, which can perhaps be included in the top level of the source directory of the application. To this end, an <tt>INSTALL.pl</tt> file as follows can be constructed:<p><pre class="lpdoc-codeblock"> :- use_package([assertions]). :- doc(filetype, application). %% forces file to be documented as an application :- doc(title,"Installation instructions"). :- doc(module,"@@include{INSTALLATION.lpdoc}").</pre> <p>Then, the ascii <tt>INSTALLATION</tt> file can be generated by simply running <tt>lpdoc -t ascii INSTALLATION.pl</tt>.<p></div><div id="Documenting version/patch changes"><h3>Documenting version/patch changes</h3> <p><a class="lpdoc-idx-anchor" id="71" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> supports version comments (<tt>:- doc(version(...), "...").</tt>) to document the list of version/patch changes (<a class="lpdoc-idx-anchor" id="72" href="lpdoc_ref_mansearch.html#CHANGELOG">CHANGELOG</a>s) of a particular software. These can be included as part of the manual or translated to plain text (<a href="#Generating README files">Generating README files</a>).<p>Version numbers in comments specify a <em>major</em>, <em>minor</em>, and <em>patch</em> number. As a common convention, <em>patch</em> changes (e.g.,1.1#2 to 1.1#3) are reserved for internal changes, such as bug fixes and backward-compatible changes whose detailed description may not be relevant for the user. More general changes (including the summary of internal changes when appropriate) are documented with changes in the <em>major</em> and <em>minor</em> numbers (e.g., 1.1#2 to 1.2#0).<p>Selecting the appropriate options in <a class="lpdoc-idx-anchor" id="73" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> (e.g., <tt>no_patch</tt> in <tt>doc_mainopts</tt>), it is possible to include in the manual the version changes but not the patch changes (which might on the other hand be included in an <a class="lpdoc-idx-anchor" id="74" href="lpdoc_ref_mansearch.html#internals manual"><em>internals manual</em></a>). This is useful, for example, to document separatelly internal from general changes.<p></div></div><div id="Troubleshooting with texinfo-based targets"><h2>Troubleshooting with texinfo-based targets</h2> <p>Due to limitations in <a class="lpdoc-idx-anchor" id="75" href="lpdoc_ref_mansearch.html#texinfo"><tt>texinfo</tt></a> and GNU info, it is sometimes a little tricky to get things to work uniformly for all formats. The following recommendations are intended to help in achieving useful manuals in texinfo-based formats, as well as some common errors and their usual fix:<p><ul> <li>The GNU info format requires all <em>nodes</em> (chapters, sections, etc.) to have different names. This is ensured by <a class="lpdoc-idx-anchor" id="76" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> for the automatically generated sections (by appending the module or file name to all section headings). However, care must be taken when writing section names manually to make them different. For example, use ``lpdoc usage'' instead of simply ``Usage'', which is much more likely to be used as a section name in another file being documented.<p><li>Also due to a limitation of the <a class="lpdoc-idx-anchor" id="77" href="lpdoc_ref_mansearch.html#info"><tt>info</tt></a> format, do not use <tt>:</tt> or <tt>,</tt> or <tt>-</tt><tt>-</tt> in section, chapter, etc. headings.<p><li>The character ``<tt>_</tt>'' in names may sometimes give problems in indices, since current versions of <a class="lpdoc-idx-anchor" id="78" href="lpdoc_ref_mansearch.html#texinfo"><tt>texinfo</tt></a> do not always handle it correctly.<p><li>Messages of the type: <pre class="lpdoc-codeblock"> ! No room for a new @write .</pre> while converting from <tt>.texi</tt> to <tt>.dvi</tt> (i.e., while running <a class="lpdoc-idx-anchor" id="79" href="lpdoc_ref_mansearch.html#tex"><tt>tex</tt></a>). These messages are <a class="lpdoc-idx-anchor" id="80" href="lpdoc_ref_mansearch.html#tex"><tt>tex</tt></a>'s way of saying that an internal area (typically for an index) is full. This is normally because more indices were selected in the <tt>index/1</tt> option of the <a class="lpdoc-idx-anchor" id="81" href="lpdoc_ref_mansearch.html#documentation configuration"><em>documentation configuration</em></a> file than the maximum number supported by the installed version of <a class="lpdoc-idx-anchor" id="82" href="lpdoc_ref_mansearch.html#tex"><tt>tex</tt></a>/<a class="lpdoc-idx-anchor" id="83" href="lpdoc_ref_mansearch.html#texinfo"><tt>texinfo</tt></a> installations, as mentioned in <a href="Generating.html">Generating and accessing manuals</a>. The easiest fix is to reduce the number of indices generated. Alternatively, it may be possible to recompile your local <a class="lpdoc-idx-anchor" id="84" href="lpdoc_ref_mansearch.html#tex"><tt>tex</tt></a>/<a class="lpdoc-idx-anchor" id="85" href="lpdoc_ref_mansearch.html#texinfo"><tt>texinfo</tt></a> installation with a higher number of indices.<p><li>Missing links in <a class="lpdoc-idx-anchor" id="86" href="lpdoc_ref_mansearch.html#info"><tt>info</tt></a> files (a section which exists in the printed document cannot be accessed in the on-line document) can be due to the presence of a colon (<tt>:</tt>), a comma (<tt>,</tt>), a double dash (<tt>--</tt>), or other such separators in a section name. Due to limitations of <a class="lpdoc-idx-anchor" id="87" href="lpdoc_ref_mansearch.html#info"><tt>info</tt></a> section names cannot contain these symbols.<p><li>Menu listings in <a class="lpdoc-idx-anchor" id="88" href="lpdoc_ref_mansearch.html#info"><tt>info</tt></a> which <em>do not work</em> (i.e., the menu listings are there, but they cannot be followed): see if they are indented. In that case it is due to an <tt>itemize</tt> or <tt>enumerate</tt> which was not closed.<p></ul></div><br/><h2>Subparts</h2><ul><li><a href="doccfg_doc.html">Documentation configuration options</a></li><li><a href="doccfg_props.html">Admissible values for the documentation configuration options</a></li></ul></div><div class="lpdoc-footer">Generated with LPdoc using Ciao</div></div><div class="lpdoc-clearer"></div></div></body></html>