updating documentation, including listing utils, adding sections on b…

…uilding, index files, and new API (#718)

* updating documentation

* more documentation improvements

* adding copy of 3.5.0 docs

docs/user_guide.md

@@ -29,6 +29,69 @@ Unrepeated sections remain in effect until redefined.
 The above overview was taken from WMO's FM 92-XII GRIB description
 of the experimental GRIB Edition 2 form.
 
+# Building NCEPLIBS-g2
+
+The NCEPLIBS-g2 library is built with CMake. Starting with
+NCEPLIBS-g2-4.0.0, the
+[NCEPLIBS-g2c](https://github.com/NOAA-EMC/NCEPLIBS-g2c) library is
+required for the build.
+
+The [NCEPLIBS-w3emc](https://github.com/NOAA-EMC/NCEPLIBS-w3emc)
+library provides GRIB1 support. It's required for some NCEPLIBS-g2
+subroutines and some utilities. If built without NCEPLIBS-w3emc, then
+NCEPLIBS-g2 will not contain any GRIB1 functionality and utilities
+which need GRIB1 subroutines will not be built.
+
+# Utilities
+
+The NCEPLIBS-g2 project contains a collection of NCEP grib
+related utilities.
+
+The utilities:
+- cnvgrib.F90 - Convert between GRIB1 and GRIB2.
+- copygb.F90 - Copy all or part of a GRIB1 file.
+- copygb2.F90 - Copy all or part of a GRIB2 file.
+- degrib2.F90 - Inventory a GRIB2 file.
+- grbindex.F90 - Create an index from a GRIB1 file.
+- grb2index.F90 - Create an index from a GRIB2 file.
+- tocgrib.F90 - Copy some GRIB2 fields to a new GRIB1 file.
+- tocgrib2.F90 - Copy some GRIB2 fields to a new GRIB2 file.
+- tocgrib2super.F90 - Copy some GRIB2 fields to a new GRIB2 file with super WMO header.
+
+# File-Based API
+
+NCEPLIBS-g2-4.0.0 introduces a new file-based API. This API adds the
+capability of handling GRIB2 files, keeping track of the locations of
+messages for the user.
+
+To open a file with the new API, call g2cf_open(). This will return a
+file ID which can be used in other subroutines.
+
+Subroutines in the new API include:
+
+* g2cf_open() - Open a GRIB2 file.
+* g2cf_open_index() - Open a file using an index file for better performance.
+* g2cf_inq() - Learn about a GRIB2 file.
+* g2cf_inq_msg() - Learn about a GRIB2 message in the file.
+* g2cf_close() - Close an opened GRIB2 file.
+
+Release all resources for the file by calling g2cf_close().
+
+# Index Files
+
+The NCEPLIBS-g2 library uses index files to help quickly navigate a
+GRIB2 file. These index files can result in significant performance
+improvement for large GRIB2 files.
+
+There are two versions of the index file. The original version
+(version 1) was used until NCEPLIBS-g2-4.0.0. This version of the
+index file does not handle files larger than 2 GB.
+
+The second version of the index file (version 2) handles GRIB2 files
+which are larger than 2 GB.
+
+Create an index file with the grb2index utility.
+
 # GRIB2 Encoding Routines
 
 To start a new GRIB2 message, call subroutine gribcreate(). It
@@ -144,6 +207,7 @@ http://www.nws.noaa.gov/tdl/iwt/grib2/frameset_grib2.htm.
 
 ## Documentation for Previous Versions of NCEPLIBS-g2
 
+* [NCEPLIBS-g2 Version 3.5.0](ver-3.5.0/index.html)
 * [NCEPLIBS-g2 Version 3.4.9](ver-3.4.9/index.html)
 * [NCEPLIBS-g2 Version 3.4.8](ver-3.4.8/index.html)
 * [NCEPLIBS-g2 Version 3.4.7](ver-3.4.7/index.html)