Richard D. Jackson wrote:
Well I've spent some time to learn texinfo. Well I should say I've gone over it and think I understand how it works that is.
I think that's enough for most purposes. :-)
Anyways there are a few things I want to achive before working on pas2texi. They are in order:
- A sample of expected output from the program. This will serve as a
guide when I start to code. It will also let us agree on what that output should be.
So as a start here is an initial draft of what I think the output should be. It is the texinfo source that you can use makeinfo to transform into info/html.
So after you have had a chance to look at it lets talk about it and revise it to fit what we want as far as output goes that is.
: * GPC RTS: (rts). GNU Pascal Runtime Library.
We usually call it "Runtime System". But that's not a matter of the program -- it will get it from the input data.
: @author Frank Heckenbach @email{frank@@pascal.gnu.de}
And some more. I'm the only one listed in the file gpc.pas since I wrote this file alone, but the actual implementation was written by many others as well. (That's a special case since usually a unit contains its implementation while gpc.pas is a purely external interface module.) I guess I should simply list all authors in gpc.pas then (will do in the next release) ...
: @c ***************************************************************************** : @c =============[ Main menu ]=================================================== : @c *****************************************************************************
I'm not really a friend of such "bold ASCII headers" -- and in an automatically generated file they're not necessary for an author to orientate. But then again, in an automatically generated file they also don't disturb anyone ...
: * Variables:: Variables, Constants, and types exported by the : Runtime system.
I think those variables, constants and types declared in the sections below should be documented there, so I'd rather call this initial section something like "Misc". But again, this must be done in gpc.pas and should not affect the program, so I don't mind ...
(Of course, it's also useful to have a list of all constants etc., but that's already served for by the indices.)
: @node Top : @top GNU Pascal Runtime System (GPC) : : [...] : : @chapter Variables
BTW, the program should have options to shift down the whole hierarchy one or two levels, e.g. put the main menu in a section and the other nodes in sub- and subsubsections, for inclusion into other texts. (In this case, of course, the texi header and title page would be omitted and the copyright notice inserted only in the main menu node.)
: @table @code : : @item MaxLongInt : @conindex MaxLontInt : @table @asis : @item Declared As : @code{MaxLongInt = High (LongInt);}
(I'd add `const' here.)
: @item Description : The maximum value a @code{LongInt} can be. : @end table : : @item MaxVarSize : @conindex MaxVarSize : @table @asis : @item Declared As : @code{MaxVarSize = MaxInt div 8;} : @item Description : Maximum size of a variable. : @end table : : @end table
: @subheading Synopsis : @verbatim : uses GPC; : function SinH (x: Real): Real; : @end verbatim : @subheading Description : The @code{SinH(x)} function returns the hyperbolic sine of x, which is defined : mathematically as (exp(x) - exp(-x)) / 2. : @subheading Example : under construction : @subheading See Also : @xref{Hyperbolic Functions, libc sinh, , libc},
Why use different formatting for constants/variables and routines? I.e., why not use `Synopsis', and subheadings instead of the table for the former as well?
Frank