There is a bug in cargo that busted the name list functionality for items, resulting in wrong/random items being returned for {{Il}} (item links).

For the time being, item links will use the exact item name for searching. This will result in some older instances of item links no longer working, in particular when legacy names are used (e.x. Pierce instead of Pierce Support).

Item links still showing incorrect items should be fixable by null-editing, while errors (red text) relating to the items not being found can be fixed manually by changing the parameter to the full name (see the template for details).

Path of Exile Wiki:Semantic Mediawiki rework

From Path of Exile Wiki
Jump to: navigation, search

Overview

With the addition of Semantic Mediawiki, the Path of Exile wiki gained the ability to dynamically populate pages and link text from pages into a database.

This gives us two major advantages:

  • removal of content duplication
  • information will only be required to be updated once per page

The purpose of this page is to coordinate the effort; to discuss specific changes, use the talk page.

Methodology

Data sources

For the purposes for the rework, a data source is a single page where the properties are set. A page can be both, a data source and a output page.

Finding suitable (groups of) pages pages

Suitable pages are pages that can potentially expose information that would be useful to query. Entire groups of pages where similar information is presented based on the page it self are optimal; for example this is the case for item pages or skill pages.

Identifying the properties to use

Once the page (or group of) has been identified, the next step is to identify suitable properties on the page. Referencing the information in the game files (many of the groups have a respective binary .dat file) may be helpful to identify such properties, but however it should kept in mind that not all information is needed in the wiki.

Finally it's also important to agree on properties beforehand, if a template is changed to change the name of a properties, it might take several hours for the change to go though.

Also make sure to declare properties, i.e. to create a page with name of the property and in the Property name space (e.g. Property:Has name). While declaring properties, also make to use a proper datatype and briefly describe what the property is for.

Naming of properties

For reference, the guidelines from the Manual of Style:


Properties should follow these rules in order to have a consistent naming scheme throughout the wiki.

Names should be short, meaningful and avoid ambiguity

This should be the case so what the property means can be identified by reading the name on sight. It should also avoid clashes with other properties.

Good:

[[Is forsaken master::Vorici]]

Bad:

[[Is:Vorici]]

Names should start with a verb

This should be done to avoid confusion about what the property actually does.

Good:

On page "Cobalt Jewel"
[[Is base item::Cobalt Jewel]]

On page "Army of Bones"
[[Has base item::Cobalt Jewel]]

Bad:

On page "Cobalt Jewel"
[[base item::Cobalt Jewel]]

On page "Army of Bones"
[[base item::Cobalt Jewel]]


Use "Is ..." for setting a single piece of information that can be used to identify the page based on the property; in particular this should be set on every page of the same "type".

See example above.


Use "Has ... " for setting additional information about the page.

Properties for multiple values should be plural; singular otherwise

The intention is to help people to tell what to expect when they are perform an ask query on a page. So properties that are intended to have multiple values (and commonly do so), should be in plural while others that have a single value associated with them should be in singular.

This rule is not strict. The use of plural naming should be considered for case there can be multiple values.

Good:

On a skill page
[[Has gem tags::Fire]]
[[Has gem tags::Cold]]
[[Has gem tags::Spell]]

Bad:

On a skill page
[[Has gem tag::Fire]]
[[Has gem tag::Cold]]
[[Has gem tag::Spell]]

Absence should be indicated by a "no"

Since it is not possible to query for the absence of properties, sometimes properties for the absence of other properties have to be created. In these cases they should be indicated by a no in their name, like so:

[[Has no ...]]

Additionally they should have Has type::Boolean set.

For example:

Property:Has item class restrictions indicates a list of restrictions

Property:Has no item class restrictions indicates the absence of said list


Creating or reworking lua modules & templates

Once the properties have been identified, the next step is to create appropriate lua modules and templates. Most of the handling should be done in lua, since it's much more flexible and readable then wikipedia templates.

The lua module should be included from a template which can add extra information or fill in some of the variables (for example, a "Skill" template might fill in "type=skill" automatically). Additional reason for the inclusion though a template is that the underlying module (and/or function) can be changed at any time allowing for more flexibility.

Inside the lua module, the variables should be verified before being added as property and raise an error if inappropriately used Template:Discussion.

Updating all the pages with the source information

In the last step, if the changes also require the source pages to be changed, each of these should be updated to use the new template (and missing information should be added accordingly).

It may be helpful to add a management category (i.e. something like [[Category:Non-semantic skill pages]]) to the template used for old pages, so they can be found and identified more easily.

Data output

For the purposes for the rework, a page contains data output if the data is accessed though semantic search A page can be both, a data source and a output page.

Generally it's advisable to update the source pages first or leave out semantic queries until the source pages are done. Obviously you can't query what doesn't exist, which might make it hard to identify issues with the queries themselves. In particular if the queries are not done yet this poses an issue.

Finding pages that list source pages or otherwise use them

The first step is to identify pages that use the information.

Pages to look for (easiest to hardest):

  • item lists (usually named List of xxx)
  • nav boxes (usually reside in the Template namespace and are named Template:Navbox xxx)
  • pages that list parts of other pages, but do not have it in their name (e.x. league specific items, overviews of the classes, etc.)
  • pages that only use a single property (e.x. "the game has 412 uniques", not on page "Scion" "scion starts with a base health of x")

Query source pages

Once the pages have been found, they should be updated with the queries.

Some things to consider and watch out for:

  • the default limit of queries is 50 (increase it as necessary or divide into sub queries).
  • the order may random or not what you expect. In general it may be sensible to order by the name (in particular if it has a name property)
  • sometimes you may need subqueries to filter out nested information (in particular for subobjects) which will require templates
  • table and list output formats are useful for most pages
  • for highly customized formatting, use the template format (and see the section below)

Create output templates

As mentioned above, some pages will require custom templates to output the information properly.

Create those templates with the prefix SMW and use


Pages that need reworking

We should try to prioritize the pages, i.e. what is accessed the most and what could benefit the most. List pages or groups here.

Mods

priority: very high completion:

  • templates: 100%
  • data exporter: 100%

Items

priority: medium

Skills

skills are a subset of items

priority: high

Masters

priority: low

Overview of progress

Estimated overview of progress.

Project Completion
Semantic Templates PyPoE Exporter Data source pages Output / formatting templates Lists/interlinked pages
Mods 100% 90% 100% 30% 10%
Items 70% 0% 0% 0% 0%
Items 100% 100% 100% 30% 20%
Masters
Areas
Quests
Monsters

Known Issues with SMW

Query depth

There is a limit on how large and complex SMW queries can be; you can use format=debug to get an idea what is happening with the query.

Some ways to solve this problem:

  • reduce the number of conditions in the query
  • reduce the number of subqueries (i.e. <q></q>
  • summarize common conditions into a concept
  • use a lua module for further iteration purposes

Redirect pages may cause issues with properties

Can occur due to:

  • moving pages (with properties) and leaving a redirect
  • editing redirect pages
  • deleting pages that contain redirects

Solution (steps):

  1. validate the properties on the real page are set as they should
    1. if missing or incorrect properties are present, null-edit the page
    2. if this is still the case, do a minor edit on the page such as adding a space

Text search not working properly

Causes and solutions

  1. Text after 40th character is not searched
    • Try limiting your search to the first portion of the text
    • Use other means of searching (i.e. other properties)
    • When working on template make sure the characters intended for search are not too long
    • SMW queries can support Full-text searches but this site does not have all the requirements for it.
  2. Text may include HTML/wikitext
    • In case of wiki links screwing search up consider searching for words only, e.x. ~Life*Leech

Properties or values were changed in a template but they don't show up in the properties

Such changes generally take a while (up to several hours) to go though, esp. on templates that are used in many places.

Solutions:

  • Just wait it out (preferred)
  • perform null-edits (edit with no changes) on all pages using the template