On Fri, 2003-02-28 at 15:09, Frank Heckenbach wrote:
<big snip>
> > 1) When moving the vars into the section in which they are declared
> > should I make a menu entry for each one or should I do a submenu of
> > vars?
>
> Good question. I'd say it depends. Sometimes, each one deserves its
> own entry, other times, there are a list of them which belong
> together (e.g., the color constants in the CRT unit).
>
> Of course, the program can't find this out automatically. One rule
> might be, if there's a comment for each of them, put them in
> separate sections, like here:
>
> var
> { Address of the lowest byte of heap used }
> HeapLow: PtrCard; asmname '_p_HeapLow'; external;
>
> { Address of the highest byte of heap used }
> HeapHigh: PtrCard; asmname '_p_HeapHigh'; external;
>
> { If set to true, `Dispose' etc. will raise a runtime error if
> given an invalid pointer. }
> HeapChecking: Boolean; asmname '_p_HeapChecking'; external;
>
Yes the above is going to strait forward to implement.
> But if there's only one comment at the top, put them in one section
> all together:
>
> const
> { Foreground and background color constants }
> Black = 0;
> Blue = 1;
> Green = 2;
> Cyan = 3;
> Red = 4;
> Magenta = 5;
> Brown = 6;
> LightGray = 7;
>
> Of course, in the indices, there should be entries for each of them.
Now this is tricky:
1) What do you call the node/section for this list of vars/functions
ect...?
2) You can't just assume that because there is not a comment that it
belongs to what was above. If you do what happens for those cases where
I haven't finshed writing the documentation for my code?
I'm thinking that to solve this we are going to need a group command.
Something like {@group group name} .... {@end group }
Where 'group name' would be the name used for the section/node.
And Yes I agree that every item needs to be placed in the index but what
happens in the case where you don't want them all in the index. maybe a
option to the @group command.
>
> > 2) If I where to put them in the section menu how about this menu sytle:
> >
> > @menu
> > * MaxInt:: Const
> > * SomeVar:: Var
> > * SomeType:: Type
> > * FuncFoo:: function
> > * ProcFoo:: Procedure
> > @end menu
> >
> > Or
> > @menu
> > * Const MaxInt::
> > * Var foo::
> > * Type foo::
> > * SomeFunc::
> > * SomeProc::
> > @end menu
>
> Since the left part of the menu corresponds to the node name, I
> prefer the former, so the node name equals the identifier.
>
> BTW, you sent this mail personally, so I'm replying personally. If
> it was meant for the list, feel free to forward and/or quote my mail
> there.
>
Sorry about that.. This one is going to the group...
> Frank
Oh FYI I've started to work on a manual for pas2texi. As soon as I get it roughed
in I will send a copy to the list.
Richard
