kramdown-latexish 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 06fa0ad97174ba629adeb406d91151b6b4aba7fc47d0b3b8e33d2b9aa147e722
+  data.tar.gz: d9af99b898053cd8dc701fac591520eba772855ad2e479197c1b0b90f048098b
+SHA512:
+  metadata.gz: 54597cc241e9985853017b5f3e56140917d0b898ad7d8451c9701b77db625f59060a110867a37acbf35b6750f88fdbe465797c97cd1e6f2b1d031d2495d4860c
+  data.tar.gz: ebaacce34386a0ea7fce3c848891e7f4e9e22f018f026bd53d4b2d60814c7b901ba33f12f9b59fe6adcbb881f9d9bde929e093f99a81b5dc982edf681965dce9

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+3.0.6

data/.travis.yml

@@ -0,0 +1,6 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+# Ruby version specified by .ruby-version
+before_install: gem install bundler -v 2.2.33

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in kramdown-latexish.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,82 @@
+PATH
+  remote: .
+  specs:
+    kramdown-latexish (1.0.0)
+      bibtex-ruby (~> 6.0)
+      citeproc-ruby (~> 2.0)
+      csl-styles (~> 2.0)
+      kramdown (~> 2.4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    bibtex-ruby (6.0.0)
+      latex-decode (~> 0.0)
+    binding_of_caller (1.0.0)
+      debug_inspector (>= 0.0.1)
+    citeproc (1.0.10)
+      namae (~> 1.0)
+    citeproc-ruby (2.0.0)
+      citeproc (~> 1.0, >= 1.0.9)
+      csl (~> 2.0)
+    coderay (1.1.3)
+    csl (2.0.0)
+      namae (~> 1.0)
+      rexml
+    csl-styles (2.0.1)
+      csl (~> 2.0)
+    debug_inspector (1.1.0)
+    diff-lcs (1.5.0)
+    kramdown (2.4.0)
+      rexml
+    latex-decode (0.4.0)
+    namae (1.1.1)
+    parser (3.2.2.1)
+      ast (~> 2.4.1)
+    proc_to_ast (0.1.0)
+      coderay
+      parser
+      unparser
+    rake (10.5.0)
+    rexml (3.2.5)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-parameterized (1.0.0)
+      rspec-parameterized-core (< 2)
+      rspec-parameterized-table_syntax (< 2)
+    rspec-parameterized-core (1.0.0)
+      parser
+      proc_to_ast
+      rspec (>= 2.13, < 4)
+      unparser
+    rspec-parameterized-table_syntax (1.0.0)
+      binding_of_caller
+      rspec-parameterized-core (< 2)
+    rspec-support (3.12.0)
+    unparser (0.6.7)
+      diff-lcs (~> 1.3)
+      parser (>= 3.2.0)
+
+PLATFORMS
+  x86_64-darwin-20
+
+DEPENDENCIES
+  bundler (~> 2.2)
+  kramdown-latexish!
+  rake (~> 10.0)
+  rspec (~> 3.0)
+  rspec-parameterized (~> 1.0)
+
+BUNDLED WITH
+   2.2.33

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Luc J. Bourhis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,283 @@
+# Kramdown::Latexish
+
+It is an extension of the Kramdown syntax taylored for mathematical articles. Its general philosophy is to imitate LaTeX as much as possible without being too verbose. This document describes the new syntactical elements added to Kramdown. We refer the reader to the documentation of the API for guidance to use it.
+
+## New syntax
+
+An important point is that each document has a language associated to it, and several concepts are then accordingly localised. We currently support English and French only but the code could easily be extended to support many more. We will provide HTML conversion as illustrations as it will be the main target but there is no conceptual reason the other converters should not work.
+
+### Equations
+
+The only difference with vanilla Kramdown is that span math can be marked with single dollars, as it is customary in LaTeX, in addition to the double dollars used in vanilla Kramdown.
+
+```
+The identity $e^{i\pi} + 1 = 0$ is attributed to Euler.
+```
+
+will eventually produce the HTML
+
+```
+<p>The identity \(e^{i\pi} + 1 = 0\) is attributed to Euler.</p>
+```
+
+and so will
+
+```
+The identity is $$e^{i\pi} + 1 = 0$$ it attributed to Euler.
+```
+
+As in vanilla Kramdown, one shall write block equations as
+
+```
+The identity
+
+$$e^{i\pi} + 1 = 0$$
+
+is attributed to Euler.
+```
+
+exactly as in vanilla Kramdown. This produces
+
+```
+<p>The identity</p>
+
+\[ e^{i\pi} + 1 = 0 \]
+
+<p>is attributed to Euler.</p>
+```
+
+Typically, one shall then rely on MathJax to render `\(…\)` and `\[…\]`.
+
+### Theorem-like environments
+
+Theorem-like environments look as follow.
+
+```
+We shall first prove the following.
+
+Lemma (Eigenspace orthogonality)
+
+For any symmetric matrix $M$, and any two eigenvalues $\lambda \ne \lambda'$, the eigenvectors for $\lambda$ are orthogonal to the eigenvectors for $\lambda'$.
+
+\Lemma
+
+It can then be used to prove the following.
+
+Theorem (Diagonalisation)
+
+Any symmetric matrix can be diagonalised in an orthogonal basis.
+
+\Theorem
+```
+We have defined two such environments in this example, of two different types. We support the following types: :definition, :property, :lemma, :theorem, and :corollary, where we use a colon prefix to distinguish them from the English words. Each environment type is introduced by a capitalised name. In English, the types without the colon. In French: définition, propriété, lemme, théorème, et corollaire.
+
+Such an environment starts with a new paragraph, whose first word is one of those environment names. There cannot be any space at the beginning of that paragraph. A title for the environment may then appear between parentheses. Then, after perhaps some spaces, the paragraph must end: the next paragraph will start the body of the theorem.
+
+That body then extends until the environment name prefixed by a backlash. That end tag must be alone in its own paragraph, without any leading spaces but trailing spaces are allowed.
+
+The body of the environment is parsed as any other part of the document whereas the title line is encased in a header, and the whole environment in a section with class "theorem-like". Thus the example above renders as
+
+```
+<p>We shall first prove the following.</p>
+
+<section class="theorem-like">
+<h5><strong>Lemma 1</strong> (Eigenspace orthogonality)</h5>
+
+<p>For any symmetric matrix $M$, and any two eigenvalues $\lambda \ne \lambda'$, the eigenvectors for $\lambda$ are orthogonal to the eigenvectors for $\lambda'$.</p>
+
+</section>
+
+<p>It can then be used to prove the following.</p>
+
+<section class="theorem-like">
+<h5><strong>Theorem 1</strong> (Diagonalisation)</h5>
+
+<p>Any symmetric matrix can be diagonalised in an orthogonal basis.</p>
+
+</section>
+```
+A few remarks are in order:
+- the level of the header is user-customisable (h5 is the default)
+- as shown, each environment is numbered, with a different numbering for each type
+
+The first line of the environment can receives Kramdown IAL's in the usual manner
+```
+{: #Euler}
+Theorem
+
+\Theorem
+```
+or
+```
+Theorem
+{: #Euler}
+
+\Theorem
+```
+
+Either of those would result in the `<section>` tag to be be given the identifier `Euler`.
+
+### Automatically numbered section headers
+
+Sections as well as all theorem-like environment are automatically numbered.
+
+Section numbers follow the pattern x.y.z, for example
+
+```
+## One
+
+### One
+
+### Two
+
+## Two
+```
+
+would result in
+
+```
+<h2>1 One</h2>
+
+<h3>1.1 One</h3>
+
+<h3>1.2 Two</h3>
+
+<h2>2 Two<h2>
+```
+
+A single number is used for theorem-like environment, each type being numbered separately. For example,
+
+```
+Theorem (Taylor-Young)
+
+\Theorem
+
+Lemma (Rolle)
+
+\Lemma
+
+Theorem (Taylor-Cauchy)
+
+\Theorem
+```
+
+would result in `Theorem 1 (Taylor-Young)`, `Theorem 2 (Taylor-Cauchy)`, and `Lemma 1 (Rolle)`.
+
+### Referencing sections or theorem-like environments
+
+If a section or a theorem-like environment was given an identifier `xxx`, either with an IAL `{: ... #xxx ...}` or for a section the special syntax `{#xxx}`, then the syntax
+`[cref:xxx]` will produce the like of
+
+```
+section <a href="#xxx" title="Section 5">5</a>
+```
+
+whereas `[Cref:xxx]` (note the capital letter) will then produce
+
+```
+Section <a href="#xxx" title="Section 5">5</a>
+```
+
+i.e. a link to that identifier, with the number as content, and with the type of the element referred to.
+
+LaTeX users will recognise the cleveref package, from which we also borrow multiple references: `[cref:one,two,three,four,five,six]` will produce
+
+```
+sections&nbsp;<a href="#two" title="Section 1.1">1.1</a>, <a href="#four" title="Section 3.2">3.2</a>, and&nbsp;<a href="#six" title="Section 1.8">1.8</a>, theorems&nbsp;<a href="#one" title="Theorem 1">1</a> and&nbsp;<a href="#five" title="Theorem 3">3</a>, and corollary&nbsp;<a href="#three" title="Corollary 5">5</a>
+```
+
+if those id's had been assigned to the corresponding sections and environments. As can be seen, the spaces between "sections", "theorems", "corollary" and the following anchor are actually non-breakable (`&nbsp;`), and so are the spaces following the word "and".
+
+The words used to introduce the anchors are of course localised in the document language. As for equations, they are typeset as `eqn \eqref{key}` and `eqns \eqref{key} and \eqref{other_key}`, with non-breakable spaces before the `\eqref`. This way, Mathjax will be able to put the numbers for the equations which were marked with `\label{key}`.
+
+### Bibliography and citations
+
+Bibliographic entries come from a file or a string in BibTeX format, in which each entry must have a key. A reference section will be added at the end of the document, introduced by a level-2 header titled "References" in English and "Références" in French. It will contain only those entries that are cited in the document, thus skipping the entries in the BibTeX input which do not appear in the main body of the document.
+
+The user can choose the style used to format it, among those supported by CSL. A list can be found [here](https://github.com/citation-style-language/styles). Each entry will be wrapped in a paragraph with a class "bibliography-item" to make it easy to customize styling. With the APA style, it would for example looks like this
+```
+<p class="bibliography-item" id="Einstein1905"> Einstein, A. (1905). Zur Elektrodynamik bewegter Körper. <i>Annalen Der Physik</i>, <i>17</i>, 891.</p>
+```
+
+Two types of citations can be made, a parenthical one,
+```
+[citep: Einstein1905]
+```
+will give
+```
+<a href="#Einstein1905">(Einstein, 1905)</a>
+```
+and a textual one,
+```
+[citet: Einstein1905]
+```
+will give
+```
+<a href="#Einstein:SR">Einstein (1905)</a>
+```
+Thus the citation is always typeset with the surname and the year of publication, using the notation from the natbib LaTeX package
+
+When there are several authors, they all appear, for example
+```
+<p><a href="#Lammerzahl_etal">(Lämmerzahl, Braxmaier, Dittus, Müller, Peters, and Schiller, 2002)</a></p>
+```
+except if the BibTeX key is preceded by a star, i.e.
+```
+[citet: *Lammerzahl_etal]
+```
+will give
+```
+<a href="#Lammerzahl_etal">Lämmerzahl et al (1975)</a>
+```
+instead.
+
+Finaly, several citations can be made in one instruction
+```
+[citep: citeX, citeY, citeZ]
+```
+resulting in those citations being combined in a conjunction with commans and a final word "and", in the same manner as for the references to sections, theorem-like environments and equations described in the previous section.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'kramdown-latexish'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install kramdown-latexish
+
+## Usage
+
+Given a string `source` and a hash `options` (c.f. [Kramdown documentation](https://kramdown.gettalong.org/rdoc/Kramdown/Options.html)), the following snippet will convert the extended Kramdown in that string into HTML
+
+```ruby
+require 'kramdown/latexish'
+
+options = Kramdown::Latexish::taylor_options(options)
+doc = Kramdown::Document.initialize(source, options)
+converted = doc.html
+```
+
+The rationales for this design is explained in the documentation for method `Kramdown::Latexish::taylor_options`.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/luc-j-bourhis/kramdown-latexish.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "kramdown/latexish"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/kramdown-latexish.gemspec

@@ -0,0 +1,41 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "kramdown/latexish/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "kramdown-latexish"
+  spec.version       = Kramdown::Latexish::VERSION
+  spec.authors       = ["Luc J. Bourhis"]
+  spec.email         = ["luc_j_bourhis@mac.com"]
+
+  spec.summary       = %q{An extension of Kramdown taylored for math-heavy documents.}
+  spec.description   = %q{It provides theorem environments, and easy references to those environments as well as to equations and section headers. Moreover, a bibliography section can be generated from a BibTeX file, and an flexible and easy mean of citing bibliographical entries is provided.}
+  spec.homepage      = "https://github.com/luc-j-bourhis/kramdown-latexish"
+  spec.license       = "MIT"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 2.2"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rspec-parameterized", "~> 1.0"
+
+  # We extend this
+  spec.add_runtime_dependency "kramdown", "~> 2.4"
+
+  # BibTeX bibliography tools
+  spec.add_runtime_dependency 'bibtex-ruby', "~> 6.0"
+
+  # Render bibliography to HTML
+  spec.add_runtime_dependency 'citeproc-ruby', "~> 2.0"
+
+  # Bibliography styles
+  spec.add_runtime_dependency 'csl-styles', "~> 2.0"
+end

data/lib/kramdown/latexish/bibliographical.rb

@@ -0,0 +1,75 @@
+require 'latex/decode'
+
+module Kramdown::Latexish
+
+  # An extension dealing with BibTeX
+  #
+  # Mostly so that we can test those methods independently of our Kramdown
+  # parser and converter
+  #
+  # The class this is included into shall provide the following methods:
+  #
+  # bibliography:
+  #   An instance of BibTeX::Bibliography holding the references
+  #
+  # lexical_and:
+  #   The conjonction of a sequence of words with commas and the word "and"
+  #   C.f. module Lexical for the requirements
+  module Bibliographical
+    # Clean BibTeX field (typically the title)
+    #
+    # 1. It converts accents, diacritics, etc to unicode.
+    #    This is implemented withu bits and pieces of the latex-decode library.
+    #    We cannot use its main function LaTeX::decode because it removes
+    #    the dollars around equations, and all braces including in equations.
+    # 2. It strips the braces outside formulae.
+    #    Example: "{A} proof of $G_{\mu\nu} = 8\pi T_{\mu\nu}$ by {E}instein"
+    #    must become "A proof of $G_{\mu\nu} = 8\pi T_{\mu\nu}$ by Einstein"
+    # 3. It puts `\ce{...}` between dollars so that MathJax can eventually
+    #    display it
+    def clean_bibtex(txt)
+      # Let latex-decode do the bulk of the work
+      LaTeX::Decode::Base.normalize(txt)
+      LaTeX::Decode::Accents.decode!(txt)
+      LaTeX::Decode::Diacritics.decode!(txt)
+      LaTeX::Decode::Punctuation.decode!(txt)
+      LaTeX::Decode::Symbols.decode!(txt)
+      LaTeX::Decode::Greek.decode!(txt)
+
+      # Protect \ce
+      txt.gsub!(/(\\ce\{.*?\})/, '$\1$')
+
+      # Remove braces outside equations
+      txt.chars.map do |c|
+        if c == '$' ... c == '$'
+          c
+        elsif c != '{' and c != '}'
+          c
+        else
+          next
+        end
+      end.compact.join
+    end
+
+    # Text of the citation for the given bibtex key
+    def citation_for(key, style, et_al, loc)
+      unless (e = bibliography[key]).nil?
+        authors = e.authors.map(&:last)
+        authors_s = authors.size == 1 ? authors[0]
+                  : et_al             ? "#{authors[0]} et al"
+                  :                     @lex.and(authors)
+        case style
+        when :parenthetical
+          "(#{authors_s}, #{e.year})"
+        when :textual
+          "#{authors_s} (#{e.year})"
+        else
+          raise "Unknown citation style: #{style.to_s}"
+        end
+      else
+        warning("Unknown bibliographic citation at line #{loc}")
+        "??#{key}??"
+      end
+    end
+  end
+end