git.s-ol.nu mmm / 7777734
much improved side-note referencing s-ol 1 year, 11 months ago
13 changed file(s) with 126 addition(s) and 84 deletion(s). Raw diff Collapse all Expand all
00 require = relative ..., 1
1 refs = require 'mmm.refs'
12 import Queue from require '.queue'
23
34 count = (base, pattern='->') -> select 2, base\gsub pattern, ''
128129 err_and_trace = (msg) -> debug.traceback msg, 2
129130 apply_conversions = (conversions, value, ...) ->
130131 for i=#conversions,1,-1
132 refs\push!
131133 step = conversions[i]
132134 ok, value = xpcall step.convert.transform, err_and_trace, step, value, ...
135 refs\pop!
133136 if not ok
134137 f, k = ...
135138 error "error while converting #{f} #{k} from '#{step.from}' to '#{step.to}':\n#{value}"
6060 cost: 1
6161 transform: (bib) => format_full parse_bibtex bib
6262 }
63 {
64 inp: 'text/bibtex'
65 out: 'mmm/dom+link'
66 cost: 1
67 transform: (bib) =>
68 info = parse_bibtex bib
69 note = format_full info
70
71 key = tostring 1
72 id = "sideref-#{key}"
73
74 intext = sup a key, href: "##{id}"
75
76 span intext, div {
77 class: 'sidenote'
78 style:
79 'margin-top': '-1rem'
80
81 div :id, class: 'hook'
82 b key, class: 'ref'
83 ' '
84 note
85 }
86 }
8763 }
8864 }
88 (arg) ->
99 return if arg == js.null
1010 arg
11
12 -- fix JS bool values
13 js_bool = if MODE == 'CLIENT'
14 (arg) ->
15 return nil if arg == js.null
16 return false if arg == 'false'
17 true
1118
1219 -- limit function to one argument
1320 single = (func) -> (val) => func val
109116 switch key
110117 when 'path' then path = val
111118 when 'facet' then facet = val
119 when 'wrap' then opts.wrap = val
112120 when 'nolink' then opts.nolink = true
113121 when 'inline' then opts.inline = true
114 when 'raw' then opts.raw = true
122
123 when 'raw' then opts.raw = true -- deprecated
124
115125 else warn "unkown attribute '#{key}=\"#{val}\"' in <mmm-embed>"
116126
117127 embed path, facet, fileder, opts
128138 for element in *embeds
129139 path = js_fix element\getAttribute 'path'
130140 facet = js_fix element\getAttribute 'facet'
131 nolink = js_fix element\getAttribute 'nolink'
132 inline = js_fix element\getAttribute 'inline'
133 raw = js_fix element\getAttribute 'raw'
141 wrap = js_fix element\getAttribute 'wrap'
142 nolink = js_bool element\getAttribute 'nolink'
143 inline = js_bool element\getAttribute 'inline'
134144 desc = js_fix element.innerText
135145 desc = nil if desc == ''
136146
137 opts = :nolink, :inline, :raw, :desc
147 raw = js_bool element\getAttribute 'raw' -- deprecated
148
149 opts = :wrap, :nolink, :inline, :desc, :raw
138150 element\replaceWith embed path or '', facet or '', fileder, opts
139151
140152 embeds = \getElementsByTagName 'mmm-link'
0 refs = require 'mmm.refs'
1
02 merge = (orig={}, extra) ->
13 with attr = {k,v for k,v in pairs orig}
24 for k,v in pairs extra
911 path .. '/'
1012
1113 (elements) ->
12 import a, div, span, pre from elements
14 import a, div, span, sup, b, pre from elements
1315
1416 find_fileder = (fileder, origin) ->
1517 if 'string' == type fileder
3941 link_to = (fileder, name, origin, attr) ->
4042 fileder = find_fileder fileder, origin
4143
42 link = fileder\get 'mmm/dom+link'
43 return link if link
44
4544 name or= fileder\get 'title: mmm/dom'
4645 name or= fileder\gett 'name: alpha'
4746
5655 }
5756
5857 embed = (fileder, name='', origin, opts={}) ->
58 if opts.raw
59 warn "deprecated option 'raw' set on embed"
60 assert not opts.wrap, "raw and wrap cannot both be set on embed"
61 opts.wrap = 'raw'
62 opts.wrap or= 'well'
63
5964 fileder = find_fileder fileder, origin
6065
6166 -- node = fileder\gett name, 'mmm/dom'
7378 (pre node)
7479 }
7580
76 return node if opts.raw
77
7881 klass = 'embed'
7982 klass ..= ' desc' if opts.desc
8083 klass ..= ' inline' if opts.inline
8184
82 node = span {
83 class: klass
84 node
85 if opts.desc
86 div opts.desc, class: 'description'
87 }
85 switch opts.wrap
86 when 'raw'
87 node
8888
89 return node if opts.nolink
90 link_to fileder, node, nil, opts.attr
89 when 'well'
90 node = span {
91 class: klass
92 node
93 if opts.desc
94 div opts.desc, class: 'description'
95 }
96
97 if opts.nolink
98 node
99 else
100 link_to fileder, node, nil, opts.attr
101
102 when 'sidenote'
103 key = opts.desc or tostring refs\get!
104 id = "sideref-#{key}"
105
106 intext = sup a key, href: "##{id}"
107
108 span intext, div {
109 class: 'sidenote'
110 style:
111 'margin-top': '-1rem'
112
113 div :id, class: 'hook'
114 b key, class: 'ref'
115 ' '
116 node
117 }
118 else
119 error "unknown embed 'wrap': '#{opts.wrap}'"
91120
92121 {
93122 :find_fileder
0 {
1 depth: 0
2 count: 0
3
4 push: =>
5 @depth += 1
6
7 pop: =>
8 @depth -= 1
9 if @depth == 0
10 @count = 0
11
12 get: =>
13 @count += 1
14 @count
15 }
2424
2525 <mmm-embed nolink path="../../references/inkandswitch" facet="markdown"></mmm-embed>
2626
27 > <mmm-embed raw path="../../references/inkandswitch"></mmm-embed>
27 > <mmm-embed wrap="raw" path="../../references/inkandswitch"></mmm-embed>
2828
2929 I also added a special override that links to
3030 BibTeX files by placing the citation in a sidenote, and adding a footnote indicator in-text.
1212 The system has proven itself perfect for publishing small- and medium-size articles and blog posts, especially for its
1313 ability to flexibly transclude content from any source. This includes diagrams (such as in this thesis),
1414 videos (as in the documentation in the appendix), but also less conventional media such as
15 interactive diagrams <mmm-link path="../references/aspect-ratios"></mmm-link> or twitter postings.
15 interactive diagrams<mmm-embed path="../references/aspect-ratios" wrap="sidenote"></mmm-embed> or twitter postings.
1616
1717 On the other hand, the development of the technical framework for this very thesis has posed greater challenges.
1818 In particular, the implementation of the reference and sidenote systems are brittle and uninspiring.
9292 Additionally it could be made possible to use this mechanism to locally override *converts* inherited from
9393 further up in the tree, for example to specialize types based on their context in the system.
9494
95 <div class="sidenote">see also <mmm-embed raw path="../references/alternatives-to-trees"></mmm-embed>
95 <div class="sidenote">see also <mmm-embed wrap="raw" path="../references/alternatives-to-trees"></mmm-embed>
9696 </div>The biggest downside to this approach would be that it presents another pressure factor for, while also
9797 reincforcing, the hierarchical organization of data, thereby exacerbating the limits of hierarchical structures.
9898
105105 to them, actively limiting their understanding, and thereby the customizability, of the system.
106106
107107 This weakness represents a failure to (fully) implement the quality of a "Living System" as proposed by
108 *Ink and Switch*<mmm-link path="../references/inkandswitch"></mmm-link>.
108 *Ink and Switch*<mmm-embed path="../references/inkandswitch" wrap="sidenote"></mmm-embed>.
109109
110110 In general however, some portion of code may always have to be left outside of the system.
111111 This also wouldn't necessarily represent a problem, but in this case it is particularily relevant
4141 (`mmm/dom+link`) that can be transcluded using the `<mmm-link>` pseudo-tag.
4242
4343 For convenience, a convert from the `URL -> cite/acm` type has been provided to `URL -> text/bibtex`,
44 which generates links to the ACM Digital Library<mmm-link path="../references/acm-dl"></mmm-link>
44 which generates links to the ACM Digital Library<mmm-embed path="../references/acm-dl" wrap="sidenote"></mmm-embed>
4545 API for accessing BibTeX citations for documents in the library.
4646 This means that it is enough to store the link to the ACM DL entry in mmmfs,
4747 and the reference will automatically be fetched (and track potential remote corrections).
88 ---------
99
1010 *Ink and Switch* suggest three qualities for tools striving to support
11 end-user programming<mmm-link path="../references/inkandswitch"></mmm-link>:
11 end-user programming<mmm-embed path="../references/inkandswitch" wrap="sidenote"></mmm-embed>:
1212
1313 - *Embodiment*, i.e. reifying central concepts of the programming model as more concrete, tangible objects
1414 in the digital space (for example through visual representation),
2828 modularity
2929 ----------
3030
31 The *UNIX Philosophy* <mmm-link path="../references/unix"></mmm-link> describes the software design paradigm
32 pioneered in the creation of the Unix operating system at the AT&T Bell Labs research center in the 1960s. The
31 The *UNIX Philosophy*<mmm-embed path="../references/unix" wrap="sidenote"></mmm-embed> describes the software design
32 paradigm pioneered in the creation of the Unix operating system at the AT&T Bell Labs research center in the 1960s. The
3333 concepts are considered quite influental and are still notably applied in the Linux community. Many attempts at
3434 summaries exist, but the following includes the pieces that are especially relevant even today:
3535
5757 present in order to assemble more complex solutions out of such parts. Therefore static content should be able to be
5858 linked to (as envisioned for the *Memex*, see above), but also to be <span class="sidenote">The term <i>transclusion</i>
5959 refers to the concept of including content from a separate document, possibly stored remotely, by reference rather than
60 by duplication. See also <mmm-embed raw path="../references/transclusion"></mmm-embed></span>*transcluded*,
60 by duplication. See also <mmm-embed wrap="raw" path="../references/transclusion"></mmm-embed></span>*transcluded*,
6161 to facilitate the creation of flexible data formats and interactions, such that e.g. a slideshow slide can include
6262 content in a variety other formats (such as images and text) from anywhere else in the system. Behaviours also should be
6363 able to be transcluded and reused to facilitate the creation of ad-hoc sytems and applets based on user needs. For
8383
8484 While there is an ongoing area of research focusing on the development of new programming paradigms,
8585 methodologies and tools that are more accessible and cater to the wide
86 range of end-users<mmm-link path="../references/subtext"></mmm-link>,
86 range of end-users<mmm-embed path="../references/subtext" wrap="sidenote"></mmm-embed>,
8787 in order to keep the scope of this work appropriate,
8888 conventional programming languages are used for the time being.
8989 Confidence is placed in the fact that eventually more user-friendly languages will be available and,
88 directly known to the system.
99
1010 In a retrospective analysis of the Xerox Star's impact on the computer
11 industry<mmm-link path="../references/xerox-star" ></mmm-link>, the desktop metaphor is described as follows:
11 industry<mmm-embed path="../references/xerox-star" wrap="sidenote"></mmm-embed>, the desktop metaphor is described as
12 follows:
1213
1314 > In a Desktop metaphor system, users deal mainly with data files, oblivious to the existence of programs.
1415 > They do not "invoke a text editor", they "open a document".
3334 <p><i>How systems influenced later systems. This graph summarizes how various systems related to Star have influenced
3435 one another over the years. Time progresses downwards. Double arrows indicate direct successors (i.e.,
3536 follow-on versions). [...]</i></p>
36 <mmm-embed raw path="../references/xerox-star"></mmm-embed></div>
37 <mmm-embed wrap="raw" path="../references/xerox-star"></mmm-embed></div>
3738 <mmm-embed nolink path="star-graph"></mmm-embed>
3839
3940 The earliest indirect influence for the Xerox Alto and many other systems of its time, was the *Memex*.
40 The *Memex* is a hypothetical device and system for knowledge management. Proposed by Vannevar Bush in 1945<mmm-link
41 path="../references/memex"></mmm-link>, the concept predates much of the technology that later was used to implement
42 many parts of the vision.
41 The *Memex* is a hypothetical device and system for knowledge management. Proposed by Vannevar Bush in 1945<mmm-embed
42 path="../references/memex" wrap="sidenote"></mmm-embed>, the concept predates much of the technology that later was used
43 to implement many parts of the vision.
4344
4445 While the article extrapolates from existing technology at the time, describing at times
4546 very concrete machinery based on microfilm and mechanical contraptions, many of the conceptual predictions became
4950 connected information, which would later be known and created as *hypertext*. While hypertext powers the majority of
5051 today's internet, many of the advantages that Bush imagined have not carried over into the personal use of computers.
5152 There are very few tools for creating personal, highly-interconnected knowledgebases, even though this is technically
52 feasible, and a proven concept (exemplified for example by the massively successful online encyclopedia *Wikipedia*<mmm-link
53 path="../references/wikipedia"></mmm-link>).
53 feasible, and a proven concept (exemplified for example by the massively successful online encyclopedia
54 *Wikipedia*<mmm-embed path="../references/wikipedia" wrap="sidenote"></mmm-embed>).
5455
5556 While there are little such tools available today, one of the systems that could be said to have come closest to a
5657 practical implementation of such a Memex-inspired system for personal use might be Apple's *HyperCard*.
5758
58 In a live demonstration<mmm-link path="../references/hypercard"></mmm-link>, the creators of the software showcase
59 a system of stacks of cards that together implement, amongst others, a calendar (with yearly and weekly views), a
60 list of digital business cards for storing phone numbers and addresses, and a todo list. However these stacks of
61 cards are not just usable by themselves, it is also demonstrated how stacks can link to each other in meaningful ways,
62 such as jumping to the card corresponding to a specific day from the yearly calendar view, or automatically looking
63 up the card corresponding to a person's first name from a mention of the name in the text on a different card.
59 In a live demonstration<mmm-embed path="../references/hypercard" wrap="sidenote"></mmm-embed>, the creators of the
60 software showcase a system of stacks of cards that together implement, amongst others, a calendar (with yearly and
61 weekly views), a list of digital business cards for storing phone numbers and addresses, and a todo list. However these
62 stacks of cards are not just usable by themselves, it is also demonstrated how stacks can link to each other in
63 meaningful ways, such as jumping to the card corresponding to a specific day from the yearly calendar view, or
64 automatically looking up the card corresponding to a person's first name from a mention of the name in the text on a
65 different card.
6466
6567 Alongside Spreadsheets, *HyperCard* remains one of the most successful implementations of end-user programming, even
6668 today. While it's technical abilities have been long matched and surpassed by other software (such as the ubiquitous
3333 - Many file-formats specify a specific data-pattern either at the very beginning or very end of a given file.
3434 On unix systems the `libmagic` database and library of these so-called *magic constants* is commonly used to guess
3535 the file-type based on these fragments of data.
36 - on UNIX systems, files to be executed are checked by a variety of methods<mmm-link path="../references/linux-exec">
37 </mmm-link> in order to determine which format would fit. For example, script files, the "shebang" symbol, `#!`, can
38 be used to specify the program that should parse this file in the first line of the file.
36 - on UNIX systems, files to be executed are checked by a variety of methods<mmm-embed path="../references/linux-exec"
37 wrap="sidenote"></mmm-embed> in order to determine which format would fit. For example, script files, the "shebang"
38 symbol, `#!`, can be used to specify the program that should parse this file in the first line of the file.
3939
4040 It should be clear already from this short list that to mainstream operating systems, as well as the applications
4141 running on them, the format of a file is almost completely unknown and at best educated guesses can be made.
4242
4343 Because these various mechanisms are applied at different times by the operating system and applications,
44 it is possible for files to be labelled as or considered as being in different formats at the same time by different components of the system.
44 it is possible for files to be labelled as or considered as being in different formats at the same time by different
45 components of the system.
4546 <div class="sidenote" style="margin-top: -5rem;">
4647 The difference between changing a file extension and converting a file between two formats is commonly unclear to users,
4748 see for example <a href="https://askubuntu.com/questions/166602/why-is-it-possible-to-convert-a-file-just-by-renaming-its-extension">
5152 This leads to confusion about the factual format of data among users, but can also pose a serious security risk:
5253 Under some circumstances it is possible that a file contains maliciously-crafted code and is treated as an executable
5354 by one software component, while a security mechanism meant to detect such code determines the same file to be a
54 legitimate image<mmm-link path="../references/poc-or-gtfo"></mmm-link> (the file may in fact be valid in both formats).
55 legitimate image<mmm-embed path="../references/poc-or-gtfo" wrap="sidenote"></mmm-embed> (the file may in fact be valid
56 in both formats).
5557
5658 In mmmfs, the example above might look like this instead:
5759 <mmm-embed path="tree_mmmfs">schematic view of an example mmmfs tree</mmm-embed>
1818
1919 For one, since applications are the products companies produce, and software represents a market of users,
2020 developers compete on features integrated into their applications. To stay relevant, monlithic software or software
21 suites tend to accrete features rather then modularise and delegate to other software<mmm-link
22 path="../references/appliances"></mmm-link>. This makes many software packages more complex and unintuitive than they
23 need to be, and also cripples interoperability between applications and data formats.
21 suites tend to accrete features rather then modularise and delegate to other software<mmm-embed wrap="sidenote"
22 path="../references/appliances"></mmm-embed>. This makes many software packages more complex and unintuitive than
23 they need to be, and also cripples interoperability between applications and data formats.
2424
2525 Because applications are incentivised to keep customers, they make use of network effects to keep customers locked-in.
2626 This often means re-implementing services and functionality that is already available to users,
4444 The application-centric computing metaphor treats applications as black boxes, and provides no means to understand,
4545 customize or modify the behaviour of apps, intentionally obscuring the inner-workings of applications and
4646 completely cutting users off from this type of ownership over their technology. While the trend seems to be to further
47 hide the way desktop operating systems work <mmm-link path="../references/osx-files"></mmm-link>, mobile systems like
48 Apple's *iOS* already started out as such so-called *walled gardens*.
47 hide the way desktop operating systems work<mmm-embed path="../references/osx-files" wrap="sidenote"></mmm-embed>,
48 mobile systems like Apple's *iOS* already started out as such so-called *walled gardens*.
4949
5050 cloud computing
5151 ---------------
6262 software solutions and ecosystems store the users' data in the cloud, often across national borders, where legal and
6363 privacy concerns are intransparently handled by the companies. If a company, for any reason, is unable or unwanting to
6464 continue servicing a customer, the users data may be irrecoverably lost (or access prevented). This can have serious
65 consequences<mmm-link path="../references/adobe"></mmm-link>, especially for professional users, for whom an inability
66 to access their tools or their cloud-stored data can pose an existential threat.
65 consequences<mmm-embed path="../references/adobe" wrap="sidenote"></mmm-embed>, especially for professional users, for
66 whom an inability to access their tools or their cloud-stored data can pose an existential threat.
6767
6868 inert data (formats)
6969 --------------------
7070
71 Cragg coins the term "inert data"<mmm-link path="../references/super-powers"></mmm-link> for the data created, and
72 left behind, by apps and applications in the computing model that is currently prevalent: Most data today is either
73 intrinsically linked to one specific application, that controls and limits access to the actual information, or even
74 worse, stored in the cloud where users have no direct access at all and depend soley on online tools that require a
75 stable network connection and a modern browser, and that could be modified, removed or otherwise negatively impacted
76 at any moment.
71 Cragg coins the term "inert data"<mmm-embed path="../references/super-powers" wrap="sidenote"></mmm-embed> for the data
72 created, and left behind, by apps and applications in the computing model that is currently prevalent: Most data today
73 is either intrinsically linked to one specific application, that controls and limits access to the actual information,
74 or even worse, stored in the cloud where users have no direct access at all and depend soley on online tools that
75 require a stable network connection and a modern browser, and that could be modified, removed or otherwise negatively
76 impacted at any moment.
7777
7878 Aside from being inaccesible to users, the resulting complex proprietary formats are also opaque and useless to other
7979 applications and the operating system, which often is a huge missed opportunity:
2323 border-top: 1px solid $gray-dark;
2424 font-size: 0.8em;
2525 word-break: break-word;
26
27 text-align: initial;
2628
2729 .hook {
2830 position: absolute;