# HG changeset patch
# User address@hidden
# Date 1203454755 0
# Node ID e4ac929fb3cefb4477e5fe80314bd239312ce41c
# Parent  bd2bd04e68caf5f52746265c87409a34d037294f
better documentation on the INDEX file format

diff -r bd2bd04e68ca -r e4ac929fb3ce doc/interpreter/package.txi
--- a/doc/interpreter/package.txi	Mon Feb 18 18:08:29 2008 +0100
+++ b/doc/interpreter/package.txi	Tue Feb 19 20:59:15 2008 +0000
@@ -449,6 +449,58 @@ Category Name 2
  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:
address@hidden
+fn = workaround description
address@hidden example
+
address@hidden
+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:
address@hidden
+fn = use <code>alternate expression</code>
address@hidden example
+
address@hidden
+the bold-italic is automatically suppressed.  You will need
+to use @code{<code>} even in references:
address@hidden
+fn = use <a href="someothersite.html"><code>fn</code></a>
address@hidden example
+
address@hidden
+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,
address@hidden
+eig(A,B) = use <f>qz</f>
address@hidden example
+
address@hidden
+Since sites may have many missing functions, you can define
+a macro rather than typing the same link over and again.
address@hidden
+$id = expansion
address@hidden example
+
address@hidden
+defines the macro id.  You can use @code{$id} anywhere in the
+description and it will be expanded.  For example,
address@hidden
+$TSA = see <a href="link_to_spctools">SPC Tools</a>
+arcov = $TSA <code>armcv</code>
address@hidden example
+
address@hidden
+id is any string of letters, numbers and @code{_}.
+
 @node PKG_ADD and PKG_DEL directives
 @subsection PKG_ADD and PKG_DEL directives