Illustrations

[Sean-Der]

• Front Cover
• Each Chapter Start

All technical diagrams are going to user mermaid.

[enobufs]

@Sean-Der Would that still be a plan in which the diagram we draw would be touched up by someone else? Mermaid is handy wherever it does good but not perfect. I am wondering if I can just insert photocopies of my quick drawing by hand, assuming that some illustrator would later make them look great?

[Sean-Der]

@enobufs I don't know how many illustrations we will be able to get unfortunately. The person who I originally talked with is busier then anticipated :( Maybe we can reach out to the Pion community?

The nice thing about mermaid is that is easy for others to edit and they are responsive at least!

[threeplanetssoftware]

One thing to consider for mermaid is that anyone viewing it on Github won't benefit from the diagram. I'm sure that is not a deal breaker since there are other differences as well, but something you may want to keep in mind.

Github:

Website:

One potential solution would be to have an images folder that has the underlying code to generate each of the diagrams, then you could generate each image from them and include the image itself in the markdown. You could potentially have a content/ diagrams folder that has the markup which generates each image and a content/images folder which has the generated images and any others that didn't come from mermaid. With that schema, there would be room to start with hand drawings of any image you want and then convert it to mermaid when someone has the time and inclination. But throughout it, both Github and the website might benefit.

[enobufs]

+1 for having a folder at ./content/images.
I am going to use image files for data channel sections. I talked to @Sean-Der a bit about it. We could put all image files flat under the folder just like markdown files in ./content/docs/. with the section number prefix (e.g. "06-")

Example:

{{< figure src="/images/06-sctp-inflight-queue-02.png">}}

We'd still have to depend on shortcodes Hugo and theme "Book" provide anyway. I'm ok with not being able to see Mermaid images directly on Github. hugo server command works great!

[Sean-Der]

I am 👍 with dropping mermaid completely. Both @enobufs and @threeplanetssoftware aren't fans, so I think we should go with the majority :)

For things generated with mermaid maybe we can leave them above the images (but commented out) so they are easy to change if needed!

[Sean-Der]

@threeplanetssoftware mind if I add you to the GitHub organization? I don't want to spam you. We would really love to have you involved long term. I know WebRTC, but it is becoming more obvious how much more help this book needs :)

[enobufs]

Mermaid is good (also other shortcodes) and I'd like to use them also. It's just that many of my diagrams can't be drawn with Mermaid. I'd use Mermaid where possible.

[threeplanetssoftware]

@threeplanetssoftware mind if I add you to the GitHub organization? I don't want to spam you.

I think I'd prefer to lurk and spot places I can help for now, since neither Hugo, nor WebRTC is something I have much experience with. I have the repo followed and that's not too spammy yet. I will let you know if I see room for a larger role.

[Sean-Der]

@threeplanetssoftware sounds good to me! Thank you so much for all the changes you have driven so far :)

[mogren]

Just to revive this discussion again. I agree that having images checked in is probably the way to go. I would be happy to try and convert some existing images and see what it looks like in all three formats we currently produce.

For pandoc, it seems like using Markdown to include them should just work to generate the PDF.

We could use something like https://app.diagrams.net to draw diagram, and also check in the original .drawio file to make it easy for anyone to edit them.

[ValarMarkhulis]

I have found an error in one of the illustrations in this repo, but I can't figure out how to edit the file without creating a new one from scratch. Found this issue, which verified that you don't have the images in an editable format on Github.

I can add to the discussion, that it is possible from https://app.diagrams.net/ or the desktop app to export an illustration as "filename.drawio.svg" or "filename.drawio.png", which makes it a picture.

But you can open it and continue editing it after the fact in diagrams.net and the app. Then you just version this file, which can also be referenced from markdown.

There is also an unofficial vs code extension, that integrates quite well.