# HG changeset patch
# User carlo@guglielmo.local
# Date 1203465305 18000
# Node ID e27f8afa99e5a841cd535c3bcbcb9c31a62d799c
# Parent  507132cef358574f5f9c3264c234db33c9495aea
better documentation on the INDEX file format

diff -r 507132cef358 -r e27f8afa99e5 doc/ChangeLog
--- a/doc/ChangeLog	Tue Feb 19 18:51:48 2008 -0500
+++ b/doc/ChangeLog	Tue Feb 19 18:55:05 2008 -0500
@@ -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
diff -r 507132cef358 -r e27f8afa99e5 doc/interpreter/package.txi
--- a/doc/interpreter/package.txi	Tue Feb 19 18:51:48 2008 -0500
+++ b/doc/interpreter/package.txi	Tue Feb 19 18:55:05 2008 -0500
@@ -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