Warning:
This wiki has been archived and is now read-only.

Publishing Incubator Group Documents

From Semantic Sensor Network Incubator Group
Jump to: navigation, search

XGRs

The W3C advice o how to publish XG reports is available from:

Images

Note: use "view source" to read the correct HTML code

  • Add a px parameter to specify the size of the image,
  • Add a center parameter,
  • Add a short description using the alt parameter (WCAG2)
  • Add a name for the figure
  • Do not use the thumb MediaWiki attribute for images as this will lead to many more MediaWiki-caused errors.


Example:
Figure used during the July 20 discussion leading to the decision to align the SSN ontology with DUL

Note: the report originally used thumbnail to make apparent the image title (making it easier for the reader to link the images to the text). MediaWiki does not handle thumbnails very well so it is not recommended to use them. 

 <a href="Simondseconoart-small.png" class="image" title="Social Networking Sites as Walled Gardens by David Simonds (Used with permission">
  <img alt="Social Networking Sites as Walled Gardens by David Simonds (Used with permission)" src="Simondseconoart-small.png" width="465" height="374"/>
 </a>

Social Networking Sites as Walled Gardens by David Simonds (Used with permission)

What we have out of MediaWiki is: 

   <a href="http://www.w3.org/2005/Incubator/ssn/wiki/File:SSO-pattern-complete.jpg" class="image" title="Figure 5.8: Implementation of the Stimulus-Sensor-Observation design pattern in the SSN Ontology">
    <img alt="A concept map showing the 7 classes and 11 properties which forms the skeleton of the SSN Ontology" src="./ssn-xgr_files/900px-SSO-pattern-complete.jpg" width="900" height="458" border="0"/>
   </a>

What needs to be done:

  • Add the caption for every image
  • Fix/modify the href to point to a local copy of the original image (and replace the images which have been shrinked during the export by the original ones)

Here is an example of caption:

Figure 5.8: Implementation of the Stimulus-Sensor-Observation design pattern in the SSN Ontology

Code snippets

Code snippets should be placed in a no wiki block to avoid the creation of extra links using the URLs in the code. 

   <someCode/>

Also, in retrospect, it would have been preferable to use Turtle snippets rather than RDF/OWL snippets.

Tables

What needs to be done:

  • Add a summary description for each table (WCAG2) and a title
  • Add scope="col" and scope="row" annotations

Example:

Table 3.1: Use case categories
Use Case Class Short Description
1. Use case 1 Description of use case 1
2. Use case 2 Description of use case 2

Bibliographical references

The W3C style for reference is partially described in the Style Manual. W3C authors tend to cite W3C documents and document available online more often than papers, so it is important to include a link to the documents when possible.

The approach to handle references on MediaWiki is based on the inclusion of an HTML snippet as shown below:

  • This is some text about GRDDL (GRDDL PRIMER 2007)
  • This is the references at the end of the report: [GRDDL PRIMER 2007] H. Halpin and I. Davis GRDDL Primer. Note W3C, 2007.

When the report is a compilation of other pages, the references should be included at the bottom of the main page (e.g. at the end of Incubator Report). The mentions to these references should include the name of this page to ensure that the link (in the HTML version derived from the wiki) is pointing to the right place.

Example: [Lefort 2009 ].

A Tagged Bibliography may also be useful when the number of references is greater than 40 or 50.

Local links

Modify all the links originally defined as local to a sub-page of a report to make them local to the main page (Incubator report).

Fix the link to local media (e.g. OWL files)

  • use the PURLs for the links instead of the links to the real files.

Fix the pink and blue boxes (containing the links to additional documents and examples)

Issue: the CSS style for XGRs does not allow the blue and pink boxes (this is a style only used in W3C "Guides" which is quite useful to highlight the additional resources e.g. ontologies, examples, ...)

Solution:

  • Add a table with the list of Modules plus links to the semi-automated documentation for each module in the figure captions
  • Add the links to the examples at the bottom of each example

Validation of XG report on the wiki

Hot tip: It is better to fix as many things as possible prior to the conversion to HTML

  • Use Total Validator with the following configuration:
    • HTML Auto detect,
    • WCAG v2 AA,
    • check for broken links ticked,
    • Show warnings ticked

Result should be something like: Total errors found: 700+ (HTML: 1, WCAG v2 A: 700+ (E892 ones + 4), Link Errors: 7 (varies))

  • Link Errors
    • E041 - 0 instance(s): The link could not be tested due to a connection failure. You should test this link manually. - 2 intermittent www.spase-group.org errors, 13 intermittent dx.doi.org errors, 1 intermittent www.alter-net.info errors.
    • E401 - 2 instance(s): Unauthorized: The remote server requires authorisation in order to access this document. You may be able to set the user/password for this link on the Advanced Form. - 2 errors caused by W3C Tracker tool
    • E404 - 5 instance(s): Not Found: The remote server could not find a document at the URL provided. The link may refer to a document that no longer exists, or is pointing to the wrong place. - 5 errors caused by link to other MediaWiki pages
  • HTML Errors
    • E651 - 1 instance(s): When you include a 'for' attribute to associate a label with a control you must provide a control with a matching 'id' value in the same form. Referencing controls in different forms, or outside of forms produces an inaccessible page.See http://www.w3.org/TR/html401/interact/forms.html#h-17.9.1 (displayed in new window). - error caused by MediaWiki (Search box)
  • WCAG v2 A Errors
    • E871 - 1 instance(s): Describe the purpose of a link by providing descriptive text as the content of the <a> element. The description lets a user distinguish this link from other links in the Web page and helps the user determine whether to follow the link. The URI of the destination is generally not sufficiently descriptive. See http://www.w3.org/TR/WCAG20-TECHS/H30.html (displayed in new window) - error caused by MediaWiki
    • E879 - 1 instance(s): Provide either a , 'title' or 'summary' attributes to describe the table. This must be a proper description and not a terse one. See http://www.w3.org/TR/UNDERSTANDING-WCAG20/content-structure-separation-programmatic.html (displayed in new window). If this is not a data table and it is an HTML5 page then this is an HTML5 error as layout tables should not be used in HTML5. Or this is an accessibility error as there is structural markup present. See http://www.w3.org/TR/2008/NOTE-WCAG20-TECHS-20081211/F46 (displayed in new window). - error caused by MediaWiki not annotating the table of contents
    • E883 - 1 instance(s): Heading elements must be ordered properly. For example, H2 elements should follow H1 elements, H3 elements should follow H2 elements, etc. Developers should not skip levels or use headings for presentation effects. See http://www.w3.org/TR/WCAG20-TECHS/F43.html (displayed in new window) error caused by MediaWiki
    • E892 - 745 instance(s): Tags that are being used purely to create a visual presentation effect should not be used. You should use CSS to control layout and presentation so that users and their aids may control it. See http://www.w3.org/TR/WCAG20-TECHS/G140.html (displayed in new window) - error caused by MediaWiki using I and B tags instead of EM and STRONG
    • E895 - 1 instance(s): References to other parts of the same document must exist to ensure that Web pages can be interpreted properly. Note that certain attributes such as 'for' can only reference certain elements in the same %lt;form>, others can only reference elements in the same table. See http://www.w3.org/TR/WCAG20-TECHS/F62.html (displayed in new window) - error caused by Media wiki

Export into HTML from MediaWiki

The trick (apart from using the macros to assemble the report into a single page to export) is to change the style to Simple and to disable the Auto-number headings features of media wiki and any other tweaks. This can be done wia the Preferences page in MediaWiki.

MediaWiki Misc Preferences (normal / to export content for publication)

  • tick Simple to export
  • tick W3CMonobook to read normally

MediaWiki Misc Preferences (normal / to export content for publication)

  • Format broken links like this (ticked / not ticked)
  • Justify paragraphs (ticked / not ticked)
  • Auto-number headings (not ticked / ticked)
  • Show table of contents (ticked / not ticked)

Then go to the report page and find the link to the Printable version on the left (this removes the \[edit\] which are embedded for each o the sections and sub-sections).

Fixing errors caused by I and B tags

Replace manually all the i tags by em tags and the b tags by strong tags (this will remove all the E892 errors).

Adding the Pubrules elements

  • Remove the part of the header and footer inherited from MediaWiki
  • Add all the elements listed in the Pubrules for XGRs

Tidy

Fix HTML errors using tidy (which do not occur when the file is exported without asking for the "Printable version") e.g.

  • Warning: unescaped & or unknown entity "&printable"
  • Warning:
    element not empty or not closed
  • Warning: replacing invalid character
  • Warning: unescaped & or unknown entity "&M_Ontology.pdf" (specific problem with URLs of O&M documents)
  • Warning: <img> element not empty or not closed
  • Warning:
    element not empty or not closed

To run tidy: tidy.exe -asxhtml -f ssn-xgr-errors.txt -o ssn-xgr-tidy.htm ssn-xgr.htm

Total Validator on the local file

Can be quite slow! But results are similar to the ones on the MediaWiki page.

Results:

  • Link Errors
    • E401 - 2 instance(s): Unauthorized: The remote server requires authorisation in order to access this document. You may be able to set the user/password for this link on the Advanced Form - same as before - tracker
    • E404 - 2 instance(s): Not Found: The remote server could not find a document at the URL provided. The link may refer to a document that no longer exists, or is pointing to the wrong place - URI of documents: http://www.w3.org/2005/Incubator/ssn/XGR-ssn-20110614/ and http://www.w3.org/2005/Incubator/ssn/XGR-ssn/
    • E500 - 10 instance(s): Internal Server Error: This appears when a link to a document caused part of the remote server to fail (e.g. a CGI program) or encounter a configuration error - errors previously appearing as a E404, who correspond to links to DOI URLs, links to IEEExplore URLs
  • HTML Errors

Fix the images

  • Move local images to images sub-folder
  • Replace the links to wiki images to link to local images (switching back from re-dimensioned images to original ones)

Fix the special characters

Check the special characters which have not been handled well during the transformation from the wiki to HTML.

  • Raul's first name plus Politechnica Replace by Raúl Politécnica
  • '
  • " (not the same before and after - search occurences of â )
  • °
  • Fix the  

Fix the "style" attributes for styles which are not defined in the CSS used by XGRs

Issue: Total Validator reports some errors because of the reference to a specific style in the toolbox box div elements: margin-bottom: 1em;

Solution: Remove all the style=" because the CSS style for XGR is quite strict.

Modify the report structure to remove the h4 for blue and pink boxes

Issue: the "toolbox" and "event" boxes should be suppressed in the HTML version (this layout option is not available for XGRs)

Solution:

  • rename the "available resources" headings as "introduction"
  • suppress the "example (OWL)" headings

Plus fix the ToC

Fix the links

Because we have used the printable version to do the export from Media Wiki, all the URLs of the links have been included in the text. This can be changed by replacing all occurrences of class="external text" by class="internal".

replace "Incubator Report#" links by "ssn-xgr.htm#" links

Rename the HTML file

It is better initially to use a specific name to manage the local links (to facilitate the search and replace operations).

But, the final version will be published as an index.html file so the "ssn-xgr.htm#..." links need to be replaced by "#..." links.

Publish the report and the ontologies

Publish the ontologies

Package all the files so that the W3C webmaster can place them in a single folder (the files are ready but they should be renamed so that their names match the last part of their PURLs)

Place the generated documentation in the same file as the file with a .htaccess file (use Recipe 3a. Extended configuration for a 'hash namespace' - PURL-adapted)

Plus the PURL set up as a 302: 

# Rewrite engine setup
RewriteEngine On
RewriteBase /ssn/ssnx/
#
# Rewrite rule to make sure we serve HTML content from the namespace URI if requested
RewriteCond %{HTTP_ACCEPT} !application/rdf\+xml.*(text/html|application/xhtml\+xml)
RewriteCond %{HTTP_ACCEPT} text/html [OR]
RewriteCond %{HTTP_ACCEPT} application/xhtml\+xml [OR]
RewriteCond %{HTTP_USER_AGENT} ^Mozilla/.*
RewriteRule ^ssn$ ssn.html [R=303]
#
# Rewrite rule to make sure we serve the RDF/XML content from the namespace URI by default
RewriteRule ^ssn$ ssn.owl [R=303]
#
# Rewrite rule to serve RDF/XML content if requested
RewriteCond %{HTTP_ACCEPT} application/rdf\+xml
RewriteRule ^ssn$ ssn.owl [R=303]
#
# Choose the default response
RewriteRule ^ssn$ ssn.owl [R=303]


Check the report (PubRules)

There is a tool developed by W3C for when the report is uploaded in its final place for the W3C webmaster to check the correct application of PubRules.

(Both checkers are useable only when the report is posted at its final location)

Manual checker http://www.w3.org/2005/07/pubrules?uimode=checker_full&uri=

Validate (Linked Data)

There is a tool developed by CTIC to check the correct deployment of the ontology and examples:

Retrieved from "https://www.w3.org/2005/Incubator/ssn/wiki/index.php?title=Publishing_Incubator_Group_Documents&oldid=3264"