@ciao-lang/ts-ciao-interface
Version:
Simple Ciao interface for node.
7 lines • 13.6 kB
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>Generating and accessing manuals — 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="lpdoc_ref_manchanges.html">←</a><a class="lpdoc-navbutton" href="Writing.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>Generating and accessing manuals</strong></a></li></ul><hr></hr><em>ON THIS PAGE</em><ul><li><a href="#Basic usage">Basic usage</a></li><ul><li><a href="#Generating manuals">Generating manuals</a></li><li><a href="#Cleaning up documentation">Cleaning up documentation</a></li></ul><li><a href="#Accessing manuals">Accessing manuals</a></li><ul><li><a href="#Accessing info manuals">Accessing info manuals</a></li><li><a href="#Accessing man manuals">Accessing man manuals</a></li><li><a href="#Accessing Active Logic Documents">Accessing Active Logic Documents</a></li></ul></ul></div><div class="lpdoc-main"><div id=""><h1>Generating and accessing manuals</h1><a class="lpdoc-idx-anchor" href="lpdoc_ref_mansearch.html#Generating"></a>
<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>
<a class="lpdoc-idx-anchor" id="0" href="lpdoc_ref_mansearch.html#generating manuals"></a> <p>This section describes how to generate a manual (semi-)automatically from a set of source files using <a class="lpdoc-idx-anchor" id="1" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> and how to access it. See <a href="Writing.html">Writing documentation</a> for details about writing proper <a class="lpdoc-idx-anchor" id="2" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> documentation.<p><div id="Basic usage"><h2>Basic usage</h2> <p><a class="lpdoc-idx-anchor" id="3" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> can be used directly from the command line, the <a class="lpdoc-idx-anchor" id="4" href="lpdoc_ref_mansearch.html#Emacs"><tt>Emacs</tt></a> editor, or from <a class="lpdoc-idx-anchor" id="5" href="lpdoc_ref_mansearch.html#bundle">bundle</a> manifest files (see <a class="lpdoc-idx-anchor" id="6" href="lpdoc_ref_mansearch.html#bundles"><tt>bundles</tt></a> in the Ciao reference manual).<p>The following provides the basic command-line usage and the main command line options available when invoking <a class="lpdoc-idx-anchor" id="7" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a>. The basic usage is:<p><pre class="lpdoc-codeblock">
lpdoc [Options] Input</pre> <p>where <tt>Input</tt> is the input file (a module or a <a class="lpdoc-idx-anchor" id="8" href="lpdoc_ref_mansearch.html#documentation configuration"><em>documentation configuration</em></a> file), and (optional) options specifying the selected target format (<tt>-t Format</tt>, as described in <a class="lpdoc-idx-anchor" id="9" href="doccfg_doc.html#docformat/1"><tt>docformat/1</tt></a>), generation options <tt>--Name=Value</tt> (see <a class="lpdoc-idx-anchor" id="10" href="doccfg_doc.html"><tt>doccfg</tt></a> for a complete list), as well as options to view or clean the generated documentation files.<p>Use <tt>lpdoc --help</tt> to see a complete list of the available command line options.<p><div id="Generating manuals"><h3>Generating manuals</h3> <p>Manuals can be generated from single module or from a collection of modules specified in a <a class="lpdoc-idx-anchor" id="11" href="lpdoc_ref_mansearch.html#documentation configuration"><em>documentation configuration</em></a> file (as described in <a href="Writing.html">Writing documentation</a>) which defines how the documentation is structured, as well as options for its generation). For example, executing from the command line:<p><pre class="lpdoc-codeblock">
lpdoc file.pl</pre> <p>generates the documentation for <tt>file.pl</tt> in the default format (<tt>HTML</tt> for single modules or the default formats specified in <a class="lpdoc-idx-anchor" id="12" href="doccfg_doc.html#docformat/1"><tt>docformat/1</tt></a> for complex manuals), while the command:<p><pre class="lpdoc-codeblock">
lpdoc -t pdf file.pl</pre> <p>generates a PDF manual. The manuals generated will generally be written in the same directory as the input file, and they will have the same name but with the format as extension (i.e., in the example above it would be <tt>file.pdf</tt>). See <a class="lpdoc-idx-anchor" id="13" href="doccfg_doc.html#output_dir/1"><tt>output_dir/1</tt></a> and <a class="lpdoc-idx-anchor" id="14" href="doccfg_doc.html#output_name/1"><tt>output_name/1</tt></a> options to change the location or name of the output).<p>To enable incremental documentation generation, <a class="lpdoc-idx-anchor" id="15" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> maintains intermediate files in a directory named <tt>file.cachedoc/</tt>. See <span class="lpdoc-missing">Cleaning up</span> for cleanup commands to remove both the intermediate and target files.<p><a class="lpdoc-idx-anchor" id="16" href="lpdoc_ref_mansearch.html#Emacs, generating manuals from"></a> <a class="lpdoc-idx-anchor" id="17" href="lpdoc_ref_mansearch.html#generating from Emacs"></a> <a class="lpdoc-idx-anchor" id="18" href="lpdoc_ref_mansearch.html#Ciao"></a> <a class="lpdoc-idx-anchor" id="19" href="lpdoc_ref_mansearch.html#Prolog, Ciao"></a> <a class="lpdoc-idx-anchor" id="20" href="lpdoc_ref_mansearch.html#Emacs, LPdoc mode"></a> If you use the <a class="lpdoc-idx-anchor" id="21" href="lpdoc_ref_mansearch.html#Emacs"><tt>Emacs</tt></a> editor (highly recommended in all circumstances), then the simplest way to quickly generate a manual is by doing it from the <a class="lpdoc-idx-anchor" id="22" href="lpdoc_ref_mansearch.html#Ciao Emacs mode">Ciao Emacs mode</a> (this mode comes with the Ciao distribution and is automatically installed with Ciao). The Ciao Emacs mode provides menu- and keyboard-binding driven facilities for generating a standalone document with the documentation corresponding to the file in the buffer being visited by Emacs. This is specially useful while modifying the source of a file, in order to check the output that will be produced when incorporating this file into a larger document.<p></div><div id="Cleaning up documentation"><h3>Cleaning up documentation</h3> <p><a class="lpdoc-idx-anchor" id="23" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> can also take care of tidying up the output of the documentation generation and the intermediate documenation generation files, using the following options:<p><ul> <p><li><tt>--clean</tt>: deletes all intermediate files, but leaves the targets (i.e., the <tt>.pdf</tt>, <tt>.ascii</tt>, <tt>.html</tt>, etc. files), as well as all the generated <tt>.texic</tt> files.<p><li><tt>--distclean</tt>: deletes all intermediate files and the generated <tt>.texic</tt> files, leaving only the targets (i.e., the <tt>.pdf</tt>, <tt>.ascii</tt>, <tt>.html</tt>, etc. files). This is the option normally used when building software distributions in which the manuals come ready made in the distribution itself and will not need to be generated during installation.<p><li><tt>--docsclean</tt>: deletes all intermediate files and the generated targets, but leaves the <tt>.texic</tt> files. This option can be used in software distributions in which the manuals in the different formats will be generated during installation. This is generally more compact, but requires the presence of several tools, such as <tt>tex</tt>, <tt>Emacs</tt>, etc., in order to generate the manuals in the target formats during installation.<p><li><tt>--realclean</tt>: performs a complete cleanup, deleting also the .texic files, i.e., it typically leaves only the original source files. This is is the most compact, but requires the presence of the tools mentioned above, the source files from which the manuals are generated and <a class="lpdoc-idx-anchor" id="24" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> in order to regenerate the manuals in the target formats during installation.<p></ul> <p></div></div><div id="Accessing manuals"><h2>Accessing manuals</h2> <p>Once generated, the documentation can be viewed by opening the target output with an appriopriate viewer (e.g., Web browser for <tt>file.html/index.html</tt>, PDF viewer for <tt>file.pdf</tt>, etc.). For convenience <a class="lpdoc-idx-anchor" id="25" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> provides a generic view command:<p><pre class="lpdoc-codeblock">
lpdoc -t Format --view file.pl</pre> <p>which will open a default viewer application for the specified format and file.<p><div class="lpdoc-note"> For HTML documentation (specially when it is part of <a class="lpdoc-idx-anchor" id="26" href="lpdoc_ref_mansearch.html#bundle">bundle</a>s) we encourage the use of the <a class="lpdoc-idx-anchor" id="27" href="lpdoc_ref_mansearch.html#ciao-serve"><tt>ciao-serve</tt></a> command, which starts a local HTTP server and provides access to dynamic documentation parts (such as search, and advanced index options). </div> <p><div id="Accessing info manuals"><h3>Accessing info manuals</h3> <p>Generated <tt>.info</tt> files are meant to be viewed by the <a class="lpdoc-idx-anchor" id="28" href="lpdoc_ref_mansearch.html#Emacs"><tt>Emacs</tt></a> editor or by the standalone <a class="lpdoc-idx-anchor" id="29" href="lpdoc_ref_mansearch.html#info"><tt>info</tt></a> application, both publicly available from the GNU project sites. To view the a generated <a class="lpdoc-idx-anchor" id="30" href="lpdoc_ref_mansearch.html#info"><tt>info</tt></a> file from <a class="lpdoc-idx-anchor" id="31" href="lpdoc_ref_mansearch.html#Emacs"><tt>Emacs</tt></a> manually (i.e., before it is installed in a common area), type <tt>C-u M-x info</tt>. This will prompt for an info file name. <a class="lpdoc-idx-anchor" id="32" href="lpdoc_ref_mansearch.html#Emacs, accessing info files"></a> Input the name of the info file generated by <a class="lpdoc-idx-anchor" id="33" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> (<tt>main</tt><tt>.info</tt>) and <a class="lpdoc-idx-anchor" id="34" href="lpdoc_ref_mansearch.html#Emacs"><tt>Emacs</tt></a> will open the manual in info mode.<p>Automatic, direct on-line access to the information contained in the info file (e.g., going automatically to predicate descriptions by clicking on predicate names in programs in an <a class="lpdoc-idx-anchor" id="35" href="lpdoc_ref_mansearch.html#Emacs"><tt>Emacs</tt></a> buffer) can be easily implemented via existing <tt>.el</tt> packages such as <tt>info-look</tt>, written by Ralph Schleicher (<a href="mailto:rs@ralph-schleicher.de"><rs@ralph-schleicher.de></a>). Support for this package can be found in <a class="lpdoc-idx-anchor" id="36" href="lpdoc_ref_mansearch.html#info-look-ciao.el"><tt>info-look-ciao.el</tt></a> <p></div><div id="Accessing man manuals"><h3>Accessing man manuals</h3> <p>The <a class="lpdoc-idx-anchor" id="37" href="lpdoc_ref_mansearch.html#Unix"><tt>Unix</tt></a> <a class="lpdoc-idx-anchor" id="38" href="lpdoc_ref_mansearch.html#man"><tt>man</tt></a> format manuals generated by <a class="lpdoc-idx-anchor" id="39" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> can be viewed using the <a class="lpdoc-idx-anchor" id="40" href="lpdoc_ref_mansearch.html#Unix"><tt>Unix</tt></a> <a class="lpdoc-idx-anchor" id="41" href="lpdoc_ref_mansearch.html#man"><tt>man</tt></a> command. In order for <a class="lpdoc-idx-anchor" id="42" href="lpdoc_ref_mansearch.html#man"><tt>man</tt></a> to be able to locate the manuals, they should be copied to one of the subdirectories (e.g., <tt>/usr/local/man/manl</tt>) of one of the main man directories (in the previous case the main directory would be <tt>/usr/local/man</tt>). As usual, any directory can be used as as a man main directory, provided it is included in the environment variable <tt>MANPATH</tt>.<p></div><div id="Accessing Active Logic Documents"><h3>Accessing Active Logic Documents</h3> <p>The <tt>.html</tt> pages generated by <a class="lpdoc-idx-anchor" id="43" href="lpdoc_ref_mansearch.html#lpdoc"><tt>lpdoc</tt></a> can be conveniently accessed by users in their web browsers without requiring any installation. This facilitates easy sharing of <a class="lpdoc-idx-anchor" id="44" href="lpdoc_ref_mansearch.html#ALD"><tt>ALD</tt></a>s.</div></div><br/></div><div class="lpdoc-footer">Generated with LPdoc using Ciao</div></div><div class="lpdoc-clearer"></div></div></body></html>