Skip to content

Commit 796bdc8

Browse files
mdbenitomdbenito
committed
Update documentation and readme
1 parent e5a57ad commit 796bdc8

File tree

2 files changed

+100
-84
lines changed

2 files changed

+100
-84
lines changed

‎README.md‎

Lines changed: 49 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# Markdown plug-in
2+
13
# TeXmacs markdown plugin
24

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

1619
## Setup
1720

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

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

36+
## Extensions to vanilla markdown
37+
38+
Besides standard Markdown, this plugins does the following:
39+
40+
* Footnotes (and marginal notes, exported as footnotes for vanilla markdown).
41+
* Links to equations and equation arrays. Labels are exported as HTML
42+
`<span>` with identifiers sanitized and custom CSS. See
43+
`extensions/tmmarkdown.css`.
44+
* Support for most standard environments, both numbered and unnumbered.
45+
Localized and with support for references and `<smart-ref>`.
46+
* Probably more…
47+
3348
## Hugo support
3449

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

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

5068
### Supported shortcodes
5169

52-
Some of the texmacs markdown requires custom shortcodes and layouts. You can
53-
find them in `extensions/hugo`. Just copy the partials and shortcodes to your
54-
Hugo project.
55-
56-
* Figures are converted to `{{< tmfigure … >}}`. This is a simplified version
57-
of Hugo's `{{<figure>}}`, which can have `.Inner` content. This is required
58-
e.g. to have citations in captions or arbitrary markup.
59-
* To introduce any shortcode in a TeXmacs document, you can use the macro
60-
`\hugo-short`.
61-
* Citations are automatically detected and converted to
62-
`{{< cite ref1 ref2 ... >}}`, and all of them are gathered in the frontmatter
63-
as well, for indization by Hugo's taxonomy system. The presentation of the
64-
label itself is done using CSS. Include the partial `ref_labels.html.html`
65-
in the document `<head>` for that.
66-
* Bibliography is rendered with the `references.html.html` template.
70+
All custom shortcodes are in `extensions/hugo/`.
71+
72+
* Figures are converted to `{{< figure … >}}`.
73+
* For arbitrary shortcodes, use `<hugo-short>`, e.g. `<hugo-short|toc>` for
74+
`{{< toc >}}`.
75+
* Citations are automatically detected and converted to `{{< cite ref
76+
>}}`, and all of them are gathered in the frontmatter as well, for
77+
indization by Hugo's taxonomy system. The rendering of bibliography is done
78+
by `{{< references >}}`.
79+
* Marginal notes and figures are converted to `{{< sidenote … >}}`
80+
and `{{< sidefigure … >}}`.
6781

6882
# Known issues
6983

70-
* The converter can break with malformed or unexpected input, like markup
71-
inside tags whose values should be strings, although some cases are (a bit
72-
sloppily) handled.
73-
* Error reporting is rather lacking. Run TeXmacs in a console to see stack
84+
For an up-to date list, see the [issue tracker in
85+
GitHub](https://github.com/texmacs/markdown/issues/).
86+
87+
* The converter can break with malformed or unexpected input, like markup
88+
inside tags whose values should be strings (although many cases are
89+
“handled”)
90+
* Error reporting is rather lacking. Run TeXmacs in a console to see stack
7491
traces and such in case you are running into problems.
75-
* No tables (yet)!
76-
* Images must be linked, not embedded in the document.
77-
78-
# To do
79-
80-
* Reverse markdown to TeXmacs conversion.
81-
* Declare converter options in init file, and use.
82-
* Make behaviour of all tags configurable, e.g. to support different styles.
83-
For instance, should titles, chapters or sections be `h1`?
84-
* Extract all Hugo extensions to a separate file, use overloading and
85-
extension of the dispatch hashmaps.
86-
* Use “converter environments”?
87-
* Use TeXmacs' `logic-dispatch`?
88-
* line-breaks and other markup in doc-data (e.g. in the doc-title) need to be
89-
properly handled if included in YAML metadata for Hugo.
90-
* Support for tables.
91-
* Extract embedded images.
92+
* EPS and PDF images are not supported by browsers. As a workaround allowing
93+
to have both, use `<md-alt-image>`. The first argument is for TeXmacs and
94+
the second one for the markdown export.
95+
* The converter supports only one style. For instance all environments have
96+
emphasized bodies and bold names, `<section>` is exported as `h1`, etc.
9297

9398
# License
9499

‎doc/markdown.en.tm‎

Lines changed: 51 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<TeXmacs|1.99.18>
1+
<TeXmacs|2.1>
22

33
<style|tmdoc>
44

@@ -39,6 +39,25 @@
3939

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

42+
<subsection|Extensions to vanilla markdown>
43+
44+
Besides standard Markdown, this plugins does the following:
45+
46+
<\itemize-dot>
47+
<item>Footnotes (and marginal notes, exported as footnotes for vanilla
48+
markdown).
49+
50+
<item>Links to equations and equation arrays. Labels are exported as HTML
51+
<verbatim|\<less\>span\<gtr\>> with identifiers sanitized and custom CSS.
52+
See <verbatim|extensions/tmmarkdown.css>.
53+
54+
<item>Support for most standard environments, both numbered and
55+
unnumbered. Localized and with support for references and
56+
<explain-macro|smart-ref>.
57+
58+
<item>Probably more<text-dots>
59+
</itemize-dot>
60+
4261
<subsection|Hugo support>
4362

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

53-
Now you can type <verbatim|\\hugo-front> and input any number of key\|value
54-
pairs as arguments, one argument each. That is: type
55-
<verbatim|\\hugo-front>, then use structured insert right to add two
56-
arguments and use the first for the key and the second for the value.
57-
Repeat as needed. Currently, only strings, lists of strings and dates
58-
(insert with <verbatim|\\date>) are supported as values. To enter a list,
59-
input <verbatim|\\tuple> as the value and use structured insert right to
60-
add items.
72+
Now you can use <explain-macro|hugo-front> to input any number of
73+
<verbatim|key\|value> pairs as arguments, one argument each. That is:
74+
insert the tag <explain-macro|hugo-front>, then use structured insert right
75+
to add two arguments and use the first for the key and the second for the
76+
value. Repeat as needed. It is possible to use strings, booleans (\Ptrue\Q,
77+
\Pfalse\Q) or dates (insert with <explain-macro|date>). Additionally, the
78+
macro <explain-macro|pdf-name> inserts the name of the file with
79+
<verbatim|.pdf> appended. To enter a list, input <explain-macro|tuple> as
80+
the value and use structured insert right to add items. To input a
81+
dictionary, use <explain-macro|dict> and again use structured insert to
82+
create tuples of <verbatim|key\|value>.
6183

6284
<subsubsection|Supported shortcodes>
6385

86+
All custom shortcodes are in <verbatim|extensions/hugo/>.
87+
6488
<\itemize-dot>
6589
<item>Figures are converted to <code*|{{\<less\> figure <text-dots>
66-
\<gtr\>}}>
90+
\<gtr\>}}>.
6791

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

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

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

77106
<section|Known issues>
78107

108+
For an up-to date list, see the <hlink|issue tracker in
109+
GitHub|https://github.com/texmacs/markdown/issues/>.
110+
79111
<\itemize>
80112
<item>The converter can break with malformed or unexpected input, like
81113
markup inside tags whose values should be strings (although many cases
@@ -84,34 +116,13 @@
84116
<item>Error reporting is rather lacking. Run <TeXmacs> in a console to
85117
see stack traces and such in case you are running into problems.
86118

87-
<item>No tables (yet)!
88-
89-
<item>Images must be linked, not embedded in the document.
90-
</itemize>
91-
92-
<section|To do>
93-
94-
<\itemize>
95-
<item>Reverse markdown to <TeXmacs> conversion.
96-
97-
<item>Declare converter options in init file, and use.
98-
99-
<item>Make behaviour of all tags configurable, e.g. to support different
100-
styles. For instance, should titles, chapters or sections be <code*|h1>?
101-
102-
<item>Extract all Hugo extensions to a separate file, use overloading and
103-
extension of the dispatch hashmaps.
104-
105-
<item>Use \Pconverter environments\Q?
106-
107-
<item>Use <TeXmacs>' <code*|logic-dispatch>?
108-
109-
<item>line-breaks and other markup in doc-data (e.g. in the doc-title)
110-
need to be properly handled if included in YAML metadata for Hugo.
111-
112-
<item>Support for tables.
119+
<item>EPS and PDF images are not supported by browsers. As a workaround
120+
allowing to have both, use <explain-macro|md-alt-image>. The first
121+
argument is for <TeXmacs> and the second one for the markdown export.
113122

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

117128
<section|License>

0 commit comments

Comments
 (0)