Support for single backtick (`) in code voice #93
Comments
amartini51
added a commit
to amartini51/swift-book
that referenced
this issue
Dec 5, 2022
This markup is the only way to create a code-voice backtick in markdown,
even though it creates a warning due to DocC's meaning of double
backticks to delimit code voice. See also that known issue:
swiftlang#71
swiftlang/swift-markdown#93
amartini51
added a commit
to swiftlang/swift-book
that referenced
this issue
Dec 12, 2022
This markup is the only way to create a code-voice backtick in markdown,
even though it creates a warning due to DocC's meaning of double
backticks to delimit code voice. See also that known issue:
#71
swiftlang/swift-markdown#93
The current (escaped) markup for the 'code' and 'x' example in Lexical
structure does render the backticks, but the backticks are in plain font
instead of code voice, which isn't correct.
Fixes rdar://102988329
sinoru
added a commit
to swiftlang-kr/swift-book
that referenced
this issue
Dec 26, 2022
commit 303719f7d5519c387b73b5e3e4a08c2c9d6d530c Merge: 85ed44e5 3cef181e Author: Alex Martini <[email protected]> Date: Tue Dec 20 11:19:47 2022 -0800 Add custom header for staging copy and build script (#73) Fixes https://github.com/apple/swift-book/issues/34 commit 3cef181ef6762db1c13f082bf0e5dc7c7756c058 Author: Alex Martini <[email protected]> Date: Thu Dec 15 13:36:30 2022 -0800 Match the copyright comment used elsewhere. commit 85ed44e57c3eeba2a62cfdbe9844a2f673e00e53 Merge: c2e70966 dbe46d11 Author: Alex Martini <[email protected]> Date: Thu Dec 15 10:46:24 2022 -0800 Restore numbered lists (#75) Fixes rdar://102987273 commit dbe46d11cf0a2f61d255c4670790a6bfe22a42bd Merge: 8ae873a0 c2e70966 Author: Alex Martini <[email protected]> Date: Thu Dec 15 10:46:10 2022 -0800 Merge branch 'main' into list_102987273 commit c2e70966da12969800dd0ed3c6e5193d8f3e3a3e Merge: caa5009f 5d744e27 Author: Alex Martini <[email protected]> Date: Thu Dec 15 10:42:03 2022 -0800 Input em-dashes with space on both sides (#77) Fixes rdar://102987894 commit 5d744e271ec89702e6d3e533be5d122f64a767e9 Merge: edfd4dd4 caa5009f Author: Alex Martini <[email protected]> Date: Thu Dec 15 10:37:57 2022 -0800 Merge branch 'main' into em_dash_102987894 commit caa5009f04929b72358b3a1d8a7a791e9e642555 Merge: 0f07c46f b84a7907 Author: Alex Martini <[email protected]> Date: Thu Dec 15 10:34:18 2022 -0800 Restore paragraph breaks that were lost lost during the RST export (#79) Fixes rdar://102991635 commit 0f07c46f38a0c734134ff98caac49a8177712baa Merge: df1bb5a3 5c5d4479 Author: Alex Martini <[email protected]> Date: Thu Dec 15 10:33:25 2022 -0800 Restore code voice for links to API symbols (#86) Fixes rdar://103197507 commit 5c5d44793764fa83af9570be2be2cf9a59fd420c Author: Alex Martini <[email protected]> Date: Thu Dec 15 10:28:52 2022 -0800 Use the correct spelling for a function's name. commit 57b53d4f77ebf294b42e41809959abacf8caeb01 Author: Alex Martini <[email protected]> Date: Wed Dec 14 14:32:04 2022 -0800 Restore code voice for links to API symbols. This was lost during the RST export to markdown. Found places to change by searching for "developer.apple.com/documentation" since all of the links are for standard library docs. Verified that all API links have matching URLs by exporting a list of links from the current published version. commit df1bb5a3bff36008c6e44934673d058acbfb5b27 Merge: 0aeb109e f745dc8d Author: Alex Martini <[email protected]> Date: Wed Dec 14 14:50:36 2022 -0800 Correct the spelling/formatting of an initializer. (#81) Fixes rdar://103034843 commit 0aeb109ee88fdf1177676b66912470fbe6f180e5 Merge: b9cce448 fe47f763 Author: Alex Martini <[email protected]> Date: Wed Dec 14 14:49:54 2022 -0800 Fix incorrect (one-space) indentation. (#83) This probably got overlooked by the searches when fixing GitHub issue #43 for PR #53 because it's a one-space indentation. It wasn't a leftover from the Swift 1 era of intentional three-space indentations -- this was just a markup error in source that didn't cause issues under the legacy RST publication pipeline because that pipeline reindented everything anyhow. Fixes rdar://103197773 commit b9cce448b3cbdaf096e5d4112c964c6a01614fa2 Merge: d7ec7c2c 9ef1e3c0 Author: Alex Martini <[email protected]> Date: Tue Dec 13 15:34:35 2022 -0800 Typo: lets -> let (subject/verb agreement) (#85) Fixes rdar://103217436 commit 9ef1e3c0a43de6bcdbb590726e2e067627c2ddef Author: Alex Martini <[email protected]> Date: Tue Dec 13 11:34:02 2022 -0800 Typo: lets -> let (subject/verb agreement) commit b84a7907edc56056d57ad193473bbbd035df4841 Merge: f3982363 d7ec7c2c Author: Alex Martini <[email protected]> Date: Mon Dec 12 16:43:52 2022 -0800 Track 'main' to resolve merge conflicts. Trivial conflict in ReferenceManual/Declarations.md -- both branches made essentially the same changes to whitespace. commit edfd4dd45b7d2d532f7eff79f2b622243708fa43 Merge: 78844ba6 d7ec7c2c Author: Alex Martini <[email protected]> Date: Mon Dec 12 16:41:05 2022 -0800 Track 'main' to resolve merge conflicts. Trivial conflict in ReferenceManual/Declarations.md -- kept the upstream formatting changes from 'main' and reapplied the em-dash changes. commit d7ec7c2c0f1ab2a872a0aa9d9da4e25ff6d3cfec Merge: abf95b59 50e1adf2 Author: Alex Martini <[email protected]> Date: Mon Dec 12 09:43:28 2022 -0800 Fix markup for backtick in code voice (#76) This markup is the only way to create a code-voice backtick in markdown, even though it creates a warning due to DocC's meaning of double backticks to delimit code voice. See also that known issue: https://github.com/apple/swift-book/issues/71 https://github.com/apple/swift-markdown/issues/93 The current (escaped) markup for the 'code' and 'x' example in Lexical structure does render the backticks, but the backticks are in plain font instead of code voice, which isn't correct. Fixes rdar://102988329 commit abf95b599637c6bf8968ae80dedfbb6aa06e0796 Merge: c5e05f12 7fb009f1 Author: Alex Martini <[email protected]> Date: Mon Dec 12 09:41:18 2022 -0800 Add missing headings and abstract to Summary of the Grammar (#82) Fixes rdar://103095366 commit fe47f763f4ba16e1e8bd0fa82846a30213ee6523 Author: Alex Martini <[email protected]> Date: Fri Dec 9 15:57:53 2022 -0800 Fix incorrect (one-space) indentation. commit 7fb009f101ed6e07f2d716ef555c41730395b394 Author: Alex Martini <[email protected]> Date: Thu Dec 8 11:42:04 2022 -0800 Revise abstract for brevity & inclusivity. We don't need to assume that someone is reading this by looking at it, versus some other modality. Saying this is the entire grammar is redundant with saying it's all in one place. commit 957779f2e05bf62d2b7e9e0691f1f019701a9e68 Author: Alex Martini <[email protected]> Date: Thu Dec 8 11:36:30 2022 -0800 Add missing chapter abstract for the grammar. Text from 3d49b27f1183e2d2e16c63e9a98051dc3f54ff44. commit 9639701312322c54ed42ce9d7fe6fa4592ea362d Author: Alex Martini <[email protected]> Date: Thu Dec 8 11:26:47 2022 -0800 Add headings to the summary of the grammar. commit c5e05f1223a209a35c709b02dc5b6c5a19765d32 Merge: aa1c9de7 632d2b71 Author: Alex Martini <[email protected]> Date: Wed Dec 7 14:30:27 2022 -0800 Add workflow guidance for more substantive writing work (#68) Fixes rdar://96314288&96317008 commit aa1c9de7d6e07a02996312f792b1f7d92958fdc7 Merge: 31451888 a8d05918 Author: Alex Martini <[email protected]> Date: Wed Dec 7 14:29:40 2022 -0800 Minor fixes (#70) commit 31451888852ccdec0787266a38cea7b89935f10c Merge: b24b294d f0505d7d Author: Alex Martini <[email protected]> Date: Wed Dec 7 14:27:53 2022 -0800 Correct a fact around @objc protocol adoption (#67) For example, the following works even though the C class isn't marked @objc, isn't a subclass of NSObject, and isn't a subclass of an @objc class: import Foundation @objc protocol P {} class C: P {} Fixes https://github.com/apple/swift-book/issues/66 commit b24b294d919e5cb29ce3d7c70a97a9f33e727fb0 Merge: b8caffb2 56b69e38 Author: Alex Martini <[email protected]> Date: Wed Dec 7 14:26:20 2022 -0800 Remove trailing whitespace (#64) Most of this came from places where the RST to markdown export process included indentation on blank lines in comments. commit b8caffb20d79da0c94032aadb96863da47f7da03 Merge: 46dbe1ef e79dbc50 Author: Alex Martini <[email protected]> Date: Wed Dec 7 14:25:27 2022 -0800 Update name in screenshot markers (#63) The iBooks Store was renamed several years ago -- the comment markers should follow the current name. When we're able to publish an ePUB version again[1], we probably want to retake all of the screenshots. We can update the value of COMMIT in the script at that time, to help us after that so we can find and retake only things that change. Fixes rdar://101972172 1: https://github.com/apple/swift-book/issues/2 commit 8ae873a041d297984b899370743f5f1437f25185 Author: Alex Martini <[email protected]> Date: Tue Dec 6 14:25:14 2022 -0800 Fix additional numbered/bullet list errors. commit f745dc8d50d9eeff039651048d21d75a912b1ab4 Author: Alex Martini <[email protected]> Date: Tue Dec 6 12:02:31 2022 -0800 Correct the spelling/formatting of an initializer. commit f3982363e0c12712c24d72bccb290808595967bc Author: Alex Martini <[email protected]> Date: Tue Dec 6 11:48:30 2022 -0800 Restore multi-paragraph list items. Found these by reviewing the output from: git grep -I '[a-z]\.[A-Z]' commit 085fd4db7bf41f4caa57ddf798e308eb224a6655 Author: Alex Martini <[email protected]> Date: Tue Dec 6 11:39:20 2022 -0800 Fix additional multiparagraph notes. Found many of these via: git grep -I '>.*\.[A-Z]' commit ebdfadbe098cc8614ed717bff7c427f240afc0a0 Author: Alex Martini <[email protected]> Date: Tue Dec 6 10:02:49 2022 -0800 Fix missing paragraph breaks and a typo. Starting a sentence with "there's" in lower case looks like a mistake from commit 264503abe86e5c14da2b42362de3fda989a3c745 when standardizing contractions. commit 5ba3dc969f15bbd7d16e59f03c1c2353e0d8683f Author: Alex Martini <[email protected]> Date: Tue Dec 6 09:56:50 2022 -0800 Restore a lost paragraph break. commit 0d56de462351c7801c50f3dc6fce3dde1ef5ed5c Author: Alex Martini <[email protected]> Date: Mon Dec 5 16:05:52 2022 -0800 Remove options that are no longer needed. Incorporates review comments from Ethan Kusters (@ethan-kusters). commit 50e1adf2f53f38e22735cfa83a9f85cab37c31b8 Author: Alex Martini <[email protected]> Date: Mon Dec 5 14:27:34 2022 -0800 Link from to the issue being worked around. commit 4a6f51d66d0e0a9c02c4d61ab07314b6f3e0c499 Author: Alex Martini <[email protected]> Date: Mon Dec 5 14:26:48 2022 -0800 Fix markup for ` in code voice. commit 998da95b4acd21172849937b5447f237de46277b Author: Alex Martini <[email protected]> Date: Mon Dec 5 12:16:21 2022 -0800 Restore two paragraph breaks lost by RST export. commit 9980f64f19015d995a71970db293a9ccb346a15a Author: Alex Martini <[email protected]> Date: Mon Dec 5 12:14:09 2022 -0800 Restore paragraph break lost during RST export. commit 78844ba67fecf00364a5e98193548424a6888a40 Author: Alex Martini <[email protected]> Date: Mon Dec 5 11:08:12 2022 -0800 Input em-dashes with space on both sides. This matches the rest of the em-dashes in the book. In most cases, because an em-dash is a clause boundary, it ends up at the end of the line with semantic line breaks. The previous RST-based publication pipeline included a step to close up em-dashes, so these few exceptions didn't cause issues. DocC doesn't close up em-dashes, and the current instruction from editorial is to set em-dashes open because the San Francisco font otherwise sets things too close together. When setting this content in another font that doesn't have that issue, like Helvetica, we'd need to teach DocC to close up the em-dashes throughout. commit f3081bcd8bf9d756045d5b551ef8c96708b4ec6b Author: Alex Martini <[email protected]> Date: Mon Dec 5 10:49:22 2022 -0800 Fix markup for backtick. This markup is the only way to create a code-voice backtick in markdown, even though it creates a warning due to DocC's meaning of double backticks to delimit code voice. See also that known issue: https://github.com/apple/swift-book/issues/71 https://github.com/apple/swift-markdown/issues/93 commit d7a9bdb801acbafcc40f275eec2ba01cab2ea0e0 Author: Alex Martini <[email protected]> Date: Mon Dec 5 10:21:46 2022 -0800 Restore a numbered list. This got incorrectly converted from a numbered list to a bulleted list during the RST export to markdown. commit 3a67bb6a8410e27b0300059f71dbb597c47b4692 Author: Alex Martini <[email protected]> Date: Thu Dec 1 11:31:01 2022 -0800 Point to the repos needed for top-of-tree DocC. commit a8d05918e29548adfd5dc4c271ff494b67ff5715 Author: Alex Martini <[email protected]> Date: Fri Nov 11 10:24:42 2022 -0800 Enable the markdown hunk header for diff context. Telling Git that .md files are markdown makes the @@ context lines in git-diff show the section heading that contains the change, rather than just showing one additional line of the context before the change. For more information, see the section "Defining a custom hunk-header" in the gitattributes(5) man page. commit c914c44ccdbbda757ee43e5d4c777abf24391a1a Author: Alex Martini <[email protected]> Date: Tue Nov 29 15:16:28 2022 -0800 Clean up formatting of term-definition lists. No changes to rendered HTML or Render JSON output. Although there is a difference in CommonMark syntax between loose and tight lists, which this commit changes because it adds blank lines between the list items, DocC doesn't treat them differently. https://spec.commonmark.org/0.30/#loose commit 56b69e38e3a797563f33be9c3901c4d94214aa91 Merge: 5a3657d9 46dbe1ef Author: Alex Martini <[email protected]> Date: Mon Nov 28 11:00:42 2022 -0800 Track 'main' to resolve merge conflict. Conflicts: Sources/TSPL/TSPL.docc/GuidedTour/GuidedTour.md Kept the changes from 'main' and re-removed stray whitespace. commit 36a028766557fc4c1726eee892301062c087b459 Author: Alex Martini <[email protected]> Date: Thu Nov 17 15:00:05 2022 -0800 Disable the "Overview" heading. Fixes rdar://102485889 commit c37464a85cbf97ccacb729acf53ede52d9048bb3 Author: Alex Martini <[email protected]> Date: Thu Nov 17 14:27:01 2022 -0800 Put back the first part's title. This looks like it was changed by accident during the conversion process from RST to markdown. commit ebdff46cbb517e1d0f981b0ba9587f4d99ffbc68 Author: Alex Martini <[email protected]> Date: Thu Nov 17 14:13:28 2022 -0800 Fix indentation; remove repetitive comments. commit 837ead3d953ff639c7604b3a4907b8f70938e9be Merge: acc3cfc3 f055a202 Author: Alex Martini <[email protected]> Date: Thu Nov 17 14:05:57 2022 -0800 Track 'main'. commit acc3cfc3064661c280b736789ecfba4f39a6d4dd Author: Alex Martini <[email protected]> Date: Thu Nov 17 10:26:31 2022 -0800 Iterate on the GitHub Pages script. - Simplify the logic to move to the repo's top level. - Save the current commit before building, instead of after. - Don't assume the remote is named "origin". - Use pushd/popd to change directories and then change back. - Various rewording and revision to comments. - Remove an (accidental?) early-exit, so the temporary worktree actually gets deleted at the end. commit 46dbe1ef27f9361f827607fabd990fb215938d67 Merge: f055a202 a5e420df Author: Alex Martini <[email protected]> Date: Thu Nov 17 13:10:03 2022 -0800 Fix two wrong words in the style guide (#69) commit a5e420df6ff05fe670c3ca27d75668ae6c8a6f01 Author: Alex Martini <[email protected]> Date: Thu Nov 17 11:04:55 2022 -0800 Fix typo: here -> there. commit 666349ecd5347396af61f112b50e39dde0abe7b5 Author: Alex Martini <[email protected]> Date: Thu Nov 17 11:04:43 2022 -0800 The book's source is now markdown. commit a0633e8e15db59ef517044f13785811f1b2b8c44 Author: Alex Martini <[email protected]> Date: Wed Nov 16 17:08:22 2022 -0800 Revert changes to the top-level markdown file. This isn't needed when building with current DocC. This partially reverts commit 0f38730cba908d0dc44523ecd7991ce930ce5a2c. commit d2174d8f1a5702a6060d021e7f1a6cb025dc3490 Author: Alex Martini <[email protected]> Date: Wed Nov 16 17:05:38 2022 -0800 Link to the Git repo directly; adjust wording. commit 632d2b71860b40dbb1dee70d1e93c59e746408aa Author: Alex Martini <[email protected]> Date: Tue Nov 15 10:53:59 2022 -0800 Link to the more specific forums area. Co-authored-by: Franklin Schrans <[email protected]> commit e79dbc500b8cd6f9fcc3b24eab89f0b37b39b49b Author: Alex Martini <[email protected]> Date: Mon Nov 7 11:54:33 2022 -0800 Add a script to help find screenshot changes. This script is a minor modification of a script I wrote in October 2017, which was part of the internal Git repository prior to open sourcing. I'm not preserving its commit history because that script doesn't have any history of interest -- just adding comments and examples over time. commit d418fafd7208740a723e04d13a5e514d3fa11849 Author: Alex Martini <[email protected]> Date: Mon Nov 7 11:47:53 2022 -0800 Use single-line comments, for more accurate search. commit e1e3df700a21e4fa5ff5602916b3a631cc8f276a Author: Alex Martini <[email protected]> Date: Fri Nov 4 13:35:15 2022 -0700 Use the current name of Apple Books in comments. This was formerly the iBooks Store, but the name changed several years ago. Apple Style Guide entry for "Book Store" says: In most cases, simply use Apple Books to refer to the service that lets users purchase, download, and read ebooks. If you need to differentiate the store from the app, you can use the Book Store, the store in Apple Books, or the Book Store in Apple Books. https://support.apple.com/guide/applestyleguide/b-apsg1a3a0436/web commit f055a202af9335d0b1a3ffe4ada75ad9ef39ba2e Merge: c9762486 01323af4 Author: Alex Martini <[email protected]> Date: Mon Nov 14 12:00:57 2022 -0800 Fix straggler comment syntax and blank lines (#62) Change some places that got didn't get fixed by PR #60 and PR #50. commit c9762486f28774e2105bdee86e11d3caa2416c97 Merge: b20a23e3 40fbff94 Author: Alex Martini <[email protected]> Date: Mon Nov 14 11:59:50 2022 -0800 Fix the tour's example for empty array & dictionary syntax (#56) These examples used to contrast the literal [] and initializer [String]() syntax, but we revised the book to remove the latter as part of a style update. https://github.com/apple/swift-book/commit/639bcc61dde12b16cb50fcd81885292bfd6a2883 Fixes rdar://101867425 commit d22ece389ba18a5c9fe2dd9630ee44d264e10c71 Author: Alex Martini <[email protected]> Date: Mon Nov 14 11:55:07 2022 -0800 Revise and reframe guidance for commit messages. commit ae971f9a7c6085f363a29a45a444226803c3387f Author: Alex Martini <[email protected]> Date: Mon Nov 14 11:40:10 2022 -0800 For brevity, drop suggestions for naming branches. Because branch names don't become part of the Git history, the branch names don't really matter. If the branch is named 'potato' but has descriptive commit messages and a pull request that gives reviewers context for the changes, that's not ideal but doesn't really cause that much of a problem. commit f0505d7d70ef97ac2442f41e0b0c5ad9d67c7339 Author: Alex Martini <[email protected]> Date: Mon Nov 14 11:12:55 2022 -0800 Remove a limitation on @objc protocol adoption. For example, this works even though the C class isn't marked @objc, isn't a subclass of NSObject, and isn't a subclass of an @objc class: import Foundation @objc protocol P {} class C: P {} Co-authored-by: Slava Pestov <[email protected]> commit b3bc05677493a0d1d24c44f9f974b976a344123b Author: Alex Martini <[email protected]> Date: Fri Nov 11 16:39:23 2022 -0800 Expand contribution guidelines, for larger changes. commit 40fbff94a6695dd86a499d69269452998ff356ba Merge: 5dab09ba b20a23e3 Author: Alex Martini <[email protected]> Date: Wed Nov 9 11:18:02 2022 -0800 Track 'main' to resolve a merge conflict. commit 5a3657d9d2115f2c0f525e5e0d6fd3f76aaccf07 Author: Alex Martini <[email protected]> Date: Mon Nov 7 16:13:26 2022 -0800 Remove trailing whitespace. Most of this came from places where the RST to markdown export process included indentation on blank lines in comments. After this commit, I confirmed that there's no remaining trailing whitespace by running: git grep -I ' $' Confirmed that there's no change in the rendered content. commit 01323af47fbc68a4e0d64dcc96bdd49a23013b4b Author: Alex Martini <[email protected]> Date: Mon Nov 7 16:18:41 2022 -0800 Remove straggler double-blank lines. commit 0f38730cba908d0dc44523ecd7991ce930ce5a2c Author: Kyle Murray <[email protected]> Date: Mon Nov 7 10:37:22 2022 -0500 Update gh-pages script and adjust HTML header. commit 5dab09bab2e439ac7bc2e762de76cde79d60578f Author: Alex Martini <[email protected]> Date: Fri Nov 4 14:35:07 2022 -0700 Take a different approach at the rewrite. With the previous approach, I was trying to avoid putting prose punctuation text to code voice punctuation, but that isn't actually as much risk of confusion as I expected. The "for example" about functions and variables is a detail that was needed in the old form, to explain when you can use the literal syntax, but isn't really needed now. Incorporates feedback from @krilnon. commit fd93e28848306bde869e45b56e543c0f195a7d84 Author: Alex Martini <[email protected]> Date: Fri Nov 4 14:23:06 2022 -0700 Fix up stragglers in the summary of the grammar. This chapter didn't exist on 'main' when the branch for commit b20a23e38ce8bc47ed653af3ad4b8f3d4879bd6f cleaned up runs of newlines, or when the branch for commit fd82527e1da695c196d5fc7475c533a9e931e8e5 changed from @Comment{ } to the <!-- --> syntax. commit 0f1599fd73d7df63a52dd74acf338446149b1c46 Author: Alex Martini <[email protected]> Date: Fri Nov 4 13:42:56 2022 -0700 Replace straggler @Comment syntax. One change in the HTML output -- there's no longer a stray } in Generics just before the Generic Subscripts heading. These got skipped over, but should have been part of commit fd82527e1da695c196d5fc7475c533a9e931e8e5 for PR #50. commit b20a23e38ce8bc47ed653af3ad4b8f3d4879bd6f Merge: 064abd17 77860525 Author: Alex Martini <[email protected]> Date: Fri Nov 4 14:16:42 2022 -0700 Collapse adjacent blank lines. (#60) Most of these runs of blank lines were added as a byproduct of the RST-to-markdown export. In a few places, these were an intentional part of authoring — for example, most of the reference has two blank lines before a section heading — which we could put back if desired. I think there is an argument to be made for the consistency of single blank lines, from an authoring perspective. I don't remember the full rationale from 2014 when Brian and I used the double blanks in the reference. Verified changes are only in blank lines with `git diff --ignore-blank-lines`, which has no output. Also confirmed that there are no changes in the HTML output from DocC. commit 778605256849dc34abf9e8e643dacedbebb7eaea Merge: 6fd02f8e 064abd17 Author: Alex Martini <[email protected]> Date: Fri Nov 4 14:16:07 2022 -0700 Merge branch 'main' into blank_lines commit 064abd17b0958d93997cca2c3549da12a33b74d4 Merge: fd82527e d73aab87 Author: Alex Martini <[email protected]> Date: Fri Nov 4 14:14:45 2022 -0700 Convert the formal grammar for DocC compatibility (#55) DocC doesn't support subscripts, so instead of using subscript "opt" for optionality, use a postfix question mark. Alternatives considered included text like "OPT" or "(opt)" and Unicode subscript characters. The former are hard to read and interrupt the flow of the grammar. The latter render poorly because they're intended for phonetic annotation, so the different letters don't share a baseline in many fonts. It's a known issue that DocC doesn't support hard breaks [1], so insert a paragraph break between each grammar production for now. I added a "double" paragraph break between groups, where there used to be a blank line, to preserve that information for when DocC adds hard break support in the future. 1: https://github.com/apple/swift-docc/issues/412 Fixes https://github.com/apple/swift-book/issues/3 Fixes rdar://101001280 commit d73aab8743e38f96356d8973ea7d55b6cfbf8a28 Author: Alex Martini <[email protected]> Date: Fri Nov 4 14:06:22 2022 -0700 Add a reminder that the summary is updated by hand. Incorporates feedback from @krilnon and @bjlanier. commit 5409b124e97172bcae7cb984434f2e210d00ffb3 Author: Alex Martini <[email protected]> Date: Fri Nov 4 13:55:18 2022 -0700 Restore text accidentally lost in a rebase. commit 1cb1ee64f19e3f5add597430dc910bedb918a760 Author: Alex Martini <[email protected]> Date: Fri Nov 4 13:38:24 2022 -0700 Don't re-introduce @Comment syntax. Changed this syntax in https://github.com/apple/swift-book/pull/50 commit ee49b93bc23ca66c712ebf579534d768e2b3b93b Author: Alex Martini <[email protected]> Date: Wed Nov 2 11:27:40 2022 -0700 Fix the empty array/dict example. These two examples used to contrast the initializer and literal syntax. When we moved all of TSPL away from initializer syntax [1], that contrast was lost, resulting in a confusing example. 1: 639bcc61dde12b16cb50fcd81885292bfd6a2883 commit 6fd02f8eccf8836242fbd484209a6822296cf21e Author: Alex Martini <[email protected]> Date: Mon Oct 24 12:29:11 2022 -0700 Collapse adjacent blank lines. Automated clean-up with the following commands in Vim: :set autowriteall :bufdo 0,/^# / g/^$/d :bufdo %! cat -s Verified changes are only in blank lines with 'git diff --ignore-blank-lines', which has no output. Also confirmed no changes in the HTML output from DocC. commit fd82527e1da695c196d5fc7475c533a9e931e8e5 Merge: 3201fc15 4fef873b Author: Alex Martini <[email protected]> Date: Thu Nov 3 17:08:27 2022 -0700 Replace @Comment blocks with HTML comments (#50) This reduces the places where content in the comment causes DocC to silently mis-parse the comment and content after it. The markdown parser for DocC first parses plain markdown syntax, and then identifies places where the `@Comment { }` syntax delimits blocks. That means it tries to parse the content of a comment as markdown first, and then later it gets turned into a comment. The parsing of HTML style comments happens as part of the first stage, which makes it less fragile. Using the DocC syntax for comments, a lot of the issues seem to come from `}` appearing in commented-out in code listings, or from other places where part of the comment is being interpreted as markdown and preventing the later DocC parsing pass from treating that content as a comment, or in some causes causing content after it to be missing. Using the HTML comment syntax, the `-->` arrow used in comment-out formal grammar conflicts with the end-of-comment marker, which I worked around by changing them to a `->` arrow. We can probably delete most or all of the commented-out formal grammar blocks, which seem to date back to the original drafting of the book's grammar. Some of the comment-parsing issues appear to be related to a known issue in Swift-Markdown: https://github.com/apple/swift-markdown/issues/84 commit 3201fc152a05654e9199ae4c79e09f9556c1f0b2 Merge: aa3829e8 663eee38 Author: Alex Martini <[email protected]> Date: Thu Nov 3 17:07:07 2022 -0700 Remove title heading and automatic see-also section (#46) The book's chapters are divided into three parts: Welcome to Swift, Language Guide, and Language Reference. As a result, the automatically generated See Also sections at the end of each chapter are fairly distracting (and obviated somewhat by DocC's new sidebar). The title heading is unnecesary in the context of a book, because all pages are the same kind of content (a chapter), unlike documentation for a framework or module that includes various types of API reference and articles. Fixes #6 Fixes rdar://101885438 commit aa3829e8a080ec595351d0b60a5ed54f1f9fb671 Merge: e88458f6 73cb5ce1 Author: Alex Martini <[email protected]> Date: Mon Oct 31 11:43:32 2022 -0700 Add chapter abstracts (#47) Fixes #1 commit 4039ee0ef4e69d2cf6460861f9444a499503db16 Author: Alex Martini <[email protected]> Date: Fri Oct 28 12:33:05 2022 -0700 Convert grammar to DocC flavored markdown. This is the same content that the previous commit added to the summary chapter, copy/pasted throughout the other chapters it the reference. commit 96ffcb66fcd5512430cdafe3220e1ce75b7ad7fe Author: Alex Martini <[email protected]> Date: Fri Oct 28 10:55:16 2022 -0700 Remove trailing > lines at end of grammar boxes. commit cb65b420749d86ad92dfbfc100290937eeeb0c34 Author: Alex Martini <[email protected]> Date: Thu Oct 27 11:23:42 2022 -0700 Add a summary of the grammar, using the new format. commit dd6c23e43cd575c9152fef1e8345385192d4f6df Author: Alex Martini <[email protected]> Date: Thu Oct 27 11:22:39 2022 -0700 Remove temporary duplicates of the grammar. commit e88458f60c9e040b4acaa212bc254f5df6c2ceef Merge: a3482037 940f17d3 Author: Alex Martini <[email protected]> Date: Wed Oct 26 16:03:00 2022 -0700 Normalize indentation in code listings (#53) Some parts of the book were written before Swift style was standardized for Swift 1. A bunch of code listings use 3 space indentation instead of 4 space indentation. There are also some `switch` statements whose cases are indented, following an older C-like style. In Swift, a case doesn't start a scope, so we write it at the same level of indentation. Under the legacy Sphinx-based publication pipeline, this wasn't an issue: The publication process used SourceKit to add syntax highlighting, which also reindented the code listings, so the published version matched Swift style. Because DocC preserves indentation, we needed to normalize these in source. Fixes https://github.com/apple/swift-book/issues/43 Fixes rdar://96988058 commit a348203722e15bec6023454db900fdd6316dd8dd Merge: 01bf9fbe 45717bf1 Author: Alex Martini <[email protected]> Date: Tue Oct 25 10:42:02 2022 -0700 Mark "syntax outline" code listings as Swift (#44) Without any language in the markdown, they don't get syntax highlighting. commit 01bf9fbee5381be5644682bb35c5fc8176f8e394 Merge: a3a8d5f4 140ce4ab Author: Alex Martini <[email protected]> Date: Tue Oct 25 10:35:44 2022 -0700 Add inits and subscripts to the underscore rule. (#51) Exported from the RST version, where this old branch was reviewed by Steve Canon <[email protected]> on Aug 30 and merged Oct 5. commit a3a8d5f4bb21c63fc56cc7ac550984c98d75987d Merge: 5e15c7b0 5e9a270a Author: Alex Martini <[email protected]> Date: Tue Oct 25 10:35:15 2022 -0700 Fix typo: smallTriange -> smallTriangle (#52) commit 940f17d35c0f65884927db36631ae81ffe80d129 Author: Alex Martini <[email protected]> Date: Mon Oct 24 20:34:13 2022 -0700 Normalize indentation of switch statements. commit a130dfcd8ad50390dc2ee510059cfb0a0abf78eb Author: Alex Martini <[email protected]> Date: Mon Oct 24 20:17:57 2022 -0700 Manually correct some incorrect bulk changes. commit 28a4aafbf9dd153fe96473e9b08c885a32cd7fc1 Author: Alex Martini <[email protected]> Date: Mon Oct 24 20:12:40 2022 -0700 Bulk replace 3 -> 4 space indents. Used a sed script to make the changes: % cat indent.sed /```swift$/,/```/ s/^ \([^ ]\)/ \1/g /```swift$/,/```/ s/^ \([^ ]\)/ \1/g /```swift$/,/```/ s/^ \([^ ]\)/ \1/g /```swift$/,/```/ s/^ \([^ ]\)/ \1/g /```swift$/,/```/ s/^ \([^ ]\)/ \1/g Replacing the longer indents first reduces false positives where three 3-space indents gets turned into three 4-space indents, which then looks like four 3-space indents and gets turned into four 4-space indents. However, still will need to do a manual pass to back out places where the 12 leading spaces were actually three 4s not four 3s. Applied it to every file: % for f in **.md do sed -f indent.sed $f > out.tmp rm $f mv out.tmp $f done Confirmed the only changes are spaces via 'git diff --ignore-space-change' which has no output. commit 5e9a270a107181daad6dcfcc71a44e172b9bdfb1 Author: Paul Brewczynski <[email protected]> Date: Mon Oct 24 17:09:22 2022 +0200 Fixed typo smallTriange -> smallTriangle commit 140ce4abc5864b5584dccae5c678d0ce7bb9bb8a Author: Alex Martini <[email protected]> Date: Fri Aug 26 15:51:52 2022 -0700 Add inits and subscripts to the underscore rule. Exported from the RST version, where this old branch was reviewed by Steve Canon <[email protected]> on Aug 30 and merged Oct 5: Pull request #122: Add inits and subscripts to the underscore rule. Merge in DP/swift-book from underscore_arg_label to develop commit 73cb5ce18ae9e629706d539f1276b082ff57e4ac Author: Alex Martini <[email protected]> Date: Tue Oct 18 10:18:49 2022 -0700 Incorporate additional edit from Joni. rdar://101052433 commit 4fef873b868b054200ae6721cb1e9ed2592abc58 Author: Alex Martini <[email protected]> Date: Mon Oct 17 18:34:14 2022 -0700 Move comments outside note boxes. The RST-to-markdown exporter had some special cases and some issues here, because RST and DocC-flavored markdown have different rules around what block level constructs can nest. Avoiding the nesting is the best option, when that's feasible. commit 50956e2816e9637797503eeace14216764f2c826 Author: Alex Martini <[email protected]> Date: Mon Oct 17 18:16:12 2022 -0700 Correct a markup change. Fixes mistakes from 8e84be0fc4af97040f074f7be9980a41f0c8e871. commit 8ae0b5bf74ea5b60a46193d1739b9d0a998a0794 Author: Alex Martini <[email protected]> Date: Mon Oct 17 18:09:25 2022 -0700 Omit arrows in commented-out prose/grammar. Writing the arrow as --> like usual would end the HTML comment. commit ff3663b4332ff9ee6875670f1d5baa4e98cba121 Author: Alex Martini <[email protected]> Date: Mon Oct 17 17:51:05 2022 -0700 Avoid @ at the start of comment lines. This works around a bug in DocC. https://github.com/apple/swift-docc/issues/409 commit 45717bf1c008fec954b358948584619b5eaf55d5 Author: Alex Martini <[email protected]> Date: Mon Oct 17 13:06:53 2022 -0700 Mark remaining syntax outlines as Swift code. commit 33d5aea8a863650b38aed1b49b7e385a94a77b10 Author: Alex Martini <[email protected]> Date: Fri Oct 14 17:08:22 2022 -0700 Rewrite for clarity. When written as "avoid conflicting" or "avoid conflicts", the reader can misread "conflict" as as verb, and then have to backtrack to re-read it as a noun. Applying an operator is a way to access or assign a value, so it doesn't need to be separate. This phrasing avoids the awkward non-parallelism in the "X and Y, and Z" construct. commit 5fc2b3692a11323a49cd123b067721c1108a1167 Author: Alex Martini <[email protected]> Date: Fri Oct 14 15:30:58 2022 -0700 Omit comma when both verbs share a subject. Co-authored-by: Chuck Toporek <[email protected]> commit c2fc6a4b1341f48dd10a769989c04c85846d33d4 Author: Alex Martini <[email protected]> Date: Fri Oct 14 14:16:53 2022 -0700 Incorporate suggestions from Kyle. Co-authored-by: Kyle Murray <[email protected]> commit 9bd9101bf885a5255adda243bba71f9339d7e0ef Author: Alex Martini <[email protected]> Date: Fri Oct 14 13:09:05 2022 -0700 Incorporate edits from Joni. rdar://101052433 commit 5e15c7b01440cfe7e2e1d78b6d6bf8250f57cbfd Merge: 84cb927b 8df496c3 Author: Alex Martini <[email protected]> Date: Fri Oct 14 12:58:36 2022 -0700 Add templates for PRs and issues (#29) I based these templates of of what Swift and Swift-DocC use. For now, I'm leaving blank issues enabled to cover things that don't fall under either template, like adopting new features added to DocC or blockers for publication to Swift.org from this repository. In the future, when we publish from this version, I'd expect us to add a specific template for updating the docs after a Swift Evolution proposal is accepted. commit f86a62d1b02a5973f3ded9ad1092378ff6492a02 Author: Alex Martini <[email protected]> Date: Thu Oct 13 16:19:49 2022 -0700 Style the description, like we do for italics. commit 8e84be0fc4af97040f074f7be9980a41f0c8e871 Author: Alex Martini <[email protected]> Date: Thu Oct 13 11:45:09 2022 -0700 Convert to HTML comment blocks. commit 4ec1ae067f86a705eedec8dcd09a40ea3cd82cc3 Author: Alex Martini <[email protected]> Date: Wed Oct 12 15:39:31 2022 -0700 Mock up a representative subset of the grammar. commit dd3dd27b7169d4a62c636a9c0a6946a41b612cf3 Author: Alex Martini <[email protected]> Date: Wed Oct 12 11:43:15 2022 -0700 Mock up grammar in DocC's flavor of markdown. commit 3d49b27f1183e2d2e16c63e9a98051dc3f54ff44 Author: Alex Martini <[email protected]> Date: Tue Oct 11 14:36:41 2022 -0700 Move abstracts into place. Note that there isn't currently a Summary of the Grammar chapter, so that abstract got lost. We can come back to this commit later. commit db0e65d1c40dd1f5776954b8ca80c5ad28b81227 Author: Alex Martini <[email protected]> Date: Tue Oct 11 13:13:46 2022 -0700 Finish first pass at chapter abstracts. commit 9f609ceb6009b32e2cfcb0077f897172e3c3d6a5 Author: Alex Martini <[email protected]> Date: Mon Oct 10 16:18:00 2022 -0700 Add some more abstracts. commit 4f35cea4f4fde902755550289628912277a86884 Author: Alex Martini <[email protected]> Date: Fri Oct 7 16:37:30 2022 -0700 Start sketching chapter abstracts in a temp file. commit 4c0e498a49532926b70a5488228148e556aa2ec1 Author: Alex Martini <[email protected]> Date: Wed Oct 5 16:55:17 2022 -0700 Mark all missing abstracts. commit 84cb927b803480df07546af97779b24956e743d7 Merge: d6862812 a4a60b4d Author: Alex Martini <[email protected]> Date: Tue Oct 11 10:19:57 2022 -0700 Fix syntax in concurrency example (#45) commit 8df496c3b1fa1ee840f7227da15ce4cddd309b36 Author: Alex Martini <[email protected]> Date: Tue Oct 11 10:12:16 2022 -0700 Match project name in link. Co-authored-by: Franklin Schrans <[email protected]> commit 7dd66dd5c89ed123671e481daaf4301a499a2aa3 Author: Alex Martini <[email protected]> Date: Mon Oct 10 15:59:07 2022 -0700 Separate the forum links for docs and DocC. Incorporates discussion with @franklinsch. commit 33e13c9e35ae44fa881e413aedb5a134be44fd43 Author: Alex Martini <[email protected]> Date: Mon Oct 10 15:51:02 2022 -0700 "Bug" is too focused on code or program behavior. Incorporates feedback from @franklinsch and @sofiaromorales. commit 663eee387f9711814d8c4dd92b9123a336cf56e4 Author: Alex Martini <[email protected]> Date: Mon Oct 10 14:04:57 2022 -0700 Use the final syntax for global options. commit a4a60b4d20aec7148b87f8ea488b3c3ca22bf53e Author: Alex Martini <[email protected]> Date: Mon Oct 10 13:35:28 2022 -0700 Match function names across example. Co-authored-by: Kyle Murray <[email protected]> commit 8859935ae8ceab517a54ccf22a3b73b522b13619 Author: wody-d <[email protected]> Date: Tue Oct 11 04:32:42 2022 +0900 Update code snippet to swift commit d9995a7934e4c9ad47d920cd4584e7507325cf1a Author: wody-d <[email protected]> Date: Tue Oct 11 04:15:25 2022 +0900 Fix swift syntax in concurrency page commit 9b80ac514ec77452f11bb4791f6340b5ec106ff0 Author: Kyle <[email protected]> Date: Sun Sep 25 10:36:00 2022 +0800 Update code snippest to Swift commit 4f965c1ecb872023daf2da3be5270253190deb9e Author: Kyle <[email protected]> Date: Sun Sep 25 10:35:42 2022 +0800 Update gitignore commit d686281272c0a198bd00edd883797afe320d5227 Merge: a10b3634 97bbd306 Author: Alex Martini <[email protected]> Date: Wed Oct 5 11:02:19 2022 -0700 Update intro sentence in The Basics (#14) commit a10b363442ee69006e7b6d2d2c571ca5a563cd34 Merge: 4f6dc15a 467d540b Author: Evan Wilde <[email protected]> Date: Tue Oct 4 16:29:19 2022 -0700 Include example of defer lexical scoping (#30) This patch adds an example of how the defer statement is lexically scoped and will execute at the end of the scope, not the end of a function. commit 1776ff52caaeaa9147cdf888abb3724b1c460af9 Author: Alex Martini <[email protected]> Date: Fri Sep 30 16:47:43 2022 -0700 Use the shorter spelling, enabled by the makefile. See also de171f47a45a8cbd137d81c0c9ba2ae881776348 commit 4f6dc15a66ff1bfcd8199daa616c1beeb132b326 Merge: de171f47 dde0c8bf Author: Alex Martini <[email protected]> Date: Fri Sep 30 15:44:17 2022 -0700 Add "await" to the list of keywords. (#38) Fixes #37 commit dde0c8bff4fc597d44d7b49e5d4e34cd00c2f2dd Author: Alex Martini <[email protected]> Date: Fri Sep 30 09:41:23 2022 -0700 Add "await" to the list of keywords. commit da32dad78fa48dd436c879c908627722d3c86aa9 Author: Alex Martini <[email protected]> Date: Wed Sep 28 14:24:55 2022 -0700 Disable see-also sections and title headings. commit a94eb0249cbe288a7abd33f3a0df0d8f754a2010 Author: Alex Martini <[email protected]> Date: Wed Sep 28 10:59:30 2022 -0700 Remove another step non-committers can't do. Incorporates feedback from Franklin Schrans <[email protected]>. commit 467d540be699fa021da5dd7601fe59db65998c30 Author: Alex Martini <[email protected]> Date: Wed Sep 28 10:48:21 2022 -0700 Minor wording adjustment. - Avoid using `defer` as a noun in the reference - Connect the code and its explanation commit de171f47a45a8cbd137d81c0c9ba2ae881776348 Merge: 7d096acd 5a8889e2 Author: Alex Martini <[email protected]> Date: Tue Sep 27 17:09:07 2022 -0700 Add a makefile (#28) I found myself using ZSH history search to remember the specific `docc` commands needed to start a preview server and to build a documentation archive (`.doccarchive` bundle). Another possible approach would be to create a build script, although a build script wouldn't be able to skip rebuilding when source files haven't changed. commit 5a8889e21faaf625fefbacda54d242142e211dab Author: Alex Martini <[email protected]> Date: Mon Sep 26 11:42:45 2022 -0700 Simplify the build command. Transformation for static hosting is enabled by default now, so no need to pass `--transform-for-static-hosting` explicitly. TSPL has only one target, so the plugin infers `--target TSPL`. Explicitly calling through `xcrun` is meaningful only on macOS with Xcode installed, and shouldn't change any behavior. Both the old and new command produce identical TSPL.doccarchive output, ignoring the order of keys in the JSON. Co-authored-by: Ethan Kusters <[email protected]> Co-authored-by: Franklin Schrans <[email protected]> commit 93b5be45e3eb97023c56be5252a28e30b623dd46 Author: Alex Martini <[email protected]> Date: Mon Sep 26 11:29:20 2022 -0700 Include images as prerequisites. An alternate approach would be to include everything in the TSPL.docc bundle: .../TSPL.doccarchive: Sources/TSPL/TSPL.docc/* .../TSPL.doccarchive: Sources/TSPL/TSPL.docc/*/* The approach that this commit takes is more specific than the alternative, and it encodes the conventions TSPL has around files and folders. The specific globs tell a contributor exactly what kind of file should be in each place, and avoids rebuilding if the modification date of a .DS_Store file or EmptyFile.swift is changed. However, we may find that this specificity limits our flexibility too much. Incorporates feedback from Franklin Schrans <[email protected]>. commit e0937d624272d6ba58a86c7f6fa3e8dcaf405d88 Author: Alex Martini <[email protected]> Date: Mon Sep 26 10:40:56 2022 -0700 Add missing period. Co-authored-by: Franklin Schrans <[email protected]> commit 7d096acd16439a87aa3f081ea94060e76582f49d Merge: e0fae515 89632162 Author: Alex Martini <[email protected]> Date: Thu Sep 22 11:39:36 2022 -0700 Rename images so they render properly at 2x scale. (#35) The renames update the image names so they follow DocC's rules for 2x images: https://developer.apple.com/documentation/docc/image Previously files were named like `someImage_2x.png`, now they're `[email protected]` so DocC picks up that it's a 2x image. Updates all the image references to remove suffixes. commit 896321629a428163a1e46a3f9041386a26663828 Author: Kyle Murray <[email protected]> Date: Thu Sep 22 11:56:36 2022 -0400 Rename images so they render properly at 2x scale. The renames update the image names so they follow DocC's rules for 2x images: https://developer.apple.com/documentation/docc/image Updates all the image references to remove suffixes. commit e0fae5151f64b37bee0b8ed7410d004e9e3b1a48 Merge: 1b4a4a87 23771862 Author: Alex Martini <[email protected]> Date: Mon Sep 19 22:46:14 2022 -0700 Remove optional bindings from repeat-while (#32) A repeat-while loop contains only an expression. That matches what is already in the grammar and the behavior of the compiler. This appears to be a copy-paste error from 'while' loops, which can contain an optional binding, and which was part of Swift first. commit c2d76bd1ff7ef888adb29d14bc039fd4717a1d8c Author: Alex Martini <[email protected]> Date: Mon Sep 19 15:55:29 2022 -0700 Use semantic line breaks. commit fb2bbba0dd9060c2a0fdc5a58e233f535ec7f2e9 Author: Evan Wilde <[email protected]> Date: Fri Sep 16 12:51:45 2022 -0700 Include example of defer lexical scoping This patch adds an example of how the defer statement is lexically scoped and will execute at the end of the scope, not the end of a function. commit 23771862417ef0685c683449a97752cb67ab1bbe Author: Danny Mösch <[email protected]> Date: Sat Sep 17 21:05:25 2022 +0200 Remove claim on possible optional bindings in repeat-while conditions commit 1b4a4a872daa02ca42dfa84f4b1c4f7018c42619 Merge: 1bd731cb 48df904c Author: Alex Martini <[email protected]> Date: Fri Sep 16 14:44:42 2022 -0700 Omit trailing "dot zero" in version number (#31) commit 48df904c698d726fb92683751fa72bba204d22e9 Author: Alex Martini <[email protected]> Date: Fri Sep 16 14:06:43 2022 -0700 Omit trailing "dot zero" in version number. Per Apple Style Guide entry for "version number": When referring to a major release number (such as macOS 10.14 or iOS 12), omit any trailing .0 unless it’s needed for clarity. https://support.apple.com/guide/applestyleguide/v-apsg51b3c806/web commit 1bd731cb15498afb14606170dd71124fb8b24c42 Merge: a3c664bc 2c9e2d38 Author: Alex Martini <[email protected]> Date: Fri Sep 16 14:01:49 2022 -0700 Update information about when concurrency is available (#27) Updated concurrency deployment target to reflect Xcode 13.2's support for concurrency back to the two earlier versions of the OSes. To keep changes minimal, and keep the paragraph clean and concise, this purposefully doesn't add wording about Xcode 13 and 13.1 only supporting macOS 12 and up, and Xcode 13.2 adding the backwards compatibility, nor any of the history of how that support was added. If someone wants to add wording to that effect that should probably be discussed separately and elsewhere. Fixes #21. commit 2d0541553703ec830bb9cb79be7a707e3972f984 Author: Alex Martini <[email protected]> Date: Fri Sep 16 13:20:48 2022 -0700 Use a more approachable syntax for ignored errors. Stopping the DocC preview produces a non-zero exit status [1], which is understood by make(1) as a failed build -- but in this case, it's expected and shouldn't cause make(1) to give up or report an error. The prefix dash ignores a non-zero exit from only the command that it marks, which is more specific and usually more correct. However, a prefix hyphen looks like a typo to those less familiar with this syntax in makefiles, and its meaning is difficult to look up. The special .IGNORE target causes make(1) to ignore all all non-zero exit from any of the commands in that target. In this case, it's very unlikely that 'make preview' would ever need to run more than this one command. 1: https://github.com/apple/swift-docc/issues/387 Co-authored-by: Kyle Murray <[email protected]> commit a3c664bc6f45d5f1cacaed3bc50de1df9083faa6 Merge: c93207b0 a4c4c43c Author: Alex Martini <[email protected]> Date: Thu Sep 15 13:11:42 2022 -0700 Add a .gitignore file (#12) commit c388ea27f8c58a28c253807906b11cc45bd76537 Author: Alex Martini <[email protected]> Date: Wed Sep 14 16:07:32 2022 -0700 Create templates for GitHub issues. commit a72b9446f5a4b07cd980a311067b60256bddcdca Author: Alex Martini <[email protected]> Date: Tue Sep 13 11:12:00 2022 -0700 Remove a step most people can't follow. Adding reviewers to a PR requires GitHub permissions, which most contributors won't have. commit bfb74145fb88c8e1ca7126c7c4fe12c5f42096a9 Author: Alex Martini <[email protected]> Date: Wed Aug 31 15:26:05 2022 -0700 Create a template for PRs. commit 2961152c95cefe9f1dbcde2356cc4b962f4fcff7 Author: Alex Martini <[email protected]> Date: Wed Aug 31 11:41:47 2022 -0700 Save long DocC commands in a makefile. commit a4c4c43cdb59cf17ce69c67b4653421c3ccbd51b Author: Alex Martini <[email protected]> Date: Wed Aug 31 11:46:09 2022 -0700 Iterate on what files to ignore. Not versioning the Package.resolved file ensures we're always using the latest version of the 'package' plug-in. DocC writes its output to .build. Both of these should match only at the top level. (Changes suggested by @franklinsch.) Finder uses .DS_Store files, so ignore those everywhere. commit 2c9e2d38480b5f98f25c7fe658b49e6db2d76786 Author: Reed Harston <[email protected]> Date: Mon Sep 12 19:38:59 2022 -0700 Changed the "concurrency requires" sentence back to 5.7 for now so a better wording can be discussed separately without holding back the deployment target fix. The book generally refers to Swift 5 as Swift 5.7, since that is the current version, so it also isn't entirely correct to put 5.5 in that sentence since the developer can't select 5.5 in Xcode, just 4, 4.2, or 5. commit f58c0d3d61e661450f24b4448cb1665f6c146be1 Author: Reed Harston <[email protected]> Date: Mon Sep 12 10:07:31 2022 -0700 Changed concurrency version back to 5.5 from 5.7. Updated concurrency deployment target to reflect Xcode 13.2's support for concurrency back to the two earlier versions of the OSes. commit c93207b088ee933480609204c58f5b9c811cce86 Merge: d0863fe2 ada13046 Author: Alex Martini <[email protected]> Date: Tue Sep 6 10:57:10 2022 -0700 Capitalize Fibonacci (#25) Fibonacci is a proper noun, so give it a capital letter. commit d0863fe23eab6445e9be2e988f5c7235688c77cd Merge: a4233029 409b29fd Author: Alex Martini <[email protected]> Date: Fri Sep 2 12:00:01 2022 -0700 Fix a hyperlink (#22) Replaced link text in the Readme file with a working link for direct access to the swift docs website. commit a423302960f95ff787aede05e77b3d21234e3b99 Merge: 39c74e61 f382e421 Author: Alex Martini <[email protected]> Date: Fri Sep 2 11:55:16 2022 -0700 Replace a hash that changed during open-sourcing. (#24) commit ada13046c490c954e748dd4cd636219057583cc7 Author: lotuspar <[email protected]> Date: Sat Sep 3 00:22:07 2022 +0800 Capitalize Fibonacci Small change; Fibonacci is a proper noun so capitalize it commit 409b29fd368d19285c73002d1fb0c5250df7fac6 Author: Saptarshi Sarkar <[email protected]> Date: Fri Sep 2 06:53:41 2022 +0530 Added link to the book itself commit f382e4216d9610ece62b08bbe618b36a9cc2f339 Author: Alex Martini <[email protected]> Date: Thu Sep 1 15:00:08 2022 -0700 Replace a hash that changed during open-sourcing. commit 39c74e615355764e3addad96b89de0bf6daa1568 Merge: 7e68e11d 62488937 Author: Alex Martini <[email protected]> Date: Thu Sep 1 13:53:09 2022 -0700 Fix typos (#23) Fix two typos. commit 62488937c94833fede3fc8ecb0e0d8150cfdccad Author: Benedict <[email protected]> Date: Thu Sep 1 22:27:23 2022 +0200 fix typos commit 6993c38b78552e1ec3c1d36f6ff62a66338ae987 Author: Saptarshi Sarkar <[email protected]> Date: Thu Sep 1 15:46:40 2022 +0530 Fixed a hyperlink Replaced link text in the Readme file with a working link for direct access to the swift docs website. commit 7e68e11d13d74a7210a783149877cfbbe26edcb8 Merge: 2502ff32 289a84bb Author: Alex Martini <[email protected]> Date: Wed Aug 31 16:34:06 2022 -0700 Fix typos (#11) Fix some typos commit 2502ff326fddcdd816f8bf3993dd8a2f09291c9b Merge: 82706c15 b67bc9a9 Author: Alex Martini <[email protected]> Date: Wed Aug 31 15:26:43 2022 -0700 Discuss markdown headings in the style guide. (#20) No content changes. Fixes https://github.com/apple/swift-book/issues/15 commit b67bc9a9cac57d8774a4d4ce272e6474bf0080c0 Author: Alex Martini <[email protected]> Date: Tue Aug 30 14:35:46 2022 -0700 Discuss markdown headings in the style guide. commit 82706c15fc7345df13a6c9af95acd8e7a7fdde0e Merge: c3fb1421 12ce5967 Author: Alex Martini <[email protected]> Date: Tue Aug 30 14:29:16 2022 -0700 Merge pull request #17 from tkrajacic/fix-backslash-space Remove `\ ` commit 97bbd306eae86f7205c97b8494d0a3ee0d2bd3bc Author: Alexander Cyon <[email protected]> Date: Tue Aug 30 22:00:45 2022 +0200 Update Sources/TSPL/TSPL.docc/LanguageGuide/TheBasics.md Make rewording more faiithful to original one, thx for suggestion @xwu! Co-authored-by: Xiaodi Wu <[email protected]> commit 12ce59679ca4a5727fda33a250dd27211ed7c68b Author: Thomas Krajacic <[email protected]> Date: Tue Aug 30 21:03:54 2022 +0200 Remove `\ ` Those seem to be an artefact of importing the content? commit c7bc78837d1064eee5b1081c830bb6207e504899 Author: Alexander Cyon <[email protected]> Date: Tue Aug 30 20:38:40 2022 +0200 Swift graduates from school. commit 289a84bb694cf64c0071d5a81cf54db502170b16 Author: Alexander Cyon <[email protected]> Date: Tue Aug 30 20:02:04 2022 +0200 Fix typos commit 3e6bff1eb10b92fe5876feda5a52b8b7d0392f7e Author: Alexander Cyon <[email protected]> Date: Tue Aug 30 19:50:02 2022 +0200 Add .gitignore commit c3fb14214a075e777084868abf59422acce89efb Author: Alex Martini <[email protected]> Date: Tue Aug 30 10:01:41 2022 -0700 Link to the Swift license. commit abb13071a926fb874af51c1d9dcb84299038d37c Author: Alex Martini <[email protected]> Date: Mon Aug 15 16:56:26 2022 -0700 Avoid a parser issue with @Comment in list item. Workaround for <rdar://98695544> commit a9415c50d459ada70f542f7f4b98c7238a432b72 Author: Alex Martini <[email protected]> Date: Mon Aug 15 15:04:40 2022 -0700 Combine adjacent comment blocks. This works around a markdown or DocC issue that was causing the "for delegate in delegates" example to appear in rendered output. commit 093f4630abcfbcc25c9f9f812cf2f930eb9bde2d Author: Alex Martini <[email protected]> Date: Mon Aug 15 14:38:18 2022 -0700 Move comment outside note. Semantically, the assertion that's in the comment is checking the prose in the note box. However, nesting @Comment inside a Note is invalid markdown. Workaround for <rdar://97460053> commit ee4f77f4aafca4bff7f203964c5b07b5e9d92314 Author: Alex Martini <[email protected]> Date: Mon Aug 15 14:36:38 2022 -0700 Add missing line break. Workaround for <rdar://97463190> commit a79e857abaa317228600491f6b69849162c6ba07 Author: RST to Markdown Conversion <> Date: Tue Aug 30 09:00:00 2022 -0700 Add footer with the license. commit e949fdbb7db88efd58e6e63fd938931ca3ee300a Author: RST to Markdown Conversion <> Date: Tue Aug 30 09:00:00 2022 -0700 Add supporting files used by DocC. commit 41db76915270670a3938ba7af33742410ad740a6 Author: RST to Markdown Conversion <> Date: Tue Aug 30 09:00:00 2022 -0700 Remove supporting files used by Sphinx. commit 96f0925407c6bd9eadd9d58d253bad3e1ef7a9f2 Author: RST to Markdown Conversion <> Date: Tue Aug 30 09:00:00 2022 -0700 Convert RST to markdown. commit 94646f9aa6ecd5a02a1670299d2a26663dfe7d02 Author: RST to Markdown Conversion <> Date: Tue Aug 30 09:00:00 2022 -0700 Rename and move files, for markdown conversion. commit c0150988c363ea1820515b49faba0d45ecee9a55 Merge: d4016f90 04041c1a Author: Kyle Murray <[email protected]> Date: Mon Aug 29 14:33:12 2022 -0700 Pull request #120: Add a code of conduct and contributing files. Merge in swift-book from kyle/code-of-conduct-and-contributing to develop. commit 04041c1abf382524f527724f9bd96f2002edeafb Author: Kyle Murray <[email protected]> Date: Mon Aug 29 17:29:54 2022 -0400 Use an ordered list in CONTRIBUTING. commit 7717a676f10cabebcc8bbe138908c935e1fe9967 Author: Kyle Murray <[email protected]> Date: Mon Aug 29 17:27:15 2022 -0400 Incorporate feedback on CONTRIBUTING from Alex. commit 758a4197a49111002b13b7c2c55461932fc5e046 Author: Kyle Murray <[email protected]> Date: Mon Aug 29 16:23:20 2022 -0400 Cross-reference CONTRIBUTING in README. commit b21f92a69c94db4fd7b675889b283a8a0b62da21 Author: Kyle Murray <[email protected]> Date: Mon Aug 29 16:20:43 2022 -0400 Update CI request phrasing. commit 86596fb85004ac590c13395988289ca3173a6bfe Author: Kyle Murray <[email protected]> Date: Mon Aug 29 16:18:04 2022 -0400 Fix typo in Alex's GH username. commit ec8fd818bda345f267b27a5a9b3f99cad466e9c0 Author: Kyle Murray <[email protected]> Date: Mon Aug 29 16:16:31 2022 -0400 Rough draft for CONTRIBUTING document. commit 37f615b956bf90d6d728c279ffbc06987f8af521 Author: Kyle Murray <[email protected]> Date: Mon Aug 29 15:07:51 2022 -0400 Add a code of conduct file. commit d4016f900ac4b44f022f62eda78ecf8f7fde8265 Author: Alex Martini <[email protected]> Date: Fri Aug 26 11:53:51 2022 -0700 Fix typo in comments. commit ace0413bd4f3f298f6542b3670d88af8150929fd Author: Alex Martini <[email protected]> Date: Wed Aug 24 11:34:05 2022 -0700 Fix text in figures. Assets from rdar://98531037 commit 8ab6e61eada279682b1b5865e2f584f2a83ad419 Author: Alex Martini <[email protected]> Date: Fri Aug 19 14:32:23 2022 -0700 Update expected error message. As of Swift 5.7 (swiftlang-5.7.0.123.8) the syntax in c3 produces only one error message, now that multi-statement closures can infer their return type (SE-0326). commit a12adb75b1f0ccfc14f7c50c68fa2671a72c6600 Author: Alex Martini <[email protected]> Date: Wed Aug 17 13:50:04 2022 -0700 Enable markdown for GitHub language detection. Following the approach used for the Swift Evolution repository: https://github.com/apple/swift-evolution/pull/1074 Co-authored-by: Kyle Murray <[email protected]> commit 3eb77025564b9a8a447ca071a7eb4f40d6a739b3 Author: Alex Martini <[email protected]> Date: Wed Aug 17 13:17:06 2022 -0700 Elevate framing from the forum post. Co-authored-by: Brian Lanier <[email protected]> commit 15bd729d3a316dc27c6dd29a32dd1cc03ac3da36 Merge: 9914875e 52e98ec8 Author: Alex Martini <[email protected]> Date: Fri Aug 12 14:39:09 2022 -0700 Pull request #118: Add an README for the open-source version Merge in DP/swift-book from oss_readme_96701996 to develop commit 52e98ec87b37821a1ecfec147267724092a3ad53 Author: Alex Martini <[email protected]> Date: Fri Aug 12 14:25:06 2022 -0700 Incorporate edits from Rob. Co-authored-by: Rob Rhyne II <[email protected]> commit c05e9d3aea81c9ecee1b6ad59c55d270d44f6d1e Author: Kyle Murray <[email protected]> Date: Fri Aug 12 13:31:34 2022 -0400 Simplify the build instructions for SwiftPM previewing. commit 2d938e5cc83bc0511d7dce9aee7d768955fd4e36 Author: Alex Martini <[email protected]> Date: Thu Aug 11 15:57:08 2022 -0700 Mention building with Xcode. Co-authored-by: Tim Triemstra <[email protected]> commit eddc57b265a1d451f167bd3e5de1fbddc764db6c Author: Alex Martini <[email protected]> Date: Thu Aug 11 11:24:11 2022 -0700 Revert "Applied suggestion" The legacy toolchain using RST and Sphinx is in current use, and will continue to be how we publish TSPL, even when the open-source version goes live. There's separate work to extend DocC, so that we can use that new toolchain in the near future. This reverts commit 9e13fb88269eea1a3a9c8befc2d8e3009f084982. commit 41d6e8dbd118a6abf2741b903f865ac7e48de319 Author: Alex Martini <[email protected]> Date: Thu Aug 11 11:23:34 2022 -0700 Reduce passive voice. Co-authored-by: Joni McNutt <[email protected]> commit 4f2831a15d45f9564189dbc4989dd8d96e9906bd Author: Alex Martini <[email protected]> Date: Wed Aug 10 14:46:46 2022 -0700 Fill in the forum link. For now, point to the DocC area, since the focus is on tooling. If needed, we can ask for a TSPL area on the forum in the future. commit 9914875ed2523710e749cc9ab4f1cd8843364dc5 Author: Alex Martini <[email protected]> Date: Wed Aug 10 10:47:00 2022 -0700 Remove Vim syntax highlighting workarounds. Even with the Vim configuration changes from the previous commit, these are still needed to prevent runaway syntax highlighting. But, since they won't be needed in the markdown version of the book, I'm deleting them too. Confirmed no difference in the HTML or [Tool S] XML output. commit 99392369c1d26d06f163cebe90d68ca4f4e6cea9 Author: Alex Martini <[email protected]> Date: Wed Aug 10 10:41:30 2022 -0700 Remove unneeded Vim syntax highlighting workarounds. These don't make any difference when you tell Vim to syntax highlight our custom directives as code listings by adding the following to your .vimrc file (or the ftplugin file for RST): " Specific kinds of code listings used by TSPL. autocmd Syntax rst syntax region rstCodeBlock start='^.. testcode::' skip='^\s*$' end='^\(\z1\s\+\)\@!' autocmd Syntax rst syntax region rstCodeBlock start='^.. assertion::' skip='^\s*$' end='^\(\z1\s\+\)\@!' autocmd Syntax rst syntax region rstCodeBlock start='^.. syntax-outline::' skip='^\s*$' end='^\(\z1\s\+\)\@!' Confirmed no difference in the HTML or [Tool S] XML output. commit e17f5043c6fe4d968a3fffe2b94814a042aa1bb4 Author: Kyle Murray <[email protected]> Date: Mon Aug 1 15:31:46 2022 -0400 Incorporate changes to readme from editorial. commit 0248e1bc6d9c65c62ab8dc988ac1fff17e418253 Author: Joni McNutt <[email protected]> Date: Mon Aug 1 12:28:05 2022 -0700 Applied suggestion commit 6303a31d0ea0950a8b0d9d754ed63760053e7071 Author: Joni McNutt <[email protected]> Date: Mon Aug 1 12:27:46 2022 -0700 Applied suggestion commit 9a363cd855526e8eaf637352556a6b366f9458f0 Author: Joni McNutt <[email protected]> Date: Mon Aug 1 12:27:35 2022 -0700 Applied suggestion commit 9e13fb88269eea1a3a9c8befc2d8e3009f084982 Author: Joni McNutt <[email protected]> Date: Mon Aug 1 12:27:20 2022 -0700 Applied suggestion commit 4d59ee4f7864d9eae044670cc69b75ba420a6768 Author: Joni McNutt <[email protected]> Date: Mon Aug 1 12:27:08 2022 -0700 Applied suggestion commit 72585eb8f598f9ecf216c4016b4d8952b20ee070 Author: Alex Martini <[email protected]> Date: Mon Jul 18 11:32:53 2022 -0700 Fix backwards curly quote. commit 169e890d46d95714af2df06a54336c72763e9455 Author: Alex Martini <[email protected]> Date: Mon Jul 18 11:24:21 2022 -0700 Incorporate feedback from Franklin. commit 3b981d05893a5d9a53842a44a7acef8533aad0c9 Author: Alex Martini <[email protected]> Date: Mon Jul 18 10:52:35 2022 -0700 Demote headings. commit 405b0dcc71ced2098ab0eb262e58cb4e1c1583a5 Author: Alex Martini <[email protected]> Date: Thu Jul 14 14:48:08 2022 -0700 Remove a comment that repeats the assert above it. commit bdbb1f031d8ef5…
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
This issue appears is input like the following:
The CommonMark definition of a code voice permits one or more backticks, which supports exactly this sort of scenario where a backtick needs to appear in code voice. Additionally, escaping via backslash isn't allowed in code voice.
The issue here is a collision with DocC's extended markup using double-backticks surround links to API symbols. Currently, building "The Swift Programming Language" with top-of-tree
docc, the output is correct but we get warnings like the following:Trying 3 or 4 backticks to start/end the code voice produces the same result.
rdar://116587933
The text was updated successfully, but these errors were encountered: