New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

3.9 Consider dividing the specification #53

Closed
ndw opened this Issue Aug 22, 2014 · 10 comments

Comments

Projects
None yet
2 participants
@ndw
Collaborator

ndw commented Aug 22, 2014

XProc 1.0 is a specification that consists of both the language definition and the inventory of required and optional steps. Release management might be simplified by separating the language core from the vocabulary of steps and providing some sort of versioning strategy that allowed the vocabulary of steps to be revised more frequently. XProc 2.0 may be defined in more than one Rec-track specification document.

@ndw ndw added this to the XProc 2.0 LC milestone Aug 25, 2014

@xquery

This comment has been minimized.

Collaborator

xquery commented Sep 4, 2014

https://xproc.github.io/specification/

seems to be a start in this direction; a few observations;

  • are we planning to remove duplication of step info defined within spec and provide link to separate docs ?
  • for steps (that live under protected xproc ns), I think we need to keep in a single repository (as it is today) ... and keep extension steps in other repository (should we consider renaming that repo to be clearer eg. extension-steps ?)
  • Are we planning separate docs for both required and optional (they are currently merged) steps ?

Lastly, I see we have a separate doc for xproc internals and errors ... FWIW I think the rules for spec decomposition should facilitate isolation of steps.

@ndw

This comment has been minimized.

Collaborator

ndw commented Sep 4, 2014

No, the namespace documents have always been (and need to be) separate. We didn't actually get them successfully installed by the W3C staff for XProc 1.0, but that's a separate problem.

The 'steps' repo is for our official steps. The 'extensions' repo is for extensions.

Maybe they should all be in the same repo. I think that would facilitate building specs for them and making the namespaces documents have all the combined details. (At the moment, the errors and steps associated with p:template are not in the ancillary namespaces documents.)

I think the highest priority question is: are we going to have separate specs for the language and steps?

We went back and forth in the 1.0 timeframe and I think we're still going back and forth.

@xquery

This comment has been minimized.

Collaborator

xquery commented Sep 4, 2014

I may have missed something ... I was under the impression that we had already agreed it was a good idea to publish steps separately from spec and thats why its in as task (with the 'should' label denoting priority and available time/effort to achieve).

As we are embark on new round of spec evolution, I would rather we resolve this sooner.

To be explicit, my pref is to have xproc official steps in same repo as spec, but published separately.

I don't fully understand the value of ns docs, especially if they are duplicated in the main spec.

Also (to take your p:template example) the errors and steps associated with p:template would surely go into the separate steps spec right ?

@ndw

This comment has been minimized.

Collaborator

ndw commented Sep 4, 2014

Maybe I missed something. Anyway, if we're resolved to do this, yes we should do it sooner.

So your preference, just to be clear, is a single language document and a separate single step vocabulary document. Is that right? Or are you thinking of separate required and optional step documents?

The NS docs are supposed to be at the NS URIs. So they return a concise summary of what's in the namespace. Or at least that's what I tried to make them do.

The p:template errors and such would go in the "vocabulary" document for sure. And if they were all in one repo (and I think I agree that they should be) then they could all be combined in the NS docs.

@ndw

This comment has been minimized.

Collaborator

ndw commented Sep 4, 2014

I think the "should" is "should consider", but...

Straw proposal, three REC track documents:

XProc 2.0: An XML Pipeline Language
XProc 2.0: Required Step Vocabulary
XProc 2.0: Optional Step Vocabulary

Thoughts?

See also: http://lists.w3.org/Archives/Public/public-xml-processing-model-wg/2014Sep/0005.html

@xquery

This comment has been minimized.

Collaborator

xquery commented Oct 5, 2014

email thread seems to indicate there is consensus on having two published specs, split as follows.

What we are trying to do is get a natural workflow with how new steps(and functions) integrate into the overall picture and how we curate them through time, as well as how they map in terms of github repos. This needs to be super clear and simple.

I propose we have a single repo for publishing the two official specs

XProc 2.0: An XML Pipeline Language
XProc 2.0: Required and Optional Steps

This allows us the flexibility to officially publish new steps independently of the XProc core spec.

Then we can use an additional repository for extension steps & functions for the publication of less formal Notes.

An example step lifecycle could be;

a) new step submission to extension step & function repo
b) publication as a Note, with step choosing to live in XProc ns (we already did this with others) or some other namespace.
c) some time passes, we choose to adopt step into official required/optional steps
d) amend 'XProc 2.0: Required and Optional Step Vocabulary' and publish with new official step

Which lets us evolve the step library independently of the core language.

Considering this, I wonder if we should decompose standard-components.xml into required-steps.xml & optional-steps.xml with the follow on that we could choose to further breakdown each step into separate documents this would make integrating steps (unsure about functions) from extension steps, easier.

Can we put this on next weeks agenda to finalize ?

@ndw

This comment has been minimized.

Collaborator

ndw commented Oct 5, 2014

Yes, I'll put it on the agenda. I feel like we get a little pushback, perhaps it was from Liam, when we discuss it.

@ndw

This comment has been minimized.

Collaborator

ndw commented Oct 27, 2014

Reorg of langspec to go with this change (editor asserts this is editorial, just noting it here):

XPath Extension Functions -> Extension Functions and goes after Standard Step Library
Security Considerations and Versioning Considerations go after Extension Functions

@ndw

This comment has been minimized.

Collaborator

ndw commented Oct 27, 2014

Also move Namespace Fixup on Outputs to an appendix or at least later

ndw added a commit that referenced this issue Nov 13, 2014

Fix issue #53 by splitting the spec in two
This was agreed at the 12 Nov 2014 WG meeting.
@ndw

This comment has been minimized.

Collaborator

ndw commented Nov 13, 2014

The split has been done. The other rearranging can be/will be done later.

@ndw ndw closed this Nov 13, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment