tex_engine/
lib.rs

1/*! This crate provides the necessary data structures and algorithms for
2processing TeX documents fully. Since there are many different TeX engines
3(e.g. `pdfTeX`, `XeTeX`, `LuaTeX`, etc.), this crate largely follows an object-oriented design
4for modularity and adaptability, with functionality largely implemented in generic traits.
5Ideally, this lets the compiler optimize the code for the specific types used,
6while still allowing for "easy" customization.
7
8See [doc] for more information.
9
10## Current state
11
12- Runs without errors over all `.tex` files that succeed with `pdflatex` that I have tried so far
13    -- which is every `.tex` file I have on my hard drive going back >10 years, which use everything
14    from `tikz` to `biblatex` to `lstlisting`.
15- Performance is roughly equivalent to `pdflatex`.
16- Many primitive commands are missing, but those that are seem to be barely used (or at least
17    not used in the `.tex` files I have tried).
18- Many algorithms are approximate; in particular: computations of dimensions of boxes/nodes,
19  page and line breaking, when exactly to enter output routines, etc. Also, various
20  details of automatically inserted glue or kerning are not implemented.
21- Some apects are only implemented to the extent that they do not throw errors, e.g. hyphenation,
22  badness.
23- Some mechanisms have grown organically and should be overhauled, e.g. the way the stomach handles
24  node lists.
25- error messages for content errors - a lot of them are TODO placeholders, mostly because
26  they should be handled by an [`ErrorHandler`](crate::utils::errors::ErrorHandler) that may recover
27  from them (as TeX does it - e.g. inserting 0 when a number is expected). This is implemented for
28  *some* errors, but not many.
29
30It should be noted that this crate primarily exists as the basis of (an upcoming reimplementation
31of) [RusTeX](https://github.com/slatex/RusTeX), a TeX-to-HTML converter, the current (old) implementation
32of which is ineffecient, difficult to extend and generally a mess. As such, the features this crate offers
33are guided by my own needs and by what I have learned in my previous attempt. Ideally it should
34be possible to extend it to support other use cases as well -- at least that is the intention.
35
36I will happily accept pull requests for additional features or suggestions on how to
37make the algorithms here more accurate. I am also very open to redesigning interfaces, if someone
38has ideas on how to improve them - the ones I used are the best compromise I could come up with
39between usability, efficiency and modularity. I will also happily help anyone
40willing to contribute to this crate, but bear in mind that I am ridiculously overconstrained
41already, so as much as I wish I could, I am in no position to dig into the various rabbit holes
42that would be required to get this crate more in line with "actual TeX".
43
44Feel free to contact me [on github](https://github.com/Jazzpirate) if you have questions.
45 */
46#![forbid(unsafe_code)]
47//#![warn(missing_docs)]
48#![doc(html_root_url = "https://docs.rs")]
49#![allow(clippy::type_complexity)]
50
51pub mod commands;
52pub mod engine;
53pub mod tex;
54pub mod utils;
55
56#[cfg(doc)]
57pub mod doc;
58
59#[cfg(feature = "pdflatex")]
60pub mod pdflatex;
61
62#[cfg(test)]
63#[doc(hidden)]
64pub mod tests;
65
66/// Default `pub use` prelude for the crate
67pub mod prelude {
68    pub use crate::engine::mouth::Mouth;
69    pub use crate::engine::stomach::TeXMode;
70    pub use crate::engine::{DefaultEngine, EngineTypes, PlainTeXEngine, TeXEngine};
71    pub use crate::tex::catcodes::{CategoryCode, CategoryCodeScheme, CommandCode};
72    pub use crate::tex::characters::{Character, CharacterMap};
73    pub use crate::tex::nodes::{horizontal::HNode, math::MathNode, vertical::VNode, NodeTrait};
74    pub use crate::tex::tokens::control_sequences::{
75        CSHandler, CSName, InternedCSName, ResolvedCSName,
76    };
77    pub use crate::tex::tokens::token_lists::{CharWrite, TokenList};
78    pub use crate::tex::tokens::Token;
79    pub use crate::utils::errors::ErrorHandler;
80}
tex_engine/lib.rs

tex_engine/
lib.rs
