[docs] Introduction to Lists

[Mat]

[edit 2: A final draft can be found at http://introductiontolists.tiddlyspot.com/  Note that this site is missing the varous filtered tiddlers so nothing appears in the examples. It is however intended for tiddlywiki.com where it works, so if you want to see it you can drag'n drop the tiddler or copy-paste the text into tiddlywiki.com.

---------------------------

[edit: For a collectively editable document, see here. Do make improvements but please note that any change is seen by everyone. ]

I hope to get the following "Introductions to Lists" into tiddlywiki.com. The text is intentionally brief - it is just an overview of the relevant concepts collect in one place.

This could/should perhaps be posted on TiddlyWikiDocs... but I figured this forum is more likely to give feedback, especially from noobs. I'm also hoping the Wizards here will point out if anything is missing or wrong.

Note: If you don't like the wikitext formatting below, you can paste the text right into a tiddler on tiddlywiki.com to read it more easily and with working links.

<:-)

---------------------------

title: Introduction to Lists

tags: Learning

text:

Lists play a central role in TiddlyWiki and there are several aspects of lists worth understanding. The following is a brief run-through of some of the more common techniques associated with lists.

Note that lists often don’t have the typical one-item-per-row appearance. This is especially true for //generated// lists (see below).

!Static lists

!!~WikiText

WikiText lists are explicitly typed lists where special characters are parsed to show special styling. Examples include bullet lists created with asterisks (*) and numbered lists (#). Behind the scenes, WikiText lists are based on the simple `<ul>` and `<li>` html-elements. For more, see [[Lists in WikiText]]

!Generated lists

Generated lists center around [[filters|Filters]] in which [[filter operators|Filter Operators]] define which are the concerned tiddlers and which parts of these tiddlers, such as their titles or their texts, that are desired for the output.

!!~ListWidget

This widget is the most powerful tool for creating lists. It allows the filter output to be manipulated and styled within the ListWidget - also into many forms that don't resemble lists at all, for example tables or complex texts.

''Side note'': Even tiddlers themselves are made with a ListWidget. The [[tiddler template|$:/core/ui/ViewTemplate]] lists the templates for each constituting field of the tiddler such as the title, the tags, the text and more.

!!Filtered transclusion

The short form for filtered transclusion (`{{{...}}}`) takes a filter as argument and outputs a line-broken but otherwise unstyled list, unless a template is applied to the output. For example `{{{ [tag[HelloThere]] || $:/core/ui/TagTemplate }}}` lists all tiddlers tagged HelloThere and presents them as tags.

!!list-links Macro

The [[list-links|list-links Macro]] macro was created to let you quickly and easily get a preformatted list, typically a bullet list. Behind the scenes it really is a ListWidget with some styling.

!Other “list related” commands

[[list|ListField]], [[list-before|Order of Tagged Tiddlers]] and [[list-after|Order of Tagged Tiddlers]] are all //field names// to control the position of tiddlers in a list.

[[list|list Operator]] and [[listed|listed Operator]] are //filter operators// that operate on the [[list field|ListField]]. ([[listed|listed Operator]] can also operator on other fields.)

[Diego Mesa]

Thanks for this Mat! Its very helpful and I think essential to the new user experience! 

[TonyM]

Mat,

Good work, Can I suggest full code examples that a user can copy and past into an empty.html to see it working, in addition I hope we may include examples that refer to the current tiddler using its title, tags or fields.

Most people learn by doing.

Thaks

Tony

[Mat]

Thanks guys.

@Tony

Can I suggest full code examples that a user can copy and past into an empty.html to see it working,

Well, the idea is for this to be included in the docs on tiddlywiki.com . This is why I link to each topic there, i.e their detailed docs, where examples typically are included also.

<:-)

[Mark S.]

Hi Mat,

Nice work!

I think without examples that show at least the output, it will be confusing to newbies. That is, they won't immediately grasp what the power of the tool is that is being discussed.

You might call "Static" something like "Static/Manual Lists" to convey that it's being done by hand.

Good luck!
Mark

[TonyM]

Mat,

I agree but elsewhere I pointed out what I ask for is often not available in existing documentation. Ideally such examples will be right next to the guidance that mentions it.

If I prepare some how do I contribute?

Regards

Tony

[Mat]

OK, OK -  @Mark, @Tony and everyone else - let's see what we collectively can come up with.

Here is a public and fully editable document. Do make improvements but note that any change is seen by everyone.

Keep in mind that @Jermolene is the one deciding if it cuts it for tiddlywiki.com so stick to the Documentation Style Guide.

<:-)

[Diego Mesa]

Hey all,

I just came across Eric Shulman's impressive "Inside TiddlyWiki: The Missing Manual"! 

https://github.com/ericshulman/InsideTiddlyWiki

I know there has been a lot of discussions recently about the best new user experience and a bit of a refresh of tw.com centered on new users, and I thought this contributes much to the discussion!

Diego

[Eric Shulman]

On Sunday, December 3, 2017 at 6:38:52 AM UTC-8, Diego Mesa wrote:

I just came across Eric Shulman's impressive "Inside TiddlyWiki: The Missing Manual"! 

https://github.com/ericshulman/InsideTiddlyWiki

I know there has been a lot of discussions recently about the best new user experience and a bit of a refresh of tw.com centered on new users, and I thought this contributes much to the discussion!

Thanks... it should be noted, however, that although the "TiddlyBook" framework and *outline* for topics is there, and some of the introductory materials have been written, much of the actual instructional content is still incomplete.  Unfortunately, while I have a clear idea of what I intend to write, progress on actually completing the book has been at a virtual standstill for quite some time due to personal circumstances outside of my control (primarily health-related problems).  I still plan to complete the work, but it's not there yet.  Thus, the "Missing Manuals" tag line in my signature.

Also, the URL you provided is a link to the github repository for the book, but there is also a direct "GitHub Pages" URL that allows you to directly view and interact with the document online:

http://tiddlytools.github.io/InsideTW/

enjoy,

-e

Eric Shulman

TiddlyTools.com: "Small Tools for Big Ideas!" (tm)

InsideTiddlyWiki: The Missing Manuals

[Mat]

@everybody

I've filed a PR and you can see the final(?) version  here. Note that the links are dead and the lists don't render because the doc is intended for tiddlywiki.com that has the required data.

Thanks to everyone who contributed!

<:-)

[Mark S.]

On my browser, WikiText and ListWidget (headlines) have tildes (~) appearing in front of them. They don't show that when transferred to tiddlywiki.com. Odd.

Mark

[Mat]

On Monday, December 4, 2017 at 4:26:40 PM UTC+1, Mark S. wrote:

On my browser, WikiText and ListWidget (headlines) have tildes (~) appearing in front of them. They don't show that when transferred to tiddlywiki.com. Odd.

I guess you're talking about when you view it on my temporary site, i.e http://introductiontolists.tiddlyspot.com/ - i.e not on a TW of your own.

Yeah, it's probably something I've messed up in my TW template. This of course doesn't affect the issue we're dealing with. I just put up that site to share the end result of the document.

Thanks for your help.

<:-)

[tobaisch]

Am Sonntag, 3. Dezember 2017 01:49:25 UTC+1 schrieb Mat:

Behind the scenes it really is a ListWidget with some styling.

 Behind the scenes??

[tobaisch]

Am Sonntag, 3. Dezember 2017 03:27:25 UTC+1 schrieb Mark S.:

Hi Mat,

I think without examples that show at least the output, it will be confusing to newbies.

Exactly my opinion.

[Jed Carty]

The extra ~ are just because the wiki has camel case linking turned off so the ~ to suppress the wikification of camel case show up. They won't be visible on tiddlywiki.com.

[tobaisch]

Am Sonntag, 3. Dezember 2017 02:31:36 UTC+1 schrieb TonyM:

Mat,

Good work, Can I suggest full code examples that a user can copy and past into an empty.html to see it working, in addition I hope we may include examples that refer to the current tiddler using its title, tags or fields.

Most people learn by doing.

Exactly Tony, that's my opinion too.
That's exactly how I learn.

[Mark S.]

Yes, in the actual macro it looks like this:

\define list-links(filter,type:"ul",subtype:"li",class:"")
<$type$ class="$class$">
<$list filter="$filter$">
<$subtype$>
<$link to={{!!title}}>
<$transclude field="caption">
<$view field="title"/>
</$transclude>
</$link>
</$subtype$>
</$list>
</$type$>
\end

You can see that it's just a <$list> listwidget with additional stuff added.

-- Mark

[tobaisch]

thx mark,
that looks not so clear to me.
is there a example-tiddler to understand how it works in "real life"

Regard
Tob

[Mark S.]

You mean how it's used?

https://tiddlywiki.com/#list-links%20Macro%20(Examples)

Good luck
-- Mark

[Mat]

@tobaisch

is there a example-tiddler to understand how it works in "real life"

Note that  http://introductiontolists.tiddlyspot.com/ does contain examples BUT because they list tiddlers that are missing in that TW, nothing is seen. The tiddler is however intended for tiddlywiki.com where you will see the actual output in the examples.

You can drag the tiddler or manually copy its contents into a new tiddler on tiddlywiki.com to see the real output examples.

<:-)

[tobaisch]

The website https://tiddlywiki.com is known to me.

I also know all the examples there.
If I search here in the forum I have already searched on https://tiddlywiki.com before and found NOT a solution
I just do not understand the explanations there.
I can not find an answer to my questions there.
That's why I ask here in the forum and hope for new explanations or examples.
Your Link: https://tiddlywiki.com/#list-links%20Macro%20(Examples)  doesnt help.

i mean how i used:
type:"ul"
subtype:"li"
class:""
<$list filter="$filter$">?
<$subtype$>?
<$link to={{!!title}}?
the example: "<<list-links filter:"[prefix[J]]">>" is everytime the same example.
Regards
Tob




[Måns Mårtensson]

Hi Eric

I remember at one of the TiddlyWiki hangouts you told that a friend of yours asked if he could get an empty version of your InsideTW document.

I'd love to see your InsideTW published as a TW-edition in its own right.

Is there any hope that you will publish it as a document we can use from scratch?

Cheers Måns

--
You received this message because you are subscribed to the Google Groups "TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywiki+unsubscribe@googlegroups.com.
To post to this group, send email to tiddl...@googlegroups.com.
Visit this group at https://groups.google.com/group/tiddlywiki.
To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/f73cf084-32d1-4490-b167-4e6517116f8a%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Mark S.]

There's 2 different topics.

You asked about "behind the scenes" so I explained how the <<list-links>> macro works. I don't know if that is ever useful, but you asked.

The other topic seems to be about how to use list-links. So I provided a link to https://tiddlywiki.com/#list-links%20Macro%20(Examples) which shows how to use list-links.

You seem to have some other question.  Post your question clearly and I'm sure someone can help.

Mark

[tobaisch]

So I provided a link to https://tiddlywiki.com/#list-links%20Macro%20(Examples) which shows how to use list-links.

Thats the problem.
You think you show me how to use list-links.
But I do not understand what you showed me.
Only you understand this explanation.
Everything is super easy and understandable for you.
You refer to a link on tiidlywiki.com and everything is fine.
It does not help if you keep showing it.
That's why I'm asking for examples.
We are spinning in a circle.
Thank you for your effort.
Regards
Tob

[Diego Mesa]

Hey tob,

I’m pretty much a newb myself. I’m happy to help you some more offline (I’ll email you directly)

[Mat]

@Diego / Måns / Eric - kindly take the MissingManuals matters in a thread separate from this one. 

@tony wrote (and @tobaisch concurred) 

>Can I suggest full code examples that a user can copy and past into an empty.html 

Well, no. Using empty.html to demo generated lists is a bad idea because the it would have to be with shadow tids. Not very educational for newbies, IMO.

I opted to use tiddlers that show up when this "Intro to Lists" is in the context I aim for, i.e on tiddlywiki.com. The idea is not really that users copy this tiddler into their own TWs.

@tobaisch - this thread is about the document that I/we are writing and while it is (only) intended to be an "Introduction to Lists" it is not an actual attempt at real teaching. The links are in the doc should lead you to more detailed explanations. If you don't understand those explanations, the best thing is for you to clearly explain what it is you want to achieve or in more detail what it is about something that you don't understand so that we can explain it. Just saying "I don't understand" makes it very difficult for someone to explain because it is not clear WHAT you don't understand. Be specific, please.

<:-)

[Dave Gifford - http://www.giffmex.org/]

Hi all

I like this description. Great idea.

I think the section on filtered transclusion could be improved, however. Here is my best attempt, for what it's worth:

Wrapping a filter (for example `[tag[HelloThere]]`) with triple brackets (`{{{ [tag[HelloThere]] }}}`) produces a linked list of the titles of all relevant tiddlers. You can also apply a template to the filter, for example `{{{ [tag[HelloThere]] || $:/core/ui/TagTemplate }}}`, which renders like:

I hope this is helpful. I wish I had more time for helping with documentation, but my employment and other personal projects are taking up most of my time. Blessings to all.

[Jeremy Ruston]

Thanks, Mat, I've committed the changes, and they are visible now in the prerelease:

https://tiddlywiki.com/prerelease/#Introduction%20to%20Lists

Your PR is merged here:

https://github.com/Jermolene/TiddlyWiki5/commit/2b21b74c500421423a543a2f5061e54d3d4f1c73

It's worth noting that I had to do a bit of cleaning up that you can see here: https://github.com/Jermolene/TiddlyWiki5/commit/49b3ed4770e8669b448a097e14ff0f17d7fb9abe

* Style tweaks

** Spaces after the "!" of titles

** Blank line after titles

** Sentence Case for Heading Text

* Make use of wikitext-example-without-html macro for the examples

* Make use of .tip macro for tip

* Some phrasing improvements and clarifications

Taken together with the discussion in this thread, it serves to illustrate that maintaining documentation is difficult, intricate work requiring attention to detail and exhaustive knowledge of what is already there. It's going to be a group effort to get things up to the standard we'd all like to see.

Best wishes

Jeremy

[Mat]

[Sorry for deleted post above]

Jeremy,

Big thanks, the result looks terrific!

<:-)