From: Staffan T. <sta...@gm...> - 2013-02-16 17:15:15
|
Quite some time ago I made some comments on the use of place-holding commas in parameter lists and the way they are documented. I didn't receive any reaction on this at the time (maybe something went wrong with my posting) and I forgot about it until now when I looked at the following description of the createStaticText method: >>--createStaticText(-+------+--x-,--y-+------+-+------+-+----------+-+--------+-)->< +-id-,-+ +-,-cx-+ +-,-cy-+ +-,-style--+ +-,-text-+ This in my opinion is a good example that illustrates the confusion that can be created when reading it. The lower line identifies the optional parameters but what I react on here is that the commas are listed there as well. If I strictly follow this to create a static text object without a resource ID, I would write it like this: createStaticText(posX, posY, posCX, posCY, myStyle, myText) But without testing it I think that the correct coding should be: createStaticText(, posX, posY, posCX, posCY, myStyle, myText) In the same way the following method call should be correct as well according to the doc, but of course it isn't: createStaticText(posX, posY, myText) Based on this I am of the opinion that the parameter list is better documented like this: >>--createStaticText(-+----+-,-x-,-y-,-+----+-,-+----+-,-+-------+-,-+------+-)->< +-id-+ +-cx-+ +-cy-+ +-style-+ +-text-+ Here there are no optional commas, which is the norm when writing a parameter list. There are exceptions to this, like the ListView 'add' method, which allows for a variable number of commas, but such exceptions are few and the variable comma seems to be documented "correctly". What's the general view on this? Staffan |
From: Mark M. <mie...@gm...> - 2013-02-16 18:05:14
|
On Sat, Feb 16, 2013 at 9:14 AM, Staffan Tylen <sta...@gm...>wrote: > Quite some time ago I made some comments on the use of place-holding > commas in parameter lists and the way they are documented. I didn't receive > any reaction on this at the time (maybe something went wrong with my > posting) > Hi Staffan, I did reply to the first posting you did. I said that all arguments are positional and that if you omit an argument you have to use a comma to keep the arguments in their correct position. I think this is fundamental to Rexx in general, at least it is fundamental to ooRexx. I went back and looked at your posting and I see that I didn't reply to your follow up, I vaguely thought I had. I was *sure* that I had put some clarifying text in the How to Read the Syntax Diagrams section. But, I see that I have not done so. ;-( > and I forgot about it until now when I looked at the following description > of the createStaticText method: > > > >>--createStaticText(-+------+--x-,--y-+------+-+------+-+----------+-+--------+-)->< > +-id-,-+ +-,-cx-+ +-,-cy-+ +-,-style--+ > +-,-text-+ > > In the above, it is sort of a unique situation with the leading id argument being optional. I would never have introduced that in a new method. In my opinion the id argument should be required, but because of backwards it has to be optional. So, I'm not real happy with how that one looks. This in my opinion is a good example that illustrates the confusion that > can be created when reading it. The lower line identifies the optional > parameters but what I react on here is that the commas are listed there as > well. If I strictly follow this to create a static text object without a > resource ID, I would write it like this: > > createStaticText(posX, posY, posCX, posCY, myStyle, myText) > > But, your thinking is wrong. ;-) If you stop and repeat to yourself 100 times: In ooRexx all arguments are positional; if I wish to omit an argument I MUST use a comma. Then I don't think you will have trouble with this any more. > But without testing it I think that the correct coding should be: > See, you already understand this. > > createStaticText(, posX, posY, posCX, posCY, myStyle, myText) > > In the same way the following method call should be correct as well > according to the doc, but of course it isn't: > > createStaticText(posX, posY, myText) > > Based on this I am of the opinion that the parameter list is better > documented like this: > > > >>--createStaticText(-+----+-,-x-,-y-,-+----+-,-+----+-,-+-------+-,-+------+-)->< > +-id-+ +-cx-+ +-cy-+ +-style-+ > +-text-+ > > Here there are no optional commas, which is the norm when writing a > parameter list. There are exceptions to this, like the ListView 'add' > method, which allows for a variable number of commas, but such exceptions > are few and the variable comma seems to be documented "correctly". > > What's the general view on this? > I am of course interested in hearing every one's view on this. My view is: Your opinion that the parameter list is better documented the way you show is a good opinion. I am not going to argue that the current style is more correct than your preference. If you had brought this up 4 years ago when I first started rewriting the doc to remove its inaccuracies I would have likely adopted that style instead of the style I did adopt. However, I think the current style is understandable. I did intend to put a clarifying statement in the section on how to read the syntax diagrams for this point. I'll be sure and do that. It already has a statement that in all cases, the text rather than the syntax diagram should be considered definitive. If you couple that statement with knowledge that in ooRexx if you omit an argument you must use the place holder comma, I don't think there is any ambiguity. I'm not going to go back and change all the already done syntax diagrams. If some one wishes to prepare a patch that changes *all* the syntax diagrams at one time to the style you propose, I'll gladly apply the patch and use that style from then on. -- Mark Miesfeld |
From: Jean-Louis F. <jfa...@gm...> - 2013-02-16 19:31:46
|
Other possibility : keep the syntax diagram as-is, and add a comma on the main line, above each optional argument (except the first one, which is a special case here, and the last one). This is not yet the right description, because commas are declared mandatory, but the syntax is correct, and the update is more easy. >>--createStaticText(-+------+--x-,--y-+-,----+-+-,----+-+-,--------+-+--------+-)->< +-id-,-+ +-,-cx-+ +-,-cy-+ +-,-style--+ +-,-text-+ A more accurate description would be similar to that : >>-TIME(--+-----------------------------------+--)------------->< +-option--+-----------------------+-+ +-,string--+----------+-+ +-,option2-+ but this is much more work to update. And more exposed to page break in the middle... |
From: Mark M. <mie...@gm...> - 2013-02-16 19:49:56
|
Hi Jean Louis On Sat, Feb 16, 2013 at 11:31 AM, Jean-Louis Faucher <jfa...@gm...>wrote: > Other possibility : keep the syntax diagram as-is, and add a comma on the > main line, above each optional argument (except the first one, which is a > special case here, and the last one). > This is not yet the right description, because commas are declared > mandatory, but the syntax is correct, and the update is more easy. > Actually, I don't think the update is easier. It is the time to go through every single syntax diagram and see if it needs to be changed, and change it, that is the hard part. My experience with working on the doc so far, tells me that it would be very time consuming. > > > > >>--createStaticText(-+------+--x-,--y-+-,----+-+-,----+-+-,--------+-+--------+-)->< > +-id-,-+ +-,-cx-+ +-,-cy-+ +-,-style--+ > +-,-text-+ > > > A more accurate description would be similar to that : > > >>-TIME(--+-----------------------------------+--)------------->< > +-option--+-----------------------+-+ > +-,string--+----------+-+ > +-,option2-+ > > That representation is exactly what I wanted to eliminate. In ooDialog with so many methods with optional parameters, you end of with many, many of the syntax diagrams on two pages. Having the syntax diagram broken up on two pages is worse than having no syntax at all in my opinion. I'm not saying that what I'm currently doing is technically accurate. It is easy to point out that it isn't technically accurate. What I'm saying is, I think it is easily understandable. And, I'm saying that the amount of time to change all the syntax diagrams to Staffan's proposal is not time I'm willing to spend. -- Mark Miesfeld |
From: Staffan T. <sta...@gm...> - 2013-02-16 19:44:43
|
> However, I think the current style is understandable. I did intend to put > a clarifying statement in the section on how to read the syntax diagrams > for this point. I'll be sure and do that. > > Sure, the current syntax diagrams are definitely understandable,but as I said I jumped on it today with the optional resource ID parameter. > It already has a statement that in all cases, the text rather than the > syntax diagram should be considered definitive. If you couple that > statement with knowledge that in ooRexx if you omit an argument you must > use the place holder comma, I don't think there is any ambiguity. > > As with a lot of other things in this generally very good documentation I've not taken the time to read everything from page one as one should, perhaps because Rexx as such was nothing new to me when I started to get acquainted with ooRexx. I'm not going to go back and change all the already done syntax diagrams. > If some one wishes to prepare a patch that changes *all* the syntax > diagrams at one time to the style you propose, I'll gladly apply the patch > and use that style from then on. > > I fully understand this position, and my comment was more academic than asking for a change. Thanks, Staffan |
From: Mark M. <mie...@gm...> - 2013-02-16 19:59:31
|
On Sat, Feb 16, 2013 at 11:44 AM, Staffan Tylen <sta...@gm...>wrote: > I'm not going to go back and change all the already done syntax diagrams. > If some one wishes to prepare a patch that changes *all* the syntax > diagrams at one time to the style you propose, I'll gladly apply the patch > and use that style from then on. > >> >> > I fully understand this position, and my comment was more academic than > asking for a change. > >From an academic point of view, I agree that your proposal is much more accurate than what I'm currently doing. ;-) As I said, if it was 4 years ago and I only had 15 syntax diagrams to change, I would change them to your style and use that going forward. As Jean-Louis pointed out, the original IBM style is the most accurate. But unfortunately, that style is much harder to produce in the first place in our document tools, hard to maintain in our document tools, and very prone to be broken up in to 2 pages with our document tools. My main goal was to prevent the diagrams from being broken up in to 2 pages. -- Mark Miesfeld |
From: Staffan T. <sta...@gm...> - 2013-02-16 19:58:24
|
> Other possibility : keep the syntax diagram as-is, and add a comma on the > main line, above each optional argument (except the first one, which is a > special case here, and the last one). > This is not yet the right description, because commas are declared > mandatory, but the syntax is correct, and the update is more easy. > > Nice idea, could probably be automated to a large extent. Thinking about it, any of the two could PROBABLY be more or less automated because the diagrams follow a definite pattern. In what format is the source to the documentation stored? SVN controlled? One file per chapter, section, page,...? I believe I saw something recently about it being changed from one mark-up language to another? Staffan |
From: Mark M. <mie...@gm...> - 2013-02-16 21:02:58
|
On Sat, Feb 16, 2013 at 11:57 AM, Staffan Tylen <sta...@gm...>wrote: > > Other possibility : keep the syntax diagram as-is, and add a comma on the >> main line, above each optional argument (except the first one, which is a >> special case here, and the last one). >> This is not yet the right description, because commas are declared >> mandatory, but the syntax is correct, and the update is more easy. >> >> > Nice idea, could probably be automated to a large extent. Thinking about > it, any of the two could PROBABLY be more or less automated because the > diagrams follow a definite pattern. > It probably could be automated if some one took enough time to do. I don't think it could be *easily* automated. Well maybe by someone more skilled than I am. ;-) > In what format is the source to the documentation stored? > In DocBook > SVN controlled? > Yes definitely. This is URL to the root of the docs, you need to convert the URL to anonymous access: svn+ssh://mie...@sv.../p/oorexx/code-0/docs/trunk This is the URL to the root of the ooDialog doc, same caveat about converting the URL: svn+ssh://mie...@sv.../p/oorexx/code-0/docs/trunk/oodialog > One file per chapter, section, page,...? > Generally in one file per related content, mostly one file per chapter, but not always. > I believe I saw something recently about it being changed from one mark-up > language to another? > It has always been DocBook since the ooRexx project started. Some years ago, David changed the file extension from .sgml to .xml. The more recent change was in the tools used to compile the books. We switched from an Open Jade tool chain to the Publican tool chain. I would heartily encourage any one with the slightest leanings towards working on the doc, especially the ooDialog doc to go for it. Patches are always welcome. Contributing some patches will get you well on your way to being nominated as a committer. As a committer you can take over the job of documenting ooDialog and I will quickly give it up. -- Mark Miesfeld |
From: Staffan T. <sta...@gm...> - 2013-02-16 21:08:17
|
> I would heartily encourage any one with the slightest leanings towards > working on the doc, especially the ooDialog doc to go for it. Patches are > always welcome. Contributing some patches will get you well on your way to > being nominated as a committer. As a committer you can take over the job > of documenting ooDialog and I will quickly give it up. > > That's what we are all afraid of :) I will have a look if we can get a quick solution to this, as long as we are in agreement that this is what we all want. Anyone against, please stand up! Staffan |
From: Mark M. <mie...@gm...> - 2013-02-16 21:32:24
|
On Sat, Feb 16, 2013 at 1:07 PM, Staffan Tylen <sta...@gm...>wrote: > > I would heartily encourage any one with the slightest leanings towards >> working on the doc, especially the ooDialog doc to go for it. Patches are >> always welcome. Contributing some patches will get you well on your way to >> being nominated as a committer. As a committer you can take over the job >> of documenting ooDialog and I will quickly give it up. >> >> > That's what we are all afraid of :) > > I will have a look if we can get a quick solution to this, as long as we > are in agreement that this is what we all want. Anyone against, please > stand up! > I have no objection to using the syntax style you proposed. I will go so far as to say your style is better and more correct than mine. I don't think the style change Jean-Louis first proposed, adding a comma on the main line, is less confusing than the current style and I would probably object to making that change. My goals are: 1.) Be able to have almost every syntax diagram fit on, at most, 2 lines. There are a very few methods where that is not possible. 2.) Have all the syntax diagrams use the same style throughout the whole book. There are still places where the IBM style has not been converted. The only reason for that is time, converting the syntax is time consuming. 3.) Be able to keep incrementally updating the ooDialog doc. So, I would object to anything that defeats those goals. Because of #3, the change from the syntax diagrams I've already done to the new style, needs to be done in a reasonably short period of time. Essentially in one step, but over a couple of days, or a week at most, would not be unreasonable. -- Mark Miesfeld |
From: Chip D. <ch...@av...> - 2013-02-17 07:20:59
|
My view on this is that Staffan is definitively correct, and that Mark's time/energy is much better directed at code matters. This is not merely an academic issue; the syntax diagrams conflict with reality (and the blanket rule). How is this any less important than a typo in the method name in a syntax diagram? Someone with the available cycles should jump on Mark's offer of a fast-track to Committer status, and pick this up. -Chip- On 2/16/2013 12:14 Staffan Tylen said: > Quite some time ago I made some comments on the use of place-holding > commas in parameter lists and the way they are documented. I didn't > receive any reaction on this at the time (maybe something went wrong > with my posting) and I forgot about it until now when I looked at the > following description of the createStaticText method: > > >>--createStaticText(-+------+--x-,--y-+------+-+------+-+----------+-+--------+-)->< > +-id-,-+ +-,-cx-+ +-,-cy-+ +-,-style--+ > +-,-text-+ > > This in my opinion is a good example that illustrates the confusion > that can be created when reading it. > > <snip> > > Based on this I am of the opinion that the parameter list is better > documented like this: > > >>--createStaticText(-+----+-,-x-,-y-,-+----+-,-+----+-,-+-------+-,-+------+-)->< > +-id-+ +-cx-+ +-cy-+ +-style-+ > +-text-+ > > Here there are no optional commas, which is the norm when writing a > parameter list. There are exceptions to this, like the ListView 'add' > method, which allows for a variable number of commas, but such > exceptions are few and the variable comma seems to be documented > "correctly". > > What's the general view on this? > > Staffan > > > > > > ------------------------------------------------------------------------------ > The Go Parallel Website, sponsored by Intel - in partnership with Geeknet, > is your hub for all things parallel software development, from weekly thought > leadership blogs to news, videos, case studies, tutorials, tech docs, > whitepapers, evaluation guides, and opinion stories. Check out the most > recent posts - join the conversation now. http://goparallel.sourceforge.net/ > > > > _______________________________________________ > Oorexx-users mailing list > Oor...@li... > https://lists.sourceforge.net/lists/listinfo/oorexx-users > |
From: Staffan T. <sta...@gm...> - 2013-02-17 09:16:58
|
> Someone with the available cycles should jump on Mark's offer of a > fast-track to Committer status, and pick this up. > > I don't know what this implies really but having started the avalange I feel I need to do something to stop it. I've therefore downloaded the whole ooRexx documentation trunk and started to attack the ooDialog material. I hope to have that finished within a day or two. What to do with it afterwards I'm not sure about, as I've never uploaded anything back. Remember, I'm just a user ;) I suspect somebody will fill me in on those details. So if this means that I'm now a Committer, so be it, at least for this particular task. Staffan |
From: Mark M. <mie...@gm...> - 2013-02-17 20:59:45
|
Hmm, for some reason some of these posts are not showing up in my mail box until hours later. On Sun, Feb 17, 2013 at 1:16 AM, Staffan Tylen <sta...@gm...>wrote: > > Someone with the available cycles should jump on Mark's offer of a >> fast-track to Committer status, and pick this up. >> >> > I don't know what this implies really but having started the avalange I > feel I need to do something to stop it. I've therefore downloaded the whole > ooRexx documentation trunk and started to attack the ooDialog material. I > hope to have that finished within a day or two. What to do with it > afterwards I'm not sure about, as I've never uploaded anything back. > Staffan, You will not be able to upload anything until you are made a committer. What you need to do is prepare a patch, or patches, and open up a Patches tracker item. https://sourceforge.net/p/oorexx/patches/ I think the best approach would probably be to get all your changes done in your local working copy, and then just prepare a patch for one .xml file. Open up a ticket and attach the patch to it, and I'll check that it applies okay. Maybe open up several tickets for several files. Then if things go well, you could either prepare a single patch for everything else, or finish up by preparing a patch for each remaining file. I'm assuming you have used svn to check out a working copy. TortoiseSVN seems to be very good at creating a patch file. But, if you are using a command line svn you can use that to create the patch. To use a command line svn, follow this procedure. The procedure would be the same using TortoiseSVN, but you would need to use the menu commands obviously. Assuming your working copy as some changes from what is in the repository: 1.) Be sure you do an update first to sync the working copy with the repository. Failing to do this will lead to problems. Notice that I am doing this from this repository URL svn.code.sf.net/p/oorexx/code-0/docs/trunk which I have checked out into a local directory name docs, bypassing the whole 'trunk' thing in my local copy: C:\work.ooRexx\wc\docs>svn update Updating '.': At revision 9002. 2.) Use the status command to see what files have differences from the repository: C:\work.ooRexx\wc\docs>svn status -q M oodialog\en-US\userInput.xml 3.) You will have a number of files listed most likely. Create a patch for just one of them to get started. You use the diff command to create the patch and redirect the output to a file. You can name the file anything you like, but it is common to use an extension of 'patch' and some file name that indicates what the patch is for. C:\work.ooRexx\wc\docs>svn diff oodialog\en-US\userInput.xml > userInput.patch 4.) Open the patch file in an editor just to see what it looks like. The patch file I just did starts out like this: Index: oodialog/en-US/userInput.xml =================================================================== --- oodialog/en-US/userInput.xml (revision 9002) +++ oodialog/en-US/userInput.xml (working copy) @@ -2737,9 +2737,9 @@ <indexterm><primary>PropertyDialog class</primary><secondary>absoluteWidth</secondary></indexterm> <programlisting> <![CDATA[ ->>--absoluteWidth----------------------------------------------------->< +>>--absoluteWidth-------------------------------->< ->>--absoluteWidth = pixels------------------------------------------->< +>>--absoluteWidth = trueOrFalse------------------>< ]]> </programlisting> @@ -2792,22 +2792,32 @@ <indexterm><primary>PropertyDialog class</primary><secondary>canCancel</secondary></indexterm> <programlisting> <![CDATA[ ->>--canCancel----------------------------------------------------->< +>>--canCancel------------------------------------>< ->>--canCancel = varName------------------------------------------->< +>>--canCancel = trueOrFalse---------------------->< ]]> </programlisting> and goes on some. 5.) Open up a Patches ticket on SourceForge, briefly describe what the patch is for, and attach the patch file to the ticket As I said, it is probably best to get all your changes done, but just open a first patches ticket for one file. If there is some problem with that first one we can work out what is wrong. Once that is straightened out, you can do all the rest. If it looks like everything is going well and you will be able to supply the patches for all of the ooDialog doc, I'll switch any new stuff I'm adding to the new format. -- Mark Miesfeld |
From: Chip D. <ch...@av...> - 2013-02-17 15:35:59
|
You have _my_ gratitude and encouragement, Staffan! Nearly all Committers start out as "just a user". When you are able to make a valuable contribution, and learn to use the open source management tools safely, you'll likely be invited to join their vaunted ranks. Don't worry, you know how patient Mark is with questions from "just users". He (and the rest of the ooRexx team) will be delighted to help you. -Chip- On 2/17/2013 04:16 Staffan Tylen said: > > Someone with the available cycles should jump on Mark's offer of a > fast-track to Committer status, and pick this up. > > > I don't know what this implies really but having started the avalange > I feel I need to do something to stop it. I've therefore downloaded > the whole ooRexx documentation trunk and started to attack the > ooDialog material. I hope to have that finished within a day or two. > What to do with it afterwards I'm not sure about, as I've never > uploaded anything back. Remember, I'm just a user ;) I suspect > somebody will fill me in on those details. So if this means that I'm > now a Committer, so be it, at least for this particular task. |
From: Staffan T. <sta...@gm...> - 2013-02-17 15:46:40
|
:) Thanks. Don't worry, you know how patient Mark is with questions from "just > users". He (and the rest of the ooRexx team) will be delighted to > help you. > > |