DESIGN.md

Provided items

The crate is meant to provide only one item, its namesake, include_display_mode_tex!() macro. This macro must embed display mode tex.

Implementation overview

First and foremost, the only macro of this crate, include_display_mode_tex!() , is implemented as a function-like procedural macro, i.e. it accepts and outputs TokenStream and is driven by the machinery provided by the proc_macro crate

Project structure

├── src
│   ├── args.rs # anything that has to do with obtaining arguments from the input TokenStream
│   └── lib.rs # the macro itself and the remaining constituent parts
├── Cargo.toml # project manifest
├── README.md # document for library users
├── DESIGN.md # document for library developers
├── LICENSE-APACHE
│       ├── # legal texts
├── LICENSE-MIT
└── .gitignore

Plans for the development

Specifying the path from canonical directories

Problem

At the time of writing the macro accepts only a string literal that contains either an absolutele path to a tex file to be embedded or a relative path from the call site directory. While this is roughly the behavior of include_str!(), it might be not very convenient for some developers.

If a developer wants to keep .tex files separate from .rs files but the depth of modules is very high, they will quickly find themselves writing something like this:

// The story goes the developer will eventually start typing the path from the crate root
#[doc = include_display_mode_tex!("../../../../../../../")]

Suggested solution

In order to make the developer experience more pleasant, the alternative syntax should be

#[doc = include_display_mod_tex!("CARGO_MANIFEST_DIR/path/from/crate_root/tex_file.tex")]

for the path from the root of the crate where the macro was called and

#[doc = include_display_mod_tex!("TEX_DIR/path/to/tex_file.tex")]

for the path from the CARGO_MANIFEST_DIR/src/tex/ where, just like earlier, CARGO_MANIFEST_DIR is the root of the crate where the macro was called.

Choice of names

• The name CARGO_MANIFEST_DIR can be already familiar to Rust developers as the name of the environment variable that Cargo sets for crates

• The name TEX_DIR is a novelty that was constructed by analogy and is expected be easy to remember

Drawbacks

The offered solution can cause some negligible compatibility issues if the developer for some unknown reason used either CARGO_MANIFEST_DIR or TEX_DIR as actual directory names.