Since writers are normally only used synchronously (i.e. to write one document
at a time), we don't guard modifications to their internal
state (e.g. temporarily replacing the string.Builder in WriteNodesAsString)
against race conditions.
The package global `orgWriter` and corresponding use cases of it (`org.String`,
`$node.String`) break that pattern - the writer is potentially used from
multiple go routines at the same time. This results in race conditions that
manifest as error messages like e.g.
could not write output: runtime error: invalid memory address or nil pointer dereference. Using unrendered content.
Additionally, since we catch panics in `Document.Write`, the corresponding
stack trace is lost and dependents of go-org never know what hit them.
As using a writer across simultaneously across go routines is not a standard
pattern, we'll sync the use of the global `orgWriter` instead of trying to make
the actual writer threadsafe; less code noise for the common use case.
current support for latex fragments was inline only, i.e. lines containing block
elements (e.g. a line starting with `* `, i.e. a headline) will not be parsed
as part of the latex fragment but the respective block element. Parsing latex
blocks at the block level should fix that. Note that in any case we don't do
any processing and just emit the raw latex (leaving the rendering to e.g. js).
The org mode toc OPTION does not just support true/false - it also allows
specifying the max headline level [1] to be included in the toc.
[1] headline level as seen in org mode - not the html tag level
We want original whitespace to be rendered in some cases (e.g. verse
blocks). This requires information about the original whitespace to be
preserved during paragraph parsing. As html ignores (collapses) whitespace by
default we don't have to adapt the html writer and can just selectively enable
rendering of the preseverved whitespace wherever we want it using
css (white-space: pre).
To differentiate meaningful whitespace from document structure based
indentation (i.e. list item base indentation) we need to introduce
document.baseLvl. A paragraph by itself does not have enough information to
differentiate both kinds of whitespace and needs this information as context
[0].
As we're already touching list indentation i went along and improved (fixed?)
descriptive list item indentation rendering in the org writer (it should match
emacs tab behavior - i.e. indent subsequent lines up to the `:: `).
[0] e.g. list items can contain blank lines - a paragraph starting with a blank
line would not know that it is part of a list item / has a base indentation -
the blank line would suggest a baseLvl of 0.
WriteNodesAsString is simple enough to implement but exposing it is helpful in
the implementation of extending writers and we don't aim to keep writer a small
interface so let's expose it.
- Remove unused footnote section title option
- Move away from maintaining a list of footnotes in the document (only needed
for html export, potential maintainance overhead when modifying the document)
and rather only build it on export when required.
- HTML export: Rename all footnotes to numbers (so we can support anonymous
footnote references by assigning them a number) and export footnotes in order
of reference, not definition. The implementation of this makes it natural to
also stop exporting unused footnote definitions so we do that as well.
Being able to very easily get the original [1] Org mode content seems like
something that will come up quite often and is very little code.
[1] it's not really the original content, but rather the pretty printed version
of that - as the semantics don't change it shouldn't matter.
The existing approach made it hard to extend existing writers.
With this change, replacing individual methods of a writer is possible by
embedding it.
Sharing the WriteNodes function also removes some unnecesseray duplication, so
win win.
Unlike the other BufferSettings, #+OPTIONS: specifies multiple options and we
cannot just look it up in either BufferSettings or DefaultSettings - both have
to be checked
Leftover from the days before BufferSettings & DefaultSettings - now that those
exists the status keywords are actually defined in
- DefaultSettings["TODO"] for the default
- BufferSettings["TODO"] for any customizations
Also ! i < len => i >= len because it's easier on the eyes
- Footnotes separator rather than headline to get around i18n
- Warn on footnote redefinition
- Do not export footnote definitions at point of definition, only in the
footnote section.
- Do not automatically exclude Footnotes section to get around possibly hiding
other content of such a section - and i18n.
The user has the choice of explicitly hiding the section via a :noexport:
tag.
and some other refactoring
- enable logging by default: debug was a bad name - it's error logging that I
just want to hide in tests
- don't panic (all the time)
- use a logger. this allows us to add more information - like the path of the
parsed file!
Until now the footnotes section was parsed but not included in the resulting
AST - his required rebuilding it in the OrgWriter. It feels cleaner to include
it in the AST and only exclude it in the export
including org files is more complex - e.g. footnotes need to be namespaced to
their source file. org does this by prefixing each included files footnotes
with a number - but even that is not enough as it doesn't guarantee
uniqueness.
As I don't have a usecase for it, I'll avoid the additional complexity for
now.
until now buffersettings were always appended using \n which means the first
value would already be written as "\nVALUE". Not anymore.
Also we finally add an option to parse just the front matter. Still not
efficient as we tokenize the whole org file but i don't think saving a few
milliseconds would be worth making the code uglier.
