I would like to run something by the group here. I'm thinking of using
TW5 for something that might be slightly off the beaten path for
TiddlyWiki. I would like advice about whether it's worth pursuing, and,
if so, further advice about how to accomplish certain goals.
A friend and I have been developing a functional programming library in
Javascript [1] that's recently started to become fairly popular, which
means that we suddenly have to deal with all sorts of infrastructure
issues we'd previously managed to ignore. High on that list is
documentation. Until now, we'd gotten by with just docco [2] annotated
source code, but users are starting to demand real API documentation as
well. Some volunteers have stepped up to add JSDoc [3] comments to the
codebase.
The trouble is that I don't particularly like any of the common JSDoc
output formats available. It struck me that TW has pretty well
everything that I would want, though. So I hacked together a
hand-crafted proof-of-concept:
<http://ramdajs.com/tw/tiddly.html>
There's still plenty to do, of course. But I would like some feedback
about both the feasibility and the rationality of the approach before I
put too much more into it. The idea is that a function preceded by a
comment like this:
/**
* Returns a single item by iterating through the list, successively
* calling the iterator function and passing it an accumulator value
* and the current value from the array, and then passing the result
* to the next call.
*
* The iterator function receives two values: `(acc, value)`
*
* Note: `ramda.foldl` does not skip deleted or unassigned indices
* (sparse arrays), unlike the native `Array.prototype.reduce` method.
* For more details on this behavior, see: [The MDN
* Article]{@link https://developer.mozilla.org/.../reduce#Description}
*
* @category List
* @signature (a -> b -> a) -> a -> [b] -> a
* @param {Function} fn The iterator function. Signature: a -> b -> a
* @param {Any} acc The accumulator value.
* @param {Array} list The list to iterate over.
* @return {Any} The final, accumulated value.
* @see {@link foldl.idx}
* @see {@link foldr}
* @alias reduce
* @example
*
* var numbers = [1, 2, 3];
* var add = function(a, b) {
* return a + b;
* };
*
* foldl(numbers, add, 10); //=> 16
*/
would end up being documented like this:
<http://ramdajs.com/tw/tiddly.html#foldl>
What I would like to do is to remove the edit/save capabilities of TW
here. And this is where I think I'm straying pretty far from the sweet
spot of TiddlyWiki. I would like to remove the last modified timestamp
as well as the Info and Edit icons from each Tiddler, as well as all the
icons and at least the "Tools" and "More" sidebar tabs. In other words,
what I really want to do is to remove everything which makes this a
dynamic Wiki, leaving behind only an excellent micro-content viewer.
I have no idea yet how to do any of that, but before I even ask about
that, I first want to know if this seems so antithetical to the spirit
of TW that I'd offend people here by even trying it. You see, although I
really love TiddlyWiki for what it is and what it can do, I also really
like the UI it presents for simply viewing micro-content. That's all I
really want to use from it in this case.
If doing that seems reasonable, then I would like to know if there are
decent references around to show me how to turn a TW into this read-only
mode. (What I saw about `zzConfig` or some such I think had something to
do with older versions; at least it didn't work when I tried it; perhaps
the old `systemConfig` is no longer very useful.)
There are several other minor things I would like to do. I'm going to
list them briefly in case someone has quick answers, but I'm not really
expecting to keep people's attention this far, so if I do decide to go
with this, I'll probably be back with more detailed questions. In any
case, here are a few other things:
- I'd like to make a "Signature" module/widget/template/something that
I can feed with source code that looks like "a -> b -> c" and puts
on the browser something where the "->"'s are replaced by Unicode
arrows. I don't have an exact syntax in mind, but something that I
could put on my tiddler that looks something like <$sig
field="signature"/>
- I'd like to create some "Types" tiddlers to describe those types
listed as argument or return types on functions, and then link the
references to them (and possibly also have some way to list the
reverse references from those tiddlers.)
- I'd like to reorganize the sidebar tabs so that the tabs show up in
the order I choose: API, A- Z, Overview, (and if I decide to keep
them) Open, and Recent
Since there are nearly two hundred functions in the library (including
aliases), a long scrolling list is not wonderful. I would like to either
- Turn my (to-become-)long list of categorized functions into an
accordion (there will probably be about ten categories.)
- Find a way to turn this list into some multi-column structure, so
that either each category individually or the entire list spans
three or four columns to fill up the available space better, and
more functions are available to see without scrolling. This would
ideally work for both the main section and the sidebar, but I would
have no issue with handling them separately if necessary.
In any case, if you've made it this far, thanks for reading. I
appreciate your attention, and would love to hear if you think this is a
reasonable use of TW.
Thanks,
-- Scott
[1]: https://github.com/CrossEye/ramda
[2]: http://jashkenas.github.io/docco/
[3]: http://usejsdoc.org/
--
You received this message because you are subscribed to the Google Groups
"TiddlyWikiDev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/tiddlywikidev.
For more options, visit https://groups.google.com/d/optout.
