Is the code or the documentation correct???

[joearms]

I wanted to list all core images so I wrote

<<list-links "[prefix[$:/core/images]]">>

I saw nothing - Am I going nuts? this worked

<<list-links "[prefix[How]]">>

This did what I expected - what does the "documentation" say

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

(I assume this is the definitive version)

   This example lists all the tiddlers whose titles start with J:

   <<list-links filter:"[prefix[J]]">>

Applying the principle of least astonishment then

   <<list-links "[prefix[$:/core/images]]">>

Should list all tiddlers whose title starts $:/code/images - but it does not

Given that the code (ie the observed behaviour) and documentation differ

I do not know if

    a) the code is correct and the documentation is in error - so I report an error in the

        documentation

    b) the documentation is correct and the code is wrong so I report an error in the code

Since documentation is easier to read than code (which is why we write it) I strongly

believe that the code should document what the code is supposed to do and NOT

what the code actually does - and then people can report errors in the code when they find them.

At the moment when code and documentation differ nobody knows which is correct and

an ad hock decision is made as to which is correct.

As an aside I'd like to add that this is not a new problem - when we developed Erlang the code

and development was always out of phase.

When I wrote [shamless plug] https://pragprog.com/book/jaerlang2/programming-erlang

I decided to describe exactly what the system should do even if this was not what the system

actually did. I said that the book was definitive and if the code in the delivered system behaved in

a different manner to the book then file a bug report since the code was incorrect.

In a new system, the code will always be further advanced than documentation since we don't yet know 

what the system should do.

In a mature system, we should now know what the system should do so the documentation should be definitive and not the code.

Tiddlywiki is mature - so maybe we should concentrate on definitive correct documentation and describe what the system is supposed to do and not what it actually does.

Cheers

/Joe

[Jeremy Ruston]

Hi Joe

I think I answered this one in my previous reply: all of the anomalous behaviour you're describing is due to the way that "shadow tiddlers" work.

Shadow tiddlers are the payload tiddlers of plugins. They have several properties:

* They don't show up in listings without taking special steps to include them

* Viewing/transcluding a shadow tiddler works as normal

* Shadow tiddlers can be overridden with an ordinary tiddler which replaces it. If that tiddler is later deleted, the shadow is restored

The core is itself a plugin, and so its components are shadow tiddlers.

Best wishes

Jeremy.

--

Jeremy Ruston

jer...@jermolene.com

https://jermolene.com

--
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 tiddlywikide...@googlegroups.com.
To post to this group, send email to tiddly...@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/94151e99-911f-4b53-b52f-3e620d0ebb9d%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[PMario]

On Saturday, December 15, 2018 at 11:38:52 AM UTC+1, joearms wrote:

I wanted to list all core images so I wrote

<<list-links "[prefix[$:/core/images]]">>

I saw nothing - Am I going nuts? this worked

<<list-links "[prefix[How]]">>

This did what I expected - what does the "documentation" say

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

(I assume this is the definitive version)

   This example lists all the tiddlers whose titles start with J:

   <<list-links filter:"[prefix[J]]">>

Applying the principle of least astonishment then

   <<list-links "[prefix[$:/core/images]]">>

Should list all tiddlers whose title starts $:/code/images - but it does not

That's right. see:https://tiddlywiki.com/#SystemTiddlers ...

Tiddlers are classified as system tiddlers if their title starts with the special string $:/. The only difference from ordinary tiddlers is that they are hidden from most searches and lists ...

So your filter needs to be [all[shadows]prefix[$:/core/images]]

all operator: https://tiddlywiki.com/#all%20Operator

A TiddlyWiki contains 3 types of tiddlers.

 - Shadow tiddlers ... come with the core or with plugins, start with $:/, should be hidden from end-users, can be overwritten, but not deleted.

 - System tiddlers ... should be hidden from end-users, because they are used by the core TW for internal tasks. eg: state-tiddlers

 - tiddlers ... everything, that endusers / consumers should see by default.

With TWclassic we had a lot of problems with so called "system-tags". TWc doesn't know about the $:/ prefix. So plugin authors and content creators, did create tags, that shouldn't be seen by consumers. ... That's why a mechanism was created, that allowed creators to "hide" those tag tiddlers from consumer-facing lists.

Some special tags where invented. excludeLists, excludeSearch, excludeXXX ... In the long run, this mechanism caused more problems,

-m

[PMario]

I was too slow ;)

-m

[joearms]

Thanks - I understand

So I now think

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

Should say something like:

This example lists all  "regular" tiddlers whose titles start with J:

<<list-links filter:"[prefix[J]]">>

NOTE: This does not list all tiddlers - in particular, system and shadow tiddlers are NOT listed

So for example to list all core images (which are shadow tiddlers) we use the  following syntax

    <<list-links filter:"[all[system+shadows]prefix[$:/core/images]]">>

Or similar

Cheers

/Joe