Publishing Incubator Group Documents

From Semantic Sensor Network Incubator Group
Revision as of 04:58, 16 June 2011 by Llefort (Talk | contribs)

Jump to: navigation, search

XGRs

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
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 handles thumbnails not well so it is not recommended to use them (or at least not recommended to use them at the time the HTML version of the report is created.


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

TO DO:

  • Add the caption for every image
  • Wrap the img element in a @class="figure" div element
  • Fix/modify the href to point to a local copy of the original image (the one which has not been shrinked during the export)

The caption is:

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

Code snippets

Place in a no wiki block to avoid the creation of extra links using the URLs in the code.

   <someCode/>
 


Tables

  • 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, then 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 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

Move all the links so that instead of being local to a sub-page of a report they are local to the main page (Incubator report).

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 pix boxes (this is a style only used in W3C "Guides")

Solution:

  • Add a table with the list of Modules plus the link to the semi-automated documentation for each module
  • Add a table with the links to the examples plus the content of the blue box for each examples

Validation of XG report on the wiki

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: 761 (HTML: 1, WCAG v2 A: 748, Link Errors: 12)

  • 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 and 13 intermittent dx.doi.org 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 - 744 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

Comment: Avoid to use thumb MediaWiki attribute for images as this will lead to many more MediaWiki-caused errors.

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.

Adding the Pubrules elements

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

Tidy

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

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

Total Validator on the local file

Very slow! But results are similar to the ones on the MediaWiki page.

Results (TO DO AGAIN):

  • 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 link to local media (e.g. OWL files)

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

Fix the images

  • Add the captions for each image
  • 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
  • suppress the "example (OWL)" headings

Plus fix the ToC

Fix the links

Because we have used the printable version, 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

Publish the report and the ontologies (TO DO)

  • 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:

Check the report (PubRules)

There is a tool developed by W3C for when the report is uploaded in its final place.

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