Hey guys ,
I just finished the first specification of a format I call CommandFile.

https://github.com/thosebeans/...

It's a configuration file format, largely designed after dockerfile with bits of TOML.

Can anyone of you, who is more well versed in writing specifications than me, read over the spec and check if it's concrete enough and if restrictions are reasonable?

So you create you own shell script interpreter instead just going for bash and some custome functions to be used in the scripts?

https://github.com/thosebeans/...

easy to read and write - description vs design goal

description of sequential processes
description only or execution?

---
UTF-8 only... Better: MUST be UTF-8 encoded... See RFC for definition of must / shall / ...

Seperators are Space U+0020 and Tab U+0009.
What are separators?

Newlines are LF U+000A or CRLF U+000D U+000A.
Yikes...

A CommandFile is comprised out of zero or more lines.
Each line contains is either empty, commented or contains a command.

Wording, grammar.

Comment: expect - except,sounds like a messy definition

Command: Wording, grammar.

Lack of intent - fixed set of commands? Up to the writer?

Arguments - Wording, lack of intent. What does an argument mean - as Command is loosely defined, argument seems to relate, but not clearly stated how.

Strings... Eh... I'm lost. Quoted, unquoted, raw, multi line.... Sounds like russian mobs pay day.

With wording I mean spelling errors, things out of context or that should be rephrased.

Get a co reader / lector.

A lot of the spec assumes some knowledge in programming that might be different understood depending on language / background.

@IntrusionCM
Thanks for your advices.
I'm currently reworking chunks of it, to correct some mistakes and make it more clear.

However, I got a few questions...

what's your problem with the newline part?
I took that one, pretty much, directly from the TOML specs.
I thought it's important to State, that files written under windows should be readable in unix and vise versa.

What about the strings part?
As it's a config-file format, I kinda assume the user has, at least, base knowledge about programming/ops and it's fair to use terms from these fields.

@metamourge

Sorry if it sounded rude. Was pretty grumpy yesterday.

I dislike the ambiguity between Windows and Unix... It's less a problem, more a sinkhole I dislike.

Sinkhole in the sense that most languages got a special constant (eg. PHP_EOL, os.linesep in Python, ...) to be OS compatible. As I wasn't sure if it is just a spec describing a series of commands or meant to be an executor I said "Yikes"... As u most likely need a constant like that then and need to cater for OS specific behaviour.

Regarding the strings... I somehow fail to see the point of the whole quoted / unquoted mess if there are no variables involved.

Quoting / Unquoting and Heredocs (multiline) stem from the necessity to separate between interpretation of variables vs non variables.

Heredoc has another problem - eg. in Bash - as it can mess up formatting.

In Bash you can use tabs to eg. enforce the formatting. The whole Heredoc gets justified with tabs, which allows to use spaces inside the Heredoc to use formatting.

It _sounds_ simple, but it's one of the things that can drive you insane, as you need to have an editor with control sign representation mode - otherwise you don't realize that Bash fails to interpret the Heredoc because you maybe added a new line to the Heredoc but forgot to use tabs instead of spaces....

All in all: yes, the concept should be known, but if you write a spec, it should be evident why you deem certain things as necessary. And that's missing here.

I'm not sure why you deem escape sequences (misleading word in my opinion) as so special... You explicitly list control characters and Ulunicode signs under escape sequences, but how / why do they get interpreted at all?

If I write \t as a string in an editor, it does not become a tabulator.

It's an interpretor in Bash which does that...

(Hope you understand what I mean... I,'m missing the 'why does it matter to distinguish escape sequences when it seems there is no interpreter for it')