Semanticmediawiki: Deprecate [[property::value]] input syntax

[JeroenDeDauw]

In favour of #set. To be removed in some future major release.

[s7eph4n]

SMW 3.0 on the horizon :)

[mwjames]

@mkroetzsch @JeroenDeDauw I saw the email but before making any decision, I'd like to hear the feedback from the community whether this can be scrapped or not.

[mwjames]

SMW 3.0 on the horizon :)

That requires more code clean-up ;-)

[JeroenDeDauw]

Yeah, should definitely send a mail to the user list.

[mkroetzsch]

Given the amount of wikis relying on this, we will need to provide a long transition phase. The first step would probably be to update the docs so as to not teach new users that this is the main thing to use.

[jamesmontalvo3]

Can you point me to the rationale for this change?

On Thu, Oct 23, 2014 at 3:01 AM, Markus Krötzsch [email protected]
wrote:

Given the amount of wikis relying on this, we will need to provide a long
transition phase. The first step would probably be to update the docs so as
to not teach new users that this is the main thing to use.

—
Reply to this email directly or view it on GitHub
https://github.com/SemanticMediaWiki/SemanticMediaWiki/issues/584#issuecomment-60204925
.

[mkroetzsch]

The rationale would be to simplify and unify the syntax. The use of [[ ]] comes from a time when MediaWiki had a far more confused parsing process and this was as good as anything. Also, the choice of syntax was motivated by the fact that early SMW only supported type Wikipage (so link syntax made sense).

Today, however, MediaWiki has a much cleaner parser function support. Almost every extension uses parser functions (written as {{#function:...}}) and some special cases use tags (written as <tag>...</tag>). SMW's special choice of syntax is not compatible with this. A particular case where this leads to problems is when you want to insert links into property values, which is disabled by default because it requires a much more complex (and inefficient) parsing process.

Another reason why #set should be favoured over [[ :: ]] is that the latter convolutes presentation with data: the use of [[ :: ]] normally produces some output on the page (which also depends on your language setting and other things). The better technique to create pretty (and fully customized) outputs is to use templates and parser functions in MW. For example, the widely available parser function #time can format times for you in many ways. Mixing presentation with data storage leads to hard-to-maintain wiki page code that has two complex tasks in one.

Also, you can often see templates using [[property::value| ]] (set the value but don't show any output). IMHO this is an anti-pattern today. My templates start with code like

{{#set:
| property1={{{param1|}}}
| property2={{{param2|}}}
| property3={{{param3|}}}
}}

This sets the properties to the given parameter values, _but only if the parameters are set_, without using any #ifeq or other stuff, and it completely keeps the data storage out of the layout. On the rest of the page, I just format data as I like, using no SMW functions in the mix.

Summary: [[ :: ]] should be avoided since it convolutes two complex tasks, data storage and presentation, into one, using a non-standard syntax that is not self-explaining to new users who see it the first time.

[vid]

I have to wonder who these users that are being targeted are. When I introduce people to wikis, MediaWiki then Semantic Mediawiki the [[property::value]] syntax is part of a very natural progression and easy to explain, particular in relation to the triple idea . Anyone who can create a link or category in a wiki can use this style and some wikis are full of this kind of annotation, and with #ask: and property browsing it's a useful combination for basic text annotating. So the main problem to me is a very large gap between a programmer and non programmer contributor.

I do certainly agree most sites are better off focusing on templates. However while in neither case is validation / consistency being comprehensively addressed, heavy use of templates makes some access (reading and writing) of semantic data even more difficult since this form can only be processed by the [S]MW specific low level parser, making use of third party tools (which I at least use quite a lot) more difficult.

[mkroetzsch]

To clarify: we are not talking about removing the option here. I have many wikis that are full of this syntax and they won't go away. The idea is to explain to new users that this is not the preferred way of doing it since it is less clean, both technically and conceptually.

On another note, it is really interesting that you are using SMW in text annotation. While we had this idea at some point, I have hardly seen any wiki doing this. Most sites now seem to prefer templates (and forms).

Finally, as you probably know, writing your own (S)MW parser is bound to be fragile. It would be preferable to reuse the MW parser in some way if you can.

[jamesmontalvo3]

@mkroetzsch thanks for the explanation. That all makes sense, and I like
your method of using set at the top of templates.

On Thu, Oct 23, 2014 at 10:22 AM, Markus Krötzsch [email protected]
wrote:

To clarify: we are not talking about removing the option here. I have many
wikis that are full of this syntax and they won't go away. The idea is to
explain to new users that this is not the preferred way of doing it since
it is less clean, both technically and conceptually.

On another note, it is really interesting that you are using SMW in text
annotation. While we had this idea at some point, I have hardly seen any
wiki doing this. Most sites now seem to prefer templates (and forms).

Finally, as you probably know, writing your own (S)MW parser is bound to
be fragile. It would be preferable to reuse the MW parser in some way if
you can.

—
Reply to this email directly or view it on GitHub
https://github.com/SemanticMediaWiki/SemanticMediaWiki/issues/584#issuecomment-60255919
.

[mwjames]

Technical perspective

From a technical perspective, the in-text annotation parsing (together with its storage) is confined to two places (InTextAnnotationParser [0] and InternalParseBeforeLinks [1]) making the technical implication less an issue and the maintenance of those two classes a bit simpler (also both have a rather high test coverage). Further, [0] handles the detection of redirect links and magic words such as __SHOWFACTBOX__.

Social perspective

Creating in-text annotations is a social process born from the "wiki" itself by the notion of "you can edit it yourself" starting with simple categorization such as Category:IDon'tWhatI'mDoing and extended by SMW to allow to make statement like annotations in form of [[property::value]].

While I can agree that using [[property::value]] (together with its special parser InTextAnnotationParser) has a weakness (in value link annotation [2]) it nevertheless is part of the feature that SMW provides to its users which are not always see that the template approach (where #set as hidden annotation parser maybe be a more appropriate to use) is the best tool at hand to solve their use case.

I still believe that in-text annotation should be an integral part of SMW (maybe I'm the only user by doing in-text glossary annotations (SemanticGlossary) or referencing to a cite [[Cite::Foo, 3015]] (SemanticCite) entry) as it allows to use text free from any template formalism.

[0] https://scrutinizer-ci.com/g/SemanticMediaWiki/SemanticMediaWiki/code-structure/master/class/SMW%5CInTextAnnotationParser

[1] https://scrutinizer-ci.com/g/SemanticMediaWiki/SemanticMediaWiki/code-structure/master/class/SMW%5CMediaWiki%5CHooks%5CInternalParseBeforeLinks

[2] https://semantic-mediawiki.org/wiki/Help:$smwgLinksInValues

[JeroenDeDauw]

To clarify: we are not talking about removing the option here.

Actually that is what I created this issue about, since this is what was in my understanding being suggested by email.

Technical perspective

Thanks for outlining that. I'm now +1 to keeping it

[kghbln]

Deprecating a certain method of annotating things makes only sense when providing an alternative to [[property::value]] at the same time. Since in-text annotation should still imho be part of SMW (+1 for keeping) an additional parser function will have to be provided allowing to do this, perhaps something like {{#add:property=value}}. The name should be short like add though. I do not think that extending the "set" parser function to annotate visibly is preferable since it would require even more to type.

[mkroetzsch]

If there are still active uses, I am also +1 for keeping it. The idea of removing it came from an email discussion where it was argued that too many input options are confusing for users. If we think that this is not so, then there is hardly any reason to change things here.

[jamesmontalvo3]

It sounds like the plan to deprecate has been abandoned, but I had a couple other thoughts that I felt were good to record somewhere:

1. The ask syntax, {{#ask: [[Property::Value]] ... }}, would be far less intuitive if you removed the value setting/displaying syntax [[Property::Value]].
2. Unless there is a feature I'm not aware of (I'm sure there are many, actually), use of {{#set: Property = Value }} is not as powerful as doing [[Property::Value]] when you want to do unit conversion. In other words, if I define Property:Mass as the following:

[[Has type::quantity]] [[Corresponds to::1 lbm]] [[Corresponds to::0.45359237 kg]]

When I do [[Mass::2.2]] in a page I get a nice interface that shows unit conversions on mouseover. Is there any way to replicate this without [[Property::Value]]?

[mkroetzsch]

1. Yes, agreed.
2. It's true that you don't get the special displaying features from #set (tooltips, conversions, internationalisation, ...). However, there I would argue that it would be nicer to separate the two. Why should somebody who wants to display a conversion tooltip for a measurement be forced to store this value in SMW? Also, if you want to display a value in several places (in some template etc.), you would need to annotate it multiple times, which is not great style (harder to maintain: might change one annotation while forgetting the other).

I would prefer if we would have functions to make nice displays (like MediaWiki's #time) separated from our annotation syntax. For example, considering how many parameters displaying functions could take to control the details of the appearance, I would say that it is not a good idea to add all of these parameters to SMW. In fact, #ask printouts ("?property") already offer you more parameters to control the output, and it seems somewhat incoherent to consider [[property::value]] as a data display feature when providing only part of the options (no parameters, no styling).

[ankostis]

(sorry for reviving this, but i think it is not yet put to rest)

@mkroetzsch wrote:

... so, if you want to display a value in several places (in some template etc.), you would need to annotate it multiple times, which is not great style ...

What about capturing the output of #set (or the hypothetical #add) into a #vardefine from the _Variables_ extension?

If the #var trick is acceptable, then the (2) case above still needs to be addressed somehow.
I mean, to avoid the limitations of inline-annotations and still being able to properly format the DataValue (e.g. with unit-conversions).
Another consideration is the performance hit when putting too many #show/#ask parser-functions in page just to auto-format the DVs.

To recapitulate:

• [[inline::annotation]]:
  
  
  
  • storage:
  
  
  • yes
  
  
  • presentation:
  
  
  • :heavy_check_mark: auto formatted values (e.g units),
  
  
  • :x: not customizeable,
  
  
  • :heavy_check_mark: cheap (not like #ask/#show),
  
  
  • reuse output:
  
  
  • :x: MUST NOT repeat (even with #vardefine)
  
  
• #set annotation:
  
  
  
  • storage:
  
  
  • yes
  
  
  • formatting:
  
  
  • no output OR
  
  
  • :heavy_check_mark: passed to a user-defined template
  
  
  • :x: unformatted value (so still impossible to get _units_ without expensive #show),
  
  
  • :heavy_check_mark: cheap,
  
  
  • reuse output:
  
  
  • intuitively not repeatable but
  
  
  • :heavy_check_mark: possible to reuse output with _Extension:Variables_.
  
  
• #ask/#show DVs:
  
  
  
  • storage:
  
  
  • no
  
  
  • formatting:
  
  
  • auto formatted
  
  
  • fully customizable
  
  
  • :x: expensive
  
  
  • reuse output:
  
  
  • :heavy_check_mark: fully
  
  

I think we're missing the middle ground, something that behaves like #set but with auto-formatting DVs, and that can be captured in a #var and copied around.
Something like the #add suggested by @kdbln, or maybe to pass one more parameter to the #set's template parameter, e.g. one named {{{fvalue}}} with the autoformatted DV?

Would that worth a new RFE-issue?

[mwjames]

@kghbln Why was this pinned? What is the expected outcome?

[kghbln]

Why was this pinned? What is the expected outcome?

My expected outcome was that I do not want to forget this. I did not know that this is a public thing. I just wanted to pin this for myself.