Skip to content
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

Add models/processes to overview #242

Open
wants to merge 2 commits into
base: main-1.3
Choose a base branch
from
Open

Conversation

Thom1729
Copy link
Collaborator

Add a short introduction to the data models and processes in the language overview. The new descriptions are meant to be formally correct, but high-level and incomplete. This is in preparation for expanding the model and process sections into full individual chapters.

By submitting this pull request, I confirm that you can use, modify, copy, and
redistribute this contribution, under the terms of your choice.

@Thom1729 Thom1729 added the Spec Change Any change to the specification itself label Oct 24, 2021
@Thom1729 Thom1729 requested a review from a team as a code owner October 24, 2021 17:54
@Thom1729
Copy link
Collaborator Author


# Chapter #. Processes
The following diagram summarizes the three _information models_.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence declares 3 things, but then 4 things are listed below.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's original text, but it does look especially dubious in the new context. I've reworded it for now.

In the future, I'm not sure that it's helpful to have the presentation stream stuff in the combined diagram, but that's for another time.

Copy link
Member

@eemeli eemeli left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The language changes here seem fine, but I'm starting to get the feeling that this informative text really ought to go into a separate document than the spec itself. Or is there some way in which any of this actually affects how YAML is handled?

What I'm envisioning here is that there could be a separate treatise on "This is how most YAML processors do things." This could help in reducing the size of the actual spec.

@Thom1729
Copy link
Collaborator Author

I generally agree. I think that in this case there is value to having a quick, formal-but-not-complete listing of the information models and processes before the detailed descriptions in the chapters. This PR adds text, but I'm hoping that having a concise introduction here will help us to remove redundant text elsewhere.

@ingydotnet
Copy link
Member

I'd like to propose slowing down on shaping the 1.3 spec until we know more clearly what we are intending to specify.

In my current opinion, the successful rollout of YAML 1.3 depends on several things including:

  • The YAML RFC process
  • The YAML test suite for 1.3 processes
  • The 1.3 Spec document
  • The 1.3 implementer guides
  • The 1.3 YAML user guides
  • The 1.3 reference grammar(s)
  • The 1.3 reference implementations
  • Various feature specs like ypath and yfun that we want to promote
  • The 1.3 scheme (YAML processor config) format
  • The 1.3 standard library

etc.

I feel like at this point we need to flesh out these ideas to get a clearer vision of what 1.3 will be, before we spend much more time of the spec.

For instance re #241, I'd like to see published documentation that replaces anything we want to remove.

Let's hold off on merging this #241 and #242 for now...

We can continue to make low hanging, non-contentious modifications to the productions, but the overall shape of the informative parts will be more obvious after we make progress on the other fronts.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Spec Change Any change to the specification itself
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants