I also find the train-tracks hard to use. If I have to write/amend them I have to go back and consult the meta documentation.
I like the javascript style tables. I don't know what DocBook can do, but I know for some people visual cues are very helpful, so we might consider a small icon to distinguish between a mandatory or an optional argument, and to pick out a default value. One thing that I always found very easy to read and understand was where only part of the Argument name was required to capitalise that part so I hope we retain that. Jon 2008/8/24 David Ashley <[EMAIL PROTECTED]> > :-) > > I always think about the presentation first and then the information. I > find it fits my development methodology better, but that is just me. If I > can't find the information then the information is useless. The presentation > is thus the key for me. > > Let see if I can put together an example of what we might be able to > accomplish with DocBook. > > > Thanks, > W. David Ashley > IBM Systems and Technology Group Lab Services > Open Object Rexx Team > Mobile Phone: 512-289-7506 > > > [image: Inactive hide details for "Rick McGuire" ---08/24/2008 03:10:03 > PM---At this point, I wasn't even thinking about the "decoratio] > "Rick McGuire" ---08/24/2008 03:10:03 PM---At this point, I wasn't even > thinking about the "decoration" elements, > > > *"Rick McGuire" <[EMAIL PROTECTED]>* > Sent by: [EMAIL PROTECTED] > > 08/24/2008 03:09 PM > Please respond to > Open Object Rexx Developer Mailing List < > [email protected]> > > > To > > "Open Object Rexx Developer Mailing List" < > [email protected]> > cc > > > Subject > > Re: [Oorexx-devel] Railroad tracks in docs > > At this point, I wasn't even thinking about the "decoration" elements, > but rather was focusing on how the information was getting presented > (arguments fully listed, then each argument fully described below). > After that, we can use whatever formatting makes sense for our docs. > > Rick > > On Sun, Aug 24, 2008 at 3:22 PM, David Ashley <[EMAIL PROTECTED]> wrote: > > I like the Javascript method of documentation. But the background color > will > > be a problem in DocBook. The style sheet will determine that kind of > > presentation, not the DocBook tags. Other than that, I can live with the > > JavaScript presentation. > > > > Thanks, > > W. David Ashley > > IBM Systems and Technology Group Lab Services > > Open Object Rexx Team > > Mobile Phone: 512-289-7506 > > > > > > "Mark Miesfeld" ---08/24/2008 01:12:32 PM---On Sun, Aug 24, 2008 at 10:45 > > AM, Rick McGuire <[EMAIL PROTECTED]> wrote: > > > > "Mark Miesfeld" <[EMAIL PROTECTED]> > > Sent by: [EMAIL PROTECTED] > > > > 08/24/2008 01:01 PM > > > > Please respond to > > Open Object Rexx Developer Mailing List < > [email protected]> > > > > To > > "Open Object Rexx Developer Mailing List" > > <[email protected]> > > cc > > > > Subject > > Re: [Oorexx-devel] Railroad tracks in docs > > On Sun, Aug 24, 2008 at 10:45 AM, Rick McGuire <[EMAIL PROTECTED]> > > wrote: > >> I did a little nosing around to see how some other languages that I > >> know allow optional arguments ... while > >> javascript does not mark arguments as optional, but uses a javadoc > >> style of where each of the arguments is in a list and the description > >> indicates whether the argument is optional or required > >> (http://www.w3schools.com/jsref/jsref_substr.asp). > > > > I like this javascript look. Marking in the table whether each arg is > > required or optional is easy to follow. It is very black and white, > > for each arg make the first word Required or Optional. > > > > I'm mostly coming from my experience with the ooDialog docs where > > there is a lot of inconsistency between the doc for one method and the > > next. For myself, I've found constructing a table in the SGML files > > to be a lot easier than constructing the variablelist. The javascript > > args look like they are presented in a table. > > > > I think the syntax line itself is easier to read when it does not have > > the square brackets in it. Especially in our doc where so many args > > are optional. > > > > -- > > Mark Miesfeld > > > > ------------------------------------------------------------------------- > > This SF.Net email is sponsored by the Moblin Your Move Developer's > challenge > > Build the coolest Linux based applications with Moblin SDK & win great > > prizes > > Grand prize is a trip for two to an Open Source event anywhere in the > world > > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > > _______________________________________________ > > Oorexx-devel mailing list > > [email protected] > > https://lists.sourceforge.net/lists/listinfo/oorexx-devel > > > > > > ------------------------------------------------------------------------- > > This SF.Net email is sponsored by the Moblin Your Move Developer's > challenge > > Build the coolest Linux based applications with Moblin SDK & win great > > prizes > > Grand prize is a trip for two to an Open Source event anywhere in the > world > > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > > _______________________________________________ > > Oorexx-devel mailing list > > [email protected] > > https://lists.sourceforge.net/lists/listinfo/oorexx-devel > > > > > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's > challenge > Build the coolest Linux based applications with Moblin SDK & win great > prizes > Grand prize is a trip for two to an Open Source event anywhere in the world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > Oorexx-devel mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/oorexx-devel > > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's > challenge > Build the coolest Linux based applications with Moblin SDK & win great > prizes > Grand prize is a trip for two to an Open Source event anywhere in the world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > Oorexx-devel mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/oorexx-devel > >
<<ecblank.gif>>
<<graycol.gif>>
------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________ Oorexx-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/oorexx-devel
