rdoc 6.15.1 → 6.16.0

data/lib/rdoc/generator/template/aliki/js/c_highlighter.js

@@ -0,0 +1,299 @@
+/**
+ * Client-side C syntax highlighter for RDoc
+ */
+
+(function() {
+  'use strict';
+
+  // C control flow and storage class keywords
+  const C_KEYWORDS = new Set([
+    'auto', 'break', 'case', 'continue', 'default', 'do', 'else', 'extern',
+    'for', 'goto', 'if', 'inline', 'register', 'return', 'sizeof', 'static',
+    'switch', 'while',
+    '_Alignas', '_Alignof', '_Generic', '_Noreturn', '_Static_assert', '_Thread_local'
+  ]);
+
+  // C type keywords and type qualifiers
+  const C_TYPE_KEYWORDS = new Set([
+    'bool', 'char', 'const', 'double', 'enum', 'float', 'int', 'long',
+    'restrict', 'short', 'signed', 'struct', 'typedef', 'union', 'unsigned',
+    'void', 'volatile', '_Atomic', '_Bool', '_Complex', '_Imaginary'
+  ]);
+
+  // Library-defined types (typedef'd in headers, not language keywords)
+  // Includes: Ruby C API types (VALUE, ID), POSIX types (size_t, ssize_t),
+  // fixed-width integer types (uint32_t, int64_t), and standard I/O types (FILE)
+  const C_TYPES = new Set([
+    'VALUE', 'ID', 'size_t', 'ssize_t', 'ptrdiff_t', 'uintptr_t', 'intptr_t',
+    'uint8_t', 'uint16_t', 'uint32_t', 'uint64_t',
+    'int8_t', 'int16_t', 'int32_t', 'int64_t',
+    'FILE', 'DIR', 'va_list'
+  ]);
+
+  // Common Ruby VALUE macros and boolean literals
+  const RUBY_MACROS = new Set([
+    'Qtrue', 'Qfalse', 'Qnil', 'Qundef', 'NULL', 'TRUE', 'FALSE', 'true', 'false'
+  ]);
+
+  const OPERATORS = new Set([
+    '==', '!=', '<=', '>=', '&&', '||', '<<', '>>', '++', '--',
+    '+=', '-=', '*=', '/=', '%=', '&=', '|=', '^=', '->',
+    '+', '-', '*', '/', '%', '<', '>', '=', '!', '&', '|', '^', '~'
+  ]);
+
+  // Single character that can start an operator
+  const OPERATOR_CHARS = new Set('+-*/%<>=!&|^~');
+
+  function isMacro(word) {
+    return RUBY_MACROS.has(word) || /^[A-Z][A-Z0-9_]*$/.test(word);
+  }
+
+  function isType(word) {
+    return C_TYPE_KEYWORDS.has(word) || C_TYPES.has(word) || /_t$/.test(word);
+  }
+
+  /**
+   * Escape HTML special characters
+   */
+  function escapeHtml(text) {
+    return text
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+  }
+
+  /**
+   * Check if position is at line start (only whitespace before it)
+   */
+  function isLineStart(code, pos) {
+    if (pos === 0) return true;
+    for (let i = pos - 1; i >= 0; i--) {
+      const ch = code[i];
+      if (ch === '\n') return true;
+      if (ch !== ' ' && ch !== '\t') return false;
+    }
+    return true;
+  }
+
+  /**
+   * Highlight C source code
+   */
+  function highlightC(code) {
+    const tokens = [];
+    let i = 0;
+    const len = code.length;
+
+    while (i < len) {
+      const char = code[i];
+
+      // Multi-line comment
+      if (char === '/' && code[i + 1] === '*') {
+        let end = code.indexOf('*/', i + 2);
+        end = (end === -1) ? len : end + 2;
+        const comment = code.substring(i, end);
+        tokens.push('<span class="c-comment">', escapeHtml(comment), '</span>');
+        i = end;
+        continue;
+      }
+
+      // Single-line comment
+      if (char === '/' && code[i + 1] === '/') {
+        const end = code.indexOf('\n', i);
+        const commentEnd = (end === -1) ? len : end;
+        const comment = code.substring(i, commentEnd);
+        tokens.push('<span class="c-comment">', escapeHtml(comment), '</span>');
+        i = commentEnd;
+        continue;
+      }
+
+      // Preprocessor directive (must be at line start)
+      if (char === '#' && isLineStart(code, i)) {
+        let end = i + 1;
+        while (end < len && code[end] !== '\n') {
+          if (code[end] === '\\' && end + 1 < len && code[end + 1] === '\n') {
+            end += 2; // Handle line continuation
+          } else {
+            end++;
+          }
+        }
+        const preprocessor = code.substring(i, end);
+        tokens.push('<span class="c-preprocessor">', escapeHtml(preprocessor), '</span>');
+        i = end;
+        continue;
+      }
+
+      // String literal
+      if (char === '"') {
+        let end = i + 1;
+        while (end < len && code[end] !== '"') {
+          if (code[end] === '\\' && end + 1 < len) {
+            end += 2; // Skip escaped character
+          } else {
+            end++;
+          }
+        }
+        if (end < len) end++; // Include closing quote
+        const string = code.substring(i, end);
+        tokens.push('<span class="c-string">', escapeHtml(string), '</span>');
+        i = end;
+        continue;
+      }
+
+      // Character literal
+      if (char === "'") {
+        let end = i + 1;
+        // Handle escape sequences like '\n', '\\', '\''
+        if (end < len && code[end] === '\\' && end + 1 < len) {
+          end += 2; // Skip backslash and escaped char
+        } else if (end < len) {
+          end++; // Single character
+        }
+        if (end < len && code[end] === "'") end++; // Closing quote
+        const charLit = code.substring(i, end);
+        tokens.push('<span class="c-value">', escapeHtml(charLit), '</span>');
+        i = end;
+        continue;
+      }
+
+      // Number (integer or float)
+      if (char >= '0' && char <= '9') {
+        let end = i;
+
+        // Hexadecimal
+        if (char === '0' && (code[i + 1] === 'x' || code[i + 1] === 'X')) {
+          end = i + 2;
+          while (end < len) {
+            const ch = code[end];
+            if ((ch >= '0' && ch <= '9') || (ch >= 'a' && ch <= 'f') || (ch >= 'A' && ch <= 'F')) {
+              end++;
+            } else {
+              break;
+            }
+          }
+        }
+        // Octal
+        else if (char === '0' && code[i + 1] >= '0' && code[i + 1] <= '7') {
+          end = i + 1;
+          while (end < len && code[end] >= '0' && code[end] <= '7') end++;
+        }
+        // Decimal/Float
+        else {
+          while (end < len) {
+            const ch = code[end];
+            if ((ch >= '0' && ch <= '9') || ch === '.') {
+              end++;
+            } else {
+              break;
+            }
+          }
+          // Scientific notation
+          if (end < len && (code[end] === 'e' || code[end] === 'E')) {
+            end++;
+            if (end < len && (code[end] === '+' || code[end] === '-')) end++;
+            while (end < len && code[end] >= '0' && code[end] <= '9') end++;
+          }
+        }
+
+        // Suffix (u, l, f, etc.)
+        while (end < len) {
+          const ch = code[end];
+          if (ch === 'u' || ch === 'U' || ch === 'l' || ch === 'L' || ch === 'f' || ch === 'F') {
+            end++;
+          } else {
+            break;
+          }
+        }
+
+        const number = code.substring(i, end);
+        tokens.push('<span class="c-value">', escapeHtml(number), '</span>');
+        i = end;
+        continue;
+      }
+
+      // Identifier or keyword
+      if ((char >= 'a' && char <= 'z') || (char >= 'A' && char <= 'Z') || char === '_') {
+        let end = i + 1;
+        while (end < len) {
+          const ch = code[end];
+          if ((ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') ||
+              (ch >= '0' && ch <= '9') || ch === '_') {
+            end++;
+          } else {
+            break;
+          }
+        }
+        const word = code.substring(i, end);
+
+        if (C_KEYWORDS.has(word)) {
+          tokens.push('<span class="c-keyword">', escapeHtml(word), '</span>');
+        } else if (isType(word)) {
+          // Check types before macros (VALUE, ID are types, not macros)
+          tokens.push('<span class="c-type">', escapeHtml(word), '</span>');
+        } else if (isMacro(word)) {
+          tokens.push('<span class="c-macro">', escapeHtml(word), '</span>');
+        } else {
+          // Check if followed by '(' -> function name
+          let nextCharIdx = end;
+          while (nextCharIdx < len && (code[nextCharIdx] === ' ' || code[nextCharIdx] === '\t')) {
+            nextCharIdx++;
+          }
+          if (nextCharIdx < len && code[nextCharIdx] === '(') {
+            tokens.push('<span class="c-function">', escapeHtml(word), '</span>');
+          } else {
+            tokens.push('<span class="c-identifier">', escapeHtml(word), '</span>');
+          }
+        }
+        i = end;
+        continue;
+      }
+
+      // Operators
+      if (OPERATOR_CHARS.has(char)) {
+        let op = char;
+        // Check for two-character operators
+        if (i + 1 < len) {
+          const twoChar = char + code[i + 1];
+          if (OPERATORS.has(twoChar)) {
+            op = twoChar;
+          }
+        }
+        tokens.push('<span class="c-operator">', escapeHtml(op), '</span>');
+        i += op.length;
+        continue;
+      }
+
+      // Everything else (punctuation, whitespace)
+      tokens.push(escapeHtml(char));
+      i++;
+    }
+
+    return tokens.join('');
+  }
+
+  /**
+   * Initialize C syntax highlighting on page load
+   */
+  function initHighlighting() {
+    const codeBlocks = document.querySelectorAll('pre[data-language="c"]');
+
+    codeBlocks.forEach(block => {
+      if (block.getAttribute('data-highlighted') === 'true') {
+        return;
+      }
+
+      const code = block.textContent;
+      const highlighted = highlightC(code);
+
+      block.innerHTML = highlighted;
+      block.setAttribute('data-highlighted', 'true');
+    });
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initHighlighting);
+  } else {
+    initHighlighting();
+  }
+})();

data/lib/rdoc/generator/template/aliki/js/search.js

@@ -0,0 +1,120 @@
+Search = function(data, input, result) {
+  this.data = data;
+  this.input = input;
+  this.result = result;
+
+  this.current = null;
+  this.view = this.result.parentNode;
+  this.searcher = new Searcher(data.index);
+  this.init();
+}
+
+Search.prototype = Object.assign({}, Navigation, new function() {
+  var suid = 1;
+
+  this.init = function() {
+    var _this = this;
+    var observer = function(e) {
+      switch(e.key) {
+        case 'ArrowUp':
+        case 'ArrowDown':
+          return;
+      }
+      _this.search(_this.input.value);
+    };
+    this.input.addEventListener('keyup', observer);
+    this.input.addEventListener('click', observer); // mac's clear field
+
+    this.searcher.ready(function(results, isLast) {
+      _this.addResults(results, isLast);
+    })
+
+    this.initNavigation();
+    this.setNavigationActive(false);
+  }
+
+  this.search = function(value, selectFirstMatch) {
+    this.selectFirstMatch = selectFirstMatch;
+
+    value = value.trim().toLowerCase();
+    if (value) {
+      this.setNavigationActive(true);
+    } else {
+      this.setNavigationActive(false);
+    }
+
+    if (value == '') {
+      this.lastQuery = value;
+      this.result.innerHTML = '';
+      this.result.setAttribute('aria-expanded', 'false');
+      this.setNavigationActive(false);
+    } else if (value != this.lastQuery) {
+      this.lastQuery = value;
+      this.result.setAttribute('aria-busy',     'true');
+      this.result.setAttribute('aria-expanded', 'true');
+      this.firstRun = true;
+      this.searcher.find(value);
+    }
+  }
+
+  this.addResults = function(results, isLast) {
+    var target = this.result;
+    if (this.firstRun && (results.length > 0 || isLast)) {
+      this.current = null;
+      this.result.innerHTML = '';
+    }
+
+    for (var i=0, l = results.length; i < l; i++) {
+      var item = this.renderItem.call(this, results[i]);
+      item.setAttribute('id', 'search-result-' + target.childElementCount);
+      target.appendChild(item);
+    };
+
+    if (this.firstRun && results.length > 0) {
+      this.firstRun = false;
+      this.current = target.firstChild;
+      this.current.classList.add('search-selected');
+    }
+    //TODO: ECMAScript
+    //if (jQuery.browser.msie) this.$element[0].className += '';
+
+    if (this.selectFirstMatch && this.current) {
+      this.selectFirstMatch = false;
+      this.select(this.current);
+    }
+
+    if (isLast) {
+      this.selectFirstMatch = false;
+      this.result.setAttribute('aria-busy', 'false');
+    }
+  }
+
+  this.move = function(isDown) {
+    if (!this.current) return;
+    var next = isDown ? this.current.nextElementSibling : this.current.previousElementSibling;
+    if (next) {
+      this.current.classList.remove('search-selected');
+      next.classList.add('search-selected');
+      this.input.setAttribute('aria-activedescendant', next.getAttribute('id'));
+      this.scrollIntoView(next, this.view);
+      this.current = next;
+      this.input.value = next.firstChild.firstChild.text;
+      this.input.select();
+    }
+    return true;
+  }
+
+  this.hlt = function(html) {
+    return this.escapeHTML(html).
+      replace(/\u0001/g, '<em>').
+      replace(/\u0002/g, '</em>');
+  }
+
+  this.escapeHTML = function(html) {
+    return html.replace(/[&<>"`']/g, function(c) {
+      return '&#' + c.charCodeAt(0) + ';';
+    });
+  }
+
+});
+

data/lib/rdoc/generator/template/aliki/js/theme-toggle.js

@@ -0,0 +1,112 @@
+(function() {
+  'use strict';
+
+  const STORAGE_KEY = 'rdoc-theme';
+  const THEME_LIGHT = 'light';
+  const THEME_DARK = 'dark';
+
+  /**
+   * Get the user's theme preference
+   * Priority: localStorage > system preference > light (default)
+   */
+  function getThemePreference() {
+    // Check localStorage first
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored === THEME_LIGHT || stored === THEME_DARK) {
+      return stored;
+    }
+
+    // Check system preference
+    if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
+      return THEME_DARK;
+    }
+
+    return THEME_LIGHT;
+  }
+
+  /**
+   * Apply theme to document
+   */
+  function applyTheme(theme) {
+    document.documentElement.setAttribute('data-theme', theme);
+    localStorage.setItem(STORAGE_KEY, theme);
+
+    // Update toggle button icon
+    const toggleBtn = document.getElementById('theme-toggle');
+    if (toggleBtn) {
+      const icon = toggleBtn.querySelector('.theme-toggle-icon');
+      if (icon) {
+        icon.textContent = theme === THEME_DARK ? '☀️' : '🌙';
+      }
+      toggleBtn.setAttribute('aria-label',
+        theme === THEME_DARK ? 'Switch to light mode' : 'Switch to dark mode'
+      );
+    }
+  }
+
+  /**
+   * Toggle between light and dark themes
+   */
+  function toggleTheme() {
+    const currentTheme = document.documentElement.getAttribute('data-theme') || THEME_LIGHT;
+    const newTheme = currentTheme === THEME_LIGHT ? THEME_DARK : THEME_LIGHT;
+    applyTheme(newTheme);
+
+    // Announce to screen readers
+    announceThemeChange(newTheme);
+  }
+
+  /**
+   * Announce theme change to screen readers
+   */
+  function announceThemeChange(theme) {
+    const announcement = document.createElement('div');
+    announcement.setAttribute('role', 'status');
+    announcement.setAttribute('aria-live', 'polite');
+    announcement.className = 'sr-only';
+    announcement.textContent = `Switched to ${theme} mode`;
+    document.body.appendChild(announcement);
+
+    // Remove after announcement
+    setTimeout(() => {
+      document.body.removeChild(announcement);
+    }, 1000);
+  }
+
+  /**
+   * Initialize theme on page load
+   */
+  function initTheme() {
+    // Apply theme immediately to prevent flash
+    const theme = getThemePreference();
+    applyTheme(theme);
+
+    // Set up toggle button listener
+    const toggleBtn = document.getElementById('theme-toggle');
+    if (toggleBtn) {
+      toggleBtn.addEventListener('click', toggleTheme);
+    }
+
+    // Listen for system theme changes
+    if (window.matchMedia) {
+      window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
+        // Only auto-switch if user hasn't manually set a preference
+        const stored = localStorage.getItem(STORAGE_KEY);
+        if (!stored) {
+          applyTheme(e.matches ? THEME_DARK : THEME_LIGHT);
+        }
+      });
+    }
+  }
+
+  // Initialize immediately (before DOMContentLoaded to prevent flash)
+  if (document.readyState === 'loading') {
+    // Apply theme as early as possible
+    const theme = getThemePreference();
+    document.documentElement.setAttribute('data-theme', theme);
+
+    document.addEventListener('DOMContentLoaded', initTheme);
+  } else {
+    initTheme();
+  }
+})();

data/lib/rdoc/generator/template/aliki/page.rhtml

@@ -0,0 +1,17 @@
+<body role="document" class="file has-toc">
+<%= render '_header.rhtml' %>
+<%= render '_sidebar_toggle.rhtml' %>
+
+<nav id="navigation" role="navigation">
+  <%= render '_sidebar_pages.rhtml' %>
+  <%= render '_sidebar_classes.rhtml' %>
+</nav>
+
+<main role="main" aria-label="Page <%= h file.full_name %>">
+<%= file.description %>
+</main>
+
+<%= render '_aside_toc.rhtml' %>
+
+<%= render '_footer.rhtml' %>
+</body>

data/lib/rdoc/generator/template/aliki/servlet_not_found.rhtml

@@ -0,0 +1,14 @@
+<body role="document">
+<%= render '_sidebar_toggle.rhtml' %>
+
+<nav id="navigation" role="navigation">
+  <%= render '_sidebar_pages.rhtml' %>
+  <%= render '_sidebar_classes.rhtml' %>
+</nav>
+
+<main role="main">
+  <h1>Not Found</h1>
+
+  <p><%= message %></p>
+</main>
+</body>

data/lib/rdoc/generator/template/aliki/servlet_root.rhtml

@@ -0,0 +1,65 @@
+<body role="document">
+<%= render '_sidebar_toggle.rhtml' %>
+
+<nav id="navigation" role="navigation">
+  <div id="project-navigation">
+    <div id="home-section" class="nav-section">
+      <h2>
+        <a href="<%= rel_prefix %>/" rel="home">Home</a>
+      </h2>
+    </div>
+
+    <%= render '_sidebar_search.rhtml' %>
+  </div>
+
+  <%= render '_sidebar_installed.rhtml' %>
+</nav>
+
+<main role="main">
+  <h1>Local RDoc Documentation</h1>
+
+  <p>Here you can browse local documentation from the ruby standard library and
+  your installed gems.</p>
+
+<%- extra_dirs = installed.select { |_, _, _, type,| type == :extra } %>
+<%- unless extra_dirs.empty? %>
+  <h2>Extra Documentation Directories</h2>
+
+  <p>The following additional documentation directories are available:</p>
+
+  <ol>
+  <%- extra_dirs.each do |name, href, exists, _, path| %>
+    <li>
+    <%- if exists %>
+      <a href="<%= href %>"><%= h name %></a> (<%= h path %>)
+    <%- else %>
+      <%= h name %> (<%= h path %>; <i>not available</i>)
+    <%- end %>
+    </li>
+  <%- end %>
+  </ol>
+<%- end %>
+
+<%- gems = installed.select { |_, _, _, type,| type == :gem } %>
+<%- missing = gems.reject { |_, _, exists,| exists } %>
+<%- unless missing.empty? then %>
+  <h2>Missing Gem Documentation</h2>
+
+  <p>You are missing documentation for some of your installed gems.
+  You can install missing documentation for gems by running
+  <kbd>gem rdoc --all</kbd>.  After installing the missing documentation you
+  only need to reload this page.  The newly created documentation will
+  automatically appear.</p>
+
+  <p>You can also install documentation for a specific gem by running one of
+  the following commands.</p>
+
+  <ul>
+  <%- names = missing.map { |name,| name.sub(/-([^-]*)$/, '') }.uniq %>
+  <%- names.each do |name| %>
+    <li><kbd>gem rdoc <%= h name %></kbd></li>
+  <%- end %>
+  </ul>
+<%- end %>
+</main>
+</body>

data/lib/rdoc/generator/template/darkfish/_head.rhtml

@@ -16,13 +16,8 @@
   <meta name="description" content="<%= h "#{file.page_name}: #{excerpt(file.comment)}" %>">
 <%- elsif @title %>
   <meta name="keywords" content="ruby,documentation,<%= h @title %>">
-
-  <%- if @options.main_page and
-      main_page = @files.find { |f| f.full_name == @options.main_page } then %>
-    <meta name="description" content="<%= h "#{@title}: #{excerpt(main_page.comment)}" %>">
-  <%- else %>
-    <meta name="description" content="Documentation for <%= h @title %>">
-  <%- end %>
+<% description = @main_page ? "#{@title}: #{excerpt(@main_page.comment)}" : "Documentation for #{@title}" %>
+  <meta name="description" content="<%= h description %>">
 <%- end %>
 
 <%- if canonical_url = @options.canonical_root %>

data/lib/rdoc/generator/template/darkfish/_sidebar_search.rhtml

@@ -4,6 +4,7 @@
       <input id="search-field" role="combobox" aria-label="Search"
              aria-autocomplete="list" aria-controls="search-results"
              type="text" name="search" placeholder="Search (/) for a class, method, ..." spellcheck="false"
+             autocomplete="off"
              title="Type to search, Up and Down to navigate, Enter to load">
     </div>
 

data/lib/rdoc/generator/template/darkfish/table_of_contents.rhtml

@@ -47,7 +47,7 @@
    unless table.empty? then %>
     <ul>
 <%- table.each do |item| %>
-<%-   label = item.respond_to?(:label) ? item.label(klass) : item.aref %>
+  <%- label = item.respond_to?(:label) ? item.label(klass) : item.aref %>
       <li><a href="<%= klass.path %>#<%= label %>"><%= item.plain_html %></a></li>
 <%- end %>
     </ul>

data/lib/rdoc/generator/template/json_index/js/searcher.js

@@ -57,10 +57,14 @@ Searcher.prototype = new function() {
   }
 
   function buildRegexps(queries) {
+    // A small minority of older browsers don't have RegExp.escape
+    // but it's not worth including a complex polyfill.
+    var escape = RegExp.escape || function(s) { return s };
+
     return queries.map(function(query) {
       var pattern = [];
       for (var i = 0; i < query.length; i++) {
-        var char = RegExp.escape(query[i]);
+        var char = escape(query[i]);
         pattern.push('([' + char + '])([^' + char + ']*?)');
       }
       return new RegExp(pattern.join(''), 'i');