Lost, lost, lost

[Jeff Wilson]

Is there any documentation that really lays out the concepts? Or, a document that takes a "task-based" approach?

I'm getting started using TW5 and the most basic functionality is obvious to me -- I can create Tiddlers, link and 'transclude' (why use such an opaque word?) them, but doing things like arranging Tiddlers hierarchically, which seems like basic functionality, are mysterious. They seem to involve creating other Tiddlers with special names and copying a bunch of code into them.

Here's something I'd like to do which I'm missing:

I want to link to an external document from my Wiki in multiple Tiddlers. Depending on the user, the document may be in a different location. I'd like to create a variable or something that defines the location of the document. Each user can change the value of the variable to point to where the document lives in his filesystem.

How would you do that?

[S. S.]

You will surely get some "spot on" help from others once they have time to reply.
If I have understood your requirements correctly, here is a solution just off the top of my head.

1. Make a new tiddler, and give it this tag: $:/tags/Macro
2. Add a field to the tiddler and name it: file
• Give this file field a value of your file name. Example: index.html
3. Add another field to the tiddler - and name it: path
• Give this path field a default value for your path to the file - Example: default/path/
4. In the body of that tiddler copy and paste the below:
   

\define external-document(file:{{!!file}} path:{{!!path}})
\rules except wikilink
<$wikify name="location" text="$path$$file$">
<a href=<<location>> target="_blank">$file$</a>
</$wikify>
\end

Save the tiddler. You have created a Global macro (a variable on steroids) - which can be used as below.

When you need to create the link to the external file using the default path, in the body of the tiddler, type this text:

<<external-document>>

Someone else receiving this tiddler - can change the path in the path field of the tiddler and call it the exact same way.

Alternatively they can change the path by using the macro like this:

<<external-document path:"the new path/whatever it might be/">>

Note the file name also can be easily changed, both by changing it in the file field, or by specifying it in the macro.

Hope that helps for now.

[Jeff Wilson]

Can the macro be in the body of an external link, like this:

[[My PDF file|<<external-document>>]]

Or, can I concatenate something to the link, like:

[[My PDF file|<<external-document>>#page=7]]

Next question: what steps are involved in generating a Tiddler hierarchy? That is, I want to show the set of Tiddlers as a tree, with a parent node and children nodes. For example, if I were describing countries of the world, I'd like to have children of each country for subtopics like Population, Society, Geography, etc..

[Mark S.]

I've done things like that with images. For images, I made it so that a drop-down configuration would let me change the base path of all images that use the <<ximg filename>> (the original macro started out being that of Tobias Bier). This way I could change the path of all images in one convenient location.

I'm thinking the same thing could be use for external documents. But I just thought of an enhancement. Have a series of tiddlers tagged as "DocPath". Each tiddler would contain the path for a particular platform/user. The tiddler using the external document macro (perhaps <<document turbulence-studies-of-agricultural-commodities.pdf>>) would be tagged with DocPath. Click on the DocPath tag and from the list of tiddlers move your favorite path to the top. That top one becomes selected as the base path for your user.

Anyone else think that would be handy?

-- Mar

[S. S.]

Jeff,

If you examine the macro you created, the line that creates the link is:

<a href=<<location>> target="_blank">$file$</a>

That line creates the expected normal HTML for a link.  You can modify it easily to:

<a href=<<location>> target="_blank">My PDF file</a>

To give a page number for your PDF, just name the file: myPDFfile#page=7

For the new unrelated question, please do start a new topic as it helps each topic stay focussed.

Have fun!

[Mark S.]

On Saturday, January 12, 2019 at 10:00:32 AM UTC-8, Jeff Wilson wrote:

Next question: what steps are involved in generating a Tiddler hierarchy? That is, I want to show the set of Tiddlers as a tree, with a parent node and children nodes. For example, if I were describing countries of the world, I'd like to have children of each country for subtopics like Population, Society, Geography, etc..

It's better if you explain what you really want to do, because the best approach is going to depend on what you want.

For instance, the stock method of making hierarchies in TW is to make a tiddler (e.g. Country) and then from the drop down menu, use "New here" to make a new tiddler (e.g. "Guatemala").. Then repeat the process for level. You can then view the results with table-of-contents macro.

The problem is, in your particular example, is that "Population" wouldn't work as a sub-child of Guatemala, because "Population" applies to every country. So you would have either make a tiddler like "Population-Guatemala" or stop the hierarchy at that point and instead use fields in the "Guatemala" tiddler to handle Population, Society, etc. So, knowing what you want in advance is helpful in figuring out which way to go.

Good luck!

-- Mark

[S. S.]

Jeff,

There is a nice explanation for using square brackets for external linking here : Linking in Wikitext 

As far as I know, macros cannot be used inside this form of linking. You can assume this is so, unless someone jumps in and corrects me.

Regards.

On Sunday, January 13, 2019 at 1:00:32 AM UTC+7, Jeff Wilson wrote:

[Jeff Wilson]

I hope you guys don't mind some criticism. TiddlyWiki should be renamed FiddlyWiki -- everything seems to require poorly document, or arcane, steps or copying someone else's code to make things work. The macro suggested above is an example. Sure, it just embeds an anchor tag into the HTML, but the reason most people use wikis is to avoid writing HTML. Thus my assumption that the macro must be able to be embedded in a [[link]]. 

Creating a hierarchy sure looks simple -- just do "New here". But I couldn't find any documentation that told me that that is what that command does. 

I agree with others that say that TW5 is pretty powerful, but it isn't for the average person until some of these things are both better documented, and a way to access/perform the more complicated things just become menu-driven or something similar.

And I'm not a Luddite. I'm fairly technical, but my expectation is that an end-user tool should make it obvious and easy to do common things. If I have to put on my 'programmer hat' to figure out how it works, it probably is too hard.

[Diego Mesa]

I've been using TW for 3 years and I couldn't agree with you more. 

Every single person Ive tried to introduce to TW has said the same thing to me. 

[Mark S.]

If you use it as described, it works out of the box. But if you immediately start wanting to do something unconventional like inserting a macro into a link, well, that's what the forum is for. There's lots of documentation. Way more than many other projects I've seen. The problem is, it's not possible to foresee how people are going to want to use TW than it is to foresee how someone is going to want to use a string. One person wants to do macrame, another wants to make a tin-can phone, and someone else wants to make a candle-wick. Very hard to document the 1000 different ways people might go.

It's much easier to document a single-purpose tool like "gpg" or "notepad" then a sprawling octopus of a tool like TW.

I would say, if there was one tiny bit of pedantic piece of information I would put at the top of the TiddlyWiki page, it's "You can't mix wikitext inside of wikitext and expect it to work" with maybe a link to https://tiddlywiki.com/#Concatenating%20text%20and%20variables%20using%20macro%20substitution. It's probably the #1 issue that newbies encounter, and a bit of heart-breaker until you figure out your way around it.

Have fun!

-- Mark

[S. S.]

Actually I would think a better rename would be to RiddlyWiki, because it could be an almost unsolvable riddle how the original creator came up with the vision, and then assembled the one file html program to be so customisable and versatile that even I could answer Jeff's not so un-complicated question! Imagine doing the same in ANY other ready to use program.

On Sunday, January 13, 2019 at 2:52:32 AM UTC+7, Jeff Wilson wrote:

--snip-- TiddlyWiki should be renamed FiddlyWiki --snip--

[TonyM]

Jeff,

We do not mind critsisium, we are always trying to improve things, I expect the documentation to be easier to improve soon.

There is however a reason why what you expected did not work, part of this is using more than one form of coding html, wikitext, macros, css and behind some macros javascript. One does not always embed in the other without further consideration. Show me an example elsewhere of this and we may harvest some ideas.

When we want to embed one "Language" in another a common practice is to construct the code in a macro definition. I will try and locate an example when off my mobile.

My point is tiddlywiki can stimulate our imagination so much we have ideas about how it can be, when there are complications that are not so obviouse, because we have multiple coding methods available at once, in an always up to date interlinked interactive platform.

I empathise, and have thought the same way, but I am starting to see how tiddlywiki raises our expectations to exceed what it currently achives. Most often a work around exists, or the community starts to digest changes to come. The key is the community, conversations and change. Its not that tw is not mature, its that it continues to evolve even although in many respects it already surpasses the competition in capabilities (if not simplicity).

In my view Far too often today, simplicity is the result of the startup culture, which wants to profit from minimalist solutions, to fund the development of more comprehencive solutions by charging and taxing their very same clients. Unnesasary compexity is desirable but not at the cost of capability, unnessasariily simple things fragment what we need to use into too many parts.

TiddlyWiki exists at a point of convergence of multiple technologies and thus is capable of great divergence as well. In this centre there are artifacts, but there is also code patterns and methods to address them.

Regards
Tony

[TonyM]

Mark,

I believe that the ability to change paths across the wiki from when its hosted as a file (Timimi and Other savers), or a bob/tiddlyServer/TiddlyDesk Top node etc... at different IP address/DNS name, folder and Port should have some defacto if not djoure (https://onlinelaw.wustl.edu/blog/legal-english-de-factode-jure/} standard as it is a common need. 

We could actually automate this to some degree using the $:/info tiddlers to generate a here path, ie relative to where it is currently hosted, but allow this to be varied in one or more groups eg images etc...

Regrads

Tony

[TonyM]

A Promised example

Concatenate to get a link

\define doc-link(path name parameters)
$path$$name$$parameters$
\end
 
<a href=<<doc-link "http://gahp.net/wp-content/uploads/2017/09/" "sample.pdf" "#page=3">> >My PDF File</a>

<a href=<<doc-link "http://gahp.net/wp-content/uploads/2017/09/" "sample.pdf" "#page=5">> target=PDFTab >My PDF File</a>

In this case we can embed a macro (with parameters) inside HTML.

The second example is always going to use the same browser tab/window ( a recent discovery of mine)

Regards

Tony

[Jeff Wilson]

What about unconventional things like adding a field? -- I can't figure out how to do so from any of the documentation.

Or other unconventional things like creating and displaying an info hierarchy?

I think there are a lot of things that apply to 80% of the uses of TiddlyWiki that remain labor intensive or mysterious from the documentation, that could be very easily improved by the experts like yourself.

[Jeff Wilson]

Where would I enter the example code below to make the doc-link function available to every tiddler?

[Jeff Wilson]

What would be really cool is to add a custom field to the TiddlyWiki called pdf-page-number, which I could then edit on every page that has a link to the PDF. Then the macro or whatever could use the value in that field to add the '#page=$pdf-page-number$' suffix to the URL.

This would require that I understand several things:

• How does one create a custom field and display it in the editor?
• How does that change the macro below? Is it as simple as referring to the field like a variable, which I believe is $variable-name$?
• Where does the macro get written in TiddlyWiki, and how do I make it available to each page?

On Saturday, January 12, 2019 at 11:15:25 PM UTC-5, TonyM wrote:

[S. S.]

Custom Fields are added to tiddlers either when they are created, or after they are created.
See : Creating and editing tiddlers
When you create a new tiddler, towards the very end there is an area to: Add a new field
Fields created there are custom fields.

However your specific question is to: add a custom field to TiddlyWiki
This request is not clear.

[Jeff Wilson]

I'm probably unclear because I am assuming there is a way to add a custom field once only, and have it show up in all Tiddlers globally, or within a 'sub-story' or whatever a particular branch of content hierarchy is called. 

Am I wrong? If so, this means opening every single Tiddler to add this field, which is a pain.

Edit: Oh, and I assumed you had to add the field name to one place in the TiddlyWiki to make it show up in the dropdown list of the custom fields widget.

[S. S.]

Jeff,

The macro instructions given before can be modified to this:

\define external-document(file:{{!!file}} path:{{!!path}} page:{{!!pdf-page-number}})
\rules except wikilink
<$wikify name="location" text="$path$$file$#page=$page$">

<a href=<<location>> target="_blank">$file$</a>
</$wikify>
\end

Add another new field to your tiddler called: pdf-page-number
Give it a value of the page number desired.

Hope that helps.

Regards.

[Jeff Wilson]

Instead of defining that macro on every page, could I define it in a single place and refer to it on each Tiddler that needs it? How would I do that?

[S. S.]

There are ways of having default fields and other things in tiddlers when creating them (including that macro you created). One way is by using templates.

There are easier ways of adding a field to a group of tiddlers than opening each one individually and adding the field manually. Some information is in: ActionWidgets

[S. S.]

If you look back at the original information given:

Save the tiddler. You have created a Global macro (a variable on steroids) - which can be used as below.

When you need to create the link to the external file using the default path, in the body of the tiddler, type this text:

<<external-document>>

The tag you put in that macro tiddler $:/tags/Macro
Makes the macro a Global Macro - available everywhere.
You only define the macro once.
You just call the macro wherever you want by typing:

<<external-document>>

[Mark S.]

No, you don't usually add fields globally. Once you add a field, it will show up in the dropdown list.

In terms of workflow, what I usually do is to clone a tiddler that has the fields and tags that I want. You can clone any tiddler from the dropdown in the upper right hand corner of the tiddler. You can use the control panel and have the clone button next to the edit buttons if it's more convenient. If you have a dedicated application tiddler, it's also possible to make a button that will generate, for instance, a biological specimen tiddler (with fields like genus, species, habitat already created).

Using templates, you can have edit fields appear in view mode based on tags (or fields) in your tiddler. So you could tag a tiddler "Specimen" and instantly have edit fields available for inserting information. See TW documentation on templates.

Macros can work locally within a tiddler or globally. See https://tiddlywiki.com/#Macro%20Definitions%20in%20WikiText .

-- Mark

[Jeff Wilson]

Unnecessary (accidental) complexity is NEVER justified. Essential complexity is something we have to live with.

Simplicity is obtained when all accidental complexity is removed. I have no problem with complex tools; I use source code IDEs like Intellij, Visual Code, and Eclipse almost everyday.

Undoubtedly much of my problems with TiddlyWiki is that I don't have a good mental model of how it works. But the documentation is awful, so that does not help. For example, I was trying to figure out how to create a list of all tiddlers with a tag equal to the name of the current page. Where do I find that information? I type "list" in the search field, and I get 323 matches. The first one that looks reasonable is "list Operator", so I click on that and get something like this:

purpose	select titles via a list field
input	ignored
! input	a selection of titles
parameter	R = a reference to a field or property of a particular tiddler
output	the titles stored as a title list at R
! output	those input titles that are not mentioned at R

R can reference either a field or a property. See TextReference for the syntax.

• If neither is specified, the list field is used by default. So [list[T]] outputs the titles listed in the list of tiddler T.
• If R consists of only a field or a property, the tiddler part of the reference defaults to the current tiddler. So [list[!!tags]] outputs the titles listed in the tags field of the current tiddler.

Examples

Ooookay... I don't know if that helps or not. Let's click the "Examples" link:

These examples make use of the Days of the Week tiddler.

[list[HelloThere]]

Try it

[list[Days of the Week!!short]]

Try it

At this point, I still don't know what to type in my tiddler.  It looks like it should be something like "[list[<foo>]]" where foo somehow indicates "all tiddlers with a tag equal to the title of the current page", but there's not clue how to figure out what "foo" should really be.

Sometime later I find the tiddler, "ListWidget". Clicking that is promising, this one actually looks like it might be the right thing. One of the examples is:

<$list filter="[tag[ListWidget]sort[title]"/>

This actually works, but it requires me to type the name of the current tiddler as the tag name. Surely there's a way to get the title of the current tiddler to automatically populate?? Somewhere I read that the title of the current Tiddler was in a field that could be referenced like "!!title". Try that, and no dice.

So, I reason, there must be a link to the filter syntax on this page, and sure enough, here it is! "tiddler filter"! I click that and get a huge list of filters, but never fear, there are short descriptions and links to describe each. I randomly click around on several trying to figure out which one works for my usecase, but can't seem to find one suitable. Or maybe I'm not giving it the right parameters. Who knows!?

I eventually (hours later) find an example in another user's TiddlyWiki. (For the record, I'm using filter="[all[current]tagging[]sort[title]]". It works. I don't know if it is the best filter to use for my example, but hey, at this point I will accept anything that moves me forward.) I don't know if I would have ever figured out that particular combination of filters, but hey, whatever.

Now my task was easy, and it was probably a super, super common usecase: I want to create a page hierarchy and be able to view that hierarchy. Shouldn't there be an article or tutorial somewhere on common ways to structure Tiddlers?

Sorry for the long rant, but I'm rather upset that I've wasted two days on this tool.

[Mark S.]

On Sunday, January 13, 2019 at 1:12:36 PM UTC-8, Jeff Wilson wrote:

Simplicity is obtained when all accidental complexity is removed. I have no problem with complex tools; I use source code IDEs like Intellij, Visual Code, and Eclipse almost everyday.

Oh great! Maybe you can tell me how to search for text in all files in a IntelliJ (Android) project -- can look for usages, but not text.

 

There's lots of documentation at TiddlyWiki.com. But you have to be willing to spend some time with it, and it's not all-joined up into a narrative.

Here's a documentation project I started, but not sure if I'll keep up:

  https://marxsal.github.io/twtutor

You can let me know if it shows any hope.

S.S. is also writing some stuff that looks pretty good, so check the forum for that.

-- Mark

[Jeff Wilson]

That's an example of why I still have Eclipse. Much better at searching just text than Intellij.

Took a glance at your documentation, and its more conceptual and task-oriented which is good. But I still don't think it is organized for a non-technical reader.

[TonyM]

Jeff,

There has being a lot of "water under the bridge" in this thread. I think its important to recognise there are a couple of new concepts in TiddlyWiki that also makes it a powerful solution. until grasped it can be a little frustrating, and from my experience it can be a little more difficult for those with a lot of procedural programming language experience.

The payoff is great so please bare with it.

As a community we each have the power to improve TiddlyWiki so please continue to contribute.

Regards

Tony

[Jeff Wilson]

Sure. I'd ask you not to assume anything about my background as you're likely to be wrong.

My point is that I can FEEL the power that's in TW5, but it is obfuscated. I suspect most users get over it and after a while can't remember the pain it takes to use beyond the very very basics. I want to use this tool (or something like it) for a non-technical hobby. I'd expect a wiki tool to be pretty much non-technical and aimed at the casual user. After writing code and mentoring others all week I don't usually want to learn another tool that I can't leverage in my career, and TW5 is teetering on the brink of being just that too much technical to use.

That said, a tutorial or two on doing simple things like "How do I create lists of tiddlers that have something in common, like a table of contents?" would go a long ways towards making this easier for everyone.

[TonyM]

Jeff,

I made no such assumption, just sharing, and my procedural programming experience has caused me some, pause for thought.

The point is we appreciate your feedback and experience, and I think in time you will see I and others here are working hard to help improve things for the whole range of users.

Personally I am about to put draft "editions" online for review,one for people wanting a text editing database, another for people wanting to learn TiddlyWiki, but there are resources already online, I recommend  spending  some time at tiddlywiki.com and where that leads you. Not all cases will be as complex as the list widget/operator because list is one of the key methods in TiddlyWiki, and its use of filters a powerful but new concept for many.

Regards

Tony

[R²]

Hi all,

Here's a documentation project I started, but not sure if I'll keep up:

  https://marxsal.github.io/twtutor

This is an excellent resource! Thanks a lot :) Very helpful and it would have helped even more should I have chanced upon it when I started toying around with Tiddlywiki nearly a month ago. We need more content like that, and perhaps even more crucially, to put forward an "essential reading" list to help with the onboarding process.

There's lots of documentation at TiddlyWiki.com. But you have to be willing to spend some time with it, and it's not all-joined up into a narrative. 

One of the frustrating things with Tiddlywiki is that its potential is easy to feel once you start toying around (though unfortunately not necessarily right from the tiddlywiki.com landing page) yet hard to tap into on the same level. I wanted a killer personal information manager and got a better deal out of Tiddlywiki than Mediawiki/Evernote/Word documents in only a few hours of use... the thing is that I now want my own custom experience, with powerful templates, automatic formatting, project management features, etc., simply because I feel I could get that out of Tiddlywiki, and I sometimes feel frustrated that I still don't have that out-of-the-box or via preexisting plugins, or that I can spend hours to find how to implement what seems to be a tiny feature in the grand scheme of things. I get that this is very much about managing one's expectations: in the real world, I would never expect to be carving a masterpiece a few days after taking up woodworking, yet that has become the typical user experience with software. Just my two cents.

Cheers,
R²

[TonyM]

R2

I have felt the same as you, and invested so so many hours, perhaps driven by a vision, but it is now an obsession. However with knowledge I no longer want a solution that mearly does every thing I can dream of, but for anything I ever will dream of, evolved with feedback loops, discoveries only made if you undertake the journey, journeys perhaps only possible in the tiddlywiki universe.

Somehow tiddlywiki5 always remained tantalising enought that its documentation and limitations were never enought to stop me, perhaps even when it should have. Perhaps knowledge of twc helped me persist.

Will others travel as I have?, Do others become inspired as I have?, I do not know. But for sure I can be a guide now, and even help smooth the way.

Is the challenge too much for others? Its hard to tell after slaying the dragons. But like a quest I can share some "Cheats".

Regards
Tony

[Diego Mesa]

I think very simple cases illustrate the problem with "Getting Started with TW". For example, imagine trying to explain to a new person who just wants to list tiddlers with a certain tag:

<$list filter="[tag[Learning]]">

</$list>

works, but 

<$list filter="[tag[Learning]]">
</$list>

shows nothing.........

We can all maintain

• "TW is incredibly powerful"
• "TW works out of the box as described"
• etc etc etc

 But I don't think we can in good conscience say its "straightforward" for people to start with.