pandocs

pandocs copied to clipboard

Creating SVG diagrams and figures the way we are currently doing is tedious, requires hand-writing SVG/XML code and it's generally a very time consuming operation.

I do thing this harms the maintainability of those, I don't think it's realistic to ask people to learn how to do this for editing a single arrow or line in a diagram. This could lead to abandoned figures - as we are bottle necked by the contributors able to go through this process..

We still didn't find a single SVG editor able to export figures the way we need (set custom CSS classes, produce clean SVG code) so either :

• we find a way to add this functionality in an OSS tool,
• or we develop some kind of tool that helps converting tool-generated SVG code to manually editable one and the other way around, to aid this process.

There is a fundamental disagreement between our two goals here. (I am reminded of the talk "Cursed Problems In Game Design", as this is pretty much the same situation we're facing. Assuming the same applies, there is no solution to the problem, only workarounds.)

One goal is end user readability, mainly from theming (#322), consistent and clear lines, etc. The other goal is maintainer accessibility, which boils down to the ability to use a graphical SVG editor.

Where these two goals fundamentally clash is that the former requires our SVGs to integrate with the rest of the page, but SVG editors are all (as far as I'm aware, anyway) designed to produce stand-alone, i.e. self-contained, SVGs. Simply put, no editor works for our use case.

The choice I made in my commits so far has been to forgo the latter goal as being the lesser of the two evils. Here is my thought process:

• Pan Docs are primarily read more than they are edited. Therefore, I believe it makes more sense to prioritize the end result, as long as the added maintenance burden is within reason.
• Editing an SVG manually boils down to XML, which is very popular; also, the SVG format is well-documented, the MDN documentation being quite accessible. I thus believe that it's within reason to do so.
• As far as intuition goes, while e.g. coordinates are not immediately graphically visible, iteration is very quick thanks to mdbook serve, so it's close enough to WYSIWYG. In the absolute worst case, it's possible to brute-force a bit, though I haven't needed to do so.
• Additionally, it's possible to use the browser's inspector to check SVG elements as well, so it's not like one is editing blindly.
• I have had trouble using Inkscape to create a prototype of one of the diagrams I later hand-wrote, which leads me to believe that there will be a barrier of entry regardless.
• For Pan Docs diagrams, we haven't needed to use every single SVG feature available; if you look at the diagrams I've produced, they mostly reuse the same few building blocks.

Nonetheless, I recognize that what avivace brings up is a legitimate problem. While I don't think doing a 180 is a good idea, let me borrow from the GDC talk I linked to in the first paragraph and propose an improvement in the form of "s'mores": documenting the editing process.

• As I have edited SVGs, I have picked up a lot of small tricks to make editing faster, and caveats to avoid. If necessary, I can document those.
• The diagrams I wrote have been very lacking in comments. This is intentional, so as not to inflate the document size too much. However, I can instead add many more of those, and have our custom mdBook renderer strip comments from SVGs. Best of both worlds!