Let us talk about de facto standards

#1

Something I have raised a number of times but not received feedback on, is allowing the community to develop and agree to some ‘‘de facto’’ standards.

  • Here I am referencing wikit text and wiki script, if something similar were to be done for JavaScript and development, it should be maintained separately.

This would allow macros and plugins to be written to these standards such that they are interoperable with other published macros and plugins. To a large extent all that is required is;

  • Agreed tiddler names
  • Agreed tiddler formats
  • Agreed Field names and functions
  • A TiddlyWiki.com documentation tiddler or on a custom community wiki.

For example
I intended to build MRU '‘Most Recently used’ features into some of my published solutions and tools.

  • Each time you navigate to a tiddler capture the last navigated time, and count the number of visits.
  • This allows the user to return to the most recently used or the most visited tiddler easily from a list.

I have also developed a strategy to enhance ‘‘copy to clipboard’’ functionality to include an “in wiki clipboard”, This would allow;

  • In Wiki paste button(s)
  • A paste box containing past copies
  • TiddlyWiki aware copies such as title, titles, tag/tags, list, filter, field value
    • from which you can select in context
  • Ability to search the clipboard(s)
  • A relationship to MRU above

Whilst I can see the above examples are easy to implement, what I am really interested in is setting up a process for the development and documentation of de facto standards we can all use and leverage together.

  • Of note, it will be totaly ‘‘optional’’ if anyone makes use of these standards
  • However if you do, your solution’s will gain function through interoperability and hackability.

Relationship to core?

  • Such standards, being optional, need not be included in the core, thus permitting simpler and shorter adoption.
  • Being optional and shared, more generic naming standards can be used without needing to name with qualifiers, and these will be documented to allow clashes to be identified, if not simply avoided.
  • Solutions could reference the documented standard to which they have being written. Saving time, adding clarity and assisting modifications.
  • Various common and best practice code snipets can be documented and shared this way.
  • Existing solutions can be rewritten to use a new standard and gain interoperability.

What do you think?

#2

For what can be agreed upon, I think would be fantastic, but with as dynamic as tw is, it might be hard to find things that all types of users can use in a standardized way. (Not saying its impossible, quite the opposite!)
As someone that has hobbies involving web design, creative writing, and studying journals, finding common formatting for my own use is very… nitpicky :sweat_smile:

That being said, discussion of all the different formats and techniques each user uses could better help others decide on standards they can implement into their own work.

For instance, I have specific guidelines for titling, tag types, and the like, that works for me but might not work for others. I know some users like PascalCase titles, others use under_scores for url friendly titles, etc.

BUT i do think discussion of plugin organziation, good stylesheet practices, common macros that you find useful, tiddler sorting (ie toc, zettelkasten, tag pooling, etc.) Are things that everyone 100% benefits from imo.

For anyone curious of what I use though…

3 tag types,
Classification: Tags ie Type: Journal Entry
Contextual (Tags) ie John Doe (Fisherman)
System Tags ie $:/abc/...

titling,
Topic (Context) ie John Doe (Fisherman)
Chain Topic #n ie Journal Entry #4
YYYY-0MM-0DD 0hh:0mm:0ss for date/time, ie
2023-03-15 Changelog

When creating a new TW,

  1. Create changelog
  2. Make and doc changes
  3. Save as template
    3.1. Use copy of template, update template when in need, etc.

  • I don’t use a ToC, but instead a tag pool.

  • I refer to segments of text in tiddlers as tidbits.

  • i organize my custom system tiddlers following the same structure as tw has in place, but make a moresidebar tab for all my $:/…/jmh/… tiddlers.

I could go further into detail, but man, thatd be a list, but just above I’m sure my system wouldn’t work for others or could be improved, so I’m lookong forward to how others use their tw so I can learn from them :blush:

#3

Thanks @Justin_H for your comments. My idea was to keep it quite simple, and personally I would stay away from styling and presentation and leave these in themes and pallets etc…

  • Extracting some examples from your "creating a new TiddlyWiki to illustrate.
  • These are quick examples not worked through yet, I expect the “entries” should be in a separate date time stamped data tiddler.

Changelog/Wiki Releases
Place to annotate wiki changes and releases

  • Stored in $:/wiki/releasenotes caption=“release notes” tagged $:/tags/SideBar
  • Format text, version, note, date/time
  • Perhaps it is published in a Control Panel tab with a toggle to display in side bar?

Manifest
List of plugins, tiddlers and macros used to build this wiki, may reference external files eg; favicon as well.

  • Stored in $:/wiki/manifest caption=“release notes” tagged $:/tags/SideBar
  • Automatically list plugins?
  • Can you explain a tag pool, is it a cloud?

My Idea would be we start a thread say on “Defacto side bar tabs eg Changelog, Manifest, current tiddler details”, then from this we may spawn a “Manifest Discussion” where the community develops an approach and standard, the end result being a new “Manifest de facto standard” we publish.

#4

Sure thing, the general concept is just a sidebar tab that behaves much like the moresidebar tab for tags, except that it sorts by tag type (I usually use the tag color) and instead of being in a single row, fills as much available space, more like if it were a paragraph of text.

From there, Its just clicking on a tag specific to what I’m lookong for, for instance a tag of “Type: Journal Entry” would list all journal tiddlers, or a tag of Status: Fubar would be a broken tiddler (some military slang :sweat_smile:) et cetera.

It was a quick way I found myself using to sort tiddlers, often times using a combination of tags rather than a hieretical system like what can be seen with the toc on the official tiddlywiki.com contents tab.

I like your use of the $:/wiki/… section for organizing system tiddlers, though I think combining release-notes and manifest into $:/wiki/docs/… would fill closer to the structure already set by tw.com

I’ll be honest until just now I wouldn’t have known the meaning of manifest in the way you used it, so I think using $:/wiki/docs/release-notes/yyyy-mm-dd might be easier to understand.

Just my perspective on things :grinning_face_with_smiling_eyes:

#5

What is and how do you define type?

  • See my previously shared reimagine tags to turbocharge tag-pills, and my current work on filter-pills
  • Manifest is different to release notes and is a list of components, flights, or on holidays you have manifests, as do application packages. The idea is to get a generic name and standard but changing its caption to say “components” or an icon, would be at the wiki owners discretion.

Other “naming” standards for custom edited tiddlers may include;

  • About this wiki information eg $:/wiki/about-info
  • Wiki Licence $:/wiki/licence
  • I currently use $:/config/wiki-name to store a formal name I use in a directory wiki

However it seems with a list or items it is best moved to separate tiddlers or a data tiddler, or with a tag, this allows new entries without overwriting existing entries.

#6

Ah, I was just using a general word. To correct myself, I would sort by a specific tag field, the one I choose to use is sorting by color, as it adds a nice visual indicator, and isn’t used for much else.

Your filtered tags are pretty impressive, I played around with something similar but less polished before moving to a different project.

Do you have the ability to set a caption to the filtered pill? Say you sort by [tag[todo]!tag[done]tag[work] and want the tag to just show as “Work Tasks (n)”?

Ah ok I see. I had assumed that might be the case but wasn’t too sure. My suggestion was putting release-notes and manifest (is it the same as a manifesto?) Under docs. Ie. $:/wiki/docs/manifest/.... or $:/wiki/about

Maybe I’m misunderstanding, I’m not too sure :sweat_smile:

1 Like
#7

Yes, already done, I call it the label.

1 Like
#8

At a high level I certainly agree.

And things like shared names, especially under the $:/wiki/ namespace are clear and easy wins. Any user who wants the same information under a different name, say, “License”, could simply transclude $:/wiki/license, but common tools could count on this tiddler either being available or at the very least having a standard meaning if it does exist.

Agreed tiddler formats is harder; I’d love to hear more about what you’re considering.

The same is true with field names and functions. I think it would be difficult to find common names that people are not already using, and which they’d be loathe to change. We could overcome this by using the same sort of namespacing for certain fields, the way we do for system tiddlers. But that’s a bit ugly.

I don’t understand what you mean by this:

What sort of standardization are you suggesting here?

That sounds useful. But how would you suggest standardizing this? Would there be a standard implementation that users could simply import, a plugin or json-tiddler? Would there just be standard naming that any such tool creates to support interoperability? Something else?

I think I’d need to hear more, and especially more specific examples to be sure, but I think it’s a good idea. Do you have any more concrete suggestions?

I can imagine a document that includes in part something like this:

  1. Well-known tiddlers

    • $:/wiki/about: A brief overview of the purpose and contents of the wiki

      For example,

      While other wikis discuss the U.S.'s Legislative, Executive, and Judicial branches, here we
      take on the most familiar parts of the U.S. Government:

      • The Bureau of Red Tape
      • The Department of Redundancy Department

    • $:/wiki/authors: A bulleted list of authors responsible for the wiki.

      For example,

    • $:/wiki/license: The license under which the wiki is shared. This should be either

      • The text of the license used by the wiki, or
      • [optionally a brief introduction to the license, and] a link to the location of the license.

      For example,

      Copyright (c) 2012-2023 John Doe and others

      Permission is hereby granted, free of charge, to any person obtaining
      a copy of this software and associated documentation files (the
      “Software”), to deal in the Software without restriction, including
      without limitation the rights to use, copy, modify, merge, publish,
      distribute, sublicense, and/or sell copies of the Software, and to
      permit persons to whom the Software is furnished to do so, subject to
      the following conditions:

      The above copyright notice and this permission notice shall be
      included in all copies or substantial portions of the Software.

      THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
      EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
      MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
      NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
      HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
      WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
      FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
      OTHER DEALINGS IN THE SOFTWARE.

      or

      This wiki is shared using the CC-BY-4.0 license.

    • etc.

But that’s specifically for the simplest bit, tiddlers with well-known names. I’d be curious to see what you might mean for the other ideas.

1 Like
#9

Hi,

I do like the idea of a $:/wiki/ namespace, as discussed by @TW_Tones, @Justin_H and @Scott_Sauyet but I think the system namespace lacks visibility, so it should be at least be completed with a tab in $:/ControlPanel, especially if License information is stored there.

Fred

#10

I do not understand why it should be system tiddlers. I personally would prefer About, License ... Since they should be shown anywhere anyway, they can be visible in the sidebar as well.

just my thoughts

#11

Hi,

I’ve been working on Fields naming schemes in a project of mine.
It is very much a work in progress, but here is what I’ve got by now:

Fields naming and namespaces

  • Some fields should have their names standardized. I chose to prefix them with @ and call them “@Fields”
  • I also wanted to use namespaces with @Fields, but found that using / causes problems with filters, so I chose . as a separator.
  • Most of my use of @Fields is for TW development purposes, but I also needed a more general namespace for tiddlers documentation, and I chose @self for this.
  • I currently use:
    • @self.description: a description of the tiddler’s purpose. Example: “Macros definitions for XXX ViewTemplate”
    • @self.status: current completion status. Example values: “wip”, “done”
    • @self.todo: list of tasks for this tiddler, when @self.status is wip. Example value: [[Add a section for Actions]] [[Add a section for Attendants]]

Regarding @self.todo's value format: I display todo items in a Tiddler header thanks to a ViewTemplate, using tw5-checklist plugin inside a <$list> widget with filter={{!!@self.todo}}.

Here are other @Fields I use in my project (which is about dynamically generating Input Forms for new tiddlers’ properties, based on meta-data stored in @Fields):

@field.caption, @field.constraints, @field.display, @field.increment, @field.maxValue, 
@field.minValue, @field.name, @field.options, @field.type, @field.unit, @field.value, 
@form.caption, @form.fields, @instance.fields, @instance.icon, @instance.mandatory-fields, 
@instance.tags, @item.cascade-index, @type.mandatory-fields

Fred

#12

Hi @pmario

I had the same reaction as you, but I think it’s a matter of balance between user-content vs meta-data.

When I use a wiki and search for something, I’m looking for actual content, not meta-data (which might nevertheless be very important). “Hiding” some information in system namespace just prevents it from appearing in search results.

Fred

2 Likes
#13

I think keeping them as system tiddlers could keep the history of the TiddlyWiki clear, and out of the way for someone didn’t want it appearing along with their other tiddlers, but does want to have these tiddlers in their wiki.

But I think it’s largely a matter of preference where users keep it or if they even keep it at all, so I’m not entirely sure if I myself would have them as system tiddlers or normal tiddlers.

:man_shrugging:

#14

The advantage of system tiddlers here is that it’s trivial to layer the non-system tiddlers atop them with a simple transclusion if you want an About and License page, but they don’t clutter up the interface for those who don’t want them.

3 Likes
#15

Thanks all for your responses;

  • Please consider telling us what you think needs a “de facto standard” without going too much into the details.

Actually most formats are simple; we just need to have them stated, it may just specify its a data tiddler, this is the key, this or that field is optional or required, a particular delimiter is in use.

Although if you think about it, without “de facto” or “de jure” standards, people do come up with their own names and Interoperability is low. If a designer is looking for interoperability, they have nowhere to go. With the existence of an optional standard, use may converge on that standard over time.

  • Still to be debated but I like simple language names like “tooltip” or short forms “alt-title” (alternative title) without encodes or prefixes, and It rarely clashes.
    • Actually that is part of the informal standard, what are your degrees of freedom?

Re: MRU Features and others;

  • This needs to be discussed to see if we can establish a standard, but for example a data tiddler who’s key is a tiddlywiki date stamp and its value a tiddler name.
  • Although we may share code, macros or plugins this is not the key intention, its about sufficient information you can build your own or use someone else design.
  • If we have a standard the way people write solutions to those standards are where the innovation and diversity takes place, only the minimal information that allows interoperability is needed.
  • One I read/receive more feedback I will start a trial discussion

Yes, this would be a de facto standard we can decide on, lets say we choose the “licence” tiddler, as @pmario implies, we may encourage it be tagged $:/tags/ControlPanel

  • Again what is a standard about?, I would think agreeing on the “licence” tiddler is a simple agreement, the tiddler is simple, searchable, predicable. But we could have flexibility eg the licence is stored in $:/wiki/licence for which “licence” would transclude {{$:/wiki/licence}}

Publishing an optional namespace method is a good idea, with the relink plugin installed and appropriate configuration, we can move between namespaces.

  • In someways a namespace is so you can avoid a clash with a standard, personally I am, interested in this as an option, good standards suggest graceful methods to break the standards, but I am more interested in the defacto standard, from which namespaces set themselves apart from (If that makes sense).
  • Thanks for sharing your field naming practices. I too like the name.namspace method as it is similar to domain names.
  • We actually have some ways to solve these questions but to reply here would be Off Topic, but perhaps an appropriate de facto standard would help here.
  • If it is something we may want to hide then a system tiddler is appropriate, with a regular tiddler transcluding it to be visible. If you don’t want it hidden then is should be a regular tiddler, found in the standard search.

Thanks all, Keep your thoughts coming.

#16

I would like to suggest making the tab as “Metadata” or something similar, to contain sub tabs for the licence, the about section, et cetera.

Well, If I were to think about a de-facto standard, I would 100% encourage the creation of release notes or a changelog or a timeline if you are modifying significant sections of a standard tiddlywiki, and how you intend it to be used if others are interested in doing so.

I think it would be good practice to keep formatting as close to what is used in TW, such as camelCase for UI, kebab-case for other things.

The usage of iso 1806 in some way (yyyy mm dd) would be a good idea since different parts of the world use different formats (here in the usa, its month-day-year for reference)

We can make a list of proposed standards here, and then start a poll to vote on what should be used and what can be kept for personal use?

As far as custom names go, I experimented with the usage of the ¢ent symbol for denoting macros, css elements, et cetera, like the $ standing for $ystem, the ¢ would stand for ¢ustom or something similar, and can be bound to a keyboard shortcut (one I use is alt 4, since it’s also a money symbol) so maybe this would be useful in some way?
Just food for thought.

#17

Thanks for your suggestions @Justin_H

Yes, perhaps a subset of the current recent tab? or a special Journal?

Should it not be the tiddlywiki time stamp [UTC]YYYY0MM0DD0hh0mm0ss0XXX from which iso 1806 is the prefix?

Some examples of “to be proposed de facto standards”, a new topic? could be started once we work out the community process.

  • Note that the following are 100% optional, map to the default behaviour and extends it a little. But if not used have no negative impact, just things relying on them may not work. Yet, such solutions will include the use of the standard.

Possibly a standard that may need to be established first is mode handling, and to support it configuration tiddlers.

For example I have a $:/config/design-mode tiddler, containing the field config-values “yes no” and the text field is set to yes or no.

  • In the example of release notes a new “release” button would appear only if [{$:/config/design-mode}match[yes]]
  • If we leave the release tiddlers to be freely named, then the key is to set each with a release-note-date which is the field on which it is listed/sorted.

Config tiddler standard

  • Tiddlers with the prefix $:/config/ contain a value such as yes/no show/hide stored in the text field
  • Such config tiddlers may have a config-values field which can contain a list of values and/or a filter that will result in the possible values.
    • If no value is returned then the configuration value is not “permitted to be changed”.

Mode handling as a rule would use a global value found in the config tiddler, such as $:/config/design-mode however any tiddler could have a matching fieldname eg design-mode with an overriding local value.

  • Thus some macros, code, or templates would include the following test;
  • [all[current]get[design-mode]] :else[{$:/config/design-mode}] +[match[yes]]
    • Untested just now
  • If you were constructing a button to select the local value of design-mode you would add the prefix $:/config/ and test of there is a config-values field.

Advanced mode handling including a variable.

  • This would first test for a variable eg <<mode-handling>>, then the local field !!design-mode then the config tiddler $:/config/design-mode.
  • This allows a $let or $set to wrap a block of code for which the design-mode value is set.

List of proposed modes resulting in a matching -mode - config tiddler, field and variable name, including the config-values field.

  • design yes/no
  • debug yes/no
  • author yes/no
  • verbose yes/no
  • wiki (read-only view update edit design)
    • View mode allows view/update/edit (possibly design) modes to be selected
    • When selecting the wiki mode one can optionaly set the other coropsponding modes.
#18

I’m still thinking it through. I’ll try to have an answer in a few days.

I meant that coming to agreement is harder. It’s pretty easy to agree that we include About and License tiddlers, and suggest a de facto standard location for them. These things have clear analogies in web sites and open source projects. But finding tiddler formats that seem common enough and then agreeing of the appropriate field names seems a much more difficult challenge.

While I might find that useful, I might also prefer a version that tracks the most visited over the past day/week/month, which would involve a rolling log of visits I can query to detail the most important sections. Since that would have enough information to also yield a MRU list, it’s possibly to argue for this to be the important format. (I’m not really trying to argue this, just to point out that this sort of things is more challenging to standardize than About/License.

One thing I think we would need to establish is who/what these pseudo-standardized behaviors are for. Are they intended primarily for other TW-award users to understand and more easily remix functionality from a wiki? Are the intended for automated tools to better report on the features of a wiki? Are they for writers of plugins who can say, “this should work on your wiki so long as you follow standards 2, 4, and 7(b)?” Or are they for someone else entirely?

1 Like
#19

Lets say I am an optimist especialy if we keep it simple, Hopefuly expressing obviouse shared standards in native tiddlywiki.

To me the ones to use are of useful shared value.

All wikis could use release notes, a shared clipboard etc…