plan tables and consider cli implications

diff --git a/cli.md b/cli.md
index cc48e0f5ff43b89b22f0301ca4ea19f7d1ddf878..89fabc5fc1b7eab3c762d954470dff6a4f20a621 100644 (file)
--- a/cli.md
+++ b/cli.md
@@ -10,6 +10,7 @@ Separate by things that act on `feed` and things that act on `entry`.
 2. Remove feed from feed list.
 3. List (unread) entries from feed list. 
 
+
 ## Feed Actions
 
 Feed options:
@@ -75,11 +76,20 @@ Needs to pull CSS as well as HTML. Or, define your own styling...
 
 ## Filters
 
-**Remember** Feed filters are not necessarily the same as entry filters.
-
 **Remember**, you can always `grep` as a way of filtering rows. 
 You can always `cut` as a way of filtering columns.
 
+This requires a good deal of CLI design.
+
+* Do I want to specify entry/feed number as positional arguments? Do I want to 
+  specify them as a filter? 
+    * Maybe "filter" is the wrong term. Maybe "selector" is better. And I don't 
+      see why number should be any different than any other selector.
+    * If we use the notion of selectors, how do we handle and/or/not?
+* Since entry filters ~= feed filters, do I want to put the filters on each
+  command (ex: `nom entry show [filters]`) or do I want to put them on `entry` 
+  and `show` (ex: `nom entry [filters] show`)?
+
 Hmm... It would be cool to batch update using filters. For example,
 
 ``` bash

diff --git a/tables.md b/tables.md
new file mode 100644 (file)
index 0000000..aecebf1
--- /dev/null
+++ b/tables.md
@@ -0,0 +1,75 @@
+# Tables
+
+Nom needs to maintain state, such as what feeds are you tracking, what aliases
+you have associated with each feed, what entries, you have read, and so on. 
+This page specs out the design of tables that manage that information.
+
+For simplicity, transparency, and portability, we will start with file-based 
+IO. Something like CSV format. If performance becomes an issue, we can switch 
+to a SQLite database or something like that.
+
+## Feed List
+
+A feed list curates which feeds to poll. At its most basic, it contains a URL.
+But some additional metadata could be helpful too.
+
+| Feed Number |         URL          | Alias | ... |
+| ------------| -------------------- | ----- | --- |
+|      1      | https://url/to/feed1 | feed1 | ... |
+|      2      | https://url/to/feed2 | feed2 | ... |
+
+For now, let's focus on URLs and Aliases:
+
+1. A URL is an unambiguous specification to a feed.
+2. An alias is a user-specified handle for a feed. It's helpful in commands 
+   when you need to reference a feed, but don't want to type the entire URL.
+
+## Entry List
+
+An entry list is more involved than a feed list because it considers state, 
+such as whether or not an entry has been viewed or not.
+
+| Entry Number |       Feed Url       | Feed Alias |          Url          | Date (Updated) | Summary | Viewed | 
+| ------------ | -------------------- | ---------- | --------------------- | -------------- | ------- | ------ | 
+|      1       | https://url/to/feed1 |    feed1   | https://url/to/entry1 |    ISO-8601    | This entry expands upon this summary! | True |
+|      2       | https://url/to/feed1 |    feed1   | https://url/to/entry2 |    ISO-8601    | This entry's for another summary!     | False |
+
+There are three scenarios that determine whether an entry shows up in our 
+reading list or not:
+
+1. The entry is not in the entry list. (It does NOT appear in our reading list.)
+2. The entry is in our list; it is marked "viewed." (It does NOT appear
+   in our reading list.)
+3. The entry is in our list; it is marked "unviewed". (It appears in our
+   reading list.)
+
+You might think, "Great! we could just delete an entry from the entry list 
+when we have read the article!" But the usual way to create an entry list is 
+to read one or more feeds and add items to the entry list. If we simply remove 
+an item, it will reappear when we update the list. So we need to keep a record 
+of the entry (at least until it has been dropped from the feed's buffer).
+
+## Feed/Entry Number
+
+Sometimes you need to interact with a single feed or entry. Feeds have aliases,
+which make sense because you will interact with the same feed many times over 
+the course of its lifetime. Entries, however, are short-lived. Adding an alias 
+to an entry isn't generally worth it. This is where the entry number comes into
+play. 
+
+Whenever you need to specify an individual entry, you can do so by specifying 
+its entry number. Think of an entry number as an *ad hoc* alias. For example,
+consider the entry list from earlier. Then
+
+`nom entry mark viewed 1`
+
+is equivalent to
+
+`nom entry mark viewed https://url/to/entry1`.
+
+**NOTE:** An entry number is subject to change whenever the number of entries 
+changes. Before performing an operation, ensure that the entry number aligns 
+with the entry that you *think* that you are operatingon.
+
+As entries are added to the entry list, you use up more entry numbers. As 
+entries are removed from the entry list, you reclaim entry numbers. 
\ No newline at end of file