Code Index

The purpose of this document is to server as an introduction and overview of the codebase for MBDoc, and describe the main abstractions for the implementation. For more detalied descriptions see the documentation for the individual classes, go here here.

1 Directory structure

This project follows the MBPDS . This means that all of the source files can be found at the top part of the project directory, and that they use only relative includes, which means that all of the sources can be moved to another directory and compiled without problem. The folder Doc is where the documentation for the project is located, and MUST have no affect on compiling the library and executable.

2 The pipeline

In order to create documents from MBDoc files there are 4 distinct steps. Build Specification, Document filesystem creation, Preprocessing+parsing and finally compilation.

2.1 Build Specification

In order to compile something in the first place, the files that is a part of build has to be specified in some way. This can either be explicitly specified with a MBDocBuild.json, or implicitly specified on the command line. More on the build process and it's design can be found here.

In the codebase however, the build specficitation is rather simple. The structure is described fully by the MBDoc::DocumentBuild struct, and only the creation of it is implemented by it. It is then passed as is to the next step, and is mainly read from. More importantly, the document build only parses and validates that the files and sub builds and their sub builds and so on exist on disk, but no sources are actually parsed, which means that invalid sources are detected further along.

2.2 Document filesystem creation

This part of the pipeline creates the "document filesystem", which is an integral part in how references are resolved, and how the compiler can access the soures to compile. This also provides a natural output structures for many formats like HTML.

This part of the pipeline is implemented by MBDoc::DocumentFilesystem, and takes as input a parsed MBDoc::DocumentBuild. It also implements a generic interface, MBDoc::ReferenceResolver, that can be used to create custom reference resolvers.

For more information about how references are resolved and the design go here.

2.2.1 Invalid references

Another design consideration, is at which point unresolved references create an error. In traditional C/C++, unresolved references are only found at the end of the compilation process, when all the output is already created. This is however generally something that is suboptimal, if your document is invalid it is something that you want to find out quickly.

However, as semantic's might have a need to provide their own reference solvers, references might be valid despite not being able to be resolved by the resolving of MBDoc::DocumentBuild.

2.3 Preprocessing and parsing

Preprocessing and parsing is currently done together by MBDoc::ParsingContext. The main reason for this is because a lot of infrastructure in preprocessing and parsing is the same, and because it ensures that eventual intermediaries can be skipped. The class has many functions, but most are convenience. The SemanticallyAuthorative function requires only an input stream and a path to assign the document, which is needed as document paths are used for reference creation. Most function are provided to make it easier to create relative paths, as that's often needed when creating a project with multiple sub builds.

This class is designed to be able to be used stand alone, and isn't designed to be a separate part of the pipeline in software and is used directly by MBDoc::DocumentFilesystem. This is however the class that is solely responsible for implementing the grammar of the markup language.

How to use and interpret the structs and classes used in MBDoc::DocumentSource are described in FormatDatastructures, which is neccessary to understand if one wants to write a new compiler.

2.4 Compiling

This is the part where the implementation for the individual output formats and semantics are. In the philosophy of theproject it is described how output formats are always linkable. The way this is achieved is naturally dependant on the format, but more importantly, is the same for all semantics. But in order to facilitate easy creation of new target format and semantics, a generic abstract class is provided that specifices the needed interface to compile a MBDoc build, with the same semantics. The reason why a mixed semantic build is still not as easily implementable, is that they don't guarantee a uniform output structure. One semantic might bundle up all files in a large document, which means that the way absolute packets paths are serialized is not trivial, and not necceserially genericly solvable. Some formats like HTTP might solve this by just having a map from absolute packet path to relative url as a string. But as other formats might not encode references in a easily insertable string, this interace might not work. This is currently a work in progress on the compilation part.

The interface for the class is currently very simple, it only has to be able a compile MBDoc::DocumentSource, along with user provided format specific command line arguments.

2.5 DocCLI

MBDoc::DocCLI is the class "closest to main", which is responsible for handling all of the user input, for documentation of what options are supported and what they do go here. The class is however only ment to work as a glue combining all of the individual parts of the project together into a convenient user interface, and MUST NOT implement functionality that requires understanding of the internals of the other classes, and can only use the public functions exposed by the other classes. Preferably, it should be feasible to implement one's own CLI with the library part of the project, instead of acting as a map for different command line options.

These are the most central classes for the codebase, but naturally there are many more defined, mainly structs that are more data oriented. To get a complete documentation for the individual classes and functions, go to Code.