Parsing other format to tiddlers: in build step or within TW?

[Scott Sauyet]

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

[Scott Sauyet]

On Friday, September 28, 2018 at 3:04:09 PM UTC-4, Scott Sauyet wrote:

I'm working on a new programming library and want to generate a tiddlywiki version of the documentation.  [ ...]

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?

I forgot to mention, regardless of any of this, I'll probably be serving this TW in Node.  I don't think that makes any difference, but perhaps it does.

  -- Scott

[Scott Sauyet]

Sorry, I just noticed that this went to the wrong group.  I'll repost on the main one.

  -- Scott