[kde-doc-english] [kdoctools] src: Update book template + man template + add arcticle template
Burkhard Lück
lueck at hube-lueck.de
Tue May 24 20:17:26 UTC 2016
Git commit cbf38fa6f3d48dab593ce197ee402dd750480f30 by Burkhard Lück.
Committed on 24/05/2016 at 20:16.
Pushed by lueck into branch 'master'.
Update book template + man template + add arcticle template
add translatable entities
remove help.menu.documentation entity
add some examples how to use the common menus Settings and Help
Add #Use this template for ...' to article + book template
Add notes to man-template.docbook about the naming scheme (manual sections)
REVIEW:127720
A +67 -0 src/article-template.docbook
M +5 -1 src/man-template.docbook
M +52 -14 src/template.docbook
http://commits.kde.org/kdoctools/cbf38fa6f3d48dab593ce197ee402dd750480f30
diff --git a/src/article-template.docbook b/src/article-template.docbook
new file mode 100644
index 0000000..6a9ffe0
--- /dev/null
+++ b/src/article-template.docbook
@@ -0,0 +1,67 @@
+<?xml version="1.0" ?>
+<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN"
+"dtd/kdedbx45.dtd" [
+<!ENTITY i18n-translatable-entity "<application>Translatable Entity</application>">
+<!ENTITY % addindex "IGNORE">
+<!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<!--
+Use this template for kioslave, systemsettings (kcontrol) modules and simple/short application docbooks
+Otherwise use use template.docbook for application docbooks
+Rename this template to index.docbook and place into the directory doc/[kcontrol|kioslave5]
+-->
+
+<article id="foo" lang="&language;">
+<articleinfo>
+<title>Foo</title>
+<authorgroup>
+<author>
+<!-- This is just put in as an example. For real documentation, please
+ define a general entity in entities/contributor.entities, e.g.
+<!ENTITY George.N.Ugnacious "<personname><firstname>George</firstname><othername>N.</othername><surname>Ugnacious</surname></personname>">
+<!ENTITY George.N.Ugnacious.mail "<email>gnu at kde.org</email>">
+and use `&George.N.Ugnacious; &George.N.Ugnacious.mail;' in the author element.
+ -->
+<personname>
+<firstname>George</firstname>
+<othername>N.</othername>
+<surname>Ugnacious</surname>
+</personname>
+<email>gnu at kde.org</email>
+</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<!-- Date of the documentation
+Change date if
+ docbook is updated and verified to be valid for the current app version
+ docbook is proofreaded and verified to be valid for the current app version
+Don't forget to include this last date.
+Please respect the format of the date (YYYY-MM-DD),it is used by scripts.
+-->
+<date>2015-04-03</date>
+
+<!--version information of Frameworks/Plasma/Applications this documentation is valid for.
+Example:
+Frameworks xx.yy for docbooks in frameworks
+Plasma xx.yy for docbooks in plasma workspace
+Applications xx.yy for docbooks released as Applications
+xx.yy (Applications xx.yy) for docbooks with own version released as Applications
+$applicationname xx.yy for applications with independent release schedule (extragear/playground)
+-->
+<releaseinfo>Frameworks xx.yy or Plasma xx.yy or Applications xx.yy or xx.yy (Applications xx.yy) or $applicationname xx.yy</releaseinfo>
+
+<keywordset>
+<keyword>KDE Applications</keyword>
+<keyword>foo</keyword>
+<keyword>bar</keyword>
+<keyword>baz</keyword>
+</keywordset>
+</articleinfo>
+
+<para>First para</para>
+
+<para>second para</para>
+
+</article>
diff --git a/src/man-template.docbook b/src/man-template.docbook
index 98b57f8..9cd6c32 100644
--- a/src/man-template.docbook
+++ b/src/man-template.docbook
@@ -3,6 +3,10 @@
<!ENTITY % English "INCLUDE">
]>
+<!--Rename this template to man-$applicationname.x.docbook,
+where x is the manual section, see https://en.wikipedia.org/wiki/Man_page#Manual_sections
+-->
+
<refentry lang="&language;">
<refentryinfo>
<!-- replace Foo with the application name-->
@@ -26,7 +30,7 @@ Example:
Frameworks xx.yy for docbooks in frameworks
Plasma xx.yy for docbooks in plasma
Applications xx.yy for docbooks released as Applications
-$applicationname xx.yy (Applications xx.yy) for docbooks with own version released as Applications
+xx.yy (Applications xx.yy) for docbooks with own version released as Applications
$applicationname xx.yy for applications with independent release schedule (extragear/playground)
-->
diff --git a/src/template.docbook b/src/template.docbook
index 3a22f5f..1fac7af 100644
--- a/src/template.docbook
+++ b/src/template.docbook
@@ -5,15 +5,27 @@
<!ENTITY kmyapplication "<application>KMyApp</application>">
<!ENTITY kappname "&kmyapplication;"><!-- replace kmyapplication here
do *not* replace kappname-->
+ <!ENTITY i18n-translatable-entity "<application>Translatable Entity</application>">
<!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 en/user.entities. -->
]>
-<!-- kdoctemplate v0.11.0 2015-04-03 lueck
+
+<!--
+Use this template for application docbooks
+For kioslave, systemsettings (kcontrol) modules and simple/short application docbooks use article-template.docbook
+Rename this template to index.docbook and place into the directory doc/ or doc/appname if you have several applications in one doc directory
+-->
+
+<!-- kdoctemplate v0.12.0 2016-04-23 lueck
+ add translatable entities
+ remove help.menu.documentation entity
+ and add some examples how to use the common menus Settings and Help
+
+ kdoctemplate v0.11.0 2015-04-03 lueck
updated instructions for date + releaseinfo
remove ENTITY package - not used anymore
add info about KDE Games special chapters
@@ -106,17 +118,17 @@ Change date if
Don't forget to include this last date.
Please respect the format of the date (YYYY-MM-DD),it is used by scripts.
-->
-<date>2015-04-03</date>
+<date>2016-04-23</date>
<!--version information of Frameworks/Plasma/Applications this documentation is valid for.
Example:
Frameworks xx.yy for docbooks in frameworks
Plasma xx.yy for docbooks in plasma workspace
Applications xx.yy for docbooks released as Applications
-$applicationname xx.yy (Applications xx.yy) for docbooks with own version released as Applications
+xx.yy (Applications xx.yy) for docbooks with own version released as Applications
$applicationname xx.yy for applications with independent release schedule (extragear/playground)
-->
-<releaseinfo>Frameworks xx.yy or Plasma xx.yy or Applications xx.yy or $applicationname xx.yy (Applications xx.yy) or $applicationname xx.yy</releaseinfo>
+<releaseinfo>Frameworks xx.yy or Plasma xx.yy or Applications xx.yy or xx.yy (Applications xx.yy) or $applicationname xx.yy</releaseinfo>
<!-- Abstract about this handbook -->
@@ -277,7 +289,8 @@ which will be expanded to:
</menuchoice></term>
<listitem><para><action>Creates a new document</action></para></listitem>
</varlistentry>
-<varlistentry>
+
+<varlistentry id="file-save">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
@@ -287,7 +300,8 @@ which will be expanded to:
</menuchoice></term>
<listitem><para><action>Saves the document</action></para></listitem>
</varlistentry>
-<varlistentry>
+
+<varlistentry id="file-quit">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
@@ -302,16 +316,40 @@ which will be expanded to:
</sect2>
-<sect2>
-<title>The Help Menu</title>
+<!-- Examples how to use the common menus Settings and Help -->
-<!-- Assuming you have a standard help menu (help, what's this, about -->
-<!-- &kmyapplication;, about KDE) then the documentation is already written. -->
-<!-- The following entity is valid anywhere that a variablelist is -->
-<!-- valid. -->
+<sect2 id="settings-help-menu">
+<title>The Settings and Help Menu</title>
+<para>
+&kmyapplication; has the common &kde; <guimenu>Settings</guimenu> and <guimenu>Help</guimenu>
+menu items, for more information read the sections about the <ulink url="help:/fundamentals/ui.html#menus-settings"
+>Settings Menu</ulink> and <ulink url="help:/fundamentals/ui.html#menus-help">Help Menu</ulink>
+of the &kde; Fundamentals.
+</para>
+</sect2>
+
+<sect2 id="help-menu1">
+<title>The Help Menu</title>
+<para>
+&kmyapplication; has the common &kde; <guimenu>Help</guimenu> menu item, for more information read the section
+about the <ulink url="help:/fundamentals/ui.html#menus-help">Help Menu</ulink> of the &kde; Fundamentals.
+</para>
+</sect2>
-&help.menu.documentation;
+<sect2 id="menu-commands">
+<title>Menu Items</title>
+<para>Apart from the common &kde; menus described in the <ulink url="help:/fundamentals/ui.html#menus">Menu</ulink>
+chapter of the &kde; Fundamentals documentation &kmyapplication; has these application specific menu entries:
+</para>
+<!-- variablelist -->
+</sect2>
+<sect2 id="help-menu2">
+<title>The Help Menu</title>
+<para>&kmyapplication; has a default &kde; <guimenu>Help</guimenu> menu as described in the
+<ulink url="help:/fundamentals/ui.html#menus-help">&kde; Fundamentals</ulink>
+with two additional entries:</para>
+<!-- variablelist -->
</sect2>
</sect1>
More information about the kde-doc-english
mailing list