[Aldor-l] +++ Documentation structure

[Christian Aistleitner]

Hello,

> Although not everyone is fluent in LaTeX, I propose LaTeX for the
> general markup of ++ comments. One good reason for LaTeX is that it is
> very powerful.

I also think that LaTeX is a good choice.

> \begin{adprogram} .. \end{adprogram}
>      environment to set short programs (which should be compilable),
>      code appears in verbatim mode.

I have been talking with Ralf about adprogram for some time now. It is not  
quite obvious if this is really needed and/or appropriate.
Personally, I would like to have it. Mainly because I am not into literate  
programming. However, if the literate programming paradigm is applied,  
adprogram is rather useless, because a code block in the literate  
programming source file would do a better job.
Furthemore, there is the question whether or not command line parameters  
to the aldor compiler are to specify as parameter to the adprogram  
environment.

However, at present stage, I agree with Ralf that it is probably not  
needed for the inital versions. It can be introduced when it is needed.

> \begin{adexceptions}
> \adthrows{MyExeption} Description of \adthisexception.
> \adthrows{MyOtherExeption} Description of \adthisexception.
> \end{adexceptions}
>      environment to describe which exceptions the function throws.
>

I am not quite sure, if this markup is enough. Maybe a

\begin{adexceptions}
  \begin{adthrows}{MyException}
    Description of \adthisexception.
  \end{adthrows}
  \begin{adthrows}{MyOtherExeption}
    Description of \adthisexception.
  \end{adthrows}
\end{adexceptions}

would do a better job. Converting the adthrows macro to an adthrows  
environment would ease the flexibility of the underlying style files.
With this constructions changing the rendered representation could be  
adjusted easier, as it is easier to add code at the end of a throws.
However I see your point and I guess your construct aims to be mapped to a  
itemize environment, which is constructed in exacly the same manner.
However, if someone wants to have a different formatting of the  
exceptions, this could be achieved easier and more convenient with an  
adthrows environment.

Of course it is possible to use a script for converting any of the two  
versions to the other.

In discussions it has already been mentioned that adexception would be  
similar to addescription. Therefore a macro adthrows is claimed to be more  
appropriate.
I see it the other way round. adexception and addescription share only one  
thing: the level at which they occur.

addescription is a text without further structure.

adexception has a list-like structure. This structure is represented by  
marking the beginning of every item by the adthrows macro. However, I  
would like to mark the beginning and the end of an item.
Of course the end of an item is marked implicitely by either a  
\end{adexception} or the beginning of a new item. Nevertheless, I would  
prefer an explicit markup for the end of a throws as well.

> Does anybody see a need for other markup?

Since it has not been mentioned explicitely, but only been used within the  
description of adexception, I would also include

\adthisexception
     expands to the most recently defined exception

--
Best regards,
Christian