Editing Help text style guide
Jump to navigation
Jump to search
The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then publish the changes below to finish undoing the edit.
Latest revision | Your text | ||
Line 1: | Line 1: | ||
Functions should have help text so that people know how to use it. | |||
= TexInfo = | |||
This is the prefered format for help text. There is also a comprehensive [http://www.gnu.org/software/texinfo/manual/texinfo/html_node/index.html TexInfo manual]. | |||
== Octave specific macros == | |||
=== seealso === | |||
Do not use this macro empty as it will create problems with the {{forge|generate_html}} package. | Do not use this macro empty as it will create problems with the {{forge|generate_html}} package. | ||
=== deftypefn === | |||
==== | == Formatting == | ||
=== Verbatim === | |||
Use this to include literal text. Special useful to insert formulas. | |||
{{Code||<pre> | {{Code||<pre> | ||
Line 145: | Line 21: | ||
</pre>}} | </pre>}} | ||
=== Examples === | |||
Do not use the example environment to insert formulas, consider using {{Codeline|@verbatim}} instead | |||
== Special inserts == | |||
=== Escape characters === | |||
To escape characters in TexInfo, use the character {{Codeline|@}}. Only the characters '''@''', '''{''' and '''}''' need to be escaped. | To escape characters in TexInfo, use the character {{Codeline|@}}. Only the characters '''@''', '''{''' and '''}''' need to be escaped. | ||
Line 177: | Line 35: | ||
In certain contexts (such as {{Codeline|@acronym}} or {{Codeline|@xref}}), commas may need to be escaped. In such situations, use {{Codeline|<nowiki>@comma{}</nowiki>}}. | In certain contexts (such as {{Codeline|@acronym}} or {{Codeline|@xref}}), commas may need to be escaped. In such situations, use {{Codeline|<nowiki>@comma{}</nowiki>}}. | ||
=== Ellipsis (...) === | |||
Ellipsis are frequently used in octave help text, | Ellipsis are frequently used in octave help text, specially when defining a function API. Use the {{Codeline|<nowiki>@dots{}</nowiki>}} rather than three dots. | ||
{{Code||<pre> | {{Code||<pre> | ||
@deftypefn {Function File} {} imhist (@var{I}) | |||
@deftypefnx {Function File} {[@var{counts}, @var{x}] =} imhist (@dots{}) | |||
</pre>}} | </pre>}} | ||