about summary refs log tree commit diff stats
diff options
context:
space:
mode:
-rw-r--r--.gitignore2
-rw-r--r--README137
-rw-r--r--README.org83
3 files changed, 139 insertions, 83 deletions
diff --git a/.gitignore b/.gitignore
index 37a09bc..caf146d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -29,3 +29,5 @@ cover_db/
 MYMETA.*
 
 /App-Crux-*
+
+*.org
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
diff --git a/README.org b/README.org
deleted file mode 100644
index ce41461..0000000
--- a/README.org
+++ /dev/null
@@ -1,83 +0,0 @@
-#+HTML_HEAD: <link rel="stylesheet" href="../static/style.css">
-#+HTML_HEAD: <link rel="icon" href="../static/favicon.png" type="image/png">
-#+OPTIONS: toc:nil
-#+EXPORT_FILE_NAME: index
-#+TITLE: Crux
-
-Crux is a wallpaper manager written in Perl, currently it supports
-fetching from Unsplash Source.
-
-Support for more sources is planned, I have previously written [[https://andinus.nand.sh/cetus/][Cetus]]
-which supports /Bing Photo of the Day/ & /NASA Astronomy Picture of the
-Day/. I plan to port all to features to Crux too.
-
-| Project Home    | [[https://andinus.nand.sh/crux/][Crux]]           |
-| Source Code     | [[https://git.tilde.institute/andinus/crux/][Andinus / Crux]] |
-| GitHub (Mirror) | [[https://github.com/andinus/crux/][Crux - GitHub]]  |
-
-*Tested on*:
-- OpenBSD 6.7
-  - Perl v5.30
-
-*Note* (OpenBSD users): If you're using a custom Perl install then add the
-path to =OpenBSD::= in @INC.
-
-* Documentation
-** Options
-*** Crux
-**** 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.
-**** help
-Prints quick help information listing all the options & a small
-description.
-*** 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 [[https://source.unsplash.com][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.
-**** 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.
-**** 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=.
-**** featured
-Only Unsplash curated images are returned if you pass =featured=, this can
-be passed along with =search=.
-**** user
-This will return a random photo from given user.
-**** userlikes
-Only returns random photo from user's likes, this is a boolean & can be
-passed with =user= option.
-**** collection
-Returns photos from a collection.
-**** daily, weekly
-This will return a set random daily or weekly image. =user= & =search=
-option can be passed to narrow the selection.
-** 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: [[https://andinus.nand.sh/projects/cross-platform-compatibility.html][Cross-platform compatibility]].