Asciidoctor :: Discussion

Does Asciidoctor silently abondon docbook?

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

24 messages Options

getreu

Re: Candidate definition for "transformation conformance

It seems to me that I did not express myself clear enough. I try better:
First I describe "what" I believe should be the goal, then in the second part I will argue the "why" confronting your arguments.

(@mojavelinux: "This is where we disagree. I do not consider the pixel-perfect presentation to be part of compliance." This is not what I meant, please see 3.)

1. Goal: "All back-ends should be interchangeable."

This means that you can render a given .adoc with whatever asciidoctor-backend and with docbook
and publish directly.

Example: I write a scientific essay and use "asciidoc -b docbook" for my editor (who uses "fop").
"asciidoctor -b html5" will render my bog and with "asciidoctor-fopub" or "asciidoctor-pdf"
the user can download a pdf rendition of my essay.

2. We need one presentation reference;
"asciidoctor-fopub" should be that presentation reference (back-end, here toolchain).

- .adoc syntax and .xml syntax describe the same semantics.
- The docbook toolchain defines the link between semantics and presentation:

INPUT REFERENCE OUTPUT A
Semantics(adoc) ---> Semantics (xml) ---------[docboc]----> presentation(pdf/html/ebook)

(Please see 2. post for the why).

3. Definition of "transformation conformance". It defines how we can measure the degree of similarity
between the output of a back-end with the reference back-end. We need this to support the goal 1.

INPUT REFERENCE OUTPUT A
Semantics(adoc) ---> Semantics (xml) ---------[docboc]----> presentation(pdf/html/ebook)

INPUT OUTPUT B
Same semantics (adoc) ------[asciidoctor-xzy]-----> "Similar" presentation(pdf/html/ebook)

Candidates:
/1/ "Every back-end should consistently produce output that represents the content as
faithfully as possible (thank you @eskwayrd)".
+ True
- Not helpful to measure similarity of 2 backend's output.
- "faithfully as possible" not quantifiable.
- "faithfully refers to semantics, but it must refer to a (reference) presentation.

/2/ "The back-end asciidoctor-xyz is 'transformation conform' when its OUTPUT B is 'similar'
to REFERENCE OUTPUT A.
'Similar' means, all graphic Unicode-code-points in the body representation are present and in the same order."
+ quantifiable
+ test can be automated
- covers only a subset of what "similar" means to a human.

Please, before rejecting these goals wait for my second post about the "why". I have to leave for now.
Best

Jens Getreu

mojavelinux

Re: Candidate definition for "transformation conformance

Administrator

Jens,

Thank you for the additional clarification. I want to make it clear that
I'm not rejecting your goals. I'm simply saying that we don't share the
same goals (and there's nothing wrong with that; diversity is good).

The following statement is completely in alignment with the project's goals=
:

"This means that you can render a given .adoc with whatever
asciidoctor-backend and with docbook and publish directly."

Yes! We want the AsciiDoc content to serve as the canonical sources of
information and semantics so it can be transformed in whatever way your
heart or business needs require. That's the grand vision of AsciiDoc.

However, this statement is not my goal:

"We need one presentation reference; "asciidoctor-fopub" should be that
presentation reference (back-end, here toolchain)."

I don't think we need one presentation reference. I think we need the
opposite, presentation flexibility. To each their own. And I certainly
don't want to be tied with the DocBook toolchain. I'm trying to get away
from the DocBook toolchain as fast as I can (while of course leaving the
option on the table for people to use it).

I promise that I'm not dismissing your idea. In fact, I support it. It's
just not the agenda that I'm pursuing as part of the core modules. If some
sort of presentation consistency is pursued, it needs to happen downstream.
Core is all about presentation flexibility and diversity. If something is
limiting your effort, I want to know about it and fix it.

Cheers,

-Dan

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

mojavelinux

Re: Candidate definition for "transformation conformance

Administrator

In reply to this post by getreu

One thing I want to add. I realize Asciidoctor PDF isn't quite there yet in terms of compliance. But we're getting closer every day. I think the right thing to do is to continue working towards that goal rather than getting distracted with other short-term solutions. Once the gaps are closed in Asciidoctor PDF, it's a clear winner because it's so much easier to customize and hack on.

-Dan

On Sun, Sep 25, 2016 at 3:09 AM, Dan Allen <[hidden email]> wrote:

Jens,

Thank you for the additional clarification. I want to make it clear that
I'm not rejecting your goals. I'm simply saying that we don't share the
same goals (and there's nothing wrong with that; diversity is good).

The following statement is completely in alignment with the project's goals=
:

"This means that you can render a given .adoc with whatever
asciidoctor-backend and with docbook and publish directly."

Yes! We want the AsciiDoc content to serve as the canonical sources of
information and semantics so it can be transformed in whatever way your
heart or business needs require. That's the grand vision of AsciiDoc.

However, this statement is not my goal:

"We need one presentation reference; "asciidoctor-fopub" should be that
presentation reference (back-end, here toolchain)."

I don't think we need one presentation reference. I think we need the
opposite, presentation flexibility. To each their own. And I certainly
don't want to be tied with the DocBook toolchain. I'm trying to get away
from the DocBook toolchain as fast as I can (while of course leaving the
option on the table for people to use it).

I promise that I'm not dismissing your idea. In fact, I support it. It's
just not the agenda that I'm pursuing as part of the core modules. If some
sort of presentation consistency is pursued, it needs to happen downstream.
Core is all about presentation flexibility and diversity. If something is
limiting your effort, I want to know about it and fix it.

Cheers,

-Dan

--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

getreu

Re: Candidate definition for "transformation conformance

Dan,

I am glad that we share this:

> 1. Goal: "All back-ends should be interchangeable."
> This means that you can render a given .adoc with whatever asciidoctor-backend and with docbook
> and publish directly.

Coming to our difference: In my understanding having *one presentation reference* and *transformation conformance* is the direct consequence sine qua non to the above goal!

It does not require much. But this should just not happen:
- as shown in the Section 5, “The Heartbleed Vulnerability” (rendition with `asciidoctor-fopub`)
- as shown in the The Heartbleed Vulnerability (rendition with `asciidoctor -b html5`)

Asciidoctors back-ends are better in many ways and offer a lot more features, but they also should produce the
same Unicode codepoints than the Docbook tool-chain does. For the rest, there is no limit to innovation!

I believe we need a concept of *transformation conformance* we stick to. Otherwise saying

"`If the need arises, you can make full use of the huge choice of
tools available for a DocBook workflow using Asciidoctor’s DocBook
converter. That’s why mapping to an enterprise documentation format
like DocBook remains a key use case for AsciiDoc.`"

is just an empty promise.