From 7503579b98be54a3ccebc1471267ab730171ff92 Mon Sep 17 00:00:00 2001 From: Ivan Ponomarev Date: Sat, 10 Apr 2021 19:10:57 +0300 Subject: [PATCH] Documenation update (#44) * documentation update * fix README.md --- README.md | 8 +- doc/src/main/asciidoc/index.adoc | 84 ++++++--- json_number.svg | 171 ++++++++++++++++++ .../org/atpfivt/jsyntrax/InputArguments.java | 17 +- .../atpfivt/jsyntrax/InputArgumentsTest.java | 16 ++ .../java/org/atpfivt/jsyntrax/MainTest.java | 8 +- pom.xml | 2 +- syntrax_scripts/input | 12 -- syntrax_scripts/style.ini | 31 ---- 9 files changed, 269 insertions(+), 80 deletions(-) create mode 100644 json_number.svg delete mode 100644 syntrax_scripts/input delete mode 100644 syntrax_scripts/style.ini diff --git a/README.md b/README.md index 2e62ce5..5012470 100644 --- a/README.md +++ b/README.md @@ -21,12 +21,12 @@ indentstack(10, This is processed by JSyntrax to generate an SVG image: -![](doc/src/main/asciidoc/images/json_number.svg) +![](json_number.svg) -JSyntrax renders SVG vector images. The SVG output can have hyperlinked text allowing users to quickly navigate to documentation of different syntax elements. +JSyntrax can render to SVG vector images or PNG bitmap images. The SVG output can have [hyperlinked text](https://atp-mipt.github.io/jsyntrax/#_hyperlinked_svg) allowing users to quickly navigate to documentation of different syntax elements. -This is a Java reimplementation of [syntrax](https://github.com/kevinpt/syntrax/) project, originally written in Python. +JSyntrax is a Java reimplementation of [syntrax](https://github.com/kevinpt/syntrax/) project, originally written in Python. We use [Apache Batik](https://xmlgraphics.apache.org/batik/) for SVG rasterization. -The aim of this project is to make `syntrax` tool easy to install on any operating system (no software is required for `jsyntrax` besides Java 11). +The aim of this project is to make `syntrax` tool easy to install on any operating system. No software and libraries are required for `jsyntrax` besides Java 11. See [documentation](https://atp-mipt.github.io/jsyntrax/). \ No newline at end of file diff --git a/doc/src/main/asciidoc/index.adoc b/doc/src/main/asciidoc/index.adoc index 1f47694..9c66470 100644 --- a/doc/src/main/asciidoc/index.adoc +++ b/doc/src/main/asciidoc/index.adoc @@ -35,7 +35,8 @@ indentstack(10, ) .... -JSyntrax can render to SVG vector images, the output can have <> allowing users to quickly navigate to documentation of different syntax +JSyntrax can render to PNG bitmap images or SVG vector images. +The SVG output can have <> allowing users to quickly navigate to documentation of different syntax elements. The https://github.com/kevinpt/JSyntrax[original Syntrax] was a heavily modified version of the railroad diagram generator used for the https://www.sqlite.org/lang.html[SQLite documentation] implemented in Python. @@ -43,40 +44,34 @@ Then in JSyntrax it has been reimplemented in Java in order to simplify installa ==== JSyntrax vs. Syntrax -Why did you reimplement Syntrax?:: The problem with Syntrax is that it requires Pycairo and Pango which may be difficult to install, especially on Windows. +Why did you reimplement Syntrax in Java?:: The problem with Syntrax is that it requires Pycairo and Pango which may be difficult to install, especially on Windows. +JSyntrax requires only JDK 11, which is easily https://adoptopenjdk.net/releases.html[available] for many platforms. -JSyntrax requires only JDK 11, which is easily available for many platforms. - -What output formats are supported?:: Unlike original Syntrax, that can output to many bitmap and vector formats, JSyntrax only produces SVG. -This can be changed in the future. +What output formats are supported?:: JSyntrax produces SVG and PNG images. The original Syntrax can also produce PDF, PS, and EPS, these formats are not yet supported by JSyntrax. Can I build my Syntrax specs with JSyntrax?:: Yes, after only a couple of minor tweaks. -If you use url maps, refer to <> section for Groovy-specific DSL which is a bit different from what was in original Syntrax. -Also, `text_mod` attribute in <> is not supported (the author of the original Syntrax warned about potential security issues with this attribute). -Instead, if a style regexp pattern contains a capturing group, the node text will contain the contents of this capturing group only. - +If you use url maps, refer to <> section for Groovy-specific DSL which is a bit different from what was in original Syntrax (in short: you will have to replace `{}` with `[]` and add `jsyntrax` wrapper function). +Also, `text_mod` attribute in <> is not supported (the author of the original Syntrax https://kevinpt.github.io/syntrax/#node-styles[warned] about potential security issues with this attribute). +Instead, if a style regexp pattern contains a capturing group, the node text will contain the contents of the first capturing group only. -Why your executable file is called `syntrax`?:: This is made intentionally in order to use https://asciidoctor.org/docs/asciidoctor-diagram/[AsciiDoctor Diagram] integration facility. JSyntrax executable has exactly the same command line arguments as Syntrax. +Why your executable file is called `syntrax`, not `jsyntrax`?:: This is made intentionally in order to use https://asciidoctor.org/docs/asciidoctor-diagram/[AsciiDoctor Diagram] integration facility. +JSyntrax executable has exactly the same <> as Syntrax and can be used as a replacement for the original `syntrax` tool. ==== Licensing JSyntrax is licensed for free commercial and non-commercial use under the terms of the MIT license. - === Requirements, download and installation -JSyntrax requires JDK 11+. No other software is required to run JSyntrax. +JSyntrax requires https://adoptopenjdk.net/releases.html[JDK 11+]. No other software is required to run JSyntrax. -You can access the JSyntrax Git repository from -https://github.com/atp-mipt/java-syntrax[Github]. +You can access the JSyntrax Git repository from https://github.com/atp-mipt/java-syntrax[Github], and download releases https://github.com/atp-mipt/jsyntrax/releases[here]. Unzip `jsyntrax-XXX.zip` file to any convenient folder. `/bin` directory will contain executable `syntrax` file. === Using JSyntrax -JSyntrax is a command line tool. You pass it an input specification file -and it will generate a diagram in any of the supported output formats. - +JSyntrax is a command line tool. You pass it an input specification file and it will generate a diagram in any of the supported output formats. ---- usage: syntrax [--get-style] [-h] [-i ] [-o ] [-s ] [--scale @@ -94,6 +89,27 @@ Options -v,--version JSyntrax version ---- +Any argument not associated with a flag is assumed to be the input file name. The default output format is PNG. + +---- +> syntrax spec +Output file spec.png was created +Done! +---- + +You can specify the specific out file you want with the `-o` option. +The extension determines the format. +You can also pass just the extension to `-o` and Syntrax will use the input file base name for the output image: + +---- +>syntrax -i spec -o result.svg +Output file result.svg was created +Done! + +>syntrax -i spec -o svg +Output file spec.svg was created +Done! +---- ==== Transparency @@ -370,9 +386,7 @@ rightstack( === Styling diagrams You can control the styling of the generated diagrams by passing in a -style INI file with the `+-s+` option. By default JSyntrax will look for -a file named "jsyntrax.ini" in the current directory and use that if it -exists. Otherwise it will fall back to its internal defaults. +style INI file with the `+-s+` option. You can use the `+--get-style+` option to generate a copy of the default styles in the current directory so you can quickly make modifications. @@ -600,9 +614,10 @@ Fonts are specified as a tuple of three items in the following order: * Point size (12, 14, 16, etc.) * Style ('normal', 'bold', 'italic') +---- title_font = ('Helvetica', 14, 'bold') +---- -[hyperlinked] === Hyperlinked SVG SVG images can have hyperlinked node text. This is implemented by adding a `+url_map+` parameter to `jsyntrax` wrapper function. @@ -628,6 +643,19 @@ jsyntrax(stack( Note that in Groovy, unlike Python, maps are enclosed in brackets `[]`, not braces `{}`. ==== +[syntrax,hyperlinked,svg,opts=interactive] +.... +jsyntrax(stack( + line('attribute', '/(attribute) identifier', 'of'), + line(choice(toploop('/entity_designator', ','), 'others', 'all'), ':'), + line('/entity_class', 'is', '/expression', ';') +), +[ + 'entity_class': 'https://www.google.com/#q=vhdl+entity+class', + '(attribute) identifier': 'http://en.wikipedia.com/wiki/VHDL' +]) +.... + Current browser policies lump SVG hyperlinks together with embedded Javascript. Because of this they do not support hyperlinks when an SVG @@ -638,3 +666,15 @@ To get functional links on a web page you must use an `++` tag instead: ---- ---- + +In Asciidoctor diagrams, we should put set `opts=interactive` or `opts=inline` on the diagram block: + +---- +[syntrax,hyperlinked,svg,opts=interactive] +.... +jsyntrax( ... , +[ + ... +]) +.... +---- \ No newline at end of file diff --git a/json_number.svg b/json_number.svg new file mode 100644 index 0000000..1d38562 --- /dev/null +++ b/json_number.svg @@ -0,0 +1,171 @@ + + + + + + + + + + + + + + + + + + + + + + + +- + + + + + + + + + + + +0 + +1-9 + + +0-9 + + + + + + + + + + + + + + + + + + + + +. + +0-9 + + + + + + + + + + + + + + + + + + + + + +e + +E + + + + + + + + + + + + ++ + +- + + + + + + + + + + + + + + + + +0-9 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/jsyntrax/src/main/java/org/atpfivt/jsyntrax/InputArguments.java b/jsyntrax/src/main/java/org/atpfivt/jsyntrax/InputArguments.java index 39d67de..2cbb40c 100644 --- a/jsyntrax/src/main/java/org/atpfivt/jsyntrax/InputArguments.java +++ b/jsyntrax/src/main/java/org/atpfivt/jsyntrax/InputArguments.java @@ -27,7 +27,6 @@ public class InputArguments { private boolean transparent; private double scale = 1.0; private boolean getDefaultStyle = false; - private boolean png = false; static { OPTIONS = new Options(); @@ -69,7 +68,7 @@ public class InputArguments { } //Any argument not associated with a flag is assumed to be the input file name if (commandLine.getArgList().size() > 0) { - this.input = Paths.get(commandLine.getArgList().get(0).toString()); + this.input = Paths.get(commandLine.getArgList().get(0)); } } @@ -89,15 +88,21 @@ public Path getInput() { return input; } - private static Path changeExtension(Path p, String ext) { + static Path changeExtension(Path p, String ext) { String path = p.toString(); - return Paths.get(path.substring(0, path.lastIndexOf('.')) - + "." + ext); + int i = path.lastIndexOf('.'); + if (i >= 0) { + return Paths.get(path.substring(0, i) + + "." + ext); + } else { + return Paths.get(path + + "." + ext); + } } public Path getOutput() { if (output == null) { - output = changeExtension(input, "svg"); + output = changeExtension(input, "png"); } else if ("png".equalsIgnoreCase(output.toString()) || "svg".equalsIgnoreCase(output.toString())) { output = changeExtension(input, output.toString()); diff --git a/jsyntrax/src/test/java/org/atpfivt/jsyntrax/InputArgumentsTest.java b/jsyntrax/src/test/java/org/atpfivt/jsyntrax/InputArgumentsTest.java index 12f339d..21738fb 100644 --- a/jsyntrax/src/test/java/org/atpfivt/jsyntrax/InputArgumentsTest.java +++ b/jsyntrax/src/test/java/org/atpfivt/jsyntrax/InputArgumentsTest.java @@ -3,6 +3,7 @@ import groovyjarjarcommonscli.ParseException; import org.junit.jupiter.api.Test; +import java.nio.file.Path; import java.nio.file.Paths; import static org.junit.jupiter.api.Assertions.*; @@ -55,4 +56,19 @@ void testDefaultInputParam() throws ParseException{ assertEquals(Paths.get("test.spec"), inputArguments.getInput()); } + + @Test + void changeExtension() { + assertEquals("foo.baz", InputArguments.changeExtension(Path.of("foo.bar"), "baz").toString()); + } + + @Test + void changeExtensionNoName() { + assertEquals(".baz", InputArguments.changeExtension(Path.of(".bar"), "baz").toString()); + } + + @Test + void addExtension() { + assertEquals("foo.baz", InputArguments.changeExtension(Path.of("foo"), "baz").toString()); + } } diff --git a/jsyntrax/src/test/java/org/atpfivt/jsyntrax/MainTest.java b/jsyntrax/src/test/java/org/atpfivt/jsyntrax/MainTest.java index b23085b..9e4e824 100644 --- a/jsyntrax/src/test/java/org/atpfivt/jsyntrax/MainTest.java +++ b/jsyntrax/src/test/java/org/atpfivt/jsyntrax/MainTest.java @@ -120,13 +120,13 @@ void testSvgByOutFileType() throws IOException, URISyntaxException, NoSuchFieldE } @Test - void testSvgByDefault() throws IOException, URISyntaxException, NoSuchFieldException, IllegalAccessException { + void testPngByDefault() throws IOException, URISyntaxException, NoSuchFieldException, IllegalAccessException { Path inputPath = Paths.get(MainTest.class.getResource("jsyntrax.spec").toURI()); - Path outPath = Paths.get(inputPath.toString().substring(0, inputPath.toString().lastIndexOf('.')) + ".svg"); + Path outPath = Paths.get(inputPath.toString().substring(0, inputPath.toString().lastIndexOf('.')) + ".png"); try { Main.main(inputPath.toString()); - String svg = Files.readString(outPath); - validateSVG(svg); + byte[] png = Files.readAllBytes(outPath); + validatePng(png); } finally { Files.delete(outPath); } diff --git a/pom.xml b/pom.xml index 5176122..90313d7 100644 --- a/pom.xml +++ b/pom.xml @@ -63,7 +63,7 @@ - 1.0 + 1.1 2.1.0 2.1.2 diff --git a/syntrax_scripts/input b/syntrax_scripts/input deleted file mode 100644 index e44a6b7..0000000 --- a/syntrax_scripts/input +++ /dev/null @@ -1,12 +0,0 @@ -jsyntrax(stack( - line('attribute', '/(attribute) identifier', 'of'), - optx("None"), - line(choice(toploop('/entity_designator', ','), 'others', 'all'), ':'), - line('/entity_class', 'is', 'expression', ';'), -), - -url_map = [ - 'entity_class': 'https://www.google.com/#q=vhdl+entity+class', - '(attribute) identifier': 'http://en.wikipedia.com/wiki/VHDL' -] -) \ No newline at end of file diff --git a/syntrax_scripts/style.ini b/syntrax_scripts/style.ini deleted file mode 100644 index 85ce17f..0000000 --- a/syntrax_scripts/style.ini +++ /dev/null @@ -1,31 +0,0 @@ -[style] -line_width = 3 -outline_width = 3 -padding = 5 -line_color = (0, 0, 0) -max_radius = 29 -h_sep = 17 -v_sep = 9 -arrows = False -title_pos = 'tl' -bullet_fill = (255, 255, 0) -text_color = (0, 0, 0) -shadow = True -shadow_fill = (0, 0, 0, 127) -title_font = ('Sans', 22, 'bold') -[hex_bubble] -pattern = '^\w' -shape = 'hex' -font = ('Sans', 14, 'bold') -fill = (255,0,0,127) -[box] -pattern = '^/' -shape = 'box' -font = ('Sans', 14, 'bold') -text_color = (100, 100, 100) -fill = (136, 170, 238) -[token] -pattern = '.' -shape = 'bubble' -font = ('Times', 16, 'italic') -fill = (0, 255, 0, 127) \ No newline at end of file