Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/de-jcup/asp

Asciidoctor Server Protocol
https://github.com/de-jcup/asp

asciidoc asciidoctor asp protocol server

Last synced: about 1 month ago
JSON representation

Asciidoctor Server Protocol

Awesome Lists containing this project

README 

        
= ASP - Asciidoctor Server Protocol



[frame=none,grid=none,cols=2]

|===

a| image::https://github.com/de-jcup/asp/actions/workflows/gradle.yml/badge.svg[Java CI with Gradle,link=https://github.com/de-jcup/asp/actions/workflows/gradle.yml]

a| image::https://img.shields.io/lgtm/alerts/g/de-jcup/asp.svg?logo=lgtm&logoWidth=18[link="https://lgtm.com/projects/g/de-jcup/asp/alerts/"] 

|=== 



== About 



ASP stands for `AsciiDoctor Server Protocol` - a simple communication protocol between a client and a 

asciidoctor server instance which will do all Asciidoctor operations. So its a little bit similar to LSP 

where the language parts are central provided by a server instance.  



- Main project page: https://github.com/de-jcup/asp

- Issue tracking done at https://github.com/de-jcup/asp/issues

- Wiki: https://github.com/de-jcup/asp/wiki



== Why a server?



With https://github.com/de-jcup/eclipse-asciidoctor-editor[AsciiDoctor Editor for eclipse] it was extreme hard to handle

the OSGI depencencies in conjunction with asciidoctor/asciidoctorj and JRuby

(see https://github.com/de-jcup/eclipse-asciidoctor-editor/issues/213) 



So instead of handling this always again with new dependencies etc. working with OSGI this project was initiated, to 

become a standalone solution, which can be used by different editors without spawning always new processes but instead

reuse an already started server instance which shall be very much faster than doing a new process communciation to an

installed variant.



The editors shall only delegate their conversion tasks to server side and have a communication layer to the server 

which will produce information about converted output locations (or errors).



=== Benefits

- Independent from real installation, can be used ony systems were developers have not possiblity to install 

  asciidoctor

- Comes up with standard tool setup (will have HTML, docbook and PDF support)

- Can be used from multiple IDE integrations (eclipse-asciidoctor, ... more ...)

- Provides a client library to use the server, so convenient



== Why such an "old school" tcp client/server approach and no standard REST server ?

It started with a `spring boot` application, with rest controller etc., very nice and convenient, but...

spring bootJar did not correctly work with `asciidoctorj` + `jruby`.



Providing an own fat jar solution in combination with `spring boot` did work after time, but I got at least 59 MB 

at the very first beginning - this was too much.



Also spring boot comes with many dependencies - and asciidoctorJ has got itself

many. To prevent cross site effects the client server protocol should be as 

simple as possible and has nearly no more dependencies.

  



== How should editors/tools use this server?



=== Overview

image::doc/images/overview.png[]



=== Details



==== ASP-server-asciidoctorj

You can use ASP server either as an external process or as an embedded server.



===== As an external process

For this case a specialized launcher was created. Just use `ExternalProcessAsciidoctorJServerLauncher` as done in 

https://github.com/de-jcup/asp/blob/master/asp-doc/src/test/java/de/jcup/asp/example/ExternalProcessExample.java[ExternalProcessExample.java] and

https://github.com/de-jcup/asp/blob/master/asp-doc/src/test/java/de/jcup/asp/example/ExternalProcessWithDebugOutputExample.java[ExternalProcessWithDebugOutputExample.java] 



===== As embedded server

Same as external variant, but use `EmbeddedAsciidoctorJServerLauncher` as launcher. For examples look into integration tests.