T-spec meeting 2024-01-25

--- title: T-spec meeting 2024-01-25 tags: ["T-spec", "meeting", "minutes"] date: 2024-01-25 discussion: https://rust-lang.zulipchat.com/#narrow/stream/399173-t-spec/topic/Meeting.202024-01-25 url: https://hackmd.io/r0zuRamES02jEym5LL1RZw --- Attendees: Connor Horman, Joel Marcey, Eric Huss, Dawn, Monadic Cat ## Potential Agenda - Review of feedback from lang, opsem teams on sample chapters. - Continue abstract phases discussion (maybe try to apply the phases to array sample chapter live?) - Other business/topics ## Phases in the sample chapter - Connor: Modified to include phases with keywords. <https://github.com/chorman0773/rust-lang-spec/blob/connor-sample-chapter-arrays-rewrite/spec/lang/exprs/array.md> - Clauses starting with keywords indicate the phase. Constraints, mandates, panics, preconditions - Conner: Would like to see one chapter for lexing, and not have that spread through other chapters. - Conner: Need a glossary what the keywords mean. In particular the relationship with const-eval. - eric: Two questions: 1) Are the phases delineated as separate sections, or are the phases just mentioned within the flow of the text. 2) What are the phases? - Conner: Was following the C++ library spec, which clearly delineates the sections. - Joel: Readability-wise, keeping them separate seems to work better. - Conner: A benefit, can play with the presentation of the keyword itself to make it clearer. Can potentially be written as a marker in the source material. Can be difficult with markdown to format it. - Joel: Appreciated Will Hawkins's tool for highlighting the grammar. https://rust-lang.zulipchat.com/#narrow/stream/399173-t-spec/topic/Grammar.20visualisation.20tool/near/417957659 - Joel: Noticed Connor's didn't have links between sections. - Connor: That is something that isn't added, yet. - Joel: Not necessarily HTML linking, referencing the content. - Connor: Makes sense for the expr to refer to the type, but maybe not the other way around. - Joel: Is there anything we need to do further to expand on the sample chapter? - Connor: A glossary to define the keywords. - Joel: Can the glosssary be defined automatically? A marker in the text that indicates a keyword is being defined in that location. - Connor: Might do it the other way around. The keywords are annotated in the text, which can link back to the glossary. It can be an error if the keyword is not in the glossary. - Joel: If a keyword is in the spec a hundred times, does it have to be marked in the source every time? - Connor: Yea, keeping it a lightweight syntax. - Connor: If using custom tooling, would suggest XML. - That's a big if, and the real benefit is we can inline HTML. - Joel: Almost certainly with custom tooling. - Connor: Uneasy about using markdown, since we'll need to make so many customizations it won't look like markdown in the end. - Joel: Propose to move forward with something like what Connor mocked up, with a separate glossary defining the terms. - Joel: Would like to make some progress on the tooling, possibly updating Connor's with something closer to what we would like to see. - Joel: What kind of syntax do we feel comfortable with? - Eric: Doesn't have a strong opinion, but appreciate something as lightweight as possible. - Eric: Suggest brainstorming on Zulip on a set of terms. - Eric: Specifically, the terms we are going to be using for phases, the terms we are going to be using for delinating sections of the spec. - Connor: Keywords are intended to evoke a particular phase - Eric: Task for this week - get a list of terms and try to understand how they will fit in. - Eric: Wondering if it would be a good exercise to draft an outline for what the final document might look like. - Joel will take that as an action item. - Connor: Wants to combine what Mara does with what Connor is doing as far as naming things. Name a whole section using two levels (x.x), each subsection is with three levels (x.x.x). - Eric: it is fine to look at other docs - reference, Ferrocene, etc. for inspiration in the outline. ## Action Items - Joel: Create an initial specification outline - Joel: Start a glossary with appropriate keywords - Connor: Rewrite array sample chapter with XML tagging