Richard D. Jackson wrote:
These are usually global (per module), currently contained in a comment at the top. Ideally, the tool would get them from there using the existing information. E.g.:
: { Some utility routines for compatibility to some units available : for BP, like some `Turbo Power' units.
Title
: Copyright (C) 1998-2003 Free Software Foundation, Inc.
Copyright notice (keyword "Copyright" :-).
: Authors: Prof. Abimbola A. Olowofoyeku African_Chief@bigfoot.com : Frank Heckenbach frank@pascal.gnu.de
Author name(s) (keyword "Author(s)").
[Further description (could be put right after the title if it makes things easier)]
: This file is part of GNU Pascal. : : GNU Pascal is free software; you can redistribute it and/or modify
License (could be put together with the copyright notice if it makes things easier).
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.
code example
Yep.
header ( by this I mean module header or description )
These are the things mentioned above, aren't they?
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. :-)
Of course, adding more references explicitly (`@seealso' in my example) should also be possible.
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.
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.
Not necessarily. If you're worried about cross-references, Texinfo handles them already (see below).
As you might know, texi has references that refer to "nodes" by name. If we generally make each node's name the same as the identifier being described, we can refer to every identifier in the current or another module the same way. (The scheme would break if there are several identifiers of the same name in different modules. This is allowed, but honestly, who would do so -- within one project! I think we can ignore this. ;-)
So the translation would run like this (which is basically what is done now for the GPC manual, where the part of the new tool is taken by a simple copying of the interface):
foo.pas -> foo.texi bar.pas -> bar.texi baz.pas -> baz.texi myproj.texi (contains the main menu and possibly other documentation) {myproj,foo,bar,baz}.texi -> myproj.{info,html,dvi,ps,pdf,...}
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}'.
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.
Grant Jacobs wrote:
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 don't know if speed is a real concern here, but still I'd prefer the separate translation approach, too.
Frank
On Thu, 2003-01-30 at 11:30, Frank Heckenbach wrote:
Yes I agree and it is the way it should be. I'm going to snip the example you gave below this statment for now just because it is further down the process than I want to be at this point.
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.
True. I was kinda of asleep when I wrote this :)
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.
<snip>
Yes I do agree with you in that we should have things like bold and italics
Yes the documenter can indicate that he/she wants emphasis and leave it up to the backend to decide how to do it.
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.
<snip>
Yes but how do I go directly to a particular section in the info file?
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.
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?
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 need to think about this some more :)
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. )
~bold = this will mark the following text in bold. ~end = This ends a format command.
After that is done I will write up something for the tags.
The next stage would be how do you use the tags/commands we have decided on.
I'll leave it at that for now.
Richard
Richard D. Jackson wrote:
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.
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?) ...
Nitpick: I don't want stuff like bold and italics, but stuff like emphasis and "code" markup (i.e., no physical, but logical markup).
Exactly.
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.
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).
(makeinfo)
But I think you're thinking of texi references as more difficult than they are -- unless I'm missing something ...
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.
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
On Fri, 2003-01-31 at 23:06, Frank Heckenbach wrote:
Sorry about that try this: http://java.sun.com/j2se/1.4.1/docs/api/java/awt/Paint.html And look at the Method Detail section at the bottom. There happens to be only one method for this but it does show what I'm thinking about.
Ok I get it this time :)
Ok
Maybe I need to spend some time and learn texinfo better. As right now I know very little about what it can and can't do.
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. 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....
I will try to make a first pass today if for no other reason than to get it going.
Richard
At 8:27 PM -0600 1/2/03, Richard D. Jackson wrote:
Spot on. Much like that layout from Web Design in a Nutshell as I was referring to earlier (I did post that didn't I?), but with all the bits together in one place. I still prefer the layout of WDIN as it interates with written documentation well (not the automatic annotations, but the long hand description of the aims and use of some feature which usually written after the fact). Also it means there are short appendices with just the least needed to remind you of the keywords, parameters, etc.
But this style is good for an on-line doc.
FWIW, I'm interested in that particular layout as its how I intend to doc my APIs.
Grant
On Sat, 2003-02-01 at 20:50, Grant Jacobs wrote:
No I don't recall seeing it.
do you have a URL for example output of WDIN?
It is allso the way I want to do mine as well. 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. Besides I can add the stuff we want later but still have the things that frank wants as well. Also I like some of the ideas he has and adding some features to get fancer output should not be hard if I design it with that in mind from the get go.
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.
Richard
At 10:36 PM -0600 1/2/03, Richard D. Jackson wrote:
See below.
= Web Design in a Nutshell, in cause you didn't guess!
If the sample chapter HTML page is anything to go by, I dont think the new book is quite as good as the old with respect the layout of this section; its shown better below in my typing I think.
Here's the bit I though I'd posted earlier, which ought to explain it (makes me wonder if I ought to repost the full post - it had a few other bits in it too) :
Since the list is generated automatically, this should be rather easy to do. But would it help, or be more confusing?
Hmm. Both, but in my ideal world (!) I'd lay out the docs. in a different way. To me the best indexing/reference scheme I have seen is in 'Web Design in a Nutshell' (O'Reilly). I wish O'Reilly would use it in their other books. The index (or appendix) has the keywords in alphabetical order, referring you to an appendix with brief synopses of the keywords in alphabetical order. These, in turn, refer you to a complete synopsis at the head of a chapter. If you still can't remember how to use the thing, you're conveniently at the start of the chapter that covers that subject area needed to (re)learn it.
The beauty of this is that it can be read either front-to-back or as a reference via the index/appendices without either disrupting the use of the other.
For example, <frameset> in the index, points to p473, which contains
<frameset> Chapter 11, page 207 ------------------------------------------------- Description: Frameset Attributes: border bordercolour cols frameborder framespacing ...
Page 207 has the full synopsis, with standards support and short descriptions of the keyword's functions, eg:
<frameset> NN: 2,3,4 - MSIE: 3,4,5 - HTML 4 - WebTV - Opera3 ------------------------------------------------------------------------ <frameset> ... </frameset>
Defines a collection of frames or other framesets
Attributes
border=number Sets frame border thickness (in pixels) ... ...
If you're _still_ stuck, you read the chapter that follows.
There is a nice hierarchy that you traverse, stopping when you've reached the level you need. If you're learning, you read from the front.
This looks like a lot of work, but if done from HeaderDoc or the like, it might be possible to automate much of this straight from descriptions in the source code.
It shouldn't be too hard to make the HTML docs like this with links for the page nos., or likewise links in PDFs. I have to admit I have a vested interest in this layout, as its its precisely how I'd like to publish my API docs...
Besides, we could aim to write our own O'Reilly Nutshell book :-) JK! (And I really mean JK!)
By this, I meant the way the WDIN book is laid out. Which, since you haven't seen it, can't be what you're referring to...! So, err, what _are_ you referring to?!
I get that impression too.
Personally I'm going to leave texinfo out of mine, but that has to do with the fact that I want it to tie in with my little computer language project and I don't want that too dependent on other things as if it even come to completion it'll have to stand on its own two little feet ;-)
Grant
On Sun, 2003-02-02 at 01:02, Grant Jacobs wrote:
Oh you are talking about a book! No I did not know or guess. Which version is it. The local used book store may have a copy I can take a look at.
<big snip>
I was refering to the link into the javadoc's
Then what are you going to use for hard copy production?
Richard
At 8:21 PM -0600 2/2/03, Richard D. Jackson wrote:
Mine is version the first edition (its now second Ed.) 4/99 print run.
I probably should have written this better. There are two reason I guess.
I have my own data structure for playing around with text. Eventually, I'd like to try to use this for parsing, etc., but in the interim it seemed to me that doc notes would be simpler chance for me to try it out, etc. In that sense my aims are rather different.
The other is that I wanted to leave the dependencies downstream as much as possible and hence the exact mechanism of hard copy production downstream too. There has to be a mechanism obviously, but I don't want to tie it to one (eg. textinfo) right from the onset. Its something of a contradiction in terms because obviously you have to tie it to _something_. Initially I want a basic key-word based internal text format that can be converted into whatever at a later stage. My initial thought is to use XML/HTML or the like. That said, I suppose it could just as easily be textinfo instead of XML... Precisely what it is could (and will) come later as its just a format after all. I want to focus on just getting a code-based layout going first. (In practice this will likely be a text rep. of the binary data structure, but that's another story; debugging, etc.) This project is a back burner as I have a hell of a lot of things to do to try make $$ -- I have a salary that comes out of the sky, so I can't afford to get _too_ sidetracked. That's why I thought it might be better for me to focus on the content of the docs and just making comments as far as the doc parser goes. [long-winded aren't I?!]
I think you're probably heading roughly the same way, albeit just using plain text, so perhaps this textinfo thing is misleading.
Out of curiosity: any thought to just allowing POD to work on GPC? Say by using //= as the lead-in (since // is a comment lead-in, and = is the POD lead-in. E.g. strip all ' '*// then hand off to POD). Spoils the fun though eh? Also I suppose dealing with the types/vars/etc might be clumsy. I suppose you could do the same with textinfo and //@. Sorry, I just had to throw this in ;-)
Grant
On Sun, 2003-02-02 at 22:12, Grant Jacobs wrote:
You might want to take a look at texinfo as it looks to have most everything you would need for both printed and hard copy. It is also very strait forward. It is also less combersome than XML and requires fewer tools to work with. My biggest dislike of texinfo has mostly been with the online viewers ( aka info ) versas with texinfo itself.
You could write a quick and dirty perl script to do that if it is what you want. But as you say dealing with the language ellements would be the tricky part.
Grant
Take a look at my reply to Frank in the next email... Richard
At 11:46 PM -0600 30/1/03, Richard D. Jackson 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.
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 ! :-)
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?
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
At 6:30 PM +0100 30/1/03, Frank Heckenbach wrote:
[snip]
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!?)
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.
Anyway, this is probably too complex for this project...
Grant
-
Frank Heckenbach -
Grant Jacobs -
Richard D. Jackson