Git commit 8e2dd1317e2cafb0810b198d5cef8bc81a9d986a by Burkhard Lück. Committed on 05/01/2018 at 07:51. Pushed by lueck into branch 'master'.
adapt kbackup docbook to kf5 remove obsolete comments remove appendix installation, unused in kf5 remove chapter faq with entities reporting.bugs+updating.documentation, unused in kf5 replace setion help-menu1 with link to fundamentals improve markup fix issues reported by http://ebn.kde.org/sanitizer/just-in-time.php CCMAIL:[email protected] M +66 -176 doc/en/index.docbook https://commits.kde.org/kbackup/8e2dd1317e2cafb0810b198d5cef8bc81a9d986a diff --git a/doc/en/index.docbook b/doc/en/index.docbook index ee66358..7fa472b 100644 --- a/doc/en/index.docbook +++ b/doc/en/index.docbook @@ -1,43 +1,18 @@ <?xml version="1.0" ?> <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [ - <!-- Define an entity for your application if it is not part of KDE - CVS --> - <!ENTITY kbackup "<application>KBackup</application>"> - <!ENTITY kappname "&kbackup;"><!-- 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. --> + <!ENTITY kbackup "<application>KBackup</application>"><!--FIXME remove entitiy when kbackup depends on kdoctools >= 5.42--> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> ]> -<!-- ................................................................ --> - -<!-- 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;"> - -<!-- This header contains all of the meta-information for the document such -as Authors, publish date, the abstract, and Keywords --> +<book id="kbackup" lang="&language;"> <bookinfo> <title>The &kbackup; Handbook (for version 1.0)</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>Martin</firstname> <surname>Koller</surname> @@ -52,9 +27,6 @@ and use `&George.N.Ugnacious; &George.N.Ugnacious.mail;' in the author element. <year>2006 - 2017</year> <holder>Martin Koller</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>2009-06-14</date> @@ -68,10 +40,6 @@ and use `&George.N.Ugnacious; &George.N.Ugnacious.mail;' in the author element. </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>system</keyword> @@ -89,20 +57,15 @@ Please at least include KDE, the KDE package it is in, the name <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> -&kbackup; is a program that lets you back up any directories or files, -whereby it uses an easy to use directory tree to select the things to back up. -It lets you save your settings in so-called "profile" files, where a profile is a simple -text file containing definitions for directories and files to be included +&kbackup; is a program that lets you back up any folders or files, +whereby it uses an easy to use folder tree to select the things to back up. +It lets you save your settings in so-called <quote>profile</quote> files, where a profile is a simple +text file containing definitions for folders and files to be included or excluded from the backup process. Also, it lets you define where the backup shall be saved to. -The target can be either a local directory (⪚ a locally mounted device -like a ZIP drive, USB stick, etc.) but it can also be any remote URL +The target can be either a local folder (⪚ a locally mounted device +like a ZIP drive, USB stick, etc.) but it can also be any remote &URL; (⪚ smb://remote/some_path) to back up your data to some central server, etc. </para> @@ -131,10 +94,10 @@ format. </para> <para> If the files are compressed, you can uncompress all files -from the current directory recursively down with the following command: +from the current folder recursively down with the following command: </para> <para> -find . -name \*bz2 -print0 | xargs -0 bunzip2 +<programlisting>find . -name \*bz2 -print0 | xargs -0 bunzip2</programlisting> </para> </chapter> @@ -143,23 +106,23 @@ find . -name \*bz2 -print0 | xargs -0 bunzip2 <title>Using &kbackup;</title> <para> -All you need to do is to select which directories you want to store. -This is done by selecting all the directories in the tree view on the left side +All you need to do is to select which folders you want to store. +This is done by selecting all the folders in the tree view on the left side of the main window. </para> <para> -If you select a directory, &kbackup; will automatically store all files and -subdirectories below it. -If you want to exclude parts of a selected directory, simply deselect that files/directories -inside the still selected directory. +If you select a folder, &kbackup; will automatically store all files and +subfolders below it. +If you want to exclude parts of a selected folder, simply deselect that files/folders +inside the still selected folder. </para> <para> -In general, this means: A selected directory will store everything in it and below it, +In general, this means: A selected folder will store everything in it and below it, except the deselected parts in it. This also means, whenever you reuse a profile (see below) later on and new files -have been added to a directory already selected for backup, all the new files will +have been added to a folder already selected for backup, all the new files will also be stored. </para> @@ -192,27 +155,27 @@ To reload a selection into &kbackup;, use the <menuchoice><guimenu>File</guimenu </para> <para> -&kbackup; saves in a profile the selections for all included directories/files, -excluded directories/files, the target directory/URL, defined archive prefix, +&kbackup; saves in a profile the selections for all included folders/files, +excluded folders/files, the target folder/&URL;, defined archive prefix, the defined maximum slice file size, etc. </para> <para> If you want to ease the usage of backing up every day the same set of -files, simply store your settings into a &kbackup; profile (a .kbp file) +files, simply store your settings into a &kbackup; profile (a <filename class="extension">.kbp</filename> file) and pass that file on the command line. </para> <para> -E.g.: +⪚: </para> <para> -kbackup myData.kbp +<programlisting>kbackup myData.kbp</programlisting> </para> <para> -Hint: you can also create a shortcut on your desktop to a .kbp file +Hint: you can also create a shortcut on your desktop to a <filename class="extension">.kbp</filename> file as the file type is registered to start &kbackup; on double click </para> @@ -236,30 +199,30 @@ slices of one backup) and a trailing slice sequence number (_1 in this example). </para> <para> In the menu <menuchoice><guimenu>File</guimenu> <guimenuitem>Profile Settings</guimenuitem></menuchoice>, you can define a different archive prefix than the -default "backup". +default <quote>backup</quote>. </para> <para> In the Profile Settings Dialog, you can also define a maximum archive slice size, which limits the slice size even if there would be more space left on the target device. -This helps to create archive slices which can then be later burned on a CD/DVD, etc. +This helps to create archive slices which can then be later burned on a &CD;/&DVD;, &etc; If you explicitly limit the size of an archive slice, the available size will be marked with (*) in the main window. </para> <para> -But even if you define a slice to be of "unlimited" size, there are other constraints +But even if you define a slice to be of <quote>unlimited</quote> size, there are other constraints which limit the size of a slice: <itemizedlist> -<listitem><para>limited by the target directory (when stored directly into a local dir)</para></listitem> -<listitem><para>limited by the "tmp" dir when we create a tmp file for later upload to a remote URL</para></listitem> +<listitem><para>limited by the target folder (when stored directly into a local folder)</para></listitem> +<listitem><para>limited by the <filename class="directory">/tmp</filename> folder when we create a tmp file for later upload to a remote &URL;</para></listitem> </itemizedlist> </para> <para> -In the Profile Settings, you can also define a maximum number of backups being kept -in the target directory, and therefore automatically deleting all older backups there. -E.g. if you set it to 3, &kbackup; will keep the last 3 backups and delete all older ones. +In the <guilabel>Profile Settings</guilabel>, you can also define a maximum number of backups being kept +in the target folder, and therefore automatically deleting all older backups there. +⪚ if you set it to 3, &kbackup; will keep the last 3 backups and delete all older ones. </para> </sect1> @@ -275,34 +238,34 @@ will be finished in a much shorter time. </para> <para> This works as follows: In the profile, you define an interval (in days) for the full backup. -E.g. when you define 5 days, then &kbackup; will do a full backup of all files every 5 days. +⪚ when you define 5 days, then &kbackup; will do a full backup of all files every 5 days. Whenever you start &kbackup; before the interval expires with this profile - regardless how often you run a backup - only the files which have changed since the last backup will be saved. &kbackup; stores the time stamp of the last backup into the profile and knows therefore what to do when running the next time. </para> <para> -The archive slice files created during an incremental backup will contain the text "_inc", ⪚: +The archive slice files created during an incremental backup will contain the text <quote>_inc</quote>, ⪚: </para> <para> backup_2010.06.14-18.50.26_1_inc.tar </para> <para> -Full backup slice files will not include "_inc" in the name, ⪚: +Full backup slice files will not include <quote>_inc</quote> in the name, ⪚: </para> <para> backup_2010.06.13-20.58.14_1.tar </para> <para> When one wants to restore files from an incremental backup, it's important to look for -the most recent version of a file to be restored in all "_inc" files and finally also the last full backup +the most recent version of a file to be restored in all <quote>_inc</quote> files and finally also the last full backup slice file. This exactly is also the disadvantage of the incremental backup (but no advantage without disadvantage ;-) ) </para> <para> If you want to do a full backup earlier than the defined incremental cycle time defined in a profile, -you can do so by checking the "Force Full Backup" option in the user interface. -When &kbackup; is started via the command line, this can be achieved by using the option --forceFull +you can do so by checking the <guilabel>Force Full Backup</guilabel> option in the user interface. +When &kbackup; is started via the command line, this can be achieved by using the option <option>--forceFull</option> </para> <para> A forced full backup will restart the backup cycle, ⪚ &kbackup; counts the days to the next full backup @@ -325,7 +288,7 @@ then not-compressed .tar archive. <para> When you have selected to create the backup on some local filesystem (⪚ your extra disc, ZIP drive, etc.) - which means you did not -enter a remote target URL - &kbackup; might split the whole backup into several archive slices +enter a remote target &URL; - &kbackup; might split the whole backup into several archive slices due to media capacity limitations. </para> <para> @@ -347,25 +310,25 @@ backup_2006.08.26-13.04.44_2.tar If you want to automate the process of the backup, &kbackup; offers different command line options to help with this: <itemizedlist> -<listitem><para>--auto</para> +<listitem><para><option>--auto</option></para> <para> -When you run &kbackup; with this option and a given .kbp profile, it will +When you run &kbackup; with this option and a given <filename class="extension">.kbp</filename> profile, it will start, load the given profile, run the backup and terminate when done. All this is done with a visible &kbackup; user interface. </para> </listitem> -<listitem><para>--autobg</para> +<listitem><para><option>--autobg</option></para> <para> -When you run &kbackup; with this option and a given .kbp profile, it will -run the same process as with --auto but _without_ showing any graphical user interface. -Therefore the suffix "bg" which stands for "background" - everything is done in the background +When you run &kbackup; with this option and a given <filename class="extension">.kbp</filename> profile, it will +run the same process as with <option>--auto</option> but <emphasis>without</emphasis> showing any graphical user interface. +Therefore the suffix <quote>bg</quote> which stands for <quote>background</quote> - everything is done in the background so this is the right option to be used when you do your backups ⪚ started by a cron job. </para> <para> -When using --autobg the output from &kbackup; - showing the progress of the backup - is written +When using <option>--autobg</option> the output from &kbackup; - showing the progress of the backup - is written to stderr. By default, the output includes just a few important messages and a summary at the end. -If you pass --verbose in addition, then you will also see each file name currently being backed up. +If you pass <option>--verbose</option> in addition, then you will also see each file name currently being backed up. </para> </listitem> </itemizedlist> @@ -378,12 +341,6 @@ If you pass --verbose in addition, then you will also see each file name current <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 &kbackup; window</title> @@ -442,17 +399,17 @@ a new profile.</action></para></listitem> <guimenu>File</guimenu> <guimenuitem>Profile Settings</guimenuitem> </menuchoice></term> -<listitem><para><action>In the settings, you can define whether the archive-slice files -start with the default name "backup" or with an alternative name. +<listitem><para>In the settings, you can define whether the archive-slice files +start with the default name <quote>backup</quote> or with an alternative name. Also you can limit the archive slice size. See chapter <link linkend="archive-slices">Archive Slices</link>. These settings are also stored into the profile. -</action></para></listitem> +</para></listitem> </varlistentry> <varlistentry> <term><menuchoice> <shortcut> -<keycombo action="simul"><keycap>Ctrl+Q</keycap></keycombo> +<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> </shortcut> <guimenu>File</guimenu> <guimenuitem>Quit</guimenuitem> @@ -479,7 +436,7 @@ When this option is activated, an icon is shown in the system tray, which reflec status of a backup operation. An animation is shown when a backup is in progress, else you see a static icon. If this option is selected, the closing of the main window will not terminate &kbackup;. -The application must be explicitly terminated by selecting the "Quit" action. +The application must be explicitly terminated by selecting the <guimenuitem>Quit</guimenuitem> action. Via the context menu of the &kbackup; system tray icon you can start and cancel a backup operation - which is the same as you can do in the main window. The tooltip on this icon also gives progress information (Number of saved files, size of the backup and @@ -493,7 +450,7 @@ the last saved file). <guimenuitem>Enable All Messages</guimenuitem> </menuchoice></term> <listitem><para><action> -Activating this entry clears all internally stored "Do not ask again" flags for +Activating this entry clears all internally stored <guilabel>Do not ask again</guilabel> flags for the dialogs shown in &kbackup; </action></para></listitem> </varlistentry> @@ -501,17 +458,12 @@ the dialogs shown in &kbackup; </para> </sect2> - -<sect2> -<title>The <guimenu>Help</guimenu> Menu</title> - -<!-- Assuming you have a standard help menu (help, what's this, about --> -<!-- &kbackup;, about KDE) then the documentation is already written. --> -<!-- The following entity is valid anywhere that a variablelist is --> -<!-- valid. --> - -&help.menu.documentation; - +<sect2 id="help-menu1"> +<title>The Help Menu</title> +<para> +&kbackup; 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> </sect1> @@ -520,10 +472,6 @@ the dialogs shown in &kbackup; <chapter id="developers"> <title>Developer's Guide to &kbackup;</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> &kbackup; can be extended by using a shell script (or any other executable) which will be started at three different points during the backup process. @@ -532,7 +480,7 @@ specific way, or do other things with the produced archive files. </para> <para> -The script to execute must be given with the --script command line option. +The script to execute must be given with the <option>--script</option> command line option. </para> <para>Here is a sample script</para> @@ -575,8 +523,8 @@ The script is always invoked with four command line arguments: <itemizedlist> <listitem><para>invocation mode</para> </listitem> <listitem><para>archive (slice) file name</para> </listitem> -<listitem><para>target directory/URL</para> </listitem> -<listitem><para>mountpoint of the target directory if it's a local dir, else an empty string</para> </listitem> +<listitem><para>target directory/&URL;</para> </listitem> +<listitem><para>mountpoint of the target directory if it's a local directory, else an empty string</para> </listitem> </itemizedlist> <para> @@ -595,7 +543,7 @@ There are three possible invocation modes: the target directory</para> <para> This can be used if you want to copy the archive slice to some additional place, ⪚ -the archive is sent to the main server (via a target URL), but you want to keep the last +the archive is sent to the main server (via a target &URL;), but you want to keep the last backup also onto the local disc. </para> </listitem> @@ -610,38 +558,15 @@ target directory</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. --> - -&reporting.bugs; -&updating.documentation; - -</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> &kbackup; </para> <para> -Program copyright © 2006 - 2009 Martin Koller <email>[email protected]</email> +Program copyright © 2006 - 2009 Martin Koller <email>[email protected]</email><!--FIXME use entities when kbackup depends on kdoctools >= 5.42--> </para> <para> @@ -652,45 +577,10 @@ Documentation Copyright © 2006 - 2009 Martin Koller &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 --> </chapter> -<appendix id="installation"> -<title>Installation</title> - - -<sect1 id="getting-kapp"> -<title>How to obtain &kbackup;</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 --> - -<para> -You can download &kbackup; from www.kde-apps.org -</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> - -</appendix> - &documentation.index; </book>
