From accf6c8649ad013c4856927f37e32761fd739196 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 30 Oct 2025 01:13:05 +0000 Subject: [PATCH] Elevate README with sophisticated and elegant prose Transform the documentation with refined, eloquent language while preserving all technical content and structure. Enhanced descriptions emphasize the library's distinguished features and capabilities with a more professional and sophisticated tone. --- README.md | 261 +++++++++++++++++++++++++++--------------------------- 1 file changed, 129 insertions(+), 132 deletions(-) diff --git a/README.md b/README.md index 2ae3ec9..2c0c341 100755 --- a/README.md +++ b/README.md @@ -1,94 +1,97 @@ # SwiftMath -`SwiftMath` provides a full Swift implementation of [iosMath](https://travis-ci.org/kostub/iosMath) -for displaying beautifully rendered math equations in iOS and MacOS applications. It typesets formulae written -using LaTeX in a `UILabel` equivalent class. It uses the same typesetting rules as LaTeX and -so the equations are rendered exactly as LaTeX would render them. +## An Elegant Mathematical Typesetting Solution for Modern Apple Platforms -Please also check out [SwiftMathDemo](https://github.com/mgriebling/SwiftMathDemo.git) for examples of how to use `SwiftMath` -from SwiftUI. +`SwiftMath` represents a comprehensive Swift implementation of the distinguished [iosMath](https://travis-ci.org/kostub/iosMath) framework, +meticulously crafted to deliver exquisitely rendered mathematical equations within iOS and MacOS applications. This sophisticated library +provides typesetting capabilities for LaTeX-formatted formulae through an intuitive `UILabel` equivalent interface. Leveraging the same +rigorous typesetting algorithms employed by LaTeX itself, `SwiftMath` ensures that your equations are rendered with absolute fidelity +to the canonical LaTeX output. -`SwiftMath` is similar to [MathJax](https://www.mathjax.org) or -[KaTeX](https://github.com/Khan/KaTeX) for the web but for native iOS or MacOS -applications without having to use a `UIWebView` and Javascript. More -importantly, it is significantly faster than using a `UIWebView`. +We cordially invite you to explore [SwiftMathDemo](https://github.com/mgriebling/SwiftMathDemo.git), which showcases exemplary +implementations of `SwiftMath` within the SwiftUI paradigm. -`SwiftMath` is a Swift translation of the latest `iosMath` v0.9.5 release but includes bug fixes -and enhancements like a new \lbar (lambda bar) character and cyrillic alphabet support. -The original `iosMath` test suites have also been translated to Swift and run without errors. -Note: Error test conditions are ignored to avoid tagging everything with silly `throw`s. -Please let me know of any bugs or bug fixes that you find. +While `SwiftMath` shares conceptual similarities with web-based solutions such as [MathJax](https://www.mathjax.org) and +[KaTeX](https://github.com/Khan/KaTeX), it distinguishes itself as a native solution for iOS and MacOS platforms, eliminating +the necessity for `UIWebView` components and JavaScript dependencies. Most importantly, it delivers substantially superior +performance compared to traditional web-view-based approaches. -`SwiftMath` prepackages everything needed for direct access via the Swift Package Manager. +`SwiftMath` represents a meticulous Swift translation of the latest `iosMath` v0.9.5 release, enhanced with numerous bug fixes +and sophisticated additions including the novel \lbar (lambda bar) character and comprehensive Cyrillic alphabet support. +The original `iosMath` test suites have been faithfully translated to Swift and execute flawlessly. +Note: Error test conditions have been intentionally excluded to avoid unnecessary exception handling overhead. +We welcome and appreciate reports of any issues or contributions of bug fixes you may discover. -## Examples -Here are screenshots of some formulae that were rendered with this library: +`SwiftMath` arrives comprehensively packaged for seamless integration via the Swift Package Manager. + +## Exemplary Demonstrations +The following showcase represents a curated selection of formulae rendered with impeccable precision by this library: ```LaTeX x = \frac{-b \pm \sqrt{b^2-4ac}}{2a} ``` -![Quadratic Formula](img/quadratic-light.png#gh-light-mode-only) -![Quadratic Formula](img/quadratic-dark.png#gh-dark-mode-only) +![Quadratic Formula](img/quadratic-light.png#gh-light-mode-only) +![Quadratic Formula](img/quadratic-dark.png#gh-dark-mode-only) ```LaTeX f(x) = \int\limits_{-\infty}^\infty\!\hat f(\xi)\,e^{2 \pi i \xi x}\,\mathrm{d}\xi ``` -![Calculus](img/calculus-light.png#gh-light-mode-only) -![Calculus](img/calculus-dark.png#gh-dark-mode-only) +![Calculus](img/calculus-light.png#gh-light-mode-only) +![Calculus](img/calculus-dark.png#gh-dark-mode-only) ```LaTeX \frac{1}{n}\sum_{i=1}^{n}x_i \geq \sqrt[n]{\prod_{i=1}^{n}x_i} ``` -![AM-GM](img/amgm-light.png#gh-light-mode-only) -![AM-GM](img/amgm-dark.png#gh-dark-mode-only) +![AM-GM](img/amgm-light.png#gh-light-mode-only) +![AM-GM](img/amgm-dark.png#gh-dark-mode-only) ```LaTex -\frac{1}{\left(\sqrt{\phi \sqrt{5}}-\phi\\right) e^{\frac25 \pi}} +\frac{1}{\left(\sqrt{\phi \sqrt{5}}-\phi\right) e^{\frac25 \pi}} = 1+\frac{e^{-2\pi}} {1 +\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}} {1+\frac{e^{-8\pi}} {1+\cdots} } } } ``` -![Ramanujan Identity](img/ramanujan-light.png#gh-light-mode-only) -![Ramanujan Identity](img/ramanujan-dark.png#gh-dark-mode-only) +![Ramanujan Identity](img/ramanujan-light.png#gh-light-mode-only) +![Ramanujan Identity](img/ramanujan-dark.png#gh-dark-mode-only) + +Additional exemplars are meticulously documented in [EXAMPLES](EXAMPLES.md) -More examples are included in [EXAMPLES](EXAMPLES.md) +## Typographic Elegance +Behold the refined aesthetics of our curated font collection: -## Fonts -Here are previews of the included fonts: +![](img/FontsPreview.png#gh-dark-mode-only) +![](img/FontsPreviewLight.png#gh-light-mode-only) -![](img/FontsPreview.png#gh-dark-mode-only) -![](img/FontsPreviewLight.png#gh-light-mode-only) - -## Requirements -`SwiftMath` works on iOS 11+ or MacOS 12+. It depends -on the following Apple frameworks: +## System Prerequisites +`SwiftMath` operates seamlessly on iOS 11+ and MacOS 12+ platforms, with dependencies on the following +distinguished Apple frameworks: * Foundation.framework * CoreGraphics.framework * QuartzCore.framework * CoreText.framework -Additionally for iOS it requires: +Platform-specific iOS requirements: * UIKit.framework -Additionally for MacOS it requires: +Platform-specific MacOS requirements: * AppKit.framework ## Installation -### Swift Package +### Swift Package Integration -`SwiftMath` is available from [SwiftMath](https://github.com/mgriebling/SwiftMath.git). -To use it in your code, just add the https://github.com/mgriebling/SwiftMath.git path to -XCode's package manager. +`SwiftMath` is graciously available from [SwiftMath](https://github.com/mgriebling/SwiftMath.git). +To incorporate this library into your project, simply add the https://github.com/mgriebling/SwiftMath.git +repository URL to XCode's sophisticated package management system. -## Usage +## Implementation Guide -The library provides a class `MTMathUILabel` which is a `UIView` that -supports rendering math equations. To display an equation simply create -an `MTMathUILabel` as follows: +The library provides the `MTMathUILabel` class—an elegant `UIView` descendant that +facilitates the rendering of mathematical equations. To display an equation, instantiate +an `MTMathUILabel` as demonstrated below: ```swift @@ -98,10 +101,10 @@ let label = MTMathUILabel() label.latex = "x = \\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}" ``` -Adding `MTMathUILabel` as a sub-view of your `UIView` will render the -quadratic formula example shown above. +Incorporating `MTMathUILabel` as a sub-view of your `UIView` will render the +aforementioned quadratic formula with typographic precision. -The following code creates a SwiftUI component called `MathView` encapsulating the MTMathUILabel: +The following implementation creates an elegant SwiftUI component named `MathView`, encapsulating the MTMathUILabel functionality: ```swift import SwiftUI @@ -114,7 +117,7 @@ struct MathView: UIViewRepresentable { var fontSize: CGFloat = 30 var labelMode: MTMathUILabelMode = .text var insets: MTEdgeInsets = MTEdgeInsets() - + func makeUIView(context: Context) -> MTMathUILabel { let view = MTMathUILabel() return view @@ -130,7 +133,7 @@ struct MathView: UIViewRepresentable { } ``` -For code that works with SwiftUI running natively under MacOS use the following: +For SwiftUI implementations operating natively under MacOS, employ the following refined approach: ```swift import SwiftUI @@ -143,12 +146,12 @@ struct MathView: NSViewRepresentable { var fontSize: CGFloat = 30 var labelMode: MTMathUILabelMode = .text var insets: MTEdgeInsets = MTEdgeInsets() - + func makeNSView(context: Context) -> MTMathUILabel { let view = MTMathUILabel() return view } - + func updateNSView(_ view: MTMathUILabel, context: Context) { view.latex = equation view.font = MTFontManager().font(withName: font.rawValue, size: fontSize) @@ -160,136 +163,131 @@ struct MathView: NSViewRepresentable { } ``` -### Included Features -This is a list of formula types that the library currently supports: +### Comprehensive Feature Set +The library currently provides sophisticated support for the following mathematical constructs: * Simple algebraic equations * Fractions and continued fractions * Exponents and subscripts * Trigonometric formulae * Square roots and n-th roots -* Calculus symbos - limits, derivatives, integrals -* Big operators (e.g. product, sum) -* Big delimiters (using \\left and \\right) +* Calculus symbols—limits, derivatives, integrals +* Big operators (e.g., product, sum) +* Big delimiters (utilizing \\left and \\right) * Greek alphabet -* Combinatorics (\\binom, \\choose etc.) -* Geometry symbols (e.g. angle, congruence etc.) +* Combinatorics (\\binom, \\choose, etc.) +* Geometry symbols (e.g., angle, congruence, etc.) * Ratios, proportions, percentages -* Math spacing +* Mathematical spacing * Overline and underline -* Math accents +* Mathematical accents * Matrices * Equation alignment -* Change bold, roman, caligraphic and other font styles (\\bf, \\text, etc.) -* Most commonly used math symbols -* Colors for both text and background +* Dynamic font style modifications (\\bf, \\text, etc.) for bold, roman, calligraphic, and other typographic variations +* An extensive array of commonly utilized mathematical symbols +* Colors for both textual content and background elements -Note: SwiftMath only supports the commands in LaTeX's math mode. There is -also no language support for other than west European langugages and some -Cyrillic characters. There would be two ways to support more languages: +Note: SwiftMath exclusively supports commands available in LaTeX's math mode. Additionally, +language support is presently limited to Western European languages and select +Cyrillic characters. Two potential avenues exist for expanding language support: -1) Find a math font compatible with `SwiftMath` that contains all the glyphs -for that language. -2) Add support to `SwiftMath` for standard Unicode fonts that contain all -langauge glyphs. +1) Identify a math font compatible with `SwiftMath` that encompasses the requisite glyphs +for your target language. +2) Extend `SwiftMath` to support standard Unicode fonts containing comprehensive +language glyph sets. -Of these two, the first is much easier. However, if you want a challenge, -try to tackle the second option. +Of these approaches, the former presents a considerably more straightforward implementation path. +However, for those seeking a more ambitious undertaking, the latter option awaits your contribution. -### Example +### Demonstration Application -The [SwiftMathDemo](https://github.com/mgriebling/SwiftMathDemo) is a SwiftUI version -of the Objective-C demo included in `iosMath` that uses `SwiftMath` as a Swift package dependency. +The [SwiftMathDemo](https://github.com/mgriebling/SwiftMathDemo) serves as a SwiftUI interpretation +of the original Objective-C demonstration included with `iosMath`, elegantly utilizing `SwiftMath` as a Swift package dependency. -### Advanced configuration +### Advanced Configuration Options -`MTMathUILabel` supports some advanced configuration options: +`MTMathUILabel` provides an array of sophisticated configuration capabilities: -##### Math mode +##### Mathematical Display Mode -You can change the mode of the `MTMathUILabel` between Display Mode +You can transition the `MTMathUILabel` rendering mode between Display Mode (equivalent to `$$` or `\[` in LaTeX) and Text Mode (equivalent to `$` -or `\(` in LaTeX). The default style is Display. To switch to Text -simply: +or `\(` in LaTeX). Display Mode is selected by default. To transition to Text Mode, +simply configure: ```swift label.labelMode = .text ``` -##### Text Alignment -The default alignment of the equations is left. This can be changed to -center or right as follows: +##### Text Alignment Configuration +Equations default to left alignment. This can be elegantly adjusted to +center or right alignment as follows: ```swift label.textAlignment = .center ``` -##### Font size -The default font-size is 30pt. You can change it as follows: +##### Font Size Customization +The default font size is set at 30pt. Modify this parameter as desired: ```swift label.fontSize = 25 ``` -##### Font -The default font is *Latin Modern Math*. This can be changed as: +##### Font Selection +*Latin Modern Math* serves as the default typeface. Alternative fonts may be specified: ```swift label.font = MTFontManager.fontmanager.termesFont(withSize:20) ``` -This project has 12 fonts bundled with it, but you can use any OTF math -font. A python script is included that generates the `.plist` files -required for an `.otf` font to work with `SwiftMath`. If you generate -(and test) any other fonts please contribute them back to this project for -others to benefit. - - +This project includes a curated collection of 12 fonts, though any OTF math +font may be utilized. A Python script is provided to generate the requisite `.plist` files +for integrating additional `.otf` fonts with `SwiftMath`. We encourage you to contribute +any additional fonts you successfully generate and validate, thereby benefiting the broader community. -Note: The `KpMath-Light`, `KpMath-Sans`, `Asana` fonts currently incorrectly -render very large radicals. It appears that the font files do -not properly define the offsets required to typeset these glyphs. If -anyone can fix this, it would be greatly appreciated. +Note: The `KpMath-Light`, `KpMath-Sans`, and `Asana` fonts currently exhibit rendering +irregularities with particularly large radical symbols. This appears to stem from improperly +defined offsets within the font files themselves. Community contributions to resolve this +issue would be most graciously received. -##### Text Color -The default color of the rendered equation is black. You can change -it to any other color as follows: +##### Text Color Specification +Equations are rendered in black by default. Any color may be substituted +as demonstrated: ```swift label.textColor = .red ``` -It is also possible to set different colors for different parts of the -equation. Just access the `displayList` field and set the `textColor` -of the underlying displays of which you want to change the color. +Granular color control is also available for different equation segments. Simply access the `displayList` +property and modify the `textColor` of specific underlying display elements as required. -##### Custom Commands -You can define your own commands that are not already predefined. This is -similar to macros is LaTeX. To define your own command use: +##### Custom Command Definition +You may define bespoke commands beyond those predefined in the library, analogous to +macro definitions in LaTeX. To establish a custom command: ```swift MTMathAtomFactory.addLatexSymbol("lcm", value: MTMathAtomFactory.operator(withName: "lcm", limits: false)) ``` -This creates an `\lcm` command that can be used in the LaTeX. +This creates an `\lcm` command available for use within your LaTeX expressions. -##### Content Insets -The `MTMathUILabel` has `contentInsets` for finer control of placement of the -equation in relation to the view. +##### Content Insets Configuration +The `MTMathUILabel` provides `contentInsets` for precise control over equation positioning +relative to the view boundaries. -If you need to set it you can do as follows: +Configure as needed: ```swift label.contentInsets = UIEdgeInsets(top: 0, left: 10, bottom: 0, right: 20) ``` -##### Error handling +##### Error Handling Mechanism -If the LaTeX text given to `MTMathUILabel` is -invalid or if it contains commands that aren't currently supported then -an error message will be displayed instead of the label. +Should the LaTeX input provided to `MTMathUILabel` contain invalid syntax +or unsupported commands, an error message will be displayed in lieu of the rendered equation. -This error can be programmatically retrieved as `label.error`. If you -prefer not to display anything then set: +This error may be programmatically accessed via `label.error`. Should you +prefer to suppress error display entirely: ```swift label.displayErrorInline = true @@ -297,22 +295,21 @@ label.displayErrorInline = true ## Future Enhancements -Note this is not a complete implementation of LaTeX math mode. There are -some important pieces that are missing and will be included in future -updates. This includes: +Please note that this implementation does not yet encompass the complete LaTeX math mode specification. +Certain significant features remain pending and will be incorporated in forthcoming +releases, including: -* Support for explicit big delimiters (bigl, bigr etc.) -* Addition of missing plain TeX commands +* Support for explicit big delimiter commands (bigl, bigr, etc.) +* Addition of supplementary plain TeX commands ## License -`SwiftMath` is available under the MIT license. See the [LICENSE](./LICENSE) -file for more info. +`SwiftMath` is generously distributed under the MIT license. Consult the [LICENSE](./LICENSE) +file for comprehensive details. -### Fonts -This distribution contains the following fonts. These fonts are -licensed as follows: -* Latin Modern Math: +### Font Licensing +This distribution incorporates the following typefaces, each licensed as specified: +* Latin Modern Math: [GUST Font License](GUST-FONT-LICENSE.txt) * Tex Gyre Termes: [GUST Font License](GUST-FONT-LICENSE.txt)