[jira] [Commented] (JDO-798) Proposal – Migrate Specification to LaTeX
[ https://issues.apache.org/jira/browse/JDO-798?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17410818#comment-17410818 ] Tilmann Zäschke commented on JDO-798: - Another advantage: * There are plugins that support automatic syntax highlighting for code snippets, even in color or with line numbers, if that is desired. A potential disadvantage: * I only really used TexnicCenter so far, but I found it somewhat cumbersome to set up. It defaulted to the Acrobat PDF viewer, which does not support back-linking. Also MikTex had to be installed separately, and automatic installation of plugins and fonts sometime required manual intervention. > 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. > 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|https://www.xm1math.net/texmaker/]. > 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 t
[jira] [Commented] (JDO-798) Proposal – Migrate Specification to LaTeX
[ https://issues.apache.org/jira/browse/JDO-798?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17410823#comment-17410823 ] Tobias Bouschen commented on JDO-798: - I know what you mean. Setting it up for windows is somewhat cumbersome. With Linux, on the other hand, it works like a charm as it is available in most (if not all) major package repositories. With back-linking, do you mean selecting a section in the pdf and jumping to its source? If so, this did work out of the box for me with Texmaker. Additionally, as there are Github actions that support building latex documents, we could also set up jobs to build the document for us for every pr. This would mean that we could check the generated version of the changes without having to build them ourselves (probably mostly useful for reviews). > 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. > 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|https://www.xm1math.net/texmaker/]. > 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 iter
