From 6d4fb4362223f2db9ca139cfff81facf01a7490e Mon Sep 17 00:00:00 2001
From: "reaction.la" <reaction.la@>
Date: Wed, 28 Aug 2024 11:20:36 +0000
Subject: [PATCH] two versions of README.md, one github markdown, and one
 pandoc markdown

---
 docs/rootDocs/README.md | 94 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 docs/rootDocs/README.md

diff --git a/docs/rootDocs/README.md b/docs/rootDocs/README.md
new file mode 100644
index 0000000..c860dcc
--- /dev/null
+++ b/docs/rootDocs/README.md
@@ -0,0 +1,94 @@
+---
+title: >-
+    README
+---
+
+[pre alpha documentation (mostly a wish list)](docs/index.htm)
+
+[copyright © and license](./license.txt)
+
+pre-requisite, Pandoc to build the html documentation from the markdown files.
+
+Windows pre-requisites:  Visual Studio and git-bash
+
+To obtain the source code from which the project can be built,
+including this README.html, from the bash command line (git-bash in windows).
+
+```bash
+git clone --recurse-submodules missing url
+```
+
+To build the docs, you need pandoc on the path.
+
+```bash2
+cd wallet/docs
+./mkdocs.sh
+```
+
+To configure and build the required third party libraries in windows, then
+build the program and run unit test for the first time, you need to have
+Visual studio build tools at  their default location)
+
+```bash2
+cd wallet
+./winConfigure.bat
+```
+
+Or, if you are in the command shell or power shell,
+
+```bat
+.\winConfigure.bat
+```
+
+After a pull from remote in which the submodules have changed, the pull
+fails to automatically update the submodules by default, and when you
+switch or checkout branches, the switch fails to automatically switch
+and checkout the brances.
+
+After a pull that gives you a status of modified submodules.
+
+```bash
+git submodule update --init --recursive --remote
+```
+
+After a checkout or branch switch that gives you a status of modified submodules.
+
+```bash
+git submodule update --recursive
+```
+
+The documentation is in pandoc flavored markdown, which is
+ conveniently edited in vscode with the `markdown lint` and `Pandoc`
+ extensions included and, if you have launched `code` in the docs directory,
+ with  `file/preferences/Extensions/Markdown/Styles` set to
+ `pandoc_templates\\style.css`, that being the style used by the `mkdocs.sh` documentation build script.
+
+ On Windows, if Git Bash and Pandoc has been installed, you should be
+ able to run this shell file in bash by double clicking on it.
+
+if you add the recommended repository configuration defaults to your local repository configuration
+
+```bash
+git config --local include.path ../.gitconfig
+```
+
+this will substantially mitigate the problem of submodules failing to
+update in pushes, pulls, checkouts, and switches.
+
+[cryptographic software is under attack]:./docs/setup/contributor_code_of_conduct.html#code-will-be-cryptographically-signed
+"Contributor Code of Conduct"
+{target="_blank"}
+
+It will, however, also implement signed commits, and insist you have set up a key pair as
+explained in the contributor code of conduct because [cryptographic software is under attack] from NSA
+entryists and shills, who seek to introduce backdoors.
+
+`.gitconfig` also adds several git aliases:
+
+1. `git lg` to display the git log with committer name from `.gitsigners` that corresponds to the public key
+1. `git graph` to graph the commit tree with the committer name from `.gitsigners` that corresponds to the public key
+1. `git alias` to display the git aliases.
+1. `git utcmt` to make a commit without revealing your time zone.
+
+[Pre alpha release](./RELEASE_NOTES.html), which means it does not yet work even well
+enough for it to be apparent what it would do if it did work.