Add a glossary and index of concepts
tadbyt opened this issue · comments
Location
It is proposed that this glossary be placed in the book between the Language Reference and the Revision History.
Description
Attached is a proof-of-concept PDF version of a Glossary of Terms, Usages, and Shorthands. This glossary provides a concise definition for each term employed in The Swift Programming Language, along with an instruction for each referenced usage and shorthand.
- A term is a word or phrase that has a specific connotation with respect to Swift.
- A usage refers to the employment of one or more lexical elements (keyword, operator, punctuation mark, or delimiter) that yields a particular semantic.
- A shorthand is an alternative nomenclature that is more concise and generally clearer than the semantically equivalent explicit canonical form.
This glossary serves as a semantic counterpoint to the syntactic Summary of the Grammar in breadth, if not depth. Depth is provided by following an entry’s associated link(s) to relevant material primarily in The Swift Programming Language, the Swift standard library documentation, elsewhere in the Apple online developer documentation, and www.swift.org. Some concepts are referenced by multiple distinct terms. In these cases, a definition and relevant links are provided for one of the terms and the remainder reference that term.
Note: This glossary is based entirely on the current release (5.10) of The Swift Programming Language book, not on the current release of the language in Xcode or on any other platform. Consequently, there may be features that have been implemented in Swift compilers, but not yet documented; fixes that are in work or have been completed, but not yet released; and new features that are pre-implemented and not officially released. None are documented here. Also, errors and omissions in the text of the book, if any, are also reflected here.
Note: The attached proof-of-concept PDF and markdown versions encompasses the entire book. Completed PDF and markdown versions should be ready for review during the first half of April.
Swift Glossary 2024-03-13.pdf
Swift_Glossary_2024-03-13.md
Motivation
From my knothole, The Swift Programming Language book is the Swift de facto language standard, given that none is published, and this book is maintained by those involved with the continuing development of the language. Swift is not a simple language, although one still relatively easy to learn. It is a sophisticated, high-level modern programming language. Swift incorporates many concepts and has an extensive lexicon.
The primary motivation behind the glossary is to provide an efficient mechanism for both those learning the language and experienced practitioners to find the material they need. The book is divided into two major parts, the Language Guide and Language Reference. Concepts and their associated terminology may be found in one or both parts. Since The Swift Programming Language is no longer provided as a comprehensive document, one can no longer do a simple textual search of the entire document. Using a Google search often brings up material unassociated with Swift or out-of-date discussions. The attached glossary was put together as an exercise to gather the set of the Swift focused concepts, terms, usages, and shorthands contained in the current book so that they could be readily accessed. Incorporating this into the book may help others access the same material. In fact, there are two open issues that appear to request somewhat less ambitious alternatives (Issues #175 and #101).
Two related secondary motivations are to provide a common lexicon based on the content of the book and to provide a tool to aide in improving the quality of the book itself. A thorough reading of the book reveals that the document has had multiple authors whose use of jargon has evolved along with the language, but insufficient editing of existing material has failed to keep all sections current. The exercise of building the glossary has generated more than 20 other specific, actionable issues. An example of this is actors. In many sections, the discussion refers to one or more of classes, enumerations, and structures, but doesn’t reference actors. In some cases, this is correct. In others, it is misleading. Also, several holes in the material were identified, such as not including compound assignment operators in the formal grammar, unless as just binary infix operators. Further, instances were found where definitions given in one portion of the book seem to contradict those given in another or that multiple terms are employed for the same concept. Having a common lexicon will make it easier to find and remove these kinds of defects from the book, yielding a higher-quality, more accurate and trusted document.
Should this be incorporated, it would require only a nominal effort to maintain as the underlying book is relatively mature and stable. Changes in the glossary would only be required to correct errors and omissions and to follow along with changes to the book itself. The former should mostly be accomplished with its initial review prior to incorporation. The latter would occur when material was deleted from, moved around, or added to the book. It should only be done once the material changes to the book had in fact been reviewed and integrated. The marginal effort involved should be minimal.
Alternatives Considered
Requesting that some comprehensive document version of The Swift Programming Language be constructed is unrealistic, although there is an open issue (Issue #2) requesting that.
Requesting that an index be constructed and maintained would result an effort only slightly smaller in scope but would provide a less optimal experience. Simply identifying all the subsections in which a term or concept exists doesn’t provide as effective tool in accessing the material as providing a concise definition or instruction with references to just the most relevant subsections.
I wasn't able to look at your attached PDF to see the examples — GitHub returns a 404 error for the attachment link. Can you try to re-attach it, or copy some brief examples inline here?
Can you provide some additional detail about how this is different from #101? It sounds like you might be suggesting an index of both language keywords and Swift-specific terminology. If that's the case, we can update the title and description of this GitHub issue to focus on adding a glossary of Swift terminology .
It's probably helpful to separate out discussion of TSPL being incomplete and discussion of TSPL not having an offline searchable form like an ePUB. Those are both known issue, tracked elsewhere. Likewise, as far as using consistent terminology within TSPL, let's track that as specific PRs or issues to add needed entries to the top-level style guide and fix content, rather than trying to have a single bug to track revising everything everywhere.
The issue has been updated to include both the current PDF and markdown versions. The review is ongoing and should be completed within a month with the issue updated with the final draft versions at that time.
Thanks for re-attaching your glossary. To follow the process described in this repo's README file, discussion of what the specific issue is belongs here on a GitHub issue. If you think the 200-page glossary you attached is a solution to this issue, your next step is to pitch that on the Swift.org forums in the documentation area. I'd suggest providing context including some topics like the following:
- How did you choose what terms to define in the glossary? Are there terms in your attachment that you included for some other audience, but which TSPL should omit? (For example, why are symbols from the standard library included?)
- Where should this material go in the book? How should we leave space for other kinds of indexes, such as the language keyword index discussed in #101?
- How will we maintain the glossary going forward? (For example, should we write a script to let us author glossary entries in the chapter where the topics are discussed, but which collects them in a new chapter?)
- What style guidelines do we need to define and add to Style.md in this repo, to keep the glossary entries consistent?
- How does someone who found only part of their answer in the glossary find additional information? Do we need links back to the guide & reference sections that discuss it?
As you write up your pitch, you might also want to keep in mind that you're proposing a major addition to the book, adding 100k words to a 250k word book. You'll want explain why there isn't a smaller solution that would resolve this issue. Or if there is a smaller solution, what that would look like.
Thanks!