Editing Module:Format TemplateData/doc (section)

== {{Anker|improveMW}} Improve template documentation page – MediaWiki disappointing ==
For presentation of template depiction in VisualEditor agreement was made to abandon all markup and clickable links, permitting all tooltips in all environments. Basically this is reasonable, albeit tooltips with markup and clickable links are supported as HTML application for decades now and JavaScript is present anyway when VisualEditor is used.
* In consequence it was decided, that also presentation on template documentation views never ever is permitted to contain effective links or markup.
* That involved, that on many template documentation pages two separated parameter documentation tables are needed and required to be maintained simultaneously: One plain text version for VisualEditor, and a useful one for complex circumstances, with links and markup and lists and tables. – BTW, VisualEditor has not only tooltips, but also a static GUI view, where the lack of deepening links in parameter description is painful.  
This state is indefensible.

=== {{Anker|enhancedJSON}} Improved presentation ===
In addition to the simple syntax supported by MediaWiki and presented in the VisualEditor, the following features can be added to the JSON code for the template documentation page. They affect the elements classified as ''InterfaceText'', but are only useful for description fields.

'''Wikilinks''' (internal format)
* Using double square brackets pages can be linked as common.
* In VisualEditor, only link title is visible, as it is displayed otherwise.

'''External links''' ([[Uniform Resource Locator|URL]] format)
* Open URL are linked as usual by themselves. In VisualEditor they appear as normal text.
* External links enclosed in simple square brackets are displayed normally on the template documentation page. In VisualEditor the title is omitted and the URL is displayed so that the users can c&p it and transfer it to the address field of the browser. There is no other way.

'''Apostrophs''' <code>'</code> for italic and bold
* They can be used to emphasize on the documentation page and are missing in VisualEditor (regular script).

'''HTML entities'''
* The following entities can be used: <code style="white-space: nowrap">&amp;lt; &amp;gt; &amp;amp; &amp;quot; &amp;nbsp;</code> and all numeric formats.

'''HTML tags'''
* HTML tags (and the MediaWiki elements that are not replaced in advance) are removed for the VisualEditor. Otherwise, they remain effective.
* Attributes are often included in <code>"</code>, which conflicts with the JSON syntax. It is important to make sure that <code>'</code> is used, which can be a problem with template transclusions.

<code>&lt;noexport></code> … <code>&lt;/noexport></code>
* The enclosed areas are not exported to the VisualEditor.
* More complex wiki syntax and extensive explanations can be restricted to the documentation page.
* Within a ''noexport'' area, the line structure of the source text is considered. Otherwise everything is running in a single line, as it would also be represented in the VisualEditor.

'''Templates'''
* In particular when the template parameter <code>JSON=</code> is used, templates can be distributed anywhere in the JSON code. However, the expanded syntax might collide with the JSON syntax.

'''More effects'''
* According to the state (required, suggested, optional, deprecated) the table rows are highlighted in light blue, white, gray and pale red.
* When sorting by state, this importance is taken into account and not the alphabetical sequence of the keywords.
* Each parameter can be addressed as a jump destination. The fragment is <code>#templatedata:</code>''parameter-name''.
* Missing labels are highlighted as errors.
* A maintenance category is triggered if errors occur.
* If there are no parameters, the element <code>params:{}</code> is not required.

=== Eliminate disadvantages ===
Two aspects were found to be particularly disturbing in 2013–2017:
# Even if no parameters at all were defined, a table head is always displayed for a table without content. Even more, this is sortable.
#* A reduction was rejected with {{Phab|Task=126150}}. A sortable table of the parameters would be always necessary, even if the table has no rows at all and consists only of the header row.
#* This ridiculous statement led to the development of this module in 2016.
# Even if the context does not permit that default values or even AutoValue specifications will be defined ever, a content-free six-line definition list is output for each individual parameter value.
#* {{Phab|Task=T125333}} / {{Phab|Task=T137443}} / {{Phab|Task=T160254}}  / {{Phab|Task=T52512}}<section end="JSONenhanced" />
#* MediaWiki did not even deign to answer the disastrous documentation page situation.
The general comments show that MediaWiki only regards the presentation of TemplateData specifications in the VisualEditor as important. However, someone has to program and maintain the templates and someone needs to generate the template description and make it manageable beside the functionality in the VisualEditor form, but that is beyond ken.
* Two years later the relatively easy task {{Phab|Task=T125333}} has been solved by a community originated patch.