[
https://issues.apache.org/jira/browse/JDO-798?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Tobias Bouschen updated JDO-798:
--------------------------------
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|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.
was:
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.
> 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)
