Change convert return type

[lordofthejars]

Currently convert method returns a String, this works for text backends (html, docbook) but it doesn't work for binary backends like pdf. For this reason we need to change the convert method to something like:

public <T> T convert(Content, Options, Class T)

[abelsromero]

Wouldn't it be simplier to use some OutputStream? That way API consumers can choose to write/convert it as they like, also having to set the Class T param everytime feels a bit tiresome to me.

What do you think?

[johncarl81]

👍 I approve of returning an OutputStream.

[ysb33r]

I see a problem where multiple output files need to be created from a single input source - multi-page HTML would be a good example. What if it just returns an Object, which can then be interpreted by a Writer, which in turn can decide how to create the output. If asciidoctorj can provide a

interface Writer {
  void write( Object src, File target );
} 

which maps to the ruby Asciidoctor::Writer module then, then returned output can simply be given to the writer.

[mojavelinux]

I'm not quite sure this is the same use case. I agree we probably need the Writer interface, but that's more for the converter than for the main API. The main API is supposed to be getting the final converted result. If you produce multiple documents into memory, then I imagine the OutputStream would be a MultiOutputStream. That's how you'd handle getting back a collection of documents. But what creates those documents is the converter.

[robertpanzer]

I have the impression that inventing sth like a Writer and a MultiOutputStream could solve other problems as well:
If AsciidoctorJ could make sth like a Writer accessible to the converter it would be possible to catch all the generated output.
(In fact with my limited Ruby knowledge the Ruby Writer looks like a FileOutputStream, you pass a stream or a filename and content and this gets appended.)

Because at latest when you generate multi file output the option to not write to a file but directly return the content is not obeyed.
A Writer that acts according to these options could either directly write to a file or to memory)
But this is just a very vague idea that I have.
(And it would change the programming model of a converter.)

Am 20.05.2015 um 21:50 schrieb Dan Allen notifications@github.com:

I'm not quite sure this is the same use case. I agree we probably need the Writer interface, but that's more for the converter than for the main API. The main API is supposed to be getting the final converted result. If you produce multiple documents into memory, then I imagine the OutputStream would be a MultiOutputStream. That's how you'd handle getting back a collection of documents. But what creates those documents is the converter.

—
Reply to this email directly or view it on GitHub.

[mojavelinux]

@robertpanzer You have the right idea. Asciidoctor checks to see if a converter implements the Writer interface and, if so, allows the converter to handle writing to disk or a stream. The Converter is available from the Document, so it's possible to get access to this information.

To move this forward, I think what we need is to look at this from a high level and create a table of the various scenarios we have. Just to seed it, here are the possible things a converter is going to want to toss back to the caller in some way:

• A String (in the case of a single HTML page)
• A binary object (in the case of the PDF converter)
• A collection of Strings (in the case of multi-page HTML)

It's important to try to understand how this data makes it back to the caller. It doesn't necessary have to be the return value, or the top-level type of the return value. But we need to think about the path the information takes back to the caller. Then we can understand the right choice for the API.

[rmannibucau]

If you can decide it from parameters having N methods would be far clearer than having a multi output return type - even in ruby btw.

[abelsromero]

we need is to look at this from a high level and create a table of the various scenarios we have

I think (agreeing with @rmannibucau) that not only should we look into the outputs, but also the inputs in order to see the whole picture. After reading this conversation a couple of time, it seems to me that this is becoming a review of all the Asciidoctor interface.
Shouldn't we list the methods and analyse them case by case? Not only thinking in terms of the interface but also in features. For instance, there are methods that allow to render all documents in a folder, would it be better to remove them or improve them?

[twasyl]

IMHO, it would be nice to have something like this:

public abstract class Writer<OUTPUT_TYPE> {

  abstract OUTPUT_TYPE convertAs(...);

  abstract String convertAsString(...);

  OutputStream getStream() {
    // ...
  }
}

And then implementations for all desired outputs (PDF, HTML, ...) like:

public class HTMLWriter<org.w3c.dom.Node> {
  org.w3c.dom.Node convertAs(...) { ... }

  String convertAsString(...) { ... }
}

And in the Asciidoctor interface you could have something like:

public interface Asciidoctor {
  convert(final Writer writer, ....);
}