Merge branch 'wip/docs'

1 files changed, 30 insertions, 0 deletions

diff --git a/docs/readme.md b/docs/readme.md
new file mode 100644
index 0000000..99cbb24
--- /dev/null
+++ b/docs/readme.md
@@ -0,0 +1,30 @@
+# docs
+
+This folder contains the project documentation in [AsciiDoc][asciidoc] format.
+To compile the documents, make sure you have [Ruby][rubydl] and the
+dependencies installed by running the `bundle` command in this folder. A
+makefile is provided for convenience.
+
+## notes for writers
+
+- "I<sup>2</sup>C" is written as `I^2^C`
+- "C++" is written as `{cpp}`
+- please give cross references, links, image files, figure ids, etc. meaningful
+  names
+
+## todo (low priority)
+
+- cross-references to glossary
+
+## for later reference
+
+### get citation keys from .docx file
+
+```
+$ unar file.docx
+$ grep -o 'CITATION[^<]\+' file/word/document.xml | awk '!x[$2]++ { i++; print "[" i "] " $2 }'
+```
+
+[rubydl]: https://www.ruby-lang.org/en/documentation/installation/
+[asciidoc]: https://asciidoc.org/
+