From 3179ae118e808759bae9c91076bb9491a75d9ece Mon Sep 17 00:00:00 2001 From: Musa Al-hassy Date: Wed, 25 Dec 2024 21:06:46 -0500 Subject: [PATCH] Add: Improve box docs --- org-special-block-extras.org | 61 +++++++++--------------------------- tests/box.yaml | 34 +++++++++++++------- 2 files changed, 36 insertions(+), 59 deletions(-) diff --git a/org-special-block-extras.org b/org-special-block-extras.org index f089c14..0a64dbd 100644 --- a/org-special-block-extras.org +++ b/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: #+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 Pay Attention!" - (* 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:
#+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:
- 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 diff --git a/tests/box.yaml b/tests/box.yaml index d2e453e..ea6a446 100644 --- a/tests/box.yaml +++ b/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: |- +

+ It can be useful to draw attention to some important text by enclosing it in a + box. +

+
-

Pay Attention!

+

Uses of callout boxes

- This is the key insight… (We have an HTML box enclosing the user's - title and text) + Such boxes often callout tips, warnings, cautionary info or emphasises core + information.

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)