7. Citations, rendering and documentation

This chapter records where the strength formula comes from, and writes the formula out for a report: as text, as LaTeX, and as a table of the symbols it reads. All three come from the same declaration that calculates the strength.

The program is chapter 5's, with its first rounding rule only, the strength formula wrapped in a citation, and one specimen; the formula is rendered and documented before it is evaluated.

Cite where the formula comes from

formula::documented(expression, citation) attaches a formula::Citation to an expression. A citation has five fields: title, reference, section, equation and text. Each is optional, and a field left out reads back empty. The strength formula cites the method it is taken from:

constexpr auto loadedArea = formula::yields<Area>(var<SideA> * var<SideB>);
constexpr auto strength =
    formula::yields<Strength>(formula::documented(formula::rounded<tenthMpa>(var<Load> / loadedArea),
                                                  { .title = "Compressive strength",
                                                    .reference = "Example Standard 12:2020",
                                                    .section = "6.1",
                                                    .equation = "(1)",
                                                    .text = "The maximum load divided by the area of the loaded face." }));

The citation changes nothing that is calculated: the wrapped expression has the same dimension and gives the same value as the expression alone. A specimen 150 mm by 150 mm that carried 675 kN gives 30 MPa, as in chapter 4:

auto const specimen = formula::environment(
    formula::Measured<SideA> { 150 }, formula::Measured<SideB> { 150 }, formula::Measured<Load> { 675 });
auto const result = formula::checked_evaluate(strength, specimen);
if (!result)
{
    std::println("cannot calculate the strength: {}", result.error());
    return 1;
}
std::println("{} = {}", formula::symbol_of<Strength>(), *result);

Render it

formula::render(formula) writes a formula as plain text, and formula::render<formula::Dialect::LaTeX>(formula) writes the same formula as LaTeX, from the same declaration:

std::println("text:  {}", formula::render(strength));
std::println("LaTeX: {}", formula::render<formula::Dialect::LaTeX>(strength));

The rounding is written with its rule: to 1 dp of MPa in text, one decimal place of a megapascal, and the subscript 1\,\mathrm{MPa} in LaTeX, the places followed by the unit they count in.

render writes the formula a bound formula holds, and names no result: f_c appears in neither line (Naming the result once). The citation does not appear in either rendering: it describes the formula rather than being part of it.

Generate its documentation

formula::document(formula) returns a formula::Documentation: the rendering, the symbol table and the citations, which is everything a report's methods section needs:

formula::Documentation const page = formula::document(strength);
std::println("symbols:");
for (formula::SymbolEntry const& entry: page.symbols)
    std::println("  {:<5} {:<6} {}", entry.symbol, entry.unit, entry.description);
for (formula::Citation const& citation: page.citations)
    std::println("cited: {}, {}", citation.title, citation.reference);

page.symbols holds one formula::SymbolEntry per quantity the formula reads, in the order the formula reads them, each with the symbol, description and unit its declaration gives. Like the rendering, the symbol table describes what the formula reads and names no result, so f_c has no row. The symbol table of a calculation lists the values it calculates first (The graph, known while the program compiles). page.citations holds every citation in the formula, with all five fields; the program prints the title and the reference.

Output

text:  round(F / (a * b), to 1 dp of MPa)
LaTeX: \operatorname{round}_{1\,\mathrm{MPa}}(\frac{F}{a \cdot b})
symbols:
  F     kN     maximum load
  a     mm     first side of the loaded face
  b     mm     second side of the loaded face
cited: Compressive strength, Example Standard 12:2020
f_c = 30 MPa

Summary

formula::documented(expression, citation) -- attaches a citation to an expression, without changing what it calculates.
formula::Citation -- where a formula comes from: title, reference, section, equation and text, each optional.
formula::render(formula) -- the formula as plain text.
formula::Dialect::LaTeX -- render<formula::Dialect::LaTeX> writes the formula as LaTeX.
formula::document(formula) -- the formula's rendering, symbol table and citations.
formula::Documentation -- what document returns; its formula, symbols and citations hold the rendering, the symbol table and the citations.
formula::SymbolEntry -- one row of the symbol table: symbol, unit and description.