@thoni56, since ToolMaker is part of the ALAN toolchain (i.e. it's needed to tweak the ALAN syntax), I think it's worth trying to document ToolMaker, and I'm happy to help in this respect.
You mention "the missing documentation" in the main README. Was ToolMaker never documented because it was for internal use only? or was it documented in Swedish, or the documentation simply got lost? If there was a documentation printed on paper I could scan it and digitalize it, for example. If it's in Swedish, I could create a draft translation using DeepL, etc.
In absence of an original documentation, I could try to document the project from scratch, starting from the individual tools (which I'm currently unable to build though, see #5), and as I learn my way through start to document the notation of the grammar files, etc.
From what I gather, ToolMaker is quite an interesting set of tools, since it contains both a lexer and parser generator (whereas most of the other tools only handle the lexer or the parser). Also, while sifting through the sources I noticed it's a LALR(1) parser, so it should be similar to the Lemon parser generator in terms of parsing features, which is an excellent tool.
And if I'm not wrong, ToolMaker also provides some extra tools, which add value to it.
Anyhow, documenting it might be a long-term project, but it can be done nonetheless, a bit at the time, as I get to know ToolMaker in my free time (even if it's a morning I dedicate to it every so many months).
What do you think would be the best approach:
- I start documenting it in my fork's Wiki, and whenever a document is usable I submit it to the repository.
- I work on the documentation in a dedicated branch, and we simply merge the docs once they are production ready.
With either approach we could use Markdown or AsciiDoc, at our own discretion. Obviously, I'm more prone to use AsciiDoc since I prefer it and it would spare us porting work in case we end up creating a proper document from the various tools' READMEs.
Once I'll have access to the compiled binaries the task should be easier (I really should re-install my Ubuntu machine and just cross compile it). But since there is no documentation whatsoever right now, any input from you would be useful to set me in the right course in this task.
P.S. — Could you enable Discussions and convert this Issue into a discussion? Just to keep Issues clutter-free.
@thoni56, since ToolMaker is part of the ALAN toolchain (i.e. it's needed to tweak the ALAN syntax), I think it's worth trying to document ToolMaker, and I'm happy to help in this respect.
You mention "the missing documentation" in the main README. Was ToolMaker never documented because it was for internal use only? or was it documented in Swedish, or the documentation simply got lost? If there was a documentation printed on paper I could scan it and digitalize it, for example. If it's in Swedish, I could create a draft translation using DeepL, etc.
In absence of an original documentation, I could try to document the project from scratch, starting from the individual tools (which I'm currently unable to build though, see #5), and as I learn my way through start to document the notation of the grammar files, etc.
From what I gather, ToolMaker is quite an interesting set of tools, since it contains both a lexer and parser generator (whereas most of the other tools only handle the lexer or the parser). Also, while sifting through the sources I noticed it's a LALR(1) parser, so it should be similar to the Lemon parser generator in terms of parsing features, which is an excellent tool.
And if I'm not wrong, ToolMaker also provides some extra tools, which add value to it.
Anyhow, documenting it might be a long-term project, but it can be done nonetheless, a bit at the time, as I get to know ToolMaker in my free time (even if it's a morning I dedicate to it every so many months).
What do you think would be the best approach:
With either approach we could use Markdown or AsciiDoc, at our own discretion. Obviously, I'm more prone to use AsciiDoc since I prefer it and it would spare us porting work in case we end up creating a proper document from the various tools' READMEs.
Once I'll have access to the compiled binaries the task should be easier (I really should re-install my Ubuntu machine and just cross compile it). But since there is no documentation whatsoever right now, any input from you would be useful to set me in the right course in this task.