I'm working on a new programming library and want to generate a tiddlywiki version of the documentation. I'm looking for advice on the best way to do this. I will be maintaining the documentation in a markdown-file-per-function format; this will work well with our GitHub environment. I will need to convert that to tiddlers. I'd like to break this down into smaller parts in keeping with the TW philosophy, But I don't know if I should do this in some server-side build step or whether it would be straightforward to do that inside the TW client environment.
I will be doing this conversion in JS. Either it will take place in a Node-based build step or in a custom plugin vaguely similar to the Markdown plugin. So the core code would probably be similar either way. I know little of plugin development., but I'm more than willing to learn. And if I can manage it, I would much rather have the intact content (with just some field headers prepended) passed down to the client and interpreted there. But I just don't know how possible that is. The project is behind a corporate wall, and I can't share it, but it's similar to work I've done on the open-source Ramda (https://ramdajs.com/). Taking a function like `map` (https://ramdajs.com/docs/#map), I would start with this (sorry fairly long) markdown: ====================================================================== R.map ===== *"It is not down on any map; true places never are."* - Herman Melville Signature --------- map :: Functor f => (a -> b) -> f a -> f b map :: (a -> b) -> [a] -> [b] map :: (a -> b) -> {String : a} -> {String: b} map :: (a -> b) -> (r -> a) -> (r -> b) Description ----------- Takes a function and a [Functor][fu], applies the function to each of the functor's values, and returns a functor of the same shape. Ramda provides suitable map implementations for `Array` and `Object` and `Function`, so this function may be applied to `[1, 2, 3]`, to `{x: 1, y: 2, z: 3}` or to `n => n + 1`. It delegates to other Functors. Symbolic -------- R.map(f, [a, b, c]) //=> [f(a), f(b), f(c)] R.map(f, {x: a, y: b, z: c}) //=> {x: f(a), y: f(b), z: f(c)} R.map(f, g) //=> (...args) => f(g(...args)) R.map(f, functor) //=> functor.map(f) Examples -------- * const double = n => n + n const square = n => n * n R.map(double, [1, 2, 3]) //=> [2, 4, 6] R.map(double, {x: 2, y: 3, z: 5}) //=> {x: 4, y: 6, z: 10} R.map(double, square)(3) //=> 18 * const increment = n => n + 1 R.map(increment, Maybe.Just(42) //=> Maybe.Just(43) R.map(increment, Maybe.Nothing() //=> Maybe.Nothing() See Also -------- - R.transduce - R.addIndex Since ----- v0.1 [fu]: ../types/Functor ====================================================================== And I would like to generate a tiddler such as ====================================================================== created: 20180928141411712 modified: 20180928170503224 tags: title: R.map type: text/vnd.tiddlywiki {{$:/api/R.map/intro}} !! Signature {{$:/api/R.map/sig}} !! Description {{$:/api/R.map/desc}} !! Symbolic {{$:/api/R.map/symb}} !! Examples <$list filter="[tag[fn-Example]tag[R.map]]"> <$transclude field="text" mode="block"/> </$list> !! See Also {{$:/api/R.map/seeAlso}} !! Since ``` v0.1.0 ``` ====================================================================== and a collection of supporting tiddlers like ====================================================================== created: 20180928141421990 modified: 20180928170615408 tags: R.map fn-Signature title: $:/api/R.map/sig type: text/vnd.tiddlywiki ``` map :: Functor f => (a -> b) -> f a -> f b map :: (a -> b) -> [a] -> [b] map :: (a -> b) -> {String : a} -> {String: b} map :: (a -> b) -> (r -> a) -> (r -> b) ``` ====================================================================== I guess the first question is whether a plugin's code can be run at startup against a collection of tiddlers and generate more tiddlers. If that can't happen, then I'm pretty sure I'm stuck doing this in Node. But then, if I can, *should* I? I really like both TiddlyWiki's small-content-is-better philosophy and the single-markdown-file-per-function documentation style. Perhaps I need to live with just the one and include these simply as Markdown tiddlers. That would mean that I don't get the ability to reuse smaller parts of the documentation in other interesting places. But I don't have any immediate need to do that. It's purely speculative. And yet, if I simply put it off, it probably won't happen. I have time now to work on this that I probably won't get later. So I'm looking for advice. Would you do this in a server-side build step? Would you do it inside TiddlyWiki? Is there some better approach I'm not even seeing? Thanks for any suggestions you might have. -- Scott -- 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 tiddlywikidev+unsubscr...@googlegroups.com. To post to this group, send email to tiddlywikidev@googlegroups.com. Visit this group at https://groups.google.com/group/tiddlywikidev. To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywikidev/187f9676-e809-4389-9b49-82101f67ed03%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.