[ https://issues.apache.org/jira/browse/JDO-798?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Tobias Bouschen updated JDO-798: -------------------------------- Summary: Proposal – Migrate Specification to LaTeX (was: Proposa – Migrate Specification to LaTeX) > Proposal – Migrate Specification to LaTeX > ----------------------------------------- > > Key: JDO-798 > URL: https://issues.apache.org/jira/browse/JDO-798 > Project: JDO > Issue Type: Task > Reporter: Tobias Bouschen > Assignee: Tobias Bouschen > Priority: Minor > > 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. > In my opinion, switching to LaTeX would provide multiple benefits: > * 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. > * 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. > * 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. > * 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. > * 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. > * 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. > * LaTeX should be platform-independent, meaning the generated document > should look the same on all platforms. > * 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 busiwork 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. -- This message was sent by Atlassian Jira (v8.3.4#803005)