From d0982bc55ceebe6e2caf730d345173ba4913322f Mon Sep 17 00:00:00 2001
From: "J.-S. Caux" <J.S.Caux@uva.nl>
Date: Thu, 20 Jun 2019 07:48:48 +0200
Subject: [PATCH] Improve markup help pages
---
markup/constants.py | 73 +++++++++++++++++--
markup/templates/markup/help.html | 81 ++++++++++++++++++---
markup/templates/markup/markdown_help.html | 18 ++---
markup/templates/markup/plaintext_help.html | 43 ++++++-----
markup/views.py | 12 ++-
5 files changed, 181 insertions(+), 46 deletions(-)
diff --git a/markup/constants.py b/markup/constants.py
index f0d6e2b1a..a6fbbeb90 100644
--- a/markup/constants.py
+++ b/markup/constants.py
@@ -46,9 +46,28 @@ BLEACH_ALLOWED_TAGS = [
]
+PlainTextSuggestedFormatting = (
+ {
+ 'id': 'authorreply',
+ 'title': 'Author Reply to Report',
+ 'raw':
+r"""
+The referee writes:
+"The authors should extend their exact solution to the two-dimensional case."
-PlainTextSnippets = {
- 'maths_inline_online':
+Our response:
+Even Bethe did not manage this: see the unfulfilled promise at the end
+of his 1931 paper https://doi.org/10.1007/BF01341708.
+"""
+ },
+)
+
+
+PlainTextSnippets = (
+ {
+ 'id': 'maths',
+ 'title': 'Maths: inline and displayed',
+ 'raw':
r"""Some say $e^{i\pi} + 1 = 0$ is the most beautiful equation of all.
Do you know this famous Hamiltonian?
@@ -61,10 +80,14 @@ $$
H = \int dx \left[ \partial_x \Psi^\dagger \partial_x \Psi
+ c \Psi^\dagger \Psi^\dagger \Psi \Psi \right]
$$
-""",
-
- 'maths_multiple_lines':
"""
+ },
+
+ {
+ 'id': 'maths_multiple_lines',
+ 'title': 'Maths: multiple lines',
+ 'raw':
+r"""
Equations on multiple lines:
\[
\nabla \cdot {\boldsymbol E} = \frac{\rho}{\epsilon_0}, \qquad
@@ -84,7 +107,26 @@ Equations on multiple lines:
\end{eqnarray*}
\]
"""
-}
+ }
+)
+
+
+MarkdownSuggestedFormatting = (
+ {
+ 'id': 'authorreply',
+ 'title': 'Author Reply to Report',
+ 'raw':
+r"""
+**The referee writes:**
+> The authors should extend their exact solution to the two-dimensional case.
+
+**Our response:**
+
+Even Bethe did not manage this: see the unfulfilled promise at the end
+of his [1931 paper](https://doi.org/10.1007/BF01341708).
+"""
+ },
+)
MarkdownSnippets = (
@@ -520,3 +562,22 @@ Multiline equations can be obtained by using the ``\\`` carriage return as usual
"""},
)
+
+
+ReSTSuggestedFormatting = (
+ {
+ 'id': 'authorreply',
+ 'title': 'Author Reply to Report',
+ 'raw':
+r"""
+**The referee writes:**
+
+ The authors should extend their exact solution to the two-dimensional case.
+
+**Our response:**
+
+Even Bethe did not manage this: see the unfulfilled promise at the end
+of his `1931 paper <https://doi.org/10.1007/BF01341708>`_ .
+"""
+ },
+)
diff --git a/markup/templates/markup/help.html b/markup/templates/markup/help.html
index a2bc522b3..d5656db56 100644
--- a/markup/templates/markup/help.html
+++ b/markup/templates/markup/help.html
@@ -7,6 +7,8 @@
<span class="breadcrumb-item">Help</span>
{% endblock %}
+{% load automarkup %}
+
{% block content %}
<div class="row">
@@ -36,7 +38,10 @@
To help you decide, here is a quick summary of main points to bear in mind:
<table class="table table-bordered">
<tr>
- <th>Option</th><th>Advantages</th><th>Disadvantages</th>
+ <th>Option</th>
+ <th>Advantages</th>
+ <th>Disadvantages</th>
+ <th>Recommended for</th>
</tr>
<tr>
<td>Plain text</td>
@@ -50,24 +55,32 @@
<li>No markup!</li>
</ul>
</td>
+ <td>
+ Anybody not wanting to bother with markup
+ </td>
</tr>
<tr>
<td>Markdown</td>
<td>
<ul>
<li>ease of use</li>
+ <li>purposefully simple</li>
<li>
provides more or less all the markup you'll ever need,
- at least for small snippets
+ at least for small, simple snippets
</li>
</ul>
</td>
<td>
<ul>
<li>non-standardized: many dozen "dialects" exist</li>
+ <li>facilities for some simple things (<em>e.g.</em> tables) are missing</li>
<li>not really meant for large, complex documents</li>
</ul>
</td>
+ <td>
+ Everybody wishing for or requiring markup
+ </td>
</tr>
<tr>
<td>reStructuredText</td>
@@ -87,24 +100,70 @@
</td>
<td>
<ul>
- <li>support for maths is good, but remains less extensive than in LaTeX</li>
+ <li>support for maths is good, but remains less extensive than in LaTeX,
+ and requires annoying indentation in multiline directives</li>
</ul>
</td>
+ <td>
+ Pythonistas and Sphinx aficionados
+ </td>
</tr>
</table>
</p>
<p>
- Which option you choose is completely up to you. Our system will determine
- which one you are using and render your input accordingly.
+ Which option you choose is completely up to you. Our system will automatically
+ determine which one you are using and render your input accordingly.
</p>
- <h3 class="highlight" id="Plain">Plain text</h3>
- <p>See our <a href="{% url 'markup:plaintext_help' %}">plain text-specific</a> help page</p>
- <h3 class="highlight" id="Markdown">Markdown</h3>
- <p>See our <a href="{% url 'markup:markdown_help' %}">Markdown-specific</a> help page</p>
- <h3 class="highlight" id="reStructuredText">reStructuredText</h3>
- <p>See our <a href="{% url 'markup:restructuredtext_help' %}">reStructuredText-specific</a> help page</p>
+ <br>
+
+ <h2 class="highlight" id="Plain">Plain text 
+ <em><small><i class="fa fa-arrow-right"></i> See our <a href="{% url 'markup:plaintext_help' %}">plain text-specific</a> help page</small></em>
+ </h2>
+ {% for suggestion in PlainTextSuggestions %}
+ <h4 id="{{ suggestion.id }}">Example: {{ suggestion.title }}</h4>
+ <div class="row">
+ <div class="col-6">
+ <pre>{{ suggestion.raw }}</pre>
+ </div>
+ <div class="col-6">
+ {{ suggestion.raw|automarkup }}
+ </div>
+ </div>
+ {% endfor %}
+
+ <br>
+
+ <h2 class="highlight" id="Markdown">Markdown 
+ <em><small><i class="fa fa-arrow-right"></i> See our <a href="{% url 'markup:markdown_help' %}">Markdown-specific</a> help page</small></em></h2>
+ {% for suggestion in MarkdownSuggestions %}
+ <h4 id="{{ suggestion.id }}">Example: {{ suggestion.title }}</h4>
+ <div class="row">
+ <div class="col-6">
+ <pre>{{ suggestion.raw }}</pre>
+ </div>
+ <div class="col-6">
+ {{ suggestion.raw|automarkup }}
+ </div>
+ </div>
+ {% endfor %}
+
+ <br>
+
+ <h2 class="highlight" id="reStructuredText">reStructuredText 
+ <em><small><i class="fa fa-arrow-right"></i> See our <a href="{% url 'markup:restructuredtext_help' %}">reStructuredText-specific</a> help page</small></em></h2>
+ {% for suggestion in ReSTSuggestions %}
+ <h4 id="{{ suggestion.id }}">Example: {{ suggestion.title }}</h4>
+ <div class="row">
+ <div class="col-6">
+ <pre>{{ suggestion.raw }}</pre>
+ </div>
+ <div class="col-6">
+ {{ suggestion.raw|automarkup }}
+ </div>
+ </div>
+ {% endfor %}
</div>
</div>
diff --git a/markup/templates/markup/markdown_help.html b/markup/templates/markup/markdown_help.html
index 2f3e9bc63..a5211f716 100644
--- a/markup/templates/markup/markdown_help.html
+++ b/markup/templates/markup/markdown_help.html
@@ -28,16 +28,16 @@
{% for snippet in snippets %}
<h3 class="highlight" id="{{ snippet.id }}">{{ snippet.title }}</h3>
- <div class="row">
- <div class="col-6">
- <h3><strong>If you write:</strong></h3>
- <pre>{{ snippet.raw }}</pre>
+ <div class="row">
+ <div class="col-6">
+ <h3><strong>If you write:</strong></h3>
+ <pre>{{ snippet.raw }}</pre>
+ </div>
+ <div class="col-6">
+ <h3><strong>You will get:</strong></h3>
+ {{ snippet.raw|automarkup:'Markdown' }}
+ </div>
</div>
- <div class="col-6">
- <h3><strong>You will get:</strong></h3>
- {{ snippet.raw|automarkup:'Markdown' }}
- </div>
- </div>
{% endfor %}
</div>
diff --git a/markup/templates/markup/plaintext_help.html b/markup/templates/markup/plaintext_help.html
index 9282ee990..b18ae6f58 100644
--- a/markup/templates/markup/plaintext_help.html
+++ b/markup/templates/markup/plaintext_help.html
@@ -15,27 +15,34 @@
<div class="row">
<div class="col-12">
<h2 class="highlight">Plain text help</h2>
-
- <h3 class="highlight" id="Mathematics">Mathematics</h3>
-
- <p>
- You can delimit inline maths using dollar signs like this: <code>$ ... $</code>.
- </p>
<p>
- For on-line maths, use escaped angular brackets
- <code>\[ ... \]</code> or
- double-dollar delimiters <code>$$ ... $$</code>.
+ Plain text is the most straightforward format to use in our text fields,
+ but this comes at the cost of having no markup facilities.
+
+ Mathematics (both online and displayed) are enabled via MathJax.
+ You will find some simple examples below.
</p>
- <div class="row">
- <div class="col-6">
- <h4><strong>If you write:</strong></h4>
- <pre>{{ snippets.maths_inline_online }}</pre>
- </div>
- <div class="col-6">
- <h4><strong>You will get:</strong></h4>
- {{ snippets.maths_inline_online|automarkup:'plain' }}
+ <h3>Quick links</h3>
+ <ul>
+ {% for snippet in snippets %}
+ <li><a href="#{{ snippet.id }}">{{ snippet.title }}</a></li>
+ {% endfor %}
+ </ul>
+
+ {% for snippet in snippets %}
+ <h3 class="highlight" id="{{ snippet.id }}">{{ snippet.title }}</h3>
+ <div class="row">
+ <div class="col-6">
+ <h3><strong>If you write:</strong></h3>
+ <pre>{{ snippet.raw }}</pre>
+ </div>
+ <div class="col-6">
+ <h3><strong>You will get:</strong></h3>
+ {{ snippet.raw|automarkup:'Markdown' }}
+ </div>
</div>
- </div>
+ {% endfor %}
+
</div>
</div>
diff --git a/markup/views.py b/markup/views.py
index b6f1f5d67..8fb854523 100644
--- a/markup/views.py
+++ b/markup/views.py
@@ -6,7 +6,9 @@ from django.contrib.auth.decorators import login_required
from django.http import JsonResponse
from django.shortcuts import render
-from .constants import PlainTextSnippets, MarkdownSnippets, ReStructuredTextSnippets
+from .constants import (PlainTextSuggestedFormatting, PlainTextSnippets,
+ MarkdownSuggestedFormatting, MarkdownSnippets,
+ ReSTSuggestedFormatting, ReStructuredTextSnippets)
from .forms import MarkupTextForm
@@ -31,7 +33,12 @@ def markup_help(request):
"""
General help page about markup facilities at SciPost.
"""
- return render(request, 'markup/help.html')
+ context = {
+ 'PlainTextSuggestions': PlainTextSuggestedFormatting,
+ 'MarkdownSuggestions': MarkdownSuggestedFormatting,
+ 'ReSTSuggestions': ReSTSuggestedFormatting,
+ }
+ return render(request, 'markup/help.html', context)
def plaintext_help(request):
@@ -48,6 +55,7 @@ def markdown_help(request):
Help page for Markdown.
"""
context = {
+ 'suggestions': MarkdownSuggestedFormatting,
'snippets': MarkdownSnippets,
}
return render(request, 'markup/markdown_help.html', context)
--
GitLab