Update Elisp documentation (31.1.50)

Author: simon04

assets/stylesheets/pages/_elisp.scss

@@ -1,16 +1,8 @@
 @use 'global/classes';
 
 ._elisp {
-    dl > dt {
+    // definitions (@deffn, @defvr, ...) — the items of a plain @table have no class
+    dl > dt[class] {
         @extend %block-label, %label-blue;
     }
-
-    dl[compact] > dt {
-        background: none;
-        border-color: none;
-        line-height: normal;
-        margin: auto;
-        border: none;
-    }
-
 }

lib/docs/filters/elisp/clean_html.rb

@@ -4,24 +4,24 @@ class CleanHtmlFilter < Filter
       def call
 
         if current_url == root_url
-          # remove copyright header
-          css('table ~ p').remove
+          # remove the links to the Emacs website and the copyright notice
+          css('#content > p').remove
 
-          # remove "Detailed Node Listing" header
-          css('h2').remove
-
-          # remove "Detailed Node Listing" table
-          css('table')[1].remove
-
-          # remove copyright
+          # remove the license
           css('blockquote').remove
 
-          # remove index page in the index table
-          css('tbody tr:last-child').remove
+          # remove the short table of contents, the detailed one follows it
+          css('.element-shortcontents').remove
+
+          # remove "Table of Contents" header
+          css('.contents-heading').remove
         end
 
-        # remove navigation bar
-        css('.header').remove
+        # remove navigation bars and their separators
+        css('.nav-panel', 'hr').remove
+
+        # remove the "¶" links pointing at headers and definitions
+        css('.copiable-link').remove
 
         # Remove content in headers
         css('.chapter', '.section', '.subsection', '.subsubsection', '.appendix').each do |node|
@@ -44,11 +44,17 @@ def call
 
         end
 
-        # add id to each defun section that contains a functions, macro, etc.
+        # add a readable id to each definition of a function, macro, etc.
+        # (the items of a plain @table have no name)
+        ids = Hash.new(0)
         css('dl > dt').each do |node|
-          if !(node.parent.attribute('compact'))
-            node['id'] = node.at_css('strong').content
-          end
+          name = node.at_css('.def-name')
+          next unless name
+
+          id = name.content
+          # a few names are defined twice on the same page, e.g. as a function and as a variable
+          count = ids[id] += 1
+          node['id'] = count > 1 ? "#{id}-#{count}" : id
         end
 
         # remove br for style purposes
@@ -57,7 +63,7 @@ def call
         end
 
         # remove footnotes
-        css('.footnote').remove
+        css('.footnote', '.footnotes-segment').remove
 
         doc
       end

lib/docs/filters/elisp/entries.rb

@@ -1,24 +1,21 @@
 module Docs
   class Elisp
     class EntriesFilter < Docs::EntriesFilter
-      def get_name
-        # remove numbers at the beginning
-        name = at_css('.chapter', '.section', '.subsection', '.subsubsection', '.appendix').content.slice(/[[:alpha:]]...*/)
-
-        # remove 'Appendix' word
-        name = name.sub(/Appendix.{2}/, '') if name.include?('Appendix')
+      TYPES = {
+        'Function' => 'Builtin Functions',
+        'Predicate' => 'Builtin Functions',
+        'Macro' => 'Builtin Macros',
+        'Variable' => 'Builtin Variables',
+        'User Option' => 'Builtin User Options',
+        'Special Form' => 'Builtin Special Forms',
+        'Command' => 'Builtin Commands',
+        'Prefix Command' => 'Builtin Commands',
+        'Constant' => 'Builtin Constants'
+      }
 
-        # remove 'E.' notation for appendixes
-        if name.match?(/[[:upper:]]\./)
-          # remove 'E.'
-          name = name.sub(/[[:upper:]]\./, '')
-          # remove all dots (.)
-          name = name.gsub(/\./, '')
-          # remove all numbers
-          name = name.gsub(/[[:digit:]]/, '')
-        end
-
-        name
+      def get_name
+        # the CleanHtmlFilter already removed the numbering from the headers
+        at_css('.chapter', '.section', '.subsection', '.subsubsection', '.appendix').content
       end
 
       def get_type
@@ -29,19 +26,13 @@ def additional_entries
         entries = []
 
         css('dl > dt').each do |node|
-          if !(node.parent.attribute('compact'))
-            entry_type = 'Builtin Functions' if node.content.include?('Function')
-            entry_type = 'Builtin Macros' if node.content.include?('Macro')
-            entry_type = 'Builtin Variables' if node.content.include?('Variable')
-            entry_type = 'Builtin User Options' if node.content.include?('User Option')
-            entry_type = 'Builtin Special Forms' if node.content.include?('Special Form')
-            entry_type = 'Builtin Commands' if node.content.include?('Command')
-            entry_type = 'Builtin Constants' if node.content.include?('Constant')
+          name = node.at_css('.def-name')
+          next unless name
 
-            entry_name = node.at_css('strong').content
-            entry_path = slug + '#' + entry_name
-            entries << [entry_name, entry_path.downcase, entry_type]
-          end
+          category = node.at_css('.category-def')
+          entry_type = TYPES[category.content.strip.chomp(':')] if category
+          # the CleanHtmlFilter turned the name into the id of the definition
+          entries << [name.content, node['id'], entry_type]
         end
 
         entries

lib/docs/scrapers/elisp.rb

@@ -1,15 +1,15 @@
 module Docs
   class Elisp < FileScraper
     self.type = 'elisp'
-    self.release = '28.2'
+    self.release = '31.1.50'
     self.base_url= 'https://www.gnu.org/software/emacs/manual/html_node/elisp/'
     self.root_path = 'index.html'
     self.links = {
       home:'https://www.gnu.org/software/emacs/manual/elisp',
       code: 'https://git.savannah.gnu.org/cgit/emacs.git'
     }
 
-    html_filters.push 'elisp/entries', 'elisp/clean_html'
+    html_filters.push 'elisp/clean_html', 'elisp/entries'
 
     # some file that were not skipped by skip patterns
     options[:skip] = [
@@ -24,46 +24,17 @@ class Elisp < FileScraper
       /Antinews.html/,
       /GNU-Free-Documentation-License.html/,
       /GPL.html/,
-      /Tips.html/,
-      /Definition-of-/
+      /Tips.html/
     ]
 
-    # fix duplicates
-    options[:fix_urls]= -> (url) do
-      url.sub!('Window-Group.html', 'Basic-Windows.html')
-      url.sub!('Local-defvar-example.html', 'Using-Lexical-Binding.html')
-      url.sub!('Defining-Lisp-variables-in-C.html', 'Writing-Emacs-Primitives.html')
-      url.sub!('describe_002dsymbols-example.html', 'Accessing-Documentation.html')
-      url.sub!('The-interactive_002donly-property.html', 'Defining-Commands.html')
-      url.sub!('Text-help_002decho.html', 'Special-Properties.html')
-      url.sub!('Help-display.html', 'Special-Properties.html')
-      url.sub!('autoload-cookie.html', 'Autoload.html')
-      url.sub!('external_002ddebugging_002doutput.html', 'Output-Streams.html')
-      url.sub!('modifier-bits.html', 'Other-Char-Bits.html')
-      url.sub!('message_002dbox.html', 'Displaying-Messages.html')
-      url.sub!('abbreviate_002dfile_002dname.html', 'Directory-Names.html')
-      url.sub!('Inhibit-point-motion-hooks.html', 'Special-Properties.html')
-      url.sub!('Coding-systems-for-a-subprocess.html', 'Process-Information.html')
-      url.sub!('Process-Filter-Example.html', 'Filter-Functions.html')
-      url.sub!('Docstring-hyperlinks.html', 'Documentation-Tips.html')
-      url.sub!('seq_002dlet.html', 'Sequence-Functions.html')
-      url.sub!('should_005fquit.html', 'Module-Misc.html')
-      url.sub!('Display-Face-Attribute-Testing.html', 'Display-Feature-Testing.html')
-      url.sub!('module-initialization-function.html', 'Module-Initialization.html')
-      url.sub!('pcase_002dsymbol_002dcaveats.html', 'pcase-Macro.html')
-      url.sub!('intern.html', 'Module-Misc.html')
-      url.sub!('pcase_002dexample_002d1.html', 'pcase-Macro.html')
-      url
-    end
-
     options[:attribution]= <<-HTML
-      Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>
+      Copyright &copy; 1990-1996, 1998-2026 Free Software Foundation, Inc. <br>
       Licensed under the GNU GPL license.
     HTML
 
     def get_latest_version(opts)
       body = fetch('https://www.gnu.org/software/emacs/manual/html_node/elisp/index.html', opts)
-      body.scan(/version \d*\.?\d*/)[0].sub('version', '')
+      body.scan(/version \d+(?:\.\d+)*/)[0].sub('version ', '')
     end
 
     private