Reorganise files

.devcontainer/README.md

@@ -1,71 +1,10 @@
 # Dev Containers
 
-These Dev Containers are based on the same docker images that are used to build
-the *statically linked* Linux amd64 and arm64 binary releases of pandoc.
-
-Those multi-arch (`linux/amd64`, `linux/arm64/v8`) docker images themselves are
-based on Alpine Linux and contain *unofficial* builds of GHC.
-
-Only use the GHC available in the Dev Containers, because
-
-1. the *official* GHC bindists for Alpine Linux (`x86_64`) are just too buggy.
-2. there are currently (2023-08-28) no bindists for Alpine Linux (`AArch64`).
-
-Therefore, flags `--system-ghc` and `--no-install-ghc` are set system-wide in
-`/etc/stack/config.yaml`.
-
-## Usage
-
-For use with Github Codespaces, please follow the instruction at
-[Creating a codespace for a repository](https://docs.github.com/en/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository).
-
-For local/'remote host' usage with VS Code, please follow the instructions at
-[Developing inside a Container](https://code.visualstudio.com/docs/devcontainers/containers).
-
-### Persistence
-
-Data in the following locations is persisted:
-
-1. The user's home directory (`/home/vscode`)[^1]
-2. The Dev Container's workspace (`/workspaces`)
-
-[^1]: Alternatively for the root user (`/root`). Use with Docker/Podman in
-*rootless mode*.
-
-This is accomplished either via a *volume* or *bind mount* (or *loop device* on
-Codespaces) and is preconfigured.
-
-| **Codespaces: A 'Full Rebuild Container' resets the home directory!**<br>:information_source: This is never necessary unless you want exactly that. |
-|:----------------------------------------------------------------------------------------------------------------------------------------------------|
-
-## Install pandoc
-
-### Using cabal
-
-Addendum to [Installing pandoc &gt; Compiling from source &gt; Quick cabal method](../INSTALL.md#quick-cabal-method):
-
-Use
-`cabal build --ghc-options '-static -optl-static -optl-pthread' pandoc-cli` to
-build a *statically linked* `pandoc` executable that can run on any Linux
-machine of the same architecture.
-
-### Using stack
-
-See [Installing pandoc &gt; Compiling from source &gt; Quick stack method](../INSTALL.md#quick-stack-method)
-
-You may try
-`stack build --ghc-options '-static -optl-static -optl-pthread' pandoc-cli` to
-build a *statically linked* `pandoc` executable.  
-:information_source: This works on Alpine Linux/AArch64 but not x86_64[^2].
-
-[^2]: Most likely due to a bug in the GCC toolchain on Linux/x86_64 that was
-never fixed.  
-See [gcc - Haskell Stack Static Binary relocation R_X86_64_32 against `TMC_END' can not be used when making a shared object - Stack Overflow](https://stackoverflow.com/questions/41419102/haskell-stack-static-binary-relocation-r-x86-64-32-against-tmc-end-can-not/41427067)  
-and [Bug #640734 “crtbeginT.o needs to be recompiled with -fPIC” : Bugs : gcc-4.4 package : Ubuntu](https://bugs.launchpad.net/ubuntu/+source/gcc-4.4/+bug/640734)
+See [Pandoc's Dev Containers wiki page](https://github.com/jgm/pandoc/wiki/Dev-Containers)
 for more information.
 
-## Haskell Language Server (HLS)
-
-Choose `Manually via PATH` when asked the following question:
+## License
 
-<img width="520" alt="manageHLS" src="assets/screenshots/manageHLS.png">
+The code in this directory is not part of pandoc (the software) and, with the
+exceptions noted in [LICENSE](LICENSE), is distributed under the terms of the
+MIT License.

CONTRIBUTING.md

@@ -428,6 +428,17 @@ If you've written a useful pandoc [lua filter](lua-filters.html),
 you may want to consider submitting a pull request to the
 [lua-filters repository](https://github.com/pandoc/lua-filters).
 
+Dev Containers
+--------------
+
+A [Development Container] (or Dev Container for short) allows you to use a
+container as a full‑featured development environment.
+
+You can run Dev Containers locally/remotely (with VS Code) or create a
+[Codespace] for a branch in a repository to develop online.
+
+See [Pandoc's Dev Containers wiki page] for more information.
+
 [open issues]: https://github.com/jgm/pandoc/issues
 [closed issues]: https://github.com/jgm/pandoc/issues?q=is%3Aissue+is%3Aclosed
 [latest released version]: https://github.com/jgm/pandoc/releases/latest
@@ -457,3 +468,6 @@ you may want to consider submitting a pull request to the
 [status:more-discussion-needed]: https://github.com/jgm/pandoc/labels/status:more-discussion-needed
 [status:more-info-needed]: https://github.com/jgm/pandoc/labels/status:more-info-needed
 [stack]: https://github.com/commercialhaskell/stack
+[Development Container]: https://containers.dev
+[Codespace]: https://github.com/features/codespaces
+[Pandoc's Dev Containers wiki page]: https://github.com/jgm/pandoc/wiki/Dev-Containers