Merge pull request #102 from ocaml-community/update-readme

Update README

LICENSE.md

@@ -1,24 +1,26 @@
-Copyright (c) 2010-2012 Martin Jambon
-All rights reserved.
+Copyright (c) 2010-2012, Martin Jambon 
+All rights reserved. 
 
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions
-are met:
-1. Redistributions of source code must retain the above copyright
-   notice, this list of conditions and the following disclaimer.
-2. Redistributions in binary form must reproduce the above copyright
-   notice, this list of conditions and the following disclaimer in the
-   documentation and/or other materials provided with the distribution.
-3. The name of the author may not be used to endorse or promote products
-   derived from this software without specific prior written permission.
+Redistribution and use in source and binary forms, with or without 
+modification, are permitted provided that the following conditions are met: 
 
-THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
-IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
-OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
-IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
-INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
-NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
-THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ * Redistributions of source code must retain the above copyright notice, 
+   this list of conditions and the following disclaimer. 
+ * Redistributions in binary form must reproduce the above copyright 
+   notice, this list of conditions and the following disclaimer in the 
+   documentation and/or other materials provided with the distribution. 
+ * Neither the name of  nor the names of its contributors may be used to 
+   endorse or promote products derived from this software without specific 
+   prior written permission. 
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
+POSSIBILITY OF SUCH DAMAGE. 

README.md

@@ -1,50 +1,86 @@
-Yojson: low-level JSON library for OCaml
-========================================
+Yojson: JSON library for OCaml
+==============================
 
 [![Build Status](https://travis-ci.org/ocaml-community/yojson.svg?branch=master)](https://travis-ci.org/ocaml-community/yojson)
 
-_This library is for manipulating the json AST directly. For mapping between OCaml types and json, we recommend [atdgen](https://github.com/ahrefs/atd)._
+This library parses JSON data into a nested OCaml tree data structure.
+
 
 Library documentation
 ---------------------
 
 Currently at https://ocaml-community.github.io/yojson/
 
-Design goals
-------------
 
-* reducing inter-package dependencies by the use of polymorphic
-  variants for the JSON tree type
+Examples
+--------
+
+A simple example on how to parse JSON from a string literal.
+
+```ocaml
+let json_string = {|
+  {"number" : 42,
+   "string" : "yes",
+   "list": ["for", "sure", 42]}|}
+(* val json_string : string *)
+
+let json = Yojson.Safe.from_string json_string
+(* val json : Yojson.Safe.t *)
+
+Format.printf "Parsed to %a" Yojson.Safe.pp json
+```
+
+
+Related tooling
+---------------
 
-* allowing variants of the JSON tree type to be shipped by the library
-  itself or to be easily created as extensions of the library
+`Yojson` is a pretty common choice for parsing JSON in OCaml, as such it is the
+base for a number of tools and libraries that are built on top of it.
 
-* allowing type-aware serializers/deserializers such as json-static
-  to read and write directly without going through a JSON tree,
-  for efficiency purposes.
-  This requires making readers and writers of JSON atoms (int, string,
-  etc.) to be exported and composable.
+* [`ppx_deriving_yojson`](https://github.com/ocaml-ppx/ppx_deriving_yojson) to
+  automatically generate code that converts between `Yojson.Safe.t` and custom
+  OCaml types
+* [`ppx_yojson_conv`](https://github.com/janestreet/ppx_yojson_conv), an
+  alternative to `ppx_deriving_yojson` from Jane Street with different design
+  decisions
+* [`atd`](https://github.com/ahrefs/atd), generates mapping code from `.atd`
+  specification files and can be used in multiple languages
+* [`jsonm`](https://erratique.ch/software/jsonm) is an alternate JSON parser
+  that parses JSON into a stream of items, so the complete data structure does
+  not have to be in memory.
 
-* providing a few non-standard, optional extensions of JSON.
-  These extensions will include:
-  * optional quotes around "simple" field/constructor names
-  * a syntax for tuples (at least 2 elements): `(x, y)`
-  * a syntax for variants (0 or 1 arg only): `<Foo> <Bar:"abc">`
+Help wanted
+-----------
 
+Yojson is developed and maintained by volunteers &mdash; users like you.
+[Various issues](https://github.com/ocaml-community/yojson/issues) are in need
+of attention. If you'd like to contribute, please leave a comment on the issue
+you're interested in, or create a new issue. Experienced contributors will
+guide you as needed.
 
-Other choices already in json-wheel
------------------------------------
+There are many simple ways of making a positive impact. For example,
+you can...
 
-* distinction between ints and floats (optional)
+* Use the software in your project.
+* Give a demo to your colleagues.
+* Share the passion on your blog.
+* Tweet about what you're doing with `Yojson`.
+* Report difficulties by creating new issues. We'll triage them.
+* Ask questions on StackOverflow.
+* Answer questions on
+  [StackOverflow](https://stackoverflow.com/search?q=yojson).
+* Discuss usage on the [OCaml forums](https://discuss.ocaml.org/).
+* Pick a [task](https://github.com/ocaml-community/yojson/issues) that's easy
+  for you.
 
-* Getting rid of the UTF-X encoding constraint that prevents from
-  exchanging binary data:
-  * encoding is ASCII except for the contents of string literals
-  * string literals may represent arbitrary sequence of bytes
-  * `\uABCD` escapes in string literals expand to UTF-8
+Check out in particular
+[good first time issues](https://github.com/ocaml-community/yojson/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+time+issue%22)
+and other issues with which
+[we could use some help](https://github.com/ocaml-community/yojson/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).
 
 
-Miscellaneous
--------------
+License
+-------
 
-* no dependency on ocamlnet for UTF-8
+`Yojson` is licensed under the 3-clause BSD license, see `LICENSE.md` for
+details.

yojson.opam

@@ -5,6 +5,7 @@ homepage: "https://github.com/ocaml-community/yojson"
 bug-reports: "https://github.com/ocaml-community/yojson/issues"
 dev-repo: "git+https://github.com/ocaml-community/yojson.git"
 doc: "https://ocaml-community.github.io/yojson/"
+license: "BSD-3-Clause"
 build: [
   ["dune" "subst"] {pinned}
   ["dune" "build" "-p" name "-j" jobs]
@@ -23,11 +24,5 @@ synopsis:
 description: """
 Yojson is an optimized parsing and printing library for the JSON format.
 
-It addresses a few shortcomings of json-wheel including 2x speedup,
-polymorphic variants and optional syntax for tuples and variants.
-
 ydump is a pretty-printing command-line program provided with the
-yojson package.
-
-The program atdgen can be used to derive OCaml-JSON serializers and
-deserializers from type definitions."""
+yojson package."""