Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Render diagrams as SVG and/or PNG #200

Closed
aviflax opened this issue Sep 9, 2019 · 4 comments · Fixed by #214
Labels

Comments

@aviflax
Copy link
Contributor

@aviflax aviflax commented Sep 9, 2019

… in addition to PNG.

As discussed with @miketheman IRL.

Personally, I’d want to render to SVG+PNG simultaneously, so rather than add a single-cardinality --format option to the CLI, we might want to add --formats supporting a character-separated list of formats.

For example:

fc4 --render --formats=png,svg <diagram-yaml-file>

Of course it would support specifying a single format as well. For backwards compatibility, the default would be png.

@aviflax

This comment has been minimized.

Copy link
Contributor Author

@aviflax aviflax commented Sep 9, 2019

Ah, the CLI already has the option -f/--format which enables the YAML reformatting feature.

So instead, let’s use -o/--output-formats.

@aviflax

This comment has been minimized.

Copy link
Contributor Author

@aviflax aviflax commented Sep 9, 2019

I’m thinking that maybe instead of having the option be named in the plural and accept a character-separated list of formats, it might be more UNIX-y to name the option in the singular and allow it to be specified multiple times.

So maybe instead of:

fc4 --render --output-formats png,svg <diagram-yaml-file>

it’d be:

fc4 --render --output-format png --output-format svg <diagram-yaml-file>

but that’s more verbose and therefore less usable if someone is invoking the tool manually. So now I’m leaning back towards the former 🙄

@miketheman thoughts?

@aviflax

This comment has been minimized.

Copy link
Contributor Author

@aviflax aviflax commented Sep 10, 2019

but that’s more verbose and therefore less usable if someone is invoking the tool manually

OTOH, one could use the short -o form:

fc4 --render -o png -o svg <diagram-yaml-file>

That said, I think I’m leaning towards this:

fc4 --render -o png+svg <diagram-yaml-file>
aviflax added a commit that referenced this issue Sep 11, 2019
aviflax added a commit to aviflax/fc4-framework that referenced this issue Sep 17, 2019
@aviflax

This comment has been minimized.

Copy link
Contributor Author

@aviflax aviflax commented Sep 20, 2019

I’m making good progress on this.

Here’s the current output, from the tool on my WIP local branch, if someone specifies an invalid value for --output-formats:

$ clojure -A:main --output-formats pdf
Usage: fc4 OPTIONS PATH [PATH...]

Options:
  -f, --format                 Rewrites diagram YAML files, reformatting the YAML to improve readability and diffability.
  -s, --snap                   Rewrites diagram YAML files, snapping elements to a grid and aligning elements.
  -r, --render                 Creates image files that contain the visualization of each diagram as specified in the YAML files. The format(s) can be specified via -o/--output-formats.
  -o, --output-formats FORMAT  Specifies the output format(s) for rendering diagrams. Allowed only when -r/--render is specified. Value is a character-delimited list of output formats. Supported formats are 'png' and 'svg'; supported delimiters are '+' (plus sign) and ',' (comma). If not specified, the default is 'png'. NB: svg output is written to files with the extension '.html'.
  -w, --watch                  Watches the diagrams in/under the specified paths and processes them (as per the options above) when they change.
  -h, --help                   Prints the synopsis and a list of the most commonly used commands and exits. Other options are ignored.
      --debug                  For use by developers working on fc4 (the tool).

Errors:
   Failed to validate "--output-formats pdf": Supported formats are 'png' and 'svg'.

Full documentation is at https://fundingcircle.github.io/fc4-framework/tool/

I’m pretty happy with the UX of all this; the only concern I have is that the description of the option is way too long and it looks terrible when it’s wrapped in a terminal:

Screen Shot 2019-09-20 at 12 50 39 PM

But some of the other options also have long descriptions that wrap terribly. This seems like a bug (or, let’s say, sub-optimal behavior) in the library that’s generating that summary, clojure.tools.cli. That library would allow me to supply my own function to format the summary so maybe I’ll give that a try. I’ve created #212 to track that.

@aviflax aviflax changed the title Support rendering diagrams as SVG Render diagrams as SVG and/or PNG Sep 24, 2019
aviflax added a commit to aviflax/fc4-framework that referenced this issue Sep 25, 2019
As per FundingCircle#200.

WIP++ MAYBE REMOVE ALL THESE DEBUG STATEMENTS

WIP++ NEEDS DOCS AND MORE TESTS

WIP++

WIP++

WIP++

WIP++ code tweak

WIP++ Docs Yay!
aviflax added a commit that referenced this issue Sep 26, 2019
As per #200.
aviflax added a commit that referenced this issue Sep 26, 2019
As per #200.
aviflax added a commit that referenced this issue Oct 2, 2019
As per #200.
@aviflax aviflax closed this in #214 Oct 3, 2019
aviflax added a commit that referenced this issue Oct 29, 2019
As explained in #222:

> In #200 we added support for rendering diagrams to SVG images instead
> of, or in addition to (simultaneously with) PNG images.
>
> When I implemented that, I had the tool save the SVG images as files
> with an `.html` extension, because that was what Structurizr Express
> (SE) did. I didn’t know why that was the case, but I trusted that
> there was a good reason for that choice, so I figured I’d do the same
> thing. After all, when I opened those HTML files — both those exported
> directly from SE and those created by fc4 — in a browser — they
> rendered nicely. So it seemed good to me.
>
> Unfortunately, I neglected to account for an important goal of FC4: to
> enable peer review of changes to diagrams via GitHub Pull Requests,
> via textual diffs of the YAML sources and via visual diffs of the
> rendered images. GitHub will render SVG files with the `.svg`
> extension (as long as their contents are valid) but it won’t render
> any files with the `.html` extension.
>
> This is bad. So let’s fix the tool to save the SVG image files as
> valid SVG with the `.svg` filename extension.

This was a little more involved than one might think. I think it’s
because browsers are way more tolerant of strange issues in HTML files
as compared to SVG files.

One result of that was that the HTML file worked without a root element
— there were two SVG documents at the “root” of the file. That’s not
valid for XML, so in order to create a single SVG XML file, I had to
create a new root element and wrap the diagram and the key in SVG `g`
elements (`g` for _group_). Anyway, it works.

Fixes #222
aviflax added a commit that referenced this issue Oct 30, 2019
As explained in #222:

> In #200 we added support for rendering diagrams to SVG images instead
> of, or in addition to (simultaneously with) PNG images.
>
> When I implemented that, I had the tool save the SVG images as files
> with an `.html` extension, because that was what Structurizr Express
> (SE) did. I didn’t know why that was the case, but I trusted that
> there was a good reason for that choice, so I figured I’d do the same
> thing. After all, when I opened those HTML files — both those exported
> directly from SE and those created by fc4 — in a browser — they
> rendered nicely. So it seemed good to me.
>
> Unfortunately, I neglected to account for an important goal of FC4: to
> enable peer review of changes to diagrams via GitHub Pull Requests,
> via textual diffs of the YAML sources and via visual diffs of the
> rendered images. GitHub will render SVG files with the `.svg`
> extension (as long as their contents are valid) but it won’t render
> any files with the `.html` extension.
>
> This is bad. So let’s fix the tool to save the SVG image files as
> valid SVG with the `.svg` filename extension.

This was a little more involved than one might think. I think it’s
because browsers are way more tolerant of strange issues in HTML files
as compared to SVG files.

One result of that was that the HTML file worked without a root element
— there were two SVG documents at the “root” of the file. That’s not
valid for XML, so in order to create a single SVG XML file, I had to
create a new root element and wrap the diagram and the key in SVG `g`
elements (`g` for _group_). Anyway, it works.

Fixes #222
aviflax added a commit that referenced this issue Oct 30, 2019
As explained in #222:

> In #200 we added support for rendering diagrams to SVG images instead
> of, or in addition to (simultaneously with) PNG images.
>
> When I implemented that, I had the tool save the SVG images as files
> with an `.html` extension, because that was what Structurizr Express
> (SE) did. I didn’t know why that was the case, but I trusted that
> there was a good reason for that choice, so I figured I’d do the same
> thing. After all, when I opened those HTML files — both those exported
> directly from SE and those created by fc4 — in a browser — they
> rendered nicely. So it seemed good to me.
>
> Unfortunately, I neglected to account for an important goal of FC4: to
> enable peer review of changes to diagrams via GitHub Pull Requests,
> via textual diffs of the YAML sources and via visual diffs of the
> rendered images. GitHub will render SVG files with the `.svg`
> extension (as long as their contents are valid) but it won’t render
> any files with the `.html` extension.
>
> This is bad. So let’s fix the tool to save the SVG image files as
> valid SVG with the `.svg` filename extension.

This was a little more involved than one might think. I think it’s
because browsers are way more tolerant of strange issues in HTML files
as compared to SVG files.

One result of that was that the HTML file worked without a root element
— there were two SVG documents at the “root” of the file. That’s not
valid for XML, so in order to create a single SVG XML file, I had to
create a new root element and wrap the diagram and the key in SVG `g`
elements (`g` for _group_). Anyway, it works.

Fixes #222
aviflax added a commit that referenced this issue Oct 30, 2019
As explained in #222:

> In #200 we added support for rendering diagrams to SVG images instead
> of, or in addition to (simultaneously with) PNG images.
>
> When I implemented that, I had the tool save the SVG images as files
> with an `.html` extension, because that was what Structurizr Express
> (SE) did. I didn’t know why that was the case, but I trusted that
> there was a good reason for that choice, so I figured I’d do the same
> thing. After all, when I opened those HTML files — both those exported
> directly from SE and those created by fc4 — in a browser — they
> rendered nicely. So it seemed good to me.
>
> Unfortunately, I neglected to account for an important goal of FC4: to
> enable peer review of changes to diagrams via GitHub Pull Requests,
> via textual diffs of the YAML sources and via visual diffs of the
> rendered images. GitHub will render SVG files with the `.svg`
> extension (as long as their contents are valid) but it won’t render
> any files with the `.html` extension.
>
> This is bad. So let’s fix the tool to save the SVG image files as
> valid SVG with the `.svg` filename extension.

This was a little more involved than one might think. I think it’s
because browsers are way more tolerant of strange issues in HTML files
as compared to SVG files.

One result of that was that the HTML file worked without a root element
— there were two SVG documents at the “root” of the file. That’s not
valid for XML, so in order to create a single SVG XML file, I had to
create a new root element and wrap the diagram and the key in SVG `g`
elements (`g` for _group_). Anyway, it works.

Fixes #222
aviflax added a commit that referenced this issue Oct 31, 2019
As explained in #222:

> In #200 we added support for rendering diagrams to SVG images instead
> of, or in addition to (simultaneously with) PNG images.
>
> When I implemented that, I had the tool save the SVG images as files
> with an `.html` extension, because that was what Structurizr Express
> (SE) did. I didn’t know why that was the case, but I trusted that
> there was a good reason for that choice, so I figured I’d do the same
> thing. After all, when I opened those HTML files — both those exported
> directly from SE and those created by fc4 — in a browser — they
> rendered nicely. So it seemed good to me.
>
> Unfortunately, I neglected to account for an important goal of FC4: to
> enable peer review of changes to diagrams via GitHub Pull Requests,
> via textual diffs of the YAML sources and via visual diffs of the
> rendered images. GitHub will render SVG files with the `.svg`
> extension (as long as their contents are valid) but it won’t render
> any files with the `.html` extension.
>
> This is bad. So let’s fix the tool to save the SVG image files as
> valid SVG with the `.svg` filename extension.

This was a little more involved than one might think. I think it’s
because browsers are way more tolerant of strange issues in HTML files
as compared to SVG files.

One result of that was that the HTML file worked without a root element
— there were two SVG documents at the “root” of the file. That’s not
valid for XML, so in order to create a single SVG XML file, I had to
create a new root element and wrap the diagram and the key in SVG `g`
elements (`g` for _group_). Anyway, it works.

Fixes #222
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
1 participant
You can’t perform that action at this time.