[
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 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.
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
