Add: Improve box docs

Author: Musa Al-hassy

org-special-block-extras.org

@@ -3339,7 +3339,6 @@ Such “open methods” are known as “multimethods”; e.g., see doc:cl-defgen
   :CUSTOM_ID: Folded-Details
   :END:
 
-
 # (setq  osbe-example-yaml-cache (make-hash-table :test 'equal))
    osbe-example:~/org-special-block-extras/tests/details.yaml
 
@@ -3435,23 +3434,15 @@ your Org file or place it into your ~org-html-head~ variable.
 #+html: <style>  summary:hover {background:pink;} </style>
 #+end_box
 
-* COMMENT Boxed Text
+* DONE COMMENT Boxed Text —Calling out super duper info
    :PROPERTIES:
    :CUSTOM_ID: Boxed-Text
    :END:
 
- Folded regions, as implemented above, are displayed in a super neat text box
- which may be useful to enclose text to make it standout ---without having it
- folded away. As such, we provide the special block [[doc:org-block/box][box]] to enclosing text in
- boxes.
-
- #+latex_header: \usepackage{tcolorbox}
-#+begin_center
-Requires: src_latex[:exports code]{#+latex_header:  \usepackage{tcolorbox}}
-#+end_center
+# (setq  osbe-example-yaml-cache (make-hash-table :test 'equal))
+   osbe-example:~/org-special-block-extras/tests/box.yaml
 
-#+begin_details Implementation
- #+begin_src emacs-lisp
+ #+begin_src emacs-lisp :title Implementation :folded t
 (org-defblock box (title "" background-color nil shadow nil frame-color nil title-background-color nil)
   "Enclose text in a box, possibly with a title.
 
@@ -3524,22 +3515,7 @@ In the future, I will likely expose more arguments."
                  title contents)))))
 #+end_src
 
-Let's have some sanity tests...
-#+begin_src emacs-lisp :tangle tests.el
-(deftest "We have an HTML box enclosing the user's title (in <h3) and text"
-  [box]
-  (⇝ (⟰ "#+begin_box Pay Attention!
-                 This is the key insight...
-                 ,#+end_box")
-     "<div style=\"padding: 1em;background-color: #CCFFCC;border-radius: 15px;"
-     (* anything)
-     "<h3>Pay Attention!</h3>"
-     (* anything)
-     "This is the key insight"
-     (* anything)))
-#+end_src
- #+end_details
-
+** Three demos of  [[doc:org-block/box][box]]
  #+latex_header: \newunicodechar{ᵒ}{\ensuremath{{}^o}}
  #+html: <br>
  #+begin_box Example: A super boring observation presented obscurely :background-color blue
@@ -3573,12 +3549,12 @@ Or, with the header option ~:shadow (:left "inset cyan" :right "inset pink"
 
  For further header options, see the documentation of [[doc:org-block/box][box]].
 
-
+** Subtle Colours
  #+html: <br>
- In the first example above, /how did we get that nice light blue? What is its
- HTML code?/ That's not something I care to remember, so let's make a handy dandy
- utility … Now when users request a colour to ~box~ their text, it will be a
- ‘subtle colour’ ;-)
+ In the first example above, /how did we get that nice light blue? What
+ is its HTML code?/ That's not something I care to remember, so let's
+ make a handy dandy utility … Now when users request a colour to ~box~
+ their text, it will be a ‘subtle colour’ ;-)
 
  #+begin_details Implementation for Subtle Colours
  #+begin_src emacs-lisp -r -n
@@ -3605,12 +3581,10 @@ Names are very rough approximates.
   ))
  #+end_src
 
-#+latex: \iffalse
+To use these colour names, you will need the following incantations in
+your Org file.
 
-To use these colour names, you will need the following incantations in your
-Org file.
-
-#+begin_org-demo
+#+begin_src org :tangle no
 #+latex_header: \usepackage{xcolor}
 
 #+latex_header: \definecolor{teal}    {HTML}{99FFCC}
@@ -3627,19 +3601,12 @@ Org file.
 #+latex_header: \definecolor{custard}{HTML}{FFFFCC}
 
 #+latex_header: \definecolor{cyan}{HTML}{00FFFF}
-#+end_org-demo
-
-#+latex_header: \definecolor{"cyan"}{HTML}{00FFFF}
+#+end_src
 
 In the future, it'd be nice to account for colours for LaTeX as well.  ( E.g.,
 src_latex[:exports code]{\color{blue}} is a nightmare. )
-
-#+latex: \fi
-
  #+end_details
 
- It may be useful to /fuse/ the ~box~ and ~details~ concepts into one.  Something for
- future me ---or another contributor--- to think about ;-)
 * DONE COMMENT Nice Keystroke Renditions: kbd:C-h_h
   :PROPERTIES:
   :CUSTOM_ID: kbd:nice-keystroke-renditions

tests/box.yaml

@@ -1,11 +1,23 @@
 input: |-
-  #+begin_box Pay Attention!
-  This is the key insight...
-  (We have an HTML box enclosing the user's title and text)
-  #+end_box
+  It can be useful to draw attention to some important text by
+  enclosing it in a [[doc:org-block/box][box]].
 
+  #+begin_box Uses of callout boxes
+  Such boxes often callout tips, warnings, cautionary info or
+  emphasises core information.
+  #+end_box
+Unmaintained: "For the LaTeX backend, the following call is required."
 expectations:
   html: |-
+    <p>
+      It can be useful to draw attention to some important text by enclosing it in a
+      <abbr
+        class="tooltip"
+        title="Enclose text in a box, possibly with a title.<br><br>By default, the box’s COLOR is green for HTML and red for LaTeX,<br>and it has no TITLE.<br><br>SHADOW is an alternate style of boxing: It shows the contents in a centred<br>box with a shadow colour being the given non-nil value of SHADOW.<br>If SHADOW is a hexidecimal colour, it should be a string enclosed in double quotes.<br>More accurately, the following are all valid uses:<br><br>&emsp;&emsp;#+begin_box title :shadow t<br>&emsp;&emsp;#+begin_box title :shadow inset<br><br>&emsp;&emsp;#+begin_box title :shadow ''pink''<br>&emsp;&emsp;#+begin_box title :shadow pink<br><br>&emsp;&emsp;#+begin_box title :shadow (cyan pink orange yellow)<br>&emsp;&emsp;#+begin_box title :shadow (cyan ''inset pink'' orange)<br>&emsp;&emsp;#+begin_box title :shadow (:left cyan :right pink :deep-right orange :deep-left yellow)<br><br>Notice that prefixing colours with ‘inset’ causes the colour to be within the box,<br>rather than spread, with blur, around the box. The use of ‘inset’ swaps left and right.<br><br>The HTML export uses a padded div, whereas the LaTeX export<br>requires the tcolorbox package.<br><br>In the future, I will likely expose more arguments.<br><br>(fn BACKEND RAW-CONTENTS &rest _)"
+        >box</abbr
+      >.
+    </p>
+
     <div
       style="
         padding: 1em;
@@ -14,15 +26,13 @@ expectations:
         font-size: 0.9em;
       "
     >
-      <h3>Pay Attention!</h3>
+      <h3>Uses of callout boxes</h3>
       <p>
-        This is the key insight&#x2026; (We have an HTML box enclosing the user's
-        title and text)
+        Such boxes often callout tips, warnings, cautionary info or emphasises core
+        information.
       </p>
     </div>
   latex: |-
-    \begin{tcolorbox}[title={Pay Attention!},colback=red!5!white,colframe=red!75!black,colbacktitle=yellow!50!red,coltitle=red!25!black, fonttitle=\bfseries,subtitle style={boxrule=0.4pt, colback=yellow!50!red!25!white}]
-    	This is the key insight\ldots{}
-    	(We have an HTML box enclosing the user's title and text)
-
-    \end{tcolorbox}
+    🚫 The LaTex backend is intentionally unmaintained.
+    🫠 Whoops, there seems to be an error: 
+     (void-variable label)