Skip to content

Commit

Permalink
Update documentation and readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@mdbenito
mdbenito committed Jul 18, 2021
1 parent e5a57ad commit 796bdc8
Show file tree
Hide file tree
Showing 2 changed files with 100 additions and 84 deletions.
93 changes: 49 additions & 44 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
# Markdown plug-in

# TeXmacs markdown plugin

This plugin is a (for now one-way) converter to markdown format for
Expand All @@ -10,8 +12,9 @@ and pasting into the markdown file.
The plugin has been developed for its use in two specific websites,
[Paperwhy](https://paperwhy.8027.org/) and appliedAI's
[TransferLab](https://transferlab.appliedai.de/), and can use multiple
extensions specific to the static website generator [Hugo](https://gohugo.io/).
There might still be some code very specific to those sites, YMMV.
extensions specific to the static website generator
[Hugo](https://gohugo.io/). There might still be some code very specific to
those sites, YMMV.

## Setup

Expand All @@ -30,6 +33,18 @@ For Windows, the path (usually?) is

You can activate a menu with `Tools -> Markdown plugin`.

## Extensions to vanilla markdown

Besides standard Markdown, this plugins does the following:

* Footnotes (and marginal notes, exported as footnotes for vanilla markdown).
* Links to equations and equation arrays. Labels are exported as HTML
`<span>` with identifiers sanitized and custom CSS. See
`extensions/tmmarkdown.css`.
* Support for most standard environments, both numbered and unnumbered.
Localized and with support for references and `<smart-ref>`.
* Probably more…

## Hugo support

In addition to standard markdown, almost everything that Hugo supports can be
Expand All @@ -40,55 +55,45 @@ Setting values for the frontmatter is suported via a dedicated macro defined
in `hugo.ts`. To use it first insert the `Markdown -> Hugo` package in
`Document -> Style -> Add package` or using the plus sign in the focus bar.

Now you can type `\hugo-front` and input any number of key|value pairs as
arguments, one argument each. That is: type `\hugo-front`, then use structured
insert right to add two arguments and use the first for the key and the second
for the value. Repeat as needed. Currently, only strings, lists of strings and
dates (insert with `\date`) are supported as values. To enter a list, input
`\tuple` as the value and use structured insert right to add items.
Now you can use `<hugo-front>` to input any number of `key|value` pairs as
arguments, one argument each. That is: insert the tag `<hugo-front>`, then use
structured insert right to add two arguments and use the first for the key and
the second for the value. Repeat as needed. It is possible to use strings,
booleans (“true”, “false”) or dates (insert with `<date>`). Additionally, the
macro `<pdf-name>` inserts the name of the file with `.pdf` appended. To enter
a list, input `<tuple>` as the value and use structured insert right to add
items. To input a dictionary, use `<dict>` and again use structured insert to
create tuples of `key|value`.

### Supported shortcodes

Some of the texmacs markdown requires custom shortcodes and layouts. You can
find them in `extensions/hugo`. Just copy the partials and shortcodes to your
Hugo project.

* Figures are converted to `{{< tmfigure … >}}`. This is a simplified version
of Hugo's `{{<figure>}}`, which can have `.Inner` content. This is required
e.g. to have citations in captions or arbitrary markup.
* To introduce any shortcode in a TeXmacs document, you can use the macro
`\hugo-short`.
* Citations are automatically detected and converted to
`{{< cite ref1 ref2 ... >}}`, and all of them are gathered in the frontmatter
as well, for indization by Hugo's taxonomy system. The presentation of the
label itself is done using CSS. Include the partial `ref_labels.html.html`
in the document `<head>` for that.
* Bibliography is rendered with the `references.html.html` template.
All custom shortcodes are in `extensions/hugo/`.

* Figures are converted to `{{< figure … >}}`.
* For arbitrary shortcodes, use `<hugo-short>`, e.g. `<hugo-short|toc>` for
`{{< toc >}}`.
* Citations are automatically detected and converted to `{{< cite ref
>}}`, and all of them are gathered in the frontmatter as well, for
indization by Hugo's taxonomy system. The rendering of bibliography is done
by `{{< references >}}`.
* Marginal notes and figures are converted to `{{< sidenote … >}}`
and `{{< sidefigure … >}}`.

# Known issues

* The converter can break with malformed or unexpected input, like markup
inside tags whose values should be strings, although some cases are (a bit
sloppily) handled.
* Error reporting is rather lacking. Run TeXmacs in a console to see stack
For an up-to date list, see the [issue tracker in
GitHub](https://github.com/texmacs/markdown/issues/).

* The converter can break with malformed or unexpected input, like markup
inside tags whose values should be strings (although many cases are
“handled”)
* Error reporting is rather lacking. Run TeXmacs in a console to see stack
traces and such in case you are running into problems.
* No tables (yet)!
* Images must be linked, not embedded in the document.

# To do

* Reverse markdown to TeXmacs conversion.
* Declare converter options in init file, and use.
* Make behaviour of all tags configurable, e.g. to support different styles.
For instance, should titles, chapters or sections be `h1`?
* Extract all Hugo extensions to a separate file, use overloading and
extension of the dispatch hashmaps.
* Use “converter environments”?
* Use TeXmacs' `logic-dispatch`?
* line-breaks and other markup in doc-data (e.g. in the doc-title) need to be
properly handled if included in YAML metadata for Hugo.
* Support for tables.
* Extract embedded images.
* EPS and PDF images are not supported by browsers. As a workaround allowing
to have both, use `<md-alt-image>`. The first argument is for TeXmacs and
the second one for the markdown export.
* The converter supports only one style. For instance all environments have
emphasized bodies and bold names, `<section>` is exported as `h1`, etc.

# License

Expand Down
91 changes: 51 additions & 40 deletions doc/markdown.en.tm
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<TeXmacs|1.99.18>
<TeXmacs|2.1>

<style|tmdoc>

Expand Down Expand Up @@ -39,6 +39,25 @@

You can activate a menu with <menu|Tools|Markdown plugin>.

<subsection|Extensions to vanilla markdown>

Besides standard Markdown, this plugins does the following:

<\itemize-dot>
<item>Footnotes (and marginal notes, exported as footnotes for vanilla
markdown).

<item>Links to equations and equation arrays. Labels are exported as HTML
<verbatim|\<less\>span\<gtr\>> with identifiers sanitized and custom CSS.
See <verbatim|extensions/tmmarkdown.css>.

<item>Support for most standard environments, both numbered and
unnumbered. Localized and with support for references and
<explain-macro|smart-ref>.

<item>Probably more<text-dots>
</itemize-dot>

<subsection|Hugo support>

In addition to standard markdown, almost everything that Hugo supports can
Expand All @@ -50,32 +69,45 @@
package in <menu|Document|Style|Add package> or using the plus sign in the
focus bar.

Now you can type <verbatim|\\hugo-front> and input any number of key\|value
pairs as arguments, one argument each. That is: type
<verbatim|\\hugo-front>, then use structured insert right to add two
arguments and use the first for the key and the second for the value.
Repeat as needed. Currently, only strings, lists of strings and dates
(insert with <verbatim|\\date>) are supported as values. To enter a list,
input <verbatim|\\tuple> as the value and use structured insert right to
add items.
Now you can use <explain-macro|hugo-front> to input any number of
<verbatim|key\|value> pairs as arguments, one argument each. That is:
insert the tag <explain-macro|hugo-front>, then use structured insert right
to add two arguments and use the first for the key and the second for the
value. Repeat as needed. It is possible to use strings, booleans (\Ptrue\Q,
\Pfalse\Q) or dates (insert with <explain-macro|date>). Additionally, the
macro <explain-macro|pdf-name> inserts the name of the file with
<verbatim|.pdf> appended. To enter a list, input <explain-macro|tuple> as
the value and use structured insert right to add items. To input a
dictionary, use <explain-macro|dict> and again use structured insert to
create tuples of <verbatim|key\|value>.

<subsubsection|Supported shortcodes>

All custom shortcodes are in <verbatim|extensions/hugo/>.

<\itemize-dot>
<item>Figures are converted to <code*|{{\<less\> figure <text-dots>
\<gtr\>}}>
\<gtr\>}}>.

<item>For arbitrary shortcodes, use <verbatim|\\hugo-short>.
<item>For arbitrary shortcodes, use <explain-macro|hugo-short>, e.g.
<explain-macro|hugo-short|toc> for <code*|{{\<less\> toc \<gtr\>}}>.

<item>Citations are automatically detected and converted to
<code*|{{\<less\> cite ref \<gtr\>}}>, and all of them are gathered in
the frontmatter as well, for indization by Hugo's taxonomy system.
the frontmatter as well, for indization by Hugo's taxonomy system. The
rendering of bibliography is done by <code*|{{\<less\> references
\<gtr\>}}>.

<item>Probably more<text-dots>
<item>Marginal notes and figures are converted to <code*|{{\<less\>
sidenote <text-dots> \<gtr\>}}> and <code*|{{\<less\> sidefigure
<text-dots> \<gtr\>}}>.
</itemize-dot>

<section|Known issues>

For an up-to date list, see the <hlink|issue tracker in
GitHub|https://github.com/texmacs/markdown/issues/>.

<\itemize>
<item>The converter can break with malformed or unexpected input, like
markup inside tags whose values should be strings (although many cases
Expand All @@ -84,34 +116,13 @@
<item>Error reporting is rather lacking. Run <TeXmacs> in a console to
see stack traces and such in case you are running into problems.

<item>No tables (yet)!

<item>Images must be linked, not embedded in the document.
</itemize>

<section|To do>

<\itemize>
<item>Reverse markdown to <TeXmacs> conversion.

<item>Declare converter options in init file, and use.

<item>Make behaviour of all tags configurable, e.g. to support different
styles. For instance, should titles, chapters or sections be <code*|h1>?

<item>Extract all Hugo extensions to a separate file, use overloading and
extension of the dispatch hashmaps.

<item>Use \Pconverter environments\Q?

<item>Use <TeXmacs>' <code*|logic-dispatch>?

<item>line-breaks and other markup in doc-data (e.g. in the doc-title)
need to be properly handled if included in YAML metadata for Hugo.

<item>Support for tables.
<item>EPS and PDF images are not supported by browsers. As a workaround
allowing to have both, use <explain-macro|md-alt-image>. The first
argument is for <TeXmacs> and the second one for the markdown export.

<item>Extract embedded images.
<item>The converter supports only one style. For instance all
environments have emphasized bodies and bold names,
<explain-macro|section> is exported as <verbatim|h1>, etc.
</itemize>

<section|License>
Expand Down

0 comments on commit 796bdc8

Please sign in to comment.