首頁 探索 說明
登入
emily
/
Lettus-CSS-MathJax
關註 1
讚好 0
複刻 0
檔案 問題管理 0 合併請求 0 Wiki
分支: master
分支列表 標籤列表
Lettus-CSS-M...
/
DOCUMENTATION.md

DOCUMENTATION.md 10 KB
永久連結 文件歷史 原始文件

Lettus

These Cascading Style Sheet and JavaScript files make long mathematical texts such as articles, books or essays easier to read in a web browser. MathJax is used for the formulas. The goal is to produce LaTeX for the web.

The code is based on work done previously in the repository https://notabug.org/emily/math_scattering_theory

Constributions are welcome: https://notabug.org/emily/Lettus-CSS-MathJax

How to prepare your document

There's a few steps that must be done before being able to use this style sheet and JavaScript code. And example html-file is given in this repository, example.html. Basically all that must be done is to put your html-file into the root directory of this project, that is, the same directory as typeset.js resides. After that you should add the following tags to your document's <head>:

  <link rel="stylesheet" href="lettus.css">
  <script src="lettus_conf_mj.js"></script>
  <script src="lettus_typeset.js"></script>

The first of these is needed for styling the document, i.e. set the correct fonts, margins, etc. The second line is used for configuring MathJax. The third one is for starting MathJax and running the scripts of this project, like for example numbering the theorems.

If you like to use personal LaTeX macros, you should add them in a MathJax equation anywhere after loading typeset.js. A good place is right at the end of <head>, for example

  \(
    \newcommand{\C}{\mathbb{C}}
    \newcommand{\R}{\mathbb{R}}
    \newcommand{\N}{\mathbb{N}}
  \)

If you would like the fonts to scale correctly on mobile devices, it is worth also adding the following tag into the <head>-section:

  <meta name="viewport" content="width=device-width, initial-scale=1.0">

For a minimal example html file, you could have

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Minimal example</title>
  <link rel="stylesheet" href="lettus.css">
  <script src="lettus_conf_mj.js"></script>
  <script src="lettus_typeset.js"></script>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  \(
    \newcommand{\C}{\mathbb{C}}
    \newcommand{\R}{\mathbb{R}}
  \)
</head>

<body>
<h1>First heading</h1>
<p>
  This is the first equation: $x \in \R \Longrightarrow x \in \C$.
</p>
</body>
</html>

Typing a document

The whole purpose of this project is to make it pleasant to typeset a LaTeX-quality document in an HTML-environment. First, prepare your document as described in the above step. Then start typing your document into the <body>-section.

Use <hX>...</hX> for headings of level X, where X is between 1 and 6. The largest heading is <h1>...</h1>. Also wrap sections into <section>...</section>.

As HTML is a markup language, each piece of text should be enclosed in some tags. Typically in a scientific document most of the text are paragraphs, and they are denoted by <p>...</p>. For example

<h1>Main title</h1>

<h2>Section title</h2>
<p>Paragraph 1</p>
<p>Paragraph 2</p>
<p>
  Paragraph 3
</p>

Just like in LaTeX, HTML will ignore most whitespace, so in the above example all three paragraphs will be typeset in the same way.

To add equations, there's two ways. Inline mathematics can be enclosed in $...$ or \(...\), and for displayed mathematics use $$...$$ or \[...\]. MathJax will handle them, and most of the common LaTeX syntax will work without any need to configure extras. For example, two inline equations followed by a displayed (full-line) equation:

And because $\sqrt{2} \geq x$, we have $x^2 \leq 2$. This implies that
\[
  \int_0^x tdt \leq 1.
\]

WARNING: since HTML uses < and > for tags, it is best to use \lt and \gt instead of them in equations to avoid problems.

Note: other LaTeX equation environments can be used also. For example \begin{equation}1+2=3\end{equation} or even multiline equations:

\begin{align}
f(x) &= 1+x+x^2+\cdots+x^n \notag\\
     &= (1-x^{n+1})/(1-x)
\end{align}

What we have so far is enough for typesetting very short, a few paragraphs long, texts. For longer texts, you probably need to use lemmas, theorems and proofs. This project offers a set of environments for that purpose. For example to write a theorem and its proof, write

<div class="theorem" title="Fermat's last theorem">
<p>
  There are no $a,b,c\in\N$ and $n\in\N$ greater than $2$ such
  that $a^n+b^n=c^n$.
</p>
</div>
<div class="proof">
<p>
  Unfortunately the code-block in this readme is too short for
  a complete proof.
</p>
</div>

As you see, these environments are of the form <div class="XXXX">...</div>, with optional parameters like title. Here's the complete list of classes that are supported currently:

  • class="theorem"
  • class="lemma"
  • class="corollary"
  • class="proposition"
  • class="conjecture"
  • class="definition"
  • class="remark"
  • class="motivation"
  • class="proof"

And each of them will display the title attribute in parenthesis. For example <div class="definition" title="Fourier transform">...</div> will produce the text "Definition (Fourier transform). ..." The proof-environment will produce a black end-of-proof square at the end of the environment. Currently these environments are all numbered using the same counter.

For refering to equations and results: MathJax will automatically number all display-mode equations, unless asked not to. For a numbered equation, use \begin{equation}...\end{equation}. For unnumbered ones, use $$...$$, \[...\] or the starred version, like in LaTeX, \begin{equation*}...\end{equation*}. Then just add a \label{...} and refer to it with an \eqref{...} or a \ref{...}. For example

\begin{equation}
\label{CS}
\lvert A \cdot B \rvert \leq \lvert A \rvert \lvert B \rvert
\end{equation}
According to the Cauchy-Schwartz inequality \eqref{CS} we have...

Refering to results in the same document: This is still subject to change. Currently (commit 691fdd22de) you should add an id="..." attribute to the <div class="XYZ"> and then use a HTML link. For example

<div class="remark" id="rem1">
<p>
  What was done in the previous section has long 
  historical roots. Moreover........
</p>
</div>
<p>
  According to <a href="#rem1"></a> the following should
  have been well-known...
</p>

In this case the link will produce a clickable text "Remark X" (if X is the number assigned to the div above). So there is no need to worry about numbering or even about the type of the div (so no more "now was it a lemma or proposition again...?").

For refering to other documents, there is currently no specific mechanism. For online references one should just write it down as an HTML link. Then the JavaScript will add a reference number [X] behind it and list it in the online sources section in the footer. For example

By <a href="https://en.wikipedia.org/wiki/Hermite_polynomials">
Hermite polynomial basics</a> we see that...

However all of this reference hangling might change later depending on user feedback.

Various classes and their behavious

  • addTxtForbidden should prevent scripts from adding any text to that element
  • referenceNbr styles the [x] in citations and reference list

How to?

  • Refer to a theorem: By <a href="#finalThm">Theorem</a> we have... will produce "By Theorem 4 we have..." if its number is 4.
  • Refer to a MathJax equation: just like in TeX By \eqref{eq1} ... will produce "By (29) ..." if it is equation number 29.
  • Cite an offline source: give an element the class reference and an id, for example BPS14. Then ... was shown in <a href="#BPS">Section 2</a>. will produce "... was shown in [1, Section 2]." If the <a>-tag had empty interior, then it would produce only "[1]".
  • Cite an online source: According to <a href="https://gnu.org/licenses/license-list.html#GNUGPL">the license</a> ... will produce "According to the license [4, #GNUGPL] ..." if 4 was the number assigned to that reference.
  • Number a theorem: give the theorem's <div> the attribute data-nbr="XXX" where XXX is the number you want. Also works for lemmas, corollaries, propositions, conjectures, definitions, remarks and motivations.
  • Automatically number a theorem: set the theorem <div>'s data-counters-attribute to either 1, 2 or 3 depending on the depth of the numbering you want. Note it is recommended to use and number <section>'s if you chose the value 2 or 3. For example a theorem inside a section would have data-counters="2" while the section itself has data-counters="1". Currently the sections will not display their number.

#focusHere??

The id="focusHere" is a tool that might be useful when composing long documents.

If a document has many formulas, MathJax will not know a-priori how long the document will be. So if you have scrolled to a specific spot in the document, make a small change in the HTML, and then reload, you will end up looking at a completely different spot. Now, if you add id="focusHere" to an HTML-element, your browser will scroll to that location after MathJax has finished typesetting. This will also add a lightsalmon coloured dot to the left margin to remind you to remove the id when ready to move on.

License

The JavaScript files are licenced with the GNU Affero General Public License version 3, or any later version published by the Free Software Foundation, at your choice.

The example html files are licenced with the GNU Free Documentation License version 1.3, or at your option any later version published by the Free Software Foundation.

The Latin Modern font files have been downloaded from Font Squirrel (https://www.fontsquirrel.com/fonts/Latin-Modern-Roman). For their license see http://www.gust.org.pl/projects/e-foundry/licenses/GUST-FONT-LICENSE.txt/view . It is the LaTeX Project Public License with a non-binding request to change the names of the font files should you modify them.