1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Octave: Function Headers</title>
<meta name="description" content="GNU Octave: Function Headers">
<meta name="keywords" content="GNU Octave: Function Headers">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Tips-and-Standards.html#Tips-and-Standards" rel="up" title="Tips and Standards">
<link href="Documentation-Tips.html#Documentation-Tips" rel="next" title="Documentation Tips">
<link href="Comment-Tips.html#Comment-Tips" rel="prev" title="Comment Tips">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {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}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en">
<a name="Function-Headers"></a>
<div class="header">
<p>
Next: <a href="Documentation-Tips.html#Documentation-Tips" accesskey="n" rel="next">Documentation Tips</a>, Previous: <a href="Comment-Tips.html#Comment-Tips" accesskey="p" rel="prev">Comment Tips</a>, Up: <a href="Tips-and-Standards.html#Tips-and-Standards" accesskey="u" rel="up">Tips and Standards</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Conventional-Headers-for-Octave-Functions"></a>
<h3 class="section">C.3 Conventional Headers for Octave Functions</h3>
<a name="index-header-comments"></a>
<p>Octave has conventions for using special comments in function files
to give information such as who wrote them. This section explains these
conventions.
</p>
<p>The top of the file should contain a copyright notice, followed by a
block of comments that can be used as the help text for the function.
Here is an example:
</p>
<div class="example">
<pre class="example">## Copyright (C) 1996, 1997, 2007 John W. Eaton
##
## This file is part of Octave.
##
## Octave is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public
## License as published by the Free Software Foundation;
## either version 3 of the License, or (at your option) any
## later version.
##
## Octave is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied
## warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
## PURPOSE. See the GNU General Public License for more
## details.
##
## You should have received a copy of the GNU General Public
## License along with Octave; see the file COPYING. If not,
## see <http://www.gnu.org/licenses/>.
## usage: [IN, OUT, PID] = popen2 (COMMAND, ARGS)
##
## Start a subprocess with two-way communication. COMMAND
## specifies the name of the command to start. ARGS is an
## array of strings containing options for COMMAND. IN and
## OUT are the file ids of the input and streams for the
## subprocess, and PID is the process id of the subprocess,
## or -1 if COMMAND could not be executed.
##
## Example:
##
## [in, out, pid] = popen2 ("sort", "-nr");
## fputs (in, "these\nare\nsome\nstrings\n");
## fclose (in);
## while (ischar (s = fgets (out)))
## fputs (stdout, s);
## endwhile
## fclose (out);
</pre></div>
<p>Octave uses the first block of comments in a function file that do not
appear to be a copyright notice as the help text for the file. For
Octave to recognize the first comment block as a copyright notice, it
must start with the word ‘Copyright’ after stripping the leading
comment characters.
</p>
<p>After the copyright notice and help text come several <em>header
comment</em> lines, each beginning with ‘<samp>## <var>header-name</var>:</samp>’. For
example,
</p>
<div class="example">
<pre class="example">## Author: jwe
## Keywords: subprocesses input-output
## Maintainer: jwe
</pre></div>
<p>Here is a table of the conventional possibilities for <var>header-name</var>:
</p>
<dl compact="compact">
<dt>‘<samp>Author</samp>’</dt>
<dd><p>This line states the name and net address of at least the principal
author of the library.
</p>
<div class="example">
<pre class="example">## Author: John W. Eaton <jwe@octave.org>
</pre></div>
</dd>
<dt>‘<samp>Maintainer</samp>’</dt>
<dd><p>This line should contain a single name/address as in the Author line, or
an address only, or the string ‘<samp>jwe</samp>’. If there is no maintainer
line, the person(s) in the Author field are presumed to be the
maintainers. The example above is mildly bogus because the maintainer
line is redundant.
</p>
<p>The idea behind the ‘<samp>Author</samp>’ and ‘<samp>Maintainer</samp>’ lines is to make
possible a function to “send mail to the maintainer” without
having to mine the name out by hand.
</p>
<p>Be sure to surround the network address with ‘<samp><…></samp>’ if
you include the person’s full name as well as the network address.
</p>
</dd>
<dt>‘<samp>Created</samp>’</dt>
<dd><p>This optional line gives the original creation date of the
file. For historical interest only.
</p>
</dd>
<dt>‘<samp>Version</samp>’</dt>
<dd><p>If you wish to record version numbers for the individual Octave program,
put them in this line.
</p>
</dd>
<dt>‘<samp>Adapted-By</samp>’</dt>
<dd><p>In this header line, place the name of the person who adapted the
library for installation (to make it fit the style conventions, for
example).
</p>
</dd>
<dt>‘<samp>Keywords</samp>’</dt>
<dd><p>This line lists keywords. Eventually, it will be used by an apropos
command to allow people will find your package when they’re looking for
things by topic area. To separate the keywords, you can use spaces,
commas, or both.
</p></dd>
</dl>
<p>Just about every Octave function ought to have the ‘<samp>Author</samp>’ and
‘<samp>Keywords</samp>’ header comment lines. Use the others if they are
appropriate. You can also put in header lines with other header
names—they have no standard meanings, so they can’t do any harm.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Documentation-Tips.html#Documentation-Tips" accesskey="n" rel="next">Documentation Tips</a>, Previous: <a href="Comment-Tips.html#Comment-Tips" accesskey="p" rel="prev">Comment Tips</a>, Up: <a href="Tips-and-Standards.html#Tips-and-Standards" accesskey="u" rel="up">Tips and Standards</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
