[HN Gopher] Pikchr: A PIC-like markup language for diagrams in t...
___________________________________________________________________
Pikchr: A PIC-like markup language for diagrams in technical
documentation
Author : gjadi
Score : 147 points
Date : 2023-07-24 12:48 UTC (10 hours ago)
(HTM) web link (pikchr.org)
(TXT) w3m dump (pikchr.org)
| smusamashah wrote:
| https://pikchr.org/home/pikchrshow for trying it out
| andrewl wrote:
| Pikchr 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
| rcarmo wrote:
| This 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 wrote:
| Did you try to use https://kroki.io/ as renderer instead?
| thelazyone wrote:
| Seems like a considerable upgrade from PlanUML
| (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 wrote:
| Pikchr is quite low-level and could require a considerable high
| amount of work to get a result.
| thelazyone wrote:
| It 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 wrote:
| I 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
| ComputerGuru wrote:
| What is PIC, referenced in the title and the site copy? The only
| PIC I know is the microchip line.
| smlckz wrote:
| This 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://en.wikipedia.org/wiki/Troff
|
| https://en.wikipedia.org/wiki/PIC_(markup_language)
|
| https://www.man7.org/linux/man-pages/man7/roff.7.html
| ComputerGuru wrote:
| Thanks. I'm familiar with troff, but somehow never came
| across pic in that context. I have some reading to do!
| wrs wrote:
| One 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".
| layer8 wrote:
| https://en.wikipedia.org/wiki/PIC_(markup_language)
| dbg31415 wrote:
| I 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 wrote:
| The 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 wrote:
| Integrated in fossil as well.
|
| https://fossil-scm.org/home/doc/trunk/www/pikchr.md
| codehero wrote:
| Can anyone explain to me the advantages of Pikchr over dotfiles?
| bvrmn wrote:
| There is no advantages if you want to splash node relations and
| get quick and ugly diagram :)).
| otikik wrote:
| Mermaid [1] has been good enough for me for years.
|
| [1] https://mermaid.js.org/intro/
| JTyQZSnP3cQGa8B wrote:
| And 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.
| xigoi wrote:
| Unfortunately, Mermaid is difficult to use as a non-frontend
| library due to its reliance on the DOM API.
| ComputerGuru wrote:
| This seems a lot more low level than Mermaid.
| rcarmo wrote:
| On the other hand, it can be generated automatically, so
| conversion is certainly possible.
| mbork_pl wrote:
| This 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...
| ComputerGuru wrote:
| > 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 wrote:
| Actually 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!
| kaveh808 wrote:
| And fourth from last is preantepenultimate.
| rurban wrote:
| These are the differences to pic:
| https://pikchr.org/home/doc/trunk/doc/differences.md
|
| It's mostly backwards compatible, with some useful extensions,
| and without troff embedding support.
| junon wrote:
| This actually looks really nice. Good documentation from the
| looks of it too.
| cush wrote:
| This 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.
| rcarmo wrote:
| SVG makes it a trifle hard to connect boxes automatically,
| which this seems to do effortlessly.
| xigoi wrote:
| I'm using the language for my school notes and like it, though
| sometimes it feels too manual.
| pkoiralap wrote:
| I 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.
| electroly wrote:
| Its creators use it for "railroad" syntax diagrams in the
| SQLite documentation. For example:
| https://sqlite.org/lang_select.html
| chaxor wrote:
| What if you want to have version changes to the diagrams
| tracked by git?
| nicbou wrote:
| I 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.
| rcarmo wrote:
| When 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 wrote:
| > you will never know if draw.io will be around in a few
| years' time.
|
| https://github.com/jgraph/drawio#readme (Apache 2, at least
| _for now_ )
___________________________________________________________________
(page generated 2023-07-24 23:01 UTC)