[Docs] SMW mechanics and Property:Page_Title / Template:Summary_Table_Body

(Warning: Contains severe technical stuff! Aside from reporting a bug/fix it's also meant for people who want to get a better understanding of SMW etc.)

TL;DR: Some Page type properties should possibly be changed to a String type or improper values have to be taken care of in the query outputs.
TL;DR: We should also define what proper values for custom page title (and possibly other properties) are for pages that are listed in
TL;DR: APIs / elements tables and such (like html/elements [1]). Maybe add that to the style manual [3].

I spent some time (ca. 1am to 3am here, was helping SF doc sprint people anyway, so why sleep!) to check out some more internal mechanisms of the semantic plugins and our setup and 
to get a better understanding of things.

jaacob on IRC reported that some links showed the full article name (html/elements/abbr) instead of just the last part (abbr) in the elements table [1]. It was suspected that the 
custom page title was involved. I dug deep and indeed it was.

Some examples of the relevant part of the table (the API Name column, which could be renamed on a per use basis, I guess) looked like this:
- a
- html/elements/abbr
- Canvas

The links were fine (linking to html/elements/...), but the text was odd.

So why did those 3 elements look so different? Well, let's take a look at the value of the Page_Title property for each one:
- html/elements/a: (nothing)
- html/elements/abbr: "The <abbr> element"
- html/elements/canvas: "Canvas"

To understand how the links are produced, we have to take a look at some templates. :) The table is generated like this:
{{API_Listing
|Query=[[Category:Markup_Elements]][[Category:HTML]]
|Use_page_title=No
|List_all_subpages=No
}}

Template:API_Listing [a] uses SMW's #ask parser function to produce tabular output. Because of the 'template' parameter, Template:Summary_Table_Body [b] is called for every row. It 
gets passed 3 parameters:
{{{1}}} = the page that was found (default first parameter of a semantic query output)
{{{2}}} = value of the Page_Title property (because of ?Page_Title in [a])
{{{3}}} = value of the Summary property (because of ?Summary in [a])

A page gets its Page_Title property defined like this (raw source, in the form it's the "Custom page title" field at the top):
{{Page_Title|The <abbr> element}}

Template:Page_Title [c] just checks if a custom title was entered, if so it uses that as the value for the property, if not it uses the last part of the page name (via 
#titleparts). Nothing wrong with this template.

The problem is that Property:Page_Title is of type "Page" (the default type). That means SMW treats this property as a reference to another article and assumes the value is a valid 
page name. But because "The <abbr> element" is hardly a valid page name, SMW flags it as an improper value. Btw, to find all pages with an improper Page_Title property value, 
check out [2] (11 atm). (could also be worth it to check all the improper values via [4], I'll take a look at what the issues are later)

So what happens is (when there's an improper value for the Page_Title property) Template:Summary_Table_Body [b] gets passed nothing for its {{{2}}} parameter (Page_Title), thus the 
#if there won't provide a custom text for the link and hence the full page name is displayed as the link.

To fix that I used #titleparts in the else block, as a fallback value if the Page_Title property is passed empty (see [d]), so the last part of the page name is provided as the 
link text. I hope this looks okay in every place where such tables are used, it could break in cases where the full name is needed because of duplicate trailing name parts. It 
worked for html/elements [1], so the former mentioned examples now show as:
- a
- abbr
- Canvas

"Canvas", of course, shows because a valid value (namely "Canvas") was provided for the custom page title, although its practicability is doubtful (see TL;DR).

Sorry for the long post, I hope no one's brain exploded. ;)


[1] http://docs.webplatform.org/wiki/html/elements#Summary
[2] http://docs.webplatform.org/wiki/Special:SearchByProperty/Has_improper_value_for/Page_Title
[3] http://docs.webplatform.org/wiki/WPD:Manual_Of_Style#Article_titles
[4] http://docs.webplatform.org/wiki/Property:Has_improper_value_for

(code formatted for legibility)

[a] Template:API_Listing
{{#if:
   {{{Query|}}}
   |
     {{#ask:
       {{{Query|}}}
       |?Page_Title
       |?Summary
       |link=none
       |format=template
       |template=Summary_Table_Body
       |introtemplate=Summary_Table_Header
       |outrotemplate=Summary_Table_Footer
       |searchlabel=See more pages...
     }}
   |
}}
{{#ifeq:
   {{{List_all_subpages|}}}
   |
     Yes
   |
     ==Subpages==
     {{Special:PrefixIndex/{{PAGENAME}}/}}
   |
}}
[[
   Category:API_Listings
   |
     {{#titleparts:
       {{PAGENAME}}||-1
     }}
]]


[b] Template:Summary_Table_Body
| [[
   {{{1}}}
   {{#if:
       {{{2|}}}
       |
         {{!}}{{{2|}}}
       |
   }}
]]
|| {{{3}}}
|-


[c] Template:Page_Title
{{#if:
   {{{1|}}}
   |
     ={{{1|}}}
       {{#set:
         Page_Title={{{1|}}}
       }}=
   |
     ={{#titleparts:
       {{PAGENAME}}||-1
     }}=
     {{#set:
       Page_Title={{#titleparts:
         {{PAGENAME}}||-1
       }}
     }}
}}
{{#set:
   Path={{PAGENAME}}
}}


[d] Template:Summary_Table_Body (new)
| [[
   {{{1}}}
   {{#if:
       {{{2|}}}
       |
         {{!}}{{{2|}}}
       |
         {{!}}{{#titleparts:
           {{{1}}}||-1
         }}
   }}
]]
|| {{{3}}}
|-