Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [asciidoc-wg] AsciiDoc implementation for the Java/JVM ecosystem / project proposal

Hello Alexander,

thanks for your response.

"I didn't follow the discussion
regarding RustDoc; if you want to go into details, please provide a link
or some context."

RustDoc is the documentation tool for Rust, like JavaDoc or JsDoc for Java or _javascript_.
I was referring to this thread, especially this comment, mentioning it being a problem if some Rust standard tool inside the chain is built upon a very different (here: not Rust) language base, thus making that part of the standard build process:
This was an argument for *not* to use asciidoc syntax in RustDoc comments.

And that seems to be applicable for other build environments too, on-topic: Java resp. the JVM.
That's why I mentioned it here.

"As a user of AsciiDoc this allows you to pick the implementation that
best matches your output format or plugin needs."

"Given a source document and mulitple implementations, I assume they will
create differently styled PDFs and differently styled HTMLs."

Hmm that may be a problem, considering I want to change implementation due to some integration or API features, but wanting to keep the output style.
("Multiple implementations" is still about one ecosystem, or not?
We are not talking about exchanging a Java asciidoc tool with a python asciidoc tool here?)

The reason to supply a native JVM based asciidoc implementation is in my eyes to give Java developers the full power to create tools and plugins and orchestrate their toolchain in their native environment, without having to jump into a different language system.

To explain that from a practical point of view: As Java developers, trying to find an easily manageable way to maintain developer manuals and architecture doc, the Asciidoc Maven plugin and asciidoc-pdf were straightforward, while integrating even the Docbook toolchain was too much of a burden.
Only that we now brought Ruby somewhere into the formula felt not quite fine, in case we need to open the blackbox.

KR
Dirk


Alexander Schwartz <alexander.schwartz@xxxxxxx> schrieb am Do., 11. Juni 2020, 21:56:
Hello Dirk,

> This was when a very basic question arose:
> What indeed will be THE main -- and so most important - - benefit of
> the standardisation process?
> Will it indeed be the syntax, so to say the UI part of Asciidoc?
> Or will it be the standardised DOM/AST supported by an API, on which
> the syntax parser and the backend converters will work?
> [...]

here's my understanding: The AsciiDoc language specification will define
the syntax and the AST/ASG, see the current draft of the charter:
https://www.eclipse.org/org/workinggroups/asciidoc-charter.php

The TCK will provide test cases, and might also include a transformation
to one example HTML format (although that is not set in stone yet).

All compatible implementations - I assume there will be multiple - will
then be able to parse a document according to the same syntax. The value
of different implementations lies in how they provide access to
extensions to the AST/ASG and to different output formats.

Given a source document and mulitple implementations, I assume they will
create differently styled PDFs and differently styled HTMLs.

As a user of AsciiDoc this allows you to pick the implementation that
best matches your output format or plugin needs. When your requirements
change, you can change the implementation, but can continue to use your
AsciiDoc sources.  If you written your own (implementation specific)
plugins, you might need to rewrite them when you change implementations.

I hope this answers your question. I didn't follow the discussion
regarding RustDoc; if you want to go into details, please provide a link
or some context.

Best regards,
Alexander


--
Alexander Schwartz (alexander.schwartz@xxxxxxx)
https://www.ahus1.de

_______________________________________________
asciidoc-wg mailing list
asciidoc-wg@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/asciidoc-wg

Back to the top