tag 351746 patch
thanks
[ CCed some of the people involved in the bug report. ]
Hi!
I was playing again with usertags and usercategories, and could not
remember all the details from last time, so ended up writting what
I already had from the dpkg usertags, and from reverse engineering
the debbugs code. :)
On Wed, 2009-08-05 at 09:33:22 -0700, Don Armstrong wrote:
> On Wed, 05 Aug 2009, Carl Worth wrote:
> > On Fri, 15 May 2009 18:01:37 +0200 Martin Michlmayr wrote:
> > > I cannot believe this still hasn't been done! Don, how about this:
I started off with Martin's patch, fixed few issues and added
documentation and examples for usercategories.
> > Seriously though, the patch above looks good to me. Is there
> > anything else I can do to help this patch get applied?
>
> usertag is a request@ feature, not a control@ feature, so it's kind of
> documenting the wrong thing.
>
> I personally haven't applied it or fixed it because I missed the mail
> with the patch from Martin and hadn't seen it when looking back
> through (and it wasn't tagged patch either).
>
> That said, if you send this bug a patch which:
>
> 1) creates a new wml webpage which documents usertags and (hopefully!)
> starts on documenting user-categories
Instead of this I just added it to server-request.wml and ...
> 2) adds links from server-request and server-control to the page
... linked it from server-control.wml. If you still want it in a
separate page please say so.
> tag the bug patch, and remind me if I forget to apply it within a
> week, I'll see that it gets applied and the bug gets closed.
Few things about the new patch:
* I'm not entirely convinced of the nomenclature I've used to describe
the user categories. I've used selections, because they are used to
select what bugs to display, but maybe classification can be used
instead? The variable names used in debbugs do not seem to help
either, as they are a bit confusing.
* The [] used to denote optional arguments can get easily confused with
the ones that are part of the syntax. The examples help here a bit.
* There's no description of what are the allowed selection criteria,
but I think that can wait for later if at all.
* It builds and shows correctly on my web browser.
* The text needs a review by a native speaker, I'm not sure if it's
easily understandable?
thanks,
guillem
Index: english/Bugs/server-control.wml
===================================================================
RCS file: /cvs/webwml/webwml/english/Bugs/server-control.wml,v
retrieving revision 1.89
diff -u -r1.89 server-control.wml
--- english/Bugs/server-control.wml 17 Mar 2010 04:38:21 -0000 1.89
+++ english/Bugs/server-control.wml 28 Jan 2011 06:24:25 -0000
@@ -90,6 +90,9 @@
<dt><a href="#owner">owner</a> | <a href="#noowner">noowner</a></dt>
<dt><a href="#block">block</a> | <a href="#unblock">unblock</a></dt>
<dt><a href="#archive">archive</a> | <a href="#unarchive">unarchive</a></dt>
+ <dt><a href="server-request#user">user</a> |
+ <a href="server-request#usertag">usertag</a> |
+ <a href="server-request#usercategory">usercategory</a></dt>
</dl>
</td>
</tr>
Index: english/Bugs/server-request.wml
===================================================================
RCS file: /cvs/webwml/webwml/english/Bugs/server-request.wml,v
retrieving revision 1.25
diff -u -r1.25 server-request.wml
--- english/Bugs/server-request.wml 16 Aug 2007 05:29:27 -0000 1.25
+++ english/Bugs/server-request.wml 28 Jan 2011 06:24:25 -0000
@@ -121,6 +121,119 @@
Requests that the mailservers' reference card be sent in plain ASCII.
</dd>
+<dt><a name="user"><code>user</code> <var>address</var></a></dt>
+<dd>
+Sets <var>address</var> to be the <q>user</q> of all <code>usertag</code>
+commands that follow.
+</dd>
+
+<dt><a name="usertag"><code>usertag</code> <var>bugnumber</var>
+ [ <code>+</code> | <code>-</code> | <code>=</code> ] <var>tag</var>
+ [ <var>tag</var> ... ]</a></dt>
+<dd>
+Allows to define tags on a per-user basis. The <code>usertag</code>
+command works just like the regular <code>tag</code> command, except
+that you get to make up whatever tags you like. By default, the address
+in the <code>From:</code> or <code>Reply-To:</code> header of your mail
+will be used to set the user of the <code>usertag</code>.
+</dd>
+
+</dd>
+
+<dt><a name="usercategory"><code>usercategory</code>
+ <var>category-name</var> [ <code>[hidden]</code> ]</a></dt>
+<dd>
+<p>
+Adds, updates or removes a <code>usercategory</code>. By default the user
+category is visible, if the optional argument <code>[hidden]</code>
+is specified then it will not be visible, but still be available to be
+referenced from other user category definitions.
+</p>
+
+<p>
+This command is somewhat special, as when adding or updating a user
+category it requires a body following immediately after the command. If
+the body is empty the user category will get removed instead. The body
+is composed of lines starting with any number of spaces. Each category
+should start with a line with <code>*</code>, and optionally it can be
+followed by several selection lines starting with <code>+</code>. The
+complete format is as follows:
+</p>
+
+<div>
+* <var>category-name-1</var><br />
+* <var>Category Title 2</var>
+ [ <code>[</code><var>selection-prefix</var><code>]</code> ]<br />
+ + <var>Selection Title 1</var> <code>[</code>
+ [ <var>order</var><code>:</code> ]
+ <var>selection-1</var> <code>]</code><br />
+ + <var>Selection Title 2</var> <code>[</code>
+ [ <var>order</var><code>:</code> ]
+ <var>selection-2</var> <code>]</code><br />
+ + <var>Default Selection Title</var> <code>[</code>
+ [ <var>order</var>: ] <code>]</code><br />
+* <var>category-name-3</var><br />
+</div>
+
+<p>
+The <var>category-names</var> appearing in the command and in the body
+are used to make references between them, to avoid unneecessary inlining.
+The <var>Category Titles</var> are used in the package report summary.
+</p>
+
+<p>
+The optional <var>selection-prefix</var> is prefixed to every
+<var>selection</var> on each entry in the category section. The first
+<var>selection</var> which matches gets the bug shown under it. The
+optional <var>order</var> parameter specifies the position when showing
+the selected entries, this is useful when using a match that selects a
+superset of the previous ones but that needs to be shown before them.
+</p>
+
+<p>
+The <var>category-names</var> <code>normal</code> has the special meaning
+of being the default view, so by replacing it with a different user category
+for the <var>pkgname</var>@packages.debian.org user one can change the
+default classification for a package.
+</p>
+
+<p>
+Example usage:
+</p>
+
+<pre>
+ usercategory dpkg-program [hidden]
+ * Program
+ + dpkg-deb [tag=dpkg-deb]
+ + dpkg-query [tag=dpkg-query]
+ + dselect [package=dselect]
+
+ usercategory new-status [hidden]
+ * Status [pending=]
+ + Outstanding with Patch Available [0:pending+tag=patch]
+ + Outstanding and Confirmed [1:pending+tag=confirmed]
+ + Outstanding and More Information Needed [pending+tag=moreinfo]
+ + Outstanding and Forwarded [pending+tag=forwarded]
+ + Outstanding but Will Not Fix [pending+tag=wontfix]
+ + Outstanding and Unclassified [2:pending]
+ + From other Branch [absent]
+ + Pending Upload [pending-fixed]
+ + Fixed in NMU [fixed]
+ + Resolved [done]
+ + Unknown Pending Status []
+
+ \# Change default view
+ usercategory normal
+ * new-status
+ * severity
+
+ usercategory old-normal
+ * status
+ * severity
+ * classification
+</pre>
+</dd>
+
<dt><code>help</code></dt>
<dd>
Requests that this help document be sent by email in plain ASCII.
