[TWX] tiddler=encapsulation paradigm

[Mat]

As reflected on elsewhere, tiddler philosophy is pretty close to "encapsulation philosophy" in programming (...as far as I can tell. I'm not a coder.) 

For TiddlyWiki X (a generic term introduced by Jeremy for a potential future remake of TW) it would be neat to embrace this as a paradigm:

Tiddlers could "mirror" a general code function, e.g with the title of the tiddler serving as the function name, a predefined parameters field, using field names+values as variable declarations, etc. One function = one tiddler. (...embracing another, perhaps more aesthetic, philosophy of "everything is a tiddler")

A user friendly UI for building complex multi-function code could consist of drag'n dropping tiddlers into a flow sequence perhaps comparable to Scratch programming or Google Blockly. (BTW, the next version of the former will be based on the latter.)

Also widgets could have this physical manifestation for a GUI.

Perhaps two tiers for editing: a GUI mode and a text based mode.

The idea is worth considering; it should definitely increase re-usability for code. The tiddler-as-function-shell format would also encourage TW philosophy... or, if this was the only option for creating functions /macros, then it would simply force users into understanding tiddler philosophy. Currently, I find myself making huge monolithic tiddlers with complex macros because separate macro-tiddlers force re-rendering which makes in-TW dev hard. Separate tids currently also makes you loose overview.

<:-)

[Yakov]

Hi Mat,

I'd suggest to accompany this with some examples illustrating what you mean. For now this sounds very vague :)

Best regards,
Yakov.

четверг, 31 августа 2017 г., 11:19:56 UTC+3 пользователь Mat написал:

[PMario]

On Thursday, August 31, 2017 at 10:19:56 AM UTC+2, Mat wrote:

As reflected on elsewhere, tiddler philosophy is pretty close to "encapsulation philosophy" in programming (...as far as I can tell. I'm not a coder.) 

Encapsulation in terms of "one function should only be doing one thing well" is a good thing.

... but ...

In terms of "documentation" we want to break this paradigm. Documentation shouldn't be separated from the source code. Programmers are "lazy". They change the code, but don't fix the docs ;) ... That's one of the biggest problems we have to face.

So we need a mechanism that can combine this 2 necessities. One way would be: Literate Programming.

I actually found TW, as I was searching for a "literate programming" editor. Literate programming is a concept, that allows you to mix "documentation" with "code"... So you only have to maintain one "source of truth" ...

TW's transclusion concept is exactly one part of the equation. It allows us to mix TW-text with code of any language.

eg:

! Heading

Some literate description about the problem. ... A very detailed description.

{{code-tiddler}}

Some more text ...

The problem we are facing now, is that we need a mechanism to extract the code from the docs __AND__ convert the docs into a human readable format, that contains the code and the docs!

Tiddlers could "mirror" a general code function, e.g with the title of the tiddler serving as the function name, a predefined parameters field, using field names+values as variable declarations, etc. One function = one tiddler. (...embracing another, perhaps more aesthetic, philosophy of "everything is a tiddler")

This paragraph imo is way to "solution" oriented. It's very specific and not as generic as it should be. ... It reflects a certain point of view - yours. Which is perfectly fine. ... But it also limits its possible usecases. Cases which I and you may not think about in the moment. ...

 

A user friendly UI for building complex multi-function code could consist of drag'n dropping tiddlers into a flow sequence perhaps comparable to Scratch programming or Google Blockly. (BTW, the next version of the former will be based on the latter.)

That's possible. ... Someone with enough time and resources just needs to do it.

 

Also widgets could have this physical manifestation for a GUI.

Very early alpha versions of TW had their own widget-GUI in tiddler edit mode. ... But widgets and their parameters changed so fast, that it was impossible to keep the GUI up to date. It was hard to maintain and it also was ugly (sry to say that :) ... So it needed to be removed.

The widget parameters are pretty stable now. ... So there could be a new approach to create a GUI to create "wiki-text-programs".

Perhaps two tiers for editing: a GUI mode and a text based mode.

Hihi, ... one more system to maintain ;)

 

The idea is worth considering;

yes

it should definitely increase re-usability for code. The tiddler-as-function-shell format would also encourage TW philosophy... or, if this was the only option for creating functions /macros, then it would simply force users into understanding tiddler philosophy.

ouch ... do you really think we should "force" users? ... We need some rules - yes. But IMO the system needs to be generic enough to let the users do what they want. The system needs to go out of the users way.

 - If the user wants big tiddlers -- fine.

 - If the user wants small tiddlers -- fine too!

 

Currently, I find myself making huge monolithic tiddlers with complex macros because separate macro-tiddlers force re-rendering which makes in-TW dev hard. Separate tids currently also makes you loose overview.

That's not really your problem. It's an "editor problem". ... At the moment we have to start with big tiddlers defining many macros in one tiddler, because macros are "hidden" when you save them.

There is a workaround that I stole from Eric (thx :)

\define macro()
do something
\end

<pre><$view field="text"/></pre>

If you put the above line into macro source tiddlers you can read them in view mode, without side effects.

......... which brings us back to Literate Programming.

To be able to mix code and a literate description of code, we need to improve our UI ... a little bit. _But_ we have all the pieces already built in to TW.

have fun!
mario

[TonyM]

Mario,

The idea of literate Programming, or self documentation is supportive of community development and reuse. Sometimes the main thing is to lead by example, other developers can jump on the bandwagon. The Truth is self documentation needs to be inline with the code. I have not seen any inline commenting features, do you know any?

I took your hint and created a tiddler ShowCode and Tagged it $:/tags/ViewTemplate

<$list filter=[is[current]tag[ShowCode]]>

<pre><$view field="text"/></pre>

</$list>

If we had a comprehensive "Language Guide" reference for tiddlywiki we could allow self documentation to reference entries in the reference. For example

<- If the Current tiddler is tagged ShowCode display the text field without wiki formatting - See Docs Display in view template ->
<$list filter=[is[current]tag[ShowCode]]>

<pre><$view field="text"/></pre>

</$list>

It would be nice to have a toggle in the More toolbar to do this, actually a generic way to add tag toggles to the toolbar would be nice.

The Truth is in some cases exhaustive self documentation can give rise to bloat, so an ability to save a tiddlywiki or a tiddler with the self documentation automatically removed should be available. This should be trivial if we have a standard way to comment code, A standard "code notes field" or "code reference" link may also help

The capture of self documented code patterns in a repository would also be helpful, a kind of Git for code snippets, code tiddlers "code reference link " could then point to an entry in the repository that documents the code (in Reuse cases).

Regards
Tony

[TonyM]

All,

Sorry my above example is failing. When using text/plan

I just noticed setting the tiddler type to text/plain is another way if you do not need the code tiddler itself to include wiki formatting. perhaps other tiddler types would be better.

Tony