A reference manual for Tutorial D or Rel
Is there a reference manual for Tutorial D or Rel, with current syntax, examples and descriptive notes? Is so, where is it? If not, why not?
I have the document Tutorial D 2016-09-22.pdf, which provides the syntax, recent changes and a few chatty notes but not much else.
I have DTATRM and DBE, which provide plenty of examples but in the old syntax and cover only part of the language.
I find this a major barrier in trying to write samples in TD syntax, or in trying to use Rel. Perhaps others do too.
Maybe Hugh needs a retirement occupation, in these days of being confined to quarters?
Quote from dandl on April 1, 2020, 5:16 amIs there a reference manual for Tutorial D or Rel, with current syntax, examples and descriptive notes? Is so, where is it?
There's this: https://reldb.org/c/wp-content/uploads/2017/12/Rel-and-Tutorial-D-Quickstart.pdf
If not, why not?
I work on Rel and related software for free because it's fun.
Writing documentation isn't fun. If you want me to do that, you have to pay me.
Quote from dandl on April 1, 2020, 5:16 amIs there a reference manual for Tutorial D or Rel, with current syntax, examples and descriptive notes? Is so, where is it? If not, why not?
I have the document Tutorial D 2016-09-22.pdf, which provides the syntax, recent changes and a few chatty notes but not much else.
I have DTATRM and DBE, which provide plenty of examples but in the old syntax and cover only part of the language.
I find this a major barrier in trying to write samples in TD syntax, or in trying to use Rel. Perhaps others do too.
I'm sure you could write examples in old syntax per DTATRM; or new syntax per the 2016 doco; or some mixture of the two. People would understand/mentally translate. It's the semantics in terms of TTM that's important isn't it?
If you're writing for Rel, it'll tell you if the syntax is wrong. "major barrier"? You must have an uneventful life. I've just spent an hour queuing to get into my local supermarket -- after having tried and given up 7 times in the past couple of days.
Quote from dandl on April 1, 2020, 5:16 amIs there a reference manual for Tutorial D or Rel, with current syntax, examples and descriptive notes? Is so, where is it? If not, why not?
I have the document Tutorial D 2016-09-22.pdf, which provides the syntax, recent changes and a few chatty notes but not much else.
I have DTATRM and DBE, which provide plenty of examples but in the old syntax and cover only part of the language.
I find this a major barrier in trying to write samples in TD syntax, or in trying to use Rel. Perhaps others do too.
Maybe Hugh needs a retirement occupation, in these days of being confined to quarters?
Thanks for the suggestion but I'm afraid I already manage to keep myself well occupied. In any case, I wouldn't be able to find a publisher and I don't want to get involved in self-publishing again.
Are my two Bookboon books of any use? Possibly not as I don't think I wrote much about UDTs.
Hugh
Those wanting to write new documentation can just put it online, it doesn't have to be a printed book.
Quote from Darren Duncan on April 2, 2020, 4:49 amThose wanting to write new documentation can just put it online, it doesn't have to be a printed book.
Correction: it shouldn't be a printed book. It should be hypertext linked, online. We used Windows CHM or similar, but now I guess JavaDoc or similar would be the go.
We've done several of these (mostly me, because I'm the only one with the breadth of knowledge). What we do is:
- One page per major keyword/function.
- For each page: title and one-liner; Syntax; Description/Usage; See Also; Example.
- Articles on other topics as we think of them, or customers ask.
The ANTLR guy made money out of his book, but I guess that's the exception.
A feller I know used to point to the sign on the dunny (toilet) door: the job ain't finished until the paperwork's done. For software, that's the doco.
Quote from dandl on April 2, 2020, 5:29 amQuote from Darren Duncan on April 2, 2020, 4:49 amThose wanting to write new documentation can just put it online, it doesn't have to be a printed book.
Correction: it shouldn't be a printed book. It should be hypertext linked, online. We used Windows CHM or similar, but now I guess JavaDoc or similar would be the go.
We've done several of these (mostly me, because I'm the only one with the breadth of knowledge). What we do is:
- One page per major keyword/function.
- For each page: title and one-liner; Syntax; Description/Usage; See Also; Example.
- Articles on other topics as we think of them, or customers ask.
The ANTLR guy made money out of his book, but I guess that's the exception.
A feller I know used to point to the sign on the dunny (toilet) door: the job ain't finished until the paperwork's done. For software, that's the doco.
There are WordPress plugins for creating documentation, and given that https://reldb.org/c is WordPress, it would make sense for me to install one1 and use it.
But... Ugh.
A few years ago, I had a student do a dissertation project around software documentation approaches and he used Rel as a case study. The end result was a good start, but not enough that I thought it was worth making publicly available.
--
1 I guess it should be two, not one. One should be Rel's dialect of Tutorial D language reference, and the other should be the Rel user's guide. Maybe a third as a teacher's guide with lessons, pedagogic examples, etc.