5 ms·
Pikchr: A PIC-like markup language for diagrams in technical documentation
- junon 3y agoThis actually looks really nice. Good documentation from the looks of it too.
- otikik 3y agoMermaid [1] has been good enough for me for years. [1] https://mermaid.js.org/intro/ https://mermaid.js.org/intro/
- JTyQZSnP3cQGa8B 3y agoAnd before this, PlantUML was good enough too. It's always worth it to have alternatives. Pikchr is made by the guys who wrote SQLite, and it doesn't need to install a billion NPM dependencies. I think it's worth a try because of this.
- ComputerGuru 3y agoThis seems a lot more low level than Mermaid.
- rcarmo 3y agoOn the other hand, it can be generated automatically, so conversion is certainly possible.
- xigoi 3y agoUnfortunately, Mermaid is difficult to use as a non-frontend library due to its reliance on the DOM API.
- mbork_pl 3y agoThis is pretty impressive – it starts small, with a very simple way to create a very simple diagram, but the rabbit hole seems to go pretty deep. That said, whenever I need to create a diagram like this, I just go back to TikZ...
- thelazyone 3y agoSeems like a considerable upgrade from PlanUML (https://plantuml.com/ https://plantuml.com/ - which is amazing, but sometimes you just can't seem to be able to align the stuff the way you want too). In fact, it seems that the code is slightly less readable compared to PlantUML, I should try to recreate some tangled messes and see how the alignment options work!
- bvrmn 3y agoPikchr is quite low-level and could require a considerable high amount of work to get a result.
- thelazyone 3y agoIt feels that way, yes. I wonder when the line is drawn (pun intended) between an low-level UML description language and a SVG-like formatting language with english words in it. :/
- bvrmn 3y agoI currently try to create a some middle ground. Basic idea: use eDSL to output drawio xml and use drawio to render a final diagram. drawio could back many complex things like arrow routing. WIP output example: https://docs.tuxcare.com/images/eportal-overview.svg https://docs.tuxcare.com/images/eportal-overview.svg
- andrewl 3y agoPikchr was created by the same small group that did SQLite, and it is what creates the SQLite diagrams like the ones on this page: https://sqlite.org/lang_select.html https://sqlite.org/lang_select.html
- rcarmo 3y agoThis is amazing, considering that I can't really use Mermaid because of its puppeteer/headless browser requirement, and that the documentation is written in... itself. I'm going to see if there is a Python wrapper for it already, or try to hack one up over the weekend...
- splittingTimes 3y agoDid you try to use https://kroki.io/ https://kroki.io/ as renderer instead?
- ComputerGuru 3y agoWhat is PIC, referenced in the title and the site copy? The only PIC I know is the microchip line.
- layer8 3y agohttps://en.wikipedia.org/wiki/PIC_(markup_language) https://en.wikipedia.org/wiki/PIC_(markup_language)
- smlckz 3y agoThis refers to the pic(1) preprocessor to the troff(1) typesetter. Troff is a historical typesetting software with a long history in the Unix ecosystem. Having personally used some of the modern implementations (e.g. GNU troff or groff, heirloom troff) of troff for personal projects, it has been a pleasant experience. https://troff.org https://troff.org https://en.wikipedia.org/wiki/Troff https://en.wikipedia.org/wiki/Troff https://en.wikipedia.org/wiki/PIC_(markup_language) https://en.wikipedia.org/wiki/PIC_(markup_language) https://www.man7.org/linux/man-pages/man7/roff.7.html https://www.man7.org/linux/man-pages/man7/roff.7.html
- ComputerGuru 3y agoThanks. I'm familiar with troff, but somehow never came across pic in that context. I have some reading to do!
- wrs 3y agoOne of the first “real” applications of Unix was in the AT&T documentation department. It not only reinforced the practicality of the Unixy “small tools linked by pipes” approach, it also encouraged the “little languages” approach to those tools, which brought us lex and yacc as people built things like eqn and pic to feed into troff. To discover more, just google “unix little languages”.
- codehero 3y agoCan anyone explain to me the advantages of Pikchr over dotfiles?
- bvrmn 3y agoThere is no advantages if you want to splash node relations and get quick and ugly diagram :)).
- ComputerGuru 3y ago> the antepenultimate oval object I laughed at this thinking it was a perfectly cromulent - but completely made up - way of saying “third last” — but I just looked it up and now I feel stupid since it’s actually in the dictionary. Today I learned!
- eddd-ddde 3y agoActually a really common word in Spanish. There are lots of words in english that sound made up that are just literal translations from other languages that non natives use more commonly. Really interesting!
- mbork_pl 3y ago"Overmorrow", for example. Very rare, and the Polish equivalent is used pretty often.
- kaveh808 3y agoAnd fourth from last is preantepenultimate.
- dunham 3y agoIt comes up when studying ancient greek, if I remember right it is used to describe which syllable gets the accent (ultimate, penultimate, or antepenultimate). I also recall a shareware Ultima clone for the Amiga back in late 80's or early 90's called "penultima", but I think it's been lost to the sands of time.
- pkoiralap 3y agoI am asking out of pure ignorance. What would be a good use case for this sorta framework? Whenever I have had to create documentation in the past, I just use draw.io and it has been working well for me so far.
- rcarmo 3y agoWhen you need documentation that has to last a _long_ time and be editable by multiple people. Technical diagrams that can be revised and change tracked an item at a time are priceless in those scenarios, whereas you will never know if draw.io will be around in a few years' time.
- mdaniel 3y ago> you will never know if draw.io will be around in a few years' time. https://github.com/jgraph/drawio#readme https://github.com/jgraph/drawio#readme (Apache 2, at least for now)
- chaxor 3y agoWhat if you want to have version changes to the diagrams tracked by git?
- electroly 3y agoIts creators use it for "railroad" syntax diagrams in the SQLite documentation. For example: https://sqlite.org/lang_select.html https://sqlite.org/lang_select.html
- nicbou 3y agoI maintain a Markdown-based website. I considered using diagrams to explain certain things. It would be a pain to keep image files and rebuild and export images every time the diagram changes. Instead I can put the diagram code directly in the Markdown file and update it as needed. Version control would track those changes legibly. This is very similar to using inlined LaTeX formulas instead of screenshots of the final mathematical formula.
- smusamashah 3y agohttps://pikchr.org/home/pikchrshow https://pikchr.org/home/pikchrshow for trying it out
- cush 3y agoThis fills a gap between md/mermaid (easily editable text with no way to do layout) and svg/excalidraw (uneditable text with easily editable custom layouts). I’m not sure people are actually willing to fiddle with that language though without proper wysiwyg tools, at which point you might as well be using svg.
- xigoi 3y agoI'm using the language for my school notes and like it, though sometimes it feels too manual.
- rcarmo 3y agoSVG makes it a trifle hard to connect boxes automatically, which this seems to do effortlessly.
- cush 3y agoMermaid also connects boxes automatically. My point was WYSIWYG tools make working with svg just as effortless. The automatic connections are fine, it’s all the manual fiddling that ends up making the markup almost unreadable.
- rurban 3y agoThese are the differences to pic: https://pikchr.org/home/doc/trunk/doc/differences.md https://pikchr.org/home/doc/trunk/doc/differences.md It's mostly backwards compatible, with some useful extensions, and without troff embedding support.
- dbg31415 3y agoI can’t get behind stuff like this. It just doesn’t seem easier to use than something like Whimsical or even Visio. Who is the audience? People who want to draw but are afraid to use a mouse? Or can this be automated? But who really automates their documentation? Dunno… just seems like a lot of work to avoid drawing a drawing.
- nicbou 3y agoThe plain text representation can be embedded into documentation and tracked by source control. A change to the diagram is a change to the content, not a separate workflow that requires storing the originals somewhere. Updates don't require any third party software. This fits well into a CMS or static site generator workflow.
- ectospheno 3y agoIntegrated in fossil as well. https://fossil-scm.org/home/doc/trunk/www/pikchr.md https://fossil-scm.org/home/doc/trunk/www/pikchr.md
- mschaef 3y ago> I can’t get behind stuff like this. It just doesn’t seem easier to use than something like Whimsical or even Visio. Different people have different learning/working styles. Even if it doesn't work for you, it may well work for them. (Personally, I like the directness of tools like Visio, but they very much work at the surface of a visual diagram. It can be useful to express things textually.)
- monkeycantype 3y agodoes anyone have an example of how to use the (position,position) syntax? I can't get it to work. I can see in the docs it's not recommended, but i've got a lot of diagrams I've been scripting to render using graphviz using explicit positioning that I'd like to try converting. EDIT: oh too easy you just need the at keyword ``` box at (1,1) "1,1" box at (4,4) "4,4" ```