[FEEDBACK NEEDED] New text line syntax

[Elringus]

You may have noticed flux of new features recently. They're all driven by the feedback we got via the form. I'm very grateful to everyone who shared thoughts, especially when you pointed lacking features or subpar solutions of the current systems.

Most of the improvements we've implemented so far were pretty straightforward and few are still on the way, but there is one potential change, which I'd love to hear opinions on, before deciding whether to proceed.

Basically, the idea is to reverse markup of command lines with text lines; ie you'd have to mark beginning of text lines with a backtick (`), while commands won't require control symbol at the start of the line:

Code: Select all

; Currently
@command
Printed text.

; Proposed
command
`Printed text.

The main point of the change is to improve redability and reduce amount of typing when authoring scripts. In general, there are significantly more command lines in average script than text lines (especially in more dynamic/branching projects), so it'd make sense to promote command to the "default" construct, which doesn't require a control symbol.

Another significant point is, with the recent introduction of nesting, it may be unclear whether you indenting a text line or want to print a text with white space at the start, eg:

Code: Select all

; Is the text line nested under @await or just starting with 4 spaces?
@await
    @back x
    Text line.

; Here it's clear that the line is nested.
; Command ids can't start with space, so they're not affected by the same issue.
await
    back x
    `Text line.

There are all sorts of other pros, should we proceed we the new syntax. For example, we may as well change how authors are specified to reduce chance of conflicts with normal prose, as the current author: construct is quite common in "natural" text:

Code: Select all

; Currently, it's not clear wether you want to print "John: Hello World!"
; or print "Hello World!" authored by actor with ID "John".
John: Hello World!

; Proposed.
`John`Hello World!

This, in turn, allows additional parameters to be specified for the text lines:

Code: Select all

; Print the text authored by "John" actor with 50% speed while displaying the author as "Someone".
`John as:"Someone" speed:0.5`Hello World!

— content inside the backticks would be treated identical to a command with AuthorId.Appearance nameless parameter and other optional parameters, such as speed, as, waitInput, etc. Moreover, you'd be able to provide a custom command to be used for text lines, which could have its own parameters and/or behavior.

And, in case you'd like to enter "full text" mode, we could have something like this:

Code: Select all

``
All the lines here are considered text lines.
They don't require ` at the start,
  # may start with other (and will preserve)
    ; control symbols,
      as well as line breaks
        and leading/trailing white space.
``

``John speed:0.5
The text blocks can as well be parametrized as normal text lines.
The parameters will apply to all the lines in the block.
``

This is of course a breaking and substantial change. Should we proceed, I'll make sure to prepare an automatic migration script, so that you'd be able to convert existing scripts in batch.

Please share your thoughts (here or on Discord), especially if you feel there would be significant drawbacks with the new syntax or have alternative solutions in mind.

---

Comparing current and proposed syntax

Comparison with pseudo script below (click here to view in full size). Notice line #21, where new syntax allows applying parameters to all the parts of the generic line, whilst currently we have to duplicate them.

---

Keep in mind there will be an option to change backtick to any other symbol

I'm aware some keyboard layouts don't have the dedicated backtick key, so there will be an option to change it and all the other control symbols, as well as command identifiers via something like developer localization pack. This feature will land before the proposed change.

[Keinart]

Heavily appreciate all these new features and listening to feedback, Elringus, Naninovel it's looking great at the moment.

I wasn't sure about this change at first, but reading the post I guess it makes sense. I especially like the idea of being able to create blocks of text, maybe even being able to add inline commands in separate lines to the main text making it cleaner when writing the script. However, I would like to mention two possible problems to keep in mind:

- First one is that the colon is way more accesible for people without coding experience. I understand this is something people can get used to it very quickly, but at the same time I think is easier when editing the script to realize who is talking or not by using a symbol that is big and easy to see to separate the parts. The backtick is small and it may be harder to differentiate where the author or text starts.

- Second and more important imo, is that the backtick for international keyboards can be a bit clunky. Let me explain:

In Spanish for example, we have the backtick right next to the P, and when pressing it, it won't type on the first input but on the second and it would write two like this: ``
The reason is because in Spanish we recognize these as accents, just like á, é, ò, ù, etc. Therefore, when pressing the button it just waits until you select a vocal to add the accent to it. The only way to write it "alone" is by pressing it twice, which then generates two backticks and we have to delete one of them later. Doing this once is okay, but doing it in a large script all the time can be quite awkward as you can imagine. The normal tick however is quite easy to type ', but this one would be a problem in English I imagine. I don't know about other languages but I imagine it would be almost impossible to find something that would fit all languages so I understand if it's not really feasible to try to content everyone.

Personally, I would recommend something like | , >, or directly get the author part within brackets such as [], {}, or <>, but I see how these could interfere with the code when reading them in C#
Or maybe use the backtick but allow somewhere else to change what symbol to use.

At the end of the day these two problems are not that big of a deal, but I still you may want to consider them when making a decision.

[Elringus]

Thanks for sharing the concerns!

I've actually foreseen the locale-related issues with the backtick. And it's not limited to backtick. We already have such issues with for example @ and [], which don't exist at all in Russian layout, making it very frustrating to author scripts.

To fix issues like this I've planned a feature, which would allow overriding the control symbols and command ids, something like developer localization pack. This will land before the proposed change, so hopefully local layouts won't be an issue. I've though about using ' or " by default, but they're very common in normal text, so you'd have to escape them to include in the printed text.

Regarding changing author assign from colon to backtick: I can see the point that colon is extremely natural and backtick would be not as distinguishable, but it's the same issue as with quotes vs backtick: colon is widely used in normal text, so with something like Actor: Text it's not clear whether you want to print Actor: Text or print Text, which should be authored by Actor. Tbh, I'm not perfectly fine with the

Code: Select all

`Actor`Text

— but it's the best I was able to come up with at the moment. I don't want to add one more control symbol just for author assign, so the options are kinda limited.

[KrakenVambrite]

I'm very happy with the current syntax of naninovel. With the nested groups everything looks so good and it's very easy to organize chunks of dialogs and code. Personally, I'm not a fan of "`" for commands. Typing it in a Spanish keyboard its a bit nightmare and slow. I vote to stay with the current one :-)

Thank you! keep the good work!

[NocturneLight]

Without seeing more examples, I'm pretty much not a fan of this proposed change.

How it works currently is pretty intuitive and for the most part makes sense. You're right though that there's ambiguity on whether the actor is saying the line or if that fragment is just part of the string.

But with what you're thinking of changing it to in mind, when you switch to using the backtick and removing the @ symbol, it doesn't look good to me nor does it feel intuitive. Removing the @ symbol, I can get behind for the most part. But the backtick is a hard no for me.

You should keep researching on a replacement for that. In my mind, I'd look into parenthesis perhaps. I can't think of anything off the top of my head that Naninovel uses that for. Other alternatives are the minus and plus signs, but we're pushing it with those two. You could also think outside the box and make the word "actor" or some similar word a protected keyword in the Naninovel syntax that it looks for, just like how it currently uses the word "command".

But definitely not the backtick. That's not a good replacement nor is it intuitive in my software engineer opinion.

[Elringus]

I've added comparison with a pseudo script to the post.

[NocturneLight]

Looking at the comparison, my thought now is that removing the @ symbol is a fine decision. But, yeah, the backtick is definitely not doing it for me still. I'd still say you need to keep looking into other ways of figuring out when a line is specifying an actor or if it's part of the dialogue.

There's got to be a better way of handling that than the backtick.

[LordBeorn]

I don't mind losing the @ symbol but I don't like at all the new dialogs. I would rather prefeer mantaining the @ than having to use the ` for the dialogs.
As someone has said already, not all the keyboards have the ` symbol accessible. So it would make harder to code the scripts for those ones.
In any case i like the way the code is done right now so I would rather prefeer to mantain it as it is rathen than having to get used to a new system.

[Elringus]

I'm aware some keyboard layouts don't have the dedicated backtick key, so there will be an option to change the backtick and all the other control symbols, as well as command identifiers via something like developer localization pack. This feature will land before the proposed change. I've added notice about that to the post. Still, if you believe the backtick is a bad choice from readability point of view, that's a valid concern.

[Restush]

Based on the feature, I think it's make sense. But, the current changes will make a lot of revision for naniscript. Also I believe usage of generic text vs command is 50:50. Sometime type more generic text and sometime type more command. But, I believe community will getting used by it.

However, right now I seen Naninovel has a lot new comer, I'm not sure but for beginner in C# + Unity + Naninovel + UniTask + async/await honestly for first time really take a hard punch that need patience to learn it. When the new feature come out, they will need to get a hard punch again. I suggest the new feature should postpone on the next version (not current alpha 1.20) for sake new learner.

[Keinart]

Keep in mind that with almost all changes in anything, most people won't really like it at first since we are used to the other method, so feel free to give it a try or even some testing period where people can use both and I'm sure with time we will get used to it. I think most people won't really notice the improvements until they are actually writing it in script as you mention in your example at the 21st row.

Still I would personally use something like | but if users can personalize it when it comes around then it shouldn't be a problem, just that the default is a bit ugly for the eyes.

[Elringus]

| is already used by text identifiers, though they open with |#, so it's technically possible to still use it, but visually it may be confusing.

Another con is that it requires holding shift to type, while backtick doesn't.

That said, I do find it better looking than the backtick:

Overall, I'm currently leaning against the proposal, especially given the comment by Restush that command-text ratio is closer to 50:50. Personally, I only used NaniScript in smaller projects, so not really sure what the ratio actually is for average medium-large projects. If commands are actually not as dominant, the change doesn't really make much sense.

[CodeOfElm]

I could see losing the @command, and I agree that the second example with the backtick is cleaner to read, however it does not seem to be writer-friendly. This may not be a concern, but Naninovel is still advertised as such, and seeing `author: text` seems to be a lot more familiar, and easier to read/understand at a glance. Currently, it's not too painful to practically take the writer's scenario, and paste and convert it into naninovel if it's written a certain way. It's also still formatted in a way that beta-readers and editors can access the scene without having to convert much. Even the `@` seems intuitiuve enough to leave in.

The backtick in my opinion is cleaner to read, but also seems easier to miss. Such a small element could be easier to make mistakes with.

Regardless, if it goes forward, people will be forced to get used to it.

[Elringus]

take the writer's scenario, and paste and convert it into naninovel

That's mostly what the "full-text" mode is for; eg you can add `` at the beginning of the script and paste the scenario as-is:

Code: Select all

``
here any text would be interpreted as generic text lines
without the need to prepend the control symbol

[Robotortoise]

Hmm. This is interesting.

Honestly, I understand where you're coming from, and I always thought it was odd that system/narration/descriptive text didn't have anything denoting who was speaking it. Honestly, for consistency's sake I would prefer the descriptive text had some sort of way to denote that it was game text rather than part of the code, but I think a backwards tick is rather unintuitive. Typically from a writing standpoint, you write narration in italics of in just a discrete paragraph. If Naninovel would be trying to mimic that, perhaps enclosing asterisks would be better? or even doing HTML tags like

```nani
<nar>I sat in a grey, dull office, the thrum of an A/C the only thing I could hear. My manager was on his phone, playing a game, and I stared at the clock, praying to any and all entities above that it would move faster.</nar>
Dave: Wait...
Dave: The hand isn't moving. The darn battery is dead!!
```

[Elringus]

odd that system/narration/descriptive text didn't have anything denoting who was speaking it

We always had that, it's author: text (same as in your example). The proposal is about changing it to:

Code: Select all

`author`text

some sort of way to denote that it was game text rather than part of the code

That's actually something I don't want. NaniScript is designed to be writer-first scenario authoring DSL, not code/programming language. The questions is, do we really have that much more commands compared to prose to justify the change? The driving idea behind the change is that you generally type much more command lines than prose (generic text) lines, that removing mandatory @ before each command line and instead adding mandatory control symbol before each prose line would save lots of typing and make the scripts more readable. But, for the time being, it looks like that's not the case.