Finish comment and documentation strings
This commit is contained in:
parent
90f2d88ea2
commit
7fa45f8c1a
@ -6,9 +6,8 @@
|
||||
;; Maintainer: Gerard Vermeulen <gerard.vermeulen AT posteo DOT net>
|
||||
;; Keywords: org, hypermedia
|
||||
|
||||
;; Since this library contains a lot of code from the Emacs ox-html
|
||||
;; library, see the ox-html library for its authors, maintainer and
|
||||
;; FSF copyright.
|
||||
;; See the Emacs ox-html library for its authors, maintainer and FSF
|
||||
;; Copyright, since ox-svg4css contains a lot of code from the ox-html.
|
||||
|
||||
;; This file is NOT part of GNU Emacs.
|
||||
|
||||
@ -27,21 +26,34 @@
|
||||
|
||||
;;; Commentary:
|
||||
|
||||
;; This library implements a HTML derived backend for Org export.
|
||||
;; It tries to address limitations of SVG images and CSS in HTML pages:
|
||||
;; 1. Firstly, it probes whether to export the SVG image as an "object" tag.
|
||||
;; 2. Secondly, it probes whether to include the SVG contents in the HTML.
|
||||
;; 3. Thirdly, it probes wheter to embed the SVG image in an "img" tag.
|
||||
;; 4. The option precedence order is "svg-as-object", "svg-inclusion",
|
||||
;; "org-html-inline-images", but disabling the latter disables the other
|
||||
;; options.
|
||||
;; This library implements an HTML derived backend for Org export.
|
||||
;; It tries to address limitations of SVG images and CSS in HTML pages.
|
||||
;; For each SVG image during HTML export:
|
||||
;; 1. It checks `svg-as-object' and "image in-lining" whether to
|
||||
;; embed the SVG image in an <object> tag.
|
||||
;; 2. If not, it checks `svg-inclusion' and "image in-lining"
|
||||
;; whether to copy the SVG contents to the HTML output.
|
||||
;; 3. If not, it falls back to checking "image in-lining" to treat the
|
||||
;; SVG image as any other image and to embed it in an <img> tag.
|
||||
;; 4. It is possible to set `svg-as-object' and `svg-inclusion':
|
||||
;; - For each SVG link by means of "#+ATTR_HTML: :svg-as-object t"
|
||||
;; and "#+ATTR_HTML: :svg-inclusion t".
|
||||
;; - Within file scope by means of "#+OPTIONS: svg-as-object:t" and
|
||||
;; "#+OPTIONS: svg-inclusion:t".
|
||||
;; - Within toplevel scope by means of the options
|
||||
;; `org-html-svg-as-object' and `org-html-svg-inclusion'.
|
||||
;;
|
||||
;; I prefer the "svg-as-object" option over the "svg-inclusion" option.
|
||||
;; Caveats: the HTML output does not comply with W3C recommendations
|
||||
;; after `svg-as-object' and/or `svg-inclusion' exports and it does not
|
||||
;; comply with the Org Manual section "13.9.9 Images in HTML export"
|
||||
;; after `svg-inclusion' exports.
|
||||
;;
|
||||
;; See: https://list.orgmode.org/c1eef10be815748d2103cb81bce08708@posteo.net/
|
||||
;; where Cristian Moe has proposed to export SVG as "object" tag.
|
||||
;; Ihor Radchenko and Max Nikulin have proposed the idea of using special
|
||||
;; where Cristian Moe has proposed to embed SVG images in <object> tags.
|
||||
;; Ihor Radchenko and Max Nikulin have insisted on the use of special
|
||||
;; "#+ATTR_HTML:" attributes to control the export options.
|
||||
;;
|
||||
;; I prefer enabling `:svg-as-object' over enabling `:svg-inclusion'.
|
||||
|
||||
;;; Code:
|
||||
|
||||
@ -52,7 +64,7 @@
|
||||
(require 'ox-html)
|
||||
|
||||
|
||||
;;; Define Backend
|
||||
;;; Define Derived Backend
|
||||
|
||||
(org-export-define-derived-backend 'svg4css 'html
|
||||
:menu-entry
|
||||
@ -74,21 +86,21 @@
|
||||
|
||||
(defcustom org-html-svg-as-object nil
|
||||
"Non-nil means export SVG images in object tags when in-lining
|
||||
applies, otherwise try SVG image inclusion or try to apply the
|
||||
normal export rules.
|
||||
applies, otherwise apply SVG image inclusion or apply the normal
|
||||
export rules.
|
||||
|
||||
SVG images in object tags and CSS links in such images simply work.
|
||||
Note: https://www.w3schools.com/tags/tag_object.asp prefers \"img\"
|
||||
Note: https://www.w3schools.com/tags/tag_object.asp prefers <img>
|
||||
tag usage."
|
||||
:group 'org-export-html
|
||||
:type 'boolean)
|
||||
|
||||
(defcustom org-html-svg-inclusion nil
|
||||
"Non-nil means include SVG image contents in when in-lining
|
||||
applies, otherwise try to apply the normal export rules.
|
||||
"Non-nil means copy SVG image contents to the HTML output when
|
||||
in-lining applies, otherwise apply the normal export rules.
|
||||
|
||||
The HTML file including the SVG image contents has to link to the
|
||||
CSS to let the SVG image and the CSS work together.
|
||||
The HTML file including the SVG image contents has to include or
|
||||
to link the CSS to let the SVG image and the CSS work together.
|
||||
Note: SVG inclusion breaks \"13.9.9 Images in HTML export\"."
|
||||
:group 'org-export-html
|
||||
:type 'boolean)
|
||||
@ -118,30 +130,39 @@ NO-ATTRIBUTE-NAMES lists attribute names to omit from the result."
|
||||
(setcar output (format "%s=\"%s\"" key value)))))))))
|
||||
|
||||
(defun org-svg4css--svg-as-object-p (link info attributes-plist)
|
||||
"Check whether LINK links to an SVG image to embed in an <object> tag.
|
||||
INFO is a communication channel and ATTRIBUTES-PLIST holds all attributes
|
||||
relevant to LINK."
|
||||
(and (plist-get info :html-inline-images)
|
||||
(not (org-element-contents link))
|
||||
(let ((case-fold-search t))
|
||||
(string-match-p ".svg\\'" (org-element-property :path link)))
|
||||
(org-export-inline-image-p
|
||||
link (plist-get info :html-inline-image-rules))
|
||||
(or (and (plist-get attributes-plist :svg-as-object))
|
||||
(and (plist-get info :html-svg-as-object)
|
||||
;; Next form returns `nil' when member has value `nil'.
|
||||
(or (not (plist-member attributes-plist :svg-as-object))
|
||||
(plist-get attributes-plist :svg-as-object))))
|
||||
(org-export-inline-image-p
|
||||
link (plist-get info :html-inline-image-rules))
|
||||
(not (org-element-contents link))
|
||||
(let ((case-fold-search t))
|
||||
(string-match-p ".svg\\'" (org-element-property :path link)))))
|
||||
(plist-get attributes-plist :svg-as-object))))))
|
||||
|
||||
(defun org-svg4css--svg-inclusion-p (link info attributes-plist)
|
||||
"Check whether LINK links to an SVG image to include in the HTML output.
|
||||
INFO is a communication channel and ATTRIBUTES-PLIST holds all attributes
|
||||
relevant to LINK."
|
||||
(and (plist-get info :html-inline-images)
|
||||
(or (and (plist-get attributes-plist :svg-inclusion))
|
||||
(and (plist-get info :html-svg-inclusion)
|
||||
(or (not (plist-member attributes-plist :svg-inclusion))
|
||||
(plist-get attributes-plist :svg-inclusion))))
|
||||
(org-export-inline-image-p
|
||||
link (plist-get info :html-inline-image-rules))
|
||||
(not (org-element-contents link))
|
||||
(let ((case-fold-search t))
|
||||
(string-match-p ".svg\\'" (org-element-property :path link)))))
|
||||
(string-match-p ".svg\\'" (org-element-property :path link)))
|
||||
(org-export-inline-image-p
|
||||
link (plist-get info :html-inline-image-rules))
|
||||
(or (and (plist-get attributes-plist :svg-inclusion))
|
||||
(and (plist-get info :html-svg-inclusion)
|
||||
;; Next form returns `nil' when member has value `nil'.
|
||||
(or (not (plist-member attributes-plist :svg-inclusion))
|
||||
(plist-get attributes-plist :svg-inclusion))))))
|
||||
|
||||
(defun org-svg4css--format-svg-as-object (path attributes-plist)
|
||||
"Return a string embedding the SVG image PATH in an <objec> tag."
|
||||
(format "<object %s>
|
||||
ARIA placeholder: see https://vecta.io/blog/best-way-to-embed-svg for ideas!
|
||||
</object>" (org-svg4css--make-attribute-string
|
||||
|
||||
Loading…
Reference in New Issue
Block a user