Richard D. Jackson wrote:
return type/description ( may or may not need this ) paramiter
As for the syntax, these are clear from the declaration, therefore should not require further commenting.
I think it should be enough to write the declaration in the "Synopsis" part. A Pascal programmer ought to know what the declaration means and how to use it.
The semantics of each parameter and the return value (if any), of course, should be described in the text, but I'm not sure we need any formalities for that.
Take a look at this http://java.sun.com/j2se/1.4.1/docs/api/index.html ignore the stuf at the top and scroll down to the section containing the method documentation. This is the type of format/output I would like to see the html ouput engine produce for a function/procedure. I wouldn't mind seeing that type of output on the texinfo side either but I definatly want it on the html side. Now to do that type of formating will require that the documenter mark what is what.
Could you please give an exact URL of the page you mean? The URL above contains a frameset with several menus, I'm not sure exactly what to look at.
referance
Yes, quite important. As I wrote in my program's comments, I'd prefer to make them as easily as possible, e.g., <foo> will write the identifier foo in the text, but also put it in the references section. It might seem a small issue, but not having to write the thing twice (in the text and the references) is more comfortable and will probably encourage people to use many references. :-)
The problem with using <foo> would be that now to include a <> in your documentaion would mean you have to escape it so that a ref is not created. So I think the first thing to deside is what do you use to denote a command. example @ % * ~ whatever it is I would prefer something that will mostlikly not be needed in the docmentation so we don't have to worry about escapes.
But code samples which can include `<>', `@' etc. should already be marked up as such. That's why I suggested `...' for code samples in my draft. Markup within code samples is pointless and shouldn't be recognized, therefore these characters are "harmless".
OK, I admit, the single quote (') can appear in Pascal, so using it for the end of a code block is not good. So I'd now prefer another delimiter such as one of the chars that doesn't occur in any Pascal dialect which seem to be !%`|~, so perhaps |code| or `code` (hmm?) ...
I basically agree. Though I think there is some amount of markup we need. E.g., to mark identifiers (see above, with references for identifiers mentioned besides the current ones), and to mark sections of code etc. E.g., the description of gpc.pas:CanRead currently says:
[...] This is similar to `not EOF (aFile)', but [...]
So the `not EOF (aFile)' part should be marked in some way to avoid confusion -- preferably (to me) `...' in the input and @samp{...} in the texi output.
Yes I do agree with you in that we should have things like bold and italics
Nitpick: I don't want stuff like bold and italics, but stuff like emphasis and "code" markup (i.e., no physical, but logical markup).
Also, it *might* be useful to write emphasis sometimes. In plain text formats which don't provide for this, people will often use *...* for it, so a tool could just as well convert it to proper emphasis in the output.
Yes the documenter can indicate that he/she wants emphasis and leave it up to the backend to decide how to do it.
Exactly.
First the question I would have is what is the target application of the documenter? If for only documenting single monolithic units then a single pass ( single file ) tool would do the job. But on the other hand if you want to handle multi-module/unit applications that need to beable to cross link the documention and or have a unified cross-referance amogst all the code modules then what you really want to do is process all of the files in a single pass.
Not necessarily. If you're worried about cross-references, Texinfo handles them already (see below).
Yes Texinfo does but HTML does not. True you can just output Texinfo and then convert that to HTML but doing it that way you loose some of the things you can do in HTML that Texinfo was not designed for.
I don't think we should use any such things in the documentation at all, i.e. stick to the lowest common denominator. Or do you have anything in particular in mind which is absolutely essential and not possible to texi?
I also don't think it's worth the extra effort to create HTML directly rather than going via texi. At least for the GPC website, I probably wouldn't use it, anyway, since it's generated from one texi source so references work best.
It's different when you want to refer to things from other projects (e.g., you write documentation for your own code and want to refer to the GPC manual directly). BTW, that's no different whether the tool will translate single or multiple files, since different projects are translated separately, anyway. Actually, all that's required then is to get the name of the other documentation file -- the texi reference would then look like `@ref{WriteLn,,,gpc}' instead of `@ref{WriteLn}'.
Again how would you go directly to WriteLn in the texi file. Yes going to the main menu of the texi file would be easy but I want to link directly into it.
Well, just what I wrote. `@ref{WriteLn,,,gpc}' goes to the node `WriteLn' in the file `gpc' (in info and also the other texi outputs).
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?
(makeinfo)
But I think you're thinking of texi references as more difficult than they are -- unless I'm missing something ...
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.
I don't know exactly how you mean this, but what I do not want is to have to specify the section for each declaration. Most of the time, declarations belonging in one section are written next to each other (and I don't even see a problem to make this a fixed rule), so specifying where a new section starts should be all that's required.
But I do think the first things we need to decide is what do we use to indicate a command/tag and what tags/commands do we need. And what the tag/command should do. Lets keep it to that for now and leave how it should work or how you should use them for later. For example:
~ = this indicates a command ( I'm not advicating ~ it is just a good starting point as it is not reserved, it is not a compiler commad like {@ is and will most likly not be used in documentation. )
See above.
~bold = this will mark the following text in bold. ~end = This ends a format command.
My problem with these are that they make the text (in the source form) harder to read -- it's easier (mentally) to read over symbols than words.
That's why I suggested symbolic forms for the most common purposes (`...', <...>, *...*). And even for the occasional "named" command, I prefer a symbol at the end (such as @foo{...}).
Frank