AsciiDoctor and semantic marker pattern

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

AsciiDoctor and semantic marker pattern

Jeremie Bresson
I am sorry if the question was already discussed on this mailing list. I am not even sure that the name of the pattern I am describing, so searching for it is difficult.

In our current documentation, we mark the items of a same type (menu, wizard, field, folder, property, method name, ...) with a specific marker. This adds some semantic to our documentation. This way we can control the way menu (for example) references are displayed.

Let me provide two examples with Latex and Mediawiki.

1/ In Latex we have defined a command:

  \newcommand{\menu}[1]{\textsc{#1} menu}

And we use this in our document:

  In this example, \menu{Export to Excel} is used to export the selected row into an Excel sheet.

2/ In Mediawiki we have defined a template (for example Menu):

  <em style="color:#045FB4;">{{{1}}}</em>

And we can use it like that:

  In this example, {{Menu|Export to Excel}} is used to export the selected row into an Excel sheet.

---

What do you think of this practice?
How can I implement this with Asciidoctor?
Reply | Threaded
Open this post in threaded view
|

Re: AsciiDoctor and semantic marker pattern

mojavelinux
Administrator
Jeremie,

It's a good question, and something we need to address specifically in the documentation as the question does often come up.

You can add a "role" (which becomes a CSS class in HTML) between square brackets preceding any inline formatting. (In fact, almost every element in AsciiDoc supports the role in some way or another).

What I typically do is combine a formatting element, like italic, with a role. For instance, when I type a path, I use:

[path]_/tmp_

This becomes:

<em class="path">/tmp</em>

If you want the role to be completely anonymous (semantic only, no implicit formatting), then use the hash symbol instead:

[path]#/tmp#

which becomes

<span class="path">/tmp</span>

If you are doing this often for a particular type of element, you might want to solidify it in the syntax by creating a custom inline macro. For example:

path:/tmp[]

You can see examples of inline macros in the extensions lab repository at https://github.com/asciidoctor/asciidoctor-extensions-lab/tree/master/lib

I hope that helps!

-Dan

On Wed, Jan 21, 2015 at 1:56 AM, Jeremie Bresson [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I am sorry if the question was already discussed on this mailing list. I am not even sure that the name of the pattern I am describing, so searching for it is difficult.

In our current documentation, we mark the items of a same type (menu, wizard, field, folder, property, method name, ...) with a specific marker. This adds some semantic to our documentation. This way we can control the way menu (for example) references are displayed.

Let me provide two examples with Latex and Mediawiki.

1/ In Latex we have defined a command:

  \newcommand{\menu}[1]{\textsc{#1} menu}

And we use this in our document:

  In this example, \menu{Export to Excel} is used to export the selected row into an Excel sheet.

2/ In Mediawiki we have defined a template (for example Menu):

  <em style="color:#045FB4;">{{{1}}}</em>

And we can use it like that:

  In this example, {{Menu|Export to Excel}} is used to export the selected row into an Excel sheet.

---

What do you think of this practice?
How can I implement this with Asciidoctor?



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/AsciiDoctor-and-semantic-marker-pattern-tp2687.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: AsciiDoctor and semantic marker pattern

Jeremie Bresson
Thank you a lot for your answer. I think that the role concept is what I am looking for to bring semantic in my text.
If I understood it well, with a HTML5 Backend, I will be able to style it with CSS. How does it work with in the PDF output? Can I somehow influence the style?

I am also very interested in defining a macro. I had a look at the repository you pointed. I do not really understand it.
Does it mean I cannot define some text replacement macro directly at the beginning of my document?
In pseudo code:
    function my_function(String param) {
        return "some text before " + param + " some text after"
    }

This is all I need to have the additional LaTeX command or the MediaWiki Template I had. My idea is to have something like this for menu:
    function menu(String param) {
        return "[menu]_" + param + " menu_ "
    }

If I understood it well, I could use it like this, with the menu macro defined, I could use it like that:
    menu:Export to Excel[]

I just do not understand:
* how to write the macro?
* where to add/define it?
* will this macro be understood by all tools (for example the preview feature on GitHub, my asciidoctorj-maven-build…)?
Reply | Threaded
Open this post in threaded view
|

Re: AsciiDoctor and semantic marker pattern

Jeremie Bresson
I have noticed that my problem is discussed here: macro for todo items.

I am not the only one having trouble to understand inline macro.

The documentation issue for macro is opened: asciidoctor.org #347
Reply | Threaded
Open this post in threaded view
|

Re: AsciiDoctor and semantic marker pattern

Jeremie Bresson
I just spoke with Dan Allen at the JavaLandConf.

For Menu, Button and Keyboard, there is already a built in solution.

You need to add :experimental: at the top of the asciidoctor document.

[source,asciidoc]
----
:experimental:

Open the menu:Search[Text,Workspace] menu.

press the btn:[Press OK] button.

press kbd:[CTRL,A]

----

In my case I probably need more (Dialog, Wizard, View…) and I still will need to define some additional macro for them.
Reply | Threaded
Open this post in threaded view
|

Re: AsciiDoctor and semantic marker pattern

mojavelinux
Administrator

On Wed, Mar 25, 2015 at 11:37 AM, Jeremie Bresson [via Asciidoctor :: Discussion] <[hidden email]> wrote:
In my case I probably need more (Dialog, Wizard, View…) and I still will need to define some additional macro for them.

The tutorial for extension writers will probably really help you out then. I will focus my attention there first as I get caught up on writing for Asciidoctor.

In the meantime, even if you can't figure out how to write the extension, you can still "design" the AsciiDoc syntax and even start using it. It's usually good to have a clear picture of what syntax you want to parse...then move on to writing the extension to parse it. That's the great thing about AsciiDoc. You can just write it and deal with the rest later down the line. For instance, for Dialog, you might have:

dialog:[Title of Dialog]

Cheers,