forked from mmarkdown/mmark
-
Notifications
You must be signed in to change notification settings - Fork 0
/
mmark-syntax-images.7
69 lines (52 loc) · 2.24 KB
/
mmark-syntax-images.7
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "MMARK-SYNTAX" 7 "April 2019" "User Commands" "Mmark Markdown syntax"
.PP
Images in Mmark are somewhat complicated, not in the least, because XML2RFC needs to output both
HTML and text. To make that work you can specify multiple images in an \fB\fCartset\fR and the renderer will
pick the correct one, depending on the output.
.PP
To include artwork/source/images, you can:
.IP \(bu 4
Use a code block. If this has a language specified, it will become a \fB\fCsourcecode\fR otherwise a will
be an \fB\fCartwork\fR. The contents of both must be in plain text.
.IP \(bu 4
Use subfigures in a figure block (\fB\fC!--\fR) to group figure and potentially make them have a caption.
We also use this syntax to support an \fB\fCartset\fR, but only under special conditions (see below).
.SH "CODE BLOCKS"
.PP
A code block \fIwith\fP a language will be turned into a \fB\fCsourcecode\fR:
.PP
.RS
.nf
``` go
println("hello!")
```
.fi
.RE
.PP
If no language (the \fB\fCgo\fR above) is given it will be an \fB\fCartwork\fR.
.SH "FIGURES IN AN ARTSET"
.PP
To support \fB\fCartset\fR we do the following. If multiple images are present as subfigures, we check
if the name \fIwithout\fP the extension of the image destination (the file to be shown) is equal for all
subfigures. If so, we assume an \fB\fCartset\fR needs to be outputted and do so.
.PP
For example the following will result in a artset where an \fB\fCsvg\fR and an \fB\fCascii-art\fR version of the
(hopefully) same image exists. Note the extension \fBmust\fP be \fB\fCascii-art\fR because we use that to set
the type and XML2RFC checks for that string.
.PP
.RS
.nf
!\-\-\-
!\-\-\-
.fi
.RE
.PP
Note this syntax is also supported for the \fImanual page output\fP and it does the same thing by only
using the \fB\fCascii-art\fR version. This is true for all included imagery; only \fB\fCascii-art\fR ones are
included in the output.
.PP
By some happy co-incidence a browser will not show the \fB\fCascii-art\fR version of the image when
generating HTML. It remains to be seen if we need some code to actually filter these out.