Item2215: Alphabetically sort options
Priority: Normal
Current State: No Action Required
Released In:
Target Release: n/a
Applies To: Engine
Component: Documentation
Branches:
Several Var* doc topics present their options in an apparently random order, which makes it really had to find things at-a-glance (the one that irritates most is
VarSEARCH)
At a minimum options should be presented in alphabetical order. Best might be to group them by function - e.g. keep all the formatting options together, all the sorting options, all the search scope options etc.
--
CrawfordCurrie - 07 Oct 2009
Have you had a look at
http://trunk.foswiki.org/System/VarTABLE (trunk) ? That must make it even harder on you.
When writing plugin documentation, I usually try to put the most important (required) options at the top, and then go down in importance, using some groupings. Having an alphabetical order looses the hierarchy, and makes it harder to learn about the options.
You could be helped with:
- filtering out options, f.i. by typing the option name you are looking for
- a mini TOC that lets you jump to a row
- a sortable table
--
ArthurClemens - 07 Oct 2009
I think there are two cases (like there are two kinds of people, those that devide the world in two kinds of people, and those that don't).
- Macros with 1-5 parameters where it does not matter if the parameters are alphabetical.
- Macros with many many parameters like TABLE where you it is difficult to find your options
It is very few that are with many parameters.
Alphabetical order suits the power user that knows what the parameter is called and just needs the syntax. Most of us devs are in this group.
Order by function suits the person who is learning what a powerful macro can do. As Arthur noted.
I tend to agree with Arthur in this case. But even as it is today the beginner cannot easily overview or get the intelligence in the order.
I doubt there is a one solution fits them all. But in case of the TABLE I would group the parameters.
- Sorting
- Colours
- Borders and Spacing
- Alignment and widths
- Header and Footer
- ID, Summary, Caption
And present them in a table where it is more clear there are these groups.
Within each group I would go alphabetical.
Putting it all alphabetical is bad. You end up with this order in the TABLE docu
- caption
- cellborder
- cellpadding
- cellspacing
- columnwidths
- dataalign
- databg
- databgsorted
- datacolor
- datavalign
- disableallsort
- footerrows
- headeralign
- headerbg
- headerbgsorted
- headercolor
- headerrows
- headervalign
- id
- initdirection
- initsort
- sort
- summary
- tableborder
- tableframe
- tablerules
- tablewidth
- valign
That is really bad. Like
disableallsort
being far away from the other sort options. Or
valign
and
dataalign
being far apart. Today they are actually grouped well. It is just not very obvious that they are grouped.
So alphabetical as a rule. Please no!. Better presentation of the grouping and alphabetical within a group, sure.
For macros with 3 parameters, it does not really matter as long as the first one is the nameless default parameter.
--
KennethLavrsen - 07 Oct 2009
All this talk of table plugin made me realise; I can just click on the column header to sort. All we need now is a decent client-side table sorter
Alphabetical doesn't matter if there some other way of rapidly finding what you are looking for. For the big macros, I still think it's better to
explicitly group parameters by function. Here's how I'd suggest doing
SEARCH:
- Search Terms - what to search for
-
"text"
-
search
-
type
-
casesensitive
- Search Context - where to search
-
web
-
topic
-
excludetopic
-
scope="topic"
-
recurse
- Number and ordering of results
-
order
-
reverse
-
limit
-
date
-
noempty
-
multiple
- Formatting around the results - headers and footers
-
nonoise
-
nosummary
-
nosearch
-
noheader
-
nototal
-
zeroresults
-
header
- Formatting each result
-
expandvariables
-
nofinalnewline
-
separator
-
newline
(I dropped
bookview
completely).
Note that while compiling that I noticed several errors in the
SEARCH doc
--
CrawfordCurrie - 08 Oct 2009
Table sorter: wait for the jquery integration...
--
ArthurClemens - 08 Oct 2009
JQTablePlugin provides client-side sorting that pretty much blows this away. It's not a standard plugin, but I guess with the other observations about the sort order we can close this as "No Action"
--
CrawfordCurrie - 16 Mar 2010