Markdown tables
HM0880 opened this issue · comments
I am working through converting the table screenshots into Markdown tables. I have converted the Chapter 7 table [1]. The remaining chapters are Chapters 11, 12, 15, 16, 17, 18, 21, and 23.
I do not know how to handle the table caption. MarkedJS has table captions as an open feature request [2]. Let me know how table captions for PAIP should be done, and I will update my edits before submitting a pull request.
Hmm, looks like this is an open and unanswered question! I think I'd put the caption as free text under the table, maybe with a leading "Table: ".
It looks like Github isn't rendering the table right now, missing the header row - adding an empty row like | | | appears to help. Adding that sort of empty row also might render better than the rows of |---|.
Sorry that you're stumbling on an unclear spot in Markdown parsers! Thanks for editing and the column alignment!
Happy to help! PAIP is a great book.
Updates:
-
The table rendering is fixed. I removed the dashes, tried blank rows, and finally chose no separation between the sections. See [1].
-
The print version of PAIP uses Figure for tables (e.g., "Figure 7.1: Glossary for the STUDENT program"), so I have kept the Figure label. Let me know if you want Table instead, and I will update.
-
I do not know how to handle the reference to the table. The previous reference was
[figure 7.1](#f0010)(see below), and the current version is at [2].
The program is summarized in [figure 7.1](#f0010).
| []() |
|----------------------------------------------|
|  |
| Figure 7.1: Glossary for the STUDENT Program |
[1] https://github.com/HM0880/paip-lisp/blob/main/docs/chapter7.md
[2] https://github.com/HM0880/paip-lisp/blob/main/docs/chapter7.md?plain=1#L118
#f0010 isn't great; other chapters have that, and that might confuse things in Pandoc, which concatenates all the chapters in its workflow. How about #figure-07-1? Mimicking the links for footnotes, something like:
The program is summarized in [figure 7.1](#figure-07-1).
<a id="figure-07-1"></a>
[table]
Figure 7.1: Glossary for the STUDENT Program
Though if you opted to skip the link because it's right there, it's understandable.
I've found that markdown rendering for tables on github has been problematic. I'm glad you are trying to sort this out. Thank you!
I have chosen to follow the PAIP book convention: do not reference "close" figures (i.e., figures 23.1 and 23.2) but do reference "far away" figures (i.e., figure 23.3). (I wrote this choice in HM0880@95da530)
I have a question about the screenshots of the tables: the screenshots are referenced in the PAIP-safari.md document [1] (e.g., line 5631 references figure 04-02 [2]). I have been deleting the screenshots as I update the tables. Should I keep the screenshots so that existing scripts for export to different formats still work?
[1] https://github.com/norvig/paip-lisp/blob/main/PAIP-safari.md
[2] https://github.com/norvig/paip-lisp/blob/main/docs/images/chapter4/f04-02.jpg
This reminds me that I should probably document how I go from the epub to the chapter markdown files, but not today...
For the purposes of review, I might hold off on deleting the table gifs, for a separate PR. If you've already deleted them, don't worry about it; I can compare to a local branch.
The chapter markdown files are where almost all editing happens; the book-long markdown file isn't kept in sync. When I've generated epub or pdf files, it was from the chapters. And when I replaced formulae with vector images, I deleted the old gifs; it makes it easier to skim pixelated images and see what could be redone and fixed up.
Have you had any issues with legibility on the scan?
For the purposes of review, I might hold off on deleting the table gifs, for a separate PR. If you've already deleted them, don't worry about it; I can compare to a local branch.
OK. I added the table images back to my repo to make the future merge request easier.
The chapter markdown files are where almost all editing happens; the book-long markdown file isn't kept in sync. When I've generated epub or pdf files, it was from the chapters. And when I replaced formulae with vector images, I deleted the old gifs; it makes it easier to skim pixelated images and see what could be redone and fixed up.
There are also some other images (e.g., [1]) that could be drawn with something like Mermaid [2]. Would redrawing these sorts of images be useful?
Have you had any issues with legibility on the scan?
No, the tables have been very legible. I also have a print copy of the book so I can compare against the printed version if needed.
EDIT: Figure 12.1 has a make-= in the "Auxiliary Functions" section, but the = is not readable at all.
[1] Chapter 2 tree image
[2] https://mermaid-js.github.io/mermaid/
There are also some other images (e.g., [1]) that could be drawn with something like Mermaid [2]. Would redrawing these sorts of images be useful?
It's a good idea! (And totally a separate branch, btw.) It's been somewhere on my todo list for ages. I could see using Mermaid or Graphviz for some figures, and perhaps draw.io diagrams.net for more general drawing.
(I have a lot of bookmarks and thoughts about diagrams, but I won't dump them all here.)
I like Graphviz for its longevity, but the dynamic scaling of images produced by a Javascript solution is appealing.
I created Issue #139 for more discussion.
I've been making lots of small edits, and that can tangle up PRs with merge conflicts, and that makes me want to aim at shorter-lived branches. Is there anything that would help with the effort for turning images into markdown tables?
Is there anything that would help with the effort for turning images into markdown tables?
My initial plan was to do a PR for all the tables at once, but I plan to do a PR now for the tables that I have completed to keep up-to-date with the repo.
Edit: Opened PR #148
I'm thinking about making new ebooks in a month or so. How's it going?
Hi @pronoiac, sorry for the delay. After mid-August, I would have more time to work on the tables.