home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: Multimed / Multimed.zip / fest-141.zip / festival / lib / festdoc.scm < prev    next >
Text File  |  1999-06-20  |  8KB  |  179 lines
  1. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2. ;;;                                                                       ;;
  3. ;;;                Centre for Speech Technology Research                  ;;
  4. ;;;                     University of Edinburgh, UK                       ;;
  5. ;;;                       Copyright (c) 1996,1997                         ;;
  6. ;;;                        All Rights Reserved.                           ;;
  7. ;;;                                                                       ;;
  8. ;;;  Permission is hereby granted, free of charge, to use and distribute  ;;
  9. ;;;  this software and its documentation without restriction, including   ;;
  10. ;;;  without limitation the rights to use, copy, modify, merge, publish,  ;;
  11. ;;;  distribute, sublicense, and/or sell copies of this work, and to      ;;
  12. ;;;  permit persons to whom this work is furnished to do so, subject to   ;;
  13. ;;;  the following conditions:                                            ;;
  14. ;;;   1. The code must retain the above copyright notice, this list of    ;;
  15. ;;;      conditions and the following disclaimer.                         ;;
  16. ;;;   2. Any modifications must be clearly marked as such.                ;;
  17. ;;;   3. Original authors' names are not deleted.                         ;;
  18. ;;;   4. The authors' names are not used to endorse or promote products   ;;
  19. ;;;      derived from this software without specific prior written        ;;
  20. ;;;      permission.                                                      ;;
  21. ;;;                                                                       ;;
  22. ;;;  THE UNIVERSITY OF EDINBURGH AND THE CONTRIBUTORS TO THIS WORK        ;;
  23. ;;;  DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING      ;;
  24. ;;;  ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT   ;;
  25. ;;;  SHALL THE UNIVERSITY OF EDINBURGH NOR THE CONTRIBUTORS BE LIABLE     ;;
  26. ;;;  FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES    ;;
  27. ;;;  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN   ;;
  28. ;;;  AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,          ;;
  29. ;;;  ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF       ;;
  30. ;;;  THIS SOFTWARE.                                                       ;;
  31. ;;;                                                                       ;;
  32. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  33. ;;;                         Author: Alan W Black
  34. ;;;                         Date:   August 1996
  35. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  36. ;;;  Save documentation strings as texinfo files 
  37. ;;;
  38. ;;;  Finds all functions with documentation, and all variables with
  39. ;;;  documentation, sorts and dumps the information in doc/festfunc.texi
  40. ;;;  and doc/festvars.texi
  41. ;;;
  42. ;;;  The makefile in the doc directory runs the compiled festival binary and
  43. ;;;  causes these files to be created form the currently defined functions
  44. ;;;  and variables
  45. ;;;
  46. ;;;  Also provides function to extract manual section for documentation
  47. ;;;  string and send a url to Netscape to display it 
  48. ;;;
  49.  
  50. (define (make-doc)
  51. "(make-doc)
  52. Find function and variable document strings and save them in texinfo
  53. format to respective files."
  54.  (format t "Making function, feature and variable lists\n")
  55.  
  56.  ;; Need to ensure all library files are actually loaded if they contain
  57.  ;; funcstions/variables which have to be put in the manual
  58.  (require 'display)
  59.  (require 'mbrola)
  60.  (require 'tilt)
  61.  
  62.  (make-a-doc "festfunc.texi" 'function)
  63.  (make-a-doc "festfeat.texi" 'features)
  64.  (make-a-doc "festvars.texi" 'vars))
  65.  
  66. (define (make-a-doc outfile doclist)
  67. "(make-a-doc FILENAME DOCLIST)
  68. Make a texinfo document in FILENAME as a texinfo table, items are
  69. from DOCLIST.  DOCLIST names which doclist to use, it may be
  70. one of 'function, 'features or 'vars."
  71.   (let ((outfp (fopen outfile "wb")))
  72.    (format outfp "@table @code\n")
  73.    ;; Yes I am so lazy I'm not willing to write a sort function in Scheme
  74.    (sort-and-dump-docstrings doclist outfp)
  75.    (format outfp "@end table\n")
  76.    (fclose outfp)))
  77.  
  78. ;;;
  79. ;;;  Documentation string may refer to a section in the manual
  80. ;;;  If it does then we can automatically go to that section in the
  81. ;;;  menu using Netscape.
  82. ;;;
  83.  
  84. (defvar manual-browser "netscape"
  85. "manual-browser
  86. The Unix program name of your Netscape Navigator browser.
  87. [see Getting some help]")
  88.  
  89. (defvar manual-url 
  90.   (format nil "http://www.cstr.ed.ac.uk/projects/festival/manual-%s.%s.%s/"
  91.       (car festival_version_number)
  92.       (car (cdr festival_version_number))
  93.       (car (cdr (cdr festival_version_number))))
  94. "manual-url
  95. The default URL for the Festival Manual in html format.  You may
  96. reset this to a file://.../... type URL on you're local machine.
  97. [see Getting some help]")
  98.  
  99. ;;;  Paul got this idea from VM, the email system for emacs and
  100. ;;;  I found out how to do this from their code, thanks Kyle
  101.  
  102. (define (send-url-to-netscape url)
  103. "(send-url-to-netscape URL)
  104. Send given URL to netscape for display.  This is primarily used to 
  105. display parts of the manual referenced in documentation strings."
  106.   (system
  107.    (string-append
  108.     manual-browser
  109.     " -remote \"openURL( "
  110.     url
  111.     " )\" ")))
  112.  
  113. (define (lastline string)
  114. "(lastline STRING)
  115. Returns the part of the string which between the last newline and the 
  116. end of string."
  117.   (let ((ns (string-after string "\n")))
  118.     (if (string-equal ns "")
  119.     string
  120.     (lastline ns))))
  121.  
  122. (define (manual-sym symbol)
  123. "(manual-sym SYMBOL)
  124. Display the section in the manual that SYMBOL's docstring has
  125. identified as the most relevant.  The section is named on the
  126. last line of a documentation string with no newlines within it
  127. prefixed by \"[see \" with a \"]\" just immediately before the end
  128. of the documentation string.  The manual section name is translated to
  129. the section in the HTML version of the manual and a URL is
  130. and sent to Netscape for display.  [see Getting some help]"
  131. (let ((section (string-before (string-after 
  132.                    (lastline (eval (list 'doc symbol)))
  133.                    "[see ")
  134.                   "]")))
  135.   (cond
  136.    ((string-equal section "")
  137.     (eval (list 'doc symbol)))  ;; nothing there
  138.    (t
  139.     (manual section)))))
  140.  
  141. (define (manual section)
  142. "(manual SECTION)
  143. Display SECTION in the manual.  SECTION is a string identifying
  144. a manual section (it could be an initial substring.  If SECTION
  145. is nil or unspecifed then the Manual table of contents is displayed.
  146. This uses netscape to display the manual page so you must have that
  147. (use variable manual-browser to identify it) and the variable 
  148. manual-url pointing to a copy of the manual. [see Getting some help]"
  149. (let ((tmpfile (make_tmp_filename))
  150.       (manual-section))
  151.   (cond
  152.    ((string-matches section "\"")
  153.     (string-append "Invalid section reference containing quote: "
  154.            section "\n"))
  155.    ((not section)
  156.     (send-url-to-netscape (string-append manual-url "festival_toc.html")))
  157.    (t                            ;; find section in manual
  158.     (get_url (string-append manual-url "festival_toc.html") tmpfile)
  159.     (system
  160.      (string-append
  161.       "grep -i \"^<LI><A NAME.*" section "\" \"" tmpfile 
  162.       "\" | sed 's/^.*HREF=.//' | sed 's/.>.*$//' > \""
  163.       tmpfile ".out\""))
  164.     (set! manual-section (load (string-append tmpfile ".out") t))
  165.     (cond
  166.      ((not manual-section)
  167.       (string-append "No section called: " section))
  168.      (t
  169.       (send-url-to-netscape (string-append manual-url (car manual-section)))
  170.       (delete-file tmpfile)
  171.       (delete-file (string-append tmpfile ".out"))
  172.       "Sent manual reference url to netscape."))))))
  173.  
  174. (provide 'festdoc)
  175.  
  176.  
  177.  
  178.  
  179.