update text, add lots of TODOs

1 files changed, 75 insertions, 39 deletions

diff --git a/app/mmmfs/init.moon b/app/mmmfs/init.moon
index 68ce4f8..0a63fec 100644
--- a/app/mmmfs/init.moon
+++ b/app/mmmfs/init.moon
@@ -46,29 +46,43 @@ root = Fileder {
           ol table.unpack args
 
       append h1 'mmmfs', style: { 'margin-bottom': 0 }
+      -- @TODO: s/filesystem/a way of organizing files/g
       append p "a file and operating system to live in", style: { 'margin-top': 0, 'margin-bottom': '1em' }
 
+      -- @TODO: motivation / outline problem + need
+      -- @TODO: quote http://pchiusano.github.io/2013-05-22/future-of-software.html on Applications
+
       append p do
         fileder = footnote "fileder: file + folder. 'node', 'table' etc. are too general to be used all over."
-        child = footnote "fileders can have multiple values, like the mentioned script, but these are not considered
-          children of the fileder, as they are not fileders themselves. One fileder can have many values of different
-          types/keys associated, but these have unspecified schemas and don't nest. In addition it can have many
-          children, which are fileders themselves and can nest, but they are not labelled."
-
-        "in mmmfs, directories are files and files are directories, or something like that.
-        Listen, I don't really know yet either. The idea is that every node knows how to display it's contents;
-        so for example your 'Pictures' fileder", fileder, " contains a script within itself that renders
-        all the picture files you put into it at the children level", child, "."
-
-      append p "a fileder should also be responsible for how it's children are sorted, filtered and interacted with.
-        For example you should be able to create a fileder that is essentially a 'word document' equivalent: it could
-        contain images, websites, links and of course text as children and let you reorder, layout and edit them in
-        it's own edit interface."
-
-      append p "a picture fileder could have an alternate slideshow view (whoops - built that. Click on the 'gallery'
-        example below), or one that shows your geotagged images on a world map, if you really want that.
-        Maybe you could build a music folder that contains links to youtube videos, spotify tracks and just plain mp3
-        files, and the folder knows how to play them all."
+
+        -- @TODO: mention:
+        -- can store anything - text, an image, a link to a website or video,
+        -- a program and anything else you can think of.
+        "in mmmfs, directories, files and applications are all kind of the same thing, or something like that.
+        Listen, I don't really know yet either. The idea is that there is only one type of 'thing' -
+        a fileder", fileder, ". A fileder can store multiple variants and metadata of its content,
+        such as a markdown text and a rendered HTML version of the same document.
+        It could also store a script that transforms the markdown version into HTML and is executed on demand,
+        automatically."
+
+      append p "Fileders can also have other fileders as their children (just like directories do in a normal
+        filesystem). You can make a fileder view query these children and display them however you want.
+        A 'Pictures' fileder, for example, could contain a script within itself that renders all the picture files
+        you put into it as little previews and lets you click on them to view the full image."
+
+      append p "This means the 'Pictures' fileder can also have an alternate slideshow mode, with fullscreen view and
+        everything (some of this is built, check out the gallery example below), or one that displays geotagged images
+        on a world map, if you really want that.  Maybe you could build a music folder that contains links to youtube
+        videos, spotify tracks and just plain mp3 files, and the folder knows how to play them all.", br!, "
+        In this way fileders fulfil the purpose of 'Applications' too."
+
+      -- @TODO: BUT doesn't have to be only for one type of file:
+      -- @TODO: rework
+      -- making a multi-media collage representing your thoughts and mental organization of a topic
+      append p "A fileder is also responsible for how it's children are sorted, filtered and interacted with.
+        For example you should be able to create a fileder that is essentially a 'word document' equivalent: it can
+        contain images, websites, links and of course text as children and let you reorder, layout and edit them
+        whenever you open the fileder."
 
       append p "Sounds cool, no? Here's some examples of things a fileder can be or embed:"
 
@@ -94,36 +108,55 @@ root = Fileder {
         -- get 'preview' as a DOM description (nil if no value or conversion possible)
         content = child\get 'preview', 'mmm/dom'
 
-        -- get 'preview' as a DOM description (nil if no value or conversion possible)
+        -- get 'name' as a DOM description (nil if no value or conversion possible)
         name = child\gett 'name', 'alpha'
 
         preview title, content, name
 
-
       append h2 "details"
+      -- @TODO s/parts: dimensions, aspects?
+      -- @TODO: first mention both properties & children; then go into detail
+      -- @TODO: main content
+      append do
+        name = html.i 'name'
+        type = html.i 'type'
+
+        p "Fileders are made up of two main parts. The first is the list of ", (html.i 'properties'), ",
+        which are values identified by a ", name, " and ", type, ". These values are queried using strings like ",
+        (code 'title: text/plain'), " or ", (code 'mmm/dom'), ", which describe both the ", name,
+        " of a property (", (code '"title"'), " and ", (code '""'), ", the unnamed/main property) and the ", type,
+        " of a property. Property types can be something resembling a MIME-type or a more complex structure
+        (see ", (html.i "type chains"), " below). A fileder can have multiple properties of different types
+        set that share a ", name, ". In this case the overlapping properties are considered equivalent and the one
+        with the most appropriate ", type, " is selected, depending on the query.
+        The unnamed property is considered a fileder's 'main content', i.e. what you are interested in when viewing it."
+
+      append p "The second part of a fileder is the list of it's children, which are fileders itself.
+        The children are stored in an ordered list and currently identified by their ", (code 'name: alpha'),
+        " property for UI and navigation purposes only (not sure if this is a good idea tbh)."
+
+--      append do
+--        github = footnote a 's-ol/mmm', href: 'https://github.com/s-ol/mmm/tree/master/app/mmmfs'
+--          "Oh and also everything is on github and stuff", github,
+--          " if you care about that."
+
       append do
         mmmdom = code ('mmm/dom'), footnote span (code 'mmm/dom'), " is a polymorphic content type;
           on the server it is just an HTML string (like ", (code 'text/html'), "),
           but on the client it is a JS DOM Element instance."
-        fengari = a 'fengari.io', href: 'https://fengari.io'
-        p "What you are viewing right now is a fileder that has a Lua/Moonscript function as a value which
-          is rendering all this text. It returns a value whose type interface is known as ", mmmdom, ", which is
-          basically an HTML subtree. The function can be run, and the results generated, statically on the server
-          (resulting in an HTML file), or dynamically on the client (via ", fengari, ").", br!,
-          "The function is passed the fileder itself (as a Lua table) and potentially also receives some other
-          helpers for accessing it's environment (parent fileders, functions for querying the tree etc) or info
-          specific to the function key/type, but I haven't built or thought about any of that yet. Sorry."
 
-      append do
-        github = footnote a 's-ol/mmm', href: 'https://github.com/s-ol/mmm/tree/master/app/mmmfs'
-        p "Anyway, this node is set up as some sort of wiki/index thing and just lists its children-fileders' ", (code 'title: text/plain'),
-          " values and ", (code 'preview: mmm/dom'), " previews (if set). Oh and also everything is on github and stuff", github,
-          " if you care about that."
+        p "What you are viewing right now is the main property of the root fileder.
+          The property is queried as ", mmmdom, ", a website fragment (DOM node). This website fragment
+          is then added to the page in the main content area, where you are most likely reading it right now."
+
+        p "Anyway, this node is set up as a very generic sort of index thing and just lists its children-fileders' 
+          alongside this text part you are reading.", br!, "For each child it displays the ", (code 'title: text/plain'),
+          " and shows the ", (code 'preview: mmm/dom'), " property (if set)."
 
       append h3 "converts"
-      append p "Well actually it's a bit more complex. You see, the code that renders these previews ", (html.i "asks"), " for those
-        name/type pairs (", (code 'title: text/plain'), ', ', (code 'preview: mmm/dom'), "), but the values don't actually have to
-        be ", (html.i "defined"), " as these types."
+      append p "So far I have always listed properties as they are being queried, but a main feature of mmmfs is
+        type conversion. This means that you generally ask for content in whichever format suits your application,
+        and rely on the type resolution mechanism to make that happen."
 
       append moonscript [[
 -- render a preview block
@@ -143,7 +176,10 @@ append div for child in *@children
   preview title, content
       ]]
 
-      append p "For example, the markdown child below only provides ", (code 'preview'), " as ", (code 'text/markdown'), ":"
+      append p "Here the code that renders these previews. You can see it ", (html.i "asks"), " for the
+        properties ", (code 'title: text/plain'), ' and ', (code 'preview: mmm/dom'), "), but the values don't actually have to
+        be ", (html.i "defined"), " as these types.
+        For example, the markdown child below only provides ", (code 'preview'), " as ", (code 'text/markdown'), ":"
 
       append moonscript [[
 Fileder {
@@ -172,7 +208,7 @@ and some bold **text** and `code tags` with me.",
 
       append h3 "type chains"
       append p "In addition, a property type can be encoded using multiple types in a ", (code 'type chain'), ".
-        For example the root node you are viewing currently is defined as ", (code 'moon -> mmm/dom'), ",
+        For example the root node you are viewing currently is actually defined as ", (code 'moon -> mmm/dom'), ",
         meaning it's value is a moonscript function returing a regular ", (code 'mmm/dom'), " value."
 
       append p "Both value chains and 'sideways' converts are resolved using the same mechanism,