Condiitonal text and variables

[rafamadriz]

recently I found out about asciidoc and when going through the documentation, I found some features that can be really useful and it would an awesome thing to have on neorg:

• conditionals: are based on the presence or value of document attributes. This is one example how the syntax looks in asciidoc:

ifdef::env-github[]
This content is for GitHub only.
endif::[]

This can give a lot of flexibility since you can create templates which contents are going to change based in those conditionals.

• variables or attributes: You can save A LOT of typing with this. One perfect example is the asciidoctor README, if you take a look at the raw, at the top of the file, all the urls used in README are defined as variables.

:url-org: https://github.com/asciidoctor
:url-repo: {url-org}/asciidoctor
:url-asciidoctorj: {url-org}/asciidoctorj

Notice how you can create on variable for the base url, and then concatenate that with the other urls used. And then can save a fair amount of typing by just referencing those variables, one example from the README.

Asciidoctor organization on GitHub:: {url-org}

All of this is explained better and with examples of how this can be useful in this video: https://www.youtube.com/watch?v=-jeb_YFnODM&t=688s

When it comes to the syntax of how this can be done in neorg, since the at sign @ is already used for a lot of other things, it think it would be save to follow that spec:

I'm just throwing out some ideas for the syntax

@const project_name = neorg

@if project_name == neorg 
This is a test.
@endif 

@vhyrro what do you think about this ? Do you agree that something like variables can be worth it to have it ?

[vhyrro]

Huh, sounds interesting! I'm literally about to fall asleep so I'll continue discussion when i wake up but I think this could be useful for certain situations. The syntax will need to be switched around a bit imo but we can think that through when I'm not slowly drifting away due to sleepiness lmao

It's useful for sure and can provide some nice flexibility to both potential neorg plugins and to the actual people writing their documents as well.

[rafamadriz]

Hey @vhyrro have you thought about this ? I know that there's a other things that are of higher priority and a feature like this is probably not getting implemented in neorg any time soon, but I'd like to know your opinion.

This project looks more exiting every day, thanks for your awesome work!

[vhyrro]

Hey man, thx for reminding me about this. I completely forgot. Over the course of however many days have passed since this post we have had new syntax emerge mostly thanks to your suggestion :)

The insertion modifier has been introduced which, well, inserts one bit of data somewhere else (either in the document or inserts a value into a variable):

= variable_name a value

If the first item begins with a capital letter then the item is inserted into the document, for example:

= TOC Table of Contents:

Would insert a table of contents in that part of the document. We don't have any if checks that would allow you to conditionally insert data into the document but I'm pretty sure we'll stick with:

@if variable_name a value
Some special stuff in the document because "variable_name" was set to "a value"
@end

I'll have to figure out some implementation details but once that's done we should be golden! Whaddya think?

[rafamadriz]

I think it's great, I have a few questions:

• Just to make sure I understand.

If the first item begins with a capital letter then the item is inserted into the document, for example:

= TOC Table of Contents:

Would insert a table of contents in that part of the document.

That would save the string "Table of Contents" into the variable TOC but also would insert it into the document, right ? but what happens when I want a variable which first letter of value is capital but I don't want the variable to be inserted at that point of the document ?

• In case that I'm writing something that has exactly that syntax, but I don't actually want to save it to a variable or anything, does the escape sequence \ before = prevents the creation of the variable ?

• What's the syntax to call a variable ?

In my humble opinion, I feel like the syntax for insertion modifiers or variables should be a bit more explicit.

[mrossinek]

So there are two different objects which we are talking about here:

Insertions

These follow the syntax

= <capitalized word> <arguments>

In the example above, = TOC Table of Contents will insert a table of contents, titled as Table of Contents, at rendering time into the document. Currently, we don't have a renderer so this concept is still quite abstract. However, we are working on a ToC-dsiplaying command in PR #88.

Variables

These follow the syntax

= <lower-case word> <arguments>

This will be some sort of variable assignment. This is also still a rather theoretical concept as it does not really do anything yet. We did not even have a syntax defined to access variables until you brought this up 😅
Currently we are thinking about using a =-attached modifier for that syntax. That means you could use =variable= to access a variable in your document. (But again, this does not do anything yet).

Since insertions and variables are defined as outlined above, it will not be possible to use capitalized variable names. But we think that this is not a limitation which is going to cause problems to the user.

EDIT: I forgot about the escaping: Yes, writing \= will escape the = sign. However, I think variable definition will only happen when you start the line with = anyways (disregarding leading whitespace ofcourse). @vhyrro please correct me if I'm wrong about this.