Git commit e3490b55a04e89fc03c5d54ea75385cb538c978f by Matthieu Gallien. Committed on 12/02/2017 at 13:56. Pushed by mgallien into branch 'master'.
start Elisa handbook M +1 -0 CMakeLists.txt A +7 -0 doc/CMakeLists.txt A +416 -0 doc/index.docbook https://commits.kde.org/elisa/e3490b55a04e89fc03c5d54ea75385cb538c978f diff --git a/CMakeLists.txt b/CMakeLists.txt index 9b4a7d1..fbf1b04 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -46,6 +46,7 @@ configure_file(config-upnp-qt.h.cmake ${CMAKE_CURRENT_BINARY_DIR}/config-upnp-qt add_subdirectory(src) add_subdirectory(autotests) +add_subdirectory(doc) install( PROGRAMS org.kde.elisa.desktop diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt new file mode 100644 index 0000000..ba4a0a8 --- /dev/null +++ b/doc/CMakeLists.txt @@ -0,0 +1,7 @@ +# documentation + +KDOCTOOLS_CREATE_HANDBOOK( + index.docbook + INSTALL_DESTINATION ${KDE_INSTALL_DOCBUNDLEDIR}/en + SUBDIR elisa +) diff --git a/doc/index.docbook b/doc/index.docbook new file mode 100644 index 0000000..927fbad --- /dev/null +++ b/doc/index.docbook @@ -0,0 +1,416 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [ + <!ENTITY elisa "<application>Elisa</application>"> + <!ENTITY i18n-translatable-entity "<application>Elisa</application>"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> +<book id="elisa" lang="&language;"> + +<!-- This header contains all of the meta-information for the document such +as Authors, publish date, the abstract, and Keywords --> + +<bookinfo> +<title>The &elisa; Handbook</title> + +<authorgroup> +<author> +<personname> +<firstname>Matthieu</firstname> +<surname>Ugnacious</surname> +</personname> +<email>[email protected]</email> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2017</year> +<holder>Matthieu Gallien</holder> +</copyright> +<legalnotice>&FDLNotice;</legalnotice> + +<date>2017-02-11</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>Elisa 0.1</releaseinfo> + +<!-- Abstract about this handbook --> + +<abstract> +<para> +&elisa; is a music player designed to be simple to use. +</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdemultimedia</keyword> +<keyword>Elisa</keyword> +<keyword>audio</keyword> +<keyword>music</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para> +&elisa; is a music player designed to be simple to use. +</para> +</chapter> + +<chapter id="using-kapp"> +<title>Using &elisa;</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 &elisa;</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="screenshot.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot</phrase> + </textobject> + </mediaobject> +</screenshot> +</para> + + +<sect1 id="kapp-features"> +<title>More &elisa; 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> + <textobject> + <phrase>Squiggle</phrase> + </textobject> +</inlinemediaobject></guiicon> is used to draw squiggly lines all over +the &elisa; 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. + +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 &elisa; window</title> + +<sect2> +<title>The File Menu</title> +<para> +<variablelist> +<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> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>New</guimenuitem> +</menuchoice></term> +<listitem><para><action>Creates a new document</action></para></listitem> +</varlistentry> + +<varlistentry id="file-save"> +<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 id="file-quit"> +<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> &elisa;</para></listitem> +</varlistentry> +</variablelist> +</para> + +</sect2> + +<!-- Examples how to use the common menus Settings and Help --> + +<sect2 id="settings-help-menu"> +<title>The Settings and Help Menu</title> +<para> +&elisa; 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> +&elisa; 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> + +<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 &elisa; has these application specific menu entries: +</para> +<!-- variablelist --> +</sect2> + +<sect2 id="help-menu2"> +<title>The Help Menu</title> +<para>&elisa; 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> +</chapter> + +<chapter id="developers"> +<title>Developer's Guide to &elisa;</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 &elisa; plugins is a joy to behold. +</para> + + +</chapter> + +<chapter id="faq"> +<title>Questions and Answers</title> + +<!-- (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. --> + +<qandaset id="faqlist"> +<qandaentry> +<question> +<para>My Mouse doesn't work. How do I quit &elisa;?</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 I not 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> + +<chapter id="credits"> + +<!-- 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> + +<para> +&elisa; +</para> +<para> +Program copyright 2010-2014 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> + +<para> +Documentation Copyright © 2012-2014 George N. Ugnacious <email>[email protected]</email> +</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&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 Installation is optional, usually not required + +Entities &install.intro.documentation; + &install.compile.documentation; will be removed in later kdoctools + +--> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-kapp"> +<title>How to obtain &elisa;</title> + +<!-- This first entity contains boiler plate for applications that are +part of KDE archive. 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 or kf5 +.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 &elisa;, you need few libraries from +&kf5; 5.1 (bar, baz). Foobar.lib is +required in order to support the advanced &elisa; features. &elisa; 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 &elisa; itself can be found +on <ulink url="ftp://ftp.kapp.org";>The &elisa; 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 &elisa; 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; +-->
