Skip to content

Commit

Permalink
Add: Improve box docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Musa Al-hassy committed Dec 26, 2024
1 parent 7c0e104 commit 3179ae1
Show file tree
Hide file tree
Showing 2 changed files with 36 additions and 59 deletions.
61 changes: 14 additions & 47 deletions org-special-block-extras.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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}
Expand All @@ -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
Expand Down
34 changes: 22 additions & 12 deletions tests/box.yaml
View file
Original file line number Diff line number Diff line change
@@ -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;
Expand All @@ -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)

0 comments on commit 3179ae1

Please sign in to comment.