[PATCH v3 1/2] emacs: User-defined sections in notmuch-hello

[Daniel Schoepe]

On Wed, 06 Jul 2011 13:34:13 +0200, Michal Sojka <sojkam1 at fel.cvut.cz> wrote:
> > -(defcustom notmuch-hello-tag-list-make-query nil
> > -  "Function or string to generate queries for the all tags list.
> 
> I'm not sure it is a good thing to remove customizations that are
> included in a released version. Some users may configure it and their
> configuration disappear when they install a new version. Is there a way
> to migrate this settings to a new, section-based one?

Agreed, I think I only removed it because at the time I first
implemented user-defined sections, my patch, which introduced
notmuch-hello-tag-list-make-query, hadn't been applied yet.

> This is IMHO still hard to understand only from looking at the
> customization widget. Ideally, I'd like to see somewhere a paragraph
> like this: "This displays a list of all tags, optionally hiding some of
> them. It is also possible to filter the list of messages matching each
> tag by an additional filter query. Similarly, the count of messages
> displayed next to the buttons can be generated by applying another
> filter to the tag query."
> 
> Actually, when reading the above paragraph, it still seems a way too
> complex. What about the following: I do not think it has sense to list
> custom tags with zero counts - I think everybody would use
> :hide-empty-tags all the time. Then, the result of listing all tags with
> 'notmuch search-tags', filtering them with 'filter' and throwing away
> empty tags, would be the same as running 'notmuch search-tags filter'
> and then finding the counts by 'notmuch count tag:TAG and filter'. One
> of the advantage of this approach is that it would probably be faster to
> generate the section, because you won't query the counts of all tags if
> your filter matches only a few of them.
> 
> Additionally, as I didn't read carefully your previous discussions about
> the additional filter for counts, I do not see much use for it. If you
> only want to see which tags has unread messages, you can simply add a
> new section with (:make-query "tag:unread") and you would get what you
> want. You can also disable all-tags sections.
> 
> So my proposal is to forget about different queries for filters and
> counts and having here only the following options: filter, hide-tags and
> hide-if-empty.
> 
> Then, the documentation would be simple: "This section displays buttons
> for all tags of messages matching a FILTER. Optionally, some of these
> tags may be hidden."
> 
> Is there a use case, which is not covered by this?

I'm not sure, I can imagine someone wanting to have an overview of all
his tags, whether there are, e.g., unread messages or not. If we decide
to keep this functionality, it should be inverted though, i.e. one has
to explicitly specify :show-empty-searches to get them.

About the counts: I introduced this because Austin Clements says he
finds it useful in his comment here:

id:"BANLkTi=729DWai4q57iBSfz1wDhBXsmndQ at mail.gmail.com"

Also, I think/hope that we can just improve the documentation
sufficiently without sacrificing flexibility.

> 
> > +  :type
> > +  (let ((opts
> > +	 '((:title (string :tag "Title for this section"))
> > +	   (:make-query (string :tag "Filter for each tag"))
> > +	   (:make-count (string :tag "Different query to generate counts"))
> > +	   (:hide-tags (repeat :tag "Tags that will be hidden" string))
> 
> I can imagine, that :hide-tags could also be a (list of) regexp(es).
> 
> > +	   (:initially-hidden (boolean :tag "Hide this on startup?"))
> 
> This is IMHO not needed here, as you always has to enable this section
> manually.

A user might still want to have the section collapsed when starting the
notmuch UI and only have it shown when he needs it. (I use that for a
section that displays unread counts for each tag).

> 
> > +		 (:hide-empty-tags
> 
> Rename to :hide-empty-queries.
> 
> > +		  (boolean :tag "Hide tags with no matching messages"))
> 
> Hide queries...

Right, thanks.

> 
> > +		 (:hide-if-empty (boolean :tag "Hide if empty"))))))
> > +
> > +(defcustom notmuch-hello-sections
> > +  (list #'notmuch-hello-insert-header
> > +	#'notmuch-hello-insert-saved-searches
> > +	#'notmuch-hello-insert-search
> > +	#'notmuch-hello-insert-recent-searches
> > +	#'notmuch-hello-insert-alltags
> > +	#'notmuch-hello-insert-footer)
> > +  "Sections for notmuch-hello.
> > +
> > +Each entry of this list should be a function of no arguments that
> > +should return if notmuch-hello-target is produced as part of its
> 
> What is notmuch-hello-target? I guess I know what it is from reading the
> code, but if I didn't read the code, this mentioning it here would be of
> little value for me. Perhaps make the notmuch-hello-target clickable and
> document it below.

Yes, you're right, this needs more documentation.

> 
> > +output and nil otherwise. For convenience an element can also be
> > +a list of the form (FUNC ARG1 ARG2 .. ARGN) in which case FUNC
> > +will be applied to the rest of the list.
> > +
> > +The functions will be run to construct the content of the
> > +notmuch-hello buffer in the order they appear in this list."
> > +  :group 'notmuch
> > +  :type 
> > +  '(repeat
> > +    (choice (function-item notmuch-hello-insert-header)
> > +	    (function-item notmuch-hello-insert-saved-searches)
> > +	    (function-item notmuch-hello-insert-search)
> > +	    (function-item notmuch-hello-insert-recent-searches)
> > +	    (function-item notmuch-hello-insert-alltags)
> > +	    (function-item notmuch-hello-insert-footer)
> > +	    (function-item notmuch-hello-insert-inbox)
> > +	    notmuch-hello-tags-section
> > +	    notmuch-hello-query-section
> > +	    (function :tag "Custom function"))))
> > +
> > +;; only defined to avoid compilation warnings about free variables
> > +(defvar notmuch-hello-target nil)
> 
> Add the documentation as discussed above. Additionally, it seems that
> having only the label in this variable is not enough, since the same
> label can appear in multiple sections. Perhaps, we need both the title
> of the section and the label here.

What do you mean by label? "Custom function"? If yes, that element will
have the actual function name in the input element next to it anyway.

> > +  ;;(setq buffer-read-only t)
> 
> Don't we want to get rid of this line?

I guess so, it was there before my patch though.

> 
> > +  )
> > +
> > +(defun notmuch-hello-generate-tag-alist (&optional hide-tags filter-query filter-count)
> >    "Return an alist from tags to queries to display in the all-tags section."
> >    (notmuch-remove-if-not
> > -   #'cdr
> > +   #'identity
> >     (mapcar (lambda (tag)
> > -	     (cons tag
> > -		   (cond
> > -		    ((functionp notmuch-hello-tag-list-make-query)
> > -		     (concat "tag:" tag " and ("
> > -			     (funcall notmuch-hello-tag-list-make-query tag) ")"))
> > -		    ((stringp notmuch-hello-tag-list-make-query)
> > -		     (concat "tag:" tag " and ("
> > -			     notmuch-hello-tag-list-make-query ")"))
> > -		    (t (concat "tag:" tag)))))
> > +	     (let ((query (notmuch-hello-filtered-query (concat "tag:" tag)
> > +							filter-query)))
> > +	       (when query
> > +		 (if filter-count
> > +		     (list tag (notmuch-hello-filtered-query tag filter-query)
> > +			   (notmuch-hello-filtered-query (concat "tag:" tag)
> > +							 filter-count))
> > +		   (cons tag (notmuch-hello-filtered-query
> > +			      (concat "tag:" tag) filter-query))))))
> >  	   (notmuch-remove-if-not
> >  	    (lambda (tag)
> > -	      (not (member tag notmuch-hello-hide-tags)))
> > +	      (not (member tag hide-tags)))
> >  	    (process-lines notmuch-command "search-tags")))))
> >  
> > +(defun notmuch-hello-insert-header ()
> > +  "Insert the default notmuch-hello header."
> > +  (when notmuch-show-logo
> > +    (let ((image notmuch-hello-logo))
> > +      ;; The notmuch logo uses transparency. That can display poorly
> > +      ;; when inserting the image into an emacs buffer (black logo on
> > +      ;; a black background), so force the background colour of the
> > +      ;; image. We use a face to represent the colour so that
> > +      ;; `defface' can be used to declare the different possible
> > +      ;; colours, which depend on whether the frame has a light or
> > +      ;; dark background.
> > +      (setq image (cons 'image
> > +			(append (cdr image)
> > +				(list :background (face-background 'notmuch-hello-logo-background)))))
> > +      (insert-image image))
> > +    (widget-insert "  "))
> > +
> > +  (widget-insert "Welcome to ")
> > +  ;; Hack the display of the links used.
> > +  (let ((widget-link-prefix "")
> > +	(widget-link-suffix ""))
> > +    (widget-create 'link
> > +		   :notify (lambda (&rest ignore)
> > +			     (browse-url notmuch-hello-url))
> > +		   :help-echo "Visit the notmuch website."
> > +		   "notmuch")
> > +    (widget-insert ". ")
> > +    (widget-insert "You have ")
> > +    (widget-create 'link
> > +		   :notify (lambda (&rest ignore)
> > +			     (notmuch-hello-update))
> > +		   :help-echo "Refresh"
> > +		   (notmuch-hello-nice-number
> > +		    (string-to-number (car (process-lines notmuch-command "count")))))
> > +    (widget-insert " messages.")))
> 
> Perhaps you want to end this (and also all other) section with an empty
> line so that the order of sections doesn't matter. I use sections in
> this order: header, inbox, saved-searches and there is no space between
> header and inbox and two spaces between inbox and saved-searches.

My thinking was to have no section end with a newline and insert a
newline between each section when building the notmuch-hello buffer, to
prevent forgotten trailing newlines when defining a new section.

> I might be useful to include here a link to the customization of this
> page. Maybe, it would be useful to have notmuch-hello subgroup in
> customization interface and link to this group. But creation of the
> subgroup should be definitely in a separate patch.

Yes definitely. Pieter Praet recently sent a patch reorganizing the
customization options into subgroups, so I'll change it once that patch
has been applied.

Cheers,
Daniel
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 835 bytes
Desc: not available
URL: <http://notmuchmail.org/pipermail/notmuch/attachments/20110706/5d072d39/attachment.pgp>