typst PDF: include a general and a precise TOC

we need to hide the Conten't false TOC in the PDF,
but keep it in the EPUB.

for #509

Author: vindarel

Makefile

@@ -13,7 +13,7 @@ epub: clean
 	sbcl --load make-cookbook.lisp --eval '(generate)' --eval '(to-epub)' --eval '(uiop:quit)'
 
 pdf: clean
-	sbcl --load make-cookbook.lisp --eval '(generate)' --eval '(to-pdf)' --eval '(uiop:quit)'
+	sbcl --disable-debugger --load make-cookbook.lisp --eval '(generate)' --eval '(to-pdf)' --eval '(uiop:quit)'
 
 sample-pdf: clean
 	sbcl --load make-cookbook.lisp --eval '(generate)' --eval '(sample-pdf)' --eval '(uiop:quit)'

foreword.md

@@ -4,6 +4,14 @@ title: Foreword
 
 <!-- that's for the EPUB and the PDF versions -->
 
+The Common Lisp Cookbook is a collaborative resource. Thanks to
+everyone who helped along the way.
+
+<!-- We want the Cookbook to help you learn Common Lisp in a wide range of -->
+<!-- day-to-day tasks. It can be used by Lisp newcomers as a tutorial -->
+<!-- (getting started, functions, CLOS…) and by everybody as a reference -->
+<!-- (loop!). -->
+
 We hope that these EPUB and PDF versions make the learning experience
 even more practical and enjoyable.
 

index.md

@@ -80,10 +80,16 @@ The CL Cookbook aims to tackle all sort of topics, for the beginner and for the
 * [Using the Win32 API](win32.html)
 <!-- epub-exclude-end -->
 
+<!-- pdf-include-start
 
-## Download in EPUB
+{{PDF-TOCS}}
 
-The Cookbook is also available in EPUB (and PDF) format.
+   pdf-include-end -->
+
+
+## Download in EPUB and PDF
+
+The Cookbook is also available in EPUB and PDF format.
 
 You can [download it directly in EPUB](https://github.com/LispCookbook/cl-cookbook/releases/download/2023-12-13/common-lisp-cookbook.epub) and [PDF](https://github.com/LispCookbook/cl-cookbook/releases/download/2023-12-13/common-lisp-cookbook.pdf), and you can **pay what you want** to further support its development:
 
@@ -110,7 +116,7 @@ The Cookbook has been translated to:
 * [Chinese simplified](https://oneforalone.github.io/cl-cookbook-cn/#/) ([Github](https://github.com/oneforalone/cl-cookbook-cn))
 * [Portuguese (Brazilian)](https://lisp.com.br/cl-cookbook/) ([Github](https://github.com/commonlispbr/cl-cookbook))
 
-# Other CL Resources
+## Other CL Resources
 
 <p id="two-cols"></p>
 
@@ -153,7 +159,7 @@ Specifications
 * [The Common Lisp HyperSpec](http://www.lispworks.com/documentation/HyperSpec/Front/index.htm) by Kent M. Pitman (also available in [Dash](https://kapeli.com/dash), [Zeal](https://zealdocs.org/) and [Velocity](https://velocity.silverlakesoftware.com/))
 * [The Common Lisp Community Spec](https://cl-community-spec.github.io/pages/index.html) - a new rendering produced from the ANSI specification draft, that everyone has the right to edit.
 
-# Further remarks
+## Further remarks
 
 This is a collaborative project that aims to provide for Common Lisp something
 similar to the [Perl Cookbook][perl] published by O'Reilly. More details about

make-cookbook.lisp

@@ -14,6 +14,17 @@
 
 (require 'asdf)
 
+;; You need the str library already installed:
+;; (ql:quickload "str")
+;; We use str:replace-all which relies on ppcre, so we need a library anyways.
+;; That's why I'm doing and using CIEL: small scripts are much easier to run and share.
+
+(handler-case
+    (require 'str)
+  (error ()
+    (format t "~&Please install the 'str' library to generate the PDF: (ql:quickload \"str\")~&")
+    (uiop:quit 1)))
+
 (defparameter chapters
   (list
    "index.md"
@@ -71,6 +82,17 @@
 (defparameter *epub-command-placeholder* "pandoc -o ~a --toc metadata.txt ~a"
   "format with book name and sources file.")
 
+(defparameter pdf-toc "== Table Of Contents (High-level)
+<high-level-table-of-contents>
+#outline(title: none, depth:1)
+
+#pagebreak()
+
+== Table Of Contents (Detailed)
+<detailed-table-of-contents>
+#outline(title: none, depth:3)
+")
+
 (defun reset-target ()
   (uiop:run-program (format nil "echo > ~a" *full-markdown*)))
 
@@ -95,6 +117,16 @@
   (format t "~&Generating a very short PDF sample.~&")
   (uiop:run-program (format nil "typst compile ~a" *typst-preamble*)))
 
+(defun insert-pdf-tocs ()
+  "Replace {{PDF-TOCS}} in the .typ file with a proper TOC declaration.
+
+  Using sed was tooooo cumbersome."
+  (format t "~&Inserting our table of contents into full-with-preamble.typ…~&")
+  (let* ((file.typ "full-with-preamble.typ")
+         (file-string (uiop:read-file-string file.typ))
+         (new-content (str:replace-all "{{PDF-TOCS}}" pdf-toc file-string)))
+    (str:to-file file.typ new-content)))
+
 (defun to-pdf ()
   "Needs pandoc >= 3.8 with Markdown to Typst conversion,
   and the typst binary on the path."
@@ -114,10 +146,14 @@
                     :output t
                     :error-output t)
 
+  ;; Insert our two outlines:
+  (insert-pdf-tocs)
+
   ;; Compile the Typst document:
   (uiop:run-program "typst compile full-with-preamble.typ" :output t :error-output t)
   ; todo utiliser min-book?
-  (uiop:run-program "mv full-with-preamble.pdf common-lisp-cookbook.pdf"))
+  (uiop:run-program "mv full-with-preamble.pdf common-lisp-cookbook.pdf")
+  (format t "Done: common-lisp-cookbook.pdf"))
 
 (defun build-full-source ()
   (format t "Creating the full source into ~a...~&" *full-markdown*)

metadata.txt

@@ -7,7 +7,7 @@ title:
 creator:
 - role: author
   text: The Common Lisp Cookbook contributors
-rights: © January 2025, vindarel <vindarel@mailz.org>.
-  This e-book is free of charge, but you can [pay what you want](https://ko-fi.com/s/01fee22a32) for it. 
+rights: © November 2025, vindarel <vindarel@mailz.org>.
+  This e-book is free of charge, but you can [pay what you want](https://ko-fi.com/s/01fee22a32) for it.
 cover-image: orly-cover.png
 ...

typst-preamble.typ

@@ -4,6 +4,7 @@
     to: "odd"
 )
 
+#set heading(numbering: "1.")
 #show link: underline
 
 #set page(numbering: "1")