Should we deprecate this repository ?

[ggrossetie]

• Deck.js backend has been replaced by asciidoctor/asciidoctor-deck.js
• reveal.js backend has been replaced by asciidoctor/asciidoctor-reveal.js
• Bespoke.js backend has been replaced by asciidoctor/asciidoctor-bespoke (the README is not up to date)

So the only remaining backends in this repository is DZSlides but we could extract it in itsown repository (in order to deprecate this repository) ?

Also I think we should migrate issues if there are still relevant.

Manpage, DocBook 4/5 and HTML 5 backends had been integrated into core, so I'm not sure if we want to keep them ?

What do you think ?

[mojavelinux]

This repository is still relevant, but the focus (an possibly title) needs to change. The purpose of this repository is to provide reference templates for the built-in converters that can be used as a starting point for customizing the output. You are correct that the slideshow templates don't belong here.

I'd say that the first action is to pull out the dzslides templates into a separate repository (though, honestly, I'd rather just put them in a branch and take them out of master because I'm not investing in dzslides anymore). The section action is to rename it to something like asciidoctor-reference-templates so it's clear they exist only as a reference.

[arBmind]

I still use dzslides and just realized the templates do no longer work with the latest asciidoctor releases. (1.5.5. is the last version that works)

[mojavelinux]

My feeling about the dzslides templates is that we shouldn't continue to invest in them. The reason I say that is because Bespoke covers everything that dzslides does, but it has the added benefit that it's actually distributed as a stable release in official channels.

We had built the dzslides templates to work with a forked version of dzslides, so it was all very much an experiment. I don't want to break anyone's slides, so what we might decide to do is accept some contributions to get them cleaned up to work with 1.5.6 and then put them into a branch so it's clear it's are archived.

[voidmain]

This issue is pretty old, but I've been working with Asciidoctor 2.0.10 and the HAML templates and there are plenty of issues. Things that used to work with 1.x versions of Asciidoctor no longer work. My suggestion would be to fix this repository rather than kill it.

One example issue I've found is the @text field for inline_anchors. If you have this adoc definition:

<<Some Anchor>>

The output from the HAML template is now:

<a href="#some-anchor">[some-anchor]</a>

I've looked a bit at the core Asciidoctor code and it looks like various things have changed and the internal converters aren't using the same process as the templates here. I'd be happy to update the HAML templates and resubmit them, but it's really challenging because I can't find a clear set of documentation about what is passed to the HAML template.

If there is documentation anywhere, point me at it and I'll go to town. Otherwise, I'll have to hack up the internal classes to get what I need.

[mojavelinux]

My suggestion would be to fix this repository rather than kill it.

If someone wants to come forward to maintain the repository, I'd support that effort and allow it to continue on in this organization. However, I do not have time to maintain it myself.

[voidmain]

I might be up for that. I'm slowly learning all the core classes in Asciidoctor. As an example, here's the fix for the inline_anchor:

- case @type
- when :xref
  %a(href=@target)<=(@text || (@document.find_by(id: @target[1..-1])[0] ? @document.find_by(id: @target[1..-1])[0].title : 'BROKEN LINK'))
- when :ref
  %a(id=@target)
- when :bibref
  %a(id=@target)>
  =%([#{@target}])
- else
  %a(href=@target){:id=>@id, :class=>role, :target=>(attr :window), :title=>(attr :title)}=@text

I prefer the error String than wrapping the missing xref id in square-brackets. I'll see how things progress and possibly report back.

[mojavelinux]

I might be up for that.

I'm excited to hear that!

I prefer the error String than wrapping the missing xref id in square-brackets.

If this repository continues on, the behavior of these templates should not differ from the built-in HTML converter. You're free to create a separate repository of templates that do, it just can't be these. The assumption is that these templates serve as a copy of the built-in HTML converter in the form of templates, to use as a jumping off point.

If you want a log message to be added, then it's something we should discuss in core.

[voidmain]

Fair enough.

One comment I'll make is that it really seems like this repo should deprecated, merged into core, and simplified. Hardcoding output logic in the Ruby code in core seems like it is less flexible. Also, when auxiliary repositories like this fall behind core, it's just more work to manage, hence your lack of time to fix these templates. My suggestion would be something along these lines:

• Drop HAML, SLIM and stick with ERB to start (or whichever you like best). There really is little need to cater to multiple template engines.
• Create the correct templates based on core
• Delete core's hard-coded logic and only support templates
• Provide a TemplateEngineFactory and TemplateEngine interface in core (might already exist) that anyone can override to support whatever random templating engine they like (solves problems like: "Why don't you guys support SpankyTemplates? I'll never use this unless you do!")
• Default versions of the interfaces are for ERB
• Ship the ERB with the next version of core
• Unit test as usual -- asserting on the output from the new templates
• Bask in the glory of templates that are always correct and easy for anyone to tweak!

Just a thought. :)

[r0ckarong]

One comment I'll make is that it really seems like this repo should deprecated, merged into core, and simplified. Hardcoding output logic in the Ruby code in core seems like it is less flexible. Also, when auxiliary repositories like this fall behind core, it's just more work to manage, hence your lack of time to fix these templates.

This is exactly what I've been banging my head against for the last six hours. The hardcoded logic means there are no working templates once the code moves on. Then you need to understand the entire converter to get an idea how the templating could work.

I think this repository should definitely be flagged as deprecated and "don't come here for anything useful" because if you don't already know what the code does the templates here are absolutely useless.

[mojavelinux]

I'm sorry to hear that you've struggled in an attempt to use these templates. The files in this repository are here as a reference for what a template looks like. I volunteered to publish them as a resource for the community to share. For a time, I tried to keep them in sync with the core processor, but it was too much work. Since then, other community members have come along and improved on them. But they remain an example, nothing more.

You can state that you don't find these templates helpful. But do not come into a volunteer project like Asciidoctor making demands. And please respect the work of others. Saying something that was created by the community is "absolutely useless" is hurtful, discourages others from contributing, and is not welcome here.

Putting templates directly into core adds layers that are unnecessary and slows down the processor. That's not a direction we will be taking.

I'm open to trimming down this repository to fewer examples so that they're easy to follow, but someone needs to come forward to do the hard work. It takes time and effort and it's not my focus right now. What I can do is improve the disclaimer on the repository to make it clear that these are examples only and not meant to replicate the output of the built-in converters.

[r0ckarong]

But do not come into a volunteer project like Asciidoctor making demands.

Saying something that was created by the community is "absolutely useless" is hurtful,

but someone needs to come forward to do the hard work.

It takes time and effort and it's not my focus right now.

I have typed out this comment in about a dozen ways before now. If I respond to anything:

I echoed the sentiment of the original reporter of this issue that this repo was already outdated 4 years ago. I come from an entire day (again) of reading threads upon threads on the AsciiDoctor forum about users who do their best to try and understand how it should work with the few resources provided; coming away broken.

How would I be in the position to make demands? I am trying to make a living and not having to explain to my boss why I need to take several months off to learn how to be a Ruby programmer.

What I am trying achieve here is to reach a person to make them see that the creature they have unleashed upon the world is untamable for many of us and we would like to know how to reign it in. People love AsciiDoc, they love AsciiDoctor, they love Antora. You're the person to blame for that love because of all your hard work. So, sorry, you're also the person to blame when that doesn't work out right because there simply isn't a commitee that does these things any other way.

I don't doubt your efforts, Dan. I believe in you and that's why I stick with AsciiDoctor and want to keep using and pushing it across industries. I also believe this can be done better but how is someone who is interested and doesn't come from a purely programming background going to contribute here if this is all so incredibly cryptic?

For what it's worth, I am offering my help to improve this. As many before me have. I am serious. What I need though is input because I am not a Ruby person and won't be for the foreseeable future. If you can provide me with raw stuff I will try, apply and document.

This is all I can offer. This is all I "demand".

[mojavelinux]

What I am trying achieve here is to reach a person to make them see that the creature they have unleashed upon the world is untamable
you're also the person to blame when that doesn't work out right
this is all so incredibly cryptic
I "demand"

I do not deserve to be spoken to this way, nor does anyone else in this community. These comments are blatantly disrespectful, accusatory, and insulting. And they were posted after I specifically asked to keep the conversation respectful, which makes this a personal and direct attack. There is NO place for that kind of diatribe in this community. The author of these comments has been suspended from the Asciidoctor project for a period of 30 days as a warning. If the behavior continues, that suspension will become permanent.