appropriate for GitHub as opposed to svn

COPYRIGHT.md

@@ -1,3 +1,16 @@
-DART software - Copyright UCAR. This open source software is provided
-by UCAR, "as is", without charge, subject to all terms of use at
-http://www.image.ucar.edu/DAReS/DART/DART_download
+
+![DARTlogo](documentation/images/Dartboard7.png "DART Logo")
+
+Copyright 2019 University Corporation for Atmospheric Research
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -1,42 +1,41 @@
-# DART software - Copyright UCAR. This open source software is provided
-# by UCAR, "as is", without charge, subject to all terms of use at
-# http://www.image.ucar.edu/DAReS/DART/DART_download
-#
-# DART $Id$
 
-Welcome to DART, the Data Assimilation Research Testbed.
-See the bottom of this file for quick-start instructions.
+![DARTlogo](docs/images/Dartboard7.png)
 
-Extensive on-line documentation is on the project web pages:
- http://www.image.ucar.edu/DAReS/DART
+## Welcome to DART, the Data Assimilation Research Testbed.
 
-Extensive local documentation is included in the DART subversion
-checkout.  Open 'documentation/index.html' in your browser to begin.
+[quick-start instructions for the impatient](#QuickStart)
 
-A Matlab/PDF introduction is in the documentation/DART_LAB directory.  
+Extensive on-line documentation is available at the GitHub project web pages:
+[https://ncar.github.io/DART](https://ncar.github.io/DART)
+or in the repository at [docs/index.md](docs/index.md). It's probably a good idea
+to be familiar with the [GitHub workflow](https://guides.github.com/introduction/flow/).
+
+<table><tr>
+<td><img height=250, src="./docs/images/DARTspaghettiSquare.gif"></td> 
+<td><img height=250, src="./docs/images/science_nuggets/AssimAnim.gif"></td>
+</tr></table>
+
+[Extensive local documentation is included with DART.](docs/index.md)
+
+A Matlab-based introduction is in the `docs/DART_LAB` directory.  
 There are a set of PDF presentations along with hands-on Matlab exercises.  
 This starts with a very basic introduction to data assimilation and covers 
 several fundamental algorithms in the system.
-
-A slightly more advanced tutorial in PDF format is in the documentationb/tutorial
-subdirectory.  Start with the index file which explains what each subsection covers.
+A more exhaustive tutorial for data assimilation with DART is in PDF format at 
+[docs/tutorial](docs/tutorial/index.html).
 
 The DART Manhattan release documentation is on the web:
 http://www.image.ucar.edu/DAReS/DART/Manhattan/documentation/html/Manhattan_release.html
-
-and also in the subversion tree here at:
- documentation/html/Manhattan_release.html
-
-General documentation in HTML format is in the documentation/html directory. 
-In addition, all parts of the DART system include HTML files in the respective 
-model and source directories.  There is an 'index.html' file in the top level
-documentation directory which references all the other doc files.
+and in the repository at:
+[docs/html/Manhattan_release.html](docs/html/Manhattan_release.html)
 
 There is a mailing list where we summarize updates to the DART repository
-and notify users about recent bug fixes.  It is not generally used for
-discussion so it's a low-traffic list.  To add yourself go here and
-click on 'Dart-users', and if you use WRF see 'wrfdart-users' also:
- http://mailman.ucar.edu/mailman/listinfo/
+and notify users about recent bug fixes.
+It is not generally used for discussion so it's a low-traffic list.
+To subscribe to the list, click on
+[Dart-users](http://mailman.ucar.edu/mailman/listinfo/dart-users).
+If you use WRF, there is also a
+[Wrfdart-users](http://mailman.ucar.edu/mailman/listinfo/wrfdart-users).
 
 The Manhattan release is new and currently supports only a subset of the 
 models.  We will port over any requested model so contact us if yours
@@ -46,57 +45,99 @@ development features.  All new development will be based on the
 Manhattan release but the 'classic' release will remain for those
 models which already have the necessary features.
 
-Existing users will see that we have rearranged our directory tree.
-We hope this helps you find the various pieces that come with the
-DART distribution.
-
 Contact us for more help or for more information on other models already
 using DART or for how to add your model or observation types.
 
 Thank you -
 The DART Development Team.
 dart at ucar.edu
 
+## DART source code tree
+
+The top level DART source code tree contains the following directories and files:
+
+| Directory            | Purpose  |
+| :--------------      | :------- |
+| `assimilation_code/` | Low-level library and fonts required by NCAR Graphics and NCL |
+| `build_templates/`   | Configuration files for installation |
+| `developer_tests/`   | regression testing |
+| `diagnostics/`       | routines to diagnose assimilation performance |
+| `docs/`              | General documentation and DART_LAB tutorials |
+| `models/`            | the interface routines for the models |
+| `observations/`      | routines for converting observations and forward operators |
+| **Files**            | **Purpose** |
+| `CHANGELOG.md`       | Brief summary of recent changes |
+| `COPYRIGHT.md`       | terms of use and copyright information |
+| `README.md`          | Basic Information about DART |
+
+## Bug reports and feature requests
+
+Use the GitHub [issue tracker](https://github.com/NCAR/DART-2.0/issues) 
+to submit a bug or request a feature.
 
-Quick-start for the impatient:
+## Citing DART
 
-Go into the 'build_templates' directory and copy over the closest
-mkmf.template.compiler.system file into 'mkmf.template'.
+Cite DART using the following text:
 
-Edit it to set the NETCDF directory location if not in /usr/local
-or comment it out and set $NETCDF in your environment.  
-*This NetCDF library must have been compiled with the same compiler
+> The Data Assimilation Research Testbed (Version X.Y.Z) [Software]. (2019). Boulder, Colorado: UCAR/NCAR/CISL/DAReS.  http://doi.org/10.5065/D6WQ0202
+
+Update the DART version and year as appropriate.
+
+---
+
+<a name="QuickStart"></a>
+## Quick-start for the impatient:
+
+There are several large files that are needed to run some of the tests and examples but are not included
+in order to keep the repository as small as possible. If you are interested in running *bgrid_solo*, 
+*cam-fv*, or testing the *NCEP/prep_bufr* observation converter, you will need these files.
+These files are available at:
+
+| Release                | Size   | Filename  |
+| :--------------        | :----- | :-------- |
+| "Manhattan"        |  189M  | [Manhattan_large_files.tar.gz](https://www.image.ucar.edu/pub/DART/Release_datasets/Manhattan_large_files.tar.gz) |
+| "wrf-chem.r13172"  |  141M  | [wrf-chem.r13172_large_files.tar.gz](https://www.image.ucar.edu/pub/DART/Release_datasets/wrf-chem.r13172_large_files.tar.gz) |
+| "Lanai"            |  158M  | [Lanai_large_files.tar.gz](https://www.image.ucar.edu/pub/DART/Release_datasets/Lanai_large_files.tar.gz) |
+| "Kodiak"           |  158M  | [Kodiak_large_files.tar.gz](https://www.image.ucar.edu/pub/DART/Release_datasets/Kodiak_large_files.tar.gz) |
+| "Jamaica"          |   32M  | [Jamaica_large_files.tar.gz](https://www.image.ucar.edu/pub/DART/Release_datasets/Jamaica_large_files.tar.gz) |
+| "Hawaii"           |   32M  | [Hawaii_large_files.tar.gz](https://www.image.ucar.edu/pub/DART/Release_datasets/Hawaii_large_files.tar.gz) |
+
+Download the appropriate tar file and untar it into your DART repository. Ignore any warnings about
+```tar: Ignoring unknown extended header keyword``` .
+
+Go into the `build_templates` directory and copy over the closest
+`mkmf.template`._compiler.system_ file into `mkmf.template`.
+
+Edit it to set the NETCDF directory location if not in `/usr/local`
+or comment it out and set $NETCDF in your environment.  *This NetCDF 
+library must have been compiled with the same compiler
 that you use to compile DART and must include the F90 interfaces.*
 
-Go into 'models/lorenz_63/work' and run './quickbuild.csh'.
+Go into `models/lorenz_63/work` and run *quickbuild.csh*.
 
-If it compiles, hooray.  Run this series of commands to do a very
-basic test:
+> cd models/lorenz_63/work  
+> ./quickbuild.csh  
 
-ncgen -o perfect_input.nc perfect_input.cdl
-./perfect_model_obs
-ncgen -o filter_input.nc filter_input.cdl
-./filter
+If it compiles, *:tada:*!  Run this series of commands to do a very basic test:
 
-If that runs, hooray again.  Finally, if you have Matlab installed on
+> ./perfect_model_obs  
+> ./filter  
+
+If that runs, *:tada:* again!  Finally, if you have Matlab installed on
 your system add '$DART/diagnostics/matlab' to your matlab search path 
 and run the 'plot_total_err' diagnostic script while in the 
-'models/lorenz_63/work' directory.  If the output plots and looks 
+`models/lorenz_63/work` directory.  If the output plots and looks 
 reasonable (error level stays around 2 and doesn't grow unbounded) 
 you're great!  Congrats.
 
 If you are planning to run one of the larger models and want to
-use the Lorenz 63 model as a test, run './quickbuild.csh -mpi'.
+use the Lorenz 63 model as a test, run ```./quickbuild.csh -mpi```.
 It will build filter and any other MPI-capable executables with MPI.
 *The 'mpif90' command you use must have been built with the same 
 version of the compiler as you are using.*
 
-
 If any of these steps fail or you don't know how to do them, go to the
 DART project web page listed above for very detailed instructions that
 should get you over any bumps in the process.
 
-# <next few lines under version control, do not edit>
-# $URL$
-# $Revision$
-# $Date$
+---