File: Desktop_menus.xml

package info (click to toggle)
publican 4.2.6-1
  • links: PTS, VCS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 15,584 kB
  • ctags: 450
  • sloc: perl: 12,896; xml: 11,510; makefile: 45; sh: 6
file content (247 lines) | stat: -rw-r--r-- 11,200 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section [
<!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent">
%BOOK_ENTITIES;
<!ENTITY % sgml.features "IGNORE">
<!ENTITY % xml.features "INCLUDE">
<!ENTITY % DOCBOOK_ENTS PUBLIC "-//OASIS//ENTITIES DocBook Character Entities V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/dbcentx.mod">
%DOCBOOK_ENTS;
]>
<section conformance="134" version="5.0" xml:id="sect-Publican-Users_Guide-Desktop_menu_entries_for_documents" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
	<info xml:id="info-Publican-Users_Guide-Desktop_menu_entries_for_documents">
		<title>Desktop menu entries for documents</title>

	</info>
	 <para>
		By default, RPM packages of <application>Publican</application> documents for desktop use appear on the GNOME desktop under the <menuchoice><guimenu>System</guimenu><guisubmenu>Documentation</guisubmenu></menuchoice> menu. When users have large numbers of documents installed on their systems, this menu becomes very cluttered and difficult to navigate. Documentation for many different products and perhaps different languages becomes intermixed, adding to the confusion.
	</para>
	 <para>
		To group documentation for your product under a separate submenu within the GNOME <menuchoice><guimenu>System</guimenu><guisubmenu>Documentation</guisubmenu></menuchoice> menu, you must:
	</para>
	 <itemizedlist>
		<listitem>
			<para>
				create and distribute a desktop menu package that creates the new submenu.
			</para>

		</listitem>
		 <listitem>
			<para>
				specify the menu <firstterm>category</firstterm> in the document, and optionally, have the documentation package <firstterm>require</firstterm> the desktop menu package.
			</para>

		</listitem>

	</itemizedlist>
	 <para>
		Note that the <guimenu>Documentation</guimenu> menu does not group entries under a submenu until two or more documents are installed that belong on that submenu. The first document appears under <menuchoice><guimenu>System</guimenu><guisubmenu>Documentation</guisubmenu></menuchoice>.
	</para>
	 <section conformance="135" xml:id="sect-Publican-Users_Guide-Desktop_menu_entries_for_documents-Creating_an_desktop_menu_package">
		<info xml:id="info-Publican-Users_Guide-Creating_an_desktop_menu_package">
			<title>Creating an desktop menu package</title>

		</info>
		 <para>
			A desktop menu package consists of:
		</para>
		 <itemizedlist>
			<listitem>
				<para>
					a <firstterm>desktop entry</firstterm> (<filename>.directory</filename>) file that provides metadata about the new submenu.
				</para>

			</listitem>
			 <listitem>
				<para>
					a <firstterm>desktop menu</firstterm> (<filename>.menu</filename>) file that defines the position of the new submenu within the <guimenu>Documentation</guimenu> menu.
				</para>

			</listitem>

		</itemizedlist>
		 <para>
			The structure for the <filename>.directory</filename> file for <application>Publican</application>-generated documentation is as follows:
		</para>
		 <itemizedlist>
			<listitem>
				<para>
					the <firstterm>group header</firstterm> <literal>[Desktop Entry]</literal>
				</para>

			</listitem>
			 <listitem>
				<para>
					the <parameter>Name</parameter> parameter, set to the name of the submenu that you want to place under the <guimenu>Documentation</guimenu> menu.
				</para>

			</listitem>
			 <listitem>
				<para>
					optionally, localizations of the <parameter>Name</parameter> parameter, in the format <parameter>Name[<replaceable>language_code</replaceable>]</parameter> where <replaceable>language_code</replaceable> is a language code in glibc format, <emphasis>not</emphasis> the XML format that <application>Publican</application> uses for language codes.
				</para>

			</listitem>
			 <listitem>
				<para>
					the <parameter>Comment</parameter> parameter, set to a description of the new submenu.
				</para>

			</listitem>
			 <listitem>
				<para>
					optionally, localizations of the <parameter>Comment</parameter> parameter, in the format <parameter>Comment[<replaceable>language_code</replaceable>]</parameter> where <replaceable>language_code</replaceable> is a language code in glibc format, <emphasis>not</emphasis> the XML format that <application>Publican</application> uses for language codes.
				</para>

			</listitem>
			 <listitem>
				<para>
					the <parameter>Type</parameter> parameter, set to <literal>Directory</literal>.
				</para>

			</listitem>
			 <listitem>
				<para>
					the <parameter>Encoding</parameter> parameter, set to <literal>UTF-8</literal>.
				</para>

			</listitem>

		</itemizedlist>
		 <example conformance="239" xml:id="exam-Publican-Users_Guide-Creating_an_desktop_menu_package-Example_.directory_file">
			<info xml:id="info-Publican-Users_Guide-Example_.directory_file">
				<title>Example .directory file</title>

			</info>
			 <para>
				The following file, <filename>menu-example.directory</filename> illustrates the structure of a desktop entry file.
			</para>
			 
<programlisting><xi:include href="extras/menu-example.directory" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>

		</example>
		 <para>
			The desktop entry file is placed in <filename>/usr/share/desktop-directories/</filename>
		</para>
		 <para>
			For a full description of how desktop entries work, refer to the <citetitle>Desktop Entry Specification</citetitle>, available from <uri xlink:href="http://standards.freedesktop.org/entry-spec/latest/" xmlns:xlink="http://www.w3.org/1999/xlink">http://standards.freedesktop.org/entry-spec/latest/</uri>
		</para>
		 <para>
			A desktop menu file is an XML file that contains:
		</para>
		 <itemizedlist>
			<listitem>
				<para>
					a document type declaration for the freedesktop.org Desktop Menu Specification:
				</para>
				 
<programlisting language="XML">&lt;!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
"http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd"&gt;</programlisting>

			</listitem>
			 <listitem>
				<para>
					a <firstterm>root element</firstterm>, <tag>&lt;Menu&gt;</tag>, that contains:
				</para>
				 <itemizedlist>
					<listitem>
						<para>
							a <tag>&lt;Name&gt;</tag> element with the content <literal>Documentation</literal>
						</para>

					</listitem>
					 <listitem>
						<para>
							another <tag>&lt;Menu&gt;</tag> element that in turn contains:
						</para>
						 <itemizedlist>
							<listitem>
								<para>
									a <tag>&lt;Name&gt;</tag> element with the content <literal>Documentation</literal> (just like the root element)
								</para>

							</listitem>
							 <listitem>
								<para>
									a <tag>&lt;Directory&gt;</tag> element with its content the name of the desktop entry file you created, for example:
								</para>
								 
<programlisting language="XML">&lt;Directory&gt;menu-example.directory&lt;/Directory&gt;</programlisting>

							</listitem>
							 <listitem>
								<para>
									an <tag>&lt;Includes&gt;</tag> element with the content <literal>X-<replaceable>category_name</replaceable></literal>, where <replaceable>category_name</replaceable> is an identifier for the documents that will be grouped together under this menu entry. For example:
								</para>
								 
<programlisting language="XML">&lt;Includes&gt;X-Example-Docs&lt;/Includes&gt;</programlisting>

							</listitem>

						</itemizedlist>

					</listitem>

				</itemizedlist>

			</listitem>

		</itemizedlist>
		 <example conformance="240" xml:id="exam-Publican-Users_Guide-Creating_an_desktop_menu_package-Example_.menu_file">
			<info xml:id="info-Publican-Users_Guide-Example_.menu_file">
				<title>Example .menu file</title>

			</info>
			 <para>
				The following file, <filename>menu-example.menu</filename> illustrates the structure of a desktop menu file.
			</para>
			 
<programlisting><xi:include href="extras/menu-example.menu" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>

		</example>
		 <para>
			The desktop menu file is placed in <filename>/etc/xdg/menus/settings-merged/</filename>
		</para>
		 <para>
			For a full description of how desktop menus work, refer to the <citetitle>Desktop Menu Specification</citetitle>, available from <uri xlink:href="http://standards.freedesktop.org/desktop-menu-spec/latest/" xmlns:xlink="http://www.w3.org/1999/xlink">http://standards.freedesktop.org/desktop-menu-spec/latest/</uri>
		</para>

	</section>
	 <section conformance="136" xml:id="sect-Publican-Users_Guide-Desktop_menu_entries_for_documents-Setting_a_desktop_menu_category">
		<info xml:id="info-Publican-Users_Guide-Setting_a_desktop_menu_category">
			<title>Setting a desktop menu category</title>

		</info>
		 <para>
			To place a document in a submenu of <menuchoice><guimenu>System</guimenu><guisubmenu>Documentation</guisubmenu></menuchoice>, set the <parameter>menu_category</parameter> parameter in its <filename>publican.cfg</filename> file to match the content of the <tag>&lt;Includes&gt;</tag> element in the corresponding desktop menu file. For example, consider a desktop menu file that contains the element:
		</para>
		 
<programlisting language="XML">&lt;Includes&gt;X-Example-Docs&lt;/Includes&gt;</programlisting>
		 <para>
			To place a document in the submenu defined by this desktop menu file, the document's <filename>publican.cfg</filename> file should contain:
		</para>
		 
<programlisting>menu_category: X-Example-Docs</programlisting>
		 <important>
			<para>
				Publican will process the string in menu_category and replace <literal>__LANG__</literal> with the current language. This allows menus to be customized on a per language basis.
			</para>
			 <informalexample>
<programlisting>menu_category: X-Example-Docs-__LANG__</programlisting>
			 </informalexample>
		</important>
		 <para>
			Note that you can include this parameter in the <filename>defaults.cfg</filename> file or <filename>overrides.cfg</filename> file of a brand so that all documents built with that brand are grouped into this submenu automatically without you having to set the <parameter>menu_category</parameter> parameter in each document.
		</para>
		 <para>
			If you ship the desktop menu and desktop entry files in an RPM package, you can make RPM packages of documentation <firstterm>require</firstterm> the desktop menu package. With this dependency set, the desktop menu package is installed automatically on users' systems when they install a documentation package, which ensures that the documentation appears under the submenu you have created for your project. Set the dependency with the <parameter>dt_requires</parameter> parameter in the document's <filename>publican.cfg</filename> file. For example, if you ship a desktop menu package named <package>foodocs-menu</package>, set:
		</para>
		 
<programlisting>dt_requires: foodocs-menu</programlisting>
		 <para>
			Note that you can include this parameter in the <filename>defaults.cfg</filename> file or <filename>overrides.cfg</filename> file of a brand so that all documents built with that brand require the same desktop menu package.
		</para>

	</section>

</section>