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)