Variables/references in documentation

[malakeel]

I am wondering about the way to use references in the documentation. For example, if I have a word that I need to use in multiple places where copy/paste is not the best way. An example could be an entity name that could change, a software version number .. etc.

What is the best way to do this other than using search and replace ?

[MykolaGolubyev]

Good question. Something I had in a backlog for a while.
there is a plug-in include-markdown that includes a different markdown file in the current one. If we add an inline version of it then it may work for your use case.

[malakeel]

Yes, the "inline" would do the trick. I overlooked that part

[malakeel]

@MykolaGolubyev

I appreciate the efforts, and the answer. I have read somewhere that znai uses FreeMarker. If this is correct then something like the following should work:

`
<#assign x = 1>
${x}

`
However, this was not the case for me, or at least I missed something. I guess it depends on how FreeMarker was used in the code.
Following up with your suggestion, here's what I did and it worked (others in the same position can use this method):

• create a directory somewhere. I created it in the root of the doc variables.
• add ./variables to lookup-paths file.
• create a file like variables/maven-version.md with the content I want to use. Let's say 3.8.4.
• In my mark-down I used:
  :include-markdown: maven-version.md

And the variable is displayed properly.

This gets the job done. May be not obvious, nor convenient, but it is okay. Thank you for your help

[malakeel]

I guess, the replacement has to be on its own line. Otherwise it wont work if in the middle of text.
Hum !

[MykolaGolubyev]

#1036

[MykolaGolubyev]

I agree that include-markdown may not be obvious. Will work on adding inline support.

Could you clarify what you want to achieve with template?

Thanks for starting this discussion. If you have suggestions for the plugins - do let me know

[MykolaGolubyev]

@malakeel let me know if inline template plugin is something you will find useful

[malakeel]

@MykolaGolubyev
Thank you for getting back. I think it is useful, but I prefer if you don't take my opinion only. I can get around this temporarily by running some other preprocessing step. It is not urgent. I prefer if you think about the best way to do it, and how to address most case cases. You know better than anyone about the program, so you can handle it in the most generic way.
From what you described, I think it makes sense to use inline template plugin. But at the same time, preprocessing with Freemarker makes sense. The program is in early stages, and unlikely to break something if you change the default behavior. If changing the default behavior improves things for the long run, then I would do it there (if I were you).

[MykolaGolubyev]

Appreciate the thought process.
so how do you plan to pass the variable values?

If you have time, could you please fill a bit of info here on how do you use or plan to use znai: #824

[MykolaGolubyev]

@malakeel were you able to figure things out? Sorry I sort of dropped the ball on this one

[MykolaGolubyev]

@malakeel circling back here, do you still need help on this?