General Strategy for Going Forward #34
Unanswered
tajmone
asked this question in
Syntax Roadmap
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
@polyglot-jones, I've finally managed to cut-out some time (read: stole from other deadlines) to revisit the current syntax status, and to fix a couple of broken elements, and add some pending ones.
Overall, the various pieces of the syntax seems to be starting to fall into their right place, in virtue of other elements having been fixed — e.g. the constrained highlight/mark element, which wasn't working before and had to be commented out (see #2), now turned out to be working fine by just uncommenting it and move up its
include:
directive.As you know, many elements in the syntax have been commented out wholesale, because there were just too many breaking points in the parsing. Our goal should be to gradually reintroduce those elements — one at the time! — but not before ensuring that all implemented elements are thoroughly covered by syntax tests.
Test Coverage!!!
If the original syntax had been developed around tests, it probably would have never got so entangled and broken (but then, I believe ST2 didn't have a syntax tester like ST4). Anyway, let's not make the mistake of ignoring how important test-coverage is in order to have a fully working AsciiDoc syntax.
Although the basic tests all pass, I still notice that in some real-case scenario documents there's the occasional document highlighting break-up (some context which is never popping out, or some elements precedence issue). We need to detect all these breakage cases, annotate them in this section of Discussions, until we can come up with a good minimum viable example of the problem, and then add tests for it in a dedicated dev branch were we can start to tackle to problem by tweaking the syntax.
So, it's very important in this precise moment to ensure full-coverage of all working elements, so that whenever we tweak the syntax we'll detect any unwanted changes affecting working elements (the last thing we want is to introduce new breakage into the syntax).
Working Out Nested Inclusions and Order Priority
Another major problem I see is related to which elements should be included in nested contexts, which should not, and their exact order of priority. This might not be quite as simple as it looks like, but we'll eventually realize that there are some elements which can be grouped into a dedicate
include
s context, to keep the syntax DRY and be able to tweak such inclusions in a single place.Right now, many
include:
directives for implemented elements were simply commented out to reduce syntax breakage and be able to focus on context-specific problems. So, once test-coverage is robust, we can start to uncomment back some of thoseinclude
s and see if these elements work as expected in nested context.Beta Was this translation helpful? Give feedback.
All reactions