At 9:36 AM -0600 27/1/03, Richard D. Jackson wrote:
On Mon, 2003-01-27 at 03:36, Grant Jacobs wrote:
A few observations from trying out gpc (Linux).
<snip> > 6. While I appreciate the effort that has been made, personally, I > don't consider projects complete until the docs have been written... > it seems to me much of the doc. at present is just a shell, full of > '(Under construction)'! It would make a huge difference if some of > the people who know how things are supposed to be filled in the odd > gap... > I couldn't agree with you more.
Where is the original (text) document format? Is it the HTML format? I might try poke the odd bit in myself.
It is in texinfo format in the ./p/doc/[lang] directory. also it seems some of the doc is generated as well.
Do you might telling me exactly where this is located :-) - ie. URL, etc. Is not on the website, nor my installation and ftp'ing ft.gnu.de doesn't any me any joy...
Grant
Grant Jacobs wrote:
It is in texinfo format in the ./p/doc/[lang] directory. also it seems some of the doc is generated as well.
Do you might telling me exactly where this is located :-) - ie. URL, etc. Is not on the website, nor my installation and ftp'ing ft.gnu.de doesn't any me any joy...
It's in the GPC source distributions.
Richard D. Jackson wrote:
As I stated above I need to learn more about texinfo. And I do agree that symbolic forms are/should be easer to read. Anyways give me a little time to look into texinfo a little more for the output side.
Given the original copyright notice in my draft (1999) and that it's been laying around since then, I guess you can take all the time you need. :-)
But in the mean time I think we need to move this discusion over to what symbols do we need, What can we figure out from the code so don't need symbols for ect....
Exactly. I think identifiers will have to be marked up in some way since some identifiers are words that occur in normal language, so automatic recognition would be overkill. What would be possible automatically though (however with some effort), is to detect whether a given identifier is
- the current one
- directly belonging to the current one (i.e., record/object field, routine parameter)
- in another package (if we do the reference list)
- in the same package (either via multi-pass, in case it's further down, or simply by assumption if nothing of the above cases matches)
I think it's fair to say that all identifiers of the last two classes should go into the "see also" section automatically (which should take care of a large part of these sections already).
Grant Jacobs wrote:
Grant Jacobs wrote:
Don't include format per se, but include some style class information like 'header' 'text' etc so that it can be appropriately formatted later.
I'd prefer sections to headers. The difference may be small, but rather than inserting headers here and there, this will structure the documentation. I suppose that smaller units will not need sections at all, but for larger ones they could be useful. One hierarchy level should be enough, though.
I think what Richard was driving at is that this level of annotation is to be done outside the code, after the fact. In the code, you just have the elements. Later you style the elements into some formatted structure. The formatted structure would be defined, say, in a style sheet (etc.) which would be separate from the code & initial doc output. Or are we missing eachother's points??? (Or agreeing and crossing on our explanations!?)
If that's Richard's point, I don't think I agree. I prefer to have all information contained in the source file. So everyone who gets the (Pascal) source also has the full documentation implicitly.
I don't really see a "visual" problem with sectioning comments in a source file, either. Many use some kind of them (e.g., lines of `***', `===' or whatever) anyway, and turning them into a slightly different form would not be a big change.
So you actually get up to three levels:
- The units that a projects consists of (if several ones) which can be turned into sections automatically, of course.
- The explicit sections within a unit via comments which can become subsections in the output.
- If you will, blocks of related constants etc. (say, the color constants in the CRT unit) which do not need individual comments. Though they probably shouldn't be separate sections, but rather several entries on one page.
Its a good point, but I think processing all the files in a single pass has exactly the same flaw as compiling code in the same fashion. The interface/implementation approach was developed for that reason.
I don't know if speed is a real concern here, but still I'd prefer the separate translation approach, too.
I wasn't thinking of speed but independence of each module, ie. that documenting one module can go ahead independently of the other to a degree if the cross-referenced bits are accessed/checked/coordinated in some sensible manner. (Think of how given another module's definition components, you can (in principle!) develop a separate module, compiling against the definition module.) Put another way, I was probably thinking more along the lines where different (sub)projects need to refer to eachother, which as you commented is a somewhat different issue.
This is probably also a concern with GPC for some time since the various units will probably be documented at different speeds.
However, in my idea, the utility can even process a completely uncommented source file. It will then generate basically skeleton entries (though I can understand well if you don't exactly like them, given the amount of them in the current manual ;-). At least they would contain the unit name and synopsis, so they're better than nothing, and they'd allow for references from other modules to work (i.e., point to the skeleton instead of missing) ...
Grant Jacobs wrote:
This is actually along the lines of what I was trying to refer to with the implementation/definition/cross-ref thing... you'd need doc modules to 'export' the references that other doc modules can refer to, etc.
Practically, its probably better to have a program scan the docs for marked up keywords, which can simply be added to a cross-ref file. You could easily have one for each doc file, that represented the compiled symbol refs for that doc, which can then be referred to by any other, etc.
This might be useful. Though I think I'd rather have a single program do both (probably controllable by options), because having several "parsers" for the same "input language" (i.e., the marked up comments) can more easily lead to inconsistencies ...
You could do it via one long list, which I think is what you're suggesting, or one for each doc file. I was thinking of the latter originally, but one cross ref file is probably enough for this project I suspect ! :-)
If the files are translated separately, I guess also the reference files will have to be separate, but that's a detail and will turn out when it's implemented.
Richard D. Jackson wrote:
But one of the things I really need to do is look over what texinfo can or can'nt do. Because I would really like my online doc's and printed docs to have a simular layout if possible.
That's precisely the goal of texinfo. It is not a universal formatter (unless you use explicit conditionals for the different output formats), but within its scope, it provides for equivalent documentation in the various formats from a single source (which IMHO is absolutely essential for GPC, given the amount of stuff to be documented, and the lack of human resources to even maintain several overlapping documentations) ...
Grant Jacobs wrote:
But I think for a first pass I will take a harder look at what frank wants as it is not nearly as complicated as what we want.
I get that impression too.
When I reviewed my draft before posting, I actually wondered if it wasn't too complex already. ;-) But we can always discuss whether some particular features should be added or omitted ...
Frank
On Sun, 2003-02-02 at 22:42, Frank Heckenbach wrote:
Grant Jacobs wrote:
<snip>
Richard D. Jackson wrote:
As I stated above I need to learn more about texinfo. And I do agree that symbolic forms are/should be easer to read. Anyways give me a little time to look into texinfo a little more for the output side.
Given the original copyright notice in my draft (1999) and that it's been laying around since then, I guess you can take all the time you need. :-)
But in the mean time I think we need to move this discusion over to what symbols do we need, What can we figure out from the code so don't need symbols for ect....
Exactly. I think identifiers will have to be marked up in some way since some identifiers are words that occur in normal language, so automatic recognition would be overkill. What would be possible automatically though (however with some effort), is to detect whether a given identifier is
the current one
directly belonging to the current one (i.e., record/object field, routine parameter)
in another package (if we do the reference list)
in the same package (either via multi-pass, in case it's further down, or simply by assumption if nothing of the above cases matches)
I think it's fair to say that all identifiers of the last two classes should go into the "see also" section automatically (which should take care of a large part of these sections already).
I actualy got some time the other day and took a little harder look at pasdoc. And you know something it has most of what we want. Including a very simple markup style. It only looks at comments in the interface section and all non escaped comments are included in the documentation where the comment is placed right before the procedure/function var, const, class ect... It also contains a fairly complet pascal language parser. It uses this to figure out what the laguage elements are after the comment. And it fully indexes everything. The one down fall is that it only outputs TeX and HTML. But from what I can see adding texinfo should not be hard.
So for the time being I'm going to spend some more time looking at it and see if I can get it to compile on gpc. Then I'm going to spend some time cleaning it up as the original author has allot of conditional code so it will build with quite a few differant compilers. Seeing that I'm only interested in gpc I may remove that stuff.
I've tried to contact the auther ( Marco Schmidt ) but my email bounced. I will try again but he may have moved on. Luckly the code is under the GPL so it won't be a problem for me or gpc to use it. But I should change the name though.
Grant Jacobs wrote:
Grant Jacobs wrote:
Don't include format per se, but include some style class information like 'header' 'text' etc so that it can be appropriately formatted later.
I'd prefer sections to headers. The difference may be small, but rather than inserting headers here and there, this will structure the documentation. I suppose that smaller units will not need sections at all, but for larger ones they could be useful. One hierarchy level should be enough, though.
I think what Richard was driving at is that this level of annotation is to be done outside the code, after the fact. In the code, you just have the elements. Later you style the elements into some formatted structure. The formatted structure would be defined, say, in a style sheet (etc.) which would be separate from the code & initial doc output. Or are we missing eachother's points??? (Or agreeing and crossing on our explanations!?)
If that's Richard's point, I don't think I agree. I prefer to have all information contained in the source file. So everyone who gets the (Pascal) source also has the full documentation implicitly.
I do agree with you here BTW. But I also think that Grant is thinking the same thing but we are crossing on explanations. Grant's comment above I think is on the presentation side of things versers the content side.
I don't really see a "visual" problem with sectioning comments in a source file, either. Many use some kind of them (e.g., lines of `***', `===' or whatever) anyway, and turning them into a slightly different form would not be a big change.
So you actually get up to three levels:
The units that a projects consists of (if several ones) which can be turned into sections automatically, of course.
The explicit sections within a unit via comments which can become subsections in the output.
If you will, blocks of related constants etc. (say, the color constants in the CRT unit) which do not need individual comments. Though they probably shouldn't be separate sections, but rather several entries on one page.
Its a good point, but I think processing all the files in a single pass has exactly the same flaw as compiling code in the same fashion. The interface/implementation approach was developed for that reason.
I don't know if speed is a real concern here, but still I'd prefer the separate translation approach, too.
I wasn't thinking of speed but independence of each module, ie. that documenting one module can go ahead independently of the other to a degree if the cross-referenced bits are accessed/checked/coordinated in some sensible manner. (Think of how given another module's definition components, you can (in principle!) develop a separate module, compiling against the definition module.) Put another way, I was probably thinking more along the lines where different (sub)projects need to refer to eachother, which as you commented is a somewhat different issue.
This is probably also a concern with GPC for some time since the various units will probably be documented at different speeds.
However, in my idea, the utility can even process a completely uncommented source file. It will then generate basically skeleton entries (though I can understand well if you don't exactly like them, given the amount of them in the current manual ;-). At least they would contain the unit name and synopsis, so they're better than nothing, and they'd allow for references from other modules to work (i.e., point to the skeleton instead of missing) ...
Yes Even if no documentation is provided then if nothing else it should document what is there. What functions/procedures vars, records ect. where each is a seperate index/section point.
Grant Jacobs wrote:
This is actually along the lines of what I was trying to refer to with the implementation/definition/cross-ref thing... you'd need doc modules to 'export' the references that other doc modules can refer to, etc.
Practically, its probably better to have a program scan the docs for marked up keywords, which can simply be added to a cross-ref file. You could easily have one for each doc file, that represented the compiled symbol refs for that doc, which can then be referred to by any other, etc.
This might be useful. Though I think I'd rather have a single program do both (probably controllable by options), because having several "parsers" for the same "input language" (i.e., the marked up comments) can more easily lead to inconsistencies ...
Yes I agree a single tool to do both jobs. Where the default is to output both the documenation and a machine readable index.
You could do it via one long list, which I think is what you're suggesting, or one for each doc file. I was thinking of the latter originally, but one cross ref file is probably enough for this project I suspect ! :-)
If the files are translated separately, I guess also the reference files will have to be separate, but that's a detail and will turn out when it's implemented.
Richard D. Jackson wrote:
But one of the things I really need to do is look over what texinfo can or can'nt do. Because I would really like my online doc's and printed docs to have a simular layout if possible.
That's precisely the goal of texinfo. It is not a universal formatter (unless you use explicit conditionals for the different output formats), but within its scope, it provides for equivalent documentation in the various formats from a single source (which IMHO is absolutely essential for GPC, given the amount of stuff to be documented, and the lack of human resources to even maintain several overlapping documentations) ...
I really need to make the time to read the texinfo manual :) If the explicit conditionals you mentioned above will let me do what I want for the HTML output then I just may end up with one output format. With a switch to pretty up the HTML if you want it.
Grant Jacobs wrote:
But I think for a first pass I will take a harder look at what frank wants as it is not nearly as complicated as what we want.
I get that impression too.
When I reviewed my draft before posting, I actually wondered if it wasn't too complex already. ;-) But we can always discuss whether some particular features should be added or omitted ...
Your draft is significaly simpler than pasdoc but then again pasdoc spends most of its time figuring things out from the code so that the code becomes a source for the documentation. Which is the right way to do it as it makes writing the documentation easer on the programmer.
Boy has my list of things todo increased from this conversation: 1) Read the texinfo manual 2) port and update pasdoc 3) learn more about pascal. Well if nothing else porting and updating pasdoc will make me learn more pascal. And I think it is a worthy first project as it will cover most of the language scope.
Richard
Richard D. Jackson wrote:
That's precisely the goal of texinfo. It is not a universal formatter (unless you use explicit conditionals for the different output formats), but within its scope, it provides for equivalent documentation in the various formats from a single source (which IMHO is absolutely essential for GPC, given the amount of stuff to be documented, and the lack of human resources to even maintain several overlapping documentations) ...
I really need to make the time to read the texinfo manual :)
It might look quite complex initially (there are many things that are rarely used). Sometimes it's easier to just look at some existing documentation ...
If the explicit conditionals you mentioned above will let me do what I want for the HTML output then I just may end up with one output format.
Yes, they look like this (from GPC's documentation):
@ifhtml @html <table align=right><tr><td> <a href="../images/GnuPascal.png"> <img alt="[Gnu and Blaise Pascal]" src="../images/GnuPascal-small.png" width=123 height=99><br> (PNG, 10 KB) </a> </td></tr></table> @end html @end ifhtml
`@ifhtml' is the conditional (there are `@if[not]{html,info,plaintext,tex}'), and `@html' allows for verbatim HTML code.
With a switch to pretty up the HTML if you want it.
If you mean me, I'm not sure if I want it. I think I'd have too see a concrete example and what the "pretty up" would do, but I guess we'll find out in time ...
Your draft is significaly simpler than pasdoc but then again pasdoc spends most of its time figuring things out from the code so that the code becomes a source for the documentation. Which is the right way to do it as it makes writing the documentation easer on the programmer.
Yes, I expect this to be the difficult part. The output should be the considerably easier bit.
My biggest dislike of texinfo has mostly been with the online viewers ( aka info ) versas with texinfo itself.
You mean the "default" info reader? I don't like is as well (I find it harder to use than vi, and I'm not a fan of vi ;-). But that's not the only one that exists. RHIDE as well as my editor PENG contain their own info readers and I think emacs also does, and probably more programs. But if you prefer HTML or PDF, just use that. :-)
Frank
On Tue, 2003-02-04 at 17:01, Frank Heckenbach wrote:
Richard D. Jackson wrote:
That's precisely the goal of texinfo. It is not a universal formatter (unless you use explicit conditionals for the different output formats), but within its scope, it provides for equivalent documentation in the various formats from a single source (which IMHO is absolutely essential for GPC, given the amount of stuff to be documented, and the lack of human resources to even maintain several overlapping documentations) ...
I really need to make the time to read the texinfo manual :)
It might look quite complex initially (there are many things that are rarely used). Sometimes it's easier to just look at some existing documentation ...
If the explicit conditionals you mentioned above will let me do what I want for the HTML output then I just may end up with one output format.
Yes, they look like this (from GPC's documentation):
@ifhtml @html
<table align=right><tr><td> <a href="../images/GnuPascal.png"> <img alt="[Gnu and Blaise Pascal]" src="../images/GnuPascal-small.png" width=123 height=99><br> (PNG, 10 KB) </a> </td></tr></table> @end html @end ifhtml
`@ifhtml' is the conditional (there are `@if[not]{html,info,plaintext,tex}'), and `@html' allows for verbatim HTML code.
Great that will get what I need/want. But that is on the back burner as I want to get texinfo working first.
With a switch to pretty up the HTML if you want it.
If you mean me, I'm not sure if I want it. I think I'd have too see a concrete example and what the "pretty up" would do, but I guess we'll find out in time ...
When I get to it there I will make up some samples.
Your draft is significaly simpler than pasdoc but then again pasdoc spends most of its time figuring things out from the code so that the code becomes a source for the documentation. Which is the right way to do it as it makes writing the documentation easer on the programmer.
Yes, I expect this to be the difficult part. The output should be the considerably easier bit.
True that is the reason I'm going to work on pasdoc as all of the hard stuff is done. I just need to figure out how it does it so I can maintain it and modify it for our use.
My biggest dislike of texinfo has mostly been with the online viewers ( aka info ) versas with texinfo itself.
You mean the "default" info reader? I don't like is as well (I find it harder to use than vi, and I'm not a fan of vi ;-). But that's not the only one that exists. RHIDE as well as my editor PENG contain their own info readers and I think emacs also does, and probably more programs. But if you prefer HTML or PDF, just use that. :-)
I will have to look into RHIDE and PENG.
Richard
-
Frank Heckenbach -
Grant Jacobs -
Richard D. Jackson