Asciidoctor :: Discussion

AsciiDoctor and semantic marker pattern

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

6 messages Options

Jeremie Bresson

Jan 21, 2015; 8:56am

AsciiDoctor and semantic marker pattern

163 posts

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):

{{{1}}}

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?

mojavelinux

Jan 21, 2015; 9:05am

Re: AsciiDoctor and semantic marker pattern

Administrator

2681 posts

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:

/tmp

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

[path]#/tmp#

which becomes

/tmp

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):

{{{1}}}

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

... [show rest of quote]

Dan Allen | http://google.com/profiles/dan.j.allen

Jeremie Bresson

Feb 04, 2015; 7:22am

Re: AsciiDoctor and semantic marker pattern

163 posts

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…)?

Jeremie Bresson

Feb 21, 2015; 6:45pm

Re: AsciiDoctor and semantic marker pattern

163 posts

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

Jeremie Bresson

Mar 25, 2015; 10:37am

Re: AsciiDoctor and semantic marker pattern

163 posts

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.

mojavelinux

Apr 01, 2015; 7:09pm

Re: AsciiDoctor and semantic marker pattern

Administrator

2681 posts

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,

-Dan

Dan Allen | http://google.com/profiles/dan.j.allen