Merge branch 'stable'

Author: mpilgrem

doc/README.md

@@ -0,0 +1,75 @@
+---
+title: Get involved
+---
+<div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
+
+# Get involved
+
+## Feedback and discussion
+
+* For general comments, feedback and support, please post to the
+  [Haskell Community](https://discourse.haskell.org/about).
+* For bugs, issues, or requests, please
+  [open an issue](https://github.com/commercialhaskell/stack/issues/new).
+* When using Stack Overflow, please use the
+  [haskell-stack](http://stackoverflow.com/questions/tagged/haskell-stack) tag.
+
+## How to contribute to the maintenance or development of Stack
+
+A [guide](../CONTRIBUTING.md) is provided to help potential contributors to the
+Stack project.
+
+If you have already installed a version of Stack and the
+[Git application](https://git-scm.com/) the followings steps should get you
+started with building Stack from source with Stack:
+
+1.  Clone the `stack` repository from GitHub with the command:
+
+    ~~~text
+    git clone https://github.com/commercialhaskell/stack.git
+    ~~~
+
+2.  Change the current working directory to the cloned `stack` directory with
+    the command:
+
+    ~~~text
+    cd stack
+    ~~~
+
+3.  Build the `stack` executable using a preexisting installation of Stack with
+    the command:
+
+    ~~~text
+    stack build
+    ~~~
+
+4.  Once the `stack` executable has been built, check its version with the
+    command:
+
+    ~~~text
+    stack exec -- stack --version
+    ~~~
+
+    Make sure the version is the latest one.
+
+5.  In the GitHub repository's issue tracker, look for issues tagged with
+    [newcomer friendly](https://github.com/commercialhaskell/stack/issues?q=is%3Aopen+is%3Aissue+label%3a%22newcomer+friendly%22)
+    and
+    [awaiting pull request](https://github.com/commercialhaskell/stack/issues?q=is%3Aopen+is%3Aissue+label%3A%22awaiting+pull+request%22)
+    labels.
+
+If you need to check your changes quickly command:
+
+~~~text
+stack repl
+~~~
+
+and then, at the REPL's prompt, command:
+
+~~~text
+:main --stack-root=<path_to_root> --stack-yaml=<path_to_stack.yaml> <COMMAND>
+~~~
+
+This allows you to set a special Stack root (instead of the default Stack root)
+and to target your commands at a particular `stack.yaml` file instead of the one
+found in the current directory.

doc/community/index.md

@@ -44,7 +44,7 @@ currently four snapshot types:
 * No snapshot, just use packages shipped with the compiler. For GHC this looks
   like `snapshot: ghc-9.6.5`
 * Custom snapshot, via a URL or relative file path. For further information, see
-  the [snapshot and package location](../../topics/pantry.md) documentation.
+  the [snapshot location](../../topics/snapshot_location.md) documentation.
 
 Each of these snapshots will also determine what constraints are placed on the
 compiler version. See the [compiler-check](non-project.md#compiler-check) option
@@ -122,7 +122,8 @@ A Pantry package location is one or three different kinds of sources:
 * a Git or Mercurial repository.
 
 For further information on the format for specifying a Pantry package location,
-see the [Pantry](../../topics/pantry.md) documentation. For example:
+see the [package location](../../topics/package_location.md) documentation. For
+example:
 
 ~~~yaml
 extra-deps:
@@ -314,7 +315,95 @@ custom-preprocessor-extensions:
 - erb
 ~~~
 
-TODO: Add a simple example of how to use custom preprocessors.
+??? example "Use of a custom preprocessor"
+
+    The [Ruby](https://www.ruby-lang.org/en/) programming language provides
+    [`erb`](https://docs.ruby-lang.org/en/master/ERB.html) at the command line.
+    `erb` provides a templating system for Ruby. The following example uses
+    `erb` as a custom preprocessor.
+
+    The example is a single-package project with a customised `Setup.hs`, which
+    Stack will use to build:
+    ~~~haskell
+    {-# LANGUAGE CPP #-}
+
+    module Main
+      ( main
+      ) where
+
+    import           Distribution.Simple ( defaultMainWithHooks, simpleUserHooks )
+    import           Distribution.Simple.PreProcess
+                       ( PreProcessor (..), mkSimplePreProcessor, unsorted )
+    import           Distribution.Simple.UserHooks ( UserHooks (..) )
+    import           Distribution.Types.BuildInfo ( BuildInfo )
+    import           Distribution.Types.ComponentLocalBuildInfo
+                       ( ComponentLocalBuildInfo )
+    import           Distribution.Types.LocalBuildInfo ( LocalBuildInfo )
+    import           System.Process ( readCreateProcess, proc, shell )
+
+    main :: IO ()
+    main = defaultMainWithHooks simpleUserHooks
+      { hookedPreProcessors = [("erb", runRuby)]
+      }
+
+    runRuby ::
+         BuildInfo
+      -> LocalBuildInfo
+      -> ComponentLocalBuildInfo
+      -> PreProcessor
+    runRuby _ _ _ = PreProcessor
+      { platformIndependent = True
+      , ppOrdering = unsorted
+      , runPreProcessor = mkSimplePreProcessor $ \erbFile fout verbosity ->
+          readCreateProcess (erbProcess erbFile) "" >>= writeFile fout
+      }
+     where
+       erbProcess erbFile =
+    #if defined(mingw32_HOST_OS)
+         shell $ "erb " <> erbFile
+    #else
+         proc "erb" [erbFile]
+    #endif
+    ~~~
+
+    The example has a package description file (`package.yaml`) that specifies a
+    `Custom` build type:
+    ~~~yaml
+    spec-version: 0.36.0
+    name: my-package
+    version: 0.1.0.0
+    build-type: Custom
+
+    dependencies: base
+
+    custom-setup:
+      dependencies:
+      - base
+      - Cabal
+      - process
+
+    library:
+      source-dirs: src
+      generated-exposed-modules: MyModule
+    ~~~
+
+    The example has a `src/MyModule.erb` file that will be preprocessed to
+    create Haskell source code:
+    ~~~text
+    module MyModule where
+
+    <% (1..5).each do |i| %>
+    test<%= i %> :: Int
+    test<%= i %> = <%= i %>
+    <% end %>
+    ~~~
+
+    The example has a project-level configuration file (`stack.yaml`):
+    ~~~yaml
+    snapshot: lts-22.30
+    custom-preprocessor-extensions:
+    - erb
+    ~~~
 
 ## extra-package-dbs