Git commit d425295c7e127ad5dc09aae299ade55348ddcb58 by Thomas Eschenbacher. Committed on 28/02/2017 at 22:04. Pushed by eschenbacher into branch 'master'.
doc: split off developer sections from handbook into seperate file to reduce load of translators. new make target "html_doc_devel" (included in "apidoc") M +3 -0 CHANGES M +4 -2 CMakeLists.txt M +24 -0 doc/CMakeLists.txt A +776 -0 doc/devel.docbook M +7 -703 doc/en/index.docbook M +1 -1 doxy.cfg.in https://commits.kde.org/kwave/d425295c7e127ad5dc09aae299ade55348ddcb58 diff --git a/CHANGES b/CHANGES index a896affd..21aa155b 100644 --- a/CHANGES +++ b/CHANGES @@ -45,6 +45,9 @@ * renamed command "edit_label" -> "label:edit" * implemented loading and saving of labels * allow special value -1 as index for label:delete(...) to delete _all_ labels + * doc: split off developer sections from handbook into seperate file, to + reduce load of translators. new make target "html_doc_devel" + (included in "apidoc") 0.9.2 [2016-06-26] diff --git a/CMakeLists.txt b/CMakeLists.txt index 01c013a6..4f421346 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -421,7 +421,7 @@ FIND_PROGRAM(DOXYGEN_EXECUTABLE doxygen) IF (DOXYGEN_EXECUTABLE AND RM_EXECUTABLE) SET(DOXYFILE ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile) - SET(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/apidoc) + SET(DOXYGEN_OUTPUT_DIR ${CMAKE_BINARY_DIR}/doc/api) SET(DOXYGEN_LOGFILE ${CMAKE_CURRENT_BINARY_DIR}/doxygen.log) MESSAGE(STATUS "Found doxygen: ${DOXYGEN_EXECUTABLE}") @@ -433,7 +433,9 @@ IF (DOXYGEN_EXECUTABLE AND RM_EXECUTABLE) ) ADD_CUSTOM_TARGET(apidoc - COMMAND "${RM_EXECUTABLE}" -R -f "${CMAKE_CURRENT_BINARY_DIR}/html" + DEPENDS html_doc_devel + COMMAND "${RM_EXECUTABLE}" -R -f "${CMAKE_BINARY_DIR}/doc/api" + COMMAND "${CMAKE_COMMAND}" -E make_directory "${CMAKE_BINARY_DIR}/doc/api" COMMAND "${DOXYGEN_EXECUTABLE}" "${DOXYFILE}" COMMAND "${CAT_EXECUTABLE}" "${DOXYGEN_LOGFILE}" DEPENDS ${DOXYFILE} diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 4dd89eab..37a3626e 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -163,4 +163,28 @@ FOREACH(_file ${_files}) ENDFOREACH(_file ${_files}) ############################################################################# +### "make html_doc_devel" ### + +SET(_common_en_dir ${CMAKE_INSTALL_PREFIX}/${HTML_INSTALL_DIR}/en/kdoctools5-common) +SET(_html_dir_devel ${CMAKE_CURRENT_BINARY_DIR}/devel) +GET_TARGET_PROPERTY(MEINPROC_EXECUTABLE ${KDOCTOOLS_MEINPROC_EXECUTABLE} LOCATION) + +ADD_CUSTOM_TARGET(html_doc_devel + COMMENT "Generating HTML developer documentation" + DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/devel.docbook + # start with an empty output (_html_dir) + COMMAND ${CMAKE_COMMAND} -E remove_directory ${_html_dir_devel} + COMMAND ${CMAKE_COMMAND} -E make_directory ${_html_dir_devel} + # create the HTML pages from docbook + COMMAND cd ${_html_dir_devel} && ${MEINPROC_EXECUTABLE} + --check ${CMAKE_CURRENT_SOURCE_DIR}/devel.docbook + # copy files for the "common" directory + COMMAND ${CMAKE_COMMAND} -E make_directory ${_html_dir_devel}/common + COMMAND ${CP_EXECUTABLE} -n ${_common_en_dir}/* ${_html_dir_devel}/common/ + # fix wrong paths in the HTML pages + COMMAND cd ${_html_dir_devel} && ${CMAKE_SOURCE_DIR}/doc/fix-common + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} +) + +############################################################################# ############################################################################# diff --git a/doc/devel.docbook b/doc/devel.docbook new file mode 100644 index 00000000..84612841 --- /dev/null +++ b/doc/devel.docbook @@ -0,0 +1,776 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [ + <!ENTITY kwave "<application>Kwave</application>"> + <!ENTITY % English "INCLUDE"> <!-- change language only here --> + <!ENTITY % addindex "IGNORE"> + <!ENTITY version "0.9.3"> + <!ENTITY version_tag "0_9_3"> + <!ENTITY version_year "2017"> + <!ENTITY % ents PUBLIC "-//KDE//ENTITIES Application-Variable Entities V2.0//EN" "entities/kde-prologue.entities"> + <!ENTITY url_git_web_kde "http://commits.kde.org/kwave";> + <!ENTITY url_prefix_gitweb "&url_git_web_kde;?path="> + <!ENTITY url_cmake "http://www.cmake.org";> + <!ENTITY url_download "http://kwave.sourceforge.net/download.html";> + <!ENTITY url_doxygen "http://www.stack.nl/~dimitri/doxygen";> + <!ENTITY url_homepage "http://kwave.sourceforge.net/";> + <!ENTITY url_kde_project "http://www.kde.org/applications/multimedia/kwave/";> + <!ENTITY url_mailinglist "https://lists.sourceforge.net/lists/listinfo/kwave-devel";> + <!ENTITY url_readme "&url_prefix_gitweb;README"> + <!ENTITY url_sourceforge "http://sourceforge.net";> + <!ENTITY url_git_web_sf "http://sourceforge.net/p/kwave/code/commit_browser";> + <!ENTITY url_git_list_tags "http://commits.kde.org/kwave.git/refs/";> + <!ENTITY url_git_master "git://anongit.kde.org/kwave.git"> +]> + +<book lang="&language;"> + +<bookinfo> + <title>The &kwave; Developer Handbook</title> + + <authorgroup> + <author> + <firstname>Thomas</firstname> + <surname>Eschenbacher</surname> + <affiliation> + <address><email>[email protected]</email></address> + </affiliation> + </author> + + <!-- TRANS:ROLES_OF_TRANSLATORS --> + + </authorgroup> + + <copyright><year>1998-2000</year><holder>Martin Wilz</holder></copyright> + <copyright><year>&version_year;</year><holder>Thomas Eschenbacher</holder></copyright> + + <legalnotice>&FDLNotice;</legalnotice> + + <date>2017-01-29</date> + <releaseinfo>0.9.3 (Applications 16.12)</releaseinfo> + + <abstract><para>&kwave; is a simple sound editor built on &kf5-full;.</para></abstract> + + <keywordset> + <keyword>KDE</keyword> + <keyword>KF5</keyword> + <keyword>multimedia</keyword> + <keyword>sound</keyword> + <keyword>audio</keyword> + <keyword>Kwave</keyword> + <keyword>wav</keyword> + <keyword>editor</keyword> + <keyword>record</keyword> + <keyword>playback</keyword> + <keyword>sonagram</keyword> + <keyword>FFT</keyword> + <keyword>Linux</keyword> + </keywordset> +</bookinfo> + +<!-- ###################################################################### --> +<!-- ### Chapter: Installation ### --> +<!-- ###################################################################### --> + +<chapter id="installation"><title>Installation</title> + &underFDL; + &underGPL; + +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<!-- +++ Section: Getting Kwave +++ --> +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + + <sect1 id="getting"><title>How to obtain &kwave;</title> + + <para> + &kwave; has an own homepage under + <ulink url="&url_homepage;">&url_homepage;</ulink>. Here you can + find further information about the project, as well as + information about current stable and up-to-date development + versions. + </para> + <para> + There also is a KDE project page + at <ulink url="&url_kde_project;">&url_kde_project;</ulink> which + shows a short summary of the application. + </para> + + <para> + If you want to get a &kwave; release, you have the choice to visit + <ulink url="&url_download;">&url_download;</ulink> and + <itemizedlist> + <listitem><para> + download a binary package of the latest stable version, if + there is one for your distribution, + </para></listitem> + <listitem><para> + download a source RPM package of the latest stable version, + </para></listitem> + <listitem><para> + compile on your own, from a .tar.bz2 archive with the source code + of the latest stable version, + </para></listitem> + <listitem><para> + compile on your own, from the latest GIT source. + </para></listitem> + </itemizedlist> + </para> + + <para> + Don't be afraid, compiling Kwave should be quite simple even if + you are not a software developer. It just needs some developer + packages to be installed and some time. + </para> + + </sect1> + +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<!-- +++ Section: Requirements +++ --> +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + + <sect1 id="requirements"><title>Requirements</title> + + <para> + In order to successfully use &kwave;, you need: + <itemizedlist> + <listitem><para> + a computer running Linux (&kwave; might also run under + some other operating system, but we have never tested + this, please let us know if you get it working under + some other platform / operating system) + </para></listitem> + <listitem><para> + working sound playback (not really required for using but + what would you do with a sound editor if you cannot + <emphasis>hear</emphasis> the result of your work?) + </para></listitem> + <listitem><para> + KDE Frameworks 5.2 (KF5) or higher (at least the libraries, + if you are using a different desktop, you can also run &kwave; + if the proper libraries are installed). + </para></listitem> + <listitem><para> + Qt-5.4 or higher (normally comes as a dependency of KF5) + </para></listitem> + <listitem><para> + ALSA 1.0.14 or higher (for record/playback) + </para></listitem> + <listitem><para> + PulseAudio 4.0 or higher (for record/playback) + </para></listitem> + <listitem><para> + id3lib-3.8.1 or higher (for ID3 tags) + </para></listitem> + <listitem><para> + mad-0.15 or higher (optionally for MP3 import/export) + </para></listitem> + <listitem><para> + flac-1.2.0 or higher (for FLAC import/export) + </para></listitem> + <listitem><para> + libsamplerate-0.1.3 or higher (sample rate conversion) + </para></listitem> + </itemizedlist> + </para> + + <para> + For a more complete and up-to-date list, please consult the + <ulink url="&url_readme;">'README'</ulink> file that is included + in the source distribution. + This file also contains some special hints for getting &kwave; running and/or + building &kwave; under some distributions. + </para> + + <para> + If you intend to compile &kwave; from the sources, you will need at least: + <itemizedlist> + <listitem><para> + <ulink url="&url_cmake;">cmake</ulink>-2.8.12 or newer + </para></listitem> + <listitem><para> + A recent C/C++ compiler. GCC-4.x works fine, some older and any + newer version (like gcc-5.0) should work too. + </para></listitem> + <listitem><para> + The glibc2 (libc-6) development environment. On SuSE systems + the package is called "libc", on other systems it might be + called "libc-devel". + </para></listitem> + <listitem><para> + Qt5 and KF5 development packages + </para></listitem> + <listitem><para> + pulseaudio-0.9.16 or newer + </para></listitem> + <listitem><para> + id3lib-devel-3.8.1 or newer + </para></listitem> + <listitem><para> + fftw-3.0 or newer + </para></listitem> + <listitem><para> + mad-devel-0.15 or newer + (if you have the permission to use MP3 code) + </para></listitem> + <listitem><para> + flac-devel-1.2.0 newer + </para></listitem> + <listitem><para> + If you intend to get the &kwave; sources via GIT, you will also + need a current git package. + </para></listitem> + <listitem><para> + ...many other packages, please take a look at the + <ulink url="&url_readme;">'README'</ulink> file included in + the source package. + </para></listitem> + </itemizedlist> + </para> + + </sect1> + +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<!-- +++ Section: Manual Compilation +++ --> +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + + <sect1 id="manual_compilation"><title>Manual Compilation and installation</title> + + <para> + Since version 0.7.10 &kwave; uses + <ulink url="&url_cmake;">cmake</ulink>, a make system + that is also used by KDE itself. So if you know how to build other KDE + applications, you should not have any difficulties in building &kwave;. + If you run into problems please report them to + the &kwave; <ulink url="&url_mailinglist;">mailing list</ulink>. + </para> + + <para> + In order to compile and install &kwave; on your system, it is best + practice to do a <emphasis>out-of-tree</emphasis> build. This means + that you hold the sources of &kwave; in one directory and build the + package in another (temporary) directory. + </para> + + <para> + For example, assuming that your sources are already + unpacked in <filename><replaceable>$HOME/src/kwave-&version;</replaceable></filename>, you + can do the following: +<screen width="50" format="linespecific"> +<prompt>% </prompt><command>mkdir /tmp/kwave-build</command> +<prompt>% </prompt><command>cd /tmp/kwave-build</command> +<prompt>% </prompt><command>cmake <replaceable>$HOME/src/kwave-&version;</replaceable> <replaceable>[build options]</replaceable></command> +<prompt>% </prompt><command>make</command> +<prompt>% </prompt><command>su root -c "make install"</command> +</screen> + (Specifying build options is a way to enable or disable specific features. + See the following section for descriptions) + </para> + + </sect1> + +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<!-- +++ Section: Build options +++ --> +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + + <sect1 id="build_options"><title>Build options</title> + + <para> + By specifying build options, you can enable or disable some features + of &kwave;, like excluding some components or plugins from the + generated package. Here is a list of the available options: + + <itemizedlist> + <listitem><para> + <literal>WITH_ALSA</literal> + enable playback/recording via ALSA + [<literal>on</literal>/<literal>off</literal>, + default=<literal>on</literal>] + </para></listitem> + <listitem id="CMAKE_WITH_DEBUG"><para> + <literal>WITH_DEBUG</literal> + build a debug version + [<literal>on</literal>/<literal>off</literal>, + default=<literal>off</literal>] + </para></listitem> + <listitem><para> + <literal>WITH_DOC</literal> + build online documentation + [<literal>on</literal>/<literal>off</literal>, + default=<literal>on</literal>] + </para></listitem> + <listitem><para> + <literal>WITH_FLAC</literal> + enable support for FLAC files + [<literal>on</literal>/<literal>off</literal>, + default=<literal>on</literal>] + </para></listitem> + <listitem><para> + <literal>WITH_MP3</literal> + enable support for mp3 files + [<literal>on</literal>/<literal>off</literal>, + default=<literal>off</literal>] + Please note that you need the permission to use code + covered by the MP3 software patents! + </para></listitem> + <listitem><para> + <literal>WITH_OGG_OPUS</literal> + enable support for Ogg/Opus files + [<literal>on</literal>/<literal>off</literal>, + default=<literal>on</literal>] + </para></listitem> + <listitem><para> + <literal>WITH_OGG_VORBIS</literal> + enable support for Ogg/Vorbis files + [<literal>on</literal>/<literal>off</literal>, + default=<literal>on</literal>] + </para></listitem> + <listitem><para> + <literal>WITH_OPTIMIZED_MEMCPY</literal> + use an optimized version of memcpy, available for + X86, X86_64 and PPC platforms + [<literal>on</literal>/<literal>off</literal>, + default=<literal>on</literal>] + </para></listitem> + <listitem><para> + <literal>WITH_OSS</literal> + enable playback/recording via OSS + [<literal>on</literal>/<literal>off</literal>, + default=<literal>on</literal>] + </para></listitem> + <listitem><para> + <literal>WITH_PULSEAUDIO</literal> + enable playback/recording via PulseAudio + [<literal>on</literal>/<literal>off</literal>, + default=<literal>on</literal>] + </para></listitem> + <listitem><para> + <literal>WITH_QT_AUDIO</literal> + enable playback via Qt Multimedia + [<literal>on</literal>/<literal>off</literal>, + default=<literal>on</literal>] + </para></listitem> + </itemizedlist> + </para> + + <para> + These options can be passed to <literal><command>cmake</command></literal> + with <command><literal>-D</literal><replaceable>option</replaceable><literal>=</literal><replaceable>value</replaceable></command>. + For example, if you want to enable MP3 support, + you can pass the corresponding option as follows: +<screen width="70" format="linespecific"> +<prompt>% </prompt><command>cmake <replaceable>[source directory]</replaceable> -DWITH_MP3=ON <replaceable>[other options...]</replaceable></command> +</screen> + </para> + </sect1> + +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<!-- +++ Section: Building RPM packages from tar.bz2 archives +++ --> +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + + <sect1 id="building_rpm_from_tarbz2"> + <title>Building RPM packages from tar.bz2 archives</title> + + <sect2 id="building_with_rpm_ta"> + <title>With working rpmbuild -ta</title> + + <para> + If you are running a system with RPM support, the preferred way to + install &kwave; on your system will be the creation of a nice RPM + package. First you should get the current source of &kwave;, either + as a tar.bz2 archive from the &kwave; download page or + check out an up-to-date copy via the GIT repository hosted on KDE + servers, or the mirror repository hosted by + <ulink url="&url_sourceforge;">SourceForge</ulink> where + you can get the sources of the latest development version. + </para> + <para> + For instructions on how to get access to the repository, read + in the chapter about + <link linkend="building_rpm_from_git">building from git</link>. + + There also is a GIT web interface on <ulink url="&url_git_web_kde;">KDE</ulink> + and on <ulink url="&url_git_web_sf;">SourceForge</ulink> where + you can use to browse through the sources. + </para> + + <para> + If you have downloaded tar.bz2 archives of &kwave;, + create and install the RPMs just by doing the following steps + (where <replaceable>[arch]</replaceable> stands for the platform you + have built the package and might be something like + <literal>i586</literal>, <literal>i686</literal>, + <literal>sparc</literal> or whatever, + <replaceable>XXX</replaceable> stands for the version number + you have downloaded). + </para> + + <para> + To build the &kwave; package and install it do: +<screen width="70" format="linespecific"> +<prompt>% </prompt><command>rpmbuild -ta <replaceable>kwave-XXX.tar.bz2</replaceable></command> +<prompt>% </prompt><command>rpm -i <replaceable>/usr/src/redhat/RPMS/[arch]/kwave-XXX.[arch].rpm</replaceable></command> +</screen> + </para> + + <note><para> + <emphasis>Note for SuSE users: </emphasis> + you have to specify the directory + <filename>/usr/src/packages</filename> instead + of <filename>/usr/src/redhat</filename> ! + </para></note> + + <para> + If you haven't seen any errors, then that's it and you can skip the + rest of this chapter. If rpm was unable to build the packages + and says something like "spec file not found", then go on and + read the rest of this section. + </para> + + </sect2> + + <sect2 id="rpm_build_with_broken_rpm"> + <title>With broken rpmbuild -ta support</title> + + <para><anchor id="manual_rpm_creation"/> + If you cannot get <command>rpmbuild -ta</command> working, here are + the steps for making that manually (the hard way): + </para> + + <orderedlist> + <listitem><para> + Go to your RPM "topdir". This normally + is <filename>/usr/src/redhat</filename> + for the redhat distribution + or <filename>/usr/src/packages</filename> if you + have the SuSE distribution. +<screen width="70" format="linespecific"> +<prompt>% </prompt><command>cd /usr/src/<replaceable>redhat</replaceable></command> +</screen> + </para></listitem> + + <listitem><para> + Put the tar.bz2 archive into the SOURCES subdirectory (you + have to replace "somewhere" with the real directory where + the files are, of course). +<screen width="70" format="linespecific"> +<prompt>% </prompt><command>cp <replaceable>/somewhere/kwave-XXX.tar.bz2</replaceable> SOURCES</command> +</screen> + </para></listitem> + + <listitem><para> + Extract the spec file from the archives and put it into + the SPEC subdirectory. +<screen width="70" format="linespecific"> +<prompt>% </prompt><command>tar -xOjf SOURCES/<replaceable>kwave-XXX.tar.bz2</replaceable> \*.spec > SPECS/kwave.spec</command> +</screen> + </para></listitem> + + <listitem><para> + Let rpm do the compile job and generate the rpm of &kwave;. + If you only want to make a binary package, you + can specify <literal>-bb</literal> instead of + <literal>-ba</literal>, or just <literal>-bs</literal> to build + only a source package. +<screen width="70" format="linespecific"> +<prompt>% </prompt><command>rpmbuild -ba SPECS/kwave.spec</command> +</screen> + </para></listitem> + + <listitem><para> + If everything was ok, you can install the binary rpm of + &kwave;, it will be in the BUILD directory. + If you already have a version of &kwave; installed, + please remove it first or use the parameter + <literal>-U</literal> instead + of <literal>-i</literal> for upgrading instead of installing. +<screen width="70" format="linespecific"> +<prompt>% </prompt><command>rpm -ivh BUILD/<replaceable>[arch]/kwave-XXX.[arch].rpm</replaceable></command> +</screen> + </para></listitem> + + </orderedlist> + + </sect2> + </sect1> + +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<!-- +++ Section: Building RPM packages from GIT +++ --> +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + + <sect1 id="building_rpm_from_git"> + <title>Building RPM packages from GIT</title> + + <sect2 id="git_checkout"><title>Checking out the sources</title> + + <para> + For initially checking out the sources you will need some disk space + (about 25 megabytes) in a directory of your choice, the git package + of your favorite distribution and full access to the Internet. If you + get error messages about rejected connections you either have typed + something wrong or your provider doesn't give you full access. + A good place for the source files will be <filename>"$HOME/src"</filename>. + </para> + + <orderedlist> + <listitem><para> + First create the directory that will receive the subdirectory with + &kwave; sources and change into it: +<screen width="40" format="linespecific"> +<prompt>% </prompt><command>mkdir -p <replaceable>$HOME/src</replaceable></command> +<prompt>% </prompt><command>cd <replaceable>$HOME/src</replaceable></command> +</screen> + </para></listitem> + <listitem> + <para> + Then check out the latest sources from the GIT server: +<screen width="70" format="linespecific"> +<prompt>% </prompt><command>git clone &url_git_master; kwave</command> +</screen> + </para> + <para> + or you can check out a specific release with the following commands: +<screen width="70" format="linespecific"> + <prompt>% </prompt><command>git clone &url_git_master; kwave</command> + <prompt>% </prompt><command>cd kwave</command> + <prompt>% </prompt><command>git checkout tags/<replaceable>[release-tag]</replaceable> </command> +</screen> + You can look up the names of the release tags in the git web page at + <ulink url="&url_git_list_tags;"> &url_git_list_tags;</ulink>. + The release tags are always built out of the word <literal>Release-</literal> and + the version number of the release, with underscores instead of dots. + For example "<literal>Release-&version_tag;</literal>" for v&version;. + </para> + </listitem> + </orderedlist> + + <warning><para> + There <emphasis>must not</emphasis> be a directory named + <filename>kwave</filename> under + the directory you want to check out. Otherwise the git program will + complain about already existing files and the checkout will + not work. + </para></warning> + + </sect2> + + <sect2 id="git_update"><title>Updating fresh sources from GIT</title> + <para> + The procedure described in the previous section is only necessary + once. For further updates it is much easier. Just change into the + directory where you have the checked out sources and do the following + to update to the latest version: +<screen width="40" format="linespecific"> +<prompt>% </prompt><command>git pull</command> +</screen> + Then go on to the next section and compile as usual. + </para> + <note><para> + If you think that you have messed up your local source tree or if there + are conflicts during updating and you want to start through from a clean + state, you can do the following to discard all local changes and switch + back to the latest version from the master branch: +<screen width="40" format="linespecific"> +<prompt>% </prompt><command>git clean --force -d</command> +<prompt>% </prompt><command>git reset --hard</command> +<prompt>% </prompt><command>git checkout <replaceable>master</replaceable></command> +</screen> + </para></note> + </sect2> + + <sect2 id="git_compiling"><title>Compiling</title> + <para> + Building rpm package from a GIT snapshot is quite simple. The procedure + is nearly the same as described in the last section, so it unhappily also + has the same problem with the <command>rpmbuild -ta</command> command + our method internally uses. + Like in the previous chapter, <replaceable>[arch]</replaceable> stands + for the platform you have built the package and might be something + like <literal>i386</literal>, <literal>i586</literal>, + <literal>sparc</literal> or whatever, + <replaceable>XXX</replaceable> stands + for the version number you have checked out. + </para> + + <note><para> + <emphasis>Note for SuSE users: </emphasis> + here you have to specify the directory + <filename>/usr/src/packages</filename> instead + of <filename>/usr/src/redhat</filename> too! + </para></note> + + <para> + Assuming that + you are in the root of where you checked out from GIT, do the + following to create a Makefile, the &kwave; package and + install it. If you already have a version of &kwave; installed, + please remove it first or use <command>rpm -U</command> instead + of <command>rpm -i</command> for updating instead of installing. +<screen width="70" format="linespecific"> +<prompt>% </prompt><command>mkdir /tmp/kwave-build</command> +<prompt>% </prompt><command>cd /tmp/kwave-build</command> +<prompt>% </prompt><command>cmake <replaceable>$HOME/src/kwave</replaceable></command> +<prompt>% </prompt><command>make rpm</command> +<prompt>% </prompt><command>rpm -ivh /usr/src/redhat/BUILD/<replaceable>[arch]/kwave-XXX.[arch].rpm</replaceable></command> +</screen> + </para> + + <note><para> + If you still have problems with <command>make rpm</command>, + you will find the tar.bz2 + archive that was produced in <filename>/tmp</filename>. + Please follow the instructions in the + <link linkend="manual_rpm_creation">previous</link> chapter. + </para></note> + + </sect2> + </sect1> + +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<!-- +++ Section: Building DEB package from Source +++ --> +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + + <sect1 id="building_deb_from_src"> + <title>Building a DEB package for testing and personal use</title> + + <para> + If you want to create a deb package of &kwave;, ⪚ for testing a + version that is not yet available via official package repositories, + then you can create your own package quite easily. First of all, you + need to install some required tools: +<screen width="70" format="linespecific"> +<prompt>% </prompt><command>sudo apt-get install build-essential checkinstall</command> +</screen> + </para> + + <para> + Then you can install the required build dependencies by pretending to + install the dependencies of the official &kwave; version: +<screen width="70" format="linespecific"> +<prompt>% </prompt><command>sudo apt-get build-dep kwave</command> +</screen> + </para> + + <para> + After installing the required packages, you can build &kwave; as + described in the chapters before. After building you can type this + to get a .deb file in your current build directory: +<screen width="70" format="linespecific"> +<prompt>% </prompt><command>make deb</command> +</screen> + </para> + + <note><para> + The .deb file you get from this step will not have the quality that + a package from your official distribution has - it is just good enough + for installing and safely uninstalling &kwave; for testing purposes + and for personal use. + </para></note> + + </sect1> + +</chapter> + +<!-- ###################################################################### --> +<!-- ### Chapter: Developer's Guide to Kwave ### --> +<!-- ###################################################################### --> + +<chapter id="developers"><title>Developer's Guide to &kwave;</title> + + <para> + <inlinemediaobject> + <imageobject> + <imagedata fileref="under-construction.png" format="PNG"/> + </imageobject> + <textobject> <phrase>under construction</phrase> </textobject> + </inlinemediaobject> + </para> + <para> + Sorry, this chapter is still to be written... At the moment the + source code is nearly completely documented with tags suitable with + the KDE documentation tools. We currently prefer using + <ulink url="&url_doxygen;">doxygen</ulink>. Maybe some day we will spend some time for + writing a tool that converts the doxygen output into something + we can include into the docbook source (the source this page has + been built of). + </para> + <para> + If you want to write a plugin, contribute something to this + project (or maybe write the converter mentioned above), please + feel free to contact one of the authors directly + and / or subscribe to the &kwave; mailing list: + <ulink url="&url_mailinglist;"> "&url_mailinglist;"</ulink>. + Help is always welcome! + </para> + + <!-- @@@ most of this has still to be done ... @@@ --> + +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<!-- +++ Section: API documentation +++ --> +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + + <sect1 id="make_apidoc"><title>API documentation</title> + + <para> + If you are interested in the internal of &kwave; and you have + <ulink url="&url_doxygen;">doxygen</ulink> installed, then you + can type: +<screen width="50" format="linespecific"> +<prompt>% </prompt><command>make apidoc</command> +</screen> + </para> + <para> + to get a directory + <filename><replaceable>doc/api/html</replaceable></filename>, + with documentation of the source and the internal API in your + current build directory. + </para> + <tip> + <para> + API documentation can be found <ulink url="../api/html/index.html">here...</ulink>. + </para> + </tip> + </sect1> + +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<!-- +++ Section: Starting in a test environment +++ --> +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + + <sect1 id="create_wrapper"><title>Starting in a test environment</title> + + <para> + If you are developing or testing &kwave;, then you do not necessarily + need to uninstall/install &kwave; after every build. Instead you can + use the application from where it is built by using a wrapper script. + This wrapper script can be built with the following command: +<screen width="50" format="linespecific"> +<prompt>% </prompt><command>make wrapper</command> +</screen> + </para> + <para> + The script will be named <filename><replaceable>kw</replaceable></filename>, + feel free to modify it to match your system if needed. + </para> + <warning><para> + For this to work, you must <emphasis>not</emphasis> have &kwave; + installed on your system. If so, please uninstall the package + before! + </para></warning> + + </sect1> + +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<!-- +++ Section: Adding a new plugin +++ --> +<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<!-- + <sect1 id="add_new_plugin"><title>Adding a new Plugin</title> + + <para> + to be written... + </para> + + </sect1> +--> + +</chapter> + +</book> diff --git a/doc/en/index.docbook b/doc/en/index.docbook index 89218ac7..84f17b1d 100644 --- a/doc/en/index.docbook +++ b/doc/en/index.docbook @@ -7,18 +7,16 @@ <!ENTITY version_tag "0_9_3"> <!ENTITY version_year "2017"> <!ENTITY % ents PUBLIC "-//KDE//ENTITIES Application-Variable Entities V2.0//EN" "entities/kde-prologue.entities"> + <!ENTITY url_devel_building_rpm_from_git "http://kwave.sourceforge.net/doc/devel/building_rpm_from_git.html";> + <!ENTITY url_devel_requirements "http://kwave.sourceforge.net/doc/devel/requirements.html";> <!ENTITY url_git_web_kde "http://commits.kde.org/kwave";> <!ENTITY url_prefix_gitweb "&url_git_web_kde;?path="> <!ENTITY url_authors "&url_prefix_gitweb;AUTHORS"> <!ENTITY url_changelog "&url_prefix_gitweb;CHANGES"> - <!ENTITY url_cmake "http://www.cmake.org";> <!ENTITY url_debian "http://www.debian.org";> - <!ENTITY url_download "http://kwave.sourceforge.net/download.html";> - <!ENTITY url_doxygen "http://www.stack.nl/~dimitri/doxygen";> <!ENTITY url_flac "http://flac.sourceforge.net/";> <!ENTITY url_homepage "http://kwave.sourceforge.net/";> <!ENTITY url_id3lib "http://id3lib.sourceforge.net/";> - <!ENTITY url_kde_project "http://www.kde.org/applications/multimedia/kwave/";> <!ENTITY url_lame "http://lame.sourceforge.net/";> <!ENTITY url_levelmeter "https://web.archive.org/web/*/http://www.rikkus.info/esound-level-meter/";> <!ENTITY url_libaudiofile "http://www.68k.org/~michael/audiofile/";> @@ -27,13 +25,10 @@ <!ENTITY url_licenses "&url_prefix_gitweb;LICENSES"> <!ENTITY url_mailinglist "https://lists.sourceforge.net/lists/listinfo/kwave-devel";> <!ENTITY url_ogg_vorbis "http://www.xiph.org";> - <!ENTITY url_readme "&url_prefix_gitweb;README"> <!ENTITY url_rfc2361 "http://www.ietf.org/rfc/rfc2361.txt";> <!ENTITY url_sourceforge "http://sourceforge.net";> <!ENTITY url_sox "http://sox.sourceforge.net/";> <!ENTITY url_git_web_sf "http://sourceforge.net/p/kwave/code/commit_browser";> - <!ENTITY url_git_list_tags "http://commits.kde.org/kwave.git/refs/";> - <!ENTITY url_git_master "git://anongit.kde.org/kwave.git"> <!ENTITY i18n-cmd_syntax "Syntax: "> <!ENTITY i18n-plugin_lbl_internal_name "Internal Name:"> <!ENTITY i18n-plugin_lbl_type "Plugin Type:"> @@ -458,7 +453,8 @@ you can get the sources of the latest development version. For instructions on how to get access to the repository, read in the chapter about - <link linkend="building_rpm_from_git">building from GIT</link>. + <ulink url="&url_devel_building_rpm_from_git;">building from GIT</ulink> + in the developer documentation. There also is a GIT web interface on <ulink url="&url_git_web_kde;">KDE</ulink> and on <ulink url="&url_git_web_sf;">SourceForge</ulink> where you can use to browse through the sources. @@ -506,597 +502,6 @@ </chapter> <!-- ###################################################################### --> -<!-- ### Chapter: Installation ### --> -<!-- ###################################################################### --> - -<chapter id="installation"><title>Installation</title> - -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> -<!-- +++ Section: Getting Kwave +++ --> -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> - - <sect1 id="getting"><title>How to obtain &kwave;</title> - - <para> - &kwave; has an own homepage under - <ulink url="&url_homepage;">&url_homepage;</ulink>. Here you can - find further information about the project, as well as - information about current stable and up-to-date development - versions. - </para> - <para> - There also is a KDE project page - at <ulink url="&url_kde_project;">&url_kde_project;</ulink> which - shows a short summary of the application. - </para> - - <para> - If you want to get a &kwave; release, you have the choice to visit - <ulink url="&url_download;">&url_download;</ulink> and - <itemizedlist> - <listitem><para> - download a binary package of the latest stable version, if - there is one for your distribution, - </para></listitem> - <listitem><para> - download a source RPM package of the latest stable version, - </para></listitem> - <listitem><para> - compile on your own, from a .tar.bz2 archive with the source code - of the latest stable version, - </para></listitem> - <listitem><para> - compile on your own, from the latest GIT source. - </para></listitem> - </itemizedlist> - </para> - - <para> - Don't be afraid, compiling Kwave should be quite simple even if - you are not a software developer. It just needs some developer - packages to be installed and some time. - </para> - - </sect1> - -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> -<!-- +++ Section: Requirements +++ --> -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> - - <sect1 id="requirements"><title>Requirements</title> - - <para> - In order to successfully use &kwave;, you need: - <itemizedlist> - <listitem><para> - a computer running Linux (&kwave; might also run under - some other operating system, but we have never tested - this, please let us know if you get it working under - some other platform / operating system) - </para></listitem> - <listitem><para> - working sound playback (not really required for using but - what would you do with a sound editor if you cannot - <emphasis>hear</emphasis> the result of your work?) - </para></listitem> - <listitem><para> - KDE Frameworks 5.2 (KF5) or higher (at least the libraries, - if you are using a different desktop, you can also run &kwave; - if the proper libraries are installed). - </para></listitem> - <listitem><para> - Qt-5.4 or higher (normally comes as a dependency of KF5) - </para></listitem> - <listitem><para> - ALSA 1.0.14 or higher (for record/playback) - </para></listitem> - <listitem><para> - PulseAudio 4.0 or higher (for record/playback) - </para></listitem> - <listitem><para> - id3lib-3.8.1 or higher (for ID3 tags) - </para></listitem> - <listitem><para> - mad-0.15 or higher (optionally for MP3 import/export) - </para></listitem> - <listitem><para> - flac-1.2.0 or higher (for FLAC import/export) - </para></listitem> - <listitem><para> - libsamplerate-0.1.3 or higher (sample rate conversion) - </para></listitem> - </itemizedlist> - </para> - - <para> - For a more complete and up-to-date list, please consult the - <ulink url="&url_readme;">'README'</ulink> file that is included - in the source distribution. - This file also contains some special hints for getting &kwave; running and/or - building &kwave; under some distributions. - </para> - - <para> - If you intend to compile &kwave; from the sources, you will need at least: - <itemizedlist> - <listitem><para> - <ulink url="&url_cmake;">cmake</ulink>-2.8.12 or newer - </para></listitem> - <listitem><para> - A recent C/C++ compiler. GCC-4.x works fine, some older and any - newer version (like gcc-5.0) should work too. - </para></listitem> - <listitem><para> - The glibc2 (libc-6) development environment. On SuSE systems - the package is called "libc", on other systems it might be - called "libc-devel". - </para></listitem> - <listitem><para> - Qt5 and KF5 development packages - </para></listitem> - <listitem><para> - pulseaudio-0.9.16 or newer - </para></listitem> - <listitem><para> - id3lib-devel-3.8.1 or newer - </para></listitem> - <listitem><para> - fftw-3.0 or newer - </para></listitem> - <listitem><para> - mad-devel-0.15 or newer - (if you have the permission to use MP3 code) - </para></listitem> - <listitem><para> - flac-devel-1.2.0 newer - </para></listitem> - <listitem><para> - If you intend to get the &kwave; sources via GIT, you will also - need a current git package. - </para></listitem> - <listitem><para> - ...many other packages, please take a look at the - <ulink url="&url_readme;">'README'</ulink> file included in - the source package. - </para></listitem> - </itemizedlist> - </para> - - </sect1> - -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> -<!-- +++ Section: Manual Compilation +++ --> -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> - - <sect1 id="manual_compilation"><title>Manual Compilation and installation</title> - - <para> - Since version 0.7.10 &kwave; uses - <ulink url="&url_cmake;">cmake</ulink>, a make system - that is also used by KDE itself. So if you know how to build other KDE - applications, you should not have any difficulties in building &kwave;. - If you run into problems please report them to - the &kwave; <link linkend="mailing-list">mailing list</link>. - </para> - - <para> - In order to compile and install &kwave; on your system, it is best - practice to do a <emphasis>out-of-tree</emphasis> build. This means - that you hold the sources of &kwave; in one directory and build the - package in another (temporary) directory. - </para> - - <para> - For example, assuming that your sources are already - unpacked in <filename><replaceable>$HOME/src/kwave-&version;</replaceable></filename>, you - can do the following: -<screen width="50" format="linespecific"> -<prompt>% </prompt><command>mkdir /tmp/kwave-build</command> -<prompt>% </prompt><command>cd /tmp/kwave-build</command> -<prompt>% </prompt><command>cmake <replaceable>$HOME/src/kwave-&version;</replaceable> <replaceable>[build options]</replaceable></command> -<prompt>% </prompt><command>make</command> -<prompt>% </prompt><command>su root -c "make install"</command> -</screen> - (Specifying build options is a way to enable or disable specific features. - See the following section for descriptions) - </para> - - </sect1> - -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> -<!-- +++ Section: Build options +++ --> -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> - - <sect1 id="build_options"><title>Build options</title> - - <para> - By specifying build options, you can enable or disable some features - of &kwave;, like excluding some components or plugins from the - generated package. Here is a list of the available options: - - <itemizedlist> - <listitem><para> - <literal>WITH_ALSA</literal> - enable playback/recording via ALSA - [<literal>on</literal>/<literal>off</literal>, - default=<literal>on</literal>] - </para></listitem> - <listitem id="CMAKE_WITH_DEBUG"><para> - <literal>WITH_DEBUG</literal> - build a debug version - [<literal>on</literal>/<literal>off</literal>, - default=<literal>off</literal>] - </para></listitem> - <listitem><para> - <literal>WITH_DOC</literal> - build online documentation - [<literal>on</literal>/<literal>off</literal>, - default=<literal>on</literal>] - </para></listitem> - <listitem><para> - <literal>WITH_FLAC</literal> - enable support for FLAC files - [<literal>on</literal>/<literal>off</literal>, - default=<literal>on</literal>] - </para></listitem> - <listitem><para> - <literal>WITH_MP3</literal> - enable support for mp3 files - [<literal>on</literal>/<literal>off</literal>, - default=<literal>off</literal>] - Please note that you need the permission to use code - covered by the MP3 software patents! - </para></listitem> - <listitem><para> - <literal>WITH_OGG_OPUS</literal> - enable support for Ogg/Opus files - [<literal>on</literal>/<literal>off</literal>, - default=<literal>on</literal>] - </para></listitem> - <listitem><para> - <literal>WITH_OGG_VORBIS</literal> - enable support for Ogg/Vorbis files - [<literal>on</literal>/<literal>off</literal>, - default=<literal>on</literal>] - </para></listitem> - <listitem><para> - <literal>WITH_OPTIMIZED_MEMCPY</literal> - use an optimized version of memcpy, available for - X86, X86_64 and PPC platforms - [<literal>on</literal>/<literal>off</literal>, - default=<literal>on</literal>] - </para></listitem> - <listitem><para> - <literal>WITH_OSS</literal> - enable playback/recording via OSS - [<literal>on</literal>/<literal>off</literal>, - default=<literal>on</literal>] - </para></listitem> - <listitem><para> - <literal>WITH_PULSEAUDIO</literal> - enable playback/recording via PulseAudio - [<literal>on</literal>/<literal>off</literal>, - default=<literal>on</literal>] - </para></listitem> - <listitem><para> - <literal>WITH_QT_AUDIO</literal> - enable playback via Qt Multimedia - [<literal>on</literal>/<literal>off</literal>, - default=<literal>on</literal>] - </para></listitem> - </itemizedlist> - </para> - - <para> - These options can be passed to <literal><command>cmake</command></literal> - with <command><literal>-D</literal><replaceable>option</replaceable><literal>=</literal><replaceable>value</replaceable></command>. - For example, if you want to enable MP3 support, - you can pass the corresponding option as follows: -<screen width="70" format="linespecific"> -<prompt>% </prompt><command>cmake <replaceable>[source directory]</replaceable> -DWITH_MP3=ON <replaceable>[other options...]</replaceable></command> -</screen> - </para> - </sect1> - -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> -<!-- +++ Section: Building RPM packages from tar.bz2 archives +++ --> -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> - - <sect1 id="building_rpm_from_tarbz2"> - <title>Building RPM packages from tar.bz2 archives</title> - - <sect2 id="building_with_rpm_ta"> - <title>With working rpmbuild -ta</title> - - <para> - If you are running a system with RPM support, the preferred way to - install &kwave; on your system will be the creation of a nice RPM - package. First you should get the current source of &kwave;, either - as a tar.bz2 archive from the &kwave; download page or - check out an up-to-date copy via - <link linkend="git-repository">GIT</link> (like described in - the <link linkend="git_checkout">chapter about GIT</link>) and read the - <link linkend="building_rpm_from_git">next</link> chapter. - </para> - - <para> - If you have downloaded tar.bz2 archives of &kwave;, - create and install the RPMs just by doing the following steps - (where <replaceable>[arch]</replaceable> stands for the platform you - have built the package and might be something like - <literal>i586</literal>, <literal>i686</literal>, - <literal>sparc</literal> or whatever, - <replaceable>XXX</replaceable> stands for the version number - you have downloaded). - </para> - - <para> - To build the &kwave; package and install it do: -<screen width="70" format="linespecific"> -<prompt>% </prompt><command>rpmbuild -ta <replaceable>kwave-XXX.tar.bz2</replaceable></command> -<prompt>% </prompt><command>rpm -i <replaceable>/usr/src/redhat/RPMS/[arch]/kwave-XXX.[arch].rpm</replaceable></command> -</screen> - </para> - - <note><para> - <emphasis>Note for SuSE users: </emphasis> - you have to specify the directory - <filename>/usr/src/packages</filename> instead - of <filename>/usr/src/redhat</filename> ! - </para></note> - - <para> - If you haven't seen any errors, then that's it and you can skip the - rest of this chapter. If rpm was unable to build the packages - and says something like "spec file not found", then go on and - read the rest of this section. - </para> - - </sect2> - - <sect2 id="rpm_build_with_broken_rpm"> - <title>With broken rpmbuild -ta support</title> - - <para><anchor id="manual_rpm_creation"/> - If you cannot get <command>rpmbuild -ta</command> working, here are - the steps for making that manually (the hard way): - </para> - - <orderedlist> - <listitem><para> - Go to your RPM "topdir". This normally - is <filename>/usr/src/redhat</filename> - for the redhat distribution - or <filename>/usr/src/packages</filename> if you - have the SuSE distribution. -<screen width="70" format="linespecific"> -<prompt>% </prompt><command>cd /usr/src/<replaceable>redhat</replaceable></command> -</screen> - </para></listitem> - - <listitem><para> - Put the tar.bz2 archive into the SOURCES subdirectory (you - have to replace "somewhere" with the real directory where - the files are, of course). -<screen width="70" format="linespecific"> -<prompt>% </prompt><command>cp <replaceable>/somewhere/kwave-XXX.tar.bz2</replaceable> SOURCES</command> -</screen> - </para></listitem> - - <listitem><para> - Extract the spec file from the archives and put it into - the SPEC subdirectory. -<screen width="70" format="linespecific"> -<prompt>% </prompt><command>tar -xOjf SOURCES/<replaceable>kwave-XXX.tar.bz2</replaceable> \*.spec > SPECS/kwave.spec</command> -</screen> - </para></listitem> - - <listitem><para> - Let rpm do the compile job and generate the rpm of &kwave;. - If you only want to make a binary package, you - can specify <literal>-bb</literal> instead of - <literal>-ba</literal>, or just <literal>-bs</literal> to build - only a source package. -<screen width="70" format="linespecific"> -<prompt>% </prompt><command>rpmbuild -ba SPECS/kwave.spec</command> -</screen> - </para></listitem> - - <listitem><para> - If everything was ok, you can install the binary rpm of - &kwave;, it will be in the BUILD directory. - If you already have a version of &kwave; installed, - please remove it first or use the parameter - <literal>-U</literal> instead - of <literal>-i</literal> for upgrading instead of installing. -<screen width="70" format="linespecific"> -<prompt>% </prompt><command>rpm -ivh BUILD/<replaceable>[arch]/kwave-XXX.[arch].rpm</replaceable></command> -</screen> - </para></listitem> - - </orderedlist> - - </sect2> - </sect1> - -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> -<!-- +++ Section: Building RPM packages from GIT +++ --> -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> - - <sect1 id="building_rpm_from_git"> - <title>Building RPM packages from GIT</title> - - <sect2 id="git_checkout"><title>Checking out the sources</title> - - <para> - For initially checking out the sources you will need some disk space - (about 25 megabytes) in a directory of your choice, the git package - of your favorite distribution and full access to the Internet. If you - get error messages about rejected connections you either have typed - something wrong or your provider doesn't give you full access. - A good place for the source files will be <filename>"$HOME/src"</filename>. - </para> - - <orderedlist> - <listitem><para> - First create the directory that will receive the subdirectory with - &kwave; sources and change into it: -<screen width="40" format="linespecific"> -<prompt>% </prompt><command>mkdir -p <replaceable>$HOME/src</replaceable></command> -<prompt>% </prompt><command>cd <replaceable>$HOME/src</replaceable></command> -</screen> - </para></listitem> - <listitem> - <para> - Then check out the latest sources from the GIT server: -<screen width="70" format="linespecific"> -<prompt>% </prompt><command>git clone &url_git_master; kwave</command> -</screen> - </para> - <para> - or you can check out a specific release with the following commands: -<screen width="70" format="linespecific"> - <prompt>% </prompt><command>git clone &url_git_master; kwave</command> - <prompt>% </prompt><command>cd kwave</command> - <prompt>% </prompt><command>git checkout tags/<replaceable>[release-tag]</replaceable> </command> -</screen> - You can look up the names of the release tags in the git web page at - <ulink url="&url_git_list_tags;"> &url_git_list_tags;</ulink>. - The release tags are always built out of the word <literal>Release-</literal> and - the version number of the release, with underscores instead of dots. - For example "<literal>Release-&version_tag;</literal>" for v&version;. - </para> - </listitem> - </orderedlist> - - <warning><para> - There <emphasis>must not</emphasis> be a directory named - <filename>kwave</filename> under - the directory you want to check out. Otherwise the git program will - complain about already existing files and the checkout will - not work. - </para></warning> - - </sect2> - - <sect2 id="git_update"><title>Updating fresh sources from GIT</title> - <para> - The procedure described in the previous section is only necessary - once. For further updates it is much easier. Just change into the - directory where you have the checked out sources and do the following - to update to the latest version: -<screen width="40" format="linespecific"> -<prompt>% </prompt><command>git pull</command> -</screen> - Then go on to the next section and compile as usual. - </para> - <note><para> - If you think that you have messed up your local source tree or if there - are conflicts during updating and you want to start through from a clean - state, you can do the following to discard all local changes and switch - back to the latest version from the master branch: -<screen width="40" format="linespecific"> -<prompt>% </prompt><command>git clean --force -d</command> -<prompt>% </prompt><command>git reset --hard</command> -<prompt>% </prompt><command>git checkout <replaceable>master</replaceable></command> -</screen> - </para></note> - </sect2> - - <sect2 id="git_compiling"><title>Compiling</title> - <para> - Building rpm package from a GIT snapshot is quite simple. The procedure - is nearly the same as described in the last section, so it unhappily also - has the same problem with the <command>rpmbuild -ta</command> command - our method internally uses. - Like in the previous chapter, <replaceable>[arch]</replaceable> stands - for the platform you have built the package and might be something - like <literal>i386</literal>, <literal>i586</literal>, - <literal>sparc</literal> or whatever, - <replaceable>XXX</replaceable> stands - for the version number you have checked out. - </para> - - <note><para> - <emphasis>Note for SuSE users: </emphasis> - here you have to specify the directory - <filename>/usr/src/packages</filename> instead - of <filename>/usr/src/redhat</filename> too! - </para></note> - - <para> - Assuming that - you are in the root of where you checked out from GIT, do the - following to create a Makefile, the &kwave; package and - install it. If you already have a version of &kwave; installed, - please remove it first or use <command>rpm -U</command> instead - of <command>rpm -i</command> for updating instead of installing. -<screen width="70" format="linespecific"> -<prompt>% </prompt><command>mkdir /tmp/kwave-build</command> -<prompt>% </prompt><command>cd /tmp/kwave-build</command> -<prompt>% </prompt><command>cmake <replaceable>$HOME/src/kwave</replaceable></command> -<prompt>% </prompt><command>make rpm</command> -<prompt>% </prompt><command>rpm -ivh /usr/src/redhat/BUILD/<replaceable>[arch]/kwave-XXX.[arch].rpm</replaceable></command> -</screen> - </para> - - <note><para> - If you still have problems with <command>make rpm</command>, - you will find the tar.bz2 - archive that was produced in <filename>/tmp</filename>. - Please follow the instructions in the - <link linkend="manual_rpm_creation">previous</link> chapter. - </para></note> - - </sect2> - </sect1> - -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> -<!-- +++ Section: Building DEB package from Source +++ --> -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> - - <sect1 id="building_deb_from_src"> - <title>Building a DEB package for testing and personal use</title> - - <para> - If you want to create a deb package of &kwave;, ⪚ for testing a - version that is not yet available via official package repositories, - then you can create your own package quite easily. First of all, you - need to install some required tools: -<screen width="70" format="linespecific"> -<prompt>% </prompt><command>sudo apt-get install build-essential checkinstall</command> -</screen> - </para> - - <para> - Then you can install the required build dependencies by pretending to - install the dependencies of the official &kwave; version: -<screen width="70" format="linespecific"> -<prompt>% </prompt><command>sudo apt-get build-dep kwave</command> -</screen> - </para> - - <para> - After installing the required packages, you can build &kwave; as - described in the chapters before. After building you can type this - to get a .deb file in your current build directory: -<screen width="70" format="linespecific"> -<prompt>% </prompt><command>make deb</command> -</screen> - </para> - - <note><para> - The .deb file you get from this step will not have the quality that - a package from your official distribution has - it is just good enough - for installing and safely uninstalling &kwave; for testing purposes - and for personal use. - </para></note> - - </sect1> - -</chapter> - -<!-- ###################################################################### --> <!-- ### Chapter: Basics about digital audio ### --> <!-- ###################################################################### --> @@ -5024,7 +4429,7 @@ </chapter> <!-- ###################################################################### --> -<!-- ### Chapter: Developer's Guide to Kwave ### --> +<!-- ### Chapter: Plugin Reference ### --> <!-- ###################################################################### --> <chapter id="plugins"><title>Plugins</title> @@ -5930,7 +5335,7 @@ Provides various internal commands useful for debugging and scripting &kwave;. These functions are only available through the main menu if &kwave; has been compiled in debug mode - (see <link linkend="CMAKE_WITH_DEBUG">build options)</link>. + (built with the option CMAKE_WITH_DEBUG). </para> </listitem> </varlistentry> @@ -7807,106 +7212,6 @@ </chapter> <!-- ###################################################################### --> -<!-- ### Chapter: Developer's Guide to Kwave ### --> -<!-- ###################################################################### --> - -<chapter id="developers"><title>Developer's Guide to &kwave;</title> - - <para> - <inlinemediaobject> - <imageobject> - <imagedata fileref="under-construction.png" format="PNG"/> - </imageobject> - <textobject> <phrase>under construction</phrase> </textobject> - </inlinemediaobject> - </para> - <para> - Sorry, this chapter is still to be written... At the moment the - source code is nearly completely documented with tags suitable with - the KDE documentation tools. We currently prefer using - <ulink url="&url_doxygen;">doxygen</ulink>. Maybe some day we will spend some time for - writing a tool that converts the doxygen output into something - we can include into the docbook source (the source this page has - been built of). - </para> - <para> - If you want to write a plugin, contribute something to this - project (or maybe write the converter mentioned above), please - feel free to contact one of the authors directly - and / or subscribe to - the &kwave; <link linkend="mailing-list">mailing list</link>. - Help is always welcome! - </para> - - <!-- @@@ most of this has still to be done ... @@@ --> - -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> -<!-- +++ Section: Creating API documentation +++ --> -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> - - <sect1 id="make_apidoc"><title>Creating API documentation</title> - - <para> - If you are interested in the internal of &kwave; and you have - <ulink url="&url_doxygen;">doxygen</ulink> installed, then you - can type: -<screen width="50" format="linespecific"> -<prompt>% </prompt><command>make apidoc</command> -</screen> - </para> - <para> - to get a directory - <filename><replaceable>apicod/html</replaceable></filename>, - with documentation of the source and the internal API in your - current build directory. - </para> - - </sect1> - -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> -<!-- +++ Section: Starting in a test environment +++ --> -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> - - <sect1 id="create_wrapper"><title>Starting in a test environment</title> - - <para> - If you are developing or testing &kwave;, then you do not necessarily - need to uninstall/install &kwave; after every build. Instead you can - use the application from where it is built by using a wrapper script. - This wrapper script can be built with the following command: -<screen width="50" format="linespecific"> -<prompt>% </prompt><command>make wrapper</command> -</screen> - </para> - <para> - The script will be named <filename><replaceable>kw</replaceable></filename>, - feel free to modify it to match your system if needed. - </para> - <warning><para> - For this to work, you must <emphasis>not</emphasis> have &kwave; - installed on your system. If so, please uninstall the package - before! - </para></warning> - - </sect1> - -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> -<!-- +++ Section: Adding a new plugin +++ --> -<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> - -<!-- - <sect1 id="add_new_plugin"><title>Adding a new Plugin</title> - - <para> - to be written... - </para> - - </sect1> ---> - -</chapter> - -<!-- ###################################################################### --> <!-- ### Chapter: Questions and Answers ### --> <!-- ###################################################################### --> @@ -7925,8 +7230,7 @@ <answer> <para> Read in the - <link linkend="requirements">chapter</link> - mentioned before. + <ulink url="&url_devel_requirements;">developer documentation</ulink>. </para> </answer> </qandaentry> diff --git a/doxy.cfg.in b/doxy.cfg.in index 8efcb454..b0037e86 100644 --- a/doxy.cfg.in +++ b/doxy.cfg.in @@ -2165,7 +2165,7 @@ DOT_NUM_THREADS = 0 # The default value is: Helvetica. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_FONTNAME = FreeSans +DOT_FONTNAME = # The DOT_FONTSIZE tag can be used to set the size (in points) of the font of # dot graphs.
