update docs (#159)

Author: justinwoo

docs/faq.md

@@ -1,33 +1,13 @@
 # FAQ
 
-## Is there an easier way to manage my package sets than to edit packages.json?
+## Is there an easier way to manage my package sets than to edit packages.json? / How do I prepare a packages.json in some way other than editing JSON?
 
-Yes. For example, the [Spacchetti](https://github.com/justinwoo/spacchetti/) project uses Dhall to allow for easily maintaining a fork with separate type-checked sub-sets of packages and to allow for users to have local overrides of package sets.
+Yes. [purescript/package-sets](https://github.com/purescript/package-sets) itself uses Dhall to programmatically prepare the package set, which are then normalized into `packages.dhall` on release: <https://github.com/purescript/package-sets/releases>. You can import this file in your own Dhall files and add/override packages to customize your package set.
 
 ## How come I can't install (some package) from the package set?
 
 You should make sure you're using the correct [package-set release](https://github.com/purescript/package-sets/releases) and have updated the value of "set" in your `psc-package.json` file. See [The `psc-package.json` format](https://github.com/purescript/psc-package#the-psc-packagejson-format) section for more details.
 
-## Can I add a dependency which is not in the package set?
-
-Not right now. We might add this feature in future, but for now, consider either:
-
-- Adding your dependency to the package set if possible, or
-- Creating your own custom package set
-
-There used to be a feature called "add-from-bower", which could modify a package set from [purescript/package-sets](https://github.com/purescript/package-sets/). This feature was removed as it proved to be very buggy and confusing for users, who thought that this feature would let them install arbitrary bower dependencies. See <https://github.com/purescript/psc-package/issues/121>.
-
-## Why is Add-From-Bower gone?
-
-The feature named "add-from-bower" never did what users expected it to do: to install packages to a project from Bower.
-
-Instead, what this feature did was to add packages to a package set from [purescript/package-sets](https://github.com/purescript/package-sets/). However, due to the buggy nature of the feature, it was agreed that the feature should be removed and left up to other tools to handle. See <https://github.com/purescript/psc-package/issues/121>, where the top post describes how the [Spacchetti](https://github.com/spacchetti/spacchetti) package set adds Bower dependencies to the package set.
-
-If you really would like to mix Psc-Package and Bower dependencies, you have two "real" options today. However, these will break if your packages are not all compatible, because this defeats the guarantees of having a package set.
-
-1. Install the Bower dependencies anyway, and then only source the globs for individual dependencies, so you do not have conflicting definitions of other common modules. You can do this by supplying pass-through arguments: `psc-package build -- 'bower_componenents/purescript-my-lib/src/**/*.purs'`
-2. Use the "Bower style" installation of Psc-Package2Nix: <https://github.com/justinwoo/psc-package2nix/tree/master/test-bower-style>. This will require that you use a system that can use the [Nix](https://nixos.org/nix/) package manager. See the link for more details.
-
 ## Why are my changes not updated in my package set?
 
 Package sets are cached based on a git reference (e.g. tag or branch)
@@ -42,4 +22,4 @@ $ psc-package install
 
 ## Can I use Psc-Package with Nix?
 
-Yes, now there is a solution for using Psc-Package with Nix: <https://github.com/justinwoo/psc-package2nix>. Please file issues in that project if you run into any.
+Yes, please see the page about Nix here: <https://psc-package.readthedocs.io/en/latest/nix.html>.

docs/installation.md

@@ -50,8 +50,8 @@ env:
   - PATH=$HOME/purescript:$HOME/psc-package:$PATH
 
 install:
-  - TAG=v0.12.0
-  - PSC_PACKAGE_TAG=v0.4.1
+  - TAG=v0.13.6
+  - PSC_PACKAGE_TAG=v0.6.0
   - wget -O $HOME/purescript.tar.gz https://github.com/purescript/purescript/releases/download/$TAG/linux64.tar.gz
   - tar -xvf $HOME/purescript.tar.gz -C $HOME/
   - chmod a+x $HOME/purescript

docs/intro.md

@@ -10,7 +10,13 @@ A _package set_ is a mapping from package names to:
 
 A package set repository contains a `packages.json` file which contains all mapping information. `psc-package` uses this information to decide which repos need to be cloned.
 
-The default package set is [purescript/package-sets](https://github.com/purescript/package-sets), but it is possible to create custom package sets by forking an existing package set or creating a new one from scratch. One benefit of using the default package set is that it is verified by a continuous integration process.
+The default package set is [purescript/package-sets](https://github.com/purescript/package-sets), but it is possible to create custom package sets in many ways:
+
+* by preparing a package set with Dhall using the packages.dhall from releases: <https://github.com/purescript/package-sets/releases>
+* forking `purescript/package-sets` to your own repository
+* creating a new one from scratch
+
+. One benefit of using the default package set is that it is verified by a continuous integration process.
 
 ## The `psc-package.json` format
 
@@ -19,7 +25,7 @@ Here is a simple project configuration:
 ```json
 {
     "name": "my-project",
-    "set": "psc-0.10.2",
+    "set": "psc-0.13.6",
     "source": "https://github.com/purescript/package-sets.git",
     "depends": [
         "prelude"
@@ -30,6 +36,6 @@ Here is a simple project configuration:
 It defines:
 
 - The project name
-- The package set to use to resolve dependencies (this corresponds to a branch or tag of the package set source repository)
-- The package set source repository Git URL (change this if you want to host your own package sets)
+- The package set to use to resolve dependencies. This corresponds to a branch or tag of the package set source repository if you use a Git URL as your source. Otherwise it serves as just an identifier.
+- The package set source, which is either a repository Git URL or a path to a package set `packages.json` file.
 - Any dependencies of the project, as a list of names of packages from the package set

docs/nix.md

@@ -1,5 +1,9 @@
 # Usage with Nix
 
-## [justinwoo/psc-package2nix](https://github.com/justinwoo/psc-package2nix)
+## [justinwoo/psc-package2nix](https://github.com/justinwoo/psc-package2nix) (Older)
 
 Justin Woo has made a psc-package2nix project for generating nix derivations from Psc-Package dependencies: <https://github.com/justinwoo/psc-package2nix>
+
+## [justinwoo/soba](https://github.com/justinwoo/soba) (Newer)
+
+Because of the relative rarity in using psc-package with Nix, there is not excessive documentation on how to use this tool. See mostly the `soba insdhall` and `soba nix` commands in this tool.

docs/usage.md

@@ -40,3 +40,56 @@ The local package database can be queried using the following commands:
 
 - `sources` - list source directories for active package versions. This can be useful when building a command for, say, running PSCi.
 - `dependencies` - list all transitive dependencies
+
+## Local package sets
+
+In `psc-package.json`, you can set `"source"` to be a path to a local file:
+
+```json
+{
+  "name": "name",
+  "set": "local",
+  "source": "packages.json",
+  "depends": [
+    "aff"
+  ]
+}
+```
+
+From here, you can generate a local packages.json file in any way you please and use this package set directly. Consider if you use Dhall:
+
+```dhall
+let upstream =
+      https://github.com/purescript/package-sets/releases/download/psc-0.13.5-20200103/packages.dhall sha256:0a6051982fb4eedb72fbe5ca4282259719b7b9b525a4dda60367f98079132f30
+
+in    upstream
+    ⫽ { calpis =
+          { dependencies = [ "prelude" ]
+          , repo = "https://github.com/justinwoo/purescript-calpis.git"
+          , version = "v0.1.0"
+          }
+      }
+```
+
+This definition takes an existing release and adds the "calpis" package. Then we can generate a package set from this by running Dhall-JSON:
+
+> dhall-to-json --file packages.dhall --output packages.json
+
+Then we can install this package expected:
+
+```bash
+$ psc-package install calpis
+Installing calpis
+psc-package.json file was updated
+
+$ cat psc-package.json
+{
+  "name": "name",
+  "set": "local",
+  "source": "packages.json",
+  "depends": [
+    "aff",
+    "calpis"
+  ]
+}
+```