| Name | flm-core JSON |
| Version |
0.3.0a12
JSON |
| download |
| home_page | |
| Summary | Flexible Latex-like Markup |
| upload_time | 2023-08-30 07:33:52 |
| maintainer | |
| docs_url | None |
| author | Philippe Faist |
| requires_python | >=3.8,<4.0 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# A Flexible Latex-Like Markup (FLM) language
This package provides a simple parser and formatter for a custom markup language
that is inspired by LaTeX syntax.
The syntax of FLM is essentially a subset of standard LaTeX commands, including
macros, environments, and some characters that have a special meaning; these
features are parsed in a loosely similar fashion to usual LaTeX code.
The framework is meant to be very easily extendible and customizable. The
parser is based on the upcoming version 3 of
[*pylatexenc*](https://github.com/phfaist/pylatexenc)
(currently in pre-release on pypi).
FLM is used to write the contents of the [Error Correction
Zoo](https://errorcorrectionzoo.org/) in a way that is intuitive for scientists,
flexible, and robust. It is easily extensible and closely resembles the LaTeX
langauge that many scientists are familiar with. FLM pushes further one of the
core insights of LaTeX, namely, that the code should *describe* document
contents in an intuitive way, as a markup language, while disregarding as much
as possible the details of how that contents will be typeset. The final
typesetting is fully customizable, e.g., through CSS styling of its HTML output
(including the use of templates).
I intended to call this project "LLM" as an acronym for Latex-Like Markup, but
had to revise my choice after the astronomical growth of large language models.
You can install FLM with pip:
```bash
$ pip install flm-core
```
Example `mydocument.flm`:
```latex
---
title: Kitaev's Surface Code
---
\section{Kitaev's Surface Code}
The \emph{stabilizers} of the \textit{surface code} on the 2-dimensional
torus are generated by star operators \(A_v\) and plaquette operators
\(B_p\). Each star operator is a \textbf{product} of four Pauli-\(X\)
operators on the edges adjacent to a vertex \(v\) of the lattice; each
plaquette operator is a product of four Pauli-\(Z\) operators applied to
the edges adjacent to a face, or plaquette, \(p\) of the lattice
(\ref{figure:toric-code-operators}).
\begin{figure}
\includegraphics{toric-code-operators}
\caption{Stabilizer generators and logical operators of the 2D surface
code on a torus. The star operators \(A_v\) and the plaquette
operators \(B_p\) generate the stabilizer group of the toric code.
The logical operators are strings that wrap around the torus.}
\label{figure:toric-code-operators}
\end{figure}
...
```
To compile your document into an HTML page, use:
```bash
$ flm mydocument.flm -o mydocument.html --format=html --template=simple
```
You can then open the `mydocument.html` file in your browser.
# This is work in progress!
This project is still early in an active development stage, and there might
still be a few bugs around. You can expect the API to still change pretty
drastically. Feel free to share ideas!
# Use as a command-line tool
You can use `flm` in command-line mode to compile your documents:
```bash
$ flm mydocument.flm
```
Run `flm --help` to get a list of options. They should be fairly
standard and/or self-explanatory:
```bash
# output to file mydocument.html, format HTML, including skeleton
# HTML structure with minimal CSS.
$ flm mydocument.flm -o mydocument.html --format=html --template=simple
```
Available formats are `html`, `text`, `latex`, and `markdown`. Formats
`text`, `markdown`, and `latex` are very experimental! (You can also
generate `pdf` output with the options `--workflow=runlatexpdf --format=pdf`
if your system has a standard LaTeX distribution such as TeXLive installed)
- **Additional HTML Templates:**
The `--template=` option can be used to change the template used to render the
document. See also the
[*flm-templates*](https://github.com/phfaist/flm-templates) extension package
for some additional templates and template engines. You can try:
```
> pip install flm-templates flm-htmlplus
```
and then
```
> flm mydocument.flm -o output.html -w flm_htmlplus -P 'pkg:flm_templates' -t sunset
```
Or try the template `-t oldtextbook`.
- **Citations from arXiv & DOI:**
Automatically fetch citations from the arXiv, DOI x-references, or other
sources using the [*flm-citations*](https://github.com/phfaist/flm-citations)
extension package (see README file there). Install the extension package
using pip:
```
> pip install flm-citations
```
And then try to compile, e.g., the following FLM document:
```yaml
---
$import:
- pkg:flm_citations
---
\section{Introduction}
Let's cite Kitaev's surface code~\cite{doi:10.1070/RM1997v052n06ABEH002155,doi:10.1007/978-1-4615-5923-8_19,arXiv:quant-ph/9707021}. ...
```
- **Theorems and proofs:** Use the environments
``\begin{theorem}..\end{theorem}``, ``{lemma}``, ``{proposition}``,
``{definition}``, ``{remark}``, etc. for typesetting theorems. You can pin
labels to theorem statements ``\label{thm:XYZ}`` (use the `thm:` or `x:`
prefixes regardless of the theorem type, so you can easily change it without
having to update the label). These environments accept an optional argument
so you can specify a title, e.g. ``\begin{theorem}[Euler's theorem]
... \end{theorem}``. Typeset proofs with ``\begin{proof} ... \end{proof}``.
The proof's optional argument enjoys an additional syntax: use
``\begin{proof}[*thm:XYZ] ...`` to typeset `Proof (Theorem 3)` (with the
correct theorem reference using its label, which must match the one specified
to the theorem's ``\label`` command). Use ``\begin{proof}[**thm:XYZ] ...`` to
simply typeset `Proof` as usual, but in this way you have the information about
which theorem the proof is directly at hand; if you later move it around there
is no ambiguity as to which theorem the proof is associated with. It is also
the same syntax as supported by the [phfthm latex
package](https://github.com/phfaist/phfqitltx) which is able to produce
hyperlinks between theorems and their proofs.
## Document Front Matter
FLM Documents can contain YAML front matter that specify (i) options for the FLM
parser, (ii) which features to enable, and (iii) additional document metadata such
as a title.
```yaml
---
title: 'My FLM document'
flm:
parsing:
dollar_inline_math_mode: True
features:
endnotes:
categories:
- category_name: footnote
counter_formatter: unicodesuperscript
heading_title: 'Footnotes'
endnote_command: 'footnote'
---
\section{Greeting}
Hello, \emph{world}. Inline math can now also be typeset
as $a$ and $b$. ...
```
### Imports
You can use the `$import:` directive to import a configuration from an
external file, URL, or extension package:
```yaml
$import:
- my-flm-config.yaml # merge my-flm-config.yaml into this config.
# you can still specify configuration to merge with here ...
...
flm:
...
```
The `$import:` target can specify multiple configurations to import. Each list
item can be a absolute or relative file path (`$import: 'my-flm-config.yaml'` or
`$import: /path/to/my/flm-config.yaml`), a URL (`$import:
https://example.com/my/flm-config.yaml`), or a fully qualified python package
name introduced with ``pkg:package_name`` (e.g., `$import: pkg:flm_citations`).
If a package name is specified to the `$import` directive, the package is loaded
and the default FLM configuration is extracted from it and included (the
`flm_default_import_config` attribute of the module is read; it is assumed to be
a dictionary or a callable that returns a dictionary). You can optionally
follow the package name by a path to specify submodules/attributes to read
instead of `flm_default_import_config`; e.g., ``pkg:mypackage/foo/bar`` will
import the module `mypackage` and import the configuration dictionary stored in
``mypackage.foo.bar``. FLM extention plugin/package authors can use this
feature to offer preset customization configurations that can easily be included
with ``pkg:some_flm_extension_package/some/preset/name``.
### Parser configuration
Here's a basic parser configuration that you can adapt:
```yaml
flm:
parsing:
# Enable/Disable comments as in LaTeX, led by ‘%%’
enable_comments: true
# This string initiates a comment up to the end of
# the line, if comments are enabled. By default we
# require TWO '%' signs to avoid accidental comments
# (e.g., "... is up 10% from ...")
comment_start: '%%'
# Enable/Disable math mode with $ signs as in LaTeX
# in addition to \( ...\)
dollar_inline_math_mode: false
# Force parsing of the content in block-level mode
# (paragraphs). Here ‘null’ means to auto-detect
force_block_level: null
```
### Renderer configuration (`html`, `text`, `latex`, `markdown`)
Here's a basic renderer configuration that you can adapt **for HTML output**
(`--format=html`):
```yaml
flm:
renderer:
html:
use_link_target_blank: false
html_blocks_joiner: ''
# use ‘headings_tags_by_level: null’ for defaults
heading_tags_by_level:
1: h1
2: h2
3: h3
4: span
5: span
6: span
inline_heading_add_space: true
```
Here's a basic renderer configuration that you can adapt **for text output**
(`--format=text`):
```yaml
flm:
renderer:
text:
display_href_urls: true
```
Here's a basic renderer configuration that you can adapt **for LaTeX output**
(`--format=latex`):
```yaml
flm:
renderer:
latex:
heading_commands_by_level:
1: "section"
2: "subsection"
3: "subsubsection"
4: "paragraph"
5: "subparagraph"
6: null
```
Here's a basic renderer configuration that you can adapt **for Markdown output**
(`--format=markdown`):
```yaml
flm:
renderer:
markdown:
use_target_ids: 'github' # or 'anchor' or 'pandoc' or null
```
### Features and their configuration
Many FLM features are organized explicitly into feature classes which can be
enabled or disabled at wish. Features include:
- enumeration (`\begin{enumerate}...\end{enumerate}`) and itemization
(`\begin{itemize}...\end{itemize}`) lists
- floats: figures and tables (`\begin{figure}...\end{figure}`)
- headings (`\section{...}` etc.)
- etc.
Features can be selected and configured directly in the FLM config metadata. For instance
the following configuration is extracted from the default feature configuration when you run
FLM:
```yaml
flm:
features:
# list features that should be available here.
enumeration:
enumeration_environments:
enumerate:
# here null means to use defaults
counter_formatter: null
itemize:
counter_formatter:
- "\u2022"
- '-'
- "\u25B8"
refs: {}
endnotes:
categories:
- category_name: footnote
counter_formatter: alph
endnote_command: footnote
heading_title: Footnotes
render_options:
include_headings_at_level: 1
set_headings_target_ids: true
endnotes_heading_title: null
endnotes_heading_level: 1
floats:
float_types:
- counter_formatter: Roman
float_caption_name: Fig.
float_type: figure
content_handlers: ['any', 'includegraphics', 'cells']
- counter_formatter: Roman
float_caption_name: Tab.
float_type: table
content_handlers: ['cells']
defterm: {}
graphics: {}
```
## Additional Features such as *Citations*
Additional features can be imported in the flm config. They can reside in other
python packages. Some day I'll properly document how to write new features.
For now, check out the examples in `flm/feature/xxx.py` (and keep in mind that
the APIs are still likely to change!).
To include for instance the citations feature provided by the
[flm-citations](https://github.com/phfaist/flm-citations) package, install that
package and use the config:
```yaml
$import:
- pkg:flm_citations
bibliography:
- bibpreset.yaml
- anotherbibtest.json
```
Citations are organized by citation prefix and are automatically retrieved
depending on the type of citation. By default:
- Citations of the form `arxiv:<arXiv ID>` are automatically retrieved from the arXiv API
- Citations of the form `doi:<DOI>` are automatically retrieved from [doi.org](https://doi.org/)
- Citations of the form `manual:{Manual citation}` add the manual citation itself as a citation
- Citations of the form `bib:key` look up `key` in one of the specified bibliography files. The
bibliography files are expected to be CSL-JSON or CSL-YAML files. (Sorry, no bibtex for now.)
You can of course configure all of that manually. Check out the code in the
[`flm-citations`](https://github.com/phfaist/flm-citations) repo for more insight. Doc will
hopefully come soon.
# Using the `flm` package
Needs doc.
## Example. Converting FLM to HTML
Note: Math is simply marked with `<span class=...>` tags for use with
[MathJax](https://www.mathjax.org/).
Example:
```py
from flm.flmenvironment import make_standard_environment
from flm.stdfeatures import standard_features
from flm.fragmentrenderer.html import HtmlFragmentRenderer
environ = make_standard_environment(features=standard_features())
# suppose we have fragments of FLM text
fragment_1 = environ.make_fragment(r'Hello, \emph{world}.')
fragment_2 = environ.make_fragment(
r'''Here's a question: \(1+2=?\)
\begin{enumerate}[(a)]
\item 1
\item 2
\item 3
\end{enumerate}
'''
)
# we can define a callback to render these fragments within an
# HTML page. The advantage of doing so is that different fragments
# can "see" each other! (E.g., for \ref's, etc.) This feature can
# be useful especially in combination with template engines.
def render_fn(render_context):
return (
"<main>\n"
+ "<div>" + fragment_1.render(render_context) + "</div>\n"
+ fragment_2.render(render_context) + "\n"
+ "</main>"
)
doc = environ.make_document(render_fn)
fragment_renderer = HtmlFragmentRenderer()
result_html, render_context = doc.render(fragment_renderer)
print(result_html)
# *** Prints:
#
# <main>
# <div>Hello, <span class="textit">world</span>.</div>
# <p>Here's a question: <span class="inline-math">\(1+2=?\)</span></p>
# <dl class="enumeration enumerate"><dt>(a)</dt><dd><p>1</p></dd><dt>(b)</dt><dd><p>2</p></dd><dt>(c)</dt><dd><p>3</p></dd></dl>
# </main>
```
# A Javascript FLM library
You can transpile the core part of this library to Javascript using Transcrypt.
See [the `flm-js` subfolder](flm-js/README.md) for more details.
Raw data
{
"_id": null,
"home_page": "",
"name": "flm-core",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Philippe Faist",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/b9/f5/70fa79b2492a24554a845796542c0fbfc22e3a8ffebc7cbb3fcc5754917b/flm_core-0.3.0a12.tar.gz",
"platform": null,
"description": "# A Flexible Latex-Like Markup (FLM) language\n\nThis package provides a simple parser and formatter for a custom markup language\nthat is inspired by LaTeX syntax.\n\nThe syntax of FLM is essentially a subset of standard LaTeX commands, including\nmacros, environments, and some characters that have a special meaning; these\nfeatures are parsed in a loosely similar fashion to usual LaTeX code.\n\nThe framework is meant to be very easily extendible and customizable. The\nparser is based on the upcoming version 3 of\n[*pylatexenc*](https://github.com/phfaist/pylatexenc)\n(currently in pre-release on pypi).\n\nFLM is used to write the contents of the [Error Correction\nZoo](https://errorcorrectionzoo.org/) in a way that is intuitive for scientists,\nflexible, and robust. It is easily extensible and closely resembles the LaTeX\nlangauge that many scientists are familiar with. FLM pushes further one of the\ncore insights of LaTeX, namely, that the code should *describe* document\ncontents in an intuitive way, as a markup language, while disregarding as much\nas possible the details of how that contents will be typeset. The final\ntypesetting is fully customizable, e.g., through CSS styling of its HTML output\n(including the use of templates).\n\nI intended to call this project \"LLM\" as an acronym for Latex-Like Markup, but\nhad to revise my choice after the astronomical growth of large language models.\n\nYou can install FLM with pip:\n```bash\n$ pip install flm-core\n```\n\nExample `mydocument.flm`:\n```latex\n---\ntitle: Kitaev's Surface Code\n---\n\\section{Kitaev's Surface Code}\n\nThe \\emph{stabilizers} of the \\textit{surface code} on the 2-dimensional\ntorus are generated by star operators \\(A_v\\) and plaquette operators\n\\(B_p\\). Each star operator is a \\textbf{product} of four Pauli-\\(X\\)\noperators on the edges adjacent to a vertex \\(v\\) of the lattice; each\nplaquette operator is a product of four Pauli-\\(Z\\) operators applied to\nthe edges adjacent to a face, or plaquette, \\(p\\) of the lattice\n(\\ref{figure:toric-code-operators}).\n\n\\begin{figure}\n \\includegraphics{toric-code-operators}\n \\caption{Stabilizer generators and logical operators of the 2D surface\n code on a torus. The star operators \\(A_v\\) and the plaquette\n operators \\(B_p\\) generate the stabilizer group of the toric code.\n The logical operators are strings that wrap around the torus.}\n \\label{figure:toric-code-operators}\n\\end{figure}\n\n...\n```\n\nTo compile your document into an HTML page, use:\n```bash\n$ flm mydocument.flm -o mydocument.html --format=html --template=simple\n```\n\nYou can then open the `mydocument.html` file in your browser.\n\n# This is work in progress!\n\nThis project is still early in an active development stage, and there might\nstill be a few bugs around. You can expect the API to still change pretty\ndrastically. Feel free to share ideas!\n\n# Use as a command-line tool\n\nYou can use `flm` in command-line mode to compile your documents:\n```bash\n$ flm mydocument.flm\n```\n\nRun `flm --help` to get a list of options. They should be fairly\nstandard and/or self-explanatory:\n```bash\n# output to file mydocument.html, format HTML, including skeleton\n# HTML structure with minimal CSS.\n$ flm mydocument.flm -o mydocument.html --format=html --template=simple\n```\n\nAvailable formats are `html`, `text`, `latex`, and `markdown`. Formats\n`text`, `markdown`, and `latex` are very experimental! (You can also\ngenerate `pdf` output with the options `--workflow=runlatexpdf --format=pdf`\nif your system has a standard LaTeX distribution such as TeXLive installed)\n\n- **Additional HTML Templates:**\n The `--template=` option can be used to change the template used to render the\n document. See also the\n [*flm-templates*](https://github.com/phfaist/flm-templates) extension package\n for some additional templates and template engines. You can try:\n ```\n > pip install flm-templates flm-htmlplus\n ```\n and then\n ```\n > flm mydocument.flm -o output.html -w flm_htmlplus -P 'pkg:flm_templates' -t sunset\n ```\n Or try the template `-t oldtextbook`.\n\n- **Citations from arXiv & DOI:**\n Automatically fetch citations from the arXiv, DOI x-references, or other\n sources using the [*flm-citations*](https://github.com/phfaist/flm-citations)\n extension package (see README file there). Install the extension package\n using pip:\n ```\n > pip install flm-citations\n ```\n And then try to compile, e.g., the following FLM document:\n ```yaml\n ---\n $import:\n - pkg:flm_citations\n ---\n \\section{Introduction}\n Let's cite Kitaev's surface code~\\cite{doi:10.1070/RM1997v052n06ABEH002155,doi:10.1007/978-1-4615-5923-8_19,arXiv:quant-ph/9707021}. ...\n ```\n\n- **Theorems and proofs:** Use the environments\n ``\\begin{theorem}..\\end{theorem}``, ``{lemma}``, ``{proposition}``,\n ``{definition}``, ``{remark}``, etc. for typesetting theorems. You can pin\n labels to theorem statements ``\\label{thm:XYZ}`` (use the `thm:` or `x:`\n prefixes regardless of the theorem type, so you can easily change it without\n having to update the label). These environments accept an optional argument\n so you can specify a title, e.g. ``\\begin{theorem}[Euler's theorem]\n ... \\end{theorem}``. Typeset proofs with ``\\begin{proof} ... \\end{proof}``.\n The proof's optional argument enjoys an additional syntax: use\n ``\\begin{proof}[*thm:XYZ] ...`` to typeset `Proof (Theorem 3)` (with the\n correct theorem reference using its label, which must match the one specified\n to the theorem's ``\\label`` command). Use ``\\begin{proof}[**thm:XYZ] ...`` to\n simply typeset `Proof` as usual, but in this way you have the information about\n which theorem the proof is directly at hand; if you later move it around there\n is no ambiguity as to which theorem the proof is associated with. It is also\n the same syntax as supported by the [phfthm latex\n package](https://github.com/phfaist/phfqitltx) which is able to produce\n hyperlinks between theorems and their proofs.\n\n## Document Front Matter\n\nFLM Documents can contain YAML front matter that specify (i) options for the FLM\nparser, (ii) which features to enable, and (iii) additional document metadata such\nas a title.\n```yaml\n---\ntitle: 'My FLM document'\nflm:\n parsing:\n dollar_inline_math_mode: True\n features:\n endnotes:\n categories:\n - category_name: footnote\n counter_formatter: unicodesuperscript\n heading_title: 'Footnotes'\n endnote_command: 'footnote'\n---\n\n\\section{Greeting}\nHello, \\emph{world}. Inline math can now also be typeset\nas $a$ and $b$. ...\n\n```\n\n### Imports\n\nYou can use the `$import:` directive to import a configuration from an\nexternal file, URL, or extension package:\n```yaml\n$import:\n - my-flm-config.yaml # merge my-flm-config.yaml into this config.\n\n# you can still specify configuration to merge with here ...\n...\nflm:\n ...\n```\n\nThe `$import:` target can specify multiple configurations to import. Each list\nitem can be a absolute or relative file path (`$import: 'my-flm-config.yaml'` or\n`$import: /path/to/my/flm-config.yaml`), a URL (`$import:\nhttps://example.com/my/flm-config.yaml`), or a fully qualified python package\nname introduced with ``pkg:package_name`` (e.g., `$import: pkg:flm_citations`).\nIf a package name is specified to the `$import` directive, the package is loaded\nand the default FLM configuration is extracted from it and included (the\n`flm_default_import_config` attribute of the module is read; it is assumed to be\na dictionary or a callable that returns a dictionary). You can optionally\nfollow the package name by a path to specify submodules/attributes to read\ninstead of `flm_default_import_config`; e.g., ``pkg:mypackage/foo/bar`` will\nimport the module `mypackage` and import the configuration dictionary stored in\n``mypackage.foo.bar``. FLM extention plugin/package authors can use this\nfeature to offer preset customization configurations that can easily be included\nwith ``pkg:some_flm_extension_package/some/preset/name``.\n\n\n### Parser configuration\n\nHere's a basic parser configuration that you can adapt:\n```yaml\nflm:\n parsing:\n # Enable/Disable comments as in LaTeX, led by \u2018%%\u2019\n enable_comments: true\n # This string initiates a comment up to the end of\n # the line, if comments are enabled. By default we\n # require TWO '%' signs to avoid accidental comments\n # (e.g., \"... is up 10% from ...\")\n comment_start: '%%'\n # Enable/Disable math mode with $ signs as in LaTeX\n # in addition to \\( ...\\)\n dollar_inline_math_mode: false\n # Force parsing of the content in block-level mode\n # (paragraphs). Here \u2018null\u2019 means to auto-detect\n force_block_level: null\n```\n\n### Renderer configuration (`html`, `text`, `latex`, `markdown`)\n\nHere's a basic renderer configuration that you can adapt **for HTML output**\n(`--format=html`):\n```yaml\nflm:\n renderer:\n html:\n use_link_target_blank: false\n html_blocks_joiner: ''\n # use \u2018headings_tags_by_level: null\u2019 for defaults\n heading_tags_by_level:\n 1: h1\n 2: h2\n 3: h3\n 4: span\n 5: span\n 6: span\n inline_heading_add_space: true\n```\n\nHere's a basic renderer configuration that you can adapt **for text output**\n(`--format=text`):\n```yaml\nflm:\n renderer:\n text:\n display_href_urls: true\n```\n\nHere's a basic renderer configuration that you can adapt **for LaTeX output**\n(`--format=latex`):\n```yaml\nflm:\n renderer:\n latex:\n heading_commands_by_level:\n 1: \"section\"\n 2: \"subsection\"\n 3: \"subsubsection\"\n 4: \"paragraph\"\n 5: \"subparagraph\"\n 6: null\n```\n\nHere's a basic renderer configuration that you can adapt **for Markdown output**\n(`--format=markdown`):\n```yaml\nflm:\n renderer:\n markdown:\n use_target_ids: 'github' # or 'anchor' or 'pandoc' or null\n```\n\n\n### Features and their configuration\n\nMany FLM features are organized explicitly into feature classes which can be\nenabled or disabled at wish. Features include:\n\n- enumeration (`\\begin{enumerate}...\\end{enumerate}`) and itemization\n (`\\begin{itemize}...\\end{itemize}`) lists\n \n- floats: figures and tables (`\\begin{figure}...\\end{figure}`)\n\n- headings (`\\section{...}` etc.)\n\n- etc.\n\nFeatures can be selected and configured directly in the FLM config metadata. For instance\nthe following configuration is extracted from the default feature configuration when you run\nFLM:\n```yaml\nflm:\n features:\n # list features that should be available here.\n enumeration:\n enumeration_environments:\n enumerate:\n # here null means to use defaults\n counter_formatter: null\n itemize:\n counter_formatter:\n - \"\\u2022\"\n - '-'\n - \"\\u25B8\"\n refs: {}\n endnotes:\n categories:\n - category_name: footnote\n counter_formatter: alph\n endnote_command: footnote\n heading_title: Footnotes\n render_options:\n include_headings_at_level: 1\n set_headings_target_ids: true\n endnotes_heading_title: null\n endnotes_heading_level: 1\n floats:\n float_types:\n - counter_formatter: Roman\n float_caption_name: Fig.\n float_type: figure\n content_handlers: ['any', 'includegraphics', 'cells']\n - counter_formatter: Roman\n float_caption_name: Tab.\n float_type: table\n content_handlers: ['cells']\n defterm: {}\n graphics: {}\n```\n\n## Additional Features such as *Citations*\n\nAdditional features can be imported in the flm config. They can reside in other\npython packages. Some day I'll properly document how to write new features.\nFor now, check out the examples in `flm/feature/xxx.py` (and keep in mind that\nthe APIs are still likely to change!).\n\nTo include for instance the citations feature provided by the\n[flm-citations](https://github.com/phfaist/flm-citations) package, install that\npackage and use the config:\n```yaml\n$import:\n - pkg:flm_citations\nbibliography:\n - bibpreset.yaml\n - anotherbibtest.json\n```\nCitations are organized by citation prefix and are automatically retrieved\ndepending on the type of citation. By default:\n- Citations of the form `arxiv:<arXiv ID>` are automatically retrieved from the arXiv API\n- Citations of the form `doi:<DOI>` are automatically retrieved from [doi.org](https://doi.org/)\n- Citations of the form `manual:{Manual citation}` add the manual citation itself as a citation\n- Citations of the form `bib:key` look up `key` in one of the specified bibliography files. The\n bibliography files are expected to be CSL-JSON or CSL-YAML files. (Sorry, no bibtex for now.)\n\nYou can of course configure all of that manually. Check out the code in the\n[`flm-citations`](https://github.com/phfaist/flm-citations) repo for more insight. Doc will\nhopefully come soon.\n\n\n# Using the `flm` package\n\nNeeds doc.\n\n## Example. Converting FLM to HTML\n\nNote: Math is simply marked with `<span class=...>` tags for use with\n[MathJax](https://www.mathjax.org/).\n\nExample:\n```py\nfrom flm.flmenvironment import make_standard_environment\nfrom flm.stdfeatures import standard_features\nfrom flm.fragmentrenderer.html import HtmlFragmentRenderer\n\nenviron = make_standard_environment(features=standard_features())\n\n# suppose we have fragments of FLM text\nfragment_1 = environ.make_fragment(r'Hello, \\emph{world}.')\nfragment_2 = environ.make_fragment(\n r'''Here's a question: \\(1+2=?\\)\n\\begin{enumerate}[(a)]\n\\item 1\n\\item 2\n\\item 3\n\\end{enumerate}\n'''\n)\n\n# we can define a callback to render these fragments within an\n# HTML page. The advantage of doing so is that different fragments\n# can \"see\" each other! (E.g., for \\ref's, etc.) This feature can\n# be useful especially in combination with template engines.\ndef render_fn(render_context):\n return (\n \"<main>\\n\"\n + \"<div>\" + fragment_1.render(render_context) + \"</div>\\n\"\n + fragment_2.render(render_context) + \"\\n\"\n + \"</main>\"\n )\n\ndoc = environ.make_document(render_fn)\n\nfragment_renderer = HtmlFragmentRenderer()\nresult_html, render_context = doc.render(fragment_renderer)\n\nprint(result_html)\n# *** Prints:\n#\n# <main>\n# <div>Hello, <span class=\"textit\">world</span>.</div>\n# <p>Here's a question: <span class=\"inline-math\">\\(1+2=?\\)</span></p>\n# <dl class=\"enumeration enumerate\"><dt>(a)</dt><dd><p>1</p></dd><dt>(b)</dt><dd><p>2</p></dd><dt>(c)</dt><dd><p>3</p></dd></dl>\n# </main>\n```\n\n\n# A Javascript FLM library\n\nYou can transpile the core part of this library to Javascript using Transcrypt.\nSee [the `flm-js` subfolder](flm-js/README.md) for more details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Flexible Latex-like Markup",
"version": "0.3.0a12",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "efbef040f4595fe7aa9f82db6f4026da6a07bc26e6518af702f67d3c381b1365",
"md5": "7785319ebe9f17f2c983bd0af407e2fb",
"sha256": "a7bf12c77e61c31e090efd0b39256eda687943e6da205d0b00d3f443d354acfe"
},
"downloads": -1,
"filename": "flm_core-0.3.0a12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7785319ebe9f17f2c983bd0af407e2fb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 156569,
"upload_time": "2023-08-30T07:33:50",
"upload_time_iso_8601": "2023-08-30T07:33:50.345443Z",
"url": "https://files.pythonhosted.org/packages/ef/be/f040f4595fe7aa9f82db6f4026da6a07bc26e6518af702f67d3c381b1365/flm_core-0.3.0a12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b9f570fa79b2492a24554a845796542c0fbfc22e3a8ffebc7cbb3fcc5754917b",
"md5": "98dca75db3bd018795e859a702b60457",
"sha256": "a2e6cf50e7a1c60e893924a156884dfebda73a5f600f27d875bc610cd2eccc70"
},
"downloads": -1,
"filename": "flm_core-0.3.0a12.tar.gz",
"has_sig": false,
"md5_digest": "98dca75db3bd018795e859a702b60457",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 129775,
"upload_time": "2023-08-30T07:33:52",
"upload_time_iso_8601": "2023-08-30T07:33:52.643478Z",
"url": "https://files.pythonhosted.org/packages/b9/f5/70fa79b2492a24554a845796542c0fbfc22e3a8ffebc7cbb3fcc5754917b/flm_core-0.3.0a12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-30 07:33:52",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "flm-core"
}
