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

On Sun, Nov 4, 2012 at 8:14 AM, frozenice <frozenice@frozenice.de> wrote:

> (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.)
>

Fun!

>
> 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.
>

Before I read further, let me quickly say that IIRC the reason this happens
is for pages that don't yet have Page_Title or API_Name set. In many cases,
this is simply articles that were imported from MSDN but were never
"touched".

>
> 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 &lt;abbr&gt; 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 &lt;abbr&gt; element}}
>

Ah, that goes against the convention I was assuming for reference page
titles when I wrote that template.

>
> 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).


Whoops! I should have explicitly set that to a 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 &lt;abbr&gt;
> 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. ;)
>

On the contrary, thanks so much for digging into the muck that is our
template set-up. I hope that over time you can grow your understanding so
there can be at least two of us who are in a position to debug/improve it.
I'm going to talk about this general need tomorrow in the call.

>
>
> [1] http://docs.webplatform.org/**wiki/html/elements#Summary<http://docs.webplatform.org/wiki/html/elements#Summary>
> [2] http://docs.webplatform.org/**wiki/Special:SearchByProperty/**
> Has_improper_value_for/Page_**Title<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<http://docs.webplatform.org/wiki/WPD:Manual_Of_Style#Article_titles>
> [4] http://docs.webplatform.org/**wiki/Property:Has_improper_**value_for<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}}}
> |-
>
>