search

asciidoctor / asciidoctor-latex

:triangular_ruler: Add LaTeX features to AsciiDoc & convert AsciiDoc to LaTeX
http://asciidoctor.org
Other
111 stars 26 forks source link

Proposal to promote project to asciidoctor-latex-plus #67

Open mojavelinux opened 6 years ago

mojavelinux commented 6 years ago

I'd like to propose that this project be promoted (i.e., renamed) to asciidoctor-latex-plus. I support the idea of improvising on the AsciiDoc syntax to create a dialect that appeals to a more LaTeX-minded audience, and I certainly want to encourage that innovation. However, I'm concerned that by calling it asciidoctor-latex, we've left a gap for the user seeking a faithful conversion of vanilla AsciiDoc to LaTeX. LaTeX is a very important format in this toolchain and we want to do the basics well.

By renaming the project to asciidoctor-latex-plus, it leaves room for a more "plain Jane" asciidoctor-latex converter. This converter would use as few LaTeX packages as possible and only convert standard blocks to their LaTeX equivalent. I envision it building on the manpage converter in core, which is going to provide a useful starting point as it produces output in the same markup family (non-XML). (There would be no HTML output in asciidoctor-latex).

It may even happen that asciidoctor-latex-plus eventually builds on asciidoctor-latex, no longer having to worry about converting the basic elements. Instead, it can focus on the extended elements. In that regard, I think it will make more room for creativity to flourish in asciidoctor-latex-plus.

If there's agreement with this proposal, I'd be happy to help set up the two projects and get the ball rolling. I'd be looking for someone who is interested in completing the converter and also someone to maintain it. (My one request is that we have good tests for it).

tribut commented 6 years ago

Sounds reasonable.

jxxcarlson commented 6 years ago

I agree with @mojavelinux that there are two separate needs and therefore having two projects make sense. As I see it, asciidoctor-latex-plus is indeed asciidoctor-latex plus some other things. Therefore, if the projects could be set up so that the latter can build on any changes to the former, that would be great, since it would allow me to work with a better foundation. For reasons of my own interests and abilities, I think it would be best to have someone other than me be the lead on the base (vanilla) version. Of course I would be glad to help to the extent that I can.

I see two benefits from this. One is that by having a really good asciidoc-latex (complete coveragte!), one will have a way to generate very high quality pdf output for asciidoc docs. The other is that it will make my own work much easier.

prudhomm commented 6 years ago

sounds good. we can definitely provide tests :)

jxxcarlson commented 6 years ago

I am in complete agreement with this proposal, and especially look forward to what is said in the paragraph below.

Let’s do it!

On Jul 27, 2017, at 3:57 AM, Dan Allen notifications@github.com wrote:

It may even happen that asciidoctor-latex-plus eventually builds on asciidoctor-latex, no longer having to worry about converting the basic elements. Instead, it can focus on the extended elements. In that regard, I think it will make more room for creativity to flourish in asciidoctor-latex-plus.

mojavelinux commented 6 years ago

Great! Thanks for the feedback. I'll start working on this change this weekend. It shouldn't affect any outstanding work as GitHub preserves all the data. The only change is that when we create a new repository at asciidoctor-latex, you'll need to update your git remote URL to asciidoctor-latex-plus. But I'll let you know as we go along.

mojavelinux commented 6 years ago

I'm going to need to push this migration to next weekend. I have family coming into town and I ran out of time this weekend to get it started. I'll be back ;)

mojavelinux commented 6 years ago

Here's my proposal (when I get to it):

The main open question is how to structure the converter. Clearly, we want a concrete converter class which can be extended, perhaps named LaTeXConverter. But should we create a monolithic class like the ManpageConverter, or should we create a class for each node? So far, I've been implementing converters as a single class with methods to handle each node, but I'm open to new approaches.

The converter should not extend the built-in converter class since that is meant to be internal. Instead, it should extend or include the Converter class, which is the proper extension point. In fact, there should be no direct reference to any converter-related class in core except for Converter.

In terms of goals and policies, the converter should only convert AsciiDoc to LaTeX. In doing so, it should not introduce any new syntax into AsciiDoc, nor should it do any preprocessing. Instead, it should faithfully map the semantics of AsciiDoc to the semantics of LaTeX. Enhancements to the notation belong in "plus", as that will become the experimental playground for new ideas that may find their way back into core.

The output the converter produces should only require the most minimal LaTeX toolchain as possible, within reason. In other words, if someone has the LaTeX toolchain (which the README should document how to install or at least what's expected), they should be able to convert the .tex file without having to get a lot of extra / optional LaTeX packages. If they need more stuff included in the header, they can rely on docinfo files, just like with other formats.

ggrossetie commented 6 years ago

The output the converter produces should only require the most minimal LaTeX toolchain as possible, within reason.

👍 It will also be easier to port this converter to JavaScript.

tribut commented 5 years ago

Are there any plans to proceed on this? I have a couple of improvements I want to make to asciidoctor-latex and I'm not sure if waiting for this split to happen would save everybody time...