update packages

lisp/ox-tufte/src/README.org

@@ -1,17 +1,37 @@
-#+TITLE: Ox-tufte
+#+TITLE: ox-tufte
 #+AUTHOR: The Bayesians Inc.
 
-[[https://melpa.org/#/ox-tufte][file:https://melpa.org/packages/ox-tufte-badge.svg]]
-[[https://stable.melpa.org/#/ox-tufte][file:https://stable.melpa.org/packages/ox-tufte-badge.svg]]
+This is an [[https://orgmode.org/manual/Exporting.html#index-export-back_002dend][export backend for Org mode]] that exports buffers to HTML that is
+compatible with [[https://edwardtufte.github.io/tufte-css/][Tufte CSS]].
 
-* Changes since version 2.x
-- =ox-tufte-init= is no longer needed in addition to loading the library and has
-  been removed.
-- inline margin-note syntax changes
-  - inline margin-note-as-macro syntax has been added.
-  - margin-note-as-link syntax has been un-deprecated.
-  - all three inline margin-note syntaxes (=-as-babel-call=, =-as-macro=,
-    =-as-link=) are documented with their respective limitations and quirks.
+* Changes since version 3.x
+Version 4.x alters some of the internals considerably from the 3.x version.
+Notably some configuration options have changed.  See below for details.
+
+** As of version 4.2.x
+- Some care is taken to ensure that the IDs of the generated HTML elements
+  (e.g., footnote references) are reproducible.  In case the IDs vary across
+  builds, it's a bug.  Versions 4.1.x were supposed to implement this, but those
+  releases were botched.
+** As of version 4.0.x
+- Altering variables =org-html-checkbox-type= and =org-html-divs= no longer has
+  any effect.  To provide default values for the corresponding options, use
+  variables =org-tufte-html-checkbox-type= and =org-tufte-html-sections=
+  respectively.  The properties are still called =:html-checkbox-type= and
+  =:html-divs=, however.
+- Similarly, =HTML_DOCTYPE= (as well, variable =org-html-doctype= and property
+  =:html-doctype=) and =HTML_CONTAINER= (as well, variable
+  =org-html-container-element= and property =:html-container=) keywords and
+  =html5-fancy= option (as well, variable =org-html-html5-fancy= and property
+  =:html-html5-fancy=) are disabled.  Altering these values from the defaults is
+  not supported.
+- The =tufte-html= backend definition makes explicit the options that it
+  overrides compared to the =html= backend.
+- New command =org-tufte-convert-region-to-html= added.
+- Invoking =org-export-string-as= now works ([[https://github.com/ox-tufte/ox-tufte/issues/22][#22]]).
+- Loading =ox-tufte= now advises =org-export-as=.  For advanced uses, the depth
+  of the installed advice is user-configurable via =setopt= (see
+  =org-tufte-export-as-advice-depth=).
 * Introduction
 [[https://edwardtufte.github.io/tufte-css/][Tufte CSS]] has visually appealing defaults for webpages and supports (among other
 things) margin and side notes. Unfortunately, /Tufte CSS/ makes a number of
@@ -64,6 +84,8 @@ And then in your ~init.el~ (or equivalent):
 It's important that you download [[https://github.com/edwardtufte/tufte-css][tufte css]] ([[https://github.com/edwardtufte/tufte-css/releases/tag/v1.8.0][v1.8.0]]) and place it on your server
 (with the fonts).
 
+[[https://repology.org/project/emacs:ox-tufte/versions][file:https://repology.org/badge/vertical-allrepos/emacs:ox-tufte.svg]]
+
 ** Usage
 The recommended way to use =ox-tufte= is *with* [[https://orgmode.org/manual/CSS-support.html][the default style provided by
 ox-html]]. Include =tufte.css= followed by =src/ox-tufte.css= (strictly in that
@@ -273,13 +295,15 @@ class with an =#+attr_html= annotation.
 There may be some experimental extensions in =src/ox-tufte-experimental.css=.
 If desired, this css file should be included /after/ =src/ox-tufte.css=.
 * Limitations
-- The generated HTML is not compatible with [[https://orgmode.org/worg/code/org-info-js/][org-info.js]]. This is because
-  =ox-tufte= customizes the value of =org-html-divs= to align it with what's
-  expected by =tufte-css=.
-- Code blocks (multiline) currently behave /only/ in a "fullwidth" manner. I.e.,
-  if there is sidenote content from previous paragraph, or a block margin-note
-  it will push the code block down.
-
+** Incompatibility with =org-info.js=
+The generated HTML is not compatible with [[https://orgmode.org/worg/code/org-info-js/][org-info.js]]. This is because
+=ox-tufte= customizes the value of =org-html-divs= to align it with what's
+expected by =tufte-css=.
+** Code blocks are only fullwidth
+Code blocks (multiline) currently behave /only/ in a "fullwidth" manner. I.e.,
+if there is sidenote content from previous paragraph, or a block margin-note it
+will push the code block down.
+** Constraints inherited from =tufte-css=
 Additionally, =ox-tufte= presently inherits the following limitations from
 [[https://edwardtufte.github.io/tufte-css/][tufte-css]]:
 - Footnotes/sidenotes cannot contain nested footnotes/sidenotes.
@@ -287,6 +311,11 @@ Additionally, =ox-tufte= presently inherits the following limitations from
   elements).
 - Captions for =iframe-wrapper= blocks aren't supported.
 - The generated HTML must (and does) use an =html5= doctype.
+** Incompatibility with =org-special-block-extras=
+As of [2024-01-12 Fri], =org-special-block-extras= is incompatible with
+=ox-tufte=.  As noted in [[https://github.com/ox-tufte/ox-tufte/issues/20#issuecomment-1880626278][this comment]], the incompatibility is primarily due to
+hard-coded checks in =org-special-block-extras= which are too restrictive and
+need to be relaxed.
 * Customization
 ** Footnotes section at bottom
 The behaviour depends on the =:footnotes-section-p= option (which uses the value
@@ -343,3 +372,16 @@ For footnote references, something like below would work
 * References
 - https://edwardtufte.github.io/tufte-css/
 - https://gitlab.com/snippets/22309
+
+* CHANGELOG                                                         :ARCHIVE:
+** Changes since version 2.x
+:PROPERTIES:
+:ARCHIVE_TIME: 2024-01-12 Fri 15:14
+:END:
+- =ox-tufte-init= is no longer needed in addition to loading the library and has
+  been removed.
+- inline margin-note syntax changes
+  - inline margin-note-as-macro syntax has been added.
+  - margin-note-as-link syntax has been un-deprecated.
+  - all three inline margin-note syntaxes (=-as-babel-call=, =-as-macro=,
+    =-as-link=) are documented with their respective limitations and quirks.