Skip to content

Commit 1a0751b

Browse files
chrisfennerchrisfenner
committed
explicitly support and give examples for multiline and pipe tables
1 parent 7325bae commit 1a0751b

File tree

2 files changed

+147
-26
lines changed

2 files changed

+147
-26
lines changed

‎build.sh

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -300,7 +300,7 @@ if [ -n "${pdf_output}" ]; then
300300
--metadata=date:"${DATE}" \
301301
--metadata=date-english:"${DATE_ENGLISH}" \
302302
--metadata=year:"${YEAR}" \
303-
--from=markdown+implicit_figures+grid_tables+table_captions-markdown_in_html_blocks \
303+
--from=markdown+implicit_figures+multiline_tables+grid_tables+table_captions-markdown_in_html_blocks \
304304
"${build_dir}/${input_file}" \
305305
--to=markdown \
306306
| pandoc \
@@ -323,7 +323,7 @@ if [ -n "${pdf_output}" ]; then
323323
--metadata=titlepage-rule-height:0 \
324324
--metadata=colorlinks:true \
325325
--metadata=contact:[email protected] \
326-
--from=markdown+implicit_figures+grid_tables+table_captions-markdown_in_html_blocks \
326+
--from=markdown+implicit_figures+multiline_tables+grid_tables+table_captions-markdown_in_html_blocks \
327327
${extra_pandoc_options} \
328328
--to=pdf \
329329
--output="${pdf_output}"
@@ -369,7 +369,7 @@ if [ -n "${latex_output}" ]; then
369369
--metadata=titlepage-rule-height:0 \
370370
--metadata=colorlinks:true \
371371
--metadata=contact:[email protected] \
372-
--from=markdown+implicit_figures+grid_tables+table_captions-markdown_in_html_blocks \
372+
--from=markdown+implicit_figures+multiline_tables+grid_tables+table_captions-markdown_in_html_blocks \
373373
${extra_pandoc_options} \
374374
--to=latex \
375375
--output="${latex_output}"
@@ -392,7 +392,7 @@ if [ -n "${docx_output}" ]; then
392392
--metadata=date:"${DATE}" \
393393
--metadata=date-english:"${DATE_ENGLISH}" \
394394
--metadata=year:"${YEAR}" \
395-
--from=markdown+implicit_figures+grid_tables+table_captions-markdown_in_html_blocks \
395+
--from=markdown+implicit_figures+multiline_tables+grid_tables+table_captions-markdown_in_html_blocks \
396396
"${build_dir}/${input_file}" \
397397
--to=markdown \
398398
| pandoc \
@@ -404,7 +404,7 @@ if [ -n "${docx_output}" ]; then
404404
--filter=pandoc-crossref \
405405
--resource-path=.:/resources \
406406
--data-dir=/resources \
407-
--from=markdown+implicit_figures+grid_tables+table_captions-markdown_in_html_blocks \
407+
--from=markdown+implicit_figures+multiline_tables+grid_tables+table_captions-markdown_in_html_blocks \
408408
--reference-doc=/resources/templates/tcg_template.docx \
409409
${extra_pandoc_options} \
410410
--to=docx \
@@ -430,7 +430,7 @@ if [ -n "${html_output}" ]; then
430430
--metadata=date:"${DATE}" \
431431
--metadata=date-english:"${DATE_ENGLISH}" \
432432
--metadata=year:"${YEAR}" \
433-
--from=markdown+implicit_figures+grid_tables+table_captions-markdown_in_html_blocks \
433+
--from=markdown+implicit_figures+multiline_tables+grid_tables+table_captions-markdown_in_html_blocks \
434434
"${build_dir}/${input_file}" \
435435
--to=markdown \
436436
| pandoc \
@@ -456,7 +456,7 @@ if [ -n "${html_output}" ]; then
456456
--metadata=titlepage-rule-height:0 \
457457
--metadata=colorlinks:true \
458458
--metadata=contact:[email protected] \
459-
--from=markdown+implicit_figures+grid_tables+table_captions-markdown_in_html_blocks \
459+
--from=markdown+implicit_figures+multiline_tables+grid_tables+table_captions-markdown_in_html_blocks \
460460
${extra_pandoc_options} \
461461
--to=html \
462462
--output="${html_output}"

‎guide.md

Lines changed: 140 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -612,10 +612,14 @@ graph TD;
612612

613613
# Tables {#sec:tables}
614614

615-
We support two notation styles for tables: Markdown and HTML.
615+
We support several notation styles for tables.
616616

617617
## Markdown Tables
618618

619+
There are several ways to write a table in Markdown.
620+
621+
### Simple Markdown Tables {#sec:simple-markdown-tables}
622+
619623
Small, simple tables like @tbl:shapes are easier to read in raw Markdown form in the following style:
620624

621625
```md
@@ -636,69 +640,186 @@ Table: Shapes {#tbl:shapes}
636640
| Triangle | 3 |
637641
| Möbius strip | 1 |
638642

643+
Note the table caption and cross-reference in curly braces above the table.
639644

645+
### Multiline Markdown Tables {#sec:multiline-markdown-tables}
640646

641-
Note the table caption and cross-reference in curly braces above the table.
647+
Sometimes, you may need to write a lot of Markdown content in the cell of a table,
648+
and this content may need multiple lines in your editor.
642649

643-
## HTML Tables
650+
```md
651+
Table: Table Types {#tbl:table-types}
652+
653+
-------------------------------------------------------------------------------
654+
**Table Kind** **Easy?** **Recommended?** **References**
655+
--------------- ----------- ------------------- -------------------------------
656+
Simple Yes When each cell @sec:simple-markdown-tables,
657+
Markdown is about one @tbl:shapes
658+
Tables word or so.
659+
660+
Multiline Yes When you have @sec:multiline-markdown-tables,
661+
Markdown content that's @tbl:table-types
662+
Tables more than a few
663+
words.
664+
665+
Grid Markdown No When you have @sec:grid-tables,
666+
Tables row or column @tbl:fruits-grid
667+
spans and need
668+
full Markdown
669+
support (e.g.,
670+
crossrefs or
671+
equations).
672+
673+
HTML Yes When you have @sec:html-tables,
674+
Tables row or column @tbl:fruits-html
675+
spans, and
676+
don't need
677+
full Markdown
678+
or don't mind
679+
doing all the
680+
styling in
681+
HTML.
682+
-------------------------------------------------------------------------------
683+
```
684+
685+
Table: Table Types {#tbl:table-types}
686+
687+
-------------------------------------------------------------------------------
688+
**Table Kind** **Easy?** **Recommended?** **References**
689+
--------------- ----------- ------------------- -------------------------------
690+
Simple Yes When each cell @sec:simple-markdown-tables,
691+
Markdown is about one @tbl:shapes
692+
Tables word or so.
693+
694+
Multiline Yes When you have @sec:multiline-markdown-tables,
695+
Markdown content that's @tbl:table-types
696+
Tables more than a few
697+
words.
698+
699+
Grid Markdown No When you have @sec:grid-tables,
700+
Tables row or column @tbl:fruits-grid
701+
spans and need
702+
full Markdown
703+
support (e.g.,
704+
crossrefs or
705+
equations).
706+
707+
HTML Yes When you have @sec:html-tables,
708+
Tables row or column @tbl:fruits-html
709+
spans, and
710+
don't need
711+
full Markdown
712+
or don't mind
713+
doing all the
714+
styling in
715+
HTML.
716+
-------------------------------------------------------------------------------
717+
718+
### Grid Tables {#sec:grid-tables}
719+
720+
You may have some data that needs to be presented in a table that allows you
721+
to make cells span rows or columns. Grid tables like @tbl:fruits-grid can be
722+
used for this. Note that editing these tables requires a bit more typing. It's
723+
recommended to use these only when you need row and column spanning.
724+
725+
Some tools provide assistance for generating tables of this type. If you find
726+
a tool that is handy for editing Markdown grid-style tables, please send a PR
727+
to github.com/trustedcomputinggroup/pandoc!
644728

645-
For larger, or more complex tables like @tbl:fruits, it may be preferable to use HTML. If you want to make
646-
table cells span rows or columns, this is the only way to do it.
729+
```md
730+
Table: Fruits (Pipe) {#tbl:fruits-grid}
731+
732+
+----------------------+----------------------------+
733+
| **Color and Fruit** | **Mistaken for Vegetable** |
734+
+=============+========+============================+
735+
| | Red | No |
736+
| Apple +--------+----------------------------+
737+
| | Green | No |
738+
+-------------+--------+----------------------------+
739+
| Tomato | Red | Yes |
740+
+-------------+--------+----------------------------+
741+
| Banana | Yellow | No |
742+
+-------------+--------+----------------------------+
743+
```
744+
745+
Table: Fruits (Pipe) {#tbl:fruits-grid}
746+
747+
+----------------------+----------------------------+
748+
| **Color and Fruit** | **Mistaken for Vegetable** |
749+
+=============+========+============================+
750+
| | Red | No |
751+
| Apple +--------+----------------------------+
752+
| | Green | No |
753+
+-------------+--------+----------------------------+
754+
| Tomato | Red | Yes |
755+
+-------------+--------+----------------------------+
756+
| Banana | Yellow | No |
757+
+-------------+--------+----------------------------+
758+
759+
760+
## HTML Tables {#sec:html-tables}
761+
762+
A rowspan/colspan table like @tbl:fruits-pipe can be implemented in HTML like
763+
the below. Note that this is a little easier to type, and a little harder to
764+
read in plain-text form. We recommend preferring [grid tables](#sec:grid-tables)
765+
to HTML tables, but HTML tables can be fine in certain situations (for example,
766+
a gradual migration away from a Word document using Pandoc, which typically
767+
converts Word tables into HTML).
647768

648769
```md
649-
<table id="tbl:fruits">
650-
<caption>Fruits</caption>
770+
<table id="tbl:fruits-html">
771+
<caption>Fruits (HTML)</caption>
651772
<tr>
652-
<th colspan="2">Color and Fruit</th>
653-
<th>Mistaken for Vegetable</th>
773+
<th colspan="2"><strong>Color and Fruit</strong></th>
774+
<th><strong>Mistaken for Vegetable</strong></th>
654775
</tr>
655776
<tr>
656-
<td>Red</td>
657777
<td rowspan="2">Apple</td>
778+
<td>Red</td>
658779
<td>No</td>
659780
</tr>
660781
<tr>
661782
<td>Green</td>
662783
<td>No</td>
663784
</tr>
664785
<tr>
665-
<td>Red</td>
666786
<td>Tomato</td>
787+
<td>Red</td>
667788
<td>Yes</td>
668789
</tr>
669790
<tr>
670-
<td>Yellow</td>
671791
<td>Banana</td>
792+
<td>Yellow</td>
672793
<td>No</td>
673794
</tr>
674795
</table>
675796
```
676797

677798
The above HTML table becomes the below:
678799

679-
<table id="tbl:fruits">
680-
<caption>Fruits</caption>
800+
<table id="tbl:fruits-html">
801+
<caption>Fruits (HTML)</caption>
681802
<tr>
682-
<th colspan="2">Color and Fruit</th>
683-
<th>Mistaken for Vegetable</th>
803+
<th colspan="2"><strong>Color and Fruit</strong></th>
804+
<th><strong>Mistaken for Vegetable</strong></th>
684805
</tr>
685806
<tr>
686-
<td>Red</td>
687807
<td rowspan="2">Apple</td>
808+
<td>Red</td>
688809
<td>No</td>
689810
</tr>
690811
<tr>
691812
<td>Green</td>
692813
<td>No</td>
693814
</tr>
694815
<tr>
695-
<td>Red</td>
696816
<td>Tomato</td>
817+
<td>Red</td>
697818
<td>Yes</td>
698819
</tr>
699820
<tr>
700-
<td>Yellow</td>
701821
<td>Banana</td>
822+
<td>Yellow</td>
702823
<td>No</td>
703824
</tr>
704825
</table>

0 commit comments

Comments
 (0)