Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Activity
    Ulf Riehm
    @ukubauka

    @djencks_gitlab

    Ok, sorry. Let me explain that a little better.
    We have 1 repository, which holds

    /Manuals (What antora would call a "component")
    /Manuals/Extrusion (What antora would call a "module")
    /Manuals/Extrusion/Motor-Manual.adoc
    /Manuals/Extrusion/Screw-Manual.adoc
    /Manuals/Clamp/Timing-belt-Manual.adoc
    /Manuals/Clamp/Mold-interface.adoc

    but also
    /Automation (we would move that into another repository, actually, its another team...)
    /Automation/Classes/Motion-Control/Variables.adoc
    /Automation/Classes/Heating/Controls.adoc

    but also
    /Commons
    /Commons/Icons/...
    /Commons/Settings.adoc (what antora would call a "partial")

    All of the manuals and automation docs (what antora would call "pages") include the //commons/settings.adoc to control their appearance and behaviour when we transfer them to pdf's using asciidoctor-pdf. Also we refer to the iconsdir alike.
    Now, how do we get that to antor aso we can use the repository in BOTH ways, that is as source for pdf's and also as a website. Maybe I can't.

    David Jencks
    @djencks_gitlab
    @ukubauka ok, what is in the included partials you mentioned?
    I'm wondering if some of the problems are that plain asciidoctor and Antora syntax for reference targets is different.
    Setting an asciidoctor attribute in an included file or in the playbook or component descriptor should have the same effect in Antora.
    Ulf Riehm
    @ukubauka
    @djencks_gitlab the partials hold values for predefined attributes (such as toc, sectnums, etc ...) but also plenty of "shortcuts" e.g. using an attribute :1: to represent a unicode encircled "1". I can see how i would place them in a partial family in an antora module, but not how to create partials which are accessible for all modules AND at the same time the adocs work without running it through antora, e.g. in a firefox plugin.
    David Jencks
    @djencks_gitlab
    From that I think the main problem you have is the reference syntax difference.
    Ulf Riehm
    @ukubauka
    yes
    David Jencks
    @djencks_gitlab
    If you use antora style references, they aren't going to work in a browser plugin without a really major development effort.... you'd basically be writing a "live antora" system.
    I think there's a similar problem with asciidoctor-pdf, but I think it's much more tractable.
    Ulf Riehm
    @ukubauka
    Well, the plugin is king for reviewing what you write. You dont want to run it through antora to find out there is a typo in an include:: or image:: or a blank which kills the table or whatever... Also antora would be on a pipeline somewhere in a datacenter and I dont want every writer to work it through locally. So how would he check his result easily? We are a machine building company... you can not imagine the efforts it took us to understand the first 0,5% of git.
    David Jencks
    @djencks_gitlab
    I would like @mojavelinux's opinion on this, but I think it would be only a moderate amount of work to (1) have antora export some aspects of the content catalog and (2) provide an asciidoctor extension or plugin to interpret Antora style reference correctly.
    My experience is that the chrome Asciidoctor plugin gives a useful but incomplete preview, and that running Antora locally with an "author mode" playbook for the part you're actually working on is quick and easy for a complete view of what you'll get.
    I'm not sure how easy it is to add extensions/plugins to the asciidoctor browser plugins, but it wouldn't be hard to write something to syntax-check Antora references, even if they aren't resolved.
    Ulf Riehm
    @ukubauka

    Ok lets mull it over. Thanks for the response. Your suggestion would have allow (1) to have a single source for two different backends (2) enhance the referencing in asciidoctor.

    True, we could make "author playbooks"

    Dan Allen
    @mojavelinux

    but I think it would be only a moderate amount of work to (1) have antora export some aspects of the content catalog and (2) provide an asciidoctor extension or plugin to interpret Antora style reference correctly.

    exactly. And when parsing AsciiDoc, Antora works exclusively via Asciidoctor extensions, so all of it can be replicated outside of Antora (provided you have all the metadata you need).

    I'm not sure how easy it is to add extensions/plugins to the asciidoctor browser plugins

    it's not hard. there is a field in the configuration page for them

    You dont want to run it through antora to find out there is a typo in an include:: or image:: or a blank which kills the table or whatever.

    I think you do, because otherwise you won't be totally sure there isn't an error. but that's just my (strongly held) opinion.

    Dan Allen
    @mojavelinux

    I'm wondering if some of the problems are that plain asciidoctor and Antora syntax for reference targets is different.

    they are different, but what Antora does is not non-standard. it uses the standard extension mechanism in Asciidoctor to enhance the syntax (to make it more context aware). we are very careful not to modify AsciiDoc, but rather to channel everything through extensions.

    David Jencks
    @djencks_gitlab
    So, IIUC, for the browser scenario, a fairly easy although partial first step would be to write extensions for the asciidoctor.js browser plugin to (1) parse and verify antora reference syntax and (2) for references into the same component/version, translate to links into the antora source tree. This wouldn't completely work for distributed components, but would help otherwise.
    David Jencks
    @djencks_gitlab
    My impression is that asciidoctor-pdf is a pdf renderer for ruby asciidoctor... how plausible is it to run this renderer through Opal and then use it in Antora (presumably with something like a UI-free pipeline)?
    Dan Allen
    @mojavelinux

    how plausible is it to run this renderer through Opal and then use it in Antora

    not likely, and likely impossible. that's what asciidcotor-pdf.js is for. all node

    btw, the exporting of the content catalog is already something i've been exploring for sharded sites (like main and archive). we could continue to build on that for author mode tools
    danyill
    @danyill
    @ukubauka several users here do produce PDF as well and use Antora. The openSUSE documentation does that. See the website. This is done using asciidoctor-pdf and it would take some effort to fully understand it, but you could start with the Makefile
    I do think that asciidoctor-pdf.js has a bright future with Antora but for a really clean integration some architecture is required but there has already been some good discussion on an issue: antora/antora#349
    David Jencks
    @djencks_gitlab
    I've seen that issue for ages but had no idea about the https://github.com/Mogztter/asciidoctor-pdf.js project. I added a comment to the issue :-)
    Dan Allen
    @mojavelinux
    thanks @djencks_gitlab
    Dan Allen
    @mojavelinux
    :confetti_ball:
    David Jencks
    @djencks_gitlab
    After spending half an hour looking for the issue for antora/antora-ui-default!56 and realizing there wasn't one I opened a new one antora/antora-ui-default#107.
    Dan Allen
    @mojavelinux
    you're absolutely right. thank you for closing that gap
    (could be why we keep forgetting about it)
    David Jencks
    @djencks_gitlab
    :-) I also have an architectural question there... I've been playing with pdf generation...
    Pi3r
    @PierreR
    I am currently trying to fix algolia indices to include breadcrumbs titles.
    Is there any pointer on a valid/good Algolia config.json for Antora site based on the default UI ?
    Thanks
    Vincent Smit
    @vincent-smit
    He guys, does anybody know an alternative to making a block [%collapsible]?
    François Violette
    @fviolette
    Pending antora/antora#522, maybe like this: https://bcouetil.gitlab.io/academy/BP-asciidoc.html#dropdown-code-snippet
    Alexander Schwartz
    @ahus1
    If you are using IntelliJ and the AsciiDoc plugin: I've added Antora support to the latest preview releases (0.30.26 onwards). It pre-populates imagesdir, examplesdir etc. This way it will be easier for authors to write content with references inside the local antora module.
    To read more: https://github.com/asciidoctor/asciidoctor-intellij-plugin/wiki/Antora-support
    I wonder if any user wants to give it a trial run, get a pre-release here: https://github.com/asciidoctor/asciidoctor-intellij-plugin/releases
    Once I receive some feedback from Antora users, I'll publish this release to the regular channels.
    Feel free to open issues on the GitHub repo of the plugin.
    François Violette
    @fviolette
    Thanks a lot! Will give this a try this weekend.
    Dan Haywood
    @danhaywood_gitlab
    @ahus1 - nice to some initial support for Antora in your plugin. As a first bit of feedback: setting "examplesdir" attribute doesn't really help, because in Antora the reference is something like:
    include::example$test.java[tags=e1]
    ie, the "example$" family needs to be understood.
    In the wiki you have:
    include::{examplesdir}/examples/test.java[tags=e1]
    which the plugin will understand, but Antora won't, I suspect.
    more detail on families is here: https://docs.antora.org/antora/2.2/component-structure/#family-directories
    Alexander Schwartz
    @ahus1
    @danhaywood_gitlab - according to https://gitlab.com/antora/antora/blob/master/packages/asciidoc-loader/devdocs/architecture-guidebook.adoc the loader fills the attribute {examplesdir} with "example$". I've also seen projects like the camel docs using this attribute, for example here: https://github.com/apache/camel/blob/master/docs/user-manual/modules/ROOT/pages/walk-through-an-example.adoc
    From Antora's point of view both will work. From the plugin's point of view only {examplesdir} is supported for now (that is, until I can teach Asciidoctor ruby to support this syntax).
    David Jencks
    @djencks_gitlab
    @ahus1 Do you know which parts of Asciidoctor ruby are used in the intellij plugin? Antora modifies the html5 generator to decode antora reference syntax; I might be able to figure out how to do that in ruby. Is something else used in the editor?
    Alexander Schwartz
    @ahus1
    @djencks_gitlab - the Ruby part (actually AsciiDoctorJ) is used to create the HTML for the preview (on the right). For autocomplete and navigation support in the editor (on the left) it's plain Lexing/Parsing using the IntelliJ SDK. I already have an Idea on how to make it work for the editor, but I could definitely use some help for the (J)Ruby part to make it work in the preview.
    I can walk you through the code. To have a look what's happening already have a look at https://github.com/asciidoctor/asciidoctor-intellij-plugin/blob/master/src/main/java/org/asciidoc/intellij/AsciiDoc.java ... initWithExtensions() prepares Asciidoctor instances in various variations, and render() finally converts AsciiDoc to HTML.
    There is always the chance of monkey-patching with ruby AFAIK. Some of the "Extensions" I include already do this.
    Discussion is a bit out-of-scope for this antora-users chat, I suggest we could continue the discussion in a GitHub issue. Please dare to create an issue with the asciidoc-intellij-plugin.
    David Jencks
    @djencks_gitlab
    @ahus1 I added a comment to the issue you've been using.
    Dan Allen
    @mojavelinux
    @ahus1 the guidebook is out of date regarding the resource referencing. the docs are currently the authority
    the attributes were a first attempt at referencing, but we quickly realized it was too limited. so now there is a universal referencing system in Antora as @danhaywood_gitlab cited.
    Dan Allen
    @mojavelinux
    sorry for the confusion