diff options
Diffstat (limited to 'kdoctools/template.docbook')
| -rw-r--r-- | kdoctools/template.docbook | 630 |
1 files changed, 539 insertions, 91 deletions
diff --git a/kdoctools/template.docbook b/kdoctools/template.docbook index bda3c8e97..719379c1f 100644 --- a/kdoctools/template.docbook +++ b/kdoctools/template.docbook @@ -1,121 +1,569 @@ <?xml version="1.0" ?> -<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ -<!ENTITY % English "INCLUDE"> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!-- Define an entity for your application if it is not part of KDE + CVS --> + <!ENTITY kmyapplication "<application>KMyApp</application>"> + <!ENTITY kappname "&kmyapplication;"><!-- replace kmyapplication here + do *not* replace kappname--> + <!ENTITY package "kde-module"><!-- kdebase, kdeadmin, etc. Leave + this unchanged if your + application is not maintained in KDE CVS --> + <!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. --> ]> +<!-- 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 + Changed to Installation/Help menu entities 18 October 2001 + Other minor cleanup and changes 18 October 2001 + FPI change and minor changes November 2002 --> + +<!-- +This template was designed by: David Rugge [email protected] +with lots of help from: Eric Bischoff [email protected] +and Frederik Fouvry [email protected] +of the KDE DocBook team. + +You may freely use this template for writing any sort of KDE documentation. +If you have any changes or improvements, please let us know. + +Remember: +- in XML, the case of the <tags> and attributes is relevant ; +- also, quote all attributes. + +Please don't forget to remove all these comments in your final documentation, +thanks ;-). +--> + +<!-- ................................................................ --> + +<!-- The language must NOT be changed here. --> +<!-- If you are writing original documentation in a language other --> +<!-- than English, change the language above ONLY, not here --> +<book lang="&language;"> -<refentry lang="&language;"> -<refentryinfo> -<title>KDE User's Manual</title> -<author><personname> -<firstname><!-- --Your first name-- --></firstname> -<surname><!-- --Your last name-- --></surname> +<!-- This header contains all of the meta-information for the document such +as Authors, publish date, the abstract, and Keywords --> + +<bookinfo> +<title>The &kmyapplication; Handbook</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> -<affiliation><address><email><!-- --Your email address-- --></email></address></affiliation></author> -<date><!-- --Date when this manpage was written, in the ISO 8601 format -'yyyy-mm-dd'-- --></date> -<productname>K Desktop Environment</productname> -</refentryinfo> +<email>[email protected]</email> +</author> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +<copyright> +<year>2002</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>2003-01-10</date> +<releaseinfo>1.01.00</releaseinfo> + +<!-- Abstract about this handbook --> + +<abstract> +<para> +&kmyapplication; is an application specially designed to do nothing you would +ever want. +</para> +</abstract> + +<!-- This is a set of Keywords for indexing by search engines. +Please at least include KDE, the KDE package it is in, the name + of your application, and a few relevant keywords. --> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdeutils</keyword> +<keyword>Kapp</keyword> +<keyword>nothing</keyword> +<keyword>nothing else</keyword> +</keywordset> + +</bookinfo> + +<!-- The contents of the documentation begin here. Label +each chapter so with the id attribute. This is necessary for two reasons: it +allows you to easily reference the chapter from other chapters of your +document, and if there is no ID, the name of the generated HTML files will vary +from time to time making it hard to manage for maintainers and for the CVS +system. Any chapter labelled (OPTIONAL) may be left out at the author's +discretion. Other chapters should not be left out in order to maintain a +consistent documentation style across all KDE apps. --> + +<chapter id="introduction"> +<title>Introduction</title> + +<!-- The introduction chapter contains a brief introduction for the +application that explains what it does and where to report +problems. Basically a long version of the abstract. Don't include a +revision history. (see installation appendix comment) --> + +<para> +&kmyapplication; is a program that lets you do absolutely nothing. Please report +any problems or feature requests to the &kde; mailing lists. +</para> +</chapter> + +<chapter id="using-kapp"> +<title>Using &kmyapplication;</title> + +<!-- This chapter should tell the user how to use your app. You should use as +many sections (Chapter, Sect1, Sect3, etc...) as is necessary to fully document +your application. --> + +<para> + +<!-- Note that all graphics should be in .png format. Use no gifs because of +patent issues. --> +<screenshot> +<screeninfo>Here's a screenshot of &kmyapplication;</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="screenshot.png" format="PNG"/> + </imageobject> + <imageobject> + <imagedata fileref="screenshot.eps" format="EPS"/> + </imageobject> + <textobject> + <phrase>Screenshot</phrase> + </textobject> + </mediaobject> +</screenshot> +</para> + + +<sect1 id="kapp-features"> +<title>More &kmyapplication; features</title> + +<para>It slices! It dices! and it comes with a free toaster!</para> +<para> +The Squiggle Tool <guiicon><inlinemediaobject> + <imageobject> + <imagedata fileref="squiggle.png" format="PNG"/> + </imageobject> + <imageobject> + <imagedata fileref="squiggle.eps" format="EPS"/> + </imageobject> + <textobject> + <phrase>Squiggle</phrase> + </textobject> +</inlinemediaobject></guiicon> is used to draw squiggly lines all over +the &kmyapplication; main window. It's not a bug, it's a feature! +</para> + +</sect1> +</chapter> + +<chapter id="commands"> +<title>Command Reference</title> + +<!-- (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. --> + +<sect1 id="kapp-mainwindow"> +<title>The main &kmyapplication; window</title> + +<sect2> +<title>The File Menu</title> +<para> +<variablelist> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>New</guimenuitem> +</menuchoice></term> +<listitem><para><action>Creates a new document</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Save</guimenuitem> +</menuchoice></term> +<listitem><para><action>Saves the document</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Quit</guimenuitem> +</menuchoice></term> +<listitem><para><action>Quits</action> &kmyapplication;</para></listitem> +</varlistentry> +</variablelist> +</para> + +</sect2> + +<sect2> +<title>The <guimenu>Help</guimenu> Menu</title> + +<!-- 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. --> + +&help.menu.documentation; + +</sect2> + +</sect1> +</chapter> + +<chapter id="developers"> +<title>Developer's Guide to &kmyapplication;</title> + +<!-- (OPTIONAL) A Programming/Scripting reference chapter should be +used for apps that use plugins or that provide their own scripting hooks +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! +</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><command><!-- --The command this page is about-- --></command></refentrytitle> -<manvolnum><!-- --The section this page should be in-- --></manvolnum> +<refentrytitle>XtUnmanageChildren</refentrytitle> +<refmiscinfo>Xt - Geometry Management</refmiscinfo> </refmeta> - <refnamediv> -<refname><command><!-- --The command this page is about-- --></command></refname> -<refpurpose><!-- --Very brief description, suitable for 'whatis'-- --></refpurpose> -</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> -<cmdsynopsis> -<command><!-- --The command this page is about-- --></command> -<arg choice="req"><!-- --Required command specific options-- --></arg> -<arg choice="opt"><!-- --Optional command specific options-- --></arg> -<arg choice="opt">KDE Generic Options</arg> -<arg choice="opt">Qt Generic Options</arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1> -<title>Description</title> -<para><!-- --Description of the app, what it's for, what it does and doesn't -do.-- --> </para> - -</refsect1> +<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> -<refsect1> -<title>Options</title> -<para>App options, in a variablelist</para> +<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> -<!-- --The Following sections are optional, but recommended if they are -applicable.-- --> +<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> -<title>Environment</title> -<para><!-- --Environment variablesars that affect this command, how to set -them, who sets them, how they affect it, probably in a variablelist. Only for -man sections 1, 6, 7 and 8-- --></para> +<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> -<title>Files</title> -<para><!-- --Files used by this command (eg, rc files, locations of caches -etc.) who puts them there, how they are configured, and if it's safe -to remove them, probably in a variablelist.-- --></para> +<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> -<refsect1> -<title>See Also</title> -<para><!-- --foo(1)-style references, use a simplelist for these-- --></para> +</chapter> -<para>More detailed user documentation is available from <ulink -url="help:/<!-- --commandname-- -->">help:/<!-- --command-- --></ulink> -(either enter this <acronym>URL</acronym> into &konqueror;, or run -<userinput><command>khelpcenter</command> -<parameter>help:/<!-- --command-- --></parameter></userinput>).</para> +<chapter id="faq"> +<title>Questions and Answers</title> -<para>There is also further information available at <!-- --link to -website if applicable-- --></para> -</refsect1> +<!-- (OPTIONAL but recommended) This chapter should include all of the silly +(and not-so-silly) newbie questions that fill up your mailbox. This chapter +should be reserved for BRIEF questions and answers! If one question uses more +than a page or so then it should probably be part of the +"Using this Application" chapter instead. You should use links to +cross-reference questions to the parts of your documentation that answer them. +This is also a great place to provide pointers to other FAQ's if your users +must do some complicated configuration on other programs in order for your +application work. --> -<refsect1> -<title>Examples</title> -<para><!-- -- Give examples on how to use the program with different parameters -here, don't forget to explain what each invocation does exactly. Be verbose, -many users find this the most useful part of the documentation! -- --></para> -</refsect1> +&reporting.bugs; +&updating.documentation; -<refsect1> -<title>Standards</title> +<qandaset id="faqlist"> +<qandaentry> +<question> +<para>My Mouse doesn't work. How do I quit &kmyapplication;?</para> +</question> +<answer> +<para>You silly goose! Check out the <link linkend="commands">Commands +Section</link> for the answer.</para> +</answer> +</qandaentry> +<qandaentry> +<question> +<para>Why can't I twiddle my documents?</para> +</question> +<answer> +<para>You can only twiddle your documents if you have the foobar.lib +installed.</para> +</answer> +</qandaentry> +</qandaset> +</chapter> -<para><!-- --If the app adheres to any particular standards or RFC's, note -them here.-- --> </para> -</refsect1> +<chapter id="credits"> -<refsect1> -<title>History</title> -<para><!-- --Programs derived from other sources sometimes have this, or you -might keep a modification log here. If the log gets overly long or detailed, -consider maintaining it in a separate file, though.-- --> -</refsect1> +<!-- Include credits for the programmers, documentation writers, and +contributors here. The license for your software should then be included below +the credits with a reference to the appropriate license file included in the KDE +distribution. --> + +<title>Credits and License</title> -<refsect1> -<title>Bugs</title> -<para><!-- --Things that cause specific errors, so that people may avoid it, -or at least will be prepared for it.-- --> +<para> +&kmyapplication; +</para> +<para> +Program copyright 1997 John Q. Hacker <email>[email protected]</email> +</para> +<para> +Contributors: +<itemizedlist> +<listitem><para>Konqui the KDE Dragon <email>[email protected]</email></para> +</listitem> +<listitem><para>Tux the Linux Penguin <email>[email protected]</email></para> +</listitem> +</itemizedlist> </para> -</refsect1> -<refsect1> -<title>Restrictions</title> -<para><!-- --Bugs you don't plan to fix. :-)-- --></para> -</refsect1> +<para> +Documentation Copyright © 1999 George N. Ugnacious <email>[email protected]</email> +</para> -<refsect1> -<title>Authors</title> -<para><!-- --Author information of the developer and man page writer.-- --></para> -</refsect1> +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> -</refentry> +&underFDL; <!-- FDL: do not remove --> + +<!-- Determine which license your application is licensed under, + and delete all the remaining licenses below: + + (NOTE: All documentation are licensed under the FDL, + regardless of what license the application uses) --> + +&underGPL; <!-- GPL License --> +&underBSDLicense; <!-- BSD License --> +&underArtisticLicense; <!-- BSD Artistic License --> +&underX11License; <!-- X11 License --> + +</chapter> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-kapp"> +<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 +application --> + +&install.intro.documentation; + +</sect1> + +<sect1 id="requirements"> +<title>Requirements</title> + +<!-- +List any special requirements for your application here. This should include: +.Libraries or other software that is not included in kdesupport, +kdelibs, or kdebase. +.Hardware requirements like amount of RAM, disk space, graphics card +capabilities, screen resolution, special expansion cards, etc. +.Operating systems the app will run on. If your app is designed only for a +specific OS, (you wrote a graphical LILO configurator for example) put this +information here. +--> + +<para> +In order to successfully use &kmyapplication;, you need &kde; 1.1. 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. +</para> + +<para> +All required libraries as well as &kmyapplication; itself can be found +on <ulink url="ftp://ftp.kapp.org">The &kmyapplication; home page</ulink>. +</para> + +<!-- For a list of updates, you may refer to the application web site +or the ChangeLog file, or ... --> +<para> +You can find a list of changes at <ulink +url="http://apps.kde.org/kapp">http://apps.kde.org/kapp</ulink>. +</para> +</sect1> + +<sect1 id="compilation"> +<title>Compilation and Installation</title> + +<!-- This entity contains the boilerplate text for standard --> +<!-- compilation instructions. If your application requires any --> +<!-- special handling, remove it, and replace with your own text. --> + +&install.compile.documentation; + +</sect1> + +<sect1 id="configuration"> +<title>Configuration</title> + +<para>Don't forget to tell your system to start the <filename>dtd</filename> +dicer-toaster daemon first, or &kmyapplication; won't work !</para> + +</sect1> + +</appendix> + +&documentation.index; +</book> + +<!-- +Local Variables: +mode: xml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +End: + +vim:tabstop=2:shiftwidth=2:expandtab +kate: space-indent on; indent-width 2; tab-width 2; indent-mode none; +--> |