Editing install.rst

README

@@ -23,49 +23,57 @@
  Raghuram Thiagarajan
  Akash Arora
 
------------------------------------------------------------------------
-I. Directory Structure
-
-src/ - Fortran 90 source files
-src/build - - directory containing Makefile
-examples/ - usage examples, with input files
-doc/ - documentation files
-doc/sphinx - - user manual text files
-doc/api - - auto-generated api documentation
-tools/ - Tools for processing output and source
-tools/matlab - - matlab m-files for visualization
-tools/python - - python scripts for data analysis
-tools/python/preprocess-0.6.1 - Forpedo preprocessor script
+ Dependencies:
+
+ PSCF depends upon the FFTW fast Fourier transform library and the 
+ LAPACK linear algebra library. These packages must be installed 
+ before attempting to compile the program from source. Neither of
+ these packages is needed to use a precompiled binary executable, 
+ which is self-contained.
 
 -----------------------------------------------------------------------
-II. Dependencies
+Directory Structure
 
-The program depends upon the FFTW fast Fourier transform library
-and the LAPACK linear algebra library. The program can use either 
-version 2 or version 3 of the FFTW library. You will need to 
-install both LAPACK and FFTW before attempting to compile the 
-program.
+ src/ - Fortran 90 source files
+ src/build - - directory containing Makefile
+ examples/ - usage examples, with input files
+ doc/ - documentation files
+ doc/sphinx - - user manual text files
+ doc/api - - auto-generated api documentation
+ tools/ - Tools for processing output and source
+ tools/matlab - - matlab m-files for visualization
+ tools/python - - python scripts for data analysis
+ tools/python/preprocess-0.6.1 - Forpedo preprocessor script
+
+ An annotated list of source files is provided in the file src/SRC_FILES. 
 
 ----------------------------------------------------------------------
-III. Compiling and Linking
+Documentation
+
+The source files for a user manual are easily readable text files that 
+are stored in the doc/user-man directory, The resulting web pages are 
+also available online at the site:
+
+ https://pscf.readthedocs.org
 
 Instructions for compiling the program from source, as well as various
 ways to install precompiled executables, are discussed in the file 
 
  doc/sphinx/install.rst
 
-An annotated list of source files is provided in the file src/SRC_FILES. 
+and in the corresponding section of the web user manual. 
+
+Developer API documentation may be generated by following the 
+instructions given in the file doc/README, which are repeated in the
+user manual. The resulting .html page are installed in doc/devel-man.
 
 ----------------------------------------------------------------------
-IV. Preprocessor
+Preprocessor Script
 
 Several of the fortran *.f source files have been created using a 
 python preprocessor from corresponding files that end with the suffix
 *.fp.f. This preprocessor script, named "Forpedo", is included with the 
-distribution. The only *.f files that are now built in this way are:
-src/build/pscf_pd.f src/build/scf_mod.f and src/build/iterate_mod.f
-Because coies of these three files are included with this distribution, 
-it is not necessary for you to run the preprocessor in order to compile 
-the program. Before modifying any of the fortran source files, however, 
-please read the discussion of the preprocessor near the end of the file 
+distribution. Before modifying any of the fortran source files, please 
+read the discussion of the preprocessor near the end of the file 
 src/SRC_FILES.
+

doc/user-man/install.rst

@@ -9,8 +9,8 @@ and can be installed on either the linux operating system or in the Mac OS X.
 There are two different ways to install a working version of PSCF in either 
 operating system:
 
- * Install a precompiled binary
- * Compile and install from source code
+ * Install a precompiled binary package
+ * Compile from source code
 
 Installation of a precompiled binary is somewhat simpler, but does not allow
 the user to modify and recompile the program. The required steps for both
@@ -31,35 +31,72 @@ procedure is similar to that for installing any other application on a Mac:
 
  * Download the Mac pscf<version>.dmg installer from the PSCF home page
 
- * Double click on the installer file
+ * Open the .dmg file, and drag and drop the pscf_terminal icon file 
+ into your Applications folder.
 
- * Drag the file pscf_terminal application into the applications folder.
+To run the program, simply double clicking the pscf_terminal application.
+This will open up a yellow terminal window from which you can use standard 
+unix commands to navigate within the directory structure of your Mac, and 
+from which you can invoke the pscf command.
 
-Double clicking the pscf_terminal application will open up a yellow terminal
-window from which you can use standard unix commands to navigate within the
-directory structure of your Mac, and from which you can invoke the pscf 
-command.
+The first time you attempt to run pscf_terminal, Mac OSX security settings 
+will prevent the application from starting because it is from an "Unknown
+Developer". You will need to add an exception for this software. The 
+following instructions are provided by Apple on
+https://support.apple.com/kb/PH18657?locale=en_US: 
+
+1. In the Finder, locate the app you want to open.
+ - Don’t use Launchpad to do this. Launchpad doesn’t allow you to 
+ access the shortcut menu.
+
+2. Press the Control key, then click the app icon, then choose Open from 
+ the shortcut menu.
+
+3. Click Open.
+
+The app is saved as an exception to your security settings, and you can 
+open it in the future by double-clicking it just as you can any registered 
+app.
 
 Ubuntu or Debian Linux
 ----------------------
 
-The Ubuntu and Debian distributions of the linux operating systems both use 
-package management systems that use deb package file format, with the .deb 
-extension. To install on Ubuntu or Debian:
+Ubuntu and Debian distributions of the linux operating systems both use 
+package management systems that use .deb package files. To install on 
+Ubuntu:
 
  * Download the pscf<version>.deb package from the PSCF home page
 
- * Install the package by running::
+ * Use the Ubuntu software center graphical installer or the apt-get
+ command line utility to install the following packages:
+
+ - fftw3
+ - liblapack3
+
+ To install these packages using apt-get, enter::
+
+ sudo apt-get fftw3
+ sudo apt-get liblapack3
+
+ * Install the pscf package by running::
+
+ dpkg -i pscf<version>.deb
+
+ * If the above command fails because of a missing dependence, try 
+ running::
+
+ apt-get install pscf<version>.deb
+
+ This allows apt-get to attempt to fetch any missing dependencies.
 
- dpkg -i pscf<version>.deb
 
 Fedora / Redhat Linux
 ---------------------
 
-Fedora and Redhat distributions of the linux operating systems use package 
-management systems that use .rpm package files. Instructions are similar to
-those for Ubuntu/Debian, except for the use of a different package file 
-format and package manager. In this case:
+Redhat distributions of the linux operating systems, including Fedora 
+and CentOS, use package management systems that use .rpm package files. 
+Instructions are similar to those for Ubuntu/Debian, except for the use 
+of a different package file format and package manager. In this case:
 
  * Download the pscf<version>.rpm package from the PSCF home page