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