Wikitext docs overhaul first step #6828

pmario · 2022-07-26T13:45:07Z

The WikiText tag now creates a more logical sort order
There is a button to open all wikitext rules in the StoryRiver
Formatting in WikiText uses a table now and has more info
There is a new wikitext-template tiddler, that adds a footer to every tiddler tagged WikiText. The footer links back to the WikiText tiddler.

There may be more steps, but this could be a start. This discussion at Talk triggered the PR.

pmario · 2022-07-26T13:53:33Z

There is a JSON file, which can be imported, to see what's going on

twMat · 2022-07-26T20:51:16Z

editions/tw5.com/tiddlers/wikitext/Formatting in WikiText.tid

-* `~~strikethrough~~` for ~~strikethrough~~ text (<<.icon $:/core/images/strikethrough>>)
+<div class="no-code-border">
+
+|Wikitext | Editor Button |HTML |Rendered Output |h


Second col has centered headline text.

Maybe change third col heading "HTML" into "HTML equivalent" or "rendered HTML" or some such because the people reading this whole tid are typically beginners and may otherwise believe that they need to know this (i.e learn html)

Overall for the table, I imagine an English teacher complaining about using "2" instead of "Two" or "Double".

Second col has centered headline text.

That's intentional. The buttons are centred too. It looks better.

Maybe change third col heading "HTML" into "HTML equivalent" or "rendered HTML" or some such because the people reading this whole tid are typically beginners and may otherwise believe that they need to know this (i.e learn html)

I think I'll remove that column and add the HTML output to the end of the tiddler. eg: For those who are interested.

"2" instead of "Two" or "Double".

That's intentional 2 ... IMO the number is much more visible as the word two. It's especially needed for ''bold''

twMat · 2022-07-26T20:51:23Z

editions/tw5.com/tiddlers/wikitext/Formatting in WikiText.tid

+<div class="no-code-border">
+
+|Wikitext | Editor Button |HTML |Rendered Output |h
+|```backticks` ``are used for  for code | (<<.icon $:/core/images/mono-line>>) |`<code>backticks</code>` are used for code|`backticks` are used for  for code |


IMO the output looks better with... hm I need to type it explicitly because github renders it otherwise:

backtickbacktick space backtickFOObacktick space backtickbacktick

i.e which renders symmetrical spaces around the backticked word.

Also note the double "for" in both the first and the last table columns.

My CSS settings got messed up. It should look like this:

twMat · 2022-07-26T20:57:51Z

IMO the output from a simple list-links macro is not particularly elegant for longer lists. I would prefer either a more hierarchical list with proper headings and subheadings (e.g "Complex elements" listing e.g tables and lists etc).

...Even more readable would be a ToC widget presenting these items, instead of a plain list. That way it could actually all be presented in one tiddler (a little at a time). I understand it is not optimal for small screen (...but on the other hand, how on earth do you find the special characters in the mobile keyboard anyway) but maybe there could be a media query or some responsive design...

twMat · 2022-07-26T21:11:09Z

All options to format wikitext can be found at WikiText

Maybe instead:

See WikiText for the full list of formatting options.

pmario · 2022-07-27T06:33:02Z

@twMat

I think the following table is much more useful as the first one:

Jermolene

Thanks @pmario just a few minor comments.

Jermolene · 2022-07-27T06:38:19Z

editions/tw5.com/tiddlers/concepts/WikiText.tid

@@ -1,15 +1,23 @@
 created: 20131205155227468
-modified: 20140919191220377
+list: [[Headings in WikiText]] [[Paragraphs in WikiText]] [[Hard Linebreaks in WikiText]] [[Formatting in WikiText]] [[Dashes in WikiText]] [[Block Quotes in WikiText]] [[Lists in WikiText]] [[Definitions in WikiText]] [[Tables in WikiText]] [[Code Blocks in WikiText]] [[Typed Blocks in WikiText]] [[Images in WikiText]] [[Horizontal Rules in WikiText]] [[Linking in WikiText]] [[Variables in WikiText]] [[Macro Definitions in WikiText]] [[Macro Calls in WikiText]] [[Macros in WikiText]] [[Transclusion in WikiText]] [[Transclusion and Substitution]] [[Styles and Classes in WikiText]] [[HTML in WikiText]] [[Widgets in WikiText]] [[WikiText Parser Modes]]


I'm not sure that we should rearrange these items. The disadvantage is that it makes it much harder to visually scan the list of children to look for a specific entry.

As a general rule, I think it's only advisable to have manual ordering for lists of less than about 7 items.

Jermolene · 2022-07-27T06:39:34Z

editions/tw5.com/tiddlers/concepts/WikiText.tid

 tags: Concepts Reference
 title: WikiText
 type: text/vnd.tiddlywiki

+\define openAll()


If this is a useful feature then it should be made universally available, and not just buried in one particular docs tiddler.

One of our key goals with the documentation is consistency. The value of consistency across the docs more than outweighs the advantages of a random, isolated improvement like this.

Jermolene · 2022-07-27T06:41:54Z

editions/tw5.com/tiddlers/concepts/WikiText.tid

 ~WikiText is a concise, expressive way of typing a wide range of text formatting, hypertext and interactive features. It allows you to focus on writing without a complex user interface getting in the way. It is designed to be familiar for users of [[MarkDown|http://daringfireball.net/projects/markdown/]], but with more of a focus on linking and the interactive features.

 ~WikiText can also be inserted to the text field using the [[Editor toolbar]].

-See [[Formatting text in TiddlyWiki]] for an introduction to WikiText.
+The following elements of WikiText syntax are built into the core. 


Do we use the phrase "elements of wikitext syntax" elsewhere in the docs? Again, we should try to be consistent with terminology.

We could say the "The following WikiText syntax rules are built into the core", but perhaps there is another collective noun/phraser that we already use.

Jermolene · 2022-07-27T06:43:34Z

editions/tw5.com/tiddlers/system/$__editions_tw5.com_wikitext-template.tid

+tags: $:/tags/ViewTemplate
+title: $:/editions/tw5.com/wikitext-template
+
+<$list filter="[all[current]tag[WikiText]]" variable="listItem">


Again this feels like a local, isolated fix to a universal issue. All we're doing here is providing a link back to one of the tags on the current tiddler. That's already possible using the tag pill. Randomly providing another means to do the same thing just makes it look like we don't trust the tagging mechanism as a means of user navigation.

From the feedback we get from new users. It isn't enough, to have "hidden information" behind the tag-pill. Because new users don't know about it.

If I search for "Formatting" in the sidebar search I may find: "Formatting in Wikitext" and open it. ... My expectation is, that I do get all the info. ... But the tiddler only contains one part of the info. ... That's why I think it makes sense to tell the users, that there is more.

That's all reasonable logic, but if it is true then it would actually be an argument for adding breadcrumbs to each docs tiddler, not for making a random isolated improvement for a single tag.

OK. What about a "tip" eg: <<.tip "The WikiText tag-pill at the top of the tiddler will show you all wikitext rules">>

eg: IMO It's a call to action to "use the tagging system" and if they click the link the effect is similar

Jermolene · 2022-07-27T06:44:24Z

editions/tw5.com/tiddlers/wikitext/Formatting in WikiText.tid

+  border: initial;
+  background-color: initial;
+}
+</style>


(a) the core never uses local style blocks, nor do we recommend their use

(b) why aren't these styles in one of the docs stylesheets?

b) Because I forgot to move them sorry.

Ha! No problem

pmario · 2022-07-27T08:18:07Z

Again this feels like a local, isolated fix to a universal issue. All we're doing here is providing a link back to one of the tags on the current tiddler. That's already possible using the tag pill. Randomly providing another means to do the same thing just makes it look like we don't trust the tagging mechanism as a means of user navigation

Yes. I think we should be allowed to ask that question, because it's "hidden information"

I think Roam and others clearly show, that users these days want visual clues about back/linking. We've had that feature for almost 20 years and they can make a hype out of an ancient feature?! ... Sure because nobody saw it in our wikis. It's still hidden.

I think TagglyTagging is still a thing and it should be easy to implement it. Not at the top of the tiddler, but the bottom. In the footer.

I think the docs should have a visible backlinks or / and keywords area in the footer of every tiddler. ... But that's way above the scope of this little PR.

Mehregan and Stroll are TW5 examples.
Mehregan:

Stroll

pmario · 2022-07-27T08:22:36Z

--- probably OT ---
If I click a tag in my wikis I do get this:

twMat · 2022-07-27T09:35:02Z

Tag pill ... hidden information ... Maybe tag pills could feature a small indicator?

pmario · 2022-07-27T10:24:41Z

Tag pill ... hidden information ... Maybe tag pills could feature a small indicator? image

This would be a core change.

I think you should open a different issue for that change. It's outside the scope for this PR, which only changes documentation related tiddlers.

pmario · 2022-07-27T10:34:54Z

This PR will be closed in favour of a new one

Wikitext docs overhaul first step

b39ce81

pmario mentioned this pull request Jul 26, 2022

[Overview] This issue tracks WikiText documentation changes #6829

Open

10 tasks

twMat reviewed Jul 26, 2022

View reviewed changes

Jermolene reviewed Jul 27, 2022

View reviewed changes

pmario closed this Jul 27, 2022

pmario deleted the wikitext-docs-overha-1658843101 branch July 28, 2022 17:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Wikitext docs overhaul first step #6828

Wikitext docs overhaul first step #6828

pmario commented Jul 26, 2022 •

edited

pmario commented Jul 26, 2022

twMat Jul 26, 2022

pmario Jul 27, 2022

twMat Jul 26, 2022 •

edited

pmario Jul 27, 2022

twMat commented Jul 26, 2022 •

edited

twMat commented Jul 26, 2022

pmario commented Jul 27, 2022 •

edited

Jermolene left a comment

Jermolene Jul 27, 2022

Jermolene Jul 27, 2022

Jermolene Jul 27, 2022

Jermolene Jul 27, 2022

pmario Jul 27, 2022

Jermolene Jul 27, 2022

pmario Jul 27, 2022

pmario Jul 27, 2022

Jermolene Jul 27, 2022

pmario Jul 27, 2022

Jermolene Jul 27, 2022

pmario commented Jul 27, 2022

pmario commented Jul 27, 2022 •

edited

twMat commented Jul 27, 2022

pmario commented Jul 27, 2022

pmario commented Jul 27, 2022

Wikitext docs overhaul first step #6828

Wikitext docs overhaul first step #6828

Conversation

pmario commented Jul 26, 2022 • edited

pmario commented Jul 26, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

twMat Jul 26, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

twMat commented Jul 26, 2022 • edited

twMat commented Jul 26, 2022

pmario commented Jul 27, 2022 • edited

Jermolene left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pmario commented Jul 27, 2022

pmario commented Jul 27, 2022 • edited

twMat commented Jul 27, 2022

pmario commented Jul 27, 2022

pmario commented Jul 27, 2022

pmario commented Jul 26, 2022 •

edited

twMat Jul 26, 2022 •

edited

twMat commented Jul 26, 2022 •

edited

pmario commented Jul 27, 2022 •

edited

pmario commented Jul 27, 2022 •

edited