improve the CSS

- There are now two HTML styles: :DEFAULT and :CHARTER.
  PAX:UPDATE-ASDF-SYSTEM-HTML-DOCS defaults to :DEFAULT by default,
  while the live browser defaults to :CHARTER.

- More mobile friendly: remove the table of contents sidebar if the
  page is too narrow.

- Fall back on Georgia for the main fontn if XCharter and Charter are
  not present.

- Fall back on Times New Roman for H1 headings if XEB Garamond is not
  present.

- Make it easier to use a sans-serif font (by editing :root in the CSS).

- Remove unused font files.

README

@@ -1203,6 +1203,12 @@ the same (see *DOCUMENT-FANCY-HTML-NAVIGATION*).
 Finally, note that the URLs exposed by the web server are subject to
 change.
 
+- [variable] *BROWSE-HTML-STYLE* :CHARTER
+
+    The HTML style to use for browsing live documentation. Affects only
+    non-w3m browsers. See *DOCUMENT-HTML-DEFAULT-STYLE* for the possible
+    values.
+
 ### Markdown Support
 
 The @MARKDOWN in docstrings is processed with the @3BMD library.
@@ -1802,11 +1808,13 @@ HTML documentation and the default CSS stylesheet.
 
 #### HTML Output
 
-- [function] UPDATE-ASDF-SYSTEM-HTML-DOCS SECTIONS ASDF-SYSTEM &KEY PAGES (TARGET-DIR (ASDF/SYSTEM:SYSTEM-RELATIVE-PATHNAME ASDF-SYSTEM "doc/")) (UPDATE-CSS-P T)
+- [function] UPDATE-ASDF-SYSTEM-HTML-DOCS SECTIONS ASDF-SYSTEM &KEY PAGES (TARGET-DIR (ASDF/SYSTEM:SYSTEM-RELATIVE-PATHNAME ASDF-SYSTEM "doc/")) (UPDATE-CSS-P T) (STYLE \*DOCUMENT-HTML-DEFAULT-STYLE\*)
 
     Generate pretty HTML documentation for a single ASDF system,
-    possibly linking to github. If UPDATE-CSS-P, copy the CSS style
-    sheet to TARGET-DIR as well. Example usage:
+    possibly linking to github. If UPDATE-CSS-P, copy the STYLE files to
+    TARGET-DIR (see *DOCUMENT-HTML-DEFAULT-STYLE*).
+
+    Example usage:
 
     ```
     (update-asdf-system-html-docs @pax-manual :mgl-pax)
@@ -1827,6 +1835,19 @@ HTML documentation and the default CSS stylesheet.
 
 See the following variables, which control HTML generation.
 
+- [variable] *DOCUMENT-HTML-DEFAULT-STYLE* :DEFAULT
+
+    The HTML style to use. It's either STYLE is either :DEFAULT or
+    :CHARTER. The :DEFAULT CSS stylesheet relies on the default
+    fonts (sans-serif, serif, monospace), while :CHARTER bundles some
+    fonts for a more controlled look.
+
+    The value of this variable affects the default style of
+    UPDATE-ASDF-SYSTEM-HTML-DOCS. If you change this variable, you may
+    need to do a hard refresh in the browser (often `C-<f5>`). See
+    *BROWSE-HTML-STYLE* for how to control the style used for
+    @BROWSING-LIVE-DOCUMENTATION.
+
 - [variable] *DOCUMENT-HTML-MAX-NAVIGATION-TABLE-OF-CONTENTS-LEVEL* NIL
 
     NIL or a non-negative integer. If non-NIL, it overrides
@@ -1982,7 +2003,7 @@ For example, this is how PAX registers itself:
 
 ```
 
-- [function] UPDATE-PAX-WORLD &KEY (DOCS \*REGISTERED-PAX-WORLD-DOCS\*) DIR
+- [function] UPDATE-PAX-WORLD &KEY (DOCS \*REGISTERED-PAX-WORLD-DOCS\*) DIR UPDATE-CSS-P (STYLE \*DOCUMENT-HTML-DEFAULT-STYLE\*)
 
     Generate HTML documentation for all DOCS. Files are created in
     DIR (`(asdf:system-relative-pathname :mgl-pax "world/")` by

README.md

@@ -1353,6 +1353,14 @@ the same (see [`*DOCUMENT-FANCY-HTML-NAVIGATION*`][6ab0]).
 Finally, note that the `URL`s exposed by the web server are subject to
 change.
 
+<a id="x-28MGL-PAX-3A-2ABROWSE-HTML-STYLE-2A-20VARIABLE-29"></a>
+
+- [variable] **\*BROWSE-HTML-STYLE\*** *:CHARTER*
+
+    The HTML style to use for browsing live documentation. Affects only
+    non-w3m browsers. See [`*DOCUMENT-HTML-DEFAULT-STYLE*`][90fa] for the possible
+    values.
+
 <a id="x-28MGL-PAX-3A-40MARKDOWN-SUPPORT-20MGL-PAX-3ASECTION-29"></a>
 
 ### 8.4 Markdown Support
@@ -2034,11 +2042,13 @@ HTML documentation and the default CSS stylesheet.
 
 <a id="x-28MGL-PAX-3AUPDATE-ASDF-SYSTEM-HTML-DOCS-20FUNCTION-29"></a>
 
-- [function] **UPDATE-ASDF-SYSTEM-HTML-DOCS** *SECTIONS ASDF-SYSTEM &KEY PAGES (TARGET-DIR (ASDF/SYSTEM:SYSTEM-RELATIVE-PATHNAME ASDF-SYSTEM "doc/")) (UPDATE-CSS-P T)*
+- [function] **UPDATE-ASDF-SYSTEM-HTML-DOCS** *SECTIONS ASDF-SYSTEM &KEY PAGES (TARGET-DIR (ASDF/SYSTEM:SYSTEM-RELATIVE-PATHNAME ASDF-SYSTEM "doc/")) (UPDATE-CSS-P T) (STYLE \*DOCUMENT-HTML-DEFAULT-STYLE\*)*
 
     Generate pretty HTML documentation for a single ASDF system,
-    possibly linking to github. If `UPDATE-CSS-P`, copy the CSS style
-    sheet to `TARGET-DIR` as well. Example usage:
+    possibly linking to github. If `UPDATE-CSS-P`, copy the `STYLE` files to
+    `TARGET-DIR` (see [`*DOCUMENT-HTML-DEFAULT-STYLE*`][90fa]).
+    
+    Example usage:
     
     ```
     (update-asdf-system-html-docs @pax-manual :mgl-pax)
@@ -2059,6 +2069,21 @@ HTML documentation and the default CSS stylesheet.
 
 See the following variables, which control HTML generation.
 
+<a id="x-28MGL-PAX-3A-2ADOCUMENT-HTML-DEFAULT-STYLE-2A-20VARIABLE-29"></a>
+
+- [variable] **\*DOCUMENT-HTML-DEFAULT-STYLE\*** *:DEFAULT*
+
+    The HTML style to use. It's either `STYLE` is either `:DEFAULT` or
+    `:CHARTER`. The `:DEFAULT` CSS stylesheet relies on the default
+    fonts (sans-serif, serif, monospace), while `:CHARTER` bundles some
+    fonts for a more controlled look.
+    
+    The value of this variable affects the default style of
+    [`UPDATE-ASDF-SYSTEM-HTML-DOCS`][bb12]. If you change this variable, you may
+    need to do a hard refresh in the browser (often `C-<f5>`). See
+    [`*BROWSE-HTML-STYLE*`][e527] for how to control the style used for
+    [Browsing Live Documentation][a595].
+
 <a id="x-28MGL-PAX-3A-2ADOCUMENT-HTML-MAX-NAVIGATION-TABLE-OF-CONTENTS-LEVEL-2A-20VARIABLE-29"></a>
 
 - [variable] **\*DOCUMENT-HTML-MAX-NAVIGATION-TABLE-OF-CONTENTS-LEVEL\*** *NIL*
@@ -2236,7 +2261,7 @@ For example, this is how PAX registers itself:
 
 <a id="x-28MGL-PAX-3AUPDATE-PAX-WORLD-20FUNCTION-29"></a>
 
-- [function] **UPDATE-PAX-WORLD** *&KEY (DOCS \*REGISTERED-PAX-WORLD-DOCS\*) DIR*
+- [function] **UPDATE-PAX-WORLD** *&KEY (DOCS \*REGISTERED-PAX-WORLD-DOCS\*) DIR UPDATE-CSS-P (STYLE \*DOCUMENT-HTML-DEFAULT-STYLE\*)*
 
     Generate HTML documentation for all `DOCS`. Files are created in
     `DIR` (`(asdf:system-relative-pathname :mgl-pax "world/")` by
@@ -3403,6 +3428,7 @@ they are presented.
   [8ece]: #x-28MGL-PAX-3ADEFINE-GLOSSARY-TERM-20MGL-PAX-3AMACRO-29 "MGL-PAX:DEFINE-GLOSSARY-TERM MGL-PAX:MACRO"
   [8f19]: dref/README.md#x-28DREF-3ALOCATE-20FUNCTION-29 "DREF:LOCATE FUNCTION"
   [8fb6]: #x-28MGL-PAX-3A-2ADOCUMENT-MARK-UP-SIGNATURES-2A-20VARIABLE-29 "MGL-PAX:*DOCUMENT-MARK-UP-SIGNATURES* VARIABLE"
+  [90fa]: #x-28MGL-PAX-3A-2ADOCUMENT-HTML-DEFAULT-STYLE-2A-20VARIABLE-29 "MGL-PAX:*DOCUMENT-HTML-DEFAULT-STYLE* VARIABLE"
   [9172]: http://www.lispworks.com/documentation/HyperSpec/Body/t_t.htm "T (MGL-PAX:CLHS CLASS)"
   [935f]: http://www.lispworks.com/documentation/HyperSpec/Issues/iss045.htm '"SUMMARY:CHARACTER-PROPOSAL:2-6-5" (MGL-PAX:CLHS MGL-PAX:SECTION)'
   [9439]: http://www.lispworks.com/documentation/HyperSpec/Body/m_pr_unr.htm "PRINT-UNREADABLE-OBJECT (MGL-PAX:CLHS MGL-PAX:MACRO)"
@@ -3447,6 +3473,7 @@ they are presented.
   [b93c]: http://www.lispworks.com/documentation/HyperSpec/Body/t_string.htm "STRING (MGL-PAX:CLHS CLASS)"
   [ba62]: dref/README.md#x-28FUNCTION-20MGL-PAX-3ALOCATIVE-29 "FUNCTION MGL-PAX:LOCATIVE"
   [ba74]: #x-28MGL-PAX-3A-40LINKS-20MGL-PAX-3ASECTION-29 "Links and Systems"
+  [bb12]: #x-28MGL-PAX-3AUPDATE-ASDF-SYSTEM-HTML-DOCS-20FUNCTION-29 "MGL-PAX:UPDATE-ASDF-SYSTEM-HTML-DOCS FUNCTION"
   [bc83]: #x-28MGL-PAX-3A-40MARKDOWN-SYNTAX-HIGHLIGHTING-20MGL-PAX-3ASECTION-29 "Syntax Highlighting"
   [bcb6]: http://www.lispworks.com/documentation/HyperSpec/Body/e_warnin.htm "WARNING (MGL-PAX:CLHS CONDITION)"
   [bdd5]: #x-28MGL-PAX-3A-40HOME-SECTION-20MGL-PAX-3ASECTION-29 "Home Section"
@@ -3485,6 +3512,7 @@ they are presented.
   [e391]: #x-28MGL-PAX-3ADISLOCATED-20MGL-PAX-3ALOCATIVE-29 "MGL-PAX:DISLOCATED MGL-PAX:LOCATIVE"
   [e442]: http://www.lispworks.com/documentation/HyperSpec/Body/03_d.htm '"3.4" (MGL-PAX:CLHS MGL-PAX:SECTION)'
   [e51f]: #x-28MGL-PAX-3AEXPORTABLE-REFERENCE-P-20GENERIC-FUNCTION-29 "MGL-PAX:EXPORTABLE-REFERENCE-P GENERIC-FUNCTION"
+  [e527]: #x-28MGL-PAX-3A-2ABROWSE-HTML-STYLE-2A-20VARIABLE-29 "MGL-PAX:*BROWSE-HTML-STYLE* VARIABLE"
   [e548]: dref/README.md#x-28MGL-PAX-3AWRITER-20MGL-PAX-3ALOCATIVE-29 "MGL-PAX:WRITER MGL-PAX:LOCATIVE"
   [e5ab]: http://www.lispworks.com/documentation/HyperSpec/Body/f_symb_3.htm "SYMBOL-PACKAGE (MGL-PAX:CLHS FUNCTION)"
   [e5af]: http://www.lispworks.com/documentation/HyperSpec/Body/t_symbol.htm "SYMBOL (MGL-PAX:CLHS CLASS)"

src/document/browse.lisp

@@ -39,8 +39,7 @@
   `slime-symbol-at-point`, possibly with a nearby locative the same
   way as in @NAVIGATING-IN-EMACS. The convenience function
   `mgl-pax-document-current-definition` documents the definition with
-  point in it.
-  """
+  point in it."""
   (@pax-urls section)
   (@apropos section)
   (@emacs-setup-for-browsing section)
@@ -136,7 +135,13 @@
   the same (see *DOCUMENT-FANCY-HTML-NAVIGATION*).
 
   Finally, note that the URLs exposed by the web server are subject to
-  change.""")
+  change."""
+  (*browse-html-style* variable))
+
+(defvar *browse-html-style* :charter
+  "The HTML style to use for browsing live documentation. Affects only
+  non-w3m browsers. See *DOCUMENT-HTML-DEFAULT-STYLE* for the possible
+  values.")
 
 ;;; Document PAX*-URL in FILENAME, both STRINGs. Return a `file:' URL
 ;;; as (:FILE-URL <URL>) or (:ERROR <STRING>). FILENAME may denote a

src/document/document-util.lisp

@@ -70,20 +70,36 @@
 (defsection @html-output (:title "HTML Output")
   (update-asdf-system-html-docs function)
   "See the following variables, which control HTML generation."
+  (*document-html-default-style* variable)
   (*document-html-max-navigation-table-of-contents-level* variable)
   (*document-html-head* variable)
   (*document-html-sidebar* variable)
   (*document-html-top-blocks-of-links* variable)
   (*document-html-bottom-blocks-of-links* variable))
 
+(defvar *document-html-default-style* :default
+  "The HTML style to use. It's either STYLE is either :DEFAULT or
+  :CHARTER. The :DEFAULT CSS stylesheet relies on the default
+  fonts (sans-serif, serif, monospace), while :CHARTER bundles some
+  fonts for a more controlled look.
+
+  The value of this variable affects the default style of
+  UPDATE-ASDF-SYSTEM-HTML-DOCS. If you change this variable, you may
+  need to do a hard refresh in the browser (often `C-<f5>`). See
+  *BROWSE-HTML-STYLE* for how to control the style used for
+  @BROWSING-LIVE-DOCUMENTATION.")
+
 (defun/autoloaded update-asdf-system-html-docs
     (sections asdf-system &key pages
               (target-dir (asdf:system-relative-pathname
                            asdf-system "doc/"))
-              (update-css-p t))
+              (update-css-p t)
+              (style *document-html-default-style*))
   "Generate pretty HTML documentation for a single ASDF system,
-  possibly linking to github. If UPDATE-CSS-P, copy the CSS style
-  sheet to TARGET-DIR as well. Example usage:
+  possibly linking to github. If UPDATE-CSS-P, copy the STYLE files to
+  TARGET-DIR (see *DOCUMENT-HTML-DEFAULT-STYLE*).
+
+  Example usage:
 
   ```
   (update-asdf-system-html-docs @pax-manual :mgl-pax)
@@ -100,16 +116,17 @@
                         :mgl-pax
                         \"https://github.com/melisgl/mgl-pax\"))))
   ```"
-  (document-html sections pages target-dir update-css-p nil))
+  (document-html sections pages target-dir update-css-p style nil))
 
 ;;; Generate with the default HTML look.
-(defun document-html (sections page-specs target-dir update-css-p
+(defun document-html (sections page-specs target-dir update-css-p style
                       link-to-pax-world-p)
   (when update-css-p
-    (copy-css target-dir))
+    (copy-css style target-dir))
   (document sections
-            :pages (add-html-defaults-to-page-specs (ensure-list sections)
-                    page-specs target-dir link-to-pax-world-p)
+            :pages (add-html-defaults-to-page-specs
+                    (ensure-list sections) page-specs target-dir
+                    link-to-pax-world-p)
             :format :html))
 
 (defun add-html-defaults-to-page-specs (sections page-specs dir
@@ -160,19 +177,26 @@
 
 (defun remove-special-chars (string)
   (remove-if (lambda (char)
-               (find char "!@#$%^&*"))
+               (find char "!@#$%^&*/"))
              string))
 
-(defun copy-css (target-dir)
-  (ensure-directories-exist target-dir)
-  (loop for file in '("src/document/jquery.min.js"
-                      "src/document/toc.min.js"
-                      "src/document/style.css")
-        do (let ((target-file (merge-pathnames (file-namestring file)
-                                               target-dir)))
-             (uiop:delete-file-if-exists target-file)
-             (uiop:copy-file (asdf:system-relative-pathname :mgl-pax file)
-                             target-file))))
+(defun copy-css (style target-dir)
+  (copy-dir (html-style-dir style) target-dir))
+
+(defun copy-dir (dir to-dir)
+  (dolist (file (uiop:directory* (merge-pathnames "*.*" dir)))
+    (let* ((relative-file (enough-namestring (namestring file) dir))
+           (to-file (merge-pathnames relative-file to-dir)))
+      (uiop:delete-file-if-exists to-file)
+      (ensure-directories-exist to-file)
+      (if (uiop:file-pathname-p file)
+          (uiop:copy-file file to-file)
+          (copy-dir file to-file)))))
+
+(defun html-style-dir (style)
+  (asdf:system-relative-pathname :mgl-pax (ecase style
+                                            ((:default) "web/default/")
+                                            ((:charter) "web/charter/"))))
 
 (defvar *document-html-head* nil
   "Stuff to be included in the `<head>` of the generated HTML.
@@ -352,8 +376,9 @@
 
 ;;;; The autoloaded part of @PAX-WORLD
 
-(defun/autoloaded update-pax-world (&key (docs *registered-pax-world-docs*)
-                                         dir)
+(defun/autoloaded update-pax-world
+    (&key (docs *registered-pax-world-docs*) dir update-css-p
+          (style *document-html-default-style*))
   "Generate HTML documentation for all DOCS. Files are created in
   DIR (`(asdf:system-relative-pathname :mgl-pax \"world/\")` by
   default if DIR is NIL). DOCS is a list of entries of the form (NAME
@@ -367,7 +392,7 @@
   If necessary a default page spec is created for every section."
   (let ((dir (or dir (asdf:system-relative-pathname :mgl-pax "world/"))))
     (multiple-value-bind (sections pages) (sections-and-pages docs)
-      (create-pax-world sections pages dir nil))))
+      (create-pax-world sections pages dir update-css-p style))))
 
 (defun sections-and-pages (registered-docs)
   (values (apply #'append (mapcar #'denoted-list
@@ -394,7 +419,7 @@
   that clicking on the locative type (e.g. `[function]`) will take you
   to the sources on github if possible."))
 
-(defun create-pax-world (sections page-specs dir update-css-p)
+(defun create-pax-world (sections page-specs dir update-css-p style)
   (define-pax-world-dummy)
   (unwind-protect
        (progn
@@ -405,7 +430,7 @@
                                 :output (,(merge-pathnames "index.html" dir)
                                          ,@*default-output-options*))
                               page-specs)
-                        dir update-css-p t))
+                        dir update-css-p style t))
     (setq @pax-world-dummy nil)))
 
 (defun set-pax-world-list (objects)
@@ -443,11 +468,11 @@
         (pax-file (ecase format
                     ((:plain) "README")
                     ((:markdown) "README.md")
-                    ((:html) "README.html")))
+                    ((:html) "doc/pax-manual.html")))
         (dref-file (ecase format
                      ((:plain) "dref/README")
                      ((:markdown) "dref/README.md")
-                     ((:html) "dref/README.html"))))
+                     ((:html) "doc/dref-manual.html"))))
     `((:objects (, @pax-manual)
        :output (,(asdf:system-relative-pathname "mgl-pax" pax-file)
                 ,@*default-output-options*)
@@ -475,7 +500,8 @@
   (let ((*document-downcase-uppercase-code* t))
     (update-asdf-system-html-docs (pax-and-dref-sections)
                                   :mgl-pax :pages (pax-and-dref-pages
-                                                   :html))))
+                                                   :html)
+                                  :update-css-p t :style :charter)))
 
 
 ;;; Load systems that use PAX and generate PAX World in
@@ -500,7 +526,7 @@
     (asdf:load-system :lmdb))
   (time
    (let ((*document-downcase-uppercase-code* t))
-     (update-pax-world))))
+     (update-pax-world :style :charter))))
 
 #+nil
 (update-pax-world*)

src/web/web.lisp

@@ -118,15 +118,12 @@
 
 ;;;; Web server
 
-;;; HUNCHENTOOT:*DISPATCH-TABLE* will be bound to this locally to
-;;; avoid conflicts with other HUNCHENTOOT servers running in the same
-;;; image.
 (defun web-toplevel-static-files ()
-  (let ((static-root (asdf:system-relative-pathname :mgl-pax "web/")))
-    (values (uiop:directory* (merge-pathnames "*.*" static-root))
-            static-root)))
+  (let ((style-dir (html-style-dir *browse-html-style*)))
+    (values (uiop:directory* (merge-pathnames "*.*" style-dir))
+            style-dir)))
 
-(defparameter *dispatch-table*
+(defun make-dispatch-table ()
   (multiple-value-bind (static-files static-root) (web-toplevel-static-files)
     (let ((dispatchers ()))
       (dolist (file static-files)
@@ -144,6 +141,23 @@
             dispatchers)
       dispatchers)))
 
+;;; Cache the dispatch table of the most recent request, which depends
+;;; on *BROWSE-HTML-STYLE*.
+(defvar *style-and-dispatch-table* nil)
+
+(defun dispatch-table ()
+  (if (eq (car *style-and-dispatch-table*) *browse-html-style*)
+      (cdr *style-and-dispatch-table*)
+      (let ((*browse-html-style* *browse-html-style*))
+        (setq *style-and-dispatch-table* (cons *browse-html-style*
+                                               (make-dispatch-table)))
+        (cdr *style-and-dispatch-table*))))
+
+;;; HUNCHENTOOT:*DISPATCH-TABLE* will be bound to this locally to
+;;; avoid conflicts with other HUNCHENTOOT servers running in the same
+;;; image.
+(defparameter *dispatch-table* (make-dispatch-table))
+
 (defvar *server*
   (make-instance 'hunchentoot:easy-acceptor
                  ;; Any free port
@@ -160,7 +174,7 @@
 (defmethod hunchentoot:acceptor-dispatch-request
     :around ((acceptor (eql *server*)) request)
   (declare (ignorable request))
-  (let ((hunchentoot:*dispatch-table* (append *dispatch-table*
+  (let ((hunchentoot:*dispatch-table* (append (dispatch-table)
                                               *hyperspec-dispatch-table*))
         (*document-hyperspec-root*
           (cond ((null *web-document-hyperspec-root*)