datalog-theme 0.10.1 → 0.11.0

data/lib/datalog/latex_speech/words.json

@@ -0,0 +1,88 @@
+{
+  "about": "How a LaTeX expression reads as a label for a screen reader (#417). The build (lib/datalog/latex_speech.rb) and the browser (assets/js/math/latex-speech.js) both read this file, so the two say the same; tests/fixtures/latex-speech.json holds the cases both test suites check.",
+  "greek": [
+    "alpha", "beta", "gamma", "delta", "epsilon", "zeta", "eta", "theta", "iota", "kappa", "lambda", "mu",
+    "nu", "xi", "omicron", "pi", "rho", "sigma", "tau", "upsilon", "phi", "chi", "psi", "omega"
+  ],
+  "words": {
+    "varepsilon": "epsilon", "vartheta": "theta", "varphi": "phi", "varrho": "rho", "varsigma": "sigma",
+    "varpi": "pi", "varkappa": "kappa",
+
+    "leq": "less than or equal to", "le": "less than or equal to", "leqslant": "less than or equal to",
+    "geq": "greater than or equal to", "ge": "greater than or equal to", "geqslant": "greater than or equal to",
+    "neq": "not equal to", "ne": "not equal to", "approx": "approximately equal to",
+    "equiv": "equivalent to", "sim": "similar to", "simeq": "similar or equal to", "cong": "congruent to",
+    "propto": "proportional to", "ll": "much less than", "gg": "much greater than",
+    "in": "in", "notin": "not in", "ni": "contains", "subset": "subset of",
+    "subseteq": "subset of or equal to", "supset": "superset of", "supseteq": "superset of or equal to",
+    "mid": "given", "parallel": "parallel to", "perp": "perpendicular to",
+
+    "to": "to", "rightarrow": "to", "longrightarrow": "to", "mapsto": "maps to",
+    "leftarrow": "left arrow", "gets": "gets", "Rightarrow": "implies", "implies": "implies",
+    "Longrightarrow": "implies", "Leftarrow": "is implied by", "impliedby": "is implied by",
+    "Leftrightarrow": "if and only if", "iff": "if and only if", "leftrightarrow": "left right arrow",
+    "uparrow": "up arrow", "downarrow": "down arrow",
+
+    "times": "times", "cdot": "dot", "div": "divided by", "pm": "plus or minus", "mp": "minus or plus",
+    "ast": "star", "star": "star", "circ": "circle", "bullet": "bullet", "oplus": "direct sum",
+    "otimes": "tensor product", "cup": "union", "cap": "intersection", "setminus": "minus",
+    "wedge": "and", "land": "and", "vee": "or", "lor": "or", "neg": "not", "lnot": "not",
+    "forall": "for all", "exists": "there exists", "nexists": "there does not exist",
+
+    "infty": "infinity", "partial": "partial", "nabla": "nabla", "emptyset": "empty set",
+    "varnothing": "empty set", "prime": "prime", "angle": "angle", "triangle": "triangle",
+    "square": "square", "Box": "square", "blacksquare": "end of proof", "qed": "end of proof",
+    "hbar": "h bar", "ell": "ell", "aleph": "aleph", "dagger": "dagger",
+    "ldots": "dots", "cdots": "dots", "dots": "dots", "vdots": "dots", "ddots": "dots",
+
+    "langle": "left angle bracket", "rangle": "right angle bracket", "lvert": "|", "rvert": "|",
+    "vert": "|", "lVert": "double bar", "rVert": "double bar", "Vert": "double bar", "|": "double bar",
+    "lfloor": "floor of", "rfloor": "", "lceil": "ceiling of", "rceil": "",
+    "{": "{", "}": "}", "%": "percent", "$": "$", "&": "and", "#": "#", "_": "_", "colon": ":",
+
+    "newline": ";", ",": "", ";": "", ":": "", "!": "", " ": "", "quad": "", "qquad": "",
+    "enspace": "", "thinspace": "", "medspace": "", "thickspace": "", "negthinspace": "",
+    "negmedspace": "", "negthickspace": "",
+
+    "displaystyle": "", "textstyle": "", "scriptstyle": "", "scriptscriptstyle": "", "limits": "",
+    "nolimits": "", "nonumber": "", "notag": "", "allowbreak": "", "hline": "", "toprule": "",
+    "midrule": "", "bottomrule": ""
+  },
+  "big_operators": {
+    "sum": "summation", "prod": "product", "coprod": "coproduct", "bigcup": "union",
+    "bigcap": "intersection", "bigoplus": "direct sum", "bigotimes": "tensor product",
+    "int": "integral", "iint": "double integral", "iiint": "triple integral", "oint": "contour integral",
+    "max": "max", "min": "min", "sup": "sup", "inf": "inf", "argmax": "argmax", "argmin": "argmin"
+  },
+  "limits": { "lim": "limit", "limsup": "limit superior", "liminf": "limit inferior" },
+  "text": [
+    "text", "textrm", "textit", "textbf", "textsf", "texttt", "textnormal", "emph", "mbox", "hbox",
+    "mathrm", "mathit", "mathsf", "mathtt", "mathnormal", "operatorname", "boxed"
+  ],
+  "text_mode": [
+    "text", "textrm", "textit", "textbf", "textsf", "texttt", "textnormal", "emph", "mbox", "hbox"
+  ],
+  "styles": {
+    "mathbb": "double-struck", "mathcal": "script", "mathscr": "script", "mathfrak": "fraktur",
+    "mathbf": "bold", "boldsymbol": "bold", "bm": "bold", "pmb": "bold",
+    "vec": "vector", "overrightarrow": "vector", "cancel": "cancelled", "bcancel": "cancelled",
+    "xcancel": "cancelled", "sout": "cancelled"
+  },
+  "accents": {
+    "hat": "hat", "widehat": "hat", "bar": "bar", "overline": "bar", "tilde": "tilde",
+    "widetilde": "tilde", "dot": "dot", "ddot": "double dot", "underline": "underline",
+    "check": "check", "breve": "breve", "acute": "acute", "grave": "grave"
+  },
+  "silent_with_argument": [
+    "label", "tag", "hspace", "vspace", "phantom", "hphantom", "vphantom", "color", "eqref", "ref"
+  ],
+  "sizes": [
+    "left", "right", "middle", "big", "Big", "bigg", "Bigg", "bigl", "bigr", "Bigl", "Bigr", "biggl", "biggr",
+    "Biggl", "Biggr"
+  ],
+  "matrices": ["matrix", "pmatrix", "bmatrix", "Bmatrix", "vmatrix", "Vmatrix", "smallmatrix"],
+  "with_columns": ["array", "tabular", "alignat", "alignedat"],
+  "superscripts": { "2": "squared", "3": "cubed", "T": "transpose", "-1": "inverse", "prime": "prime" },
+  "primes": ["", "prime", "double prime", "triple prime"],
+  "roots": { "2": "square root", "3": "cube root" }
+}

data/lib/datalog/latex_speech.rb

@@ -0,0 +1,355 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Datalog
+  # Reads a LaTeX expression as words, for the label a screen reader announces.
+  # Symbols are spoken as words, since a screen reader may skip "∈" or "ℝ" at
+  # its usual settings. A command is read, or left out of the name when it
+  # isn't part of what the expression says (spacing, \label, a \tag's number),
+  # but never lost because no table knows it: an unknown one is read by its
+  # name (#417).
+  #
+  # The browser reads expressions the same way (assets/js/math/latex-speech.js),
+  # from the same table, latex_speech/words.json, and both test suites check
+  # tests/fixtures/latex-speech.json.
+  module LatexSpeech
+    TABLE = JSON.parse(File.read(File.expand_path("latex_speech/words.json", __dir__))).freeze
+    WORDS = TABLE["greek"].to_h { |name| [name, name] }
+                          .merge(TABLE["greek"].to_h { |name| ["#{name[0].upcase}#{name[1..]}", "capital #{name}"] })
+                          .merge(TABLE["words"]).freeze
+    BIG_OPERATORS = TABLE["big_operators"].freeze
+    LIMITS = TABLE["limits"].freeze
+    TEXT = TABLE["text"].to_set.freeze
+    TEXT_MODE = TABLE["text_mode"].to_set.freeze
+    STYLES = TABLE["styles"].freeze
+    ACCENTS = TABLE["accents"].freeze
+    SILENT_WITH_ARGUMENT = TABLE["silent_with_argument"].to_set.freeze
+    SIZES = TABLE["sizes"].to_set.freeze
+    MATRICES = TABLE["matrices"].to_set.freeze
+    WITH_COLUMNS = TABLE["with_columns"].to_set.freeze
+    MAX_DEPTH = 64
+
+    module_function
+
+    # The words a LaTeX expression reads as, or "" when it has none.
+    def speak(latex)
+      # Single spaces, none inside brackets or before punctuation. After the
+      # collapse each pattern matches a fixed character or two, so none
+      # backtracks.
+      words = Reader.new(tokenize(latex), depth: 0, environments: []).read
+                    .gsub(/[[:space:]]+/, " ")
+                    .gsub(/ ([,;:.!?)\]}])/, '\1')
+                    .gsub(/([(\[{]) /, '\1')
+                    .gsub(/;(?=;)/, "")
+      # A line break or a separator at either end reads as nothing.
+      edge = [" ", ";", ","]
+      chars = words.chars
+      chars.shift while edge.include?(chars.first)
+      chars.pop while edge.include?(chars.last)
+      chars.join
+    end
+
+    # Splits LaTeX into commands, brace groups and characters. It walks the
+    # text once, keeping open groups on a stack rather than recursing, and
+    # drops an unescaped % and the rest of its line.
+    def tokenize(source)
+      chars = source.to_s.chars
+      root = []
+      stack = [root]
+      index = 0
+      while index < chars.length
+        char = chars[index]
+        current = stack.last
+        case char
+        when "\\"
+          token, index = command_token(chars, index)
+          current << token if token
+        when "{"
+          group = { type: :group, tokens: [] }
+          current << group
+          stack << group[:tokens]
+          index += 1
+        when "}"
+          stack.pop if stack.length > 1
+          index += 1
+        when "%"
+          index += 1 while index < chars.length && chars[index] != "\n"
+        else
+          if char.match?(/[[:space:]]/)
+            current << { type: :space } unless current.last && current.last[:type] == :space
+          else
+            current << { type: :char, value: char }
+          end
+          index += 1
+        end
+      end
+      root
+    end
+
+    # The command a backslash at `index` starts: a run of letters, or the one
+    # character after it. A backslash that ends the text is none.
+    def command_token(chars, index)
+      finish = index + 1
+      finish += 1 while finish < chars.length && letter?(chars[finish])
+      finish += 1 if finish == index + 1 && finish < chars.length
+      token = { type: :command, name: chars[(index + 1)...finish].join } if finish > index + 1
+      [token, finish]
+    end
+
+    def letter?(char)
+      char.match?(/\A[a-zA-Z]\z/)
+    end
+
+    # Reads one list of tokens, as the browser's speak() does.
+    class Reader
+      SPECIAL = {
+        "frac" => :fraction, "dfrac" => :fraction, "tfrac" => :fraction, "cfrac" => :fraction,
+        "binom" => :binomial, "dbinom" => :binomial, "tbinom" => :binomial, "sqrt" => :root,
+        "begin" => :environment_change, "end" => :environment_change, "\\" => :line_break, "pmod" => :pmod,
+        "textcolor" => :text_color, "overset" => :marked, "stackrel" => :marked, "underset" => :marked,
+        "overbrace" => :brace, "underbrace" => :brace
+      }.freeze
+
+      def initialize(tokens, context)
+        @tokens = tokens
+        @context = context
+        @inner = context.merge(depth: context[:depth] + 1)
+        @index = 0
+        @out = +""
+      end
+
+      def read
+        return "" if @context[:depth] > MAX_DEPTH
+
+        while @index < @tokens.length
+          token = @tokens[@index]
+          @index += 1
+          case token[:type]
+          when :space then @out << " "
+          when :group then @out << Reader.new(token[:tokens], @inner).read
+          when :char then character(token[:value])
+          else command(token[:name])
+          end
+        end
+        @out
+      end
+
+      private
+
+      def character(char)
+        return @out << char if @context[:text]
+
+        case char
+        when "^" then word(superscript(argument))
+        when "_" then word("sub #{read_tokens(argument)}")
+        when "'" then primes
+        when "&" then @out << (MATRICES.include?(current_environment) || current_environment == "cases" ? ", " : " ")
+        when "~" then @out << " "
+        else @out << char
+        end
+      end
+
+      def command(name)
+        return send(SPECIAL[name], name) if SPECIAL.key?(name)
+        return big_operator(name) if BIG_OPERATORS.key?(name)
+        return limit(name) if LIMITS.key?(name)
+        return word("approaches") if name == "to" && @context[:approaches]
+
+        family(name)
+      end
+
+      def family(name)
+        if TEXT.include?(name)
+          star
+          word(read_tokens(argument, @inner.merge(text: TEXT_MODE.include?(name))))
+        elsif STYLES.key?(name) then word("#{STYLES[name]} #{read_tokens(argument)}")
+        elsif ACCENTS.key?(name) then word("#{read_tokens(argument)} #{ACCENTS[name]}")
+        elsif SIZES.include?(name) then @index += 1 if char?(@tokens[@index], ".")
+        elsif SILENT_WITH_ARGUMENT.include?(name)
+          star
+          argument
+        elsif WORDS.key?(name) then word(WORDS[name])
+        elsif LatexSpeech.letter?(name[0])
+          # A function name (\sin, \log) is read as written, and so is a command
+          # nothing here knows, rather than lost.
+          word(name)
+        end
+      end
+
+      def fraction(_name)
+        top = read_tokens(argument)
+        word("#{top} over #{read_tokens(argument)}")
+      end
+
+      def binomial(_name)
+        top = read_tokens(argument)
+        word("#{top} choose #{read_tokens(argument)}")
+      end
+
+      def root(_name)
+        degree = optional
+        order = degree ? read_tokens(degree) : "2"
+        word("#{TABLE['roots'][order] || "#{order}th root"} of #{read_tokens(argument)}")
+      end
+
+      def environment_change(name)
+        # A starred environment (align*) is the same environment, unnumbered.
+        named = argument.filter_map { |token| token[:value] if token[:type] == :char }.join.strip
+        environment = named.delete_suffix("*")
+        if name == "begin"
+          @context[:environments] << environment
+          argument if WITH_COLUMNS.include?(environment)
+        else
+          @context[:environments].pop
+        end
+        kind = if environment == "cases" then "cases"
+               elsif MATRICES.include?(environment) then "matrix"
+               end
+        word(name == "begin" ? kind : "end #{kind}") if kind
+      end
+
+      def line_break(_name)
+        optional
+        word(";")
+      end
+
+      def pmod(_name)
+        word("mod #{read_tokens(argument)}")
+      end
+
+      def text_color(_name)
+        argument
+        word(read_tokens(argument, @inner.merge(text: true)))
+      end
+
+      def marked(name)
+        mark = read_tokens(argument)
+        word("#{read_tokens(argument)} with #{mark} #{name == 'underset' ? 'below' : 'above'}")
+      end
+
+      # The script after a brace is its label, not a power or an index:
+      # \overbrace{a+b}^{n} reads "a+b with n above".
+      def brace(name)
+        base = read_tokens(argument)
+        side = name == "overbrace" ? "^" : "_"
+        skip_spaces
+        return word(base) unless char?(@tokens[@index], side)
+
+        @index += 1
+        word("#{base} with #{read_tokens(argument)} #{side == '^' ? 'above' : 'below'}")
+      end
+
+      def big_operator(name)
+        found = limits(@inner)
+        lower = found[:lower]
+        upper = found[:upper]
+        phrase = BIG_OPERATORS[name]
+        phrase += if lower && !lower.empty? && upper && !upper.empty? then " from #{lower} to #{upper}"
+                  elsif lower && !lower.empty? then " over #{lower}"
+                  elsif upper && !upper.empty? then " to #{upper}"
+                  else ""
+                  end
+        word(phrase)
+      end
+
+      def limit(name)
+        found = limits(@inner.merge(approaches: true))
+        parts = [LIMITS[name]]
+        parts << "as #{found[:lower]}" if found[:lower] && !found[:lower].empty?
+        parts << "to the power #{found[:upper]}" if found[:upper] && !found[:upper].empty?
+        word(parts.join(" "))
+      end
+
+      # The sub- and superscript after an operator, in either order.
+      def limits(lower_context)
+        found = {}
+        loop do
+          skip_spaces
+          token = @tokens[@index]
+          if command?(token, "limits") || command?(token, "nolimits")
+            @index += 1
+          elsif char?(token, "_") && !found.key?(:lower)
+            @index += 1
+            found[:lower] = read_tokens(argument, lower_context)
+          elsif char?(token, "^") && !found.key?(:upper)
+            @index += 1
+            found[:upper] = read_tokens(argument)
+          else
+            return found
+          end
+        end
+      end
+
+      def superscript(raised)
+        single = raised.length == 1 ? raised.first : nil
+        return "degrees" if command?(single, "circ")
+        return "transpose" if command?(single, "top")
+
+        content = read_tokens(raised)
+        TABLE["superscripts"].fetch(content) { "to the power #{content}" }
+      end
+
+      def primes
+        count = 1
+        while char?(@tokens[@index], "'")
+          count += 1
+          @index += 1
+        end
+        word(TABLE["primes"][count] || Array.new(count, "prime").join(" "))
+      end
+
+      def current_environment
+        @context[:environments].last
+      end
+
+      def word(value)
+        @out << " #{value} " if value && !value.empty?
+      end
+
+      def skip_spaces
+        @index += 1 while @tokens[@index] && @tokens[@index][:type] == :space
+      end
+
+      # The next argument: a group's tokens, or a single token.
+      def argument
+        skip_spaces
+        token = @tokens[@index]
+        return [] unless token
+
+        @index += 1
+        token[:type] == :group ? token[:tokens] : [token]
+      end
+
+      def optional
+        skip_spaces
+        return nil unless char?(@tokens[@index], "[")
+
+        collected = []
+        @index += 1
+        while @index < @tokens.length && !char?(@tokens[@index], "]")
+          collected << @tokens[@index]
+          @index += 1
+        end
+        @index += 1
+        collected
+      end
+
+      def star
+        @index += 1 if char?(@tokens[@index], "*")
+      end
+
+      def read_tokens(tokens, context = @inner)
+        Reader.new(tokens, context).read.strip
+      end
+
+      def char?(token, value)
+        token && token[:type] == :char && token[:value] == value
+      end
+
+      def command?(token, name)
+        token && token[:type] == :command && token[:name] == name
+      end
+    end
+  end
+end

data/lib/datalog/packages/command.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Datalog
+  # `datalog packages`: commands about the site's package pages.
+  class PackagesCommand < Thor
+    class_option :root, type: :string, default: Dir.pwd, aliases: "-r",
+                        desc: "Path to the Jekyll site using the DataLog theme"
+
+    desc "refresh", "Write each package's latest release, from its registries, to _data/package_releases.yml"
+    method_option :dry_run, type: :boolean, default: false, desc: "Print the file instead of writing it"
+    long_desc <<~DESC
+      Reads the latest release of every package in the packages collection from
+      each registry its `registry:` front matter names (PyPI, crates.io, RubyGems,
+      CRAN, npm): version, release date, licence, the language version it needs,
+      and whether it is a pre-release or yanked. The package layout shows these
+      over the front matter, and the build itself never goes to a registry.
+      If a registry cannot be read, nothing is written and the command exits 1.
+    DESC
+    def refresh
+      require_relative "refresh"
+      refresher = new_refresher
+      data, yaml = refresher.run(dry_run: options[:dry_run])
+      file = refresher.data_file.delete_prefix("#{refresher.root}/")
+      count = data.values.sum(&:size)
+      if count.zero?
+        say "No package names a registry this command reads (#{Packages::ENDPOINTS.keys.join(', ')}); " \
+            "#{file} was left as it was."
+      elsif options[:dry_run]
+        say yaml
+      else
+        say "Wrote #{count} #{count == 1 ? 'release' : 'releases'} to #{file}"
+      end
+    rescue Packages::Refresh::Error => e
+      say e.message, :red
+      exit 1
+    end
+
+    no_commands do
+      # What reads the registries; a test hands it a fetch that reads fixtures.
+      def new_refresher
+        Packages::Refresh.new(root: options[:root])
+      end
+    end
+
+    def self.exit_on_failure?
+      true
+    end
+  end
+end