Descriptive Language

[bitozoid]

This is a feature request.

I wonder whether the Asciio format could be expressed in plain text. I'm thinking of a descriptive language (like graphviz, plantuml or mermaid) that can be rendered by asciio to plain text. Of course, I assume that Asciio would require a lot of graphical data (x,y positions) as well.

Plain text would provide easier version control, quick typo corrections, and full integration (not only the diagrams) into other plain text formats (I'm thinking in OrgMode).

I've seen some tools that render from plain text diagrams to SVG or raster, but I miss the first step.

Thanks a lot for the great job.

[nkh]

@bitozoid hmm, Yes! Well depending on what you want to do and the format of the plain text you want to use.

Asciio, like any "script" language application is grounded in that principle, then it can be more or less easy to do it; fortunately Asciio has always had a scripting lib to allow you to do that.

About a month ago, as if I was expecting your message ;), I rewrote the scripting interface to remove some boilerplate.

There's an effort to bring a better documentation forward, the new doc is 50% ready but unfortunately not wrapped up yet which makes it difficult for users to find it (well, it's in the documentation directory). If you install mdbook you can generate it yourself.

This is the page you're looking for:
https://github.com/nkh/P5-App-Asciio/blob/master/documentation/mdbook_asciio/src/for_developers/scripting.md

The examples are here:
https://github.com/nkh/P5-App-Asciio/tree/master/documentation/scripting

Still, We could make things even simpler if we had some application to call rather than passing the script to perl.

use strict; use warnings;

use App::Asciio::Scripting ;
use App::Asciio::stripes::process_box ;

#-----------------------------------------------------------------------------

add 'box1', new_box(TEXT_ONLY =>'box1'),  0,  2 ;
add 'box2', new_box(TEXT_ONLY =>'box2'), 20, 10 ;
add 'box3', new_box(TEXT_ONLY =>'box3'), 40,  5 ;

connect_elements 'box1', 'box2', 'down' ;
connect_elements 'box2', 'box3' ;
connect_elements 'box3', 'box1', 'up' ;

my $process = add_type 'process', 'Asciio/Boxes/process', 5, 15 ;
$process->set_text("line 1\nline 2\nline 3") ;

optimize ;

save_to "from_script.asciio" ;

ascii_out ;

could be shorter, something like below in the future (want to help?) , in the meantime the code above does the same thing.

box 'box1', 0,  2, 'title', 'box1 text' ;
box 'box2', 20,  10, 'title', 'box2 text' ;
box 'box3', 40,  5, 'title', 'box3 text' ;

connect 'box1', 'box2', DOWN ;
connect 'box2', 'box3' ;
connect 'box3', 'box1', UP ;

process 'process1', 5, 15, "some text" ;

#27 #28 #29 #54 can be off interest.

of course you can use "save_to" to get a file which can be opened for further manipulation in Asciio, not just text on the terminal.

if you're just interested in a text then https://metacpan.org/pod/Graph::Easy is a good solution, I actually looked at it for implementing routing in Asciio but haven't come any further because it would need a "multiconnector" box element which doesn't exist (yet) in Asciio.

[bitozoid]

That's great news!

I'm afraid I cannot help. I can't write a line in Perl.

Anyway, I would expect Asciio not only to read this scripting language but also to export to this format. That would be of much help.

Thanks a lot for the great work!

[nkh]

Before I forget, where did you get Asciio from, the repo, install from cpan, instal from a package manager? Windows or Linux user?

You don't have to write code to help (although knowing som Perl and Bash is fun!)

Here are a few thing that help tremendously.

• giving feedback about your experience
  • installing Asciio
  • using Asciio
  • using its documentation
  • using the scripting library
• give some scripts you've written
• giving some graphs you generated
• giving input about the other tickets I listed
• adding feature requests (don't expect instant implementation ;) took me 10 years to start developing Asciio again)
• get the CI on github to generate the docs

None of those require writing a line of code, and would you like to start programming, not sure if you do already, we can find you something simple to start with; maybe you're a web technology freak (we're looking for one), or even good at making demos and would like to share.

[nkh]

The exporters are here https://github.com/nkh/P5-App-Asciio/tree/master/setup/import_export

A good place to start ;)

[nkh]

@bitozoid did the example above get you going and was the documentation enough? in that case close this ticket or it we be closed shortly.

the documentation is now online at https://nkh.github.io/P5-App-Asciio/for_developers/scripting.html

[nkh]

@bitozoid you named that you would like Asciio to export the diagrams as text, what was the use case you had in mind?

[bitozoid]

Apologies for not responding earlier.

Let's say I need to write some documentation which includes some diagrams. I'd like all the stuff to be written in plain text, diagramas included. I mean, I want a set of source files that I can edit via a terminal and where I can do version control easily. From that set of "source" files, I would like to end up not only with some pretty printable documentation, but also with some documentation I can read in the terminal.

I would say that for text this problem is solved. For instance, markdown can be easily written and read from a terminal, and rendered via pandoc to other printable formats. Somehow, in a terminal, the source and the target for text are almost the same.

However, in the case of a diagram, imho this problem is open, because source and target are not the same, unless you edit directly a plain text diagram. Once you have your plain text diagram, there are some tools that can turn them into nice printable SVGs (for instance goat). Editing plain text diagrams is cubersome, and this is where Asciio is great.

I would say that nowadays the following tools exist:

• plain text diagram -> vector graphics: goat, ditaa, typograms, asciitosvg
• declarative lang -> vector graphics : mermaid, d2, tikz, plantuml, graphviz
• not plain nor declarative lang -> plain text diagram : asciio

A declarative language is a great idea. A plain text diagram is a great idea. Why not a

• declarative lang -> plain text diagram?

Graph::Easy and PlantUML ascii art renderer are the nearest approaches I've seen, but the result is not near enough to a free design tool as Asciio.

If Asciio could use a simple declarative languaje as file format that would solve the problem.

[nkh]

I'd say that Asciio scripting is pretty declarative

´´´
add 'text1', new_text(TEXT_ONLY =>'text'), 22, 20 ;

add 'box1', new_box(TEXT_ONLY =>'box1'), 0, 2 ;
add 'box2', new_box(TEXT_ONLY =>'box2'), 20, 10 ;
add 'box3', new_box(TEXT_ONLY =>'box3'), 40, 5 ;

connect_elements 'box1', 'box2', 'down' ;
connect_elements 'box2', 'box3' ;
connect_elements 'box3', 'box1', 'up' ;
connect_elements 'box2', 'text1' ;
´´´

Please show me how you'd rather it look, I'm always open to suggestions.

And my question above was about exporting the diagrams, would that be to first draw something in asciio and be able to put it in a text file? The problem with that is that it can be a lot lines for anything but very simple diagrams but that should be reasonably easy to write.

Since 097f80c asciio can be used as a server to render diagrams. the scripting documentation is at https://nkh.github.io/P5-App-Asciio/for_developers/scripting.html including the API