Add plain-text README file

cgit doesn't render Org files. My website will still have the html
version.

1 files changed, 137 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..85c4186
--- /dev/null
+++ b/README
@@ -0,0 +1,137 @@
+                               _________
+
+                                  CRUX
+
+                                Andinus
+                               _________
+
+
+Table of Contents
+_________________
+
+1 Documentation
+.. 1.1 Options
+..... 1.1.1 Crux
+..... 1.1.2 Unsplash Source
+.. 1.2 Cross-platform compatibility
+
+
+Crux is a wallpaper manager written in Perl, currently it supports
+fetching from Unsplash Source.
+
+I have previously written [Cetus] which supports /Bing Photo of the Day/
+& /NASA Astronomy Picture of the Day/. I plan to port all to features to
+Crux someday.
+
+*Tested on*:
+- OpenBSD 6.7
+  - Perl v5.30
+
+
+[Cetus] https://andinus.nand.sh/cetus/
+
+
+1 Documentation
+===============
+
+1.1 Options
+~~~~~~~~~~~
+
+1.1.1 Crux
+----------
+
+* 1.1.1.1 debug
+
+  This will print additional information that'll help you to debug the
+  code. You might see multiple Unveil warnings on non-OpenBSD systems,
+  ignore them.
+
+  $response received from the api will also be printed.
+
+
+* 1.1.1.2 help
+
+  Prints quick help information listing all the options & a small
+  description.
+
+
+1.1.2 Unsplash Source
+---------------------
+
+  Some options cannot be mixed, if you mix them then expect unexpected
+  results. It won't fail but can return photos that you didn't ask for.
+
+  For example, `--search nature --user test' - You might think this will
+  return an image from user "test" & related to "nature" but it won't!
+  It will either return an image related to "nature" or user "test"
+  because these options cannot be mixed. Look at [Unsplash Source] to
+  know more about the kind of queries that are valid.
+
+  I could write a check for invalid options but that would be
+  complicated so I didn't, it's easier to ignore invalid options & you
+  can always pass the `debug' option to see what query it constructed.
+
+  `--search nature --daily' - This is a valid set, I have written about
+  valid sets below, like under `daily' it's mentioned that you can pass
+  `search' option so read each description.
+
+
+[Unsplash Source] https://source.unsplash.com
+
+* 1.1.2.1 resolution
+
+  Default is "1920x1080", it doesn't check the value passed so make sure
+  you pass the correct value. This can be passed with any option, it
+  will be ignored if not applicable.
+
+
+* 1.1.2.2 search
+
+  Search accepts multiple space seperated values. It's passed directly
+  to the api.
+
+  *Note*: The feature to get space seperated values is marked as
+  experimental in Getopt::Long so the behaviour can change in future,
+  worse even get removed. To guarantee backwards compatibility pass each
+  value by itself like `--search rocky --search mountain', this is
+  equivalent to `--search rocky mountain'.
+
+
+* 1.1.2.3 featured
+
+  Only Unsplash curated images are returned if you pass `featured', this
+  can be passed along with `search'.
+
+
+* 1.1.2.4 user
+
+  This will return a random photo from given user.
+
+
+* 1.1.2.5 userlikes
+
+  Only returns random photo from user's likes, this is a boolean & can
+  be passed with `user' option.
+
+
+* 1.1.2.6 collection
+
+  Returns photos from a collection.
+
+
+* 1.1.2.7 daily, weekly
+
+  This will return a set random daily or weekly image. `user' & `search'
+  option can be passed to narrow the selection.
+
+
+1.2 Cross-platform compatibility
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  Crux should run on all supported platforms, there is OpenBSD specific
+  code but it's ignored on other platforms. To know more about how this
+  works read this page: [Cross-platform compatibility].
+
+
+[Cross-platform compatibility]
+https://andinus.nand.sh/projects/cross-platform-compatibility.html