for",
+ " ...",
+ # more
+)
+
+
+def get_abstract_latex_log(log):
+ # type: (Text) -> Text
+ '''abstract error msg from latex compilation log'''
+ msg = log.split(LATEX_ERR_LOG_BEGIN_LINE_STARTS)[1]\
+ .split(LATEX_ERR_LOG_END_LINE_STARTS)[0]
+
+ if LATEX_LOG_OMIT_LINE_STARTS:
+ msg = "\n".join(
+ line for line in msg.splitlines()
+ if (not line.startswith(LATEX_LOG_OMIT_LINE_STARTS)
+ and
+ line.strip() != ""))
+ return msg
+
+# }}}
+
+
+# {{{ strip comments from source
+
+def strip_comments(source):
+ # type: (Text) -> Text
+ # modified from https://gist.github.com/amerberg/a273ca1e579ab573b499
+ tokens = ( # noqa
+ 'PERCENT', 'BEGINCOMMENT', 'ENDCOMMENT',
+ 'BACKSLASH', 'CHAR', 'BEGINVERBATIM',
+ 'ENDVERBATIM', 'NEWLINE', 'ESCPCT',
+ 'MAKEATLETTER', 'MAKEATOTHER',
+ )
+ states = ( # noqa
+ ('makeatblock', 'exclusive'),
+ ('makeatlinecomment', 'exclusive'),
+ ('linecomment', 'exclusive'),
+ ('commentenv', 'exclusive'),
+ ('verbatim', 'exclusive')
+ )
+
+ # Deal with escaped backslashes, so we don't
+ # think they're escaping %
+ def t_BACKSLASH(t): # noqa
+ r"\\\\"
+ return t
+
+ # Leaving all % in makeatblock
+ def t_MAKEATLETTER(t): # noqa
+ r"\\makeatletter"
+ t.lexer.begin("makeatblock")
+ return t
+
+ # One-line comments
+ def t_PERCENT(t): # noqa
+ r"\%"
+ t.lexer.begin("linecomment")
+
+ # Escaped percent signs
+ def t_ESCPCT(t): # noqa
+ r"\\\%"
+ return t
+
+ # Comment environment, as defined by verbatim package
+ def t_BEGINCOMMENT(t): # noqa
+ r"\\begin\s*{\s*comment\s*}"
+ t.lexer.begin("commentenv")
+
+ #Verbatim environment (different treatment of comments within)
+ def t_BEGINVERBATIM(t): # noqa
+ r"\\begin\s*{\s*verbatim\s*}"
+ t.lexer.begin("verbatim")
+ return t
+
+ #Any other character in initial state we leave alone
+ def t_CHAR(t): # noqa
+ r"."
+ return t
+
+ def t_NEWLINE(t): # noqa
+ r"\n"
+ return t
+
+ # End comment environment
+ def t_commentenv_ENDCOMMENT(t): # noqa
+ r"\\end\s*{\s*comment\s*}"
+ #Anything after \end{comment} on a line is ignored!
+ t.lexer.begin('linecomment')
+
+ # Ignore comments of comment environment
+ def t_commentenv_CHAR(t): # noqa
+ r"."
+ pass
+
+ def t_commentenv_NEWLINE(t): # noqa
+ r"\n"
+ pass
+
+ #End of verbatim environment
+ def t_verbatim_ENDVERBATIM(t): # noqa
+ r"\\end\s*{\s*verbatim\s*}"
+ t.lexer.begin('INITIAL')
+ return t
+
+ #Leave contents of verbatim environment alone
+ def t_verbatim_CHAR(t): # noqa
+ r"."
+ return t
+
+ def t_verbatim_NEWLINE(t): # noqa
+ r"\n"
+ return t
+
+ #End a % comment when we get to a new line
+ def t_linecomment_ENDCOMMENT(t): # noqa
+ r"\n"
+ t.lexer.begin("INITIAL")
+
+ # Newline at the end of a line comment is presevered.
+ return t
+
+ #Ignore anything after a % on a line
+ def t_linecomment_CHAR(t): # noqa
+ r"."
+ pass
+
+ def t_makeatblock_MAKEATOTHER(t): # noqa
+ r"\\makeatother"
+ t.lexer.begin('INITIAL')
+ return t
+
+ def t_makeatblock_BACKSLASH(t): # noqa
+ r"\\\\"
+ return t
+
+ # Escaped percent signs in makeatblock
+ def t_makeatblock_ESCPCT(t): # noqa
+ r"\\\%"
+ return t
+
+ # presever % in makeatblock
+ def t_makeatblock_PERCENT(t): # noqa
+ r"\%"
+ t.lexer.begin("makeatlinecomment")
+ return t
+
+ def t_makeatlinecomment_NEWLINE(t): # noqa
+ r"\n"
+ t.lexer.begin('makeatblock')
+ return t
+
+ # Leave contents of makeatblock alone
+ def t_makeatblock_CHAR(t): # noqa
+ r"."
+ return t
+
+ def t_makeatblock_NEWLINE(t): # noqa
+ r"\n"
+ return t
+
+ # For bad characters, we just skip over it
+ def t_ANY_error(t): # noqa
+ t.lexer.skip(1)
+
+ lexer = ply.lex.lex()
+ lexer.input(source)
+ return u"".join([tok.value for tok in lexer])
+
+# }}}
+
+
+# {{{ remove redundant strings
+
+def strip_spaces(s, allow_single_empty_line=False):
+ # type: (Text, Optional[bool]) -> Text
+ """
+ strip spaces in s, so that the result will be
+ considered same although new empty lines or
+ extra spaces are added. Especially for generating
+ md5 of the string.
+ :param s: string. The source code
+ :param allow_single_empty_line: bool. If True,
+ single empty line will be preserved, this is need
+ for latex document body. If False, all empty line
+ will be removed.
+ :return: string.
+ """
+
+ # strip all lines
+ s = "\n".join([l.strip() for l in s.split("\n")])
+
+ if not allow_single_empty_line:
+ while "\n\n" in s:
+ s = s.replace('\n\n', '\n')
+ else:
+ while "\n\n\n" in s:
+ s = s.replace('\n\n\n', '\n\n')
+
+ # remove redundant white spaces and tabs
+ s = s.replace("\t", " ")
+ while " " in s:
+ s = s.replace(" ", " ")
+
+ return s
+
+# }}}
+
+
+def get_all_indirect_subclasses(cls):
+ # type: (Any) -> List[Any]
+ all_subcls = []
+
+ for subcls in cls.__subclasses__():
+ if not subcls.__subclasses__():
+ # has no child
+ all_subcls.append(subcls)
+ all_subcls.extend(get_all_indirect_subclasses(subcls))
+
+ return list(set(all_subcls))
+
+
+def replace_latex_space_seperator(s):
+ # type: (Text) -> Text
+ """
+ "{{", "}}", "{%", %}", "{#" and "#}" are used in jinja
+ template, so we have to put spaces between those
+ characters in latex source in the latex macro.
+ To compile the source, we are now removing the spaces.
+ """
+ pattern_list = [
+ r'{ {',
+ r'} }',
+ r'{ #',
+ r'# }',
+ r'{ %',
+ r'% }'
+ ]
+ for pattern in pattern_list:
+ while pattern in s:
+ s = s.replace(pattern, pattern.replace(" ", ""))
+
+ return s
+
+
+def get_mongo_db(database=None):
+ # type: (Optional[Text]) -> MongoClient
+ if not database:
+ database = getattr(
+ settings, "RELATE_MONGODB_NAME",
+ "relate-mongodb")
+ args = []
+ uri = getattr(settings, "RELATE_MONGO_URI", None)
+ if uri:
+ args.append(uri)
+ client = MongoClient(*args, connect=False)
+ db = client[database]
+ return db
+
+# vim: foldmethod=marker
diff --git a/doc/content.rst b/doc/content.rst
index 8c5ae9d27..b0af060e5 100644
--- a/doc/content.rst
+++ b/doc/content.rst
@@ -343,6 +343,8 @@ This could then be used from wherever RELATE markup is allowed::
to embed a YouTube player. (YouTube is a registered trademark.)
+.. include:: tex-macro.rst
+
.. _course_yml:
The Main Course Page File
diff --git a/doc/tex-macro.rst b/doc/tex-macro.rst
new file mode 100644
index 000000000..fe40d2695
--- /dev/null
+++ b/doc/tex-macro.rst
@@ -0,0 +1,226 @@
+.. _latex_to_img:
+
+Built-in LaTeX to image macro
+-----------------------------
+
+.. currentmodule:: course.latex
+
+Relate provides a built-in
+`Jinja `_ macro named
+``latex`` which automatically converts the wrapped LaTex code into a cached
+image, which is consequently rendered in a html page.
+For example:
+
+.. code-block:: jinja
+
+
+ {% call latex(compiler="pdflatex", image_format="png", alt="example") %}
+.. code-block:: latex
+
+ \documentclass{article}
+ \usepackage[utf8]{inputenc}
+ \usepackage[table]{xcolor}
+ \setlength{\arrayrulewidth}{1mm}
+ \setlength{\tabcolsep}{18pt}
+ \renewcommand{\arraystretch}{2.5}
+ \newcolumntype{s}{>{\columncolor[HTML]{AAACED} } p{3cm} }
+ \arrayrulecolor[HTML]{DB5800}
+ \begin{document}
+ \begin{tabular}{ |s|p{3cm}|p{3cm}| }
+ \hline
+ \rowcolor{lightgray} \multicolumn{3}{|c|}{Country List} \\
+ \hline
+ Country Name or Area Name& ISO ALPHA 2 Code &ISO ALPHA 3 \\
+ \hline
+ Afghanistan & AF &AFG \\
+ \rowcolor{gray}
+ Aland Islands & AX & ALA \\
+ Albania &AL & ALB \\
+ Algeria &DZ & DZA \\
+ American Samoa & AS & ASM \\
+ Andorra & AD & \cellcolor[HTML]{AA0044} AND \\
+ Angola & AO & AGO \\
+ \hline
+ \end{tabular}
+
+ \end{document}
+
+.. code-block:: jinja
+
+ {% endcall %}
+
+
+The above markup creates a horizontally centered image of a colored
+LaTex table::
+
+
+ 
+
+
+Prerequisites
+^^^^^^^^^^^^^
+* **TexLive**
+ - For installation of TexLive.
+ See `Instructions on TUG `_.
+ - For Linux platform
+ - Vanilla TexLive is preferable if you want to use latest version
+ of TexLive and not to bother upgrading packages.
+ - If you don't mind use outdated version of TexLive, you can also
+ install the version comes with Linux distributed by::
+
+ sudo apt-get install texlive-full
+
+* **latexmk**, required, shipped with TexLive full installation,
+ version >= 4.39 is required.
+* **dvisvgm**, optional, shipped with TexLive full installation.
+* **dvipng**, required, shipped with TexLive full installation.
+* **ImageMagick**, required.
+ - For Windows platform, install with option
+ ``install legacy component`` ticked.
+* **MongoDB**, required.
+
+Configurations
+^^^^^^^^^^^^^^
+In your :file:`local_settings.py`:
+
+* Enable latex to image functionality by configuring
+ "RELATE_LATEX_TO_IMAGE_ENABLED = True".
+* Configure "RELATE_LATEX_BIN_PATH" option to
+ the bin path of the TexLive installation. For example,
+ "/usr/local/texlive/2015/bin/x86_64-linux". That is also
+ where ``latexmk``, ``dvisvgm`` and ``dvipng`` should be
+ found.
+* Configure ImageMagick bin path "RELATE_IMAGEMAGICK_BIN_DIR" to
+ the absolute path of the location of the bin ``convert``
+ (``convert.exe`` for Windows) of your ImageMagick installation.
+ This is required for Windows since Windows itself has another
+ cmd named ``convert``.
+* Configure "IMAGE_CACHE_MAX_BYTES" option to set the max cache
+ bytes for generated images. Note that the value should be
+ larger than most images converted, or else those images won't be
+ cached and will resulting in more disk reading.
+
+Usage
+^^^^^
+
+Generally, it can be done by simply wrapping the source code
+of a full latex document by the ``latex`` caller:
+
+.. code-block:: jinja
+
+ {% call latex(compiler="pdflatex", image_format="png") %}
+ The latex source code
+ {% endcall %}
+
+By *full document* we mean it must contain ``\documentclass``,
+``\begin{document}`` and ``end{document}``.
+
+* Required params:
+ **compiler**
+ str, the command line used to compile the tex
+ file, currently available: ``xelatex``, ``pdflatex``, ``latex``
+ and ``lualatex``.
+ **image_format**
+ str, the output format of the image, only
+ ``png`` and ``svg`` are available.
+
+ .. note::
+ * Output with ``svg`` format only support ``latex`` as compiler.
+ If ``compiler="latex"``.
+ * If the code contains figure generated by ``tikz/pgf`` , the
+ image_format will be forced using ``svg``.
+ * ``svg`` images generated are always huge in size, sometimes 10
+ times of that of the png images. It consume more caches and slow
+ down the rendering of pages on browsers.
+
+* Optional params:
+ **tex_filename**
+ A string, the based filename of the latex, and image
+ as well, if not set, use md5 of the full latex code.
+ **tex_preamble**
+ A string, which allows user move the preamble part of
+ the latex code out of the ``latex`` macro. For example, we can use
+ ``{% set foo %}{% endset %}`` block to define ``foo`` as the preamble
+ and then use ``tex_premable=foo`` as an argument of the ``latex``
+ caller. Those definitions can also be saved as macros in the course
+ repo. That is a good practice for latex code with common preambles.
+ However, this should be used with cautiousness, as changing of the
+ preamble definition will force all the originally valid images,
+ whose preambles have been changed, to be recompiled, which might
+ result in failure (same for ``tex_preamble_extra``). For latex code
+ that might be changed in the future, the best practice is to keep
+ full latex document in the page markup.
+ **tex_preamble_extra**
+ A string, more packages or settings appended to
+ ``tex_preamble``.
+
+ Using ``tex_preamble``, the above example can be changed to the following
+ which generate exactly the same output.
+
+ .. code-block:: jinja
+
+ {% set preamble %}
+ \documentclass{article}
+ \usepackage[utf8]{inputenc}
+ \usepackage[table]{xcolor}
+ \setlength{\arrayrulewidth}{1mm}
+ \setlength{\tabcolsep}{18pt}
+ \renewcommand{\arraystretch}{2.5}
+ \newcolumntype{s}{>{\columncolor[HTML]{AAACED} } p{3cm} }
+ \arrayrulecolor[HTML]{DB5800}
+ {% endset %}
+
+
+ {% call latex(compiler="pdflatex", image_format="png",
+ tex_preamble=preamble, alt="example") %}
+ .. code-block:: latex
+
+ \begin{document}
+ \begin{tabular}{ |s|p{3cm}|p{3cm}| }
+ \hline
+ \rowcolor{lightgray} \multicolumn{3}{|c|}{Country List} \\
+ \hline
+ Country Name or Area Name& ISO ALPHA 2 Code &ISO ALPHA 3 \\
+ \hline
+ Afghanistan & AF &AFG \\
+ \rowcolor{gray}
+ Aland Islands & AX & ALA \\
+ Albania &AL & ALB \\
+ Algeria &DZ & DZA \\
+ American Samoa & AS & ASM \\
+ Andorra & AD & \cellcolor[HTML]{AA0044} AND \\
+ Angola & AO & AGO \\
+ \hline
+ \end{tabular}
+ \end{document}
+ .. code-block:: jinja
+
+ {% endcall %}
+
+
+ **force_regenerate**
+ A boolean, if True, regenerate the image no matter
+ it exists or not. Default to ``False``.
+ **html_class_extra**
+ A string, extra html class for the ``![]()
`` tag,
+ besides ``img-responsive``.
+ **alt**
+ A string, a brief description of the image, Default to the
+ document part of the tex source.
+ **empty_pagestyle**
+ A boolean, if ``True``, ``\pagestyle{empty}`` will
+ be added to existing preamble and a standalone image will be
+ generated. Default to ``True``.
+
+.. note::
+
+ ``{{``, ``}}``, ``{%``, ``%}``, ``{#`` and ``#}`` are used as marking
+ strings in jinja template, latex code submitted (including preabmle
+ part and self-defined commands) should avoid containing those strings,
+ or else jinja will just fail to render. The work around is to manually
+ insert a space (spaces or tabs) between the two character (e.g.,
+ ``{{`` --> ``{ {``) for each of those strings appeared in latex code.
+
+A more sophisticated example can be found at
+`relate-example `_.
\ No newline at end of file
diff --git a/local_settings.example.py b/local_settings.example.py
index 43a1756cb..14607617f 100644
--- a/local_settings.example.py
+++ b/local_settings.example.py
@@ -11,6 +11,9 @@
# Configure the following as url as above.
RELATE_BASE_URL = "http://YOUR/RELATE/SITE/DOMAIN"
+RELATE_LATEX_TO_IMAGE_ENABLED = True
+RELATE_LATEX_BIN_DIR = \
+ "/usr/local/texlive/2015/bin/x86_64-linux"
# Uncomment this to use a real database. If left commented out, a local SQLite3
# database will be used, which is not recommended for production use.
#
@@ -226,6 +229,37 @@
# }}}
+
+# {{{ convert LaTeX to image settings
+
+# The MongoDB database name for RELATE
+RELATE_MONGODB_NAME = "my_relate-mongodb"
+
+# The collection name in RELATE_MONGODB_NAME where the datauris are stored
+RELATE_LATEX_DATAURI_MONGO_COLLECTION_NAME = "my_relate_latex_datauri"
+
+# The collection name in RELATE_MONGODB_NAME where the compile error are stored
+RELATE_LATEX_ERROR_MONGO_COLLECTION_NAME = "my_relate_latex_error"
+
+# To enable tex2img functionality, uncomment the following line.
+#RELATE_LATEX_TO_IMAGE_ENABLED = True
+
+# The bin dir of tex compiler and image converter should be
+# correctly configured or RELATE will failed to start.
+#RELATE_LATEX_BIN_PATH = "/usr/local/texlive/2015/bin/x86_64-linux"
+#RELATE_IMAGEMAGICK_BIN_DIR = "/path/to/imagemagic/convert/bin/"
+
+# configure the following only if dvisvgm or dvipng can't be found
+# in sys evn..
+#RELATE_DVISVGM_BIN_DIR = "/path/to/dvisvgm/bin/"
+#RELATE_DVIPNG_BIN_DIR = "/path/to/dvipng/bin/"
+
+# image, especially svg have large file size, files with size
+# exceed the following won't be cached.
+RELATE_IMAGE_CACHE_MAX_BYTES = 65536
+
+# }}}
+
# {{{ docker
# A string containing the image ID of the docker image to be used to run
diff --git a/requirements.txt b/requirements.txt
index abd6f2daa..8996fdfda 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -109,4 +109,9 @@ pytools
# For mypy (static type checking) support
typing
+# For mongodb
+pymongo
+
+# For string parse
+ply
# vim: foldmethod=marker