From 52d65276a47e24e51ee0de179f540df740f5d08c Mon Sep 17 00:00:00 2001
From: cos <cos>
Date: Sun, 15 Oct 2023 15:38:27 +0200
Subject: Update documentation

---
 .gitignore      |  4 ++++
 FAQ.md          |  6 ++++++
 README.md       | 26 ++++++++++++++++++++++++++
 RELEASE.md      | 22 ++++++++++++++++++++++
 doc/preseed.txt |  2 +-
 5 files changed, 59 insertions(+), 1 deletion(-)
 create mode 100644 .gitignore
 create mode 100644 FAQ.md
 create mode 100644 RELEASE.md

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..c407bc8
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,4 @@
+*.html
+preseed-*.zip
+release.sh
+snapshot-*
diff --git a/FAQ.md b/FAQ.md
new file mode 100644
index 0000000..ec571e8
--- /dev/null
+++ b/FAQ.md
@@ -0,0 +1,6 @@
+**Q: I get 'fatal: dumb http transport does not support shallow capabilities'**
+
+**A:** If this is when using vim-plug, it's because it needs to be configured
+with `let g:plug_shallow = 0` for that plugin manager to work. You could also
+switch protocol by cloning from _ssh://anonymous@git.netizen.se/vim-preseed_
+which does support shallow repository operations.
diff --git a/README.md b/README.md
index 97a368f..5d3a4a0 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,30 @@
+vim-preseed
+===========
 A filetype plugin for [vim][] to add syntax highlighting to  Debian [preseed][]
 files.
 
+Install
+-------
+Use your preferred procedure, just as for installing any plugin. There should
+be no special steps required. Please see ':help plugin' if unsure.
+
+Unless having any other preference, the simplest installation method is likely
+to merely do something along the lines of:
+
+    mkdir -p ~/.vim/pack/git-plugins/start/ || :
+    cd ~/.vim/pack/git-plugins/start/
+    git clone https://git.netizen.se/vim-preseed
+
+It might be possible to use a plugin manager of some sorts. Some quirks are in
+the [Frequently Asked Questions](FAQ.md).
+
+About
+-----
+Vim v9.0 on debian 12 bookworm and v7.3 on FreeDOS 1.3 are tested. That means
+it is known be usable with at least the contemporary stable release of its
+primarily targeted environment, as well as a more than decade old release on an
+today rather fringe platform. Hopefully that equates to everywhere reasonable.
+
 This plugin seems to work for me. Yet this is my first attempt at publishing  a
 vim plugin. I am fully aware the pattern matching should be possible to do more
 cleanly.  One could also imagine wishing to use the WarningMsg group, and place
@@ -8,6 +32,8 @@ known broken syntax (such as leading spaces in values) in it. It is unlikely to
 be any further feature development on this by me, but my aim is to maintain the
 code. Patches are welcome, as is positive and constructive feedback.
 
+License
+-------
 Provided under MIT No Attribution License. Relicensing will be immediately done
 on request,  if needed for inclusion in the vim official source tree or as part
 of its debian package.
diff --git a/RELEASE.md b/RELEASE.md
new file mode 100644
index 0000000..1892d6e
--- /dev/null
+++ b/RELEASE.md
@@ -0,0 +1,22 @@
+As this plugin is trivial there are no proper releases, and thus no real
+release numbers.
+
+For the purpose of publishing the script to [vimorg][] the release number is
+simply the sequential number of the commit of which the uploaded archive was
+generated from. The process is as follows:
+
+    _base='https://git.netizen.se'
+    _repo='vim-preseed'
+    _hash=$( git ls-remote "$_base/$_repo" HEAD | cut -c1-7 )
+    _c_no=$( git log --oneline "$_hash" | wc -l )
+    _date=$( date '+%Y, %B %d' )
+    _name="${_repo%-main}"; _name="${_name#vim-}"
+    wget "$_base/$_repo/snapshot/$_repo-main.zip"
+    7zz rn "$_repo-main.zip" "$_repo-main" "$_name"
+    mv "$_repo-main.zip" "$_name-$_c_no.zip"
+    echo "export of commit $_c_no ($_hash) from $_base/$_repo. $_date." \
+        > "snapshot-$_hash.txt"
+    7zz a "$_name.zip" "snapshot-$_hash.txt"
+    unset _base _repo _name _hash _init _c_no _date
+
+[vimorg]: https://www.vim.org/scripts/
diff --git a/doc/preseed.txt b/doc/preseed.txt
index 6b6767e..5603423 100644
--- a/doc/preseed.txt
+++ b/doc/preseed.txt
@@ -2,7 +2,7 @@
 
                                                        *ft-preseed-syntax*
 Preseed files enable automated installation of the Debian operating systems and
-some of its derivatives. As the preseed files is typically either have "txt" or
+some of its derivatives. As the preseed files typically either have "txt" or
 simply no file extension, filetype detection relies on their first line being
 `#_preseed_V1`.
 
-- 
cgit v1.2.3