From 7c0e104c93f31ed9449650d1a337f4e00452e006 Mon Sep 17 00:00:00 2001 From: Musa Al-hassy Date: Wed, 25 Dec 2024 09:13:34 -0500 Subject: [PATCH] Add: Improve details docs --- org-special-block-extras.org | 505 +++++++++++++++-------------------- tests/details.yaml | 78 ++++-- tests/e2e.el | 4 +- 3 files changed, 276 insertions(+), 311 deletions(-) diff --git a/org-special-block-extras.org b/org-special-block-extras.org index 4f75d7d..f089c14 100644 --- a/org-special-block-extras.org +++ b/org-special-block-extras.org @@ -29,6 +29,9 @@ html-export-style:solarized_light # TODO: Since the implementation is a find-replace, nested blocks do not honor enclosing blocks. # For example, try placing a `rename` block within an `example` block and see that it is expanded! +# TODO: Add :noexport support to [all?] blocks? +# TODO: Could generalize this to be a hook that's run before processing blocks, and :noexport support amounts to a hook that returns "" for the block. + # (setq osbe-example-yaml-cache (make-hash-table :test 'equal)) # 1. osbe-example:~/org-special-block-extras/tests/doc.yaml # 2. osbe-example:~/org-special-block-extras/tests/rename.yaml @@ -2391,7 +2394,7 @@ A full example: :CUSTOM_ID: Short_Example_An_opportunity_to_learn :END: -The following tiny block is composed from two [[doc:org--details][details]] blocks and a [[doc:org--box][box]] block +The following tiny block is composed from two [[doc:org-block/details][details]] blocks and a [[doc:org-block/box][box]] block ---defined elsewhere in this article. It is intended to give the reader another opportunity to make sure they have tried to solve the puzzle posed in the main text before seeing the answer ----this works well in HTML, not so in LaTeX. @@ -3331,37 +3334,48 @@ Such “open methods” are known as “multimethods”; e.g., see doc:cl-defgen #+end_src :End: -* COMMENT Folded Details ---As well as boxed text and subtle colours +* DONE COMMENT Folded Details ---Let the user see stuff only if they're interested :PROPERTIES: :CUSTOM_ID: Folded-Details :END: - #+begin_center -/How did we fold away those implementations?/ - #+end_center -Sometimes there is a remark or a code snippet that is useful to have, but not -relevant to the discussion at hand and so we want to /fold away such [[doc:org--details][details]]/. +# (setq osbe-example-yaml-cache (make-hash-table :test 'equal)) + osbe-example:~/org-special-block-extras/tests/details.yaml -+ ‘Conversation-style’ articles, where the author asks the reader questions - whose answers are “folded away” so the reader can think about the exercise - before seeing the answer. +-------------------------------------------------------------------------------- + +Below is a concrete example of a ‘conversation-style’ usage of the ~details~ block: +#+begin_box "Here's a nifty puzzle, can you figure it out? 👽" +Reductions ---incidentally also called ‘folds’[fn:1]--- embody +primitive recursion and thus computability. For example, what does +~(-reduce #'/ (number-sequence 1.0 𝓃))~ compute when given a whole +number 𝓃? -+ Hiding boring but important code snippets, such as a list of import - declarations or a tedious implementation. +#+begin_details Solution :title-color pink +Rather than guess-then-check, let's /calculate/! -#+latex_header: \usepackage{tcolorbox} -#+begin_center -Requires: src_latex[:exports code]{,#+latex_header: \usepackage{tcolorbox}} -#+end_center +#+begin_src emacs-lisp :tangle no + (-reduce #'/ (number-sequence 1.0 𝓃)) += ;; Lisp is strict: Evaluate inner-most expression + (-reduce #'/ '(1.0 2.0 3.0 … 𝓃)) += ;; Evaluate left-associating reduction + (/ (/ (/ 1.0 2.0) ⋯) 𝓃) +=;; Arithmetic: (/ (/ a b) c) = (* (/ a b) (/ 1 c)) = (/ a (* b c)) + (/ 1.0 (* 2.0 3.0 … 𝓃)) +#+END_SRC -:Pics: -#+caption: Visually hiding, folding away, details -[[file:images/details.png]] -:End: +We have thus found the above Lisp program to compute the inverse factorial of 𝓃; +i.e., $\large \frac{1}{𝓃!}$. +#+end_details -#+begin_details Implementation -#+begin_src emacs-lisp +Neato, let's do more super cool stuff ^_^ +#+end_box + +-------------------------------------------------------------------------------- + +Below is a concrete example of hiding a boring, but important, code snippet, using the ~details~ block: +#+begin_src emacs-lisp :folded t :title Implementation (org-defblock details (title "Details" background-color "#e5f5e5" title-color "green") "Enclose contents in a folded up box, for HTML. @@ -3406,67 +3420,9 @@ it may be prudent to expose more aspects as arguments. " background-color title-color title contents)))) #+end_src -:Posterity_Older_implementation: -#+BEGIN_SRC emacs-lisp -n -r :tangle no -(defun org--details (backend contents) -"Format CONTENTS as a ‘folded region’ according to BACKEND. - -CONTENTS may have a ‘:title’ argument specifying a title for -the folded region." -(-let* (;; Get arguments - ((contents′ . (&alist 'title)) - (org--extract-arguments contents 'title))) - (when (s-blank? title) (setq title "Details")) - (setq title (s-trim title)) - (format - (s-collapse-whitespace ;; Remove the whitespace only in the nicely presented - ;; strings below - (pcase backend - (`html "
- - - %s - - - - %s -
") - (`latex "\\begin{quote} - \\begin{tcolorbox}[colback=white,sharp corners,boxrule=0.4pt] - \\textbf{%s:} - %s - \\end{tcolorbox} - \\end{quote}"))) - title contents′))) -#+END_SRC - -#+RESULTS: -: org--details - -:End: - -We could use -src_latex[:exports code]{\begin{quote}\fbox{\parbox{\linewidth}{\textbf{Details:} -...}}\end{quote}}; however, this does not work well with [[https://github.com/alhassy/emacs.d#bibliography--coloured-latex-using-minted][minted]] for coloured -source blocks. Instead, we use ~tcolorbox~. - -Let's have some sanity tests... -#+begin_src emacs-lisp :tangle tests.el :comments link -(deftest "The result is a
tag containing the user's title & text." - [details] - (⇝ (⟰ "#+begin_details TITLE-RIGHT-HERE - My aside... - ,#+end_details") - "")) -#+end_src -#+end_details +-------------------------------------------------------------------------------- +#+begin_box "Tip 🌼" If you fear that your readers may not click on details boxes in the HTML export, you could, say, have the details heading “flash pink” whenever the user hovers over it. This can be accomplished by inserting the following incantation into @@ -3477,49 +3433,16 @@ your Org file or place it into your ~org-html-head~ variable. # Which, I will do, for fun. #+html: +#+end_box -** Example: /Here's a nifty puzzle, can you figure it out?/ - :PROPERTIES: - :CUSTOM_ID: Example - :END: -Reductions ---incidentally also called ‘folds’[fn:1]--- embody primitive -recursion and thus computability. For example, what does the following compute -when given a whole number 𝓃? -#+BEGIN_SRC emacs-lisp :tangle no -(-reduce #'/ (number-sequence 1.0 𝓃)) -#+END_SRC - -#+begin_details Solution :title-color pink -Rather than guess-then-check, let's /calculate/! - -#+begin_src emacs-lisp :tangle no - (-reduce #'/ (number-sequence 1.0 𝓃)) -= ;; Lisp is strict: Evaluate inner-most expression - (-reduce #'/ '(1.0 2.0 3.0 … 𝓃)) -= ;; Evaluate left-associating reduction - (/ (/ (/ 1.0 2.0) ⋯) 𝓃) -=;; Arithmetic: (/ (/ a b) c) = (* (/ a b) (/ 1 c)) = (/ a (* b c)) - (/ 1.0 (* 2.0 3.0 … 𝓃)) -#+END_SRC - -We have thus found the above Lisp program to compute the inverse factorial of 𝓃; -i.e., $\large \frac{1}{𝓃!}$. -#+end_details - -Neato, let's do more super cool stuff ^_^ - -#+begin_footnotesize -( In the Emacs Web Wowser, folded regions are displayed unfolded similar to -LaTeX. ) -#+end_footnotesize -** Boxed Text +* COMMENT Boxed Text :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--box][box]] to enclosing text in + folded away. As such, we provide the special block [[doc:org-block/box][box]] to enclosing text in boxes. #+latex_header: \usepackage{tcolorbox} @@ -3648,7 +3571,7 @@ Or, with the header option ~:shadow (:left "inset cyan" :right "inset pink" #+end_box - For further header options, see the documentation of [[doc:org--box][box]]. + For further header options, see the documentation of [[doc:org-block/box][box]]. #+html:
@@ -3717,7 +3640,175 @@ src_latex[:exports code]{\color{blue}} is a nightmare. ) It may be useful to /fuse/ the ~box~ and ~details~ concepts into one. Something for future me ---or another contributor--- to think about ;-) -* Parallel ---/Place ideas side-by-side, possibly with a separator/ +* DONE COMMENT Nice Keystroke Renditions: kbd:C-h_h + :PROPERTIES: + :CUSTOM_ID: kbd:nice-keystroke-renditions + :END: + +Anyone who writes /about/ Emacs will likely want to mention keystrokes in an +aesthetically pleasing way, such as [[kbd:C-u 80 -]] to insert 80 dashes, +or kbd:C-c_C-e_h_o to export an Org-mode file to HTML, +or the useful . + +- ~kbd:𝒳~ will show a tooltip defining 𝒳, as an Emacs Lisp function, if possible. + For example, ~kbd:C-h_h~ is kbd:C-h_h; and likewise == is (we need to use ~<...>~ since punctuation is not picked up as part of link + labels). In contrast, ~kbd:nope~ renders as kbd:nope /without/ a tooltip (nor a + red border). + + You can also supply explicit tooltip description: =[[kbd:key + sequence][description]]= will show as [[kbd:key sequence][description]]; i.e., + the key sequence in nice key font along with a tooltip explaining it. + + +# To make a screenshot, add the following to the above :PROPERTIES: drawer. +# :UNNUMBERED: t +# +#+attr_html: :width 80% :height 80%s +[[file:./images/kbd.png]] + +#+begin_details Implementation + +#+begin_src emacs-lisp +(org-deflink kbd + "Show keysequence O-LABEL in a nice grey button-like font, along with a tooltip of its documentation, if any. + +Such links do not get folded in [[bracket]] style, and are rendered as buttons within Emacs. + +Moreover, O-LABEL may use ‘_’ in-lieu of spaces or [[bracket]] link notation. + +Examples: + [[kbd:C-x C-s]] + ≈ + ≈ kbd:C-x_C-s" + [:display 'full + :let (the-label (s-trim (s-replace "_" " " o-label)) + lisp-func (ignore-errors (cl-second (help--analyze-key (kbd the-label) the-label))) + tooltip (or o-description (ignore-errors (documentation lisp-func)) "") + tooltip? (not (equal tooltip "")) + style (if tooltip? "border-color: red" "") + keystrokes (format "%s" style the-label)) + ;; o-description is always nil when it comes to deciding the :face. + :face (list :inherit 'custom-button :box (if tooltip? "red" t)) + :help-echo (format "%s ∷ %s\n%s" the-label (or lisp-func "") tooltip)] + (if (equal o-backend 'latex) + (format "\\texttt{%s}" the-label) + (if tooltip? + ;; The style=⋯ is to remove the underlining caused by . + (format "%s\">%s" + the-label (or lisp-func "") (org-ospe-html-export-preserving-whitespace tooltip) + keystrokes) + keystrokes))) +#+end_src + +The following styling rule is used to make the keystrokes displayed nicely. +#+begin_src emacs-lisp :noweb-ref enable-mode :tangle no + (defvar org--ospe-kbd-html-setup nil + "Has the necessary keyboard styling HTML beeen added?") + + (unless org--ospe-kbd-html-setup + (setq org--ospe-kbd-html-setup t)) + (when org-special-block-add-html-extra + (setq org-html-head-extra + (concat org-html-head-extra + " + "))) +#+end_src + +Let's have some sanity tests... +#+begin_src emacs-lisp :tangle tests.el :comments link +(deftest "It becomes tags, but final symbol non-ascii *may* be ignored" + [kbd direct-org-links] + (⇝ (⟰ "kbd:C-u_80_-∀") "

\nC-u 80_-∀

")) + +(deftest "[[It]] becomes tags" + [kbd square-org-links] + (⇝ (⟰ "[[kbd:C-u_80_-]]") "

\nC-u 80 -

")) + +(deftest " becomes tags, and surrounding space is trimmed" + [kbd angle-org-links] + (⇝ (⟰ "") "

\nC-u 80 -

")) + +;; FIXME: uh-oh! +(when nil +(deftest "It has a tooltip documenting the underlying Lisp function, when possible" + [kbd tooltip] + (⇝ (⟰ "") + + "Uses the + next face from ‘hi-lock-face-defaults’ without + prompting,
unless you use a prefix argument.
Uses + ‘find-tag-default-as-symbol-regexp’ to retrieve the symbol + at point.

This uses Font lock mode if it is enabled; + otherwise it uses overlays,
in which case the + highlighting will not update as you type. The + Font
Lock mode is considered ''enabled'' in a buffer if + its ‘major-mode’
causes ‘font-lock-specified-p’ to return + non-nil, which means
the major mode specifies support for + Font Lock." + (* anything) + "M-s h ."))) +#+end_src + +#+end_details + +:Hide: +#+HTML: +#+HTML: +:End: +* DONE COMMENT Parallel ---/Place ideas side-by-side, possibly with a separator/ :PROPERTIES: :CUSTOM_ID: Parallel :END: @@ -4897,174 +4988,6 @@ Let's have some sanity tests... generalisation would be when rendering text in multiple languages; e.g., use red and blue to interleave Arabic poetry with its English translation. -* COMMENT Nice Keystroke Renditions: kbd:C-h_h - :PROPERTIES: - :CUSTOM_ID: kbd:nice-keystroke-renditions - :END: - -Anyone who writes /about/ Emacs will likely want to mention keystrokes in an -aesthetically pleasing way, such as [[kbd:C-u 80 -]] to insert 80 dashes, -or kbd:C-c_C-e_h_o to export an Org-mode file to HTML, -or the useful . - -- ~kbd:𝒳~ will show a tooltip defining 𝒳, as an Emacs Lisp function, if possible. - For example, ~kbd:C-h_h~ is kbd:C-h_h; and likewise == is (we need to use ~<...>~ since punctuation is not picked up as part of link - labels). In contrast, ~kbd:nope~ renders as kbd:nope /without/ a tooltip (nor a - red border). - - You can also supply explicit tooltip description: =[[kbd:key - sequence][description]]= will show as [[kbd:key sequence][description]]; i.e., - the key sequence in nice key font along with a tooltip explaining it. - - -# To make a screenshot, add the following to the above :PROPERTIES: drawer. -# :UNNUMBERED: t -# -#+attr_html: :width 80% :height 80%s -[[file:./images/kbd.png]] - -#+begin_details Implementation - -#+begin_src emacs-lisp -(org-deflink kbd - "Show keysequence O-LABEL in a nice grey button-like font, along with a tooltip of its documentation, if any. - -Such links do not get folded in [[bracket]] style, and are rendered as buttons within Emacs. - -Moreover, O-LABEL may use ‘_’ in-lieu of spaces or [[bracket]] link notation. - -Examples: - [[kbd:C-x C-s]] - ≈ - ≈ kbd:C-x_C-s" - [:display 'full - :let (the-label (s-trim (s-replace "_" " " o-label)) - lisp-func (ignore-errors (cl-second (help--analyze-key (kbd the-label) the-label))) - tooltip (or o-description (ignore-errors (documentation lisp-func)) "") - tooltip? (not (equal tooltip "")) - style (if tooltip? "border-color: red" "") - keystrokes (format "%s" style the-label)) - ;; o-description is always nil when it comes to deciding the :face. - :face (list :inherit 'custom-button :box (if tooltip? "red" t)) - :help-echo (format "%s ∷ %s\n%s" the-label (or lisp-func "") tooltip)] - (if (equal o-backend 'latex) - (format "\\texttt{%s}" the-label) - (if tooltip? - ;; The style=⋯ is to remove the underlining caused by . - (format "%s\">%s" - the-label (or lisp-func "") (org-ospe-html-export-preserving-whitespace tooltip) - keystrokes) - keystrokes))) -#+end_src - -The following styling rule is used to make the keystrokes displayed nicely. -#+begin_src emacs-lisp :noweb-ref enable-mode :tangle no - (defvar org--ospe-kbd-html-setup nil - "Has the necessary keyboard styling HTML beeen added?") - - (unless org--ospe-kbd-html-setup - (setq org--ospe-kbd-html-setup t)) - (when org-special-block-add-html-extra - (setq org-html-head-extra - (concat org-html-head-extra - " - "))) -#+end_src - -Let's have some sanity tests... -#+begin_src emacs-lisp :tangle tests.el :comments link -(deftest "It becomes tags, but final symbol non-ascii *may* be ignored" - [kbd direct-org-links] - (⇝ (⟰ "kbd:C-u_80_-∀") "

\nC-u 80_-∀

")) - -(deftest "[[It]] becomes tags" - [kbd square-org-links] - (⇝ (⟰ "[[kbd:C-u_80_-]]") "

\nC-u 80 -

")) - -(deftest " becomes tags, and surrounding space is trimmed" - [kbd angle-org-links] - (⇝ (⟰ "") "

\nC-u 80 -

")) - -;; FIXME: uh-oh! -(when nil -(deftest "It has a tooltip documenting the underlying Lisp function, when possible" - [kbd tooltip] - (⇝ (⟰ "") - - "Uses the - next face from ‘hi-lock-face-defaults’ without - prompting,
unless you use a prefix argument.
Uses - ‘find-tag-default-as-symbol-regexp’ to retrieve the symbol - at point.

This uses Font lock mode if it is enabled; - otherwise it uses overlays,
in which case the - highlighting will not update as you type. The - Font
Lock mode is considered ''enabled'' in a buffer if - its ‘major-mode’
causes ‘font-lock-specified-p’ to return - non-nil, which means
the major mode specifies support for - Font Lock." - (* anything) - "M-s h ."))) -#+end_src - -#+end_details - -:Hide: -#+HTML: -#+HTML: -:End: * COMMENT   /“Link Here!”/ & OctoIcons :PROPERTIES: :CUSTOM_ID: Link-Here-OctoIcons @@ -8298,6 +8221,11 @@ since otherwise things don't look as nice in a markdown readme file. #+caption: Displaying thoughts side-by-side ^_^ Top is browser, then Emacs, then PDF [[file:images/parallel.png]] + + +#+caption: Visually hiding, folding away, details +[[file:images/details.png]] + * COMMENT Case Studies ** In doubt, a block's main argument should be enclosed in quotes :PROPERTIES: @@ -8356,7 +8284,6 @@ After 372 pages, it was shown that $1 + 1 = 2$ It is said that $e^{i \cdot \pi} + 1 = 0$ is the truth. #+end_theorem - * TODO [#A] COMMENT Summary :PROPERTIES: :CUSTOM_ID: Summary diff --git a/tests/details.yaml b/tests/details.yaml index 0f9830a..96216d3 100644 --- a/tests/details.yaml +++ b/tests/details.yaml @@ -1,14 +1,47 @@ input: |- - #+begin_details TITLE-RIGHT-HERE :title-color "cyan" - The result is a
tag containing the user's title & text. - But, in LaTeX, this is a colourful box. + Sometimes there is a remark or a code snippet that is useful to + have, but not relevant to the discussion at hand and so we want to + /fold away such [[doc:org-block/details][details]]/. + + #+begin_details Example use cases + + ‘Conversation-style’ articles, where the author asks the reader questions + whose answers are “folded away” so the reader can think about the exercise + before seeing the answer. + + + Hiding boring but important code snippets, such as a list of import + declarations or a tedious implementation. #+end_details - (FIXME: The use of quotes in the :title-color keyword is only required for the LaTeX backend.) + Full syntax ~#+begin_details "title" :background-color "cyan" :title-color "green"~. +Unmaintained: |- + + 1. The LaTex implementation requires: + #+latex_header: \usepackage{tcolorbox} + 2. The use of quotes in the :title-color keyword is only required for the LaTeX backend. + + 3. In the LaTeX implementation, We could use src_latex[:exports + code]{\begin{quote}\fbox{\parbox{\linewidth}{\textbf{Details:} + ...}}\end{quote}}; however, this does not work well with + [[https://github.com/alhassy/emacs.d#bibliography--coloured-latex-using-minted][minted]] + for coloured source blocks. Instead, we use ~tcolorbox~. + expectations: html: |- +

+ Sometimes there is a remark or a code snippet that is useful to have, but not + relevant to the discussion at hand and so we want to + fold away such + details. +

+
TITLE-RIGHT-HERE + Example use cases -

- The result is a <details> tag containing the user's title & text. - But, in LaTeX, this is a colourful box. -

+
    +
  • + ‘Conversation-style’ articles, where the author asks the reader questions + whose answers are “folded away” so the reader can think about the exercise + before seeing the answer. +
    • + +
  • + Hiding boring but important code snippets, such as a list of import + declarations or a tedious implementation. +
    • +

- (FIXME: The use of quotes in the :title-color keyword is only required for the - LaTeX backend.) + Full syntax + #+begin_details "title" :background-color "cyan" :title-color "green".

latex: |- - \definecolor{osbe-bg}{HTML}{e5f5e5}\colorlet{osbe-fg}{cyan}\begin{quote} - \begin{tcolorbox}[colback=osbe-bg,colframe=osbe-fg,title={TITLE-RIGHT-HERE},sharp corners,boxrule=0.4pt] - The result is a
tag containing the user's title \& text. - But, in \LaTeX{}, this is a colourful box. - - - \end{tcolorbox} - \end{quote} - - (FIXME: The use of quotes in the :title-color keyword is only required for the \LaTeX{} backend.) + 🚫 The LaTex backend is intentionally unmaintained. + 🫠 Whoops, there seems to be an error: + (void-variable label) diff --git a/tests/e2e.el b/tests/e2e.el index e996b00..f473efb 100644 --- a/tests/e2e.el +++ b/tests/e2e.el @@ -247,10 +247,12 @@ my liking, then move the `input' to the relevant yaml file." (cl-letf* (((symbol-function 'make-title) (lambda (it) (format "
﴾%s﴿
" it))) (src.title (make-title "What You Write")) (tgt.title (make-title "What You Get"))) - (format "
%s 
 %s
%s %s
" + (format "
%s 
%s
%s %s
" src.color src.title src tgt.color tgt.title tgt)))) + +;; TODO: Expose this in use-facing docs, then covert that prose into a yaml test using the workflow documented in osbe-example link type. (org-defblock src (language "emacs-lisp" folded nil title "Details") "yup" (-let [org--supported-blocks '(details)] ;; to avoid infinite recursive calls for `src'