A few years ago, I redid most illustrations and included them in the docs as SVG files. The primary driver was switching from PNG to SVG to better accommodate hi-dpi displays. I also committed the source files. Unfortunately, they're in a proprietary format and cannot be reused without a Mac and an OmniGraffle licence.
(Before someone starts listing the arguments against proprietary formats — yes, I learnt them 15 years ago, and yes, I still chose OmniGraffle's UX over Inkscape's. : You're welcome to redo the diagrams with Inkscape and replace mine as long as the result doesn't look significantly worse.)
While not ideal, this got the job done. Diagrams look all right on all kind of devices.
To sum up:
- I think SVG should be the preferred format for illustrations in the docs
- I'm worried about ASCII art on small devices: line wrapping would be a problem
- whatever you want to make the diagram as long as it exports to SVG and looks reasonable
- commit the source file so someone has a chance to reuse them, regardless of their format
Personally I use plantuml to generate various diagrams. It is open source there even exists plugin for sphinx. It uses relatively understandable diagram language. Exports svg along the many other formats. And there are realtime preview plugins to most editors and ides.
Only big downside is that requires java runtime.
Curtis Maloney <[hidden email]> kirjoitti pe 30. marrask. 2018 klo 21.47:
On 11/30/18 7:38 PM, guettli wrote:
> I do not care for the strategy, I care for the goal.
> How to find clear consensus now?
There is a time honored practice in open source of spurring more
spirited discussion by presenting a solution, however sub-optimal it may be.
It may not be the accepted solution, but it's far more likely to get
people to give input than asking for discussion.
[No, I'm not just wrapping up "patches welcome" - this is a general
observation in life. It's just more openly recognised in OSS :) ]