[prev in list] [next in list] [prev in thread] [next in thread]
List: kde-commits
Subject: KDE/kdelibs/kdoctools
From: Burkhard Lück <lueck () hube-lueck ! de>
Date: 2010-10-27 14:02:39
Message-ID: 20101027140239.73767AC897 () svn ! kde ! org
[Download RAW message or body]
SVN commit 1190377 by lueck:
template update
@Yuri: please review, thanks
yurchor@ukr.net
M +51 -158 template.docbook
--- trunk/KDE/kdelibs/kdoctools/template.docbook #1190376:1190377
@@ -7,16 +7,23 @@
do *not* replace kappname-->
<!ENTITY package "kde-module"><!-- kdebase, kdeadmin, etc. Leave
this unchanged if your
- application is not maintained in KDE CVS -->
+ application is not maintained in KDE source \
archiv --> <!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE"> <!-- ONLY If you are writing non-English
original documentation, change
the language here -->
<!-- Do not define any other entities; instead, use the entities
- from entities/general.entities and $LANG/user.entities. -->
+ from entities/general.entities and en/user.entities. -->
]>
-<!-- kdoctemplate v0.9 January 10 2003
+<!-- kdoctemplate v0.9.1 2010-10-27 lueck
+ changed releaseinfo format
+ removed screenshot format="EPS
+ added comment when to write a command reference
+ added tip using id's in varlistentries
+ removed refentry stuff
+
+ kdoctemplate v0.9 January 10 2003
Changes to comments to clarify entity usage January 10 2003
Minor update to "Credits and Licenses" section on August 24, 2000
Removed "Revision history" section on 22 January 2001
@@ -73,23 +80,21 @@
</authorgroup>
<copyright>
-<year>2002</year>
+<year>2010</year>
<holder>George N. Ugnacious</holder>
</copyright>
-<!-- Translators: put here the copyright notice of the translation -->
-<!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook
- and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>
-<!-- Date and version information of the documentation
-Don't forget to include this last date and this last revision number, we
-need them for translation coordination !
-Please respect the format of the date (YYYY-MM-DD) and of the version
-(V.MM.LL), it could be used by automation scripts.
-Do NOT change these in the translation. -->
+<!-- Date of the documentation
+Don't forget to include this last date.
+Please respect the format of the date (YYYY-MM-DD),it is used by scripts.
+-->
+<date>2010-01-10</date>
-<date>2003-01-10</date>
-<releaseinfo>1.01.00</releaseinfo>
+<!--version information of the application and kde this documentation is valid for.
+either 'xx.yy.zz (&kde; x.y)' or '&kde; x.y'
+-->
+<releaseinfo>1.01.00 (&kde; 4,5)</releaseinfo>
<!-- Abstract about this handbook -->
@@ -155,9 +160,6 @@
<imageobject>
<imagedata fileref="screenshot.png" format="PNG"/>
</imageobject>
- <imageobject>
- <imagedata fileref="screenshot.eps" format="EPS"/>
- </imageobject>
<textobject>
<phrase>Screenshot</phrase>
</textobject>
@@ -175,9 +177,6 @@
<imageobject>
<imagedata fileref="squiggle.png" format="PNG"/>
</imageobject>
- <imageobject>
- <imagedata fileref="squiggle.eps" format="EPS"/>
- </imageobject>
<textobject>
<phrase>Squiggle</phrase>
</textobject>
@@ -194,9 +193,28 @@
<!-- (OPTIONAL, BUT RECOMMENDED) This chapter should list all of the
application windows and their menubar and toolbar commands for easy reference.
Also include any keys that have a special function but have no equivalent in the
-menus or toolbars. This may not be necessary for small apps or apps with no tool
-or menu bars. -->
+menus or toolbars.
+This may not be necessary for small apps or apps with no tool or menu bars.
+Don't bother users with well known kde menu items like Settings->Shortcuts etc.
+
+Use cases for a command reference:
+
+Applications with many menu items (Kate/Konqueror)
+Applications with different modes and menus (KWrite/Konqueror)
+-> Enables search for menu items
+
+For Applications with default menu items and some special items where user
+needs additional information use something like:
+"Apart from the common KDE menu items you find these action in the menu:
+
+File -> Special Action: Explanation of special action
+
+Tools -> Special Tool: Explanation of special tool
+
+Use variablelist markup for this
+-->
+
<sect1 id="kapp-mainwindow">
<title>The main &kmyapplication; window</title>
@@ -204,7 +222,12 @@
<title>The File Menu</title>
<para>
<variablelist>
-<varlistentry>
+<varlistentry id="file-new">
+<!-- Tip: With id's here, then you can use them like
+"select <xref linkend="file-new"/> to open the file dialog"
+which will be expanded to:
+"select File->New (Ctrl+N) to open the file dialog"
+-->
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
@@ -240,7 +263,7 @@
</sect2>
<sect2>
-<title>The <guimenu>Help</guimenu> Menu</title>
+<title>The Help Menu</title>
<!-- Assuming you have a standard help menu (help, what's this, about -->
<!-- &kmyapplication;, about KDE) then the documentation is already written. -->
@@ -262,140 +285,10 @@
and/or development libraries. -->
<para>
-Programming &kmyapplication; plugins is a joy to behold. Just read through the next
-66 pages of API's to learn how!
+Programming &kmyapplication; plugins is a joy to behold.
</para>
-<!-- Use refentries to describe APIs. Refentries are fairly complicated and you
-should consult the docbook reference for further details. The example below was
-taken from that reference and shortened a bit for readability. -->
-<refentry id="re-1007-unmanagechildren-1">
-<refmeta>
-<refentrytitle>XtUnmanageChildren</refentrytitle>
-<refmiscinfo>Xt - Geometry Management</refmiscinfo>
-</refmeta>
-<refnamediv>
-<refname>XtUnmanageChildren
-</refname>
-<refpurpose>remove a list of children from a parent widget's managed
-list.
-<indexterm id="ix-1007-unmanagechildren-1"><primary>widgets</primary><secondary>removing</secondary></indexterm>
-<indexterm id="ix-1007-unmanagechildren-2"><primary>XtUnmanageChildren</primary></indexterm>
-</refpurpose>
-
-</refnamediv>
-<refsynopsisdiv>
-<refsynopsisdivinfo>
-<date>4 March 1996</date>
-</refsynopsisdivinfo>
-<synopsis>
-void XtUnmanageChildren(<replaceable class="parameter">children</replaceable>, \
<replaceable class="parameter">num_children</replaceable>)
- WidgetList <replaceable class="parameter">children</replaceable>;
- Cardinal <replaceable class="parameter">num_children</replaceable>;
-</synopsis>
-
-<refsect2 id="r2-1007-unmanagechildren-1">
-<title>Inputs</title>
-<variablelist>
-<varlistentry>
-<term><replaceable class="parameter">children</replaceable>
-</term>
-<listitem>
-<para>Specifies an array of child widgets. Each child must be of
-class RectObj or any subclass thereof.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><replaceable class="parameter">num_children</replaceable>
-</term>
-<listitem>
-<para>Specifies the number of elements in <replaceable \
class="parameter">children</replaceable>.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</refsect2></refsynopsisdiv>
-
-<refsect1 id="r1-1007-unmanagechildren-1">
-<title>Description
-</title>
-<para><function>XtUnmanageChildren()</function> unmaps the specified widgets
-and removes them from their parent's geometry management.
-The widgets will disappear from the screen, and (depending
-on its parent) may no longer have screen space allocated for
-them.
-</para>
-<para>Each of the widgets in the <replaceable \
class="parameter">children</replaceable> array must have
-the same parent.
-</para>
-<para>See the “Algorithm” section below for full details of the
-widget unmanagement procedure.
-</para>
-</refsect1>
-
-<refsect1 id="r1-1007-unmanagechildren-2">
-<title>Usage</title>
-<para>Unmanaging widgets is the usual method for temporarily
-making them invisible. They can be re-managed with
-<function>XtManageChildren()</function>.
-</para>
-<para>You can unmap a widget, but leave it under geometry
-management by calling <function>XtUnmapWidget()</function>. You can
-destroy a widget's window without destroying the widget by
-calling <function>XtUnrealizeWidget()</function>. You can destroy a
-widget completely with <function>XtDestroyWidget()</function>.
-</para>
-<para>If you are only going to unmanage a single widget, it is
-more convenient to call <function>XtUnmanageChild()</function>. It is
-often more convenient to call <function>XtUnmanageChild()</function>
-several times than it is to declare and initialize an array
-of widgets to pass to <function>XtUnmanageChildren()</function>. Calling
-<function>XtUnmanageChildren()</function> is more efficient, however,
-because it only calls the parent's <function>change_managed()</function>
-method once.
-</para>
-</refsect1>
-
-<refsect1 id="r1-1007-unmanagechildren-3">
-<title>Algorithm
-</title>
-<para><function>XtUnmanageChildren()</function> performs the following:
-</para>
-<variablelist>
-<varlistentry>
-<term>-
-</term>
-<listitem>
-<para>Ignores the child if it already is unmanaged or is being
-destroyed.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>-
-</term>
-<listitem>
-<para>Otherwise, if the child is realized, it makes it nonvisible
-by unmapping it.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-<para>
-</para>
-</refsect1>
-
-<refsect1 id="r1-1007-unmanagechildren-4">
-<title>Structures</title>
-<para>The <type>WidgetList</type> type is simply an array of widgets:
-</para>
-<screen id="sc-1007-unmanagechildren-1">typedef Widget *WidgetList;
-</screen>
-</refsect1>
-</refentry>
-
</chapter>
<chapter id="faq">
@@ -489,7 +382,7 @@
<title>How to obtain &kmyapplication;</title>
<!-- This first entity contains boiler plate for applications that are
-part of KDE CVS. You should remove it if you are releasing your
+part of KDE archiv. You should remove it if you are releasing your
application -->
&install.intro.documentation;
@@ -511,7 +404,7 @@
-->
<para>
-In order to successfully use &kmyapplication;, you need &kde; 1.1. Foobar.lib is
+In order to successfully use &kmyapplication;, you need &kde; 4.5. Foobar.lib is
required in order to support the advanced &kmyapplication; features. \
&kmyapplication; uses about 5 megs of memory to run, but this may vary depending on \
your platform and configuration.
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic