[Proposal] Code Regions and Document Services

Introduction

The ideas shared, below, pertain to connections between literate computer programming, computer-aided reasoning, computer-aided mathematical proofs, computer-aided argumentation, computer-aided fact-checking and computational journalism.

Web documents can include code regions for content in computer programming languages, knowledge representation languages, other machine-readable syntaxes, or natural languages. These code regions can connect to URL-addressable services to provide features including presenting users with visual hints and feedback. Such visual hints and feedback could pertain to the correctness of programming language portions, to epistemological factors pertaining to fact-checking, or to the verification and correctness of reasoning or argumentation.

Code Regions

Code regions are document elements which contain content in computer programming languages, knowledge representation languages, other machine-readable languages, or natural languages.

Groups of code regions connect to URL-addressable services. A service processes the contents of a group of code regions and provides state information and informational messages for each code region in the group. Web documents can contain multiple groups of code regions, each connected to a service.

Services can provide users with visual hints and feedback on code regions. Code regions connected to services pertaining to programming languages could provide users with help, information, warnings and errors. Code regions connected to services pertaining to fact-checking could provide users with a number of epistemological visual hints and feedback items. Code regions connected to services pertaining to automated reasoning or automated theorem proving could provide users with visual hints and feedback related to verification or correctness.

The technical means of providing users with visual hints and feedback are cascading stylesheets utilizing an attribute-based style selector to vary styling based upon the value of a state attribute which is updated by a service. The possible values of the state attribute are service-specific.

As styleable document elements, code regions can be either inline or block elements in documents, flowing within regions of text or positioned between regions of text.

Services

A service is any compiler, interpreter, runtime environment, automated theorem prover, automated reasoner, fact-checking system, or other software system which can, via a protocol, provide custom state data and messages for code regions.

Services can be hosted locally on client machines, hosted on organizations’ servers, remote servers, or hosted on the cloud.

A service receives a request which includes a grouping of code regions, the contents of those code regions, and it responds with state information for each code region, e.g. “ok” or “error”, and an array of pertinent messages for each code region.

Example code-region Element and Attributes

The following element and attributes are a preliminary rough-draft sketch provided for purposes of discussion and to expand upon and to clarify upon the ideas discussed above.

In the following example, all of the code-region elements with a group attribute value of “1234” are gathered together for purposes of an XML-RPC request to a service at a relative URL “service.php”. The HTML/XHTML contents of the group’s code-region elements are included in the XML-RPC request to the service. The service is invoked whenever: (1) one of the code regions in the group changes, (2) the document sequence of code regions in the group changes, or (3) the group’s service is invoked via JavaScript. Whenever the service is successfully invoked, it responds with data which is utilized to automatically populate the state and message attributes of each code-region element in the group.

<code-region
service="service.php"
service-type="xml-rpc"
group="1234"
index="1"
state="error"
message="…">
  …
</code-region>

The service attribute is for the URL of a services with which to process the contents of a sequence of code regions participating in a group.

The service-type attribute is for extensibility and indicates the type of or protocol for the service, e.g. XML-RPC. The default value could be “xml-rpc”.

The group attribute is a text string identifying which group that a code region is in. The text value should be unique to the document. A Web document can contain multiple groups and each can contain multiple code regions.

The index attribute of a code region is the code region’s index within the sequence of code regions within a group. Its default value is obtained from auto-incrementing a counter for each code region of a group as it occurs in document order.

The state attribute is for data returned by a service for a particular code region. It is a service-specific text value which is automatically placed into the attribute value for purposes of scripting or styling.

For example,

code-region[state='ok']:after { content:url('ok.png'); }
code-region[state='error']:after { content:url('error.png'); }

or

code-region[state='error'] { text-decoration:underline wavy red; }

The message attribute is for data returned by a service for a particular code region. Its value is an array of service-specific text strings. Where the state attribute could indicate an error, the value(s) of the message attribute might describe the error.

The content-editable attribute is for indicating whether a user can edit the content of the code region.

The Advancement of Artificial Intelligence

With code regions, Web documents can make use of artificial intelligence services including, but not limited to: automated theorem provers, automated reasoners and fact-checking systems.

Users could, for instance, author argumentative essays and utilize code regions, resembling literate computer programming, to show that their facts were checked and that their arguments were valid and machine-verifiable.

The ease of authoring, viewing and sharing Web documents which utilize artificial intelligence services could invigorate artificial intelligence research and development.

Conclusion

The ideas shared, above, pertain to connections between literate computer programming, computer-aided reasoning, computer-aided mathematical proofs, computer-aided argumentation, computer-aided fact-checking and computational journalism.

Web documents can include code regions for content in computer programming languages, knowledge representation languages, other machine-readable syntaxes, or natural languages. These code regions can connect to URL-addressable services to provide features including presenting users with visual hints and feedback. Such visual hints and feedback could pertain to the correctness of programming language portions, to epistemological factors pertaining to fact-checking, or to the verification and correctness of reasoning or argumentation.

Other Possible Markup

Here are some other preliminary markup ideas for the scenarios described above:

1. Services could be declared or defined in the HTML document head element and reference code-region elements by id.

<html>
  <head>
    <service id="service1" service="service.php">
      <element xref="cr1" />
      <element xref="cr2" />
      <element xref="cr3" />
    </service>
  </head>
  <body>
    <p>
      <span>...</span>
      <code-region id="cr1" state="ok">...</code-region>
      <span>...</span>
      <code-region id="cr2" state="ok">...</code-region>
      <span>...</span>
      <code-region id="cr3" state="ok">...</code-region>
    </p>
  </body>
</html>

2. Services could be declared or defined in the HTML document head element and select code-region elements by class name.

<html>
  <head>
    <service id="service1" service="service.php" select="thm-1" />
  </head>
  <body>
    <p>
      <span>...</span>
      <code-region class="thm-1" state="ok">...</code-region>
      <span>...</span>
      <code-region class="thm-1" state="ok">...</code-region>
      <span>...</span>
      <code-region class="thm-1" state="ok">...</code-region>
    </p>
  </body>
</html>

3. service elements could be parents or ancestors of grouped code-region elements.

<html>
  <body>
    <p>
      <service id="service1" service="service.php">
        <span>...</span>
        <code-region state="ok">...</code-region>
        <span>...</span>
        <code-region state="ok">...</code-region>
        <span>...</span>
        <code-region state="ok">...</code-region>
      </service>
    </p>
  </body>
</html>

Types of Services

Possible types of services include:

• spelling checking
• grammar checking
• syntax checking
• software verification and validation
• fact-checking
• proof checking
• reasoning verification
• argumentation verification

Messages and JavaScript

In addition to the possibility of setting a message attribute in a manner pertaining to the value of the state attribute, implementation possibilities include populating an array of JavaScript message objects on each code-region element by processing services’ responses. A message, then, could be more than a text string; each message value could deserialize to a JavaScript object with multiple fields or properties. A message could, for instance, contain a selection range.

With JavaScript messages available to place on code-region elements, and with some other JavaScript processing, more types of services become possible.

• spelling recommendation
• grammar recommendation
• syntax recommendation
• other content recommendation
• compilers
• interpreters
• computer algebra systems
• displaying relevant messages when users hover over content

code-region Content Replacement

If services can replace the HTML contents of code-region elements with HTML content provided in services’ responses, then other types of services become possible:

• syntax highlighting

Conclusion

Hopefully, the lists above show the utility of code regions and services. There are probably other types of services to be considered as well.

Multiple Document Services

One might observe that multiple document services can be defined in Web documents and that they could reference or select overlapping sets of code-region elements. One might, for example, desire to use both a spell checker and grammar checker service on the same document content.

In the approach described, above, state attributes are populated by document services for purposes of scripting and styling. Some complexity would arise when populating state attributes on code-region elements with service-specific values from multiple document services.

A solution is to specify which HTML attributes will be used for service-specific state data per document service. With respect to messages pertaining to state, text-string messages or JavaScript message objects could be interwoven into arrays or placed into other data structures which indicate which document services that sets of messages are from.

Hopefully, the following examples can clarify:

1. Services could be declared or defined in the HTML document head element and reference code-region elements by id.

<html>
  <head>
    <service id="service1" service="service1.php" state="state1">
      <element xref="cr1" />
      <element xref="cr2" />
      <element xref="cr3" />
    </service>
    <service id="service2" service="service2.php" state="state2">
      <element xref="cr3" />
    </service>
  </head>
  <body>
    <p>
      <span>...</span>
      <code-region id="cr1" state1="ok">...</code-region>
      <span>...</span>
      <code-region id="cr2" state1="ok">...</code-region>
      <span>...</span>
      <code-region id="cr3" state1="ok" state2="ok">...</code-region>
    </p>
  </body>
</html>

2. Services could be declared or defined in the HTML document head element and select code-region elements by class name.

<html>
  <head>
    <service id="service1" service="service1.php" state="state1" select="thm-1" />
    <service id="service2" service="service2.php" state="state2" select="qed" />
  </head>
  <body>
    <p>
      <span>...</span>
      <code-region class="thm-1" state1="ok">...</code-region>
      <span>...</span>
      <code-region class="thm-1" state1="ok">...</code-region>
      <span>...</span>
      <code-region class="thm-1 qed" state1="ok" state2="ok">...</code-region>
    </p>
  </body>
</html>

3. As an aside, the approach facilitates nesting service elements for approach 3. service elements could be parents or ancestors of grouped code-region elements.

<html>
  <body>
    <p>
      <service id="service1" service="service1.php" state="state1">
        <span>...</span>
        <code-region state1="ok">...</code-region>
        <span>...</span>
        <code-region state1="ok">...</code-region>
        <span>...</span>
        <service id="service2" service="service2.php" state="state2">
          <code-region state1="ok" state2="ok">...</code-region>
        </service>
      </service>
    </p>
  </body>
</html>

Conclusion

Specifying which HTML attributes are to be populated by document services facilitates multi-service scenarios, e.g. both spell checking and grammar checking, and styling and scripting based on state data from multiple document services.

Well-known Document Services

It may be the case that certain document services are well-known, e.g. spell checking, and often available client-side or at a location known to or configured on a Web browser.

For these scenarios, uniform resource names could refer to well-known document services and could be provided instead of URL’s. Web browsers could, then, recognize the uniform resource names of well-known document services to encapsulate client-local document services or to route to document services at configured locations.

For example:

<service id="service1" service="urn:service:spell-checker:en-US">
  <element xref="cr1" />
</service>

or

<service id="service1" service="urn:service:spell-checker:en-US" select="spchk" />

would intend for Web browsers to utilize a well-known document service, in this case spell checking, available either client-side or at a location known to or configured on a Web browser.