ascii-ipa:2.2.0

packages/preview/ascii-ipa/2.2.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog of `ascii-ipa`
+
+follows [semantic versioning](https://semver.org)
+
+## 2.2.0
+
+- X-SAMPA
+  - Added support for separator `-` (https://github.com/imatpot/typst-ascii-ipa/pull/5)
+  - Added support for [SAMPROSA](https://en.wikipedia.org/wiki/X-SAMPA#SAMPROSA) tone notation (https://github.com/imatpot/typst-ascii-ipa/pull/6)
+
+## 2.1.0
+
+- General
+  - Introduced `replace-raw` convenience `show`-rule
+- Conlang X-SAMPA (CXS)
+  - Added support
+
+## 2.0.0
+
+> [!CAUTION]
+> This release contains breaking changes
+
+- General
+  - **BREAKING:** Dropped support for `override-font` to avoid [`str`](https://typst.app/docs/reference/foundations/str/)/[`content`](https://typst.app/docs/reference/foundations/content/) ambiguity
+  - Added bracket & braces support for [precise, morphophonemic, indistinguishable, obscured, and transliterated](https://en.wikipedia.org/wiki/International_Phonetic_Alphabet#Brackets_and_transcription_delimiters) notations
+  - Added support for converting [`raw`](https://typst.app/docs/reference/text/raw/)
+- Branner
+  - **BREAKING:** Infixed `))` (e.g. `t))s`) is no longer supported and must now be used as a postfix (e.g. `ts))`) as per the official specification
+  - Added support for more IPA characters and diacritics according to official specification
+- Praat
+  - Added support for more IPA characters and diacritics according to official specification
+- SIL
+  - Added support for more IPA characters and diacritics according to official specification
+  - Added support for subscripts
+  - Added support for right-bar tone glides
+  - Added support for left-bar tones
+  - Added Unicode support for hooks (palatal, retroflex)
+  - Added Unicode support for middle tildes (velar, pharyngeal)
+  - Added Unicode support for superscripts
+- X-SAMPA
+  - Added support for more IPA characters and diacritics according to official specification
+
+## 1.1.1
+
+- Fixed a bug in X-SAMPA where ``` ` ``` falsely took precedence over ``` @` ``` (https://github.com/imatpot/typst-packages/issues/1)
+
+## 1.1.0
+
+- Translations will now return a [`str`](https://typst.app/docs/reference/foundations/str/) if the font is not overridden
+- The library now explicitly exposes functions via a "gateway" entrypoint
+- Update internal project structure
+- Update package metadata
+- Update documentation
+
+## 1.0.0
+
+- Initial release

packages/preview/ascii-ipa/2.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 imatpot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/preview/ascii-ipa/2.2.0/README.md

@@ -0,0 +1,166 @@
+# `ascii-ipa`
+
+🔄 ASCII / IPA conversion for Typst
+
+This package allows you to easily convert different ASCII representations of the International Phonetic Alphabet (IPA) to and from the IPA.
+It also offers some minor utilities to make phonetic transcriptions easier to use overall.
+The package is being maintained [here][repo].
+
+Note: This is an extended port of the [`ipa-translate`][ipa-translate] Rust crate by [tirimid][tirimid]'s conversion features into native Typst.
+Most conversions are implemented according to [this Wikipedia article][ipa-wikipedia] which in turn relies of the official specifications of the respective ASCII representations.
+
+## Conversion
+
+The package supports multiple ASCII representations for the IPA with one function each:
+
+| Notation | Function name   |
+|----------|-----------------|
+| Branner  | `#branner(...)` |
+| CXS      | `#cxs(...)`     |
+| Praat    | `#praat(...)`   |
+| SIL      | `#sil(...)`     |
+| X-SAMPA  | `#xsampa(...)`  |
+
+They all return the converted value as a [`string`][typst-str] and accept the set of same parameters:
+
+| Parameter | Type                  | Positional / Named | Default | Description                                                                                                |
+|-----------|-----------------------|--------------------|---------|------------------------------------------------------------------------------------------------------------|
+| `value`   | [`string`][typst-str] | positional         |         | Main input to the function. Usually the transcription in the corresponsing ASCII-based notation.           |
+| `reverse` | [`bool`][typst-bool]  | named              | `false` | Reverses the conversion. Pass Unicode IPA into `value` to get the corresponsing ASCII-based notation back. |
+
+### Examples
+
+All examples use the Swiss German word [⟨Chuchichäschtli⟩ [ˈχʊ.χːi.ˌχæʃːt.lɪ]][chuchichäschtli] for the conversion.
+
+```typst
+#import "@preview/ascii-ipa:2.2.0": *
+
+// returns "ˈχʊ.χːi.ˌχæʃːt.lɪ"
+#branner("'XU.X:i.,Xae)S:t.lI")
+
+// returns "'XU.X:i.,Xae)S:t.lI"
+#branner("ˈχʊ.χːi.ˌχæʃːt.lɪ", reverse: true)
+
+// returns "ˈχʊ.χːi.ˌχæʃːt.lɪ"
+#cxs("'XU.X:i.,X&S:t.lI")
+
+// returns "'XU.X:i.,X&S:t.lI"
+#cxs("ˈχʊ.χːi.ˌχæʃːt.lɪ", reverse: true)
+
+// returns "ˈχʊ.χːi.ˌχæʃːt.lɪ"
+#praat("\\'1\\cf\\hs.\\cf\\:f.\\'2\\ae\\sh\\:ft.l\\ic")
+
+// returns "\\'1\\cf\\hs.\\cf\\:f.\\'2\\ae\\sh\\:ft.l\\ic"
+#praat("ˈχʊ.χːi.ˌχæʃːt.lɪ", reverse: true)
+
+// returns "ˈχʊ.χːi.ˌχæʃːt.lɪ"
+#sil("}x=u<x=:i}}x=a<s=:tli=")
+
+// returns "}x=u<x=:i}}x=a<s=:tli="
+#sil("ˈχʊ.χːi.ˌχæʃːt.lɪ", reverse: true)
+
+// returns "ˈχʊ.χːi.ˌχæʃːt.lɪ"
+#xsampa("\"XUX:i%X{S:tlI")
+
+// returns "\"XUX:i%X{S:tlI"
+#xsampa("ˈχʊ.χːi.ˌχæʃːt.lɪ", reverse: true)
+```
+
+### With `raw`
+
+You can also use [`raw`][typst-raw] for the conversion.
+This is useful if the notation uses a lot of backslashes.
+
+```typst
+#import "@preview/ascii-ipa:2.2.0": praat
+
+// regular string
+#praat("\\'1\\cf\\hs.\\cf\\:f.\\'2\\ae\\sh\\:ft.l\\ic")
+
+// raw
+#praat(`\'1\cf\hs.\cf\:f.\'2\ae\sh\:ft.l\ic`)
+```
+
+Note: `raw` will not play nicely with notations that use ``` ` ``` a lot.
+
+### Convenience `show`-rule
+
+You can use a `show`-rule to automatically turn `raw`-blocks into converted IPA.
+The following example will turn any inline-`raw` into X-SAMPA converted IPA, unless the `<code>` label is added.
+It also properly rescales the font size to match surrounding text, since `raw` uses a 20% smaller font size for its monospaced text by default.
+This is done for aesthetic reasons, you can read more here:
+
+- https://github.com/typst/typst/issues/1331
+- https://github.com/typst/typst/issues/6302
+
+```typst
+#{
+  let font = "Your IPA font here"
+  show raw: set text(size: 1em / 0.8)
+  show raw.where(block: false): it => {
+    if it.at("label", default: none) != <code> { // skip code-labeled raws
+      text(font: font, xsampa(it))
+    } else {
+      it
+    }
+  }
+}
+
+// Example
+
+Chuchichäschtli is pronounced `"XU.X:i.%X{S:t.lI`        // will render ˈχʊ.χːi.ˌχæʃːt.lɪ as normal text
+Chuchichäschtli is pronounced `"XU.X:i.%X{S:t.lI` <code> // will render "XU.X:i.%X{S:t.lI as raw code
+```
+
+This exact beheviour is provided built-in, so you don't need to define it yourself.
+
+```typst
+#import "@preview/ascii-ipa:2.2.0": replace-raw, xsampa
+#show: replace-raw(xsampa, font: "Your IPA font here")
+```
+
+You can also customize the `skip` label and the `size` if you want, otherwise the above defaults are provided.
+
+## Brackets & Braces
+
+You can easily mark your notation text as different types of brackets or braces.
+
+```typst
+#import "@preview/ascii-ipa:2.2.0": *
+
+#phonetic("ˈχʊ.χːi.ˌχæʃːt.lɪ")          // [ˈχʊ.χːi.ˌχæʃːt.lɪ]
+#phnt("ˈχʊ.χːi.ˌχæʃːt.lɪ")              // [ˈχʊ.χːi.ˌχæʃːt.lɪ]
+
+#precise("ˈχʊ.χːi.ˌχæʃːt.lɪ")           // ⟦ˈχʊ.χːi.ˌχæʃːt.lɪ⟧
+#prec("ˈχʊ.χːi.ˌχæʃːt.lɪ")              // ⟦ˈχʊ.χːi.ˌχæʃːt.lɪ⟧
+
+#phonemic("ˈχʊ.χːi.ˌχæʃːt.lɪ")          // /ˈχʊ.χːi.ˌχæʃːt.lɪ/
+#phnm("ˈχʊ.χːi.ˌχæʃːt.lɪ")              // /ˈχʊ.χːi.ˌχæʃːt.lɪ/
+
+#morphophonemic("ˈχʊ.χːi.ˌχæʃːt.lɪ")    // ⫽ˈχʊ.χːi.ˌχæʃːt.lɪ⫽
+#mphnm("ˈχʊ.χːi.ˌχæʃːt.lɪ")             // ⫽ˈχʊ.χːi.ˌχæʃːt.lɪ⫽
+
+#indistinguishable("ˈχʊ.χːi.ˌχæʃːt.lɪ") // (ˈχʊ.χːi.ˌχæʃːt.lɪ)
+#idst("ˈχʊ.χːi.ˌχæʃːt.lɪ")              // (ˈχʊ.χːi.ˌχæʃːt.lɪ)
+
+#obscured("ˈχʊ.χːi.ˌχæʃːt.lɪ")          // ⸨ˈχʊ.χːi.ˌχæʃːt.lɪ⸩
+#obsc("ˈχʊ.χːi.ˌχæʃːt.lɪ")              // ⸨ˈχʊ.χːi.ˌχæʃːt.lɪ⸩
+
+#orthographic("Chuchichäschtli")        // ⟨Chuchichäschtli⟩
+#orth("Chuchichäschtli")                // ⟨Chuchichäschtli⟩
+
+#transliterated("Chuchichäschtli")      // ⟪Chuchichäschtli⟫
+#trlt("Chuchichäschtli")                // ⟪Chuchichäschtli⟫
+
+#prosodic("ˈχʊ.χːi.ˌχæʃːt.lɪ")          // {ˈχʊ.χːi.ˌχæʃːt.lɪ}
+#prsd("ˈχʊ.χːi.ˌχæʃːt.lɪ")              // {ˈχʊ.χːi.ˌχæʃːt.lɪ}
+```
+
+[repo]: https://github.com/imatpot/typst-ascii-ipa
+[ipa-translate]: https://github.com/tirimid/ipa-translate
+[tirimid]: https://github.com/tirimid
+[ipa-wikipedia]: https://en.wikipedia.org/wiki/Comparison_of_ASCII_encodings_of_the_International_Phonetic_Alphabet
+[typst-str]: https://typst.app/docs/reference/foundations/str/
+[typst-bool]: https://typst.app/docs/reference/foundations/bool/
+[typst-raw]: https://typst.app/docs/reference/text/raw/
+[chuchichäschtli]: https://als.wikipedia.org/wiki/Chuchich%C3%A4schtli

packages/preview/ascii-ipa/2.2.0/src/lib/converters.typ

@@ -0,0 +1,31 @@
+#import "utils.typ": sanitize
+#import "converters/branner.typ": convert-branner
+#import "converters/cxs.typ": convert-cxs
+#import "converters/praat.typ": convert-praat
+#import "converters/sil.typ": convert-sil
+#import "converters/xsampa.typ": convert-xsampa
+
+#let branner(text, reverse: false) = convert-branner(
+  sanitize(text),
+  reverse: reverse,
+)
+
+#let cxs(text, reverse: false) = convert-cxs(
+  sanitize(text),
+  reverse: reverse,
+)
+
+#let praat(text, reverse: false) = convert-praat(
+  sanitize(text),
+  reverse: reverse,
+)
+
+#let sil(text, reverse: false) = convert-sil(
+  sanitize(text),
+  reverse: reverse,
+)
+
+#let xsampa(text, reverse: false) = convert-xsampa(
+  sanitize(text),
+  reverse: reverse,
+)