Feedback request: a ES spec. organization experiment
Allen Wirfs-Brock wrote:
I'm personally finding it harder to find things in the current draft.
To fix this I've been experimenting with several different organizations and I would like some feedback on the alternative I've come up with.
I think the third version is the most readable. The addition (w.r.t. the second version) of subsection headings is useful: if I scroll for more than a couple pages without seeing a section number, I can lose track of where I am.
In the fourth version, in the Semantics section, each production is basically the header of a mini-section, so I think it would be an improvement if the productions stood out more than they do. E.g., put a horizontal rule before each, or indent the subordinate text.
On 12 October 2011 02:32, Allen Wirfs-Brock <allen at wirfs-brock.com> wrote:
The experiments are shown in harmony:11.1.5-alternatives.pdf This contains four versions of section 11.5.1 (Object literals). Each section is about 4 pages long and contains the same specification text, but organized in slightly different ways. The first version is what is currently in the specification. All the semantics definitions are lumped together in a single "Semantics" section in roughly the same order as the productions occur in the grammar. Each definition includes the grammar production it applies to so the order doesn't have any semantic significance. The second version regroups the semantic functions according to semantic function. First there are all the static semantic definitions for all the productions. Then all the PropertyDefinitionList function definitions for the productions that define it, and so until finally there are the evaluation function definitions for all the productions. The third version is ordered just like the second version but it uses explicit subsection headings for each function group in order to make them more visible. The four version orders everything by grammar production. It shows a production and immediately has all the functions that apply to that production.
The third version seems far superior. It makes a proper, visible separation between static semantics and dynamic semantics, which is very helpful, and standard practice as well.
In fact, you could be even more consistent about the triptych syntax/static semantics/dynamic semantics by grouping all of the latter in a subsection as well. That would be my preferred structure. (If you worry about having too many levels of numbering you might want to avoid numbering the individual bits of the dynamic semantics in that case. I think their section numbers are a minor concern.)
(BTW, in addition to a better structure, I have to agree with Claus that having hyperlinks in the PDF would be a real blessing. I don't know how much work that would be, though.)
Allen,
Have you considered moving the spec drafting to a revision controlled system, such as git? Michael Smith maintains an annotated and hyperlinked version of ES5.1 here es5.github.com. A system like this would certainly make your maintenance tasks easier, in addition to facilitating a simplified workfow for creating experimental versions.
On Oct 12, 2011, at 2:53 AM, Andreas Rossberg wrote:
The third version seems far superior. It makes a proper, visible separation between static semantics and dynamic semantics, which is very helpful, and standard practice as well. .#3 was also my favorite from the first batch
In fact, you could be even more consistent about the triptych syntax/static semantics/dynamic semantics by grouping all of the latter in a subsection as well. That would be my preferred structure. (If you worry about having too many levels of numbering you might want to avoid numbering the individual bits of the dynamic semantics in that case. I think their section numbers are a minor concern.)
harmony:11.1.5-alternatives-2.pdf has a 5th alternative version that follows your suggested structure. Note that I classified semantic functions that only depend upon the static structure of the program under "static semantics"
Unless somebody comes up with some better ideas I think this is the one I will go with.
(BTW, in addition to a better structure, I have to agree with Claus that having hyperlinks in the PDF would be a real blessing. I don't know how much work that would be, though.)
I agree that internal hyperlinks would be useful, but I don't intend to spend any time on them until this editions is much closer to completion. They're too hard to maintain in a rapidly changing document.
On 12 October 2011 18:34, Allen Wirfs-Brock <allen at wirfs-brock.com> wrote:
harmony:11.1.5-alternatives-2.pdf has a 5th alternative version that follows your suggested structure. Note that I classified semantic functions that only depend upon the static structure of the program under "static semantics" Unless somebody comes up with some better ideas I think this is the one I will go with.
Nice, me likes.
(BTW, in addition to a better structure, I have to agree with Claus that having hyperlinks in the PDF would be a real blessing. I don't know how much work that would be, though.)
I agree that internal hyperlinks would be useful, but I don't intend to spend any time on them until this editions is much closer to completion. They're too hard to maintain in a rapidly changing document.
Sure, I can definitely understand that.
On Oct 12, 2011, at 9:28 AM, Rick Waldron wrote:
Allen,
Have you considered moving the spec drafting to a revision controlled system, such as git? Michael Smith maintains an annotated and hyperlinked version of ES5.1 here es5.github.com. A system like this would certainly make your maintenance tasks easier, in addition to facilitating a simplified workfow for creating experimental versions.
The formal standards process is still targeted towards producing paper documents and Ecma currently requires that these documents be delivered in MS Word format and follow specific styling guidelines (there is what is essentially an ISO standard for standards that we are supposed to follow).
Ecma-262 is a complex document. Edition 6 is likely to exceed 300 pages. While Word is far from perfect, it actually provides reasonable support and tooling for documents of that size. It isn't clear to me how github would help with such a document. While I have no fundamental objection to an HTML based document and editing environment, I have no interest to reverting to doing manual formatting markug. I moved beyond that technology around 1985. I've yet to see HTML document tooling that addresses the WYSIWYG production of documents of this complexity. It they are out there I would like to hear about them.
Have you considered moving the spec drafting to a revision controlled system, such as git? Michael Smith maintains an annotated and hyperlinked version of ES5.1 here es5.github.com. A system like this would certainly make your maintenance tasks easier, in addition to facilitating a simplified workfow for creating experimental versions.
It would be interesting to know what tools were used to generate the HTML version from the PDF - somewhere in that toolchain, hyperlinks were added.
[sorry for the incomplete message earlier - keyboard glitch]
Have you considered moving the spec drafting to a revision controlled system, such as git? Michael Smith maintains an annotated and hyperlinked version of ES5.1 here es5.github.com. A system like this would certainly make your maintenance tasks easier, in addition to facilitating a simplified workfow for creating experimental versions.
It would be interesting to know what tools were used to generate the HTML version from the PDF - somewhere in that toolchain, hyperlinks were added.
The formal standards process is still targeted towards producing paper documents and Ecma currently requires that these documents be delivered in MS Word format and follow specific styling guidelines (there is what is essentially an ISO standard for standards that we are supposed to follow).
Ecma-262 is a complex document. Edition 6 is likely to exceed 300 pages. While Word is far from perfect, it actually provides reasonable support and tooling for documents of that size. It isn't clear to me how github would help with such a document. While I have no fundamental objection to an HTML based document and editing environment, I have no interest to reverting to doing manual formatting markug. I moved beyond that technology around 1985.
My favourite tested technology for that size documents would be LaTeX;-) But there is no need to switch away from the tools you are using. At least, I think that Word has "Export To XML" and "Import From XML" functionality.
So the XML version could be on github, and serve for patch sending and discussion, as well as giving a basis for tools to work on (such as a search/replace for adding hyperlinks). I do not know what Word offers in the way of collaborative editing, but even if you don't want to use github collaboration, having a spec version on github that can be processed by tools would be great.
Assuming, of course, that the exported XML is not completely unreadable!-)
I do understand that you have more important tasks to worry about for the foreseeable future than adding hyperlinks[*]. When the time comes to add them, please remember to turn bookmarks into "named destinations" as well? It allows to open PDF documents with URL fragments, jumping directly to the named sections.
Claus clausreinke.github.com
[*] In LaTeX, at least, internal hyperlinks would be logical, not absolute, so I'm surprised to hear that they would pose maintenance problems during drafting in Word.
On Wed, Oct 12, 2011 at 1:34 PM, Claus Reinke <claus.reinke at talk21.com>wrote:
[sorry for the incomplete message earlier - keyboard glitch]
Have you considered moving the spec drafting to a revision
controlled system, such as git? Michael Smith maintains an annotated and hyperlinked version of ES5.1 here es5.github.com. A system like this would certainly make your maintenance tasks easier, in addition to facilitating a simplified workfow for creating experimental versions.
It would be interesting to know what tools were used to generate the HTML version from the PDF - somewhere in that toolchain, hyperlinks were added.
The formal standards process is still targeted towards producing
paper documents and Ecma currently requires that these documents be delivered in MS Word format and follow specific styling guidelines (there is what is essentially an ISO standard for standards that we are supposed to follow).
Ecma-262 is a complex document. Edition 6 is likely to exceed 300 pages. While Word is far from perfect, it actually provides reasonable support and tooling for documents of that size. It isn't clear to me how github would help with such a document. While I have no fundamental objection to an HTML based document and editing environment, I have no interest to reverting to doing manual formatting markug. I moved beyond that technology around 1985.
My favourite tested technology for that size documents would be LaTeX;-) But there is no need to switch away from the tools you are using. At least, I think that Word has "Export To XML" and "Import From XML" functionality. So the XML version could be on github, and serve for patch sending and discussion, as well as giving a basis for tools to work on (such as a search/replace for adding hyperlinks). I do not know what Word offers in the way of collaborative editing, but even if you don't want to use github collaboration, having a spec version on github that can be processed by tools would be great.
Assuming, of course, that the exported XML is not completely unreadable!-)
It will be, at least to humans :)
But it doesn't need to be -- there'd still be a huge advantage to tossing the xml -- or better, just the doc or docx -- up to github. Tools could then poll and process what's there in various ways -- all without Allen having to do any heavy lifting. A possible side effect would be a git repo full of the post-processed results (in various forms) enabling diffing one could only dream of against a naked word doc.
[snipped the rest]
On Oct 12, 2011, at 11:11 AM, Dean Landolt wrote:
On Wed, Oct 12, 2011 at 1:34 PM, Claus Reinke <claus.reinke at talk21.com> wrote: ...
Assuming, of course, that the exported XML is not completely unreadable!-)
It will be, at least to humans :)
But it doesn't need to be -- there'd still be a huge advantage to tossing the xml -- or better, just the doc or docx -- up to github. Tools could then poll and process what's there in various ways -- all without Allen having to do any heavy lifting. A possible side effect would be a git repo full of the post-processed results (in various forms) enabling diffing one could only dream of against a naked word doc.
The doc version of the latest stable draft is always posted at harmony:specification_drafts I can also start to post a docx version if there are people that want them.
For the curious, I've created and uploaded html and docx versions of my experiments document: harmony:11.1.5-alternatives-2.htm
and
harmony:11.1.5-alternatives-2.xml
(the ES wiki wouldn't let me upload a file with the docx extension so I changed it to xml. change it back to docx if you want to open it with word. Also, I note the Firefox claims that it is not a well-formed XML document...)
On Wed, Oct 12, 2011 at 2:47 PM, Allen Wirfs-Brock <allen at wirfs-brock.com>wrote:
On Oct 12, 2011, at 11:11 AM, Dean Landolt wrote:
On Wed, Oct 12, 2011 at 1:34 PM, Claus Reinke <claus.reinke at talk21.com>wrote:
...
Assuming, of course, that the exported XML is not completely unreadable!-)
It will be, at least to humans :)
But it doesn't need to be -- there'd still be a huge advantage to tossing the xml -- or better, just the doc or docx -- up to github. Tools could then poll and process what's there in various ways -- all without Allen having to do any heavy lifting. A possible side effect would be a git repo full of the post-processed results (in various forms) enabling diffing one could only dream of against a naked word doc.
The doc version of the latest stable draft is always posted at harmony:specification_drafts
This is perfect. Should be enough to poll, postprocess and push to github if anyone were so inclined.
I can also start to post a docx version if there are people that want them.
For the curious, I've created and uploaded html and docx versions of my experiments document:
harmony:11.1.5-alternatives-2.htmharmony:11.1.5-alternatives-2.htm
and
harmony:11.1.5-alternatives-2.xmlharmony:11.1.5-alternatives-2.xml
(the ES wiki wouldn't let me upload a file with the docx extension so I changed it to xml. change it back to docx if you want to open it with word. Also, I note the Firefox claims that it is not a well-formed XML document...)
So does chrome. If you view-source on it it appears to be binary -- and just as I suspected, it's actually just a zip (very much like odf). So for the curious, just download, change the extension to .zip and poke around to see if it's of any use.
Thanks Allen.
On Oct 12, 2011, at 12:22 PM, Dean Landolt wrote:
So does chrome. If you view-source on it it appears to be binary -- and just as I suspected, it's actually just a zip (very much like odf). So for the curious, just download, change the extension to .zip and poke around to see if it's of any use.
oops, I forgot that docx files are always zipped. that's why the docx version is the smallest of the lot.
The formal standards process is still targeted towards producing paper documents and Ecma currently requires that these documents be delivered in MS Word format and follow specific styling guidelines (there is what is essentially an ISO standard for standards that we are supposed to follow).
Ecma-262 is a complex document. Edition 6 is likely to exceed 300 pages. While Word is far from perfect, it actually provides reasonable support and tooling for documents of that size. It isn't clear to me how github would help with such a document. While I have no fundamental objection to an HTML based document and editing environment, I have no interest to reverting to doing manual formatting markug. I moved beyond that technology around 1985. I've yet to see HTML document tooling that addresses the WYSIWYG production of documents of this complexity. It they are out there I would like to hear about them.
Thanks for the clarification and explanation :)
Allen Wirfs-Brock wrote:
The doc version of the latest stable draft is always posted at harmony:specification_drafts I can also start to post a docx version if there are people that want them.
Yes, please.
Currently, to get something I can deal with, I load the .doc into OpenOffice and save as HTML, which I think loses some useful info and somewhat mangles the result. It would be better to be able to start with something closer to the source document.
On Oct 12, 2011, at 5:58 PM, Michael Dyck wrote:
Allen Wirfs-Brock wrote:
The doc version of the latest stable draft is always posted at harmony:specification_drafts I can also start to post a docx version if there are people that want them.
Yes, please.
Currently, to get something I can deal with, I load the .doc into OpenOffice and save as HTML, which I think loses some useful info and somewhat mangles the result. It would be better to be able to start with something closer to the source document.
I actually maintain the draft in .doc format as that still seems to be the preferred interchange format by most people. For now, if I publish a .docx version it will have been generated from the doc version so it should be intentionally using any docx exclusive features.
On 12/10/11 01:32, Allen Wirfs-Brock wrote:
Which style do you think I should use in the specification?
On the whole, I don't think it matters. I don't think it's really the right way to solve the problem (finding cross-referenced functions). What would be (far) better, IMO, is to link cross-references (i.e., so "PutValue" is a hyperlink to the PutValue definition).
As for the changing document, I guess at least some (most of what is from ES5.1, for a start) is almost certainly going to say around, so that effort probably isn't a waste.
(On a side-note, with the discussion of HTML, I wonder how hard it would be to write a print style-sheet targetting something like PrinceXML to cope with all the publication rules?)
The "ES6" specification has more complicated language constructs that require more verbose specification language for many constructs. One of the techniques I'm using is to have more semantic functions over grammar productions . The readability of the specification seems to be quite sensitive to how such functions are organized within the various sections of the specifications. I'm personally finding it harder to find things in the current draft.
To fix this I've been experimenting with several different organizations and I would like some feedback on the alternative I've come up with.
The experiments are shown in harmony:11.1.5-alternatives.pdf
This contains four versions of section 11.5.1 (Object literals). Each section is about 4 pages long and contains the same specification text, but organized in slightly different ways.
The first version is what is currently in the specification. All the semantics definitions are lumped together in a single "Semantics" section in roughly the same order as the productions occur in the grammar. Each definition includes the grammar production it applies to so the order doesn't have any semantic significance.
The second version regroups the semantic functions according to semantic function. First there are all the static semantic definitions for all the productions. Then all the PropertyDefinitionList function definitions for the productions that define it, and so until finally there are the evaluation function definitions for all the productions.
The third version is ordered just like the second version but it uses explicit subsection headings for each function group in order to make them more visible.
The four version orders everything by grammar production. It shows a production and immediately has all the functions that apply to that production.
Take a look at and compare each alternative presentation. Which do you find more readable? Which makes it easier to find definitions you might be searching for.
Which style do you think I should use in the specification?