TicketQuery documentation improvement proposal

[AdrianFritz]

I believe this can improve a little bit TicketQuery documentation (rendered from source code found at ​http://trac.edgewall.org/browser/trunk/trac/ticket/query.py?rev=10750#L1178)

START

---

TicketQuery macro lets you display lists of tickets matching certain criteria anywhere you can use WikiFormatting.

This macro accepts a comma-separated list of keyed parameters, in the form "key=value", as follws:

[[TicketQuery([key=value][,key=value][,key=value]...)]]

If the key is the name of a ticket field, the value must use the syntax of a filter specifier as defined in TracQuery#QueryLanguage.

• Note that this is not the same as the simplified URL syntax used for query: links starting with a ? character.
• Commas (,) can be included in field values by escaping them with a backslash (\).

The date keys created and modified can also constrain the criteria. Again, see TracQuery#QueryLanguage.

In addition to filters, several other named parameters can be used to control how the results are presented. All of them are optional.

Key	Description & Details	Default
col	Pipe-separated list of columns and its order to show (requires format=table).	col=id|summary |owner|type| status|priority |milestone
desc	Reverse (true) the natural display order of the tickets.	desc=false
format1	Sets how the list of tickets is displayed: * list — ticket id next to the summary, each ticket on a separate line. * compact — comma-separated list of ticket ids. * count — the count of matching tickets * table — similar to the custom query view (but without the controls) * progress — a view similar to the milestone progress bars.	format=list
group	Sets the ticket field for grouping tickets.	None
groupdesc	Reverse (true) the natural display order of the groups.	groupdesc=false
max	Sets the limit number of tickets to display (max=0 means no maximum).	max=0
order	Sets the ticket field for ordering tickets.	order=id
rows	Pipe-separated list of ticket fields to be viewed as a row, e.g. rows=description|summary (requires format=table)	None
verbose	Get the description for the listed tickets (true). Use with format=table only. Deprecated (< 0.12) in favor of the rows key.	verbose=false

Note ¹

For compatibility with Trac 0.10, if there's a last positional parameter given to the macro, it will be used to specify the format.

Note

Also, for compatibility with Trac 0.10, using "&" as a field separator still works (except for order) but is deprecated.

[AdrianFritz]

Other improvements should be expected here, like:

1. better identify since which Trac version every key is available or deprecated
2. check if is it expected to be shown a non specified row (formatted as "Reported by nononon, x years ago.") when only used rows=description
   • I think this probably is a bug (maybe to be filed under a new ticket after confirmed)
3. Help needed to understand this sentence: "Groups of field constraints to be OR-ed together can be separated by a litteral or argument."
4. col key default settings might require some more adjusts for proper rendering

[Remy Blank]

Feel free to edit the wiki here with your changes. The pages bundled with Trac are synchronized from this wiki. Just make sure you edit the right version for the features you document (i.e. if it's for 0.13, you should edit 0.13/TicketQuery (or create the page first, using a copy of the content of TicketQuery).

[AdrianFritz]

Thanks for guidelines Remy. First round at wiki:0.13/TicketQuery@1. Probably you will have to perform manually synchronization because original wiki page (TicketQuery) has part of its contents rendered by [[MacroList(TicketQuery)]] macro.

[Remy Blank]

I wasn't all too clear in comment:2, sorry about that. What I meant is that for pages belonging to TracGuide, we create the "versioned" page with the latest version from the "live" guide, and only then do we add modifications. This allows keeping track of the differences between versions and sometimes even to forward-merge changes.

I have done that now in 0.13/TicketQuery, by removing the page, re-creating it with a copy of TicketQuery and re-applying your changes.

[AdrianFritz]

Nice, learnt one more procedure today :-).

[Remy Blank]

Preparing for 1.0.

[Christian Boos]

Looks like this is "done", no?

[AdrianFritz]

Yes, it´s done.

[anonymous]

Were these improvements lost somehow?

[Christian Boos]

Looks like that 0.13 page hasn't yet been moved to the default TicketQuery page, as it's not part of the set of default wiki pages.

I reopen so that we can take the time to review the changes again.

[Peter Suter]

#9549 was closed as a duplicate.

comment:2:ticket:9549 hinted that the docstring​ is also missing the col parameter.

[Peter Suter]

Actually the only part I really miss is the added col parameter. (Using a complex table doesn't work so well in the docstring.)

I therefore propose:

trac/ticket/query.py

@@ -1261 +1261 @@
     The `rows` parameter can be used to specify which field(s) should
     be viewed as a row, e.g. `rows=description|summary`
 
+    The `col` parameter can be used to specify which fields should
+    be viewed as columns. For '''table''' format only.
+
     For compatibility with Trac 0.10, if there's a last positional parameter
     given to the macro, it will be used to specify the `format`.
     Also, using "&" as a field separator still works (except for `order`)

(The default​ seems too complex to describe here.)

[Peter Suter]

Committed in [12613] and merged in [12614].