Documenting ToolMaker

[tajmone]

@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:

1. I start documenting it in my fork's Wiki, and whenever a document is usable I submit it to the repository.
2. 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]

There was extensive documentation in English. However, that has simply got lost. When I preserved this from getting lost from my "former company" (actaully a much more involved story than that) the copyright holder was still in existance. I didn't think of preserving the documentation.

I have asked around amongst my former collegues, but none of them seems to have a copy, not even the one that worked on the company taking over.

So I think the best route forward would probably be option 1). I'm guessing that the documentation will never be ready for "release", but will anyway be valuable along the way.

Agree that AsciiDoc would be the prefered format.

[tajmone]

Updates on Documentation Wiki

@thoni56, I've managed to recover all the man page files from the repository and convert them to AsciiDoc. The only missing man page seems to be the one for the PMK tool.

Here you can find the Toolmake(1) AsciiDoc Wiki page, and here the Toolmake(1) HTML Live Preview.

As you can see, I added a warning admonition about SoftLab no longer being active, and that any references to the softlab.se are not associated with the SoftLab Rising company which is using the web domain today (owned by a Kalle Björk; any relation to the original SoftLab?).

Before publishing the rest of the converted man pages, I wanted to make sure with you that the admonitions notes are correct.

Of course, I also need to polish the AsciiDoc sources, since the automatic conversion from man-page to AsciiDoc is not perfect and needs adjustments. But that's not going to take more than a couple of hours in total.

But I think it's already a good start, since the man pages offer some useful insights into the various tools, especially the IMP(1) man. By studying these documents, along with the repository examples and test files, I should learn my way through ToolMaker.

Obviously, a surviving copy of the Toolmake Reference Manual mentioned in the man page (and possibly the other paper manuals that went along with the software product) would have been better, but let's work with what we have.

[tajmone]

One simple way to handle old references (email addresses, persons, etc.) could be to cross them over and replace with link to the repo if that is possible:

Yes, Asciidoctor supports the line-through role (aka strikethrough), so it's doable, and makes it clear that the email is no longer active, without redacting away the original text.

You mentioned that toolmake was not available on Windows so I got curious. [...] so I decided to see if I can restore toolmake, ripping away useless cruft like the license handling and make it run. At least to the level that you can get the -help output. I'll ping you when it can be compiled.

Thanks, that's nice! It sounds like toolmake is useful, especially in the learning stage, since it guide the user through the process of choosing the right settings, and caters for all the basic scaffolding.

[thoni56]

Whoa, that's some old code! I've cleaned it up just enough to make it compile on Linux (still a lot of warnings and other uglinesses, such as K &R non-prototyped function headers...)

Here's the output

thoni@thoni64:~/Utveckling/ToolMaker/src/toolmake$ ./toolmake -h
toolmake -- initiator for ToolMaker tools 2.1(12) (1997-07-28 17:57)

Usage: toolmake [-[-]go|-[-]verbose|-help]... <name>

Arguments:
  <name>            -- for the subsystem

Options:
  -[-]go            -- quick toolmake with all defaults accepted (default: OFF)
  -[-]verbose       -- verbose mode (default: OFF)
  -help             -- this help

[thoni56]

Fun fact: the code is so old that when ToolMake generates generation dates in the generated files it becomes 19122-02-05 ;-)

I'll keep that for a while...

[tajmone]

Fun fact: the code is so old that when ToolMake generates generation dates in the generated files it becomes 19122-02-05

Is that related to the "Millenniums Bug"? when in 2000 it was supposed to zero-out all computer dates?

[thoni56]

Related in the sense that the writer of the code did not even think of 19 becoming 20.