Bug tracker link builder : macro, attribute ?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Bug tracker link builder : macro, attribute ?

Psyko
Hello,

I'm about to start using Asciidoc to write the doc of my software.
When referencing issues in my Bug tracker I'd like to avoid having to enter the complete url.
I would like to use something like  "bug:33"  that will be replaced by the following link "http://mybugtracker.com/issue/22[Issue 22]"

I tried to search how to do that but could not figure it.
Is this already covered by something I missed ?
Should I use macro ? If so, can I define them in my adoc files ?

Thank you
Reply | Threaded
Open this post in threaded view
|

Re: Bug tracker link builder : macro, attribute ?

Jeremie Bresson
As far as I know the macro cannot be defined inside an Asciidoc File (as you can do with LaTex [1]). You need to write some code. You can use in one of this programing languages:
* Ruby
* JavaScript (I am not sure about this one)
* One language of the JVM (Java, Groovy, ...)

What you will choose, depends on the build system you use to build your documentation.

We are a Java company using maven, so the choice was straight forward for us. There is an example of what you want to do java-extension-example (This is the twitter example, but this is really close to the issue-tracker use case).

[1] \newcommand{name}[num]{definition}
Reply | Threaded
Open this post in threaded view
|

Re: Bug tracker link builder : macro, attribute ?

Psyko
Awesome thanks. I'll take a deeper look at the project.
I'm building using maven and tycho so Java it will be :)
Reply | Threaded
Open this post in threaded view
|

Re: Bug tracker link builder : macro, attribute ?

mojavelinux
Administrator
Jérémie is correct, you need to write an inline macro. It's the perfect case for one.

The JBoss Tools team has written a macro for linking to an issue tracker that you can build on. See:


It would be great to pull a simplified version of this macro into the extensions lab {1} for reference.

-Dan


On Thu, Jun 9, 2016 at 11:56 PM, Psyko [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Awesome thanks. I'll take a deeper look at the project.
I'm building using maven and tycho so Java it will be :)


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Bug-tracker-link-builder-macro-attribute-tp4755p4760.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Bug tracker link builder : macro, attribute ?

mojavelinux
Administrator
In reply to this post by Psyko
Please note that you can write extensions in Ruby and still use them in Java (Maven or Gradle build). AsciidoctorJ is a Ruby environment, so you can load Ruby scripts into it. While it's possible to write extensions in Java, it is definitely a lot simpler to write them in Ruby. Your choice.

Cheers,

-Dan

On Sat, Jun 11, 2016 at 1:19 AM, Dan Allen <[hidden email]> wrote:
Jérémie is correct, you need to write an inline macro. It's the perfect case for one.

The JBoss Tools team has written a macro for linking to an issue tracker that you can build on. See:


It would be great to pull a simplified version of this macro into the extensions lab {1} for reference.

-Dan


On Thu, Jun 9, 2016 at 11:56 PM, Psyko [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Awesome thanks. I'll take a deeper look at the project.
I'm building using maven and tycho so Java it will be :)


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Bug-tracker-link-builder-macro-attribute-tp4755p4760.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



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



--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Bug tracker link builder : macro, attribute ?

Jeremie Bresson
Creating a generic issue Tracker macro is probably a challenge. For each tracker, you need to provide:

* An URL pattern
* A default Text pattern

The macro should be able to handle multiple trackers at the same time.

Examples:

== Bugzilla installed at the Eclipse foundation:
Issue Id is a number.

* Text: "Bug {id}"
* URL: https://bugs.eclipse.org/bugs/show_bug.cgi?id={id}

== GitHub
I think we would create one tracker for each project. Issue Id is a number.
For Asciidoctorj

* Text: "#{id}" or "asciidoctor/asciidoctorj#{id}"
* URL: https://github.com/asciidoctor/asciidoctorj/issues/{id}

And Asciidoctor.org:

* Text: "#{id}" or "asciidoctor/asciidoctor.org#{id}"
* URL: https://github.com/asciidoctor/asciidoctor.org/issues/{id}

== JIRAs
(See the JBoss Tools macro). Another example with the public Jenkins JIRA instance:
Issue Id is a String "JENKINS-35666"

* Text: "{id}"
* https://issues.jenkins-ci.org/browse/{id}

The way I see it for the moment, it would be nice to define a second parameter host or server.
issue:<id>[host, optional text]

At document level as many variables are defined as necessary (see the values above)
issue-url-eclipse
issue-text-eclipse
issue-url-jenkins
issue-text-jenkins

If no host is defined in the macro, the default variables "issue-url" or "issue-text" are used.

In the text you can write something like:

Check the related issues to this problem issue:0234[eclipse] or issue:JENKINS-35666[jenkins].
Please note that issue:ROASTER-105[jboss] is also relevant.
Reply | Threaded
Open this post in threaded view
|

Re: Bug tracker link builder : macro, attribute ?

mojavelinux
Administrator
Precisely what I had in mind. 👍

Cheers,

-Dan

On Mon, Jun 13, 2016 at 6:39 AM, Jeremie Bresson [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Creating a generic issue Tracker macro is probably a challenge. For each tracker, you need to provide:

* An URL pattern
* A default Text pattern

The macro should be able to handle multiple trackers at the same time.

Examples:

== Bugzilla installed at the Eclipse foundation:
Issue Id is a number.

* Text: "Bug {id}"
* URL: https://bugs.eclipse.org/bugs/show_bug.cgi?id={id}

== GitHub
I think we would create one tracker for each project. Issue Id is a number.
For Asciidoctorj

* Text: "#{id}" or "asciidoctor/asciidoctorj#{id}"
* URL: https://github.com/asciidoctor/asciidoctorj/issues/{id}

And Asciidoctor.org:

* Text: "#{id}" or "asciidoctor/asciidoctor.org#{id}"
* URL: https://github.com/asciidoctor/asciidoctor.org/issues/{id}

== JIRAs
(See the JBoss Tools macro). Another example with the public Jenkins JIRA instance:
Issue Id is a String "JENKINS-35666"

* Text: "{id}"
* https://issues.jenkins-ci.org/browse/{id}

The way I see it for the moment, it would be nice to define a second parameter host or server.
issue:<id>[host, optional text]

At document level as many variables are defined as necessary (see the values above)
issue-url-eclipse
issue-text-eclipse
issue-url-jenkins
issue-text-jenkins

If no host is defined in the macro, the default variables "issue-url" or "issue-text" are used.

In the text you can write something like:

Check the related issues to this problem issue:0234[eclipse] or issue:JENKINS-35666[jenkins].
Please note that issue:ROASTER-105[jboss] is also relevant.



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Bug-tracker-link-builder-macro-attribute-tp4755p4766.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



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