becarpenter
Helping write the book
Hello Mr. Carpenter,
I would like to offer my assistance in writing this book. I am both an IPv6 nerd, and a LaTeX-diagramming nerd. I have two concrete ideas that I think I could help with:
- I could help automate the generation of the PDF, so that any time a commit is made, a fresh PDF is generated by GitHub Actions. That might make it easier to always have an up-to-date PDF for people to look at, and doesn't require you to manually build it.
- I could also help with generating diagrams, graphics, graphs, pretty tables and such. Perhaps that might be useful to you so that you can focus on the content. I can use the various diagramming packages that LaTeX offers to make pretty illustrations.
For example, the bytefield package should let us create some nice renderings of things like IPv6 package formats. Here's an example:
There are many more packages in LaTeX I enjoy working with that could give the book a consistent style.
If you think there is a utility in me making a run over the source and LaTeX-ify digagrams and such, I would be quite happy to do that. I figured I'd ask first if you think it's a good idea before I do it.
Cheers, Patrick
Hi Patrick. Thanks for the offer of help! First, I want my co-editor @buraglio to be aware of this thread. We haven't really announced it yet, but our plan is to drop PDF (and hopefully EPUB) builds of the book at https://ipv6textbook.com/. Did you already look at how we generate the PDF? If not, the summary is
- Munge all the individual .md files into a single file
- Make a LaTeX file using pandoc
- Make a PDF file using pdflatex
The gory details are at https://github.com/becarpenter/book6/blob/main/utilities/utDoc.md#bakebook and in the Python script https://github.com/becarpenter/book6/blob/main/utilities/bakeBook.py
I'm a Windows user but I think all of this should work on Linux too. I'm not sure if it will work on GitHub actions; and it might be a bit heavyweight to do it on every commit. Advice welcome.
As for better diagrams, yeah always a problem ;-). Could we integrate LaTeX-based diagrams into the orginal .md files? I don't want to add any manual processes.
Also any help on EPUB would be great. I used pandoc baked.tex -o baked.epub -V colorlinks=true --metadata title="book6" but results are not perfect.
Did a little work to improve alt text handling on images - not perfect, but at least the alt text will show up as a figure caption in future, which helps people using screen readers. https://github.com/becarpenter/book6/commit/bf9d6e84007c32aab59f63ae83e0bf12f0924430
Hey @becarpenter,
I had a look at your PDF release workflow, it looks sensible to me. I was able to get it running locally with minor fixes (it was looking for a title.md but the file is called Title.md, I think this is because Windows defaults to case-insensitive and Linux to case-sensitive).
Given that the whole compilation process takes about ~2s, I think this should easily be automatable with GitHub Actions, if you want to give that a try. I think the free minutes should be more that sufficient for it. If you don't have anything against it, I could make a PR for you to check it out. You could even use that to always have an up-to-date PDF link for the main website to point at.
As for the diagrams: yes, it should be possible to put the raw LaTeX code for them into the .md files and have pandoc pass them through. I will do some testing locally, and maybe send you a PR with one example so you can make sure it works on your end as well.
I have not played too much with generating EPUB files before, so there is a bit of a learning curve. I know that EPUB is a bit more limited, I think for figures we can really only use SVGs and rasterized images (not PostScript files that LaTeX prefers). If pandoc is smart, it should be able to do the right thing with the figures. If it is not, I'm sure there is some plugins to get it to do what we want, but I'd have to look into it a bit to make sure it looks right on both formats.
I fixed that case error at https://github.com/becarpenter/book6/commit/5378e77b079ce44ada2d07d557f781696b6f543d
Will get back to you on the other points.
I'd like to hear any comments from Nick @buraglio but we could certainly test with GitHub actions. I am a bit nervous because the bakeBook.py script is only one of the set of scripts. I don't think we'll hit dependencies but you never know until you try. I assume you've seen the writeup at https://github.com/becarpenter/book6/blob/main/utilities/utDoc.md
Yes, please send me an example of a LaTeX figure. I've only ever included existing graphics in LaTeX.
I use GitHub actions quite a bit for automating doc builds with Ietf drafts, I think this is a good idea to try.
On Wed, Aug 21, 2024 at 17:49 Brian E Carpenter @.***> wrote:
I'd like to hear any comments from Nick @buraglio https://github.com/buraglio but we could certainly test with GitHub actions. I am a bit nervous because the bakeBook.py script is only one of the set of scripts. I don't think we'll hit dependencies but you never know until you try. I assume you've seen the writeup at https://github.com/becarpenter/book6/blob/main/utilities/utDoc.md
Yes, please send me an example of a LaTeX figure. I've only ever included existing graphics in LaTeX.
— Reply to this email directly, view it on GitHub https://github.com/becarpenter/book6/issues/96#issuecomment-2303245674, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAHZT6W2PFVSZ5K62OEVMNDZSUKOVAVCNFSM6AAAAABMWJQF7SVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGMBTGI2DKNRXGQ . You are receiving this because you were mentioned.Message ID: @.***>
Hi,
As for better diagrams, yeah always a problem ;-). Could we integrate LaTeX-based diagrams into the orginal .md files? I don't want to add any manual processes.
Hijacking the thread here, but maybe instead of using LaTeX-based diagrams https://mermaid.js.org/ could be used. It's easy and integrates into markdown and Pandoc, you just add a source code block and "write" your diagram. There are examples for TCP/UDP headers in the documentation..
I planned on creating some or most of the headers in the next couple of weeks as I need them for my IPv6 slides and my Blog and put them up on GitLab (no IPv6 here).
Jens
I hit a problem with the mermaid diagrams and Pandoc, maybe I was missing something but I could only get consistent results by rendering them into png. (I wanted to use svg as preferred for RFCs, but that definitely would not work.) Also of course you can't do everything you might want to with mermaid, so we'll always need to accept png and jpg.
Right now @Spitfireap is working on a considerable improvement to our utilities which should get us into GitHub actions. Once that's done we can perhaps find some neat new tricks.
FYI: the topic is really how to apply GitHub Actions and it's still pending along with https://github.com/becarpenter/book6/pull/115