diff options
| -rw-r--r-- | menu/menu-spec.xml | 153 |
1 files changed, 148 insertions, 5 deletions
diff --git a/menu/menu-spec.xml b/menu/menu-spec.xml index b5954c5..9b195a3 100644 --- a/menu/menu-spec.xml +++ b/menu/menu-spec.xml @@ -4,8 +4,8 @@ <article id="index"> <artheader> <title>Desktop Menu Specification</title> - <releaseinfo>Version 0.6</releaseinfo> - <date>5 September 2003</date> + <releaseinfo>Version 0.7</releaseinfo> + <date>15 September 2003</date> <authorgroup> <author> <firstname>Waldo</firstname> @@ -52,6 +52,15 @@ </address> </affiliation> </author> + <author> + <firstname>Heinrich</firstname> + <surname>Wendel</surname> + <affiliation> + <address> + <email>h_wendel@cojobo.net</email> + </address> + </affiliation> + </author> </authorgroup> </artheader> @@ -77,6 +86,12 @@ layout. Both of these issues are addressed by the idea of <firstterm>merging</firstterm> two menu layouts. </para> + <para> + In addition to a strict definition of the contents of each menu this + specification also forsees in a number of layout / presentation hints. + This part of the specification is optional, implementations may chose to + ignore these hints. + </para> </sect1> <sect1 id="paths"> <title>File locations</title> @@ -108,7 +123,7 @@ <term><varname>$XDG_CONFIG_DIRS</varname>/menus/<replaceable>menu-file-basename</replaceable>-merged/</term> <listitem> <para> - One of the default merge directories included in the + The default merge directories included in the <DefaultMergeDirs> element. By convention, third parties may add new <Menu> files in this location. <replaceable>menu-file-basename</replaceable> means the @@ -161,8 +176,8 @@ <para> This specification adds two new fields to <ulink url="http://www.freedesktop.org/standards/desktop-entry-spec.html">desktop -entries</ulink>: <varname>Categories</varname> and - <varname>OnlyShowIn</varname>. +entries</ulink>: <varname>Categories</varname>, + <varname>OnlyShowIn</varname> and <varname>NotShowIn</varname>. </para> <para> The <varname>Categories</varname> field is a list of strings used to @@ -188,6 +203,15 @@ entries</ulink>: <varname>Categories</varname> and linkend="onlyshowin-registry"/> enumerates the strings to use for some common environments. </para> + <para> + The <varname>NotShowIn</varname> field is a list of strings identifying + the environments that should not display a given menu item. If an + <varname>NotShowIn</varname> field is present, a given environment should + only display the menu item if the string identifying that environment is + not present. The strings are case-sensitive. <xref + linkend="onlyshowin-registry"/> enumerates the strings to use for + some common environments. + </para> <sect2 id="desktop-entry-extensions-examples"> <title>Examples of using <varname>Categories</varname> and <varname>OnlyShowIn</varname></title> <para> @@ -755,6 +779,117 @@ entries</ulink>: <varname>Categories</varname> and </para> </listitem> </varlistentry> + <varlistentry> + <term><Layout [show_empty="false"]></term> + <listitem> + <para> + The <Layout> element is an optional part of this specification. + Implementations that do not support the <Layout> element should + preserve any <Layout> elements and their contents as far as + possible. + Each <Menu> may optionally contain a <Layout> element. + If multipe elements appear then only the last such element is relevant. + The purpose of this element is to offer suggestions for the presentation + of the menu. + If a menu does not contain a <Layout> element or if it contains + an empty <Layout> element then the default layout should be used. + The <Layout> element may contain <Filename>, <Menuname>, + <Separator> and <Merge> elements. The <Layout> element + defines a suggested layout for the menu starting from top to bottom. + References to desktop entries that are not contained in this + menu as defined by the <Include> and <Exclude> elements should + be ignored. References to sub-menus that are not directly contained in this + menu as defined by the <Menu> elements should be ignored. + The show_empty attribute defines whether a menu that contains no desktop + entries and no sub-menus should be shown at all. The show_empty attribute + can be "true" or "false". The default is "false". + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><DefaultLayout></term> + <listitem> + <para> + The <DefaultLayout> element is an optional part of this specification. + Implementations that do not support the <DefaultLayout> element should + preserve any <DefaultLayout> elements and their contents as far as + possible. + Each <Menu> may optionally contain a <DefaultLayout> element + which defines the default-layout for the current menu and all its sub-menus. + If a menu has a <DefaultLayout> element then this will override + any default-layout specified by a parent menu. + The default-layout defines the suggested layout if a <Menu> element + does either not have <Layout> element or if it has an empty <Layout> element. + If no default-layout has been specified then the layout as specified by the following + elements should be assumed: + <DefaultLayout><Merge type="menus"/><Merge type="files"/></DefaultLayout> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><Menuname [inline="false"] [inline_limit="4"] [inline_header="true"] [inline_alias="false"]></term> + <listitem> + <para> + This element may only appear as a child of a <Layout> or <DefaultLayout> + menu. Its contents references an immediate sub-menu of the current menu as defined + with the <Menu> element, as such it should never contain a slash. + If no such sub-menu exists the element should be ignored. + It may have an inline attribute that can be either "true" or "false", the default is "false". + If the inline attribute is "true" the menu that is referenced may be copied into the + current menu at the current point instead of being inserted as sub-menu of the current menu. + The optional inline_limit attribute defines the maximum number of entries that can be inlined. + If the sub-menu has more entries than inline_limit, the sub-menu will not be inlined. + If the inline_limit is 0 (zero) there is no limit. The default inline_limit is 4. + The optional inline_title attribute defines whether an inlined menu should be preceeded with + a header entry listing the caption of the sub-menu. + The inline_title attribute can be either "true" or "false", the default is "true". + The optional inline_alias attribute defines whether a single inlined entry should adopt the + caption of the inlined menu. In such case no additional header entry will be added regardless + of the value of the inline_title attribute. + The inline_alias attribute can be either "true" or "false", the default is "false". + Example: if a menu has a sub-menu titled "WordProcessor" with a single entry "OpenOffice 4.2", + and both inline="true" and inline_alias="true" are specified then this would result in the + "OpenOffice 4.2" entry being inlined in the current menu but the "OpenOffice 4.2" caption + of the entry would be replaced with "WordProcessor". + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><Separator></term> + <listitem> + <para> + This element may only appear as a child of a <Layout> or <DefaultLayout> + menu. It indicates a suggestion to draw a visual separator at this point in the menu. + <Separator> elements at the start of a menu, at the end of a menu or that directly + follow other <Separator> elements may be ignored. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><Merge type="menus"|"files"|"all"/></term> + <listitem> + <para> + This element may only appear as a child of a <Layout> or <DefaultLayout> + menu. It indicates the point where desktop entries and sub-menus that are not explicitly + mentioned within the <Layout> or <DefaultLayout> element are to be inserted. + It has a type attribute that indicates which elements should be inserted: + type="menus" + means that all sub-menus that are not explicitly mentioned should be inserted in + alphabetical order of their visual caption at this point. + type="files" + means that all desktop entries + contained in this menu that are not explicitly mentioned should be inserted in + alphabetical order of their visual caption at this point. + type="all" means that a mix of all sub-menus + and all desktop entries that are not explicitly mentioned should be inserted in + alphabetical order of their visual caption at this point. + Each <Layout> or <DefaultLayout> element shall have exactly one <Merge type="all"> + element or it shall have exactly one <Merge type="files"> and exactly one + <Merge type="menus"> element. An excemption is made for a completely empty <Layout> + element which may be used to indicate that the default-layout should be used instead. + </para> + </listitem> + </varlistentry> </variablelist> </para> </sect2> @@ -1052,6 +1187,14 @@ entries</ulink>: <varname>Categories</varname> and <-- Merge legacy hierarchy --> <LegacyDir>/usr/share/applnk</LegacyDir> + <-- Define default layout --> + <DefaultLayout> + <Merge type="menus"/> + <Merge type="files"/> + <Separator/> + <Menuname>More</Menuname> + </DefaultLayout> + <-- some random moves, maybe to clean up legacy dirs, maybe from menu editing --> <Move> |