Re: Conversion of SPARQL docs

> On Jan 18, 2023, at 4:25 AM, Andy Seaborne <andy@apache.org> wrote:
> 
> Suggested document title changes.
> 
> 
> "SPARQL Query Results XML Format (Second Edition)"
> ==>
> "SPARQL 1.2 Query Results XML Format"
> 
> based on consistency across the 3 results documents.

+1

> and also
> 
> "SPARQL 1.1 Graph Store HTTP Protocol"
> ==>
> "SPARQL 1.2 Graph Store Protocol"
> 
> which aligns to the 1.2 short name

+1

> (and seems to be the general usage, at least in the few times its come up in the WG)
> 
> The other protocol spec does not have "HTTP" in the title.

Also, "SPARQL 1.2 Overview” => "SPARQL 1.2 Concepts”, and a new “What’s new in SPARQL 1.2” document.

There’s likely work to do to get back some of the imporatant bits of example, table, and diagram styling. Note the ReSpec has some more facilities, particularly for examples, that we might want to employ (e.g., titles for individual examples). There’s also a convention I’ve used in the RDF specs to allow for not using HTML escapes within examples by using an “updateExample” transformation step. May or may not be useful here.

I think there are also a number of code blocks, which aren’t necessarily examples that we may want to agree on how to format. Ideally, the common bits can be extracted into the common CSS style sheet.

Gregg

>  Andy
> 
> On 18/01/2023 11:22, Andy Seaborne wrote:
>> There is a translation of each of the SPARQL 1.1 documents to reSpec format at:
>>  https://afs.github.io/sparql-respec/
>> This is bulk conversion by scripts, enough to get reSpec output to show the content and TOC. References have not been converted. (Gregg has kindly separated provided reference conversion for query and a refs database).
>> There is a WG issue:
>> https://github.com/w3c/rdf-star-wg/issues/3
>> The first goal is to be able to stop mechanical conversion and formatting so that editing the documents on their own can take over.
>> The second goal is to put into the structure Gregg has created in th WG repos.
>>   Andy
>

Received on Wednesday, 18 January 2023 16:06:48 UTC