Sophie: octave-doc-0:3.2.3-3mdv2010.0 i586

octave-doc-3.2.3-3mdv2010.0.i586.rpm

<html lang="en">
<head>
<title>Documentation and Test of Oct-Files - Untitled</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Untitled">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Oct_002dFiles.html#Oct_002dFiles" title="Oct-Files">
<link rel="prev" href="Exception-and-Error-Handling-in-Oct_002dFiles.html#Exception-and-Error-Handling-in-Oct_002dFiles" title="Exception and Error Handling in Oct-Files">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
</head>
<body>
<div class="node">
<a name="Documentation-and-Test-of-Oct-Files"></a>
<a name="Documentation-and-Test-of-Oct_002dFiles"></a>
<p>
Previous:&nbsp;<a rel="previous" accesskey="p" href="Exception-and-Error-Handling-in-Oct_002dFiles.html#Exception-and-Error-Handling-in-Oct_002dFiles">Exception and Error Handling in Oct-Files</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Oct_002dFiles.html#Oct_002dFiles">Oct-Files</a>
<hr>
</div>

<h4 class="subsection">A.1.13 Documentation and Test of Oct-Files</h4>

<p>The documentation of an oct-file is the fourth string parameter of the
<code>DEFUN_DLD</code><!-- /@w --> macro.  This string can be formatted in the same manner
as the help strings for user functions (<a href="Documentation-Tips.html#Documentation-Tips">Documentation Tips</a>),
however there are some issue that are particular to the formatting of
help strings within oct-files.

   <p>The major issue is that the help string will typically be longer than a
single line of text, and so the formatting of long help strings need to
be taken into account.  There are several manners in which to treat this
issue, but the most common is illustrated in the following example

<pre class="example">     DEFUN_DLD (do_what_i_want, args, nargout,
       "-*- texinfo -*-\n\
     @deftypefn {Function File} {} do_what_i_say (@var{n})\n\
     A function that does what the user actually wants rather\n\
     than what they requested.\n\
     @end deftypefn")
     {
     ...
     }
</pre>
   <p class="noindent">where, as can be seen, end line of text within the help string is
terminated by <code>\n\</code> which is an embedded new-line in the string
together with a C++ string continuation character.  Note that the final
<code>\</code> must be the last character on the line.

   <p>Octave also includes the ability to embed the test and demonstration
code for a function within the code itself (<a href="Test-and-Demo-Functions.html#Test-and-Demo-Functions">Test and Demo Functions</a>). 
This can be used from within oct-files (or in fact any file) with
certain provisos.  Firstly, the test and demo functions of Octave look
for a <code>%!</code> as the first characters on a new-line to identify test
and demonstration code.  This is equally a requirement for
oct-files.  Furthermore the test and demonstration code must be included
in a comment block of the compiled code to avoid it being interpreted by
the compiler.  Finally, the Octave test and demonstration code must have
access to the source code of the oct-file and not just the compiled code
as the tests are stripped from the compiled code.  An example in an
oct-file might be

<pre class="example">     /*
     
     %!error (sin())
     %!error (sin(1,1))
     %!assert (sin([1,2]),[sin(1),sin(2)])
     
     */
</pre>
   <!-- @node Application Programming Interface for Oct-Files -->
<!-- @subsection Application Programming Interface for Oct-Files -->
<!-- WRITE ME, using Coda section 1.3 as a starting point. -->
   </body></html>