search

asciidoctor / asciidoctor-diagram

:left_right_arrow: Asciidoctor diagram extension, with support for AsciiToSVG, BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag), Ditaa, Erd, GraphViz, Mermaid, Msc, PlantUML, Shaape, SvgBob, Syntrax, UMLet, Vega, Vega-Lite and WaveDrom.
http://asciidoctor.org
MIT License
435 stars 106 forks source link

update project description in gemspec #340

Closed mojavelinux closed 3 years ago

mojavelinux commented 3 years ago

I noticed that the project description in the gem was outdated. I tried to come up with a way to encapsulate all this library does in a single sentence. It may still need some work. Feedback welcome. cc: @djencks @Mogztter

ggrossetie commented 3 years ago

An extension for Asciidoctor that produces diagrams from plain text source using PlantUML, ditaa, Kroki, and other generators.

I agree, we probably need to add "and others" otherwise it might sound like Asciidoctor Diagram supports PlantUML, ditaa, Kroki and that's it.

mojavelinux commented 3 years ago

I agree, we probably need to add "and others" otherwise it might sound like Asciidoctor Diagram supports PlantUML, ditaa, Kroki and that's it.

"including" implies there are others, but I also recognize that with a global audience, we should be explicit as possible.

mojavelinux commented 3 years ago

There are blockMacro processors as well as block processors, so the source doesn't have to be in your AsciiDoc document.

I think that's getting to nuanced. Regardless of how the source is included, it's still included. I'll see if I can find a middle ground.

mojavelinux commented 3 years ago

I've made updates. Let me know what you think.

pepijnve commented 3 years ago

A family of Asciidoctor extensions for generating a broad range of diagrams sourced from plain text embedded in or referenced by your AsciiDoc document, including integration with PlantUML, ditaa, Kroki, and many others

Condensing that a bit, cutting out superfluous words I came up with this. 'Descriptions' is the one word I'm not 100% comfortable with. It's "just" the project description, so I don't think we need to overthink this either 😄

A family of Asciidoctor extensions that generate images from a broad range of embedded plain text diagram descriptions, including PlantUML, ditaa, Kroki, and many others.

mojavelinux commented 3 years ago

Updated.

If you aren't comfortable with "descriptions", might I offer "representations" as an alternative?

mojavelinux commented 3 years ago

One other idea is "depictions", which fits because you truly are describing how you want it to look.

pepijnve commented 3 years ago

It's all good for me Dan, just sharing my 2c here. The diagram code is declarative indeed. As you said "you are describing what you want". If you state it that way description seems like the appropriate noun after all.

mojavelinux commented 3 years ago

Excellent. Merge at will :+1:

pepijnve commented 3 years ago

Wish granted!