--- title: T-spec meeting 2023-12-07 tags: ["T-spec", "meeting", "minutes"] date: 2023-12-07 discussion: https://rust-lang.zulipchat.com/#narrow/stream/399173-t-spec/topic/Meeting.202023-12-07 url: https://hackmd.io/qx5IGRSPTW-lM91Y7a4lyA?both --- Attendees: Joel, Felix, Eric, Mara, Pietro, Lokathor, Lukas Wirth, TC ## Overview of Ferrocene tooling Pietro to present (improvising, technically on leave this week, so not prepared) Sphinx and rST (restructured text markup) https://www.sphinx-doc.org/ Sphinx is analogous to mdbook. It parses rST (and a dialect of markdown) and is extensible. Considered asciidoc, but impossible to generate it programatically. Drafting was fully done in Google Docs. Used different fonts etc. for features Docs doesn't have. Custom tool to convert Google Docs to rST. Easier than GitHub PR reviews in early stage. Worked in Docs until the very last stage. Might not work well for the Rust project, though. Sphinx: used custom extensions. - support for cross linking, with namespaces ```rst This is a :t:`borrow` of :t:`[string]s`. ``` - parse grammar definition to add anchors+links - collection of e.g. all 'undefined behaviour' subsections into an overview page. stable identifiers for sections. (also possible for paragraphs, but not used.) Manually added random IDs: ``` * :dp:`fls_qytgkbhqr5ln` The :t:`indexed operand` of an :t:`index expression` if evaluated in a :t:`mutable place expression context`, ``` meaningful ids (esp. for paragraphs) are hard. so used randomly generated ids ada spec has manual paragraph numbers. not advisable if things change regularly. ids also used for unit tests: - https://public-docs.ferrocene.dev/main/qualification/traceability-matrix.html - https://github.com/ferrocene/ferrocene/blob/20caa761e10510d071a921ca038828d716e638f2/tests/ui/box/unit/unique-ffi-symbols.rs full readable path into the spec would be better to use in tests. Mara: Did you consider writing your own doc tooling from scratch? No, only looked at existing tools. Might have considered writing something if nothing was suitable. AsciiDoc based tooling didn't work, because the rules are too context dependent, making the automatic conversion from Google Doc too hard. Mara: Wasn't it very annoying/verbose to write the :t:\`..\` syntax all the time? Most of those were generated (from google docs). Google Docs: using fonts/syntax for markup was painful, but automatic suggestions (instead of PR comments with suggestions) was very useful. Goal of ferrocene spec wasn't to be the most comprehensive, only to be enough for requirements from regulations. No need to think about long term. Felix: what should we learn from your experience? What tools should we consider for collaboration? The workflow worked for a small and full-time team. Wouldn't work for a longer term project of an open-source project. Joel: Would you do it the same if you were doing it all over? Glossary isn't great, bad structure. Paragraph IDs in google docs was painful. Otherwise pretty satisfied. Now using sphinx for the rest of ferrocene docs. works fine. comments in google docs really helped. would still use google doc. ## Content of Ferrocene spec (not tooling) Used ADA spec structure (chapters/sections). ADA was a big contributor. Helped removing initial discussion and bikeshedding. Just pick something that works well enough. Mostly remained unchanged. Basically only added "unsafety". Only written to meet the regulations, not intended to be the most comprehensive Rust spec. But, the spec is complete, in the sense that it specifies the whole language. For example, doesn't describe how borrow checker works. Only its requirements, which are quite simple. Will need expanding to be used by the Rust project. Doesn't have memory model. Assumes no_std. Mara: Why does the spec include Option and Result if it doesn't include libcore? libcore is left to the customer. items that are mentioned are relevant for lang items, etc. not sure about section 16. just to introduce the alternative to error handling. doesn't really belong in spec, more in a guide. regulators asked about this specifically. --- Mara: Next step is to have a discussion on which properties of the ferrocene spec we think are a good fit and which properties are not a good fit.