[JDO-798] Proposal – Migrate Specification to LaTeX

• Type: Task
• Status: Open
• Priority: Minor
• Resolution: Unresolved
• Component/s: specification
• Assignee: Tobias Bouschen
• Reporter: Tobias Bouschen
• Created: 05/Sep/21 14:54
• Updated: 17/Feb/22 19:56

Description

As we were having many issues with the current specification written using OpenOffice, I want to propose to migrate it to LaTeX.

If you are not aware, LaTeX is basically an open-source scripting language that can be used to define and build PDF documents. The content as well as the document layout is defined as plain text sources, from which the PDF is generated.

You can create LaTeX sources with any plain-text editor, but if you would like more support, there are also multiple IDEs for LaTeX. I think one of the most well known ones (and the one I used in the past) is TexMaker.

In my opinion, switching to LaTeX would provide multiple benefits:

1. The Specification sources would be held in plain-text files. As a result, they can be managed by git. As a result, it will be much easier to concurrently work on the same parts of the document as git can be used to resolve conflicts. Furthermore, as the sources are in plain text, it is much easier to review changes to the documents as you can just look at the diff.
2. It will be much easier to define a general styling (like header, footer, font, text size, etc.) for the entire document. This styling will be used everywhere unless explicitly defined otherwise in the text. Such local changes to the styling will be explicitly visible as they will be defined through commands. As a result it will be much easier to check where the styling no longer matches and why this is the case.
3. LaTeX supports a far more fine-grained control over the styling. If you are unhappy with the layout of a specific page/section/chapter (i.e. the location of a figure or an unseemly line break or page break), you have many different tools to adjust the formatting as necessary. While layouting in LaTeX can be fiddly as well, in my experience, it at least is never a mystery why a page has the layout is has.
4. The styling in LaTeX is much more customizable. You can change pretty much everything about the styling you want to. While this can take a lot of time if you have a very specific vision of how it is supposed to look or are trying to implement a very complex styling, it is easy to create a passable styling in a very short time.
5. LaTeX provides robust support for many automatically generated document features such as table of contents, bibliographies, indices, relative links to other parts of the document, etc. Most of these features are included in the default build, but if they are not (like bibliographies), additional steps can simply be defined in a build script (like a make file). As a result, you can simply build the entire document with a single command and don't have to worry about any automatically generated content not being up to date.
6. LaTeX provides a lot of additional helpful features like code sections with automatic code highlighting, automatically managed footnotes, figures with captions (which are actually bound to the figure), etc. And, even if a feature is not supported by default, it is very likely that there is a user-package to add support.
7. LaTeX should be platform-independent, meaning the generated document should look the same on all platforms.
8. Like the current OpenOffice document, LaTeX allows to split the content of the document into multiple files (i.e. a file per chapter). But, in Latex, the partitioning of the file (i.e. where a chapter/section starts) is always very apparent as this is defined through different commands.

My current idea would be to first define the general styling of the document (which will probably take a couple of iterations until we are completely happy with it) and then migrate the old documentation chapter by chapter. During this process, I would like to leave out the index and the assertions. I don't really see the value they provide and, to be honest, therefore don't feel like putting in the large amount of busywork they require. But if you think they are important, it will be easy to add them later on (which would also give us another opportunity to go through all indices and assertions and check whether they are correct).

To give you a better idea of the proposal, I will first create a small sample document (using a chapter of the current spec) to give a general overview of how a LaTeX-based Spec would work and what a possible layout would be.