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>[email protected]</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>[email protected]</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> _______________________________________________ kde-doc-english mailing list [email protected] https://mail.kde.org/mailman/listinfo/kde-doc-english
