Gpc-doc February 2003

gpc-doc@gnu.de

4 participants
5 discussions

More on documentation tool
by Richard D. Jackson 28 Feb '03

28 Feb '03

Well I've spent some time to learn texinfo. Well I should say I've gone over it and think I understand how it works that is. Anyways there are a few things I want to achive before working on pas2texi. They are in order: 1) A sample of expected output from the program. This will serve as a guide when I start to code. It will also let us agree on what that output should be. 2) A some what complete manual for the program. Again this will serve as a guide when I start to code. It will also allow us argue and or discuss the implementation details. 3) Start coding. So as a start here is an initial draft of what I think the output should be. It is the texinfo source that you can use makeinfo to transform into info/html. So after you have had a chance to look at it lets talk about it and revise it to fit what we want as far as output goes that is. Richard

3 3

Re: More on documentation tool
by Eike Lange 24 Feb '03

24 Feb '03

On Sat, Feb 22, 2003 at 12:21:18PM -0600, Richard D. Jackson wrote: > Anyways there are a few things I want to achive before working on > pas2texi. They are in order: You are working on pas2texi? Fine! > 1) A sample of expected output from the program. This will serve as a > guide when I start to code. It will also let us agree on what that > output should be. Ok, the code normally is licensed (by a header in the top of the .pas file) and the documentation itself must be licensed (always with GFDL or similar). > So as a start here is an initial draft of what I think the output should > be. It is the texinfo source that you can use makeinfo to transform into > info/html. The "node constants" (seen by comment) is really a "node variables". The rest looks fine to me. Happy Hacking ;-) Eike

1 0

Some observations [GHJ]
by Grant Jacobs 05 Feb '03

05 Feb '03

Shifting this thread over from gpc(a)gnu.de... (excuse the length of this) At 3:04 AM +0100 28/1/03, Frank Heckenbach wrote: >Grant Jacobs wrote: > >> A few observations from trying out gpc (Linux). >> >> 1. --interface-only -c doesn't (always) produce a .o as the docs >> say, > >Where does it say so? Oh, you mean in the `-c' description. OK, the >`--interface-only' description should make it clearer that it >overrides `-c' in this regard. (To me, "compiling the interface" is >clear enough to mean producing only a gpi file, but probably not to >everyone ... ;-) If you try use --interface-only on its own, the compiler stops and says you must use either -c or -S with it. So I presumed (always a bad thing to do!) after reading the -c description that your interface modules are stored as object files. (see below, also) > > but rather only a .gpi (and a .gpm in the case of modules), at >> least in my case. > >I think that's reasonable behaviour, and the docs should be >adjusted. Yes, I agree the behaviour is OK; Its the docs that need attending to! I wasn't actually meaning to complain about the behaviour. > > Either that, or its placing the object files >> somewhere else on my system! In turn, this seems to block me from >> compiling with units or modules unless I use --autobuild on the main >> program to force the issue, so to speak. > >Maybe you misunderstand the purpose of the option. It means to >process only the interface part of a unit/module. Of course, you >generally don't get a complete program without the implementation. I sort-of got this right the first time around ;-) The reason I went astray, was that I expected that compiling a unit would produce an object file, which would later be linked in when the main was compiled. In practice, none of the units I've tried compile fully on their own. You get complaints about undefined main, etc., which lead me to thinking that there much be some sort of compiler switch that'd tell it to not look for / create a main function, just create an object file 9library if that suits you better) to later be linked to a main program. That, in turn, lead me to fiddling around with different options. Which... you get the drift, anyway. This is why a description of how to compile units/modules would have helped... I suppose there is something down in the description of generation of .gpi/.gpm files that might have caused the penny to drop. But currently there appears to be nothing explicit says how its supposed to work. >`--interface-only' is only useful (necessary) in situations with >circular unit/module dependencies, e.g., A's interface uses B, and >B's implementation uses A. The only way to compile this is to first >compile B with `--interface-only', then A and B again without the >option. This paragraph ought to be inserted into the docs in the --interface-only description! (Nicely, worded - thanks.) > > 2. The blocksize parameter to reset() appears not to be optional (as >> the doc says it is) > >: Reset >: >: Like @samp{Rewrite}, @samp{Append} and @samp{Extend} do, >: @samp{Reset} accepts an optional second and third parameter for the >: name of the file in the filesystem and, for untyped files, the block >: size of the file. (For details, see @ref{Rewrite}.) > >: Rewrite >: >: The last optional parameter determines the block size of the file. >: It is valid only for untyped files. Almost always, 1 is the most >: reasonable value here. However, the existence of this parameter is a >: BP compatibility feature, and in BP it defaults to 128 because of >: historic misdesign. Therefore, GPC requires this parameter to be >: present. In @samp{--borland-pascal} mode, it makes it optional (like >: BP does), but warns about the strange default if omitted. > >I admit, it could have been made a little clearer ;-), and if you or >someone wants to help on the documentation, that's always welcome. I read the reset docs, not rewrite. I might tweak the docs at some stage. > > if the file is untyped. It'd be nice if there was > > a 'silent default' so that existing programs work 'as is'. For example >> reset( infile, infname ) ; >> gives a syntax error and demands that a buffer size be added. > >Yes, it's be nice, but BP stands in the way, as noted above. (AFAIK, >the misdesign goes back to UCSD Pascal and the CPM file system ...) >I think it would be too confusing to have two different silent >defaults, depending on the dialect option. But how about an explicit default by the user from the command-line? Easier than fiddling with their code (not that that's a terribly to do in this case)... low priority... its solvable if faintly irritating. if it was C, I'd use a macro to solve this, FWIW. >The only thing I could possibly imagine would be to make the >difference clear in some other way, e.g. to have the file declared >as `file of Void' or so (with a default of 1), whereas a simple >`file' (as in BP) behaves as it does now. Or redefine type File, doing which, err, must raise its own issues... type file = file of void ; {or} file = file[1] ; { ie file[<bufsize] } {or assigning it, a la OOP in an initialisation section } file.bufsize = 1 ; Hmm. Getting a bit fanciful, perhaps. What I'm trying to do is to tie the buffer size with the file handle, which does makes some sense. I suspect fewe users would vary the buffer size from one reset/rewrite to another, so in principle it could be associated with the file for most folk. But I can see the merits of sometimes needing to altering it. > > 3. One of my enumerated types contains 'property' and 'operator' >> which prove to be GPC reserved words of some sort as the compiler >> throws up a syntax error. I don't really want to have to alter >> these... are these keywords part of some new standard? > >`property' is from Delphi, `operator' from PXSC. > >Generally, if you don't want any extensions (which include a few new >keywords, of course), try `--extended-pascal'. > >The next GPC will also support `--disable-keyword=property,operator' >(or `{$disable-keyword=property operator}' in the source). Grr. Any ideas on how long its going to take for this to appear? I got the vague idea that part of the strategy of GPC was to allow keywords to be redefined so that older code won't bump into keywords from newer/different implementations of Pascal. So this isn't really in place yet? > > 4. It'd be nice to sort the command-line options. They are hard to >> locate as they are without trawling through the whole list. > >OTOH, they are (somewhat) sorted by topic now. But no topic headings... yet ;-) >Well, we could have one list as it is now, and another one in >alphabetic order with the same information. > >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. Besides, we could aim to write our own O'Reilly Nutshell book :-) JK! And I really mean JK! [snip] > > 6. While I appreciate the effort that has been made, personally, I >> don't consider projects complete until the docs have been written... > >I don't think anyone would consider GPC complete in any way. ;-) I know, but... :-) [snip] > > > Can I suggest that a scheme allowing user's to add >> > comments/observations to the docs be made so that at least some >> > information gets into the docs. while the implementors have their >> > minds elsewhere? Perhaps add some keyword to indicate that this >> > item/section has been written by a user rather than implementor? For >> > example perhaps bracketing the text in the spirit of the way that XML >> > does, so that the reader can easily identify which bits have been >> > contributed by users and thus while probably true need to be taken >> > with a little salt :-) >> > >> > Alternatively add another section "user's observations" or some such >> > to the description of each element. >> > >> > It might also prove a useful reference of when user's experiences are >> > at odds with the implementors intentions while a bug fix is pending. >> > >> A gpc wiki would fit the bill for such a setup. > >I'm somewhat skeptical. There have been a number of other >suggestions over the years to address the "formal issues", but in >many cases, the potential contributors lost interest or had no time >to spend shortly after (or even before) the formalities had been >settled. What I'm suggesting is a little different. Provide a framework within the docs that users can add their own observations to, but one that such that readers can see that its a user contribution. Then users can add as little or much as they like. You'd occasionally want an editor to run over the whole thing and make it more consistent. (Or have two versions of the docs - last edited version and the free-for-all version) >In the end, it really comes down to the fact that someone has to >write the stuff ... > >Actually, it's not a big issue for me to apply documentation changes >I get (and to review them for serious mistakes) -- a simple patch >sent to me or the gpc-doc list will do. I've been getting some up to >now -- but unfortunately too sporadic and by far not enough to >really cover the holes ... If you can get the automatic docs out in some format, have a field 'user notes' or whatever present. Let the users add to that. You can then receive contrib.s as diffs or simply merge the new and old docs. >So I suggest to focus on the content first, not on the formalities. I agree. Fits with what I see as the pragmatic nature of GPC. The user notes can help in this respect. >Of course, if there are several contributors you might want to agree >on the areas you work on to avoid overlaps (though the chances are >small, given the number of holes) ... :-) I'd just have people submit their bits "without delay" so we'd discover that soon enough before they built up too much of a head of steam... :-) Lazier than some formal coordination scheme! > > > Really the implementors ought to be using something like HeaderDoc or >> > whatever and write these descriptions as they code... just a > > > thought... > > >> Again I agree with you. I have only been able to find pasdoc but it was >> wrote for delphi/kylix/fpc which means the code may not be portable to >> gpc. It also has not been touched in a couple of years. I grabed a copy > > of the source and am going to take a look at getting it ported to gpc >> and add some things to it. For instance right now it will output HTML >> and Texi. The HTML part is OK but I will need to work on the Texi part > > and change it to texinfo as that is what is being used for gpc. > >I've made some plans for such a utility, in particular some features >required, and some ideas for the syntax. I've been working on something along these lines myself. (I'm very slowly working towards writing my very own little language, which will probably have an audience of one, ie. me!) >My main goal would be (unlike some -- I don't know if all -- of the >other utilities), to have the syntax as simple and readable as >possible, e.g. to use paired quotes (like `foo') for markup (which >would be @samp{foo} in texi). The purpose would explicitely *not* be >to have a complete layout system (such as TeX; I think already texi >is not), but to focus on the common things. (There can always be an >escape mode for the occasional exception.) I agree: the learning curve needs to be small. >In the end, the existing comments in the unit interfaces, where they >exists, should be accepted with few modifications, and the output >should replace the interface copies in p/doc/generated. > If there is some real interest, I could write my ideas (which now >are just some random notes). I'd be interested to see how our ideas compare. I'm working in C, but trying to make it language-independent in a simplistic way. > > I may >> actualy just end up rewriting it from scratch as it is using quite a few >> custom class that duplicate units gpc already has and I would prefer to >> use the ones gpc provides verses costom ones. I know what you mean :-) >BTW, I don't quite see where such a utility would need classes and >collections and all that stuff at all, but then, I'm only a moderate >OOP follower ... > >Frank > >-- >Frank Heckenbach, frank(a)g-n-u.de, http://fjf.gnu.de/, 7977168E >GPC To-Do list, latest features, fixed bugs: >http://www.gnu-pascal.de/todo.html >GPC download signing key: 51FF C1F0 1A77 C6C2 4482 4DDC 117A 9773 7F88 1707 -- -------------------------------------------------------- Grant Jacobs grant.jacobs(a)clear.net.nz McAndrew Bay, Dunedin, ph. +64 3 476 1820 NEW ZEALAND. fax. +64 3 476 1825

3 5

Re: Some observations [GHJ]
by Grant Jacobs 05 Feb '03

05 Feb '03

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 Ph.D. BioinfoTools ph. +64 3 476 1820 (office, after 10am) PO Box 6129, or +64 25 601 5917 (mobile) Dunedin, gjacobs(a)bioinfotools.com NEW ZEALAND. Bioinformatics tools: deriving knowledge from biological data Bioinformatics tools - software development - consulting - training Check out the website for more details: http://www.bioinfotools.com The information contained in this mail message is confidential and may be legally privileged. Readers of this message who are not the intended recipient are hereby notified that any use, dissemination, distribution or reproduction of this message is prohibited. If you have received this message in error please notify the sender immed- iately and destroy the original message. This applies also to any attached documents.

3 4

Re: Some observations [GHJ]
by Frank Heckenbach 04 Feb '03

04 Feb '03

Richard D. Jackson wrote: > What I envioson is more of a tag syntax verses a complete layout system. > By tag I mean something that indicates that something is: > Author name > Module version > copyright notice > description 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(a)bigfoot.com> : Frank Heckenbach <frank(a)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. > But not a whole lot of stuff. Leave formating and structure up to the > output code. This is how POD, JavaDoc ( core stuff that is ) and a few > others do. That way if you don't like the output you can write your own > output generator that will format it the way you want. Core Doxygen does > this as well but becasue the backend dictates the output form/layout it > has had many output generaters created for it. But I think its down fall > is that it does allow the programmer to use or embed form/layout stuff > for specific output generaters which means the programmer spends can > spend too much time trying to do some special form/layout verses just > writing the doc. 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. > 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). > One other thing I would like for it to do besides output the > documentation is to output a cross referance list so that other modules > can referance the doc if needed. > For instance lets say I'm writing a string utility unit wouldn't it be > nice if I could referance the RTS with in my doc's and actualy have a > working link to the RTS doc for a paricular function/procedure verses > something like this " see these functions in the RTS documentation > ....." 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: > 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. > 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. Frank -- Frank Heckenbach, frank(a)g-n-u.de, http://fjf.gnu.de/, 7977168E GPC To-Do list, latest features, fixed bugs: http://www.gnu-pascal.de/todo.html GPC download signing key: 51FF C1F0 1A77 C6C2 4482 4DDC 117A 9773 7F88 1707

3 11

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

2005

2004

2003

2002

2001

2000

Gpc-doc February 2003