Item2215: Alphabetically sort options

pencil
Priority: Normal
Current State: No Action Required
Released In:
Target Release: n/a
Applies To: Engine
Component: Documentation
Branches:
Reported By: CrawfordCurrie
Waiting For:
Last Change By: CrawfordCurrie
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 wink

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 frown, sad smile

-- 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

ItemTemplate edit

Summary Alphabetically sort options
ReportedBy CrawfordCurrie
Codebase 1.0.7, 1.0.6, 1.0.5, 1.0.5 beta1, 1.0.4, 1.0.3, 1.0.2, 1.0.1, 1.0.0, 1.0.0 beta3, 1.0.0 beta2, 1.0.0 beta1, trunk
SVN Range SVN 5221: Foswiki-1.1.0-dev, Mon, 28 Sep 2009, build 5161
AppliesTo Engine
Component Documentation
Priority Normal
CurrentState No Action Required
WaitingFor
Checkins
TargetRelease n/a
ReleasedIn
Topic revision: r7 - 16 Mar 2010, CrawfordCurrie
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy