Feedback request: a ES spec. organization experiment

classic Classic list List threaded Threaded
17 messages Options
Reply | Threaded
Open this post in threaded view
|

Feedback request: a ES spec. organization experiment

Allen Wirfs-Brock
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.


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?

Allen

_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request: a ES spec. organization experiment

Michael Dyck
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.

-Michael



_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request: a ES spec. organization experiment

Andreas Rossberg-4
In reply to this post by Allen Wirfs-Brock
On 12 October 2011 02:32, Allen Wirfs-Brock <[hidden email]> wrote:

> The experiments are shown
> in http://wiki.ecmascript.org/lib/exe/fetch.php?id=harmony%3Aspecification_drafts&cache=cache&media=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.)

/Andreas
_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request: a ES spec. organization experiment

Rick Waldron
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 http://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.

Rick 

On Wed, Oct 12, 2011 at 2:53 AM, Andreas Rossberg <[hidden email]> wrote:
On 12 October 2011 02:32, Allen Wirfs-Brock <[hidden email]> wrote:
> The experiments are shown
> in http://wiki.ecmascript.org/lib/exe/fetch.php?id=harmony%3Aspecification_drafts&cache=cache&media=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.)

/Andreas
_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss


_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request: a ES spec. organization experiment

Allen Wirfs-Brock
In reply to this post by Andreas Rossberg-4

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.)

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.

Allen

_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request: a ES spec. organization experiment

Andreas Rossberg-4
On 12 October 2011 18:34, Allen Wirfs-Brock <[hidden email]> wrote:
>
> http://wiki.ecmascript.org/lib/exe/fetch.php?id=harmony%3Aspecification_drafts&cache=cache&media=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.

/Andreas
_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request: a ES spec. organization experiment

Allen Wirfs-Brock
In reply to this post by Rick Waldron
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 http://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.  

Allen





Rick 

On Wed, Oct 12, 2011 at 2:53 AM, Andreas Rossberg <[hidden email]> wrote:
On 12 October 2011 02:32, Allen Wirfs-Brock <[hidden email]> wrote:
> The experiments are shown
> in http://wiki.ecmascript.org/lib/exe/fetch.php?id=harmony%3Aspecification_drafts&cache=cache&media=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.)

/Andreas
_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss



_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request: a ES spec. organization experiment

Claus Reinke
>> 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
>> http://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.
> 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.
>
> Allen
>
>
>
>
>>
>> Rick
>>
>> On Wed, Oct 12, 2011 at 2:53 AM, Andreas Rossberg <[hidden email]>
>> wrote:
>> On 12 October 2011 02:32, Allen Wirfs-Brock <[hidden email]>
>> wrote:
>> > The experiments are shown
>> > in
>> > http://wiki.ecmascript.org/lib/exe/fetch.php?id=harmony%3Aspecification_drafts&cache=cache&media=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.)
>>
>> /Andreas
>> _______________________________________________
>> es-discuss mailing list
>> [hidden email]
>> https://mail.mozilla.org/listinfo/es-discuss
>>
>
>



> _______________________________________________
> es-discuss mailing list
> [hidden email]
> https://mail.mozilla.org/listinfo/es-discuss
>

 

_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request: a ES spec. organization experiment

Claus Reinke
In reply to this post by Allen Wirfs-Brock
[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
>>> http://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
http://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.
 
_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request: a ES spec. organization experiment

Dean Landolt


On Wed, Oct 12, 2011 at 1:34 PM, Claus Reinke <[hidden email]> 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
http://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]

_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request: a ES spec. organization experiment

Allen Wirfs-Brock

On Oct 12, 2011, at 11:11 AM, Dean Landolt wrote:



On Wed, Oct 12, 2011 at 1:34 PM, Claus Reinke <[hidden email]> 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 http://wiki.ecmascript.org/doku.php?id=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:

and


(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...)

Allen



_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request: a ES spec. organization experiment

Dean Landolt


On Wed, Oct 12, 2011 at 2:47 PM, Allen Wirfs-Brock <[hidden email]> wrote:

On Oct 12, 2011, at 11:11 AM, Dean Landolt wrote:



On Wed, Oct 12, 2011 at 1:34 PM, Claus Reinke <[hidden email]> 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 http://wiki.ecmascript.org/doku.php?id=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:

and


(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.

_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request: a ES spec. organization experiment

Allen Wirfs-Brock

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.

Allen
_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request: a ES spec. organization experiment

Rick Waldron
In reply to this post by Allen Wirfs-Brock


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 :) 

_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request: a ES spec. organization experiment

Michael Dyck
In reply to this post by Allen Wirfs-Brock
Allen Wirfs-Brock wrote:
>
> The doc version of the latest stable draft is always posted
> at http://wiki.ecmascript.org/doku.php?id=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.

-Michael

_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request: a ES spec. organization experiment

Allen Wirfs-Brock

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 http://wiki.ecmascript.org/doku.php?id=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.

Allen

_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Feedback request: a ES spec. organization experiment

Geoffrey Sneddon-3
In reply to this post by Allen Wirfs-Brock
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?)

--
Geoffrey Sneddon — Opera Software
<http://gsnedders.com>
<http://opera.com>
_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss