At 11:46 PM -0600 30/1/03, Richard D. Jackson wrote:
On Thu, 2003-01-30 at 11:30, Frank Heckenbach wrote:
Richard D. Jackson wrote:
To do this automatically, the cross reference list you suggested might be useful. I.e., while translating the GPC documentation, this list is produced and stored somewhere, and when translating the documentation of another project, it could use this list to find out which identifiers should have their references pointing to the GPC documentation.
Exactly! And with the list would be the exact link to it so you can go directly to it. The problem is that Texinfo will split it up and I don't know enough texinfo yet to look into how to do that for texinfo. HTML would be easy as you are going direct to finished output where as texinfo files will still need to be processed by maketexi?
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.
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 ! :-)
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.
Yes and even better do the section at the top and down in the function/procedure documenation have a tag that indicates what section this belongs to. That way you have the formater do the work of filling out the section documentation.
Do you mean "posting" to other sections of the resulting docs here (using a "target section" a kind of address concept here), so that different doc comments can go to different parts of the resulting docs?
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 need to think about this some more :)
See my previous post & above. I wasn't really referring to speed, but rather how to cross-ref docs yet maintain independence between them.
Grant