diff --git a/.github/workflows/ubuntu.yml b/.github/workflows/ubuntu.yml index 64f02e9a..72814056 100644 --- a/.github/workflows/ubuntu.yml +++ b/.github/workflows/ubuntu.yml @@ -1,6 +1,7 @@ name: Ubuntu on: + - push - pull_request jobs: @@ -14,7 +15,7 @@ jobs: - uses: actions/checkout@v2 - name: Downloading dependencies 📥 run: | - sudo apt-get install build-essential meson libgtksourceviewmm-3.0-dev libgtkmm-3.0-dev libgtk-4-dev libgtksourceview-5-dev gi-docgen + sudo apt-get install build-essential meson libgtksourceviewmm-3.0-dev libgtkmm-3.0-dev libgtk-4-dev libgtksourceview-5-dev gi-docgen doxygen sudo apt-get install qtbase5-dev qttools5-dev-tools - name: Configure 🔧 run: meson _build -DTARGET_DOCUMENTATION=true @@ -25,11 +26,23 @@ jobs: pushd _build tar -c * | zstd -o $GITHUB_WORKSPACE/artifacts.tar.zst popd + - name: Package documentation 📜 + run: | + mkdir -p pfx + DESTDIR=$PWD/pfx ninja -C _build install + pushd pfx/usr/local/share/doc/microtex/ + tar -c * | zstd -o $GITHUB_WORKSPACE/documentation.tar.zst + popd - name: Upload build artifacts 📤 uses: actions/upload-artifact@v1 with: name: Build artifacts path: artifacts.tar.zst + - name: Upload documentation 📤 + uses: actions/upload-artifact@v1 + with: + name: Documentation + path: documentation.tar.zst build_by_cmake: runs-on: ${{ matrix.os }} diff --git a/CMakeLists.txt b/CMakeLists.txt index 00caaba1..7ebf27e0 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -45,6 +45,7 @@ endif () include(MicroTeXInstall.cmake) add_subdirectory(lib) +add_subdirectory(doc) file(COPY res DESTINATION .) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt new file mode 100644 index 00000000..68d11ff6 --- /dev/null +++ b/doc/CMakeLists.txt @@ -0,0 +1,4 @@ +set(cwd ${CMAKE_CURRENT_LIST_DIR}) +set(source_root ${microtex_SOURCE_DIR}) +set(version ${microtex_VERSION}) +configure_file(microtex.doxy.in microtex.doxy @ONLY) diff --git a/doc/cairodoc.h b/doc/cairodoc.h new file mode 100644 index 00000000..3539066b --- /dev/null +++ b/doc/cairodoc.h @@ -0,0 +1,46 @@ +/** \page cairo_doc Cairo Documentation + * + * \section cairo_opts Build options + * + * \subsection Meson + * to build support for the Cairo platform using meson, you need to + * invoke meson using -DCAIRO=true as parameter. + * + * If you want to build the GTK3MM demo too, you need to add the + * -DEXAMPLE_GTKMM=true to the params too. + * + * \subsection CMake + * + * for cmake, you need to configure it, with -DCAIRO=ON + * and optionally with -DBUILD_EXAMPLE_GTKMM=ON. + * + * \section cairo_usage Usage + * + * \subsection cairo_init Initialization and PlatformFactory setup + * Refer to \ref index "the main page" for info about information about automatic + * font detection. The PlatformFactory setup is cairo specific. + * @code + * microtex::InitFontSenseAuto autoinit; + * microtex::MicroTeX::init(autoinit); + * microtex::PlatformFactory::registerFactory("gtk", std::make_unique()); + * microtex::PlatformFactory::activate("gtk"); + * @endcode + * + * \subsection cairo_render Rendering + * You need to make use of microtex::Graphics2D_cairo to render + * equations onto a cairo surface. The graphics context takes a pointer + * to a cairo context (cairo_t). Please note that the caller + * keeps the ownership of the cairo context. + * + * To receive a microtex::Render, you can either use the convenience + * method microtex::MicroTeX::parse(), or construct it yourself using + * microtex::RenderBuilder if you need more customization. + * + * @code + * void render_to_cairo(cairo_t* ctx, microtex::Render* tex) { + * microtex::Graphics2D_cairo g2(ctx); + * tex->draw(g2, 0, 0); + * } + * @endcode + * + */ diff --git a/doc/fontdoc.h b/doc/fontdoc.h new file mode 100644 index 00000000..270257f8 --- /dev/null +++ b/doc/fontdoc.h @@ -0,0 +1,313 @@ +/** \page font_doc CLM Font Format + * + * \section font_preamble Preamble + * Fonts are a core concept of \f$\MicroTeX\f$, as some kind of Font + * is definitively required to set an equation. + * + * The CLM Font format is made exactly to fulfill this need of font + * information for \f$\MicroTeX\f$. It is a fairly simple file format, + * containing font info, glyph metrics, math tables, and other + * significant information to layout math formulas, with this data + * simply being read linearly. It does not contain any kind of error + * checking or similar. + * + * Because \f$\MicroTeX\f$ might be used on platforms without working + * font renderer/provider, and it is capable of drawing paths anyways, + * there are two different kind of font files. + * + * + * \section font_usage Using Fonts + * \f$\MicroTeX\f$ can be compiled to just use one specific render type. + * Depending on your usecase, you might want to add one of the following + * build arguments: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
+ * MesonCMake
Support for both glyph path and typeface render types (default)`-DGLYPH_RENDER_TYPE=both``-DGLYPH_RENDER_TYPE=0`
Only include support for rendering glyphs via the typeface render type`-DGLYPH_RENDER_TYPE=typeface``-DGLYPH_RENDER_TYPE=2`
Only include support for rendering glyphs via the path render type`-DGLYPH_RENDER_TYPE=path``-DGLYPH_RENDER_TYPE=1`
+ * + * \subsection font_usage_manual Manually + * In order to add fonts to \f$\MicroTeX\f$, you need to provide a + * microtex::FontSrc to microtex::MicroTeX::init() (note that the + * provided font needs to be a mathfont) or microtex::MicroTeX::addFont(). + * + * If you intend to manually specify Fonts, you can either use + * microtex::FontSrcFile or microtex::FontSrcData. Both constructors of + * each of the classes have an optional second parameter. If you intend + * to you the glyph path render type you need to leave this empty. + * Otherwise, you'll want to specify the path to the opentype font file + * that the platform load and draw glyphs from (typeface path). + * + * @code + * const FontSrcFile math = FontSrcFile {"path/to/latinmodern-math.clm1", "path/to/latinmodern-math.otf"}; + * microtex::MicroTeX::init(&math); + * @endcode + * + * \subsection font_usage_fontsense FontSense (Automatic) + * If you don't need/want to specify any specific fonts, you can also + * use FontSense to let \f$\MicroTeX\f$ automatically scan the system + * for available fonts. + * + * To use FontSense simply provide microtex::MicroTeX::init() with + * microtex::InitFontSenseAuto: + * @code + * microtex::InitFontSenseAuto autoinit; + * microtex::MicroTeX::init(autoinit); + * @endcode + * + * microtex::MicroTeX::init will throw microtex::ex_invalid_param, + * should no font be available on the system. You may want to catch + * this, you may not... (Depending on the kind of userbase that will be + * using your application) + * + * But if \f$\MicroTeX\f$ was installed via a precompiled package, + * at least one mathfont should always be available. + * + * \subsubsection font_usage_fontsense_dirs FontSense Directories + * FontSense will look in the following directories for files with + * `.clm1` and `.clm2` extensions (note that .clm1 files need a .otf + * file with the same filestem (name before the last dot) in the same + * directory as itself in order to be recognized): + * + * + * + * Note that MicroTeX will need to be compiled with `-DHAVE_AUTO_FONT_FIND=true` (Meson) / `-DHAVE_AUTO_FONT_FIND=ON` (CMake). But this being toggled on is their default behaviour. + * + * \section font_generation Generating new CLM fonts + * \f$\MicroTeX\f$ provides an `otf2clm` script that automatically + * generates the correct CLM font(s) from any opentype font. + * + * When \f$\MicroTeX\f$ is available as package from your distribution, + * the script should be part of the `microtex-tools` subpackage + * (assuming your distro does split microtex into subpackages), and + * ready to execute by invoking `microtex-otf2clm`. Alternatively, it + * is in-tree located in `prebuilt/otf2clm.sh` (note you need to have + * fontforge version 20200314 or later installed and on your PATH, and + * that cwd needs to be `prebuilt/` when invoking). + * + * \subsection font_generation_usage Usage + * + * \subsubsection font_generation_usage_single Convert single font + * ```sh + * --single \\ + * \\ + * \\ + * \\ + * [comma seperated font-style list] + * ``` + * + * Possible font styles are: + *
    + *
  • `  rm:` Roman / Serif
    • + *
  • `  bf:` Bold
    • + *
  • `  it:` Italic
    • + *
  • `  cal:` Calligraphic
    • + *
  • ` frak:` Fraktur
    • + *
  • `  bb:` Blackboard
    • + *
  • `  sf:` Sans Serif
    • + *
  • `  tt:` Typewriter / Monospace
    • + *
+ * + * Specifying a font-style list is optional. If you do not provide + * anything or provide an empty string, `otf2clm` will automatically + * attempt to determine a fitting font-style.
+ * The automatic detection is however only capable if detecting the + * following styles: `rm, bf, it, tt`. + * + * \subsubsection font_generation_usage_batch Convert multiple fonts + * ```sh + * --batch \\ + * \\ + * \\ + * + * ``` + * + * It is not possible to define font styles in batch mode. otf2clm will + * set the font-style of each specific font purely based on the result + * of its auto-detection (same limits as in \ref font_generation_usage_single). + * + * \section font_format Font Format + * \subsection font_format_meta Metadata + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
NameTypeSizeDescription + *
Magic bytes`char[3]`3 bytesExpected data: clm
Version`unsigned short`2 bytesThe current version of the file format (i.e. currently `5`), \f$\MicroTeX\f$ will reject anything but the latest version
Glyph Type`unsigned char`1 byteContains `0x02` if the font file contains glyph paths, `0x01` otherwise
Font name`char*`use `strlen()`Contains the name of the font. Read this string until you hit a `NULL` byte.
Family name`char*`use `strlen()`Contains the family name of the font. Read this string until you hit a `NULL` byte.
Is math font`boolean`1 byte`0x01` if the font contains math constants, `0x00` otherwise
Style`unsigned short`2 bytesBitset representing the style of the font. + *

Bits are: + *

    + *
  • `  rm: 0b00000001` (Roman / Serif)
    • + *
  • `  bf: 0b00000010` (Bold)
    • + *
  • `  it: 0b00000100` (Italic)
    • + *
  • `  cal: 0b00001000` (Calligraphic)
    • + *
  • ` frak: 0b00010000` (Fraktur)
    • + *
  • `  bb: 0b00100000` (Blackboard)
    • + *
  • `  sf: 0b01000000` (Sans Serif)
    • + *
  • `  tt: 0b10000000` (Typewriter / Monospace)
    • + *
+ *

+ *
Em (Size)`unsigned short`2 bytesThe em size of the font
X-Height`unsigned short`2 bytesThe height of lower case letters such as "x". A negative number indicates the value could not be computed (the font might have no lower case letters because it was upper case only, or didn’t include glyphs for a script with lower case letters).
Ascent`unsigned short`2 bytesThe font's ascent
Descent`unsigned short`2 bytesThe font's descent
+ * \subsection font_format_unicode Unicode Glyph Map + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
NameTypeSizeDescription + *
Number of Glyphs`unsigned short`2 bytesThe number of items in the glyph map. Required to read the next row
Unicode Glyph + * `typedef struct { unsigned int codepoint; unsigned short glyph_id; } UniMapItem;`
+ * `UniMapItem[Number of Glyphs]` + * 		+ * 6*(Number of Glyphs) bytes + * This is an array that should be parsed into some kind of map structure
+ * \subsection font_format_kerning Kerning Class + * // TODO + * \subsection font_format_ligatures Ligatures + * // TODO + * \subsection font_format_math Math Constants + * // TODO + * \subsection font_format_glyphs Glyphs + * // TODO + * + */ \ No newline at end of file diff --git a/doc/mainpage.h b/doc/mainpage.h new file mode 100644 index 00000000..f870f567 --- /dev/null +++ b/doc/mainpage.h @@ -0,0 +1,228 @@ +/** \mainpage µTeX + * + * A dynamic, cross-platform, and embeddable LaTeX rendering library + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Version1.0.0
LicenseMIT
AuthorsNanoMichael <artiano@hotmail.com>
Forgehttps://github.com/NanoMichael/MicroTeX
+ * + * \section introduction Introduction + * + * \f$\MicroTeX\f$ is a versitile library, capable of very efficiently + * rendering most \f$\LaTeX\f$ equations on any surface that provides + * postscript-esque vector draw instructions. If you are interested in + * implementing \f$\MicroTeX\f$ for such a surface, that doesn't have + * support yet, read this document. + * + * Currently, \f$\MicroTeX\f$ supports the following libraries and + * frameworks: + *
    + *
  • Cairo
    • + *
  • QT
    • + *
  • win32
    • + *
  • WASM
    • + *
  • GTK
    • + *
+ * + * \section install_sec Installation + * + * \subsection prebuilt Install µTeX using precompiled packages + * + * \subsection compile Compile µTeX from source + * + * To build \f$\MicroTeX\f$ yourself, please ensure that all of the + * following dependencies are installed on your operating system and + * accesible by pkg-config. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Librarypkg-configWebsite
For the Cairo platform:
libfontconfigfontconfigfreedesktop.org/wiki/Software/fontconfig/
Cairocairocairographics.org
Cairo FreeTypecairo-ftcairographics.org
Pangopangopango.gnome.org
Pango Cairopangocairopango.gnome.org
For the QT platform:
QT5 Guiqt5qt.io
kde.org/community/whatiskde/kdefreeqtfoundation/
For the win32 platform:
GDI+libgdiplusdocs.microsoft.com/en-us/windows/win32/gdiplus/-gdiplus-gdi-start
github.com/mono/libgdiplus
For the WASM platform:
Emscriptenn/aemscripten.org
For the GTK4 widget (also requires the dependencies listed under Cairo):
GLibglib-2.0wiki.gnome.org/Projects/GLib
GTK 4gtk4gtk.org
Cairo SVGcairo-svgcairographics.org
+ * Please note, that the demo applications for a corresponding library might have additional dependencies + * + * \subsubsection meson Build µTeX using Meson + * If you are able to use meson, please look at the meson_options.txt + * in the root directory of \f$\MicroTeX\f$ and figure out what + * platforms you wish to use. Then invoke: + * @code + * meson _build -D