Re: Merging the interfaces and algorithms sections

Anssi,

The pull request LGTM.  Am I to assume that all the paragraphs classed
"XXX" require expansion to complete this iteration of the spec?

Mark


On Mon, Jan 19, 2015 at 12:14 PM, Kostiainen, Anssi <
anssi.kostiainen@intel.com> wrote:

> Hi All,
>
> [Hat off]
>
> I crafted a PR [1] that attempts to structure the specification text a bit
> differently. This pass is an editorial in nature and no normative changes
> were introduced (not intentional, at least). An HTML review is available at
> [2].
>
> In the current Presentation API spec [3], the IDL blocks and the
> algorithms are in their own sections, in "Interfaces" and "Algorithms"
> sections respectively. However, many specs (such as HTML, DOM, many Web
> APIs) use a style where the prose and related algorithms immediately follow
> the respective IDL blocks. In this attempt, I merged the two similarly. On
> the same pass I tried to make sure all the interface members have
> definitions in the prose. IOW, if you click an IDL member in any of the IDL
> blocks at [2], you should land in the prose where the respective IDL member
> is defined.
>
> I added some placeholder text too that has been annotated with green boxes
> -- the boxes themselves are just an aide to help visually review what has
> been added, and we'll drop the styling after review. Placeholders that seem
> to require expansion, are followed by ellipses (...).
>
> For consistency with other specs, we may want to consider adopting a
> structure along these lines. We can use [2] as a starting point if deemed
> helpful.
>
> Btw. I opened an issue re carving out the Requirements and Example
> sections [4] into its own doc. That's an enhancement we can do at a later
> stage -- if the group thinks it is a good idea. An example of such a [very
> extensive] UCs and Reqs doc is at [5].
>
> [Hat on]
>
> Thanks,
>
> -Anssi
>
> [1] https://github.com/w3c/presentation-api/pull/41
> [2] http://rawgit.com/anssiko/presentation-api/reorg/index.html
> [3] http://w3c.github.io/presentation-api/
> [4] https://github.com/w3c/presentation-api/issues/42
> [5] http://w3c-webmob.github.io/installable-webapps/
>