Documentation improvements

1 files changed, 30 insertions, 19 deletions

diff --git a/Biz/Bild.hs b/Biz/Bild.hs
index a538f98..987e513 100644
--- a/Biz/Bild.hs
+++ b/Biz/Bild.hs
@@ -7,54 +7,59 @@
 {-# LANGUAGE TupleSections #-}
 {-# LANGUAGE NoImplicitPrelude #-}
 
--- | A general purpose build tool.
+-- | A specific-purpose build tool.
 --
 -- : out bild
 --
 -- == Design constraints
 --
---    * only input is one or more a namespaces. no subcommands, no packages
+--    * The only input is one or more a namespaces. No subcommands, no packages,
+--      no targets.
 --
---    * no need to write specific build rules, one rule for hs, one for rs, one
---    for scm, and so on
+--    * No need to write specific build rules. One rule for hs, one for rs, one
+--      for scm, and so on.
 --
---    * no need to distinguish between exe and lib, just have a single output,
---    or figure it out automatically
+--    * No need to distinguish between exe and lib because we only build
+--      exes; 'libs' are just source files in the tree.
 --
---    * never concerned with deployment/packaging - leave that to another tool
+--    * Never concerned with deployment/packaging - leave that to another tool
 --      (scp? tar?)
 --
---    * local dev builds should be preserved, while remote nix builds are used
---    for the final package
+--    * Ability to do local dev builds should be preserved, while remote nix
+--      builds are used for the final package.
 --
 -- == Features
 --
---    * namespace maps to filesystem
+--    * Namespace maps to filesystem
 --
 --        * no need for `bild -l` for listing available targets.
 --          Use `ls` or `tree`
 --
 --        * you build namespaces, not files/modules/packages/etc
 --
---    * namespace maps to language modules
+--    * Namespace maps to language modules
 --
---        * build settings can be set in the file comments
+--        * build settings can be set in the file comments, or special 'bild'
+--          args
 --
 --    * pwd is always considered the the source directory,
 --      no `src` vs `doc` etc.
 --
---    * build methods automaticatly detected with file extensions
+--    * Build rules automaticatly detected from file extensions
 --
---    * flags modify the way to interact with the build, some ideas:
+--    * Flags modify the way to interact with the build, some ideas:
 --
 --        * -p = turn on profiling
 --
 --        * -o = optimize level
 --
---    * the build is planned out with an analysis, which can be viewed
+--    * The build is planned out with an analysis, which can be viewed
 --      beforehand with `--json`. The analysis includes compiler flags, which
 --      can be used in `repl` for testing compilation locally.
 --
+--    * (WIP) Nix is used by default to build everything on a remote build
+--      machine, but local, non-Nix builds can be accomplished with `--dev`.
+--
 -- == Example Commands
 --
 -- > bild [opts] <target..>
@@ -78,10 +83,16 @@
 -- we list the deps in comments in the target file, like:
 --
 -- > -- : sys cmark
+-- > -- : sys libssl
+--
+-- The name is used to lookup the package in `nixpkgs.pkgs.<name>`. Only one
+-- package can be listed per line. Language-level deps can automatically
+-- determined by passing parsed import statements to a package database, eg
+-- `ghc-pkg find-module`. If such a package database is not available, we either
+-- keep a hand-written index that maps imports to packages, or we just list the
+-- name of the package with:
 --
--- The name is used to lookup the package in `nixpkgs.pkgs.<name>`.
--- Language-level deps can automatically determined by passing parsed import
--- statements to a package database, eg `ghc-pkg find-module`.
+-- > -- : dep package
 --
 -- The output executable is named with:
 --
@@ -99,7 +110,7 @@
 -- and really only needs to be done in the entrypoint module anyway.
 --
 -- Local module deps are included by just giving the repo root to the underlying
--- compiler for the target, and the compiler does work of walking the source
+-- compiler for the target, and the compiler does the work of walking the source
 -- tree.
 module Biz.Bild where