TeXBriX 0.2.10

A granular approach to LaTeX

TeXBriX

A granular approach to LaTeX

Texbrix is a file standard that comes with useful tools for managing and exporting latex code

Installation

Download it from PyPi:

pip install TeXBriX

TeXBriX uses Python 3.

What are TexBriX?

TeXBriX are intended as both a note taking and a document writing system. A Brik is a small text document which can contain references to other briks.

Intended Usecase

Instead of writing all of your notes in a subject into a long .tex file, like many people do, you instead write a Brik for each note, containing all relevant references. If the time comes to export a result in a paper (or many results in a book), you write a top-level Brik referencing all results you want to include. TeXBriX then generates a .tex excerpt of your notes directory containing only the depencency tree of referenced Briks.

Why not just use LaTeX' input?

Say document a.tex includes documents b.tex and c.tex, where the content of d.tex is a prerequisite for c.tex, as well as b.tex. Since you want the content of b.tex and c.tex to be useable on their own, you incude d.tex in both of them. This results in the problem, that the content of d.tex is present twice in a.tex. TeXBriX makes all of those documents useable on their own while only importing prerequisites once, no matter whether they are used multiple times or not. (There is still a way to have content printed multiple times by explicitly placing it inside a document using \brikinsert).

Using TeXBriX, you would write the content of a, b, c and d in files a.brik, b.brik, c.brik and d.brik, respectively using the syntax stated below. If you want your final documents to have a special appearance, or make some makros a prerequisite of all BriKs in your project, you would write your own template file. You can then generate a LaTeX excerpt of your project containing only the content you specify with it's prerequisites by calling texbrix.

Usage

Command Line

To generate a LaTeX document from your TeXBriX structure use the command

texbrix <top TeXBriK>

This will by default use the default_template located in the src directory. If you would like to use another template file instead (e.g. to define Math environments which should be expected to work in all BriX), pass it via the optional -template Flag.

It is recommended to simplify the compilation process using Makefiles.

Brik Structure

Currently there are two different types of Brix: Ordinary Brix and MathBrix

Ordinary Brix

Ordinary Brix are files with a .brik extension. A TeXBriK has the following basic structure:

\usepackage{<some LaTeX package required for this BriK's content>}
...
\usepackage{<more packages>}
\prerequisite{<some brik>}
...
\prerequisite{<some other brik>}
\begin{content}
This is ordinary \LaTeX.
\newline

...
\brikinsert{<yet another brik>}

...
\end{content}

Both the \prerequisite{} and the \brikinsert{} Commands take a file path relative to the BriK they are mentioned in, as well as absolute paths (without the .brik or .mbrik-Postfix). \prerequisite{} will make sure the mentioned BriK is included with all it's dependencies before the content, while not generating any duplicates. \brikinsert{} will insert the mentioned brik on the given position (with all not yet included dependencies) no matter whether or not it has been previously used.

Mathbrix

Mathbrix are files with an .mbrik extension. They behave mostly like regular briks, with the exception that they can have multiple top-level \begin{...} ... \end{...} statements. These are intended to be used for theorem, proof, definition, etc. Blocks.

In the future mathbriks will allow you to state theorems etc. without printing their proofs (e.g. for short excerpts).

Template File

You can write the general structure of your final LaTeX document in a template file (passed to TeXBriX via the -template argument). Here you should use the following placeholders:

Placeholder	Meaning
$packages	In the place where you want the LaTeX imports to be inserted
$content	Where you want the BriK's content to be

Other tools

VSCodium

Add to settings.json

"files.associations": {
	"*.brik": "latex",
        "*.texbrik": "latex
}

If you use the latex-workshop extension:

"latex-workshop.latex.tools":[
	{
		"name": "texbrix",
		"command": "texbrix",
		"args": [
			"%DOC%.brik"
		],
		"env": {}
	},
	{
		"name": "pdflatex",
		"command": "pdflatex",
		"args": [
			"-synctex=1",
			"-interaction=nonstopmode",
			"-file-line-error",
			"%DOC%.tex"
		],
		"env": {}
	}
]
"latex-workshop.latex.recipes":[
	{
		"name": "texbrix then pdflatex",
		"tools": [
			"texbrix",
			"pdflatex"
		]
	}
]