|
| 1 | +^{:kindly/hide-code true |
| 2 | + :clay {:title "Two Columns, One Namespace: Clojure to PDF" |
| 3 | + :format [:quarto :pdf] |
| 4 | + :quarto {:author :timothypratley |
| 5 | + :description "Transform your Clojure code into a beautiful, journal-style PDF, complete with math, charts, and images." |
| 6 | + :type :post |
| 7 | + :date "2025-08-21" |
| 8 | + :draft true |
| 9 | + :category :clay |
| 10 | + :tags [:clay :workflow :pdf] |
| 11 | + :documentclass "article" |
| 12 | + :classoption ["twocolumn"] |
| 13 | + ;;:mainfont "Times New Roman" |
| 14 | + :colorlinks true |
| 15 | + :toc true |
| 16 | + :number-sections true |
| 17 | + :geometry ["top=30mm" "left=20mm" "heightrounded"] |
| 18 | + :include-in-header {:text "\\AddToHook{env/Highlighting/begin}{\\small}"}}}} |
| 19 | +(ns scicloj.clay.pdf) |
| 20 | + |
| 21 | + |
| 22 | +;; --- |
| 23 | + |
| 24 | +(require '[tablecloth.api :as tc]) |
| 25 | +(require '[scicloj.tableplot.v1.plotly :as tp]) |
| 26 | + |
| 27 | +(def quick-ds |
| 28 | + (tc/dataset {:category ["html" "pdf" "revealjs"] |
| 29 | + :value [42 73 58]})) |
| 30 | + |
| 31 | +(-> quick-ds |
| 32 | + (tp/base {:=title "Instant Visuals"}) |
| 33 | + (tp/layer-bar {:=x :category |
| 34 | + :=y :value})) |
| 35 | + |
| 36 | +;; Example math: |
| 37 | + |
| 38 | +;; $$ |
| 39 | +;; \int_{0}^{1} x^2 dx = \frac{1}{3} |
| 40 | +;; $$ |
| 41 | + |
| 42 | +;; --- |
| 43 | + |
| 44 | +;; ## Introduction |
| 45 | + |
| 46 | +;; Ever wanted your Clojure project to look like it just rolled off the press at a 19th-century scientific society? |
| 47 | +;; Or maybe you want to channel your inner Ada Lovelace or Alan Turing and make something that looks like it belongs in a library archive. |
| 48 | + |
| 49 | +;; This guide shows how to create a two-column, journal-style PDF from Clojure code using Clay. |
| 50 | +;; You'll see how to export a PDF, add math, and include charts and code blocks. |
| 51 | + |
| 52 | +;; --- |
| 53 | + |
| 54 | +;; ## Making a PDF |
| 55 | + |
| 56 | +;; Make sure you set the quarto metadata on your namespace to `:format [:quarto :pdf]`, |
| 57 | +;; or if you prefer to build at the REPL, you can set the format in the options. |
| 58 | + |
| 59 | +(comment |
| 60 | + (require '[scicloj.clay.v2.api :as clay]) |
| 61 | + (clay/make! |
| 62 | + {:source-path "scicloj/clay/pdf.clj" |
| 63 | + :format [:quarto :pdf]}) |
| 64 | + :-) |
| 65 | + |
| 66 | +;; ## Why PDFs? |
| 67 | + |
| 68 | +;; PDFs are widely used for academic publishing, grant applications, and official documentation. |
| 69 | +;; They look the same everywhere and are easy to share. |
| 70 | +;; Sometimes you want a polished, typeset result, something worthy of Ada or Turing! |
| 71 | + |
| 72 | +;; ## Quick PDF Export: Using Your Browser |
| 73 | + |
| 74 | +;; In most cases, the fastest and most reliable way to create a PDF is to use your browser's built-in "Print" or "Save as PDF" feature: |
| 75 | + |
| 76 | +;; 1. Open your Clay-generated HTML page in your web browser. |
| 77 | +;; 2. Press `Cmd+P` (Mac) or `Ctrl+P` (Windows/Linux) to open the print dialog. |
| 78 | +;; 3. Select "Save as PDF" or "Print to PDF" as the destination/printer. |
| 79 | +;; 4. Adjust layout, margins, and other options as needed. |
| 80 | +;; 5. Click "Save" to export your PDF. |
| 81 | + |
| 82 | +;; This method works well for most reports, blog posts, and slideshows, and preserves the look of your HTML output. |
| 83 | + |
| 84 | +;;  |
| 85 | + |
| 86 | +;; ## Using the PDF format |
| 87 | + |
| 88 | +;; But for a traditional, journal-style PDF (e.g., two columns, custom fonts, LaTeX typesetting), use `[:format :pdf]`. |
| 89 | +;; Some features won't work quite the same, feel free to let us know if you run into issues. |
| 90 | + |
| 91 | +;; ## Prerequisites |
| 92 | + |
| 93 | +;; - Install a TeX distribution (e.g., TinyTeX: `quarto install tinytex`) |
| 94 | +;; - Install Quarto (https://quarto.org/docs/get-started/) |
| 95 | +;; - Python and the modules plotly and kaleido |
| 96 | + |
| 97 | +;; ## Example: 2-Column Journal Style via Namespace Metadata |
| 98 | + |
| 99 | +;; The options for a 2-column journal style PDF are now set in the namespace metadata above. |
| 100 | +;; See the ^{:clay ...} metadata on this namespace for a working example. |
| 101 | + |
| 102 | +;; - `:documentclass "article"` is standard for journal articles. |
| 103 | +;; - `:classoption ["twocolumn"]` enables two-column layout. |
| 104 | +;; - `:mainfont` sets the main text font (requires XeLaTeX or LuaLaTeX). |
| 105 | +;; - `:geometry` customizes page margins. |
| 106 | +;; - `:toc` and `:number-sections` add a table of contents and section numbering. |
| 107 | + |
| 108 | +;; ## Showcase: Math, Style, and Substance |
| 109 | + |
| 110 | +;; Inline math: $E = mc^2$ (because every science article needs it!) |
| 111 | + |
| 112 | +;; Display math: |
| 113 | + |
| 114 | +;; $$ |
| 115 | +;; \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} |
| 116 | +;; $$ |
| 117 | + |
| 118 | +;; Or a system of equations: |
| 119 | + |
| 120 | +;; $$ |
| 121 | +;; \begin{aligned} |
| 122 | +;; a^2 + b^2 &= c^2 \\ |
| 123 | +;; e^{i\pi} + 1 &= 0 |
| 124 | +;; \end{aligned} |
| 125 | +;; $$ |
| 126 | + |
| 127 | +;; You can add figures, tables, and code blocks using Clojure code. |
| 128 | + |
| 129 | +;; For more details and advanced options, see the [Quarto PDF documentation](https://quarto.org/docs/output-formats/pdf-basics.html). |
| 130 | + |
| 131 | +;; --- |
| 132 | + |
| 133 | +;; ## Visualizing Data: Adding Charts to Your PDF |
| 134 | + |
| 135 | +;; A journal-style PDF can include charts alongside your narrative and code. |
| 136 | +;; Let's create a simple dataset and visualize it using Tablecloth and Tableplot: |
| 137 | + |
| 138 | +(def scatter-ds |
| 139 | + (tc/dataset {:x [1 2 3 4 5] |
| 140 | + :y [10 20 15 25 18] |
| 141 | + :z [1 2 1 2 1]})) |
| 142 | + |
| 143 | +(-> scatter-ds |
| 144 | + (tp/base {:=title "Sample Scatter Plot"}) |
| 145 | + (tp/layer-point {:=x :x |
| 146 | + :=y :y |
| 147 | + :=color :z})) |
| 148 | + |
| 149 | +;; Tableplot lets you create histograms, scatter plots, bar charts, and more. |
| 150 | +;; These charts will appear in your PDF just as they do in your HTML output. |
| 151 | +;; For more advanced visualizations, see the Tableplot and Plotly documentation. |
| 152 | + |
| 153 | +;; --- |
| 154 | + |
| 155 | +;; ## Conclusion |
| 156 | + |
| 157 | +;; For most needs, browser-based PDF export is fast and easy. |
| 158 | +;; For more traditional style typeset PDFs, set `[:format :pdf]` to get a PDF file. |
0 commit comments