Finish comment and documentation strings

site-lisp/ox-svg4css/ox-svg4css.el

@@ -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
+;; See the Emacs ox-html library for its authors, maintainer and FSF
-;; library, see the ox-html library for its authors, maintainer and
+;; Copyright, since ox-svg4css contains a lot of code from the ox-html.
-;; FSF copyright.
 
 ;; This file is NOT part of GNU Emacs.
 
@@ -27,21 +26,34 @@
 
 ;;; Commentary:
 
-;; This library implements a HTML derived backend for Org export.
+;; This library implements an HTML derived backend for Org export.
-;; It tries to address limitations of SVG images and CSS in HTML pages:
+;; 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.
+;; For each SVG image during HTML export:
-;; 2. Secondly, it probes whether to include the SVG contents in the HTML.
+;; 1. It checks `svg-as-object' and "image in-lining" whether to
-;; 3. Thirdly, it probes wheter to embed the SVG image in an "img" tag.
+;;    embed the SVG image in an <object> tag.
-;; 4. The option precedence order is "svg-as-object", "svg-inclusion",
+;; 2. If not, it checks `svg-inclusion' and "image in-lining"
-;;    "org-html-inline-images", but disabling the latter disables the other
+;;    whether to copy the SVG contents to the HTML output.
-;;    options.
+;; 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.
+;; where Cristian Moe has proposed to embed SVG images in <object> tags.
-;; Ihor Radchenko and Max Nikulin have proposed the idea of using special
+;; 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
+applies, otherwise apply SVG image inclusion or apply the normal
-normal export rules.
+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
+  "Non-nil means copy SVG image contents to the HTML output when
-applies, otherwise try to apply the normal export rules.
+in-lining applies, otherwise apply the normal export rules.
 
-The HTML file including the SVG image contents has to link to the
+The HTML file including the SVG image contents has to include or
-CSS to let the SVG image and the CSS work together.
+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))))
+                    (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)))))
 
 (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