summaryrefslogtreecommitdiffstats
path: root/khelpcenter/README.metadata
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commit4aed2c8219774f5d797760606b8489a92ddc5163 (patch)
tree3f8c130f7d269626bf6a9447407ef6c35954426a /khelpcenter/README.metadata
downloadtdebase-4aed2c8219774f5d797760606b8489a92ddc5163.tar.gz
tdebase-4aed2c8219774f5d797760606b8489a92ddc5163.zip
Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebase@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'khelpcenter/README.metadata')
-rw-r--r--khelpcenter/README.metadata129
1 files changed, 129 insertions, 0 deletions
diff --git a/khelpcenter/README.metadata b/khelpcenter/README.metadata
new file mode 100644
index 000000000..733bb5ef2
--- /dev/null
+++ b/khelpcenter/README.metadata
@@ -0,0 +1,129 @@
+KHelpCenter documentation meta data structure
+=============================================
+
+KHelpCenter uses meta data files which describe the documentation available in
+the system. Each document is represented by a meta data file and shown as an
+entry in the KHelpCenter navigation tree view. The meta data contains
+information about title and short description of the document, the location of
+the document and some more information like how to search the document and
+translations of title and description. Document hierarchy is represented as
+hierarchy of the meta data files. Directories are also described by a meta data
+file which contains the same information as a document meta data file.
+
+Format of the meta data files
+-----------------------------
+
+The meta files adhere to the Desktop Entry Standard
+(http://www.freedesktop.org/Standards/desktop-entry-spec). Documentation
+specific extensions are covered by an own namespace using the prefix "X-DOC-".
+The following table describes all keys which are currently used by
+KHelpCenter:
+
+Key Value Description
+
+Name string Title of document
+Name[xx] string Translated title for language xx
+Comment string Short description of document
+Comment[xx] string Translated short description for
+ Language xx
+Icon string Name of icon for document
+DocPath URI Location of document. In addition to the
+ standard URI schemes like http: and file:
+ all schemes which are supported through
+ kioslaves can be used. In particular the
+ following non-standard URI schemes are
+ supported:
+ help: KDE manual identified by app name
+ ghelp: GNOME manual identified by app name
+ man: man page
+ info: info page
+ cgi: output of CGI script
+DocPath[xx] URI Language specific location for
+ language xx
+Lang langcode Language of document
+X-DOC-Identifier string Unique identifier for document, if this
+ entry is not present the base name of the
+ file is used as identifier
+X-DOC-Indexer command Command used for creating a search index
+ for the document.
+ The following symbols are replaced by the
+ corresponding values:
+ %f - Filename
+X-DOC-IndexTestFile filename Name of file whose existence indicates
+ the existence of a usable search index
+X-DOC-Search command Command used for searching, the output
+ of the command should be HTML which is
+ shown in KHelpCenter.
+ The following symbols in the command are
+ replaced by the corresponding values:
+ %k - Words to be searched for
+ %n - Maximum number of results
+ %m - Method for combining search words,
+ can be 'and' or 'or'
+ %l - Language of documents to be searched
+ %s - Scope of search. This is a list of
+ identifiers as given by the
+ X-DOC-Identifier entry or the bas
+ name of the desktop file if not
+ present.
+X-DOC-SearchMethod string If this entry is 'htdig' htdig is used to
+ index and search the document. The
+ Indexer, IndexTestFile and Search entries
+ aren't required in this case.
+X-DOC-SearchEnabledDefault bool If set to 'true' the document is searched
+ by default, if set to 'false' it is not.
+ This setting is overridden by user
+ selected search scopes.
+X-DOC-Weight int A number indicating the position of the
+ document within the list of siblings. A
+ greater weight indicates that the document
+ is 'heavier', thus shown below 'lighter'
+ documents. The default weight is 0.
+X-KDE-KHelpcenter string If this entry is set to one of the
+ following values a set of documents
+ generated by other means than desktop file
+ meta info is inserted at the place
+ specified by the desktop file:
+ 'apps' manuals of applications
+ from the start menu
+ 'scrollkeeper' scrollkeeper docs
+ 'applets' panel applet docs
+ 'kinfocenter' kinfocenter docs
+ 'kcontrol' kcontrol module docs
+ 'konqueror' konqueror plugin docs
+ 'kioslave' kioslave docs
+ 'info' info pages
+X-DOC-DocumentType string Type of document. The type is used to look
+ up corresponding search handlers.
+
+Meta File Location
+------------------
+
+A list of directories given by the config entry "MetaInfoDirs" in the "General"
+group of the help center configuration file "khelpcenterrc" (at
+$KDEDIRS/share/config) is scanned for desktop files. They are merged to a common
+hierarchy. If the "MetaInfoDirs" entry is empty the directory at
+$KDEDIRS/share/apps/khelpcenter/plugins is used.
+
+Document Hierarchy
+------------------
+
+The hierarchy of the documents shown in the help center is reflected by the
+hierarchy of the desktop files in the filesystem. Directories can have an
+associated desktop file with the name ".directory". It can contain all the
+keys described above.
+
+Language handling
+-----------------
+
+In addition to translation of meta information like title and short description
+of documents which is contained in the meta file, translations of whole
+documents are handled. Each translation of a document has an own desktop file.
+The language of the document is indicated by adding the language code as
+additional suffix to the the filename of the desktop file. The language suffix
+is added before the ".desktop" suffix (Example: 'apache.de.desktop' would be the
+file name for the german translation of the apache documentation).
+
+KHelpCenter shows only the documents whose language is contained in the list of
+used languages configured for the desktop in the control center. A document
+corresponding to a desktop file without language suffix is always shown.