[Emacs-diffs] Changes to emacs/man/idlwave.texi

[Richard M . Stallman]

Index: emacs/man/idlwave.texi
diff -c emacs/man/idlwave.texi:1.31 emacs/man/idlwave.texi:1.32
*** emacs/man/idlwave.texi:1.31 Fri Nov 26 12:04:57 2004
--- emacs/man/idlwave.texi      Thu Mar 24 14:00:41 2005
***************
*** 19,25 ****
  @set AUTHOR-EMAIL jdsmith@@as.arizona.edu
  @set MAINTAINER J.D. Smith
  @set MAINTAINER-EMAIL jdsmith@@as.arizona.edu
- @set IDLWAVE-HOMEPAGE http://idlwave.org/
  @c %**end of header
  @finalout
  
--- 19,24 ----
***************
*** 101,107 ****
  * Getting Started::             Tutorial
  * The IDLWAVE Major Mode::      The mode for editing IDL programs
  * The IDLWAVE Shell::           The mode for running IDL as an inferior 
program
- * Installation::                How to Install or Upgrade               
  * Acknowledgements::            Who did what
  * Sources of Routine Info::     How does IDLWAVE know about routine XYZ     
  * HTML Help Browser Tips::      
--- 100,105 ----
***************
*** 180,190 ****
  * Walking the Calling Stack::   
  * Electric Debug Mode::         
  
- Installation
- 
- * Installing IDLWAVE::          How to install the distribution
- * Installing Online Help::      Where to get the additional files needed
- 
  Sources of Routine Info
  
  * Routine Definitions::         Where IDL Routines are defined.
--- 178,183 ----
***************
*** 204,211 ****
  @node Introduction, IDLWAVE in a Nutshell, Top, Top
  @chapter Introduction
  @cindex Introduction
- @cindex CORBA (Common Object Request Broker Architecture)
- @cindex Interface Definition Language
  @cindex Interactive Data Language
  @cindex cc-mode.el
  @cindex @file{idl.el}
--- 197,202 ----
***************
*** 213,226 ****
  @cindex Feature overview
  
  IDLWAVE is a package which supports editing source files written in
! the Interactive Data Language (address@hidden is a registered
! trademark of Research Systems, Inc., a Kodak Company}), and running
  IDL as an inferior address@hidden that this package has nothing
  to do with the Interface Definition Language, part of the Common
  Object Request Broker Architecture (CORBA)address@hidden can also
  be used for editing source files for the related WAVE/CL language, but
  with only limited support.}.  It is a feature-rich replacement for the
! IDLDE development environment bundled with IDL, and uses the full
  power of Emacs to make editing and running IDL programs easier,
  quicker, and more structured.
  
--- 204,216 ----
  @cindex Feature overview
  
  IDLWAVE is a package which supports editing source files written in
! the Interactive Data Language, and running
  IDL as an inferior address@hidden that this package has nothing
  to do with the Interface Definition Language, part of the Common
  Object Request Broker Architecture (CORBA)address@hidden can also
  be used for editing source files for the related WAVE/CL language, but
  with only limited support.}.  It is a feature-rich replacement for the
! IDLDE development environment included with IDL, and uses the full
  power of Emacs to make editing and running IDL programs easier,
  quicker, and more structured.
  
***************
*** 421,431 ****
  shoulder of your nearest IDLWAVE guru for a few days.
  
  It is assumed that you have access to Emacs or XEmacs with the full
! IDLWAVE package including online help (@pxref{Installation}).  We also
! assume that you are familiar with Emacs and can read the nomenclature of
! key presses in Emacs (in particular, @kbd{C} stands for @key{CONTROL}
! and @kbd{M} for @key{META} (often the @key{ALT} key carries this
! functionality)).
  
  Open a new source file by typing:
  
--- 411,420 ----
  shoulder of your nearest IDLWAVE guru for a few days.
  
  It is assumed that you have access to Emacs or XEmacs with the full
! IDLWAVE package including online help.  We also assume that you are
! familiar with Emacs and can read the nomenclature of key presses in
! Emacs (in particular, @kbd{C} stands for @key{CONTROL} and @kbd{M} for
! @key{META} (often the @key{ALT} key carries this functionality)).
  
  Open a new source file by typing:
  
***************
*** 612,620 ****
  
  You likely have your own indentation preferences for IDL code.  For
  example, some like to indent the main block of an IDL program from the
! margin, different from the conventions used by RSI, and use only 3
! spaces as indentation between @code{BEGIN} and @code{END}.  Try the
! following lines in @file{.emacs}:
  
  @lisp
  (setq idlwave-main-block-indent 2)
--- 601,608 ----
  
  You likely have your own indentation preferences for IDL code.  For
  example, some like to indent the main block of an IDL program from the
! margin and use only 3 spaces as indentation between @code{BEGIN} and
! @code{END}.  Try the following lines in @file{.emacs}:
  
  @lisp
  (setq idlwave-main-block-indent 2)
***************
*** 1279,1297 ****
  @cindex Online Help, Installation
  @cindex Speed, of online help
  
! For IDL system routines, RSI provides extensive documentation.
! IDLWAVE can access an HTML version of this documentation very quickly
! and accurately.  This is @emph{much} faster than using the IDL online
! help application, because IDLWAVE usually gets you to the right place
! in the documentation directly --- e.g. a specific keyword of a routine
! --- without any additional browsing and scrolling.  For this online
! help to work, an HTML version of the IDL documentation, which is not
! part of the standalone IDLWAVE distribution, is required.  The
! necessary files can be downloaded from @address@hidden,
! the maintainers webpage}.  There are a variety of options for
! displaying the HTML help: see below.  Help for routines without HTML
! documentation is also available, using the routine documentation
! header and/or source.
  
  @kindex M-?
  In any IDL program (or, as with most IDLWAVE commands, in the IDL
--- 1267,1284 ----
  @cindex Online Help, Installation
  @cindex Speed, of online help
  
! IDLWAVE can display help from an HTML version of the IDL documentation
! if it is available.  This is @emph{much} faster than using the IDL
! online help application, because IDLWAVE usually gets you to the right
! place in the documentation directly --- e.g. a specific keyword of a
! routine --- without any additional browsing and scrolling.  There are
! a variety of options for displaying the HTML help: see below.  Help
! for routines without HTML documentation is also available, using the
! routine documentation header and/or source.
! 
! To make this feature work, you should set
! @code{idlwave-html-help-location} to the directory name of the
! directory where the IDL help files are installed.
  
  @kindex M-?
  In any IDL program (or, as with most IDLWAVE commands, in the IDL
***************
*** 1376,1394 ****
  Customize this variable to see what choices of browsers your system
  offers.
  
! Certain browsers like @code{w3} (bundled with many versions of Emacs)
! and @code{w3m} (@uref{http://emacs-w3m.namazu.org/}, the author's help
! browser of choice) are run within Emacs, and use Emacs buffers to
! display the HTML help.  This can be convenient, especially on small
! displays, and images can even be displayed in-line on new Emacs
! versions.  However, better formatting results are often achieved with
! external browsers, like Mozilla.  IDLWAVE assumes any browser function
! containing "w3" is displayed in a local buffer.  If you are using
! another Emacs-local browser for which this is not true, set the
! variable @code{idlwave-help-browser-is-local}.
  
! @emph{N.B. For Windows users}: IDLWAVE can bring up RSI help directly
! in the Microsoft HTMLHelp documentation supplied with IDL: no
  additional help files are needed.  Be sure to set
  @code{idlwave-system-directory} and the help file will be found
  automatically (or, alternatively, specify its location directly with
--- 1363,1381 ----
  Customize this variable to see what choices of browsers your system
  offers.
  
! Certain browsers like @code{w3} and @code{w3m}
! (@uref{http://emacs-w3m.namazu.org/}, the author's help browser of
! choice) are run within Emacs, and use Emacs buffers to display the
! HTML help.  This can be convenient, especially on small displays, and
! images can even be displayed in-line on new Emacs versions.  However,
! better formatting results are often achieved with external browsers,
! like Mozilla.  IDLWAVE assumes any browser function containing "w3" is
! displayed in a local buffer.  If you are using another Emacs-local
! browser for which this is not true, set the variable
! @code{idlwave-help-browser-is-local}.
  
! @emph{N.B. For Windows users}: IDLWAVE can bring up help directly
! from the Microsoft HTMLHelp documentation supplied with IDL: no
  additional help files are needed.  Be sure to set
  @code{idlwave-system-directory} and the help file will be found
  automatically (or, alternatively, specify its location directly with
***************
*** 2343,2349 ****
  
  
  
! @node The IDLWAVE Shell, Installation, The IDLWAVE Major Mode, Top
  @chapter The IDLWAVE Shell
  @cindex IDLWAVE shell
  @cindex Major mode, @code{idlwave-shell-mode}
--- 2330,2336 ----
  
  
  
! @node The IDLWAVE Shell, Acknowledgements, The IDLWAVE Major Mode, Top
  @chapter The IDLWAVE Shell
  @cindex IDLWAVE shell
  @cindex Major mode, @code{idlwave-shell-mode}
***************
*** 3209,3267 ****
  @end defopt
  
  
! @node Installation, Acknowledgements, The IDLWAVE Shell, Top
! @chapter Installation
! @cindex Installation
! 
! @menu
! * Installing IDLWAVE::          How to install the distribution
! * Installing Online Help::      Where to get the additional files needed
! @end menu
! 
! @node Installing IDLWAVE, Installing Online Help, Installation, Installation
! @section Installing IDLWAVE
! 
! @cindex FTP site
! @cindex URL, homepage for IDLWAVE
! @cindex Homepage for IDLWAVE
! @cindex IDLWAVE, homepage
! @cindex XEmacs package IDLWAVE
! @cindex Emacs, distributed with IDLWAVE
! @cindex Copyright, of IDL manual
! IDLWAVE is part of Emacs 21.1 and later.  It is also an XEmacs package
! and can be installed from
! @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,the XEmacs ftp site}
! with the normal package management system on XEmacs 21.  These
! pre-installed versions should work out-of-the-box.  However, the HTML
! files required for online HTML help are not distributed with
! XEmacs/Emacs and have to be installed address@hidden to
! copyright reasons, the HTML version of the IDL manual cannot be
! distributed under the GPL.}  (@pxref{Installing Online Help}).
! 
! You can also download IDLWAVE and install it yourself from
! @address@hidden, the maintainers webpage}.  Follow the
! instructions in the INSTALL file.
! 
! @node Installing Online Help,  , Installing IDLWAVE, Installation
! @section Installing Online Help
! @cindex Installing online help
! @cindex Online Help, Installation
! 
! If you want to use the online help display, an additional set of files
! (HTML versions of the IDL documentation) must be installed.  These
! files can also be downloaded from @address@hidden, the
! maintainers webpage}.  You need to place the files somewhere on your
! system and tell IDLWAVE where they are with
! 
! @lisp
! (setq idlwave-html-help-location "/path/to/help/dir/") ;e.g. /usr/local/etc
! @end lisp
! 
! Note that the help package only changes with new versions of the IDL
! documentation, and need not be updated unless your version of IDL
! changes.
! 
! @node Acknowledgements, Sources of Routine Info, Installation, Top
  @chapter Acknowledgements
  @cindex Acknowledgements
  @cindex Maintainer, of IDLWAVE
--- 3196,3202 ----
  @end defopt
  
  
! @node Acknowledgements, Sources of Routine Info, The IDLWAVE Shell, Top
  @chapter Acknowledgements
  @cindex Acknowledgements
  @cindex Maintainer, of IDLWAVE
***************
*** 3731,3740 ****
  manuals.  The file @file{idlw-rinfo.el} contains the routine information
  for the IDL system routines, and links to relevant sections of the HTML
  documentation.  The Online Help feature of IDLWAVE requires HTML
! versions of the IDL manuals to be available; the HTML documentation is
! not distributed with IDLWAVE by default, but must be downloaded
! separately from the @address@hidden, the maintainers
! webpage}.
  
  The HTML files and related images can be produced from the
  @file{idl.chm} HTMLHelp file distributed with IDL using the free
--- 3666,3672 ----
  manuals.  The file @file{idlw-rinfo.el} contains the routine information
  for the IDL system routines, and links to relevant sections of the HTML
  documentation.  The Online Help feature of IDLWAVE requires HTML
! versions of the IDL manuals to be available.
  
  The HTML files and related images can be produced from the
  @file{idl.chm} HTMLHelp file distributed with IDL using the free
***************
*** 3755,3776 ****
  5.0).  Since IDLWAVE runs on a many different system types, a single
  browser configuration is not possible, but choices abound.
  
! On many systems, the default browser configured in
! @code{browse-url-browser-function}, and hence inherited by default by
! @code{idlwave-help-browser-function}, is Netscape.  Unfortunately, the
! HTML manuals decompiled from the original RSI source contain
! formatting structures which Netscape 4.x does not handle well, though
! they are still readable.  A much better choice is Mozilla, or one of
! the Mozilla-derived browsers such as
! @uref{http://galeon.sourceforge.net/,Galeon} (Linux),
  @uref{http://www.mozilla.org/projects/camino/,Camino} (MacOSX), or
  @uref{http://www.mozilla.org/projects/firebird/,Firebird} (all
  platforms).  Newer versions of Emacs provide a browser-function choice
  @code{browse-url-gnome-moz} which uses the Gnome-configured browser.
  
! Note that the HTML files decompiled from RSI Microsoft Help sources
  contain specific references to the @samp{Symbol} font, which by default
! is not permitted in normal encodings (it's technically illegal).  Though
  it only impacts a few symbols, you can trick Mozilla-based browsers into
  recognizing @samp{Symbol} by following the directions
  @uref{http://hutchinson.belmont.ma.us/tth/Xfonts.html, here}.  With this
--- 3687,3705 ----
  5.0).  Since IDLWAVE runs on a many different system types, a single
  browser configuration is not possible, but choices abound.
  
! Unfortunately, the HTML manuals decompiled from the original
! source contain formatting structures which Netscape 4.x does not
! handle well, though they are still readable.  A much better choice is
! Mozilla, or one of the Mozilla-derived browsers such as
! @uref{http://galeon.sourceforge.net/,Galeon} (GNU/Linux),
  @uref{http://www.mozilla.org/projects/camino/,Camino} (MacOSX), or
  @uref{http://www.mozilla.org/projects/firebird/,Firebird} (all
  platforms).  Newer versions of Emacs provide a browser-function choice
  @code{browse-url-gnome-moz} which uses the Gnome-configured browser.
  
! Note that the HTML files decompiled from  Microsoft Help sources
  contain specific references to the @samp{Symbol} font, which by default
! is not permitted in normal encodings (it's invalid, technically).  Though
  it only impacts a few symbols, you can trick Mozilla-based browsers into
  recognizing @samp{Symbol} by following the directions
  @uref{http://hutchinson.belmont.ma.us/tth/Xfonts.html, here}.  With this
***************
*** 3995,4006 ****
  portability of Emacs, much of IDLWAVE does also work under different
  operating systems like Windows (with NTEmacs or NTXEmacs) or MacOS.
  
! The only real problem is that RSI does not provide a command-line
  version of IDL for Windows or MacOS(<=9) with which IDLWAVE can
! address@hidden your RSI representative and complain --- it
! should be trivial for them to provide one.  And if enough people ask for
! it, maybe they will.  The new MacOSX version of IDL @emph{does} have a
! shell and works well with IDLWAVE.}.  As a result, the IDLWAVE Shell
  does not work and you have to rely on IDLDE to run and debug your
  programs.  However, editing IDL source files with Emacs/IDLWAVE works
  with all bells and whistles, including routine info, completion and fast
--- 3924,3932 ----
  portability of Emacs, much of IDLWAVE does also work under different
  operating systems like Windows (with NTEmacs or NTXEmacs) or MacOS.
  
! The only real problem is that there is no command-line
  version of IDL for Windows or MacOS(<=9) with which IDLWAVE can
! interact.  As a result, the IDLWAVE Shell
  does not work and you have to rely on IDLDE to run and debug your
  programs.  However, editing IDL source files with Emacs/IDLWAVE works
  with all bells and whistles, including routine info, completion and fast
***************
*** 4018,4024 ****
  ;; the X/Emacs installation)
  (setq load-path (cons "c:/program files/IDLWAVE" load-path))
  
! ;; The location of the IDL library files, both from RSI and your own.
  ;; note that the initial "+" expands the path recursively
  (setq idlwave-library-path
          '("+c:/RSI/IDL55/lib/" "+c:/user/me/idllibs" ))
--- 3944,3950 ----
  ;; the X/Emacs installation)
  (setq load-path (cons "c:/program files/IDLWAVE" load-path))
  
! ;; The location of the IDL library files, both standard and your own.
  ;; note that the initial "+" expands the path recursively
  (setq idlwave-library-path
          '("+c:/RSI/IDL55/lib/" "+c:/user/me/idllibs" ))
***************
*** 4113,4121 ****
  place, and this is the source of the error.  If you recompile (or just
  "make; make install") from source, it should resolve this problem.
  Another option is to recompile the @file{idlw*.el} files by hand using
! @kbd{M-x byte-compile-file}.  Why not take the opportunity to grab the
! latest IDLWAVE version at @address@hidden, the
! maintainers webpage}
  
  @item @address@hidden@key{TAB}} doesn't complete words, it switches
  windows on my desktop.}
--- 4039,4045 ----
  place, and this is the source of the error.  If you recompile (or just
  "make; make install") from source, it should resolve this problem.
  Another option is to recompile the @file{idlw*.el} files by hand using
! @kbd{M-x byte-compile-file}.
  
  @item @address@hidden@key{TAB}} doesn't complete words, it switches
  windows on my desktop.}
***************
*** 4214,4220 ****
  @item @strong{All the Greek-font characters in the HTML help are
  displayed as Latin characters!}
  
! Unfortunately, the HTMLHelp files RSI provides attempt to switch to
  @samp{Symbol} font to display Greek characters, which is not really an
  permitted method for doing this in HTML.  There is a "workaround" for
  many browsers: @xref{HTML Help Browser Tips}.
--- 4138,4144 ----
  @item @strong{All the Greek-font characters in the HTML help are
  displayed as Latin characters!}
  
! Unfortunately, the HTMLHelp files attempt to switch to
  @samp{Symbol} font to display Greek characters, which is not really an
  permitted method for doing this in HTML.  There is a "workaround" for
  many browsers: @xref{HTML Help Browser Tips}.