Add plain-text README file

cgit doesn't render Org files. I think I'll add `*.org' to
`.gitignore' & export to plain text for README. My website will still
have the html version.

3 files changed, 297 insertions, 219 deletions

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..143d814
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+*.org
diff --git a/README b/README
new file mode 100644
index 0000000..bfe34bc
--- /dev/null
+++ b/README
@@ -0,0 +1,296 @@
+                               ━━━━━━━━━
+                                  ARA
+
+                                Andinus
+                               ━━━━━━━━━
+
+
+Table of Contents
+─────────────────
+
+1 Documentation
+.. 1.1 Options
+.. 1.2 Cross-platform compatibility
+2 Demo Videos
+
+
+Ara is a simple cli program that prints Covid-19 stats. Currently it
+only prints India's Covid stats.
+
+
+1 Documentation
+═══════════════
+
+  `ara' by default will first look for the file in `$XDG_CACHE_HOME', if
+  that is not set then `HOME/.cache' is used, the file name is assumed
+  to be `ara.json', there is currently no option to override this or the
+  full path.
+
+  If you run `ara' on OpenBSD then it should use `OpenBSD::Unveil'.
+
+  Default logic is to check if the file is available locally & if it's
+  not older than 8 minutes, in any other case it fetches the latest
+  data. This can be controlled with `local' & `latest' option.
+
+  The file is downloaded over a secure connection & the server's
+  identity is verified.
+
+
+1.1 Options
+───────────
+
+1.1.1 local
+╌╌╌╌╌╌╌╌╌╌╌
+
+  This option forces `ara' to use the data available locally, it will
+  only override this option when the file doesn't exist on disk.
+
+
+1.1.2 latest
+╌╌╌╌╌╌╌╌╌╌╌╌
+
+  This will force `ara' to fetch the latest data.
+
+  *Note*: `local' & `latest' option cannot be used together, `ara' will
+  print a warning & latest option will be ignored.
+
+
+1.1.3 notes
+╌╌╌╌╌╌╌╌╌╌╌
+
+  Only state notes will be printed if this option is passed.
+
+
+1.1.4 rows
+╌╌╌╌╌╌╌╌╌╌
+
+  `rows' option takes an integer as argument which can be passed as
+  `--rows n', where `n' is an integer.
+
+  `ara' will only print maximum these many number of rows, if you pass 0
+  or a negative number then `ara' will ignore it & print all the rows.
+
+
+1.1.5 showdelta
+╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
+
+  This will show delta values for every row, default is to show delta
+  only on rows that were updated "Today".
+
+
+1.1.6 nodelta
+╌╌╌╌╌╌╌╌╌╌╌╌╌
+
+  This will remove delta values from every column.
+
+
+1.1.7 nototal
+╌╌╌╌╌╌╌╌╌╌╌╌╌
+
+  This will remove the "Total" or "India" row from the table.
+
+  `hide' option should be used for this purpose, this option is only
+  kept for backwards compatibility.
+
+
+1.1.8 nowords
+╌╌╌╌╌╌╌╌╌╌╌╌╌
+
+  "Confirmed", "Recovered" & "Deaths" column format numbers in words.
+  For example, "1.6 lakhs" instead of "1,60,000" which makes it easier
+  to read. This option will disable this behaviour.
+
+  "Active" column doesn't format numbers in words because it's alignment
+  is set as "right" & formatting it this way doesn't look good. There is
+  currently no option to change this behaviour.
+
+
+1.1.9 hide
+╌╌╌╌╌╌╌╌╌╌
+
+  `hide' is able to hide states & columns from the table, the values
+  should be space seperated like `--hide active "last updated"
+  recovered'. These are case sensitive & should be lowercase.
+
+  Arguments can be passed as they're printed, for example `--hide "jammu
+  and kashmir"' is equivalent to `--hide jk' because "JK" is what's
+  printed on the table.
+
+  Only "States" & "Notes" column cannot be hidden, `ara' will print a
+  warning if you try to do so.
+
+  *Note*: "updated" is aliased to "last updated", so you can pass
+  `--hide updated' & it would hide the "last updated" column.
+
+  *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 `--hide jk --hide active', this is equivalent to
+  `--hide jk active'.
+
+
+◊ 1.1.9.1 Implementation
+
+  `%hide' hash is created from `@to_hide' which was created from user
+  arguments by `Getopt::Long'.
+
+  ┌────
+  │ undef @hide{ @to_hide }
+  │     if scalar @to_hide;
+  └────
+
+  `%hide' contains values of `@to_hide' as keys & the value to those
+  keys is not defined, hence `undef'. This one line says Perl to "undef
+  these keys from the hash `%hide'" where these refers to the values of
+  `@to_hide'. This will fail if `@to_hide' is empty so we have to check
+  for that.
+
+  Alternatively we can do `@hide { @to_hide } = ()' which works even if
+  `@to_hide' is empty & does the same thing otherwise, this looks more
+  cryptic so I use the first way.
+
+  To check if a specific column is to be hidden or not we use `exists'
+  like `exists $hide{something}'.
+
+  There are other ways of doing this & maybe those would be better, I
+  didn't test which one was the best.
+
+
+  ◊ 1.1.9.1.1 Columns
+
+    To make `hide' work we put create `@columns' & push columns to it
+    unless the user has asked to hide it.
+    ┌────
+    │ my @columns;
+    │
+    │ push @columns, 'Confirmed' unless exists $hide{confirmed};
+    │ push @columns, 'Active'    unless exists $hide{active};
+    └────
+
+
+  ◊ 1.1.9.1.2 States
+
+    The whole block is skipped if the user has asked to hide the state.
+    As said above, statecode is also check if that's what is printed in
+    the table which is true only if `length $state > 16'. There is no
+    good reason for not checking statecode for everything.
+    ┌────
+    │ next
+    │     if exists $hide{lc $state}
+    │     # User sees the statecode if length $state > 16 so we also match
+    │     # against that.
+    │     or ( length $state > 16
+    │              and exists $hide{lc $statewise->[$i]{statecode}});
+    └────
+
+
+1.1.10 show
+╌╌╌╌╌╌╌╌╌╌╌
+
+  `show' also accepts space seperated values & just like in `hide''s
+  case it's experimental & can change in future.
+
+  `show' will only show states that are passed. For example, `--show jk'
+  will only print data for Jammu & Kashmir. If both `show' & `hide' is
+  used for states then `hide' is ignored. `show' for states can be used
+  with `hide' for columns.
+
+
+◊ 1.1.10.1 Implementation
+
+  `show''s implementation is similar to `hide''s. `%show' hash is
+  created from `@to_show'.
+
+  ┌────
+  │ undef @show{ @to_show }
+  │     if scalar @to_show;
+  └────
+
+  If user has used `show' then `hide' is ignored, this is achieved by an
+  if-else block. This also means that invalid values in state would
+  cause `hide' to be ignored, for example passing `--show invalid'
+  wouldn't match anything but `hide' will still be ignored. This is
+  intentional.
+
+  ┌────
+  │ if ( scalar @to_show ) {
+  │     next
+  │         unless exists $show{lc $state}
+  │         or ( length $state > 16
+  │              and exists $show{lc $statewise->[$i]{statecode}});
+  │ } else { ... }
+  └────
+
+
+1.1.11 help
+╌╌╌╌╌╌╌╌╌╌╌
+
+  `help' will print help for `ara' which will have little information
+  about all these options listed above.
+
+  • `nototal' was removed from `help' because `hide' option does the
+    same thing & is recommended.
+
+
+1.2 Cross-platform compatibility
+────────────────────────────────
+
+  Previously `ara' had OpenBSD specific code & would simply fail to run
+  on other OSes, now it runs on all platforms. There is still OpenBSD
+  specific code but it's used only when `ara' detects to be running on
+  OpenBSD.
+
+  ┌────
+  │ use constant is_OpenBSD => $^O eq "openbsd";
+  │ require OpenBSD::Unveil
+  │     if is_OpenBSD;
+  │ sub unveil {
+  │     if (is_OpenBSD) {
+  │         return OpenBSD::Unveil::unveil(@_);
+  │     } else {
+  │         return 1;
+  │     }
+  │ }
+  └────
+
+  `is_OpenBSD' is a constant so the if-else block is optimized at
+  compile time. Another way would be to define the sub inside the
+  if-else block which is what I did initially but that is not the same
+  thing as this.
+
+  You cannot define sub like that in Perl because this step happens at
+  compile time & so the if-else block is ignored, which means the code
+  will be equivalent to else block being true all the time because
+  that's what comes later.
+
+  ┌────
+  │ if (is_OpenBSD) {
+  │     require OpenBSD::Unveil;
+  │     OpenBSD::Unveil->import;
+  │ } else {
+  │     sub unveil { return 1; }
+  │ }
+  └────
+
+  Above code block will override the unveil sub to be `return 1;'
+  everytime, this was fixed in commit
+  `245aebe3da915afc0feafc7257f025e2e66a987f'.
+
+  This will still fail on OpenBSD if users don't have `OpenBSD::Unveil'
+  in `@INC', this shouldn't be an issue with Perl in base but if user
+  runs custom Perl then it might not be in `@INC', in that case user is
+  expected to fix this by adding the path to `OpenBSD::' in `@INC'.
+
+
+2 Demo Videos
+═════════════
+
+  • [Ara 2020-06-14] (new options)
+  • [Ara 2020-06-06]
+
+
+[Ara 2020-06-14]
+https://diode.zone/videos/watch/95868534-8aae-497b-806e-5766236bb058
+
+[Ara 2020-06-06]
+https://diode.zone/videos/watch/03be044d-6ab7-4f01-8769-0084674dec93
diff --git a/README.org b/README.org
deleted file mode 100644
index 0e83ccf..0000000
--- a/README.org
+++ /dev/null
@@ -1,219 +0,0 @@
-#+HTML_HEAD: <link rel="stylesheet" href="../static/style.css">
-#+HTML_HEAD: <link rel="icon" href="../static/favicon.png" type="image/png">
-#+EXPORT_FILE_NAME: index
-#+TITLE: Ara
-
-Ara is a simple cli program that prints Covid-19 stats. Currently it
-only prints India's Covid stats.
-
-| Project Home    | [[https://andinus.nand.sh/ara/][Ara]]           |
-| Source Code     | [[https://git.tilde.institute/andinus/ara/][Andinus / Ara]] |
-| GitHub (Mirror) | [[https://github.com/andinus/ara/][Ara - 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.
-
-| Demo Videos    |
-|----------------|
-| [[https://diode.zone/videos/watch/95868534-8aae-497b-806e-5766236bb058][Ara 2020-06-14]] |
-| [[https://diode.zone/videos/watch/03be044d-6ab7-4f01-8769-0084674dec93][Ara 2020-06-06]] |
-
-* Documentation
-=ara= by default will first look for the file in =$XDG_CACHE_HOME=, if that
-is not set then =HOME/.cache= is used, the file name is assumed to be
-=ara.json=, there is currently no option to override this or the full
-path.
-
-If you run =ara= on OpenBSD then it should use =OpenBSD::Unveil=.
-
-Default logic is to check if the file is available locally & if it's not
-older than 8 minutes, in any other case it fetches the latest data. This
-can be controlled with =local= & =latest= option.
-
-The file is downloaded over a secure connection & the server's identity
-is verified.
-** Options
-*** local
-This option forces =ara= to use the data available locally, it will only
-override this option when the file doesn't exist on disk.
-*** latest
-This will force =ara= to fetch the latest data.
-
-*Note*: =local= & =latest= option cannot be used together, =ara= will print a
-warning & latest option will be ignored.
-*** notes
-Only state notes will be printed if this option is passed.
-*** rows
-=rows= option takes an integer as argument which can be passed as =--rows
-n=, where =n= is an integer.
-
-=ara= will only print maximum these many number of rows, if you pass 0 or
-a negative number then =ara= will ignore it & print all the rows.
-*** showdelta
-This will show delta values for every row, default is to show delta only
-on rows that were updated "Today".
-*** nodelta
-This will remove delta values from every column.
-*** nototal
-This will remove the "Total" or "India" row from the table.
-
-=hide= option should be used for this purpose, this option is only kept
-for backwards compatibility.
-*** nowords
-"Confirmed", "Recovered" & "Deaths" column format numbers in words. For
-example, "1.6 lakhs" instead of "1,60,000" which makes it easier to
-read. This option will disable this behaviour.
-
-"Active" column doesn't format numbers in words because it's alignment
-is set as "right" & formatting it this way doesn't look good. There is
-currently no option to change this behaviour.
-*** hide
-=hide= is able to hide states & columns from the table, the values should
-be space seperated like =--hide active "last updated" recovered=. These
-are case sensitive & should be lowercase.
-
-Arguments can be passed as they're printed, for example =--hide "jammu
-and kashmir"= is equivalent to =--hide jk= because "JK" is what's printed
-on the table.
-
-Only "States" & "Notes" column cannot be hidden, =ara= will print a
-warning if you try to do so.
-
-*Note*: "updated" is aliased to "last updated", so you can pass =--hide
-updated= & it would hide the "last updated" column.
-
-*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 =--hide jk --hide active=, this is equivalent to
-=--hide jk active=.
-
-**** Implementation
-=%hide= hash is created from =@to_hide= which was created from user
-arguments by =Getopt::Long=.
-
-#+BEGIN_SRC perl
-undef @hide{ @to_hide }
-    if scalar @to_hide;
-#+END_SRC
-
-=%hide= contains values of =@to_hide= as keys & the value to those keys is
-not defined, hence =undef=. This one line says Perl to "undef these keys
-from the hash =%hide=" where these refers to the values of =@to_hide=. This
-will fail if =@to_hide= is empty so we have to check for that.
-
-Alternatively we can do =@hide { @to_hide } = ()= which works even if
-=@to_hide= is empty & does the same thing otherwise, this looks more
-cryptic so I use the first way.
-
-To check if a specific column is to be hidden or not we use =exists= like
-=exists $hide{something}=.
-
-There are other ways of doing this & maybe those would be better, I
-didn't test which one was the best.
-***** Columns
-To make =hide= work we put create =@columns= & push columns to it unless the
-user has asked to hide it.
-#+BEGIN_SRC perl
-my @columns;
-
-push @columns, 'Confirmed' unless exists $hide{confirmed};
-push @columns, 'Active'    unless exists $hide{active};
-#+END_SRC
-***** States
-The whole block is skipped if the user has asked to hide the state. As
-said above, statecode is also check if that's what is printed in the
-table which is true only if =length $state > 16=. There is no good reason
-for not checking statecode for everything.
-#+BEGIN_SRC perl
-next
-    if exists $hide{lc $state}
-    # User sees the statecode if length $state > 16 so we also match
-    # against that.
-    or ( length $state > 16
-             and exists $hide{lc $statewise->[$i]{statecode}});
-#+END_SRC
-*** show
-=show= also accepts space seperated values & just like in =hide='s case it's
-experimental & can change in future.
-
-=show= will only show states that are passed. For example, =--show jk= will
-only print data for Jammu & Kashmir. If both =show= & =hide= is used for
-states then =hide= is ignored. =show= for states can be used with =hide= for
-columns.
-**** Implementation
-=show='s implementation is similar to =hide='s. =%show= hash is created from
-=@to_show=.
-
-#+BEGIN_SRC perl
-undef @show{ @to_show }
-    if scalar @to_show;
-#+END_SRC
-
-If user has used =show= then =hide= is ignored, this is achieved by an
-if-else block. This also means that invalid values in state would cause
-=hide= to be ignored, for example passing =--show invalid= wouldn't match
-anything but =hide= will still be ignored. This is intentional.
-
-#+BEGIN_SRC perl
-if ( scalar @to_show ) {
-    next
-        unless exists $show{lc $state}
-        or ( length $state > 16
-             and exists $show{lc $statewise->[$i]{statecode}});
-} else { ... }
-#+END_SRC
-*** help
-=help= will print help for =ara= which will have little information about
-all these options listed above.
-
-- =nototal= was removed from =help= because =hide= option does the same thing
-  & is recommended.
-** Cross-platform compatibility
-Previously =ara= had OpenBSD specific code & would simply fail to run on
-other OSes, now it runs on all platforms. There is still OpenBSD
-specific code but it's used only when =ara= detects to be running on
-OpenBSD.
-
-#+BEGIN_SRC perl
-use constant is_OpenBSD => $^O eq "openbsd";
-require OpenBSD::Unveil
-    if is_OpenBSD;
-sub unveil {
-    if (is_OpenBSD) {
-        return OpenBSD::Unveil::unveil(@_);
-    } else {
-        return 1;
-    }
-}
-#+END_SRC
-
-=is_OpenBSD= is a constant so the if-else block is optimized at compile
-time. Another way would be to define the sub inside the if-else block
-which is what I did initially but that is not the same thing as this.
-
-You cannot define sub like that in Perl because this step happens at
-compile time & so the if-else block is ignored, which means the code
-will be equivalent to else block being true all the time because that's
-what comes later.
-
-#+BEGIN_SRC perl
-if (is_OpenBSD) {
-    require OpenBSD::Unveil;
-    OpenBSD::Unveil->import;
-} else {
-    sub unveil { return 1; }
-}
-#+END_SRC
-
-Above code block will override the unveil sub to be =return 1;= everytime,
-this was fixed in commit =245aebe3da915afc0feafc7257f025e2e66a987f=.
-
-This will still fail on OpenBSD if users don't have =OpenBSD::Unveil= in
-=@INC=, this shouldn't be an issue with Perl in base but if user runs
-custom Perl then it might not be in =@INC=, in that case user is expected
-to fix this by adding the path to =OpenBSD::= in =@INC=.