Merge branch 'tiddlywiki-com'

2023-12-12 15:48:52 +00:00 · 2023-12-12 15:48:52 +00:00 · 0d2aeb8253
parent 9d94459c5d c9be572baf
commit 0d2aeb8253
13 changed files with 89 additions and 27 deletions
--- a/editions/tw5.com/tiddlers/concepts/Macros.tid
+++ b/editions/tw5.com/tiddlers/concepts/Macros.tid
@ -1,9 +1,15 @@
 created: 20140211171341271
-modified: 20230419103154328
+modified: 20230922094937115
 tags: Concepts Reference
 title: Macros
 type: text/vnd.tiddlywiki

+!! Important
+
+<<.from-version "5.3.0">> Macros have been [[superseded|Macro Pitfalls]] by [[Procedures]], [[Functions]] and [[Custom Widgets]] which together provide more robust and flexible ways to encapsulate and re-use code. 
+
+For text substitutions it is now recommended to use: [[Substituted Attribute Values]], [[substitute Operator]] and [[Transclusion and Substitution]]
+
 !! Introduction

 A <<.def macro>> is a named snippet of text. They are typically defined with the [[Pragma: \define]]:
@ -26,8 +32,6 @@ The parameters that are specified in the macro call are substituted for special
 *  `$parameter-name$` is replaced with the value of the named parameter
 * `$(variable-name)$` is replaced with the value of the named [[variable|Variables]]).

-<<.from-version "5.3.0">> Macros have been [[superseded|Macro Pitfalls]] by [[Procedures]], [[Custom Widgets]] and [[Functions]] which together provide more robust and flexible ways to encapsulate and re-use code. It is now recommended to only use macros when textual substitution is specifically required.
-
 !! How Macros Work

 Macros are implemented as a special kind of [[variable|Variables]]. The only thing that distinguishes them from ordinary variables is the way that the parameters are handled.
--- a/editions/tw5.com/tiddlers/concepts/Title
+++ b/editions/tw5.com/tiddlers/concepts/Title
@ -1,5 +1,5 @@
 created: 20150117152418000
-modified: 20220523075540462
+modified: 20231019155036098
 tags: Concepts
 title: Title List
 type: text/vnd.tiddlywiki
@ -15,3 +15,7 @@ Title lists are used in various places, including PermaLinks and the ListField.
 They are in fact the simplest case of a [[filter|Filters]], and are thus a way of expressing a [[selection of titles|Title Selection]].

 <<.warning """The [[Title List]] format cannot reliably represent items that contain certain specific character sequences such as `]] `. Thus it should not be used where there is a possibility of such sequences occurring.""">>
+
+See also:
+
+* The [[format Operator]] with the 'titlelist' suffix conditionally wraps double square brackets around a string if it contains whitespace
--- a/editions/tw5.com/tiddlers/filters/examples/jsonstringify
+++ b/editions/tw5.com/tiddlers/filters/examples/jsonstringify
@ -0,0 +1,11 @@
+created: 20230922121858167
+modified: 20230922122333325
+tags: [[Operator Examples]] [[jsonstringify Operator]]
+title: jsonstringify Operator (Examples)
+type: text/vnd.tiddlywiki
+
+Compare the encoding of quotes and control characters in the first example with the analogue [[example for the stringify operator|stringify Operator (Examples)]].
+<<.operator-example 1 """[[Backslash \, double quote ", single quote ', tab 	, line feed
+]] +[jsonstringify[]]""">>
+<<.operator-example 2 """[[Accents and emojis -> äñøßπ ⌛🎄🍪🍓 without suffix]] +[jsonstringify[]]""">>
+<<.operator-example 3 """[[Accents and emojis -> äñøßπ ⌛🎄🍪🍓 with rawunicode suffix]] +[jsonstringify:rawunicode[]]""">>
--- a/editions/tw5.com/tiddlers/filters/examples/stringify_Operator_(Examples).tid
+++ b/editions/tw5.com/tiddlers/filters/examples/stringify_Operator_(Examples).tid
@ -1,9 +1,11 @@
 created: 20161017154944352
-modified: 20230919124059118
+modified: 20230922122319674
 tags: [[Operator Examples]] [[stringify Operator]]
 title: stringify Operator (Examples)
 type: text/vnd.tiddlywiki

-<<.operator-example 1 """[[Title with "double quotes" and single ' and \backslash]] +[stringify[]]""">>
+Compare the encoding of quotes and control characters in the first example with the analogue [[example for the jsonstringify operator|jsonstringify Operator (Examples)]].
+<<.operator-example 1 """[[Backslash \, double quote ", single quote ', tab 	, line feed
+]] +[stringify[]]""">>
 <<.operator-example 2 """[[Accents and emojis -> äñøßπ ⌛🎄🍪🍓 without suffix]] +[stringify[]]""">>
 <<.operator-example 3 """[[Accents and emojis -> äñøßπ ⌛🎄🍪🍓 with rawunicode suffix]] +[stringify:rawunicode[]]""">>
--- a/editions/tw5.com/tiddlers/filters/jsonstringify
+++ b/editions/tw5.com/tiddlers/filters/jsonstringify
@ -1,12 +1,35 @@
 caption: jsonstringify
 created: 20171029155051467
 from-version: 5.1.14
-modified: 20230919124826880
+modified: 20230922121404577
+op-input: a [[selection of titles|Title Selection]]
+op-output: the input with JSON string encodings applied
 op-parameter: 
 op-parameter-name: 
-op-purpose: deprecated, use <<.olink stringify>> instead
+op-purpose: apply JSON string encoding to a string, see also the similar <<.olink stringify>>
+op-suffix: <<.from-version "5.1.23">> optionally, the keyword `rawunicode`
 op-suffix-name: R
 tags: [[Filter Operators]] [[String Operators]]
 title: jsonstringify Operator
 type: text/vnd.tiddlywiki

+The following substitutions are made:
+
+|!Character |!Replacement |!Condition |
+|`\` |`\\` |Always |
+|`"` |`\"` |Always |
+|Carriage return (0x0d) |`\r` |Always |
+|Line feed (0x0a) |`\n` |Always |
+|Backspace (0x08) |`\b` |Always |
+|Form field (0x0c) |`\f` |Always |
+|Tab (0x09) |`\t` |Always|
+|Characters from 0x00 to 0x1f, except listed above |`\u####` where #### is four hex digits |Always |
+|Characters from from 0x80 to 0xffff|`\u####` where #### is four hex digits |If `rawunicode` suffix is not present (default) |
+|Characters from 0x80 to 0xffff|<<.from-version "5.1.23">> Unchanged |If `rawunicode` suffix is present |
+
+<<.from-version "5.1.23">> If the suffix `rawunicode` is present, Unicode characters above 0x80 (such as ß, ä, ñ or 🎄) will be passed through unchanged. Without the suffix, they will be substituted with `\u` codes, which was the default behavior before 5.1.23. Characters outside the Basic Multilingual Plane, such as 🎄 and other emojis, will be encoded as a UTF-16 surrogate pair, i.e. with two `\u` sequences.
+
+<<.note """Mind the differences compared to <<.olink stringify>> in encoding of single quotes and control characters (0x00 to 0x1f).
+""">>
+
+<<.operator-examples "jsonstringify">>
--- a/editions/tw5.com/tiddlers/filters/stringify_Operator.tid
+++ b/editions/tw5.com/tiddlers/filters/stringify_Operator.tid
@ -1,12 +1,12 @@
 caption: stringify
 created: 20161017153038029
 from-version: 5.1.14
-modified: 20230919130847809
+modified: 20230922121406947
 op-input: a [[selection of titles|Title Selection]]
 op-output: the input with ~JavaScript string encodings applied
 op-parameter: 
 op-parameter-name: 
-op-purpose: apply ~JavaScript string encoding to a string
+op-purpose: apply ~JavaScript string encoding to a string, see also the similar <<.olink jsonstringify>>
 op-suffix: <<.from-version "5.1.23">> optionally, the keyword `rawunicode`
 op-suffix-name: R
 tags: [[Filter Operators]] [[String Operators]]
@ -18,19 +18,16 @@ The following substitutions are made:
 |!Character |!Replacement |!Condition |
 |`\` |`\\` |Always |
 |`"` |`\"` |Always |
-|Carriage return (0x0d) |`\r` |Always |
+|`'` |`\'` |Always |
 |Line feed (0x0a) |`\n` |Always |
-|Backspace (0x08) |`\b` |Always |
-|Form field (0x0c) |`\f` |Always |
-|Tab (0x09) |`\t` |Always |
-|Characters from 0x00 to 0x1f |`\x##` where ## is two hex digits |Always |
+|Carriage return (0x0d) |`\r` |Always |
+|Characters from 0x00 to 0x1f, except listed above |`\x##` where ## is two hex digits |Always |
 |Characters from 0x80 to 0xffff|`\u####` where #### is four hex digits |If `rawunicode` suffix is not present (default) |
 |Characters from 0x80 to 0xffff|<<.from-version "5.1.23">> Unchanged |If `rawunicode` suffix is present |

-<<.from-version "5.1.23">> If the suffix `rawunicode` is present, Unicode characters above 0x80 (such as ß, ä, ñ or 🎄) will be passed through unchanged. Without the suffix, they will be substituted with `\u` codes, which was the default behavior before 5.1.23.
+<<.from-version "5.1.23">> If the suffix `rawunicode` is present, Unicode characters above 0x80 (such as ß, ä, ñ or 🎄) will be passed through unchanged. Without the suffix, they will be substituted with `\u` codes, which was the default behavior before 5.1.23. Characters outside the Basic Multilingual Plane, such as 🎄 and other emojis, will be encoded as a UTF-16 surrogate pair, i.e. with two `\u` sequences.

-<<.note """Characters outside the Basic Multilingual Plane, such as 🎄 and other emojis, will be encoded as a UTF-16 surrogate pair, i.e. with two `\u` sequences.""">>
-
-<<.olink jsonstringify>> is considered deprecated, as it duplicates the functionality of <<.op stringify>>.
+<<.note """Mind the differences compared to <<.olink jsonstringify>> in encoding of single quotes and control characters (0x00 to 0x1f).
+""">>

 <<.operator-examples "stringify">>
--- a/editions/tw5.com/tiddlers/hellothere/HelloThere.tid
+++ b/editions/tw5.com/tiddlers/hellothere/HelloThere.tid
@ -20,7 +20,7 @@ TiddlyWiki lets you choose where to keep your data, guaranteeing that in the dec
 </div>
 <div class="tc-cards tc-small">
 <$link to="中文社区 - Chinese Community" class="tc-btn-big-green tc-card">
-中文社区 - Chinese Community
+中文社区<br/>Chinese Community
 </$link>
 </div>

--- a/editions/tw5.com/tiddlers/howtos/Constructing
+++ b/editions/tw5.com/tiddlers/howtos/Constructing
@ -1,5 +1,5 @@
 created: 20220427174702859
-modified: 20230809113620964
+modified: 20230922122551197
 tags: [[JSON in TiddlyWiki]] Learning
 title: Constructing JSON tiddlers

@ -13,4 +13,4 @@ At a high level, we have several ways to generate JSON data in TiddlyWiki's own
 * [[jsontiddler Macro]]
 * [[jsontiddlers Macro]]

-When constructing JSON data manually, the [[stringify Operator]] is needed to ensure that any special characters are properly escaped.
+When constructing JSON data manually, the [[jsonstringify Operator]] is needed to ensure that any special characters are properly escaped.
--- a/editions/tw5.com/tiddlers/macros/CoreMacros.tid
+++ b/editions/tw5.com/tiddlers/macros/CoreMacros.tid
@ -5,4 +5,4 @@ type: text/vnd.tiddlywiki

 The following [[macros|Macros]] are built into ~TiddlyWiki's core:

-<<list-links "[tag[Core Macros]]">>
+<<list-links "[tag[Core Macros]]" class:"multi-columns">>
--- a/editions/tw5.com/tiddlers/system/tw5.com-styles.tid
+++ b/editions/tw5.com/tiddlers/system/tw5.com-styles.tid
@ -148,6 +148,7 @@ type: text/vnd.tiddlywiki
 }

 .tc-cards.tc-small {
+	text-align: center;
 	font-size: 0.7em;
 }

--- a/editions/tw5.com/tiddlers/widgets/SetWidget.tid
+++ b/editions/tw5.com/tiddlers/widgets/SetWidget.tid
@ -1,6 +1,6 @@
 caption: set
 created: 20131115182700000
-modified: 20220523075522407
+modified: 20230720174707977
 tags: Widgets
 title: SetWidget
 type: text/vnd.tiddlywiki
@ -120,3 +120,19 @@ src='<$set name="myTiddler" value="HelloThere">
 </$set>'/>

 <<<
+
+!! Using the Set Widget to Create Global Variables
+
+There are times when it makes sense to use the features of the [[SetWidget]] rather than procedures or functions to create global variables.  This can be accomplished by placing the set variable widget in a tiddler that is tagged [[$:/tags/Global|SystemTag: $:/tags/Global]].  If multiple variables are required, the set variable widget can be nested as shown here:
+
+<<<
+<div class="doc-example">
+
+```
+<$set name="myGlobalVariable" value="I am global">
+    <$set name="myOtherGlobalVariable" value="I am also a global variable.">
+    </$set>
+</$set>
+```
+</div>
+<<<
--- a/editions/tw5.com/tiddlers/wikitext/Transclusion
+++ b/editions/tw5.com/tiddlers/wikitext/Transclusion
@ -1,5 +1,5 @@
 created: 20141018090608643
-modified: 20230419103154329
+modified: 20231030124224424
 tags: WikiText
 title: Transclusion and Substitution
 type: text/vnd.tiddlywiki
@ -55,6 +55,6 @@ As described in [[Introduction to filter notation]], you can also transclude a v

 ! Textual Substitution

-Textual substitution occurs when the value of a macro/variable is used. It is described in [[Macros]].
+Textual substitution occurs when the value of a macro/variable is used. It is described in [[Substituted Attribute Values]] and [[substitute Operator]]

-The key difference between substitution and transclusion is that substitution occurs before WikiText parsing. This means that you can use substitution to build WikiText constructions. Transclusions are processed independently, and cannot be combined with adjacent text to define WikiText constructions.
+The key difference between substitution and transclusion is that substitution occurs before WikiText parsing. This means that you can use substitution to build ~WikiText constructions. Transclusions are processed independently, and cannot be combined with adjacent text to define ~WikiText constructions.
--- a/licenses/cla-individual.md
+++ b/licenses/cla-individual.md
@ -553,3 +553,7 @@ BuckarooBanzay, @BuckarooBanzay, 2023/09/01
 Timur, @T1mL3arn, 2023/10/04

 Wang Ke, @Gk0Wk, 2023/10/17
+
+@frittro, 2023/10/27
+
+@etardiff, 2023/12/10