Mercurial > hg > octave-avbm
changeset 7496:e27f8afa99e5
better documentation on the INDEX file format
author | carlo@guglielmo.local |
---|---|
date | Tue, 19 Feb 2008 18:55:05 -0500 |
parents | 507132cef358 |
children | bb7cc90cdc5e |
files | doc/ChangeLog doc/interpreter/package.txi |
diffstat | 2 files changed, 62 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2008-02-19 Carlo de Falco <kingcrimson@tiscali.it> + + * interpreter/package.txi: Improve INDEX file documentation. + 2008-01-18 Ben Abbott <bpabbott@mac.com> * interpreter/intro.txi: Replaced reference to deprecated
--- a/doc/interpreter/package.txi +++ b/doc/interpreter/package.txi @@ -449,6 +449,64 @@ function2 function5 @end example +If you wish to refer to a function that users might expect +to find in your package but is not there, providing a work around or +ponting out that the function is available elsewhere, you can use: + +@example +fn = workaround description +@end example + +@noindent +This workaround description will not appear when listing functions in the +package with @code{pkg describe} but they will be published +in the html documentation online. +Workaround descriptions can use any html markup, but +keep in mind that it will be enclosed in a bold-italic environment. +For the special case of: + +@example +fn = use <code>alternate expression</code> +@end example + +@noindent +the bold-italic is automatically suppressed. You will need +to use @code{<code>} even in references: + +@example +fn = use <a href="someothersite.html"><code>fn</code></a> +@end example + +@noindent +Sometimes functions are only partially compatible, in which +case you can list the non-compatible cases separately. To +refer to another function in the package, use @code{<f>fn</f>}. +For example, + +@example +eig (a, b) = use <f>qz</f> +@end example + +@noindent +Since sites may have many missing functions, you can define +a macro rather than typing the same link over and again. + +@example +$id = expansion +@end example + +@noindent +defines the macro id. You can use @code{$id} anywhere in the +description and it will be expanded. For example, + +@example +$TSA = see <a href="link_to_spctools">SPC Tools</a> +arcov = $TSA <code>armcv</code> +@end example + +@noindent +id is any string of letters, numbers and @code{_}. + @node PKG_ADD and PKG_DEL directives @subsection PKG_ADD and PKG_DEL directives