diff --git a/README.md b/README.md index 70530ae..d517eaf 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,15 @@ Filters to improve Pandoc's conversion to ODT. [Pandoc](https://github.com/jgm/p At the beginning of each file (it's just a plain text file, you can open with any text editor), there's a little text explaining what the filter does. Please read carefully that little text, and decide by yourself if that filter works for your particular case. In case where customization is possible, there are local variables at the very beginning of code, after text and *before* all `require`s. -None of these filters are guaranteed to work, as I wrote them only to address Pandoc's problems in ODT writer. Hopefully, in the near future none of them will be either necessary, as Pandoc's ODT writer become more robust. +None of these filters are guaranteed to work, as I wrote them only to address Pandoc problems in ODT writer. Hopefully, in the near future none of them will be either necessary, as Pandoc's ODT writer become more robust --- in fact, some of them are becoming obsolete as Pandoc improves that. + +One of these filters, `context-table-span.lua`, is targeted at ConTeXt writer, making fake row span. This also will be made obsolete as soon as Pandoc ConTeXt writer implements real row spans (already available at Pandoc AST). + +Another one, `abstract.lua`, is targeted at all but ODT and DOCX writers. Formerly, this filter was targeted at ODT, but Pandoc now handles abstract sections better than my filter. ## Requirements -- [Pandoc](https://github.com/jgm/pandoc), min. version: 2.8 +- [Pandoc](https://github.com/jgm/pandoc), min. version: 2.14 - `util.lua` in the same directory of each filter (see below) ## Installation @@ -23,9 +27,11 @@ You can use as many filters as you want. Each filter must have his own declarati pandoc -t odt+smart --lua-filter .lua .md -o .odt ~~~~ +You can also use a [Pandoc defaults file](https://pandoc.org/MANUAL.html#default-files), declaring these filters as you would normally do. I use and recommend this approach. + Each filter addresses a particular problem, and few of them need other filters to be run to properly work. Look at the text in the beginning of file, on `dependencies` item, to see if the filter depends upon other(s) filter(s). -All of them use `util.lua` (where I put common filter tasks, to reuse code), so **you need this file too**. +Near all of them use `util.lua` (where I put common filter tasks, to reuse code), so **you need this file too**. **IMPORTANT NOTE** @@ -34,16 +40,16 @@ All filters can go whatever directory you want, but an `util.lua` **must** be in ## Available filters -| Filter name | Description | Note | -| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `abstract.lua` | [*For all writers except `docx`*] Searches for `abstract` entry in metadata and creates a `Div` in the beginning of the document, containing markup from that entry. An `abstract-title` can also be set on metadata, so this filter will create a header (level 1, unnumbered) for the abstract. | If using with ODT writer, `odt-custom-styles.lua` **must** be run **after** this filter, to make abstract custom-style work. | -| `odt-anchors.lua` | Corrects anchors when converting to ODT, by adding bookmarks where anchors should come. This allows proper cross-referencing to these anchors with links along the text. | Currently, only figures and tables anchors are supported, where the anchor is inserted at the caption. Only figures and tables that *have an* `id` are processed (see [pandoc-crossref](https://lierdakil.github.io/pandoc-crossref/#general-options) for `autoSectionLabels`). (As of [Pandoc 2.2.2](https://github.com/jgm/pandoc/releases/tag/2.2.2), header bookmarks are created properly; see [Pandoc' issue 4358](https://github.com/jgm/pandoc/issues/4358)). | -| `odt-bib-style` | Corrects the style of bibliography when converting to ODT. This is necessary because Pandoc's ODT writer doesn't properly set this style. | `odt-custom-styles.lua` *must* also be used, and must be *after* this filter. Currently, all paragraphs in bibliography are turned into raw blocks with correct style. Because of this, only italics, bold and link markups are keep; all other markup in bibliography is lost. (see [Pandoc's issue 3459](https://github.com/jgm/pandoc/issues/3459)). | -| `odt-captions.lua` | Corrects captions when converting to ODT, by adding sequence fields to the number of caption. This allows the creation of lists of figures, tables, etc. | Currently, only figure and table captions are supported. Only images and tables with caption are processed. Expected syntax of caption is the generated by [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref). (see [Pandoc's issue 2401](https://github.com/jgm/pandoc/issues/2401)) | -| `odt-custom-styles.lua` | Workaround to use custom styles when converting to ODT. This filter turns divs and spans with custom style into ODT raw blocks/inlines, with the ODT code using the custom style. Also, headers with custom style (like the `{-}`, aka `unnumbered` class) are turned into ODT raw heading blocks with the custom style. If variable `useClassAsCustomStyle` is `true`, and element (div/span/header) doesn't have a `custom-style` attribute, then first `class` is used as style. | Currently, the following elements are **ignored** by this filter: blockquotes, lists (see `odt-lists.lua`), tables and code blocks (for `div` styles), and citations, smallcaps (see `odt-smallcaps.lua`), images, quotes, strikeouts, super and subscript, math and code inlines (for `span` styles). This filter will become useless when pandoc finally implement custom styles in ODT writer (see [Pandoc's issue #2106](https://github.com/jgm/pandoc/issues/2106)). | -| `odt-lists.lua` | Improves lists when converting to ODT, by adding list styles to lists, and apropriate paragraph styles to list items. | Only lists that are one level deep are supported; in lists with two or more levels, only the innermost level is improved, generating strange results. Currently, just italics, bold, links and line blocks are preserved in lists; all other markup is ignored. | -| `odt-smallcaps.lua` | Turns smallcaps into `span` with custom character style, when converting to ODT. This is necessary because LibreOffice default smallcaps is not *true* smallcaps, but rather *reduced capitalised* letters. | You need to use a `reference-doc` with the custom character style properly set. After this, change variable `smallcapsStyle` to the name of that custom character style. Example: use `Myriad Pro:smcp` as font in style configuration. `smcp` is the [OpenType smallcaps feature](https://en.wikipedia.org/wiki/List_of_typographic_features#Features_intended_for_bicameral_[cased]_alphabets_(Latin,_Greek,_Cyrillic,_etc.)). | -| `util.lua` | Utilities for use by other filters. | This file **must** be in the same directory of any filter that depends on it. | +| Filter name | Description | Note | +|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `abstract.lua` | [*For all writers except `docx` and `odt`*] Searches for `abstract` entry in metadata and creates a `Div` in the beginning of the document, containing markup from that entry. An `abstract-title` can also be set on metadata, so this filter will create a header (level 1, unnumbered) for the abstract. | | +| `odt-anchors.lua` | Corrects anchors when converting to ODT, by adding bookmarks where anchors should come. This allows proper cross-referencing to these anchors with links along the text. | Currently, only figures and tables anchors are supported, where the anchor is inserted at the caption. Only figures and tables that *have an* `id` are processed (see [pandoc-crossref](https://lierdakil.github.io/pandoc-crossref/#general-options) for `autoSectionLabels`). | +| `odt-bib-style` | Corrects the style of bibliography when converting to ODT. This is necessary because Pandoc's ODT writer doesn't properly set this style. | `odt-custom-styles.lua` *must* also be used, and must be *after* this filter. Currently, all paragraphs in bibliography are turned into raw blocks with correct style. Because of this, only italics, bold and link markups are keep; all other markup in bibliography is lost. (see [Pandoc's issue 3459](https://github.com/jgm/pandoc/issues/3459)). | +| `odt-captions.lua` | Corrects captions when converting to ODT, by adding sequence fields to the number of caption. This allows the creation of lists of figures, tables, etc. | Currently, only figure and table captions are supported. Only images and tables with caption are processed. Expected syntax of caption is the generated by [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref). (see [Pandoc's issue 2401](https://github.com/jgm/pandoc/issues/2401)) | +| `odt-custom-styles.lua` | Workaround to use custom styles when converting to ODT. This filter turns spans and headers with custom style into ODT raw inlines/blocks, with the ODT code using the custom style. If variable `useClassAsCustomStyle` is `true`, and element (span/header but also div) doesn't have a `custom-style` attribute, then first `class` is used as style. | Currently, the following elements are **ignored** by this filter: blockquotes, lists (see `odt-lists.lua`), tables and code blocks (for `div` styles), and citations, smallcaps (see `odt-smallcaps.lua`), images, quotes, strikeouts, super and subscript, math and code inlines (for `span` styles). | +| `odt-lists.lua` | Improves lists when converting to ODT, by adding list styles to lists, and apropriate paragraph styles to list items. | Only lists that are one level deep are supported; in lists with two or more levels, only the innermost level is improved, generating strange results. Currently, just italics, bold, links and line blocks are preserved in lists; all other markup is ignored. | +| `odt-smallcaps.lua` | Turns smallcaps into `span` with custom character style, when converting to ODT. This is necessary because LibreOffice default smallcaps is not *true* smallcaps, but rather *reduced capitalised* letters. | You need to use a `reference-doc` with the custom character style properly set. After this, change variable `smallcapsStyle` to the name of that custom character style. Example: use `Myriad Pro:smcp` as font in style configuration. `smcp` is the [OpenType smallcaps feature](https://en.wikipedia.org/wiki/List_of_typographic_features#Features_intended_for_bicameral_[cased]_alphabets_(Latin,_Greek,_Cyrillic,_etc.)). | +| `util.lua` | Utilities for use by other filters. | This file **must** be in the same directory of any filter that depends on it. | ## Contributing @@ -60,10 +66,10 @@ Below there are things I didn't resolve yet. Some of them are checked, either be - [ ] make TOC position configurable, by `[toc]` markup: - [ ] filter to find `[toc]` occurrences and substitute by custom template variable - [ ] custom template that recognizes that variable (*hard, I think...*) -- [ ] make pre-textual styles work: +- [x] make pre-textual styles work: - [x] get `unnumbered` headings as textual headings (without numbering) - [x] mark `unnumbered` headings, that come before first "normal" heading, with custom style - - [ ] avoid errors with these headings + - [x] avoid errors with these headings ## License @@ -71,4 +77,4 @@ This program is free software; you can redistribute it and/or modify it under th See [LICENSE](https://github.com/jzeneto/pandoc-odt-filters/blob/master/LICENSE) for details. -© 2018 José de Mattos Neto +© 2021 José de Mattos Neto