| blob | 74c361c7e59bc1b01060069053e0af618fb49672 |
1 KHelpCenter documentation meta data structure
2 =============================================
4 KHelpCenter uses meta data files which describe the documentation available in
5 the system. Each document is represented by a meta data file and shown as an
6 entry in the KHelpCenter navigation tree view. The meta data contains
7 information about title and short description of the document, the location of
8 the document and some more information like how to search the document and
9 translations of title and description. Document hierarchy is represented as
10 hierarchy of the meta data files. Directories are also described by a meta data
11 file which contains the same information as a document meta data file.
13 Format of the meta data files
14 -----------------------------
16 The meta files adhere to the Desktop Entry Standard
17 (http://www.freedesktop.org/Standards/desktop-entry-spec). Documentation
18 specific extensions are covered by an own namespace using the prefix "X-DOC-".
19 The following table describes all keys which are currently used by
20 KHelpCenter:
22 Key Value Description
24 Name string Title of document
25 Name[xx] string Translated title for language xx
26 Comment string Short description of document
27 Comment[xx] string Translated short description for
28 Language xx
29 Icon string Name of icon for document
30 X-DocPath URI Location of document. In addition to the
31 standard URI schemes like http: and file:
32 all schemes which are supported through
33 kioslaves can be used. In particular the
34 following non-standard URI schemes are
35 supported:
36 help: KDE manual identified by app name
37 ghelp: GNOME manual identified by app name
38 man: man page
39 info: info page
40 cgi: output of CGI script
41 X-DocPath[xx] URI Language specific location for
42 language xx
43 Lang langcode Language of document
44 X-DOC-Identifier string Unique identifier for document, if this
45 entry is not present the base name of the
46 file is used as identifier
47 X-DOC-Indexer command Command used for creating a search index
48 for the document.
49 The following symbols are replaced by the
50 corresponding values:
51 %f - Filename
52 X-DOC-IndexTestFile filename Name of file whose existence indicates
53 the existence of a usable search index
54 X-DOC-Search command Command used for searching, the output
55 of the command should be HTML which is
56 shown in KHelpCenter.
57 The following symbols in the command are
58 replaced by the corresponding values:
59 %k - Words to be searched for
60 %n - Maximum number of results
61 %m - Method for combining search words,
62 can be 'and' or 'or'
63 %l - Language of documents to be searched
64 %s - Scope of search. This is a list of
65 identifiers as given by the
66 X-DOC-Identifier entry or the bas
67 name of the desktop file if not
68 present.
69 X-DOC-SearchMethod string If this entry is 'htdig' htdig is used to
70 index and search the document. The
71 Indexer, IndexTestFile and Search entries
72 aren't required in this case.
73 X-DOC-SearchEnabledDefault bool If set to 'true' the document is searched
74 by default, if set to 'false' it is not.
75 This setting is overridden by user
76 selected search scopes.
77 X-DOC-Weight int A number indicating the position of the
78 document within the list of siblings. A
79 greater weight indicates that the document
80 is 'heavier', thus shown below 'lighter'
81 documents. The default weight is 0.
82 X-KDE-KHelpcenter string If this entry is set to one of the
83 following values a set of documents
84 generated by other means than desktop file
85 meta info is inserted at the place
86 specified by the desktop file:
87 'apps' manuals of applications
88 from the start menu
89 'scrollkeeper' scrollkeeper docs
90 'applets' panel applet docs
91 'kinfocenter' kinfocenter docs
92 'kcontrol' kcontrol module docs
93 'konqueror' konqueror plugin docs
94 'kioslave' kioslave docs
95 'info' info pages
96 X-DOC-DocumentType string Type of document. The type is used to look
97 up corresponding search handlers.
99 Meta File Location
100 ------------------
102 A list of directories given by the config entry "MetaInfoDirs" in the "General"
103 group of the help center configuration file "khelpcenterrc" (at
104 $KDEDIRS/share/config) is scanned for desktop files. They are merged to a common
105 hierarchy. If the "MetaInfoDirs" entry is empty the directory at
106 $KDEDIRS/share/apps/khelpcenter/plugins is used.
108 Document Hierarchy
109 ------------------
111 The hierarchy of the documents shown in the help center is reflected by the
112 hierarchy of the desktop files in the filesystem. Directories can have an
113 associated desktop file with the name ".directory". It can contain all the
114 keys described above.
116 Language handling
117 -----------------
119 In addition to translation of meta information like title and short description
120 of documents which is contained in the meta file, translations of whole
121 documents are handled. Each translation of a document has an own desktop file.
122 The language of the document is indicated by adding the language code as
123 additional suffix to the the filename of the desktop file. The language suffix
124 is added before the ".desktop" suffix (Example: 'apache.de.desktop' would be the
125 file name for the german translation of the apache documentation).
127 KHelpCenter shows only the documents whose language is contained in the list of
128 used languages configured for the desktop in the control center. A document
129 corresponding to a desktop file without language suffix is always shown.