diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rw-r--r-- | README | 137 | ||||
| -rw-r--r-- | README.org | 83 |
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]]. |