-
Notifications
You must be signed in to change notification settings - Fork 48
/
mmark-syntax.7
1152 lines (925 loc) · 30.5 KB
/
mmark-syntax.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
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "MMARK-SYNTAX" 7 "April 2019" "User Commands" "Mmark Markdown syntax"
.PP
This is version 2 of Mmark
\[la]https://github.com/mmarkdown/mmark\[ra]: based on a new markdown
implementation
\[la]https://github.com/gomarkdown/markdown\[ra] and some (small) language changes as well. We
think these language changes lead to a more consistent user experience and lead to less confusion.
.PP
See changes from v1
\[la]#changes-from-version-1\[ra] if you're coming from version 1.
.PP
Biggest changes:
.IP \(bu 4
Including files is now done relative to the file being parsed (i.e. the \fIsane\fP way).
.IP \(bu 4
Block attributes apply to block elements \fIonly\fP.
.IP \(bu 4
Callouts
.RS
.IP \(en 4
\fIalways\fP rendered and require double greater/less\-than signs, \fB\fC<<1>>\fR.
.IP \(en 4
\fIalways\fP require a comment in the code, i.e. \fB\fC//<<1>>\fR will be rendered as a callout, a plain
\fB\fC<<1>>\fR will not.
.RE
.IP \(bu 4
Block Tables have been dropped.
.IP \(bu 4
Example lists (originally copied from Pandoc) have been dropped.
.IP \(bu 4
Plain citations, i.e. \fB\fC@RFC5412\fR, when the reference was previously seen don't work anymore,
always use the full syntax \fB\fC[@RFC5412]\fR.
.SH "WHY THIS NEW VERSION?"
.PP
It fixes a bunch of long standing bugs and the parser generates an abstract syntax tree (AST).
It will be easier to add new renderers with this setup. It is also closer to Common Mark. So we
took this opportunity to support RFC 7991 XML (xml2rfc version 3), HTML5 and manual page output.
Also with code upstreamed (to gomarkdown
\[la]https://github.com/gomarkdown\[ra]), we have less code to
maintain.
.PP
Because of the abstract syntax tree it will also be easier to write helper tools, like, for instance
a tool that checks if all referenced labels in the document are actually defined. Another idea could
be to write a "check\-the\-code" tool that syntax checks all code in code blocks. Eventually these
could be build into the \fB\fCmmark\fR binary itself. See some fun
ideas
\[la]https://github.com/mmarkdown/filter\[ra] here.
.SH "MMARK V2 SYNTAX"
.PP
This document describes all the \fIextra\fP syntax elements that can be used in Mmark. Mmark's syntax is
based on the "standard" Markdown syntax
\[la]https://daringfireball.net/projects/markdown/syntax\[ra].
A good primer on what blackfriday implements is this
article
\[la]https://notes.peter-baumgartner.net/archive/content-organisation/blackfriday-markdown/\[ra].
.PP
.RS
.PP
Read the above documents if you haven't already, it helps you understand how markdown looks and feels.
.RE
.PP
For the rest we build up on https://github.com/gomarkdown/markdown
\[la]https://github.com/gomarkdown/markdown\[ra] and support all syntax
it supports
\[la]https://github.com/gomarkdown/markdown/blob/master/README.md\[ra]. We enable the following
extensions
\[la]https://github.com/gomarkdown/markdown/blob/master/README.md#extensions\[ra] by default:
.IP \(bu 4
\fIStrikethrough\fP, allow strike through text using \fB\fC~~test~~\fR.
.IP \(bu 4
\fIAutolink\fP, detect embedded URLs that are not explicitly marked.
.IP \(bu 4
\fIFootnotes\fP Pandoc style footnotes.
.IP \(bu 4
\fIHeadingIDs\fP, specify heading IDs with \fB\fC{#id}\fR.
.IP \(bu 4
\fIAutoHeadingIDs\fP, create the heading ID from the text.
.IP \(bu 4
\fIDefinitionLists\fP, parse definition lists.
.IP \(bu 4
\fIMathJax\fP, parse MathJax
.IP \(bu 4
\fIOrderedListStart\fP, notice start element of ordered list.
.IP \(bu 4
\fIAttributes\fP, allow block level attributes.
.IP \(bu 4
\fISmartypants\fP, expand \fB\fC--\fR and \fB\fC---\fR into ndash and mdashes.
.IP \(bu 4
\fISuperSubscript\fP, parse super\- and subscript: H\d2\uO is water and 2\u10\d is 1024.
.IP \(bu 4
\fITables\fP, parse tables.
.IP \(bu 4
\fINonBlockingSpace\fP, convert "backslash space" into a non blocking space.
.PP
Mmark adds numerous enhancements to make it suitable for writing (IETF
\[la]https://ietf.org\[ra]) Internet
Drafts and even complete books. It <strike>steals</strike> borrows syntax elements from pandoc
\[la]http://johnmacfarlane.net/pandoc/\[ra],
kramdown
\[la]https://kramdown.gettalong.org/\[ra], leanpub
\[la]https://leanpub.com/help/manual\[ra], asciidoc
\[la]http://www.methods.co.nz/asciidoc/\[ra], PHP markdown extra
\[la]http://michelf.com/projects/php-markdown/extra/\[ra] and Scholarly markdown
\[la]http://scholarlymarkdown.com/Scholarly-Markdown-Guide.html\[ra].
.SH "WHAT DOES MMARK ADD?"
.PP
Mmark adds:
.IP \(bu 4
(Extended) title block
\[la]#title-block\[ra] to specify authors and IETF specific bits in
TOML
\[la]https://en.wikipedia.org/wiki/TOML\[ra] format.
.IP \(bu 4
Special sections
\[la]#special-sections\[ra], for abstracts, prefaces or notes.
.IP \(bu 4
Including other files
\[la]#including-files\[ra] with the option to specify line ranges, regular
expressions and/or prefixing each line with a custom string.
.IP \(bu 4
Document divisions
\[la]#document-divisions\[ra].
.IP \(bu 4
Captions
\[la]#captions\[ra] for code, tables, quotes and subfigures.
.IP \(bu 4
Asides
\[la]#asides\[ra].
.IP \(bu 4
Figures and Subfigures
\[la]#figures-and-subfigures\[ra] \- allows grouping images into subfigures as
well as giving a single image metadata (a link, attributes, etc.). See Images in
Mmark
\[la]/syntax/images\[ra] for more details.
.IP \(bu 4
Block Level Attributes
\[la]#block-level-attributes\[ra] that allow to specify attributes, classes and
IDs for elements.
.IP \(bu 4
Indices
\[la]#indices\[ra] to mark an item (and/or a subitem) to be referenced in the document index.
.IP \(bu 4
Citations
\[la]#citations\[ra] and adding XML References
\[la]#xml-references\[ra].
.IP \(bu 4
In document cross references
\[la]#cross-references\[ra], short form of referencing a section in the
document.
.IP \(bu 4
Super\- and Subscript
\[la]#super-and-subscript\[ra]
.IP \(bu 4
Callouts
\[la]#callouts\[ra] in code and text.
.IP \(bu 4
BCP14
\[la]#bcp14\[ra] (RFC 2119) keyword detection.
.SS "SYNTAX GOTCHAS"
.PP
Because markdown is not perfect, there are some gotchas you have to be aware of:
.IP \(bu 4
Adding a caption under a quote block (\fB\fCQuote:\fR) needs a newline before it, otherwise the caption text
will be detected as being part of the quote.
.IP \(bu 4
Including files (and code includes) requires an empty line before them, as they are block level
elements and we need to trigger \fIthat\fP scan from the parser.
.IP \(bu 4
Including files in lists requires a empty line to be present in the list item; otherwise Mmark
will only assume inline elements and not parse the includes (which are block level elements).
.IP \(bu 4
A bibliography is \fIonly added\fP if a \fB\fC{backmatter}\fR has been specified, because we need to add just
before that point.
.IP \(bu 4
Intra\-work emphasis is enabled so a string like \fB\fCSSH_MSG_KEXECDH_REPLY\fR is interpreted as
\fB\fCSSH<em>MSG</em>...\fR. You need to escape the underscores: \fB\fCSSH\_MSG...\fR.
.SS "RFC 7991 XML OUTPUT"
.PP
This is the output format used for generating Internet\-Drafts and RFCs. The generated XML needs to
be processed by another tool (xml2rfc) to generate to official (final) output. The XML from \fImmark\fP
can be used directly to upload to the IETF tools website.
.TP
Title Block:
If the document has a title block
\[la]#title-block\[ra] the front matter is already open. Closing the
front matter can only be done by starting the middle matter with \fB\fC{mainmatter}\fR. Any open
"matters" are closed when the document ends. \fIArea\fP defaults to "Internet" and \fIIpr\fP defaults to
\fB\fCtrust200902\fR.
Not giving a date will output \fB\fC<date/>\fR which mean the current date will be applied \fIwhen
xml2rfc is run\fP.
.TP
Abstract:
The abstract can be started by using the special header syntax \fB\fC.# Abstract\fR
.TP
Note:
Any special header that is not "abstract" or "preface" will be a
note
\[la]https://tools.ietf.org/html/rfc7749#section-2.24\[ra]: a numberless section.
These notes are only allowed in the \fB\fC<front>\fR section of the document.
Note [sic] that notes can only contain \fB\fC<t>\fR and not other block level elements,
Mmark will filter these out for: \fB\fCblockquote\fR currently (2020 September).
.TP
BCP 14/RFC 2119 Keywords:
If an RFC 2119 word is found enclosed in \fB\fC**\fR it will be rendered
as an \fB\fC<bcp14>\fR element: i.e. \fB\fC**MUST**\fR becomes \fB\fC<bcp14>MUST</bcp14>\fR.
.TP
Artwork:
Artwork is added by using a (fenced) code block. If the code block has an caption it will be
wrapped in a \fB\fC<figure>\fR, this is true for source code as well.
.TP
Source code:
If you want to typeset a source code instead of an artwork you must specify a language to the
fenced block:
.PP
.RS
.nf
``` go
println(hello)
````
.fi
.RE
Will be typesets as source code with the language set to \fB\fCgo\fR.
.TP
Block Level Attributes:
We use the attributes as specified in RFC 7991, e.g. to specify an empty list style use:
\fB\fC{empty="true"}\fR before the list. The renderer for this output format filters unknown attributes
away.
.TP
Footnotes:
Are discarded from the final output, don't use them.
.TP
Images:
Images are supported. We convert this to an \fB\fC<artwork>\fR with \fB\fCsrc\fR set to the image URL of path.
I.e. \fB\fC\fR becomes \fB\fC<artwork src="img.svg" type="svg" name="title"/>\fR.
Note the first \fB\fCsvg\fR (the alt text) is used as the \fB\fCtype=\fR attribute. Also note that an image
like this will be wrapped in \fB\fC<t>\fR which is not allowed in RFC 7991 syntax. So to make this
fully work you need to the image in a subfigure: \fB\fC!---\fR. See Images in Mmark
\[la]/syntax/images\[ra]
for more details.
.TP
Comments:
HTML Comments are detected and discarded. These can be useful to make the parser parse certain
constructs as a block element without meddling with the output.
.TP
HTML:
The \fB\fC<br>\fR tag is detected and converted into a hard break.
.TP
Unicode:
Just type the Unicode characters, the renderer takes care of putting these in between \fB\fC<u>\fR tags.
.SS "HTML5 OUTPUT"
.TP
Title Block:
From the title block only the title is used, in the \fB\fC<title>\fR tag.
.SS "MANUAL PAGE OUTPUT"
.TP
Title Block:
The title block needs a few elements to correctly generate a manual page
.RS
.IP \(bu 4
\fB\fCtitle\fR, title needs to \fIend in a digit\fP to signal the \fIsection\fP, defaults to "1" if nothing is
found.
.IP \(bu 4
\fB\fCarea\fR, what is it, e.g. "User Commands".
.IP \(bu 4
\fB\fCworkgroup\fR, who wrote this e.g. "Mmark Markdown".
.IP \(bu 4
\fB\fCdate\fR, date of the man page, optional, defaults to "today".
.IP \(bu 4
\fB\fCauthor\fR, to add an Authors section at the end.
.RE
.TP
Images:
See Images in Mmark
\[la]/syntax/images\[ra] for details, \fB\fCascii-art\fR images from a sub\-figure are
included.
.TP
References and citations:
Supported, a "Bibliography" section is added. Note that unlike XML2RFC, references for IDs and
RFCs \fIare not\fP automatically added.
.TP
Code Block:
Tabs are converted into four spaces.
.SH "BLOCK ELEMENTS"
.SS "TITLE BLOCK"
.PP
A Title Block contains a document's meta data; title, authors, date and other elements. The elements
that can be specified are copied from the xml2rfc v3
standard
\[la]https://tools.ietf.org/html/rfc7991\[ra]. More on these below. The complete title block is
specified in TOML
\[la]https://github.com/toml-lang/toml\[ra]. Examples title blocks can be found in the
repository of Mmark
\[la]https://github.com/mmarkdown/mmark/tree/master/rfc\[ra].
.PP
The title block itself needs three or more \fB\fC%\fR's at the start and end of the block. A minimal title
block would look like this:
.PP
.RS
.nf
%%%
title = "Foo Bar"
%%%
.fi
.RE
.SS "ELEMENTS OF THE TITLE BLOCK"
.PP
An I\-D needs to have a Title Block with the following items filled out:
.IP \(bu 4
\fB\fCtitle\fR \- the main title of the document.
.IP \(bu 4
\fB\fCabbrev\fR \- abbreviation of the title.
.IP \(bu 4
\fB\fCupdates/obsoletes\fR \- array of integers.
.IP \(bu 4
\fB\fCseriesInfo\fR, containing:
.RS
.IP \(en 4
\fB\fCname\fR \- \fB\fCRFC\fR, \fB\fCInternet-Draft\fR, \fB\fCDOI\fR, or \fB\fCFYI\fR.
.IP \(en 4
\fB\fCvalue\fR \- draft name or RFC number
.IP \(en 4
\fB\fCstream\fR \- \fB\fCIETF\fR (default), \fB\fCIAB\fR, \fB\fCIRTF\fR or \fB\fCindependent\fR.
.IP \(en 4
\fB\fCstatus\fR \- \fB\fCstandard\fR, \fB\fCinformational\fR, \fB\fCexperimental\fR, \fB\fCbcp\fR, \fB\fChistoric\fR, or \fB\fCfull-standard\fR.
.RE
.IP \(bu 4
\fB\fCipr\fR \- usually just set \fB\fCtrust200902\fR.
.IP \(bu 4
\fB\fCarea\fR \- usually just \fB\fCInternet\fR.
.IP \(bu 4
\fB\fCworkgroup\fR \- the workgroup the document is created for.
.IP \(bu 4
\fB\fCkeyword\fR \- array with keywords (optional).
.IP \(bu 4
\fB\fCauthor(s)\fR \- define all the authors.
.IP \(bu 4
\fB\fCcontact(s)\fR \- define all the contacts.
.IP \(bu 4
\fB\fCdate\fR \- the date for this I\-D/RFC.
.IP \(bu 4
\fB\fClanguage\fR \- the language for this document, this uses localized names for \fB\fCIndex\fR, \fB\fCFootnotes\fR
and \fB\fCReferences\fR, etc. Valid values are from BCP47
\[la]https://tools.ietf.org/html/bcp47\[ra]. This
defaults to \fB\fCen\fR (English). See the current
list
\[la]https://github.com/mmarkdown/mmark/blob/master/lang/lang.go\[ra].
.IP \(bu 4
\fB\fCindexInclude\fR \- set to true when you want to include an index (defaults to true).
.PP
For a manual page the \fB\fCtitle\fR, \fB\fCarea\fR and \fB\fCworkgroup\fR are mandatory, if \fB\fCdate\fR is not specified,
"today" is assumed.
.PP
An example would be:
.PP
.RS
.nf
%%%
title = "Using Mmark to create I\-Ds and RFCs"
abbrev = "mmark2rfc"
updates = [1925, 7511]
ipr= "trust200902"
area = "Internet"
workgroup = ""
keyword = ["markdown", "xml", "mmark"]
[seriesInfo]
status = "informational"
name = "Internet\-Draft"
value = "draft\-gieben\-mmark2rfc\-00"
stream = "IETF"
date = 2014\-12\-10T00:00:00Z
[[author]]
initials="R."
surname="Gieben"
fullname="R. (Miek) Gieben"
organization = "Mmark"
[author.address]
email = "miek@miek.nl"
emails = ["another@example.org"] # for when you need to speficy more than 1 email address
%%%
.fi
.RE
.PP
An \fB\fC#\fR acts as a comment in this block. TOML itself is specified here
\[la]https://github.com/toml-lang/toml\[ra].
.PP
If you want to define a \fB\fCcontact\fR do the following:
.PP
.RS
.nf
[[contact]]
initials="R.."
surname="Gieben"
fullname="R. (Miek) Gieben"
[contact.address]
email = "miek@miek.nl
.fi
.RE
.PP
You can then \fIreference\fP this contact using a \fIcitation\fP via the \fB\fCfullname\fR: \fB\fC[@R. (Miek) Gieben]\fR.
This also works when referencing an author of the I\-D. Note just like authors, defining contacts
needs to happen in the titleblock.
.PP
To renders contacts just like the authors are rendered, they need to be a put directly after opening
a new section in the \fIfirst\fP paragraph:
.PP
.RS
.nf
# Acknowledgements
[@R. (Miek) Gieben] [@More Folk]
Miek wrote ..., While More wrote ..
.fi
.RE
.SS "SPECIAL SECTIONS"
.PP
Any section that needs special handling, like an abstract or preface can be started with \fB\fC.#
Heading\fR. This creates a special section that is usually unnumbered.
.SS "INCLUDING FILES"
.PP
Including other files can done be with \fB\fC{{filename}}\fR, if the path of \fB\fCfilename\fR is \fInot\fP absolute,
the filename is taken relative to \fIcurrent file being processed\fP. With \fB\fC<{{filename}}\fR
you include a file as a code block. The main difference being it will be returned as a code
block. The file's extension \fIwill be used\fP as the language. The syntax is:
.PP
.RS
.nf
{{pathname}}[address]
.fi
.RE
.PP
And address can be \fB\fCN,M\fR, where \fB\fCN\fR and \fB\fCM\fR are line numbers. If \fB\fCM\fR is not specified, i.e. \fB\fCN,\fR it
is taken that we should include the entire file starting from \fB\fCN\fR.
.PP
Or you can use regular expression with: \fB\fC/N/,/M/\fR, where \fB\fCN\fR and \fB\fCM\fR are regular expressions that
specify from where to where to include lines from file.
.PP
Each of these can have an optional \fB\fCprefix=""\fR specifier.
.PP
.RS
.nf
{{filename}}[3,5]
.fi
.RE
.PP
Only includes the lines 3 to (\fInot\fP inclusive) 5 into the current document.
.PP
.RS
.nf
{{filename}}[3,5;prefix="C: "]
.fi
.RE
.PP
will include the same lines \fIand\fP prefix each include line with \fB\fCC:\fR.
.PP
Captioning works as well:
.PP
.RS
.nf
<{{test.go}}[/START/,/END/]
Figure: A sample function.
.fi
.RE
.PP
Note that because the extension of the file above is "go", this include will lead to the following
block being parsed:
.PP
.RS
.nf
~~~ go
// test.go data
~~~
Figure: A sample function.
.fi
.RE
.SS "DOCUMENT DIVISIONS"
.PP
Mmark support three document divisions, front matter, main matter and the back matter. Mmark
automatically starts the front matter for you \fIif\fP the document has a title block. Switching
divisions can be done with \fB\fC{frontmatter}\fR, \fB\fC{mainmatter}\fR and \fB\fC{backmatter}\fR. This must be the only
thing on the line.
.PP
Note if there isn't a \fB\fC{backmatter}\fR the bibliography will not be inserted.
.SS "CAPTIONS"
.PP
Mmark supports caption below tables
\[la]#tables\[ra], code blocks
\[la]#code-blocks\[ra] and block
quotes
\[la]#block-quotes\[ra]. You can caption each elements with \fB\fCTable:\fR, \fB\fCFigure:\fR and \fB\fCQuote:\fR
respectively. The caption extends to the first \fIempty\fP line. Some examples:
.PP
.RS
.nf
Name | Age
\-\-\-\-\-\-\-\-|\-\-\-\-\-:
Bob | 27
Alice | 23
Table: This is the table caption.
.fi
.RE
.PP
Or for a code block:
.PP
.RS
.nf
~~~ go
func getTrue() bool {
return true
}
~~~
Figure: This is a caption for a code block.
.fi
.RE
.PP
And for a quote:
.PP
.RS
.nf
> Ability is nothing without opportunity.
Quote: https://example.com, Napoleon Bonaparte
.fi
.RE
.PP
A caption can potentially contain a "heading ID": \fB\fC{#id}\fR as the \fIlast\fP text in the caption. If this
is found that ID is used as the ID for the entire figure:
.PP
.RS
.nf
Name | Age
\-\-\-\-\-\-\-\-|\-\-\-\-\-:
Bob | 27
Alice | 23
Table: This is the table caption. {#ages}
.fi
.RE
.PP
Colspan is also supported, just repeat the pipe symbol after the cell:
.PP
.RS
.nf
Name | Age
\-\-\-\-\-\-\-\-|\-\-\-\-\-
Bob ||
Alice | 23
.fi
.RE
.SS "ASIDES"
.PP
Any text prefixed with \fB\fCA>\fR will become an
aside
\[la]https://developer.mozilla.org/en/docs/Web/HTML/Element/aside\[ra]. This is similar to a block
quote, but can be styled differently.
.SS "FIGURES AND SUBFIGURES"
.PP
To \fIgroup\fP artworks and code blocks into figures, we need an extra syntax element. Scholarly
markdown
\[la]http://scholarlymarkdown.com/Scholarly-Markdown-Guide.html\[ra] has a neat syntax for this. It uses a special section syntax and all images in that
section become subfigures of a larger figure. Disadvantage of this syntax is that it can not be used
in lists. We use a fenced code block like syntax: \fB\fC!---\fR as the opening and closing "tag".
Note: only inline elements are parsed inside a figure block.
.PP
Basic usage:
.PP
.RS
.nf
!\-\-\-
!\-\-\-
.fi
.RE
.PP
if the figure block has a caption that will be used as well:
.PP
.RS
.nf
!\-\-\-
!\-\-\-
Figure: this is a figure containing subfigures.
.fi
.RE
.PP
Or when just using fenced code blocks:
.PP
.RS
.nf
!\-\-\-
~~~ ascii\-art
+\-\-\-\-\-+
| ART |
+\-\-\-\-\-+
~~~
Figure: Caption for this ascii\-art
~~~ c
printf("%s\\n", "hello");
~~~
!\-\-\-
Figure: Caption for both figures.
.fi
.RE
.SS "BLOCK LEVEL ATTRIBUTES"
.PP
A "Block Level Attribute" is a list of HTML attributes between braces: \fB\fC{...}\fR. It allows you to
set classes, an anchor and other types of \fIextra\fP information for the next block level element.
.PP
The full syntax is: \fB\fC{#id .class key="value"}\fR. Values may be omitted, i.e., just \fB\fC{.class}\fR is
valid.
.PP
The following example applies the attributes: \fB\fCtitle\fR and \fB\fCanchor\fR to the blockquote:
.PP
.RS
.nf
{title="The blockquote" #myid}
> A blockquote with a title
.fi
.RE
.PP
Gets expanded into:
.PP
.RS
.nf
<blockquote anchor="myid" title="The blockquote">
<t>A blockquote with a title</t>
</blockquote>
.fi
.RE
.SS "PARAGRAPHS"
.PP
Text that is separated from the rest of the content with empty lines.
.SS "TABLES"
.PP
Tables can be entered by using a simple syntax:
.PP
.RS
.nf
Name | Age
\-\-\-\-\-\-\-\-|\-\-\-\-\-\-
Bob | 27
Alice | 23
.fi
.RE
.PP
Table footers are supported as well and can be added with equal signs (=):
.PP
.RS
.nf
Name | Age
\-\-\-\-\-\-\-\-|\-\-\-\-\-\-
Bob | 27
Alice | 23
========|======
Total | 50
.fi
.RE
.PP
The pipe symbol (\fB\fC|\fR) to mark columns does not need to be aligned. Each row must be on a single
line.
.PP
Headerless tables are also supported, just leave of the first line.
.SS "LISTS"
.PP
Lists are the normal markdown lists, but we track how they are typeset, for ordered list the
delimiter can be either \fB\fC.\fR or \fB\fC)\fR. When a parenthesis is used the \fB\fCtype\fR is set to \fB\fC%d)\fR. Note that
any block level attributes take precedence.
.PP
Newlines between list items will create a non\-compact list, i.e. compare:
.PP
.RS
.nf
1. Item
2. Item
.fi
.RE
.PP
with:
.PP
.RS
.nf
1. Item
2. Item
.fi
.RE
.PP
This is true for all types of lists.
.SH "INLINE ELEMENTS"
.SS "INDICES"
.PP
Defining indices allows you to create an index. The define an index use the \fB\fC(!item)\fR. Sub items can
be added as well, with \fB\fC(!item, subitem)\fR. To make \fB\fCitem\fR primary, use another \fB\fC!\fR: \fB\fC(!!item,
subitem)\fR. If any index is defined the end of the document contains the list of indices. The
\fB\fC-index=false\fR flag suppresses this generation.
.PP
An index may apply to an \fIentire\fP section. This can be entered (just like contacts) by having an
index (or multiple), and just the index, to be the first paragraph after a new section.
.SS "CITATIONS"
.PP
Mmark uses the citation syntax from Pandoc: \fB\fC[@RFC2535]\fR, the citation can either be informative
(default) or normative, this can be indicated by using the \fB\fC?\fR or \fB\fC!\fR modifier: \fB\fC[@!RFC2535]\fR create
a normative reference for RFC 2535. To suppress a citation use \fB\fC[@-RFC1000]\fR. It will still add the
citation to the references, but does not show up in the document as a citation.
.PP
The first seen modifier determines the type (suppressed, normative or informative). Multiple
citation can separated with a semicolon: \fB\fC[@RFC1034;@RFC1035]\fR.
.PP
If you reference an RFC, I\-D or W3C document the reference will be added automatically (no need to
muck about with an \fB\fC<reference>\fR block). This is to say:
.PP
Any reference starting with \fIRFC\fP, \fII\-D.\fP or \fIW3C.\fP will be automatically added to the correct
reference section.
.PP
For I\-Ds you may want to add a draft sequence number, which can be done as such: \fB\fC[@?I-D.blah#06]\fR.
If you reference an I\-D \fIwithout\fP a sequence number it will create a reference to the \fIlast\fP I\-D in
citation index. I.e. a draft named "draft\-gieben\-pandoc2rfc", the I\-D reference becomes:
\fB\fCI-D.gieben-pandoc2rfc\fR. Referencing multiple versions of the same I\-D in a document will lead to
validation errors when running xml2rfc.
.PP
A bibliography section is created by default if a \fB\fC{backmatter}\fR is given, but you can suppress it
by using the command line flag \fB\fC-bibliography=false\fR. No \fB\fC{backmatter}\fR, no bibliography.
.PP
A non\-suppressed reference to the \fIfull name\fP of an author or contact will insert the referenced
person as a \fB\fCcontact\fR. See https://www.rfc\-editor.org/materials/FAQ\-xml2rfcv3.html#section\-5.4
\[la]https://www.rfc-editor.org/materials/FAQ-xml2rfcv3.html#section-5.4\[ra].
.SS "REFERENCE TEXT SUFFICES"
.PP
You can specify extra text after the citation using a comma: \fB\fC[@RFC2535, section 5]\fR, see
https://www.rfc\-editor.org/materials/FAQ\-xml2rfcv3.html#name\-how\-do\-i\-link\-to\-multiple\-se
\[la]https://www.rfc-editor.org/materials/FAQ-xml2rfcv3.html#name-how-do-i-link-to-multiple-se\[ra].
This is used in the following manner:
.IP \(bu 4
\fB\fC[@RFC2535, section 5]\fR \-> sectionFormat="of"
.IP \(bu 4
\fB\fC[@RFC2525, see, section 5]\fR \-> sectionFormat="comma"
.IP \(bu 4
\fB\fC[@RFC2525, (see) section 5]\fR \-> sectionFormat="parens"
.IP \(bu 4
\fB\fC[@RFC2525, 5]\fR \-> sectionFormat="bare"
.PP
\fB\fCpage\fR, \fB\fCparagraph\fR, etc., might be supported in the future if these pop up in XML2RFC. Translation
of these strings \fIis\fP supported for a few languages, \fB\fCzie, sectie 5\fR (Dutch) is supported for
instance.
.PP
Also note these strings need to be literary typed as shown here (we may become more lenient in the
future).
.SS "XML REFERENCES"
.PP
Any valid XML reference fragment found anywhere in the document, can be used as a citation reference.
The syntax of the XML reference element is defined in RFC
7749
\[la]https://tools.ietf.org/html/rfc7749#section-2.30\[ra]. The \fB\fCanchor\fR defined can be used in the
citation
\[la]#Citations\[ra], which the example below that would be \fB\fC[@pandoc]\fR:
.PP
.RS
.nf
<reference anchor='pandoc' target='http://johnmacfarlane.net/pandoc/'>
<front>
<title>Pandoc, a universal document converter</title>
<author initials='J.' surname='MacFarlane' fullname='John MacFarlane'>
<organization>University of California, Berkeley</organization>
<address>
<email>jgm@berkeley.edu</email>
<uri>http://johnmacfarlane.net/</uri>
</address>
</author>
<date year='2006'/>
</front>
</reference>
.fi
.RE
.PP
Note that for citing I\-Ds and RFCs you \fIdon't\fP need to include any XML, as Mmark will pull these
automatically from their online location: or technically more correct: the xml2rfc post processor
will do this.
.PP
The newer \fB\fCreferencegroup\fR is also supported. No attempt to parse it is made, it's detected and
included in the bibliography.
.SS "CROSS REFERENCES"
.PP
Cross references can use the syntax \fB\fC[](#id)\fR, but usually the need for the title within the
brackets is not needed, so Mmark has the shorter syntax \fB\fC(#id)\fR to cross reference in the document.
.PP
Example:
.PP
.RS
.nf
My header {#header}
Lorem ipsum dolor sit amet, at ultricies ...
See Section (#header).
.fi
.RE
.PP
Using Block Level Attributes this also works for tables and figures (including artwork):
.PP
.RS
.nf
{id="myid"}
\-\-\-|\-\-\-
a | b
d | d
.fi
.RE
.PP
or
.PP