C++ guide

Brief++ is a header-only C++17 library. Add this repository to your build or put include/ on your compiler’s include path. Your application creates a Document, adds content, and writes one or more output files.

Build your first report

With CMake, add Brief++ as a subdirectory and link its interface target:

add_subdirectory(external/briefpp)
add_executable(report main.cpp)
target_link_libraries(report PRIVATE briefpp::briefpp)

Create main.cpp:

#include <briefpp/report.hpp>

int main() {
    briefpp::Document doc;
    doc.title("Field measurements").author("Research team");

    auto& results = doc.section("Results").label("results");
    results.paragraph().text("The measured value was ").strong("42").text(" units.");
    results.table().columns("Parameter", "Value")
        .row("Sample count", "12")
        .row("Mean", "42");
    results.note("Values are rounded to whole units.");

    doc.write("report.md");
    doc.write("report.html");
}

The two files contain the same content in different formats. write() chooses a renderer from the filename extension. To get output as a string, call a renderer directly:

const std::string html = briefpp::HtmlRenderer{}.render(doc);

Use Brief++ without CMake

For a single source file, compile with a C++17 compiler and the include path:

c++ -std=c++17 -I path/to/briefpp/include main.cpp -o report
./report

The PyPI package also installs the C++ headers. If you have already installed it, python -c 'import briefpp; print(briefpp.get_include())' prints the path to pass with -I.

Add common report content

A section can contain subsections and blocks. Keep its returned reference when you want to add several blocks under the same heading:

auto& methods = doc.section("Methods");
methods.paragraph("We sampled the site once per hour.");
methods.equation(R"(E = mc^2)", "energy");

auto& observations = methods.section("Observations");
observations.figure("chart.png").caption("Hourly readings")
    .label("readings").width(0.7);
observations.paragraph().text("See ").reference("readings")
    .text(" for the trend.");

label() names a block; reference() links to that label in formats that support references. Figure paths are written into the output as given. Put the image where the generated document or its compiler can find it.

Run the repository example

The full example at examples/atmospheric.cpp demonstrates metadata, hyperlinks, rich text, references, two formulas, a figure, headered and headerless tables, nested lists, definitions, code, notes, fragments, and backend-specific content. Install pdflatex, then run from the repository root:

cmake -S . -B build
cmake --build build --target briefpp_demo

The seven text exports, report.pdf, density.png, and report.css appear in examples/output and can be committed with the example. The demo target requires pdflatex so a successful run always includes the PDF. Open report.html in a browser for styled output, report.md for the MyST representation, or report.json to inspect the semantic tree. To run the C++ test suite, use ctest --test-dir build --output-on-failure. The standalone test build downloads doctest v2.5.3; when Brief++ is embedded with add_subdirectory(), tests and examples default to off.

Next, see Document model for lists, rich text, fragments, and tables, or Renderers and output behavior for output formats and renderer settings.