From 7fc4f406fe13ec35fae2401b01ff911fb627f87f Mon Sep 17 00:00:00 2001 From: Andreas Stefl Date: Tue, 18 Aug 2026 15:28:30 +0200 Subject: [PATCH] docs(html): deprecate the html config options nothing reads MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `HtmlConfig::embed_outline`, `no_drm`, `background_image_format` and `background_image_dpi` are read nowhere in the library: no outline is written, no output carries a restriction to lift, and no view renders a background image to a file. Setting one has done nothing for a while, which the header did not say. Marked deprecated in the header and in the python, wasm, jni and apple bindings that carry them. They keep storing and returning what is set — no caller breaks — so removing them is a later, breaking change. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01EPasn1P1Y4xGehbRdWWFwY --- CHANGELOG.md | 3 +++ apple/include/OdrCoreObjC/ODRHtml.h | 4 ++++ jni/java/app/opendocument/core/HtmlConfig.java | 13 +++++++++---- python/src/bind_html.cpp | 12 ++++++++---- src/odr/html.hpp | 7 ++++--- wasm/js/index.d.ts | 4 ++++ 6 files changed, 32 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 387a4c07..794eda2f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,6 +29,9 @@ The release run heads these entries with the version and opens a fresh short values is still a csv. One record is a line, not a table. - A large text file appears at once: sizing the line numbers laid the page out once per line. A megabyte took 38s and now takes under a second. +- **Deprecated** `HtmlConfig::embed_outline`, `no_drm`, + `background_image_format` and `background_image_dpi`. Nothing has read them + for a while; they still store and return what is set. ## v6.7.1 - 2026-08-16 diff --git a/apple/include/OdrCoreObjC/ODRHtml.h b/apple/include/OdrCoreObjC/ODRHtml.h index 8b46496c..816eef9c 100644 --- a/apple/include/OdrCoreObjC/ODRHtml.h +++ b/apple/include/OdrCoreObjC/ODRHtml.h @@ -100,7 +100,9 @@ NS_SWIFT_NAME(HtmlConfig) @property(nonatomic) uint8_t htmlIndent; @property(nonatomic, copy) NSString *htmlIndentString; +/// @deprecated Inert. @property(nonatomic, copy) NSString *backgroundImageFormat; +/// @deprecated Inert. @property(nonatomic) double backgroundImageDpi; /// Render only pages `[begin, end)`, 0-based. `nil` end means to the last page. @@ -111,7 +113,9 @@ NS_SWIFT_NAME(HtmlConfig) @property(nonatomic, copy) NSArray *pdfDualLayerFallbackFonts; @property(nonatomic) double pdfDualLayerFallbackFontSizeAdjust; +/// @deprecated Inert. @property(nonatomic) BOOL noDrm; +/// @deprecated Inert. @property(nonatomic) BOOL embedOutline; @property(nonatomic, copy, nullable) NSString *outputPath; diff --git a/jni/java/app/opendocument/core/HtmlConfig.java b/jni/java/app/opendocument/core/HtmlConfig.java index 4d9c3a61..fd1cc301 100644 --- a/jni/java/app/opendocument/core/HtmlConfig.java +++ b/jni/java/app/opendocument/core/HtmlConfig.java @@ -42,8 +42,11 @@ public final class HtmlConfig { public int htmlIndent = 1; public String htmlIndentString = "\t"; - public String backgroundImageFormat = "png"; - public double backgroundImageDpi = 144.0; + /** @deprecated Inert. */ + @Deprecated public String backgroundImageFormat = "png"; + + /** @deprecated Inert. */ + @Deprecated public double backgroundImageDpi = 144.0; public int pageRangeBegin = 0; /** {@code null} renders to the end of the document. */ @@ -55,9 +58,11 @@ public final class HtmlConfig { }; public double pdfDualLayerFallbackFontSizeAdjust = 0.5; - public boolean noDrm = false; + /** @deprecated Inert. */ + @Deprecated public boolean noDrm = false; - public boolean embedOutline = false; + /** @deprecated Inert. */ + @Deprecated public boolean embedOutline = false; /** {@code null} keeps output in the cache directory. */ public String outputPath; diff --git a/python/src/bind_html.cpp b/python/src/bind_html.cpp index 956b1d17..ad0b8fa6 100644 --- a/python/src/bind_html.cpp +++ b/python/src/bind_html.cpp @@ -94,9 +94,11 @@ void odr_python::bind_html(py::module_ &m) { .def_readwrite("html_indent", &odr::HtmlConfig::html_indent) .def_readwrite("html_indent_string", &odr::HtmlConfig::html_indent_string) .def_readwrite("background_image_format", - &odr::HtmlConfig::background_image_format) + &odr::HtmlConfig::background_image_format, + "Deprecated and inert.") .def_readwrite("background_image_dpi", - &odr::HtmlConfig::background_image_dpi) + &odr::HtmlConfig::background_image_dpi, + "Deprecated and inert.") .def_readwrite("page_range_begin", &odr::HtmlConfig::page_range_begin) .def_readwrite("page_range_end", &odr::HtmlConfig::page_range_end) .def_readwrite("pdf_text_mode", &odr::HtmlConfig::pdf_text_mode) @@ -104,8 +106,10 @@ void odr_python::bind_html(py::module_ &m) { &odr::HtmlConfig::pdf_dual_layer_fallback_fonts) .def_readwrite("pdf_dual_layer_fallback_font_size_adjust", &odr::HtmlConfig::pdf_dual_layer_fallback_font_size_adjust) - .def_readwrite("no_drm", &odr::HtmlConfig::no_drm) - .def_readwrite("embed_outline", &odr::HtmlConfig::embed_outline) + .def_readwrite("no_drm", &odr::HtmlConfig::no_drm, + "Deprecated and inert.") + .def_readwrite("embed_outline", &odr::HtmlConfig::embed_outline, + "Deprecated and inert.") .def_readwrite("output_path", &odr::HtmlConfig::output_path) .def_readwrite("resource_locator", &odr::HtmlConfig::resource_locator); diff --git a/src/odr/html.hpp b/src/odr/html.hpp index 2f7cfa8e..3a908564 100644 --- a/src/odr/html.hpp +++ b/src/odr/html.hpp @@ -155,8 +155,9 @@ struct HtmlConfig { std::uint8_t html_indent{1}; std::string html_indent_string{"\t"}; - // background image + /// @deprecated Inert: no view renders a background image to a file. std::string background_image_format{"png"}; + /// @deprecated See @ref background_image_format. double background_image_dpi{144.0}; // Paged-document page range (currently honored by the PDF pipeline): render @@ -177,10 +178,10 @@ struct HtmlConfig { "Arial", "Helvetica", "Liberation Sans", "DejaVu Sans", "Nimbus Sans"}; double pdf_dual_layer_fallback_font_size_adjust{0.5}; - // drm options + /// @deprecated Inert: no output carries a restriction to lift. bool no_drm{false}; - // outline options + /// @deprecated Inert: an outline is never written. bool embed_outline{false}; std::optional output_path; diff --git a/wasm/js/index.d.ts b/wasm/js/index.d.ts index d2e3de29..66b1e569 100644 --- a/wasm/js/index.d.ts +++ b/wasm/js/index.d.ts @@ -74,9 +74,13 @@ export interface HtmlConfig { editable?: boolean; textDocumentMargin?: boolean; formatHtml?: boolean; + /** @deprecated Inert. */ embedOutline?: boolean; + /** @deprecated Inert. */ noDrm?: boolean; + /** @deprecated Inert. */ backgroundImageFormat?: string; + /** @deprecated Inert. */ backgroundImageDpi?: number; pageRangeBegin?: number; pageRangeEnd?: number;