Preferred Format for code examples in Techinques (User Experience Guide)

[gregoriopellegrino]

Background

We are starting to work on the techniques for EPUB Accessibility metadata and ONIX. The goal is to provide clear instructions for developers on how to implement these guidelines effectively, extracting and combining the information from the metadata source.

Issue

Given that the key information we identified in the principles document involves analyzing combinations of different metadata, we believe it is crucial to determine the preferred format for conveying instructions to developers. The challenge lies in finding a robust way to communicate which metadata to extract and how to process it to generate the required strings for display to the end users.

Proposed Solutions

We are considering two primary options for conveying these instructions:

1. XSLT (Extensible Stylesheet Language Transformations):

   • Both EPUB Accessibility metadata and ONIX formats are XML-based.
   • Applying XSLT can directly produce the text to be displayed on-screen.
   • This method leverages the XML structure to extract and format the necessary information.

2. Pseudo-code:

   • Using a pseudo-code approach allows for a more generalized set of instructions.
   • Developers can then adapt the instructions to their specific programming languages and environments.
   • This method provides flexibility but may require more effort on the developer's part.

Request for Input

We are reaching out to the community to gather input on which format would be preferable for developers implementing these guidelines. We would appreciate insights, opinions, or any alternative suggestions.

Examples

To illustrate, here's a sample for both techniques regarding the key information Visual adjustments:

XSLT Example

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:opf="http://www.idpf.org/2007/opf">
    
    <xsl:template match="/">
        <xsl:choose>
            <!-- Check if accessibilityFeature = displayTransformability is present -->
            <xsl:when test="/opf:package/opf:metadata/opf:meta[@property='schema:accessibilityFeature' and text()='displayTransformability']">
                <xsl:text>Appearance can be modified.</xsl:text>
            </xsl:when>
            
            <!-- Check if accessMode = textOnVisual is present -->
            <xsl:when test="/opf:package/opf:metadata/opf:meta[@property='schema:accessMode' and text()='textOnVisual'] and not(/opf:package/opf:metadata/opf:meta[@property='schema:accessibilityFeature' and text()='displayTransformability'])">
                <xsl:text>Appearance cannot be modified.</xsl:text>
            </xsl:when>
            
            <!-- Default case -->
            <xsl:otherwise>
                <xsl:text>Modifiability not known.</xsl:text>
            </xsl:otherwise>
        </xsl:choose>
    </xsl:template>
    
</xsl:stylesheet>

Pseudo-code Example

function check_accessibility_feature(metadata):
    if metadata['schema:accessibilityFeature'] == 'displayTransformability':
        return "Appearance can be modified."
    elif metadata['schema:accessMode'] == 'textOnVisual' and metadata['schema:accessibilityFeature'] != 'displayTransformability':
        return "Appearance cannot be modified."
    else:
        return "Modifiability not known."

Note: In the code, an accessibilityFeature and an accessMode are accessed directly as keys to a dictionary, but there may be more than one in the metadata, so preprocessing or loops would be necessary.

Questions:

1. Which format do you prefer for conveying these instructions: XSLT or Pseudo-code?
2. Do you have any other suggestions or considerations regarding the communication of metadata processing instructions?

[vincent-gros]

1. I prefer pseudo-code, even if XSLT is one of the best for this work. Pseudo-code works for everyone. You could accept proposals in a specific language from the community and, in the end, have several instances of this work, not only in XSLT!

[jonaslil]

I agree that pseudo-code should be preferred. We don't want to exclude those who use other techniques than XSLT. Pseudo-code plus programming language specific examples would be even better.

[gregoriopellegrino]

Thanks for the early feedback. How do you think we can deal with querying metadata in structured XML via pseudo-code?

I think we should simplify the task, assuming that the metadata is already loaded in some form of object model and can be accessed directly, otherwise we would have to specify the loading procedure each time and have loops to find the metadata we are interested in... I mean we should serialize the metadata in some way (like Ace by DAISY serializes the metadata in the JSON report).

If you have any other ideas, they are welcome.

[mattgarrish]

How do you think we can deal with querying metadata in structured XML via pseudo-code?

Could you start by parsing the xml to json via xmlhttprequest and then use infra-type code like we did for processing a publication manifest: https://www.w3.org/TR/pub-manifest/#processing-algorithm ?

(I really don't know off the top of my head, so maybe this is a non-starter.)

[gautierchomel]

To me there should be first a descriptive statement (see below), then pseudo-code can be added as an example and implementation could be provided for all the information (i.e. link to one xslt file).

Descriptive statement:

Visual adjustment information is obtained using two metadata keys:

• accessibilityFeature displayTransformability.
• accessMode textOnVisual

Three cases are possible:

• if schema:accessibilityFeature displayTransformability is present, then the sentence "Appearance can be modified" can be informed.
• if schema:accessMode textOnVisual is present and schema:accessibilityFeature displayTransformability is not present, then the sentence "Appearance cannot be modified." can be informed.
• in all other cases the sentence "Modifiability not known." will have to be informed.

[gautierchomel]

on dec. 14th call we agreed with descriptive statements.