Restructuring StrucSpec and Semantics

After hearing a fair bit of support and no objections to my  
restructuring experiments, and in anticipation of us perhaps wanting  
to publish new working drafts, and given the need to make progress on  
user facing documents, and in consultation with various people  
working on the core trio documents, I've started restructuring the  
editor's drafts of the Structural Specification document and the  
Semantics document.

STRUCTURAL SPEC: http://www.w3.org/2007/OWL/wiki/Syntax

The first change I've made to the structural spec is primarily adding  
new headers and introducing a more regular style of presentation to  
each section. There has been some light editing (e.g., dropping "The  
grammar for foo is as follows"), and I've consolidated all the  
details about annotation into a single section but have not yet  
rewritten it to make sense:

	DIFF: http://www.w3.org/2007/OWL/wiki/index.php? 
title=Syntax&diff=4052&oldid=3619

Note that I have put in place holder for illustrative examples, but  
haven't filled in most of them. I *welcome* contributions!!!

I hope people feel that there is a big improvement just from looking  
at the table of contents. (There are still tweaks to be done in the  
gross structure, of course, but I think this is much more explicit  
and thus more informative at-a-glance.)

I then replaced the old intro with the one from the strucref  
experiment. I introduce the distinction between entities,  
expressions, and axioms which I used in the headers:

	DIFF: http://www.w3.org/2007/OWL/wiki/index.php? 
title=Syntax&diff=4053&oldid=4052

SEMANTICS: http://www.w3.org/2007/OWL/wiki/Semantics

I added some analogous headers to the Semantics Document:
	DIFF: http://www.w3.org/2007/OWL/wiki/index.php? 
title=Semantics&curid=152&diff=3500&oldid=3284

I've not yet added cross links or tried to subdivide tables in any way.

NEXT STEPS

Things on the list:
	* start adding more cross referencing links
	  *e.g., from the primer
	* fill in examples
	  * Make examples appear in user preferred syntax
	* add and flesh out explanatory text
	* clean up annotations section
	* add selective display (e.g., if you don't want UML or you don't  
want the grammar or you don't want the examples)
	* work on index

I think the primer will be much nicer if it has cross links into more  
detailed descriptions, so I think it would be nice to publish another  
working draft of the strucspec when we publish the primer (which I  
hope is around the next heartbeat). We've made a variety of  
substantive changes as well to the strucspec, plus I think if we can  
improve the readabiilty substantively, to refresh the WD.

Feedback welcome, as always.

Cheers,
Bijan.

Received on Wednesday, 5 March 2008 20:44:46 UTC