I just finished reading the documentation. Excellent work. I am (not) eager to start documenting my code - who is(?). I did notice some grammatical errors and some awkward phrasing in the explanations. If you don't mind, as time becomes available, I'd like to send you some alternatives for your review.
In looking at the document as a whole I do think that there are some notable omissions:
<ol>
<li>There needs to be a section devoted to explaining the conventions used. when is a '"' or a "'" legal, what is the meaning of "(" as opposed to (, '[', and so on.</li>
<li>Are there any font conventions? If the user inputs something is the type font a fixed font?</li>
<li>There doesn't seem to by any single location where some of the documentation conventions are succinctly described, viz., //!<, /**, etc. They are all described in prose but not concisely as the Special Commands, HTML tags and etc. are.</li>
<li> In the Special Commands, and probably elsewhere, some of the command options don't seem to be described, although they are probably described in the prose. For example, \var (variable declaration) (and the meaning of '(' is uncertain). Similarly \attention {attention text}.</li>
</ul>
These are all nitnoys I've never seen anyone else comment on them. And, if you agree that they should be addressed, I am offering my services, when I can.
As it stands now I think that the documentation could be made somewhat more rigorous.
art
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Hi Dmitri;
I just finished reading the documentation. Excellent work. I am (not) eager to start documenting my code - who is(?). I did notice some grammatical errors and some awkward phrasing in the explanations. If you don't mind, as time becomes available, I'd like to send you some alternatives for your review.
In looking at the document as a whole I do think that there are some notable omissions:
<ol>
<li>There needs to be a section devoted to explaining the conventions used. when is a '"' or a "'" legal, what is the meaning of "(" as opposed to (, '[', and so on.</li>
<li>Are there any font conventions? If the user inputs something is the type font a fixed font?</li>
<li>There doesn't seem to by any single location where some of the documentation conventions are succinctly described, viz., //!<, /**, etc. They are all described in prose but not concisely as the Special Commands, HTML tags and etc. are.</li>
<li> In the Special Commands, and probably elsewhere, some of the command options don't seem to be described, although they are probably described in the prose. For example, \var (variable declaration) (and the meaning of '(' is uncertain). Similarly \attention {attention text}.</li>
</ul>
These are all nitnoys I've never seen anyone else comment on them. And, if you agree that they should be addressed, I am offering my services, when I can.
As it stands now I think that the documentation could be made somewhat more rigorous.
art