Comments on VFolder spec

[Havoc Pennington]

Hi,

I promised to post some notes on the actual vfolder file format,
here's a start on that, Waldo just reminded me. ;-)

So this is an XML file that defines the layout of the menus. It
doesn't contain any info about menu items themselves; no strings in
this file are user-visible names of things.

I'll append an example, as that's no doubt the easiest way to explain.
People may want to scroll down and look over the example now before
reading the rest of this mail.

Notes on specific XML elements:

 - MergeDir is an old-style directory hierarchy to be added.
   The directories are converted into categories, 
   e.g. if you have /etc/X11/applnk/System/foo.desktop, 
   it might be considered to be in the System category.

   We'd probably need to spec out the directory-name-to-category
   mapping.

 - DesktopDir is an extra location to look for .desktop files, 
   in addition to the standard /usr/share/applications

 - Keyword is matched against the Categories line in the .desktop file

 - DontShowIfEmpty is a flag for folders to hide them if there's
   nothing in them. Personally I think this should be the default, 
   instead of a special flag.

 - <Query> is pretty simple; you can have And-queries or Or-queries,
   and can negate queries. If a desktop file matches all the
   conditions it gets included.

 - <Include> is used to force a desktop file into a specific folder
   explicitly (if you wanted you could build a whole menu this way,
   without queries). <Include> seems to assume that all desktop
   filenames are unique.

 - <Exclude> is used to force a desktop file to be excluded.

 - OnlyUnallocated means to include all the desktop files that have not 
   been put in the menu yet. i.e. it's the "other" category.

   In the code in desktop-file-utils, I implemented this as a two-pass
   thing. i.e. I do one pass placing desktop files in folders and
   marking those that were placed; then a second pass, putting all 
   things not placed in the first pass everywhere that it says
   OnlyUnallocated. You could imagine doing this differently, so 
   it probably needs to be specified how it works.

 - <Desktop> gives the .directory file that contains the name/icon for
   a folder/submenu.

There are two existing implementations of this. One is on
freedesktop.org CVS in desktop-file-utils. The most relevant file is
src/vfolder-query.c. It took me a weekend or so to implement this.

The other is in the gnome-vfs 2.0 package, in
modules/vfolder-desktop-method.c.

My quibbles with the format are:

 - s/VFolderInfo/Menu/ or something
 - DontShowIfEmpty should be ShowEvenIfEmpty or nonexistent
 - MergeDir should be named something indicating that 
   it parses an old-style hierarchy

But, I'm not sure any of those matter enough to bother changing.

You might ask how menu editing works with this. I think Alex Graveley
ended up sorting this out for GNOME, so I'm cc'ing him, maybe he could
explain what we ended up with.

There are some obvious ways to do it (the simplest way is to create
one of these files in the user's home dir, just using <Include> and no
queries). But if you want to try to pick up newly-installed apps in
the user's edited menus you have to be more clever.

Havoc

<VFolderInfo>
  <!-- Merge dirs optional -->
  <MergeDir>/etc/X11/applnk/</MergeDir>
  <MergeDir>/unst/share/gnome/apps/</MergeDir>

  <DesktopDir>/unst/share/gnome/vfolders</DesktopDir>

  <!-- Root folder -->
  <Folder>
    <Name>Root</Name>

    <Query>
      <Or>
        <Keyword>Core</Keyword>
      </Or>
    </Query>

    <!-- Other folders -->

    <!-- Applications -->
    <Folder>
      <Name>Applications</Name>
      <Desktop>Applications.directory</Desktop>
      <OnlyUnallocated/>
      <Query>
        <Keyword>Application</Keyword>
      </Query>
      <DontShowIfEmpty/>
    </Folder>

    <!-- Development Tools -->
    <Folder>
      <Name>Development Tools</Name>
      <Desktop>Development.directory</Desktop>
      <Query>
        <And>
          <Keyword>Application</Keyword>
	  <Keyword>Development</Keyword>
        </And>
      </Query>
      <DontShowIfEmpty/>
    </Folder>

    <!-- Games -->
    <Folder>
      <Name>Games</Name>
      <Desktop>Games.directory</Desktop>
      <Query>
        <And>
          <Keyword>Application</Keyword>
	  <Keyword>Game</Keyword>
        </And>
      </Query>
      <DontShowIfEmpty/>
    </Folder>

    <!-- Graphics -->
    <Folder>
      <Name>Graphics</Name>
      <Desktop>Graphics.directory</Desktop>
      <Query>
        <And>
          <Keyword>Application</Keyword>
	  <Keyword>Graphics</Keyword>
        </And>
      </Query>
      <DontShowIfEmpty/>
    </Folder>

    <!-- Internet -->
    <Folder>
      <Name>Internet</Name>
      <Desktop>Internet.directory</Desktop>
      <Query>
        <And>
          <Keyword>Application</Keyword>
	  <Keyword>Network</Keyword>
        </And>
      </Query>
      <DontShowIfEmpty/>
    </Folder>

    <!-- Multimedia -->
    <Folder>
      <Name>Multimedia</Name>
      <Desktop>Multimedia.directory</Desktop>
      <Query>
        <And>
          <Keyword>Application</Keyword>
	  <Keyword>AudioVideo</Keyword>
        </And>
      </Query>
      <DontShowIfEmpty/>
    </Folder>

    <!-- Office -->
    <Folder>
      <Name>Office</Name>
      <Desktop>Office.directory</Desktop>
      <Query>
	<And>
	  <Keyword>Application</Keyword>
	  <Or>
	    <Keyword>Office</Keyword>
	    <Keyword>Spreadsheet</Keyword>
	    <Keyword>WordProcessor</Keyword>
	    <Keyword>Calendar</Keyword>
	    <Keyword>ProjectManagement</Keyword>
	  </Or>
	</And>
      </Query>
      <DontShowIfEmpty/>
    </Folder>

    <!-- Settings -->
    <Folder>
      <Name>Settings</Name>
      <Desktop>Settings.directory</Desktop>
      <Query>
        <And>
          <Keyword>Application</Keyword>
	  <Keyword>Settings</Keyword>
        </And>
      </Query>
    </Folder>

    <!-- System -->
    <Folder>
      <Name>System</Name>
      <Desktop>System.directory</Desktop>
      <Query>
        <And>
          <Keyword>Application</Keyword>
	  <Keyword>System</Keyword>
        </And>
      </Query>
      <DontShowIfEmpty/>
    </Folder>

    <!-- Utilities -->
    <Folder>
      <Name>Utilities</Name>
      <Desktop>Utilities.directory</Desktop>
      <Query>
        <And>
          <Keyword>Application</Keyword>
	  <Keyword>Utility</Keyword>
        </And>
      </Query>
      <DontShowIfEmpty/>
    </Folder>
  </Folder>
</VFolderInfo>