api tutorial rewrite (grammer)
Wesley Leggette <lists-+42/j/[email protected]>
| Newsgroups | gmane.comp.sysutils.backup.dar.general |
|---|---|
| Message-ID | <1108139975.22122.1.camel@localhost> |
I've done a small rewrite to the libdar api tutorial. If you'd like you can take a look at my patch (attached). However, I do have a few questions: ----------------- Questions regarding tutorial: - Part 3: user interaction void pause (const std::string &message); Here the comments say that Don't worry about thowing an exception in your code; it will be trapped by libdar if you don't want to manage exceptions, and are using libdar in the "no exception" method. Is this to say that you can return "false" in no exception mode, or that you HAVE to throw some type of exception? What exactly would some sample code look like here? - Part 5: creating simple archive, // my_arch should have been an object instead of a // pointer to an archive object. Is this to say that libdar::archive *my_arch = should be libdar::archive my_arch = and is a typo, or is the first example correct? Does the first comment just mean that *my_arch refers to an archive object? - Part 7: listing archive contents The user_interaction class has a listing() method which provides seperate arguments for each piece of information that can be displayed: ... file type ... void listing(const std::string & flag, const std::string & perm, const std::string & uid, const std::string & gid, const std::string & size, const std::string & date, const std::string & filename, bool is_dir, bool has_children); Which argument is responsible for telling us what type of file a particular listing is? Is it the flag argument? -- Wesley Leggette <lists-+42/j/[email protected]>
api_tutorial-grammer.patch
(text/x-patch, 69.3 KB)
Index: api_tutorial.html
===================================================================
RCS file: /var/cvs/kaylix/dar/doc/api_tutorial.html,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -r1.1.1.1 -r1.2
15,23c15,20
< <div style="text-align: justify;">Libdar is a library that has been
< built from source code
< initially located in <span
< style="font-style: italic; font-weight: bold;">dar </span>command
< line application. The
< features that libdar provides are the ability to handle
< Disk ARchive (<span style="font-style: italic;">dar</span>)'s archives,
< thanks to the following operations: <br>
< </div>
---
> <div style="text-align: justify;">
> <p>The Libdar library has been built from source code originally located directly
> in the <em><strong>dar</strong></em> command line application. Libdar provides
> a complete abstraction for handling Disk ARchive (<em>dar</em>)'s archives.
> The general operations provided are:</p>
> </div>
33,53c30,45
< style="font-style: italic;">Disk ARchive</span> has been released
< under the <span style="font-style: italic;">Gnu General Public License
< </span>(GPL), and so is the code of libdar. So, to link your code with
< libdar (statically or dynamically), <span style="font-weight: bold;">your
< application must also be covered by the GPL.</span><br>
< </div>
< <br>
< <div style="text-align: justify;">This tutorial will show you how to
< use libdar from
< the API. As the <span style="font-style: italic;">dar</span> command
< line now also uses this API, looking at his code may also be
< interesting as illustration, in particular the file <span
< style="font-style: italic;">dar_suite/dar.cpp</span>.<br>
< </div>
< <br>
< <div style="text-align: justify;">The sample codes provided here are
< very simple code that could let you
< see overall process of using libdar, they may or may not compile, I
< have even not tried to, so just use them as illustration, no more. Note
< that there is a documentation
< reference for this API which is built with dar under the directory doc/html if you have Doxygen available and can be consulted on the <a href="http://dar.linux.free.fr/html/index.html">web</a>.<br>
---
> style="font-style: italic;">Disk ARchive</span> <em>and</em> libdar have been
> released under the <span style="font-style: italic;">Gnu General Public License
> </span>(GPL). All code linked to libdar (statically or dynamically), <span style="font-weight: bold;">
> must also be covered by the GPL.</span><br>
> </div>
> <br>
> <div style="text-align: justify;">This tutorial will show you how to use the libdar
> API. As <span style="font-style: italic;">dar</span> now also uses this API,
> looking at it's code may also provide a good illustration. The file <span
> style="font-style: italic;">dar_suite/dar.cpp</span> is the primary consumer.<br>
> </div>
> <br>
> <div style="text-align: justify;">The sample code provided here is solely illustrative
> and is not guarunteed to compile. More detailed API documentation is contained
> in the source code and can be compiled to the doc/html directory using Doxygen.
> The API reference is also available <a href="http://dar.linux.free.fr/html/index.html">online</a>.<br>
58c50
< <h3>conventions</h3>
---
> <h3>Conventions</h3>
60c52,55
< Dar and libdar are written in C++, and so is the libdar API. Libdar is thus easily usable with C or C++ code. For other languages, it depends on so many things (calling convention, etc.) that I would just say you are welcome to provide the necessary adaptation layer for any particular language. :-)
---
> Dar and libdar are written in C++, and so is the libdar API. While written in
> C++, libdar is easily usable with both C and C++ code. Access from other languages
> can be provided by specific bindings. I would only say that you are welcome to
> provide the necessary bindings yourself. :-)
84,86c79,80
< <div style="text-align: justify;"> or, as we
< will do in the following examples, you can explicitely use the
< namespace in front of libdar objects :<br>
---
> <div style="text-align: justify;"> or, as shown below, you can explicitly
> use the namespace in front of libdar objects :<br>
103,107c97,100
< <h4>Exceptions or not Exceptions</h4>
< <div style="text-align: justify;">For each point we will see two ways
< of using libdar.
< One, is using exception, the other is without exceptions.
< They will be displayed this way :<br>
---
> <h4>Exceptions or no Exceptions</h4>
> <div style="text-align: justify;">The library can be used with or without exceptions.
> For each example we will see sample code for both methods. To the left is with
> exceptions, to the right without:<br>
130,133c123,125
< All exceptions used by <span style="font-style: italic;">libdar</span>
< inherit from the pure virtual <span style="font-style: italic;"><span
< style="font-weight: bold;">class Egeneric</span>.</span> The only
< method you
---
> All exceptions used by <span style="font-style: italic;">libdar</span> inherit
> from the pure virtual <span style="font-style: italic;"><span
> style="font-weight: bold;">class Egeneric</span>.</span> The only method you
135,140c127,130
< style="font-style: italic; font-weight: bold;">get_message()</span>
< call,
< which returns a string explaining the reason of the
< message in a human language. The type of the error is defined by the
< class of the
< exception. Here follows all the exception classes and their meaning:<br>
---
> style="font-style: italic; font-weight: bold;">get_message()</span> call, which
> returns a message string describing the message (in human language). The type
> of the error is defined by the class of the exception. The possible exception
> types follow:<br>
150,151c140,141
< <td style="vertical-align: top;">this is the parent class of all
< exception classes (a pure virtual class)<br>
---
> <td style="vertical-align: top;"> the parent class of all exceptions (a
> pure virtual class)<br>
157,158c147
< <td style="vertical-align: top;">exception used when memory has
< been exhausted<br>
---
> <td style="vertical-align: top;">memory has been exhausted<br>
164,165c153,154
< <td style="vertical-align: top;">exception used to signal a bug.
< A bug is triggered when reaching some code that should never be reached<br>
---
> <td style="vertical-align: top;">signals a bug, which is triggered when
> reaching some code that should never be reached<br>
171,172c160,161
< <td style="vertical-align: top;">exception used when arithmetic
< error is detected when operating on infinint<br>
---
> <td style="vertical-align: top;">arithmetic error detected when operating
> on infinint<br>
178,180c167,168
< <td style="vertical-align: top;">exception used when a limitint
< overflow is detected, the maximum value of the limitint has been
< exceeded<br>
---
> <td style="vertical-align: top;">a limitint overflow is detected, indicating
> the maximum value of the limitint has been exceeded<br>
186,187c174
< <td style="vertical-align: top;">exception used to signal range
< error<br>
---
> <td style="vertical-align: top;">signals a range error<br>
193,194c180,181
< <td style="vertical-align: top;">exception used to signal
< convertion problem between infinint and string (decimal representation)<br>
---
> <td style="vertical-align: top;">signals conversion problem between infinint
> and string (decimal representation)<br>
200,201c187
< <td style="vertical-align: top;">exception used when a requested
< feature is not (yet) implemented<br>
---
> <td style="vertical-align: top;">a requested feature is not (yet) implemented<br>
207,208c193
< <td style="vertical-align: top;">exception used when hardware
< problem is found <br>
---
> <td style="vertical-align: top;">hardware problem is found <br>
214,215c199,200
< <td style="vertical-align: top;">exception used to signal that
< the user has aborted the operation <br>
---
> <td style="vertical-align: top;">signals that the user has aborted the operation
> <br>
221,222c206,207
< <td style="vertical-align: top;">exception used when an error
< concerning the treated data has been met<br>
---
> <td style="vertical-align: top;">an error concerning the treated data has
> been encountered<br>
228,229c213,214
< <td style="vertical-align: top;">exception used when the
< inter-slice user command returned an error code<br>
---
> <td style="vertical-align: top;">the script excecuted between slices returned
> an error code<br>
235,236c220,221
< <td style="vertical-align: top;">exception used to signal an
< error in the arguments given to a libdar call of the API<br>
---
> <td style="vertical-align: top;">signals an error in the arguments given
> to a libdar call of the API<br>
242,243c227,228
< <td style="vertical-align: top;">exception used when a requested
< fearture has not beed activated at compilation time<br>
---
> <td style="vertical-align: top;">a requested feature has not beed activated
> at compilation time<br>
262,263c247
< // we include this to be able to display some <br>
< // messages<br>
---
> // we'll want to display some messages<br>
270c254
< // function for simplicity of the examples<br>
---
> // function for simplicity's sake<br>
303,317c287,300
< style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code></code><code>
< <br>
< // we include this to be able to display some <br>
< // messages<br>
< #include <io.h><br>
< <br>
< // we include this header to access lidbar API<br>
< #include <dar/libdar.h><br>
< <br>
< // all sample code shown will be inside this<br>
< // function for simplicity of the examples<br>
< void my_sample_function()<br>
< {<br>
< <br>
< </code><code> libdar::U_I maj, med, min;<br>
---
> style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code></code><code>
> <br>
> // we'll want to display some messages<br>
> #include <io.h><br>
> <br>
> // we include this header to access lidbar API<br>
> #include <dar/libdar.h><br>
> <br>
> // all sample code shown will be inside this<br>
> // function for simplicity's sake<br>
> void my_sample_function()<br>
> {<br>
> <br>
> </code><code> libdar::U_I maj, med, min;<br>
353,363c336,344
< <div style="text-align: justify;">you must check that the library
< you dynamically link with is compatible with the features you will use.
< The major number must be the same as no compatibility is assured
< between two libdar versions of different major number. And, the medium
< number must be greater or equal to the one used at compilation time to
< be sure
< that all the feature you have been using are available in the libdar
< library you dynamically link with. Changes between minor versions
< correspond to bug
< fixes which does not implies any API change, so there is no constraint
< about minor number.<br>
---
> <div style="text-align: justify;">you must check that the library you've dynamically
> linked with is compatible with the features you will be using. The major
> number must be the same, for no compatibility is assured between two libdar
> versions of different major numbers. While run-time compatibility is assured
> between medium numbers, the medium number must be greater or equal to the
> one used at compilation time to be sure that all the features you want are
> available in the libdar library you dynamically linked with. Changes between
> minor versions correspond to bug fixes and is not to imply any API change,
> thus no constraints are present there.<br>
366,370c347,351
< <li style="text-align: justify;">the get_version* calls, over
< returning version information, makes important initialization tasks for
< libdar. If it is not called first, the libdar library is not
< initialized and its behavior is unpredictable. Note that you may call
< get_version* several time if you wish, and in any flavor.<br>
---
> <li style="text-align: justify;">the get_version* call, as well as returning
> version information, does important initialization tasks for libdar. If not
> called first, the libdar library will not initialized properly and its behavior
> will be unpredictable. Note that you may call get_version* several time if
> you wish, using any override.<br>
373,376c354,356
< <h2>2 - Let's see the compilation time features</h2>
< once we have called a function of the <span style="font-style: italic;">get_version*</span>
< family it is possible to access the features activated at compilation
< time:<br>
---
> <h2>2 - Let's see the available features</h2>
> once we have called a function of the <span style="font-style: italic;">get_version*</span>
> funtion it is possible to access the features activated at compilation time:<br>
435,441c415,420
< <div style="text-align: justify;">You can do what you want with the
< resulting values, like displaying the libdar available feature, or even
< filter if you don't want to continue when a particular feature is
< missing. But, that's maybe not necessary to worry here, because libdar
< will tell you if the operation you ask requires a feature that has not
< been activated at compilation time thanks to the <span
< style="font-style: italic;">Ecompile</span> exception or the <span
---
> <div style="text-align: justify;">You can do what you want with the resulting
> values. It's possible to display the available libdar features or to terminate
> if you don't find a desired feature. However, verifying that features are available
> is not strictly neccesary because libdar will tell you if an operation you call
> requires a feature that has not been activated by throwing an Ecompile exception
> or returning the <span
448,459c427,433
< <h3>The generic <span style="font-style: italic;">user_interaction</span>
< class</h3>
< To be able to report messages to the user and to be able to ask
< questions
< to the user, a special class called<span style="font-style: italic;">
< <span style="font-weight: bold;">user_interaction </span></span>has
< been introduced as first argument of the
< API calls we will see below. Rawly, <span style="font-style: italic;">user_interaction</span>
< is a pure virtual class from which you can define your own inherited
< class to have your very own implementation of the interaction with the
< user (GUI's graphical interaction, for example). You will just have to
< override four methods which prototypes follow :<br>
---
> <h3>The generic <span style="font-style: italic;">user_interaction</span> class</h3>
> To be able to report messages to the user and prompt for feedback a special class
> called<span style="font-style: italic;"> <span style="font-weight: bold;">user_interaction
> </span></span>has been introduced. Simply put, <span style="font-style: italic;">user_interaction</span>
> is a virtual class which you can derive to provide user interaction (a GUI's
> graphical interaction, for example). There are four methods whose prototypes
> you must override:<br>
466,478c440,449
< <div style="margin-left: 40px; text-align: justify;">this method is
< called by libdar to request an boolean answer from the user. The
< question is given in argument and the <span style="font-style: italic;">pause()
< </span>method must either <span style="font-weight: bold;">return</span>
< if the user agreed the question (said
< "yes" or "true"), or <span style="font-weight: bold;">throw </span>a<span
< style="font-weight: bold;"> </span><span
< style="font-style: italic; font-weight: bold;">Euser_abort</span>
< exception if the user refused the proposition<span
< style="font-weight: bold;"><span style="font-weight: bold;">. </span></span>Don't
< worry about thowing exception in your code, it will be trapped by
< libdar if you don't want to manage exceptions, and use libdar in the
< "no exception" manner.<span style="font-weight: bold;"><span
---
> <div style="margin-left: 40px; text-align: justify;">this method is called by
> libdar when the library needs a yes or no ("continue" or "kill")
> answer to a question, which is provided by the string <em>message</em>. The
> question posed by <em>pause()</em> must be answered by returning if "true"
> or throwing a <em><strong>Euser_abort</strong></em> exception if the user refused
> the proposition<span
> style="font-weight: bold;"><span style="font-weight: bold;">. </span></span>Don't
> worry about thowing an exception in your code; it will be trapped by libdar
> if you don't want to manage exceptions, and are using libdar in the "no exception"
> method.<span style="font-weight: bold;"><span
486,489c457,459
< <div style="margin-left: 40px; text-align: justify;">libdar call this
< method to display an informational message to the user. It may not
< always be a warning as the name suggests, sometimes it is just
< normal information.<br>
---
> <div style="margin-left: 40px; text-align: justify;">libdar calls this method
> to display an informational message to the user. It is not always a warning
> as the name suggests, but sometimes just normal information.<br>
496,504c466,473
< <div style="margin-left: 40px; text-align: justify;">This call is used
< to get a arbitrary answer from the user. As this is actually mainly
< used to get a password from the user (when no password has been suplied
< for an encrypted archive), the <span style="font-style: italic;">echo </span>argument
< tells that the user answer shall or shall not be displayed on screen.
< If <span style="font-style: italic;">echo</span> is set to "false" the
< implementation of <span style="font-style: italic;">get_string() </span>must
< hide the
< character typed by the user in answer to the displayed question.<br>
---
> <div style="margin-left: 40px; text-align: justify;">This call is used to get
> a arbitrary answer from the user. This is mainly used to get a password from
> the user (when no password has been supplied for an encrypted archive), the
> <span style="font-style: italic;">echo </span>argument indicates if the user
> response should be displayed on the screen (again, very useful for handling
> password input). If <span style="font-style: italic;">echo</span> is set to
> "false" the implementation of <span style="font-style: italic;">get_string()
> </span>should hide the characters typed by the user.<br>
513,526c482,487
< <div style="margin-left: 40px; text-align: justify;">This is a
< technical call that must return a copy of the "this" object, like would
< do the copy constructor. Why not simply use the copy constructor?
< because libdar may need to keep an internal copy of the object. But the
< object which class is an inherited class of <span
< style="font-style: italic;">user_interaction </span>is not know by
< his real class but through a <span style="font-style: italic;">user_interaction
< pointer </span>type. So invoking the copy constructor of the <span
< style="font-style: italic;">user_interaction</span>
< class will make the new object copied only for the <span
< style="font-style: italic;">user_interaction </span>part, this may
< cause a crash when using the object copy. A simple implementation of
< this method should be something like this (even if you don't want to
< use exceptions):<br>
---
> <div style="margin-left: 40px; text-align: justify;">A deep copy operation must
> be implemented here. This is because libdar stores the reference to the <span
> style="font-style: italic;">user_interaction</span> class as a pointer but may
> want to keep a complete internal copy at some point. A simple implementation
> of this method should be something like this (even if you don't want to use
> exceptions):<br>
528c489,490
< <div style="margin-left: 40px;"><code></code><code></code>
---
> </div>
> <code></code><code></code>
555,569c517,530
< <div style="text-align: justify;"><span style="font-style: italic;">A </span>inherited
< class from<span style="font-style: italic;"> user_interaction</span>
< called <span style="font-weight: bold; font-style: italic;">user_interaction_callback</span>
< proposes an implementation of the user interaction based on callback
< functions. This just replaces the three interactions methods (pause,
< warning and get_string) by three normal functions of your choice, which
< must be given to the <span style="font-style: italic;">user_interaction_callback</span>'s
< constructor and you don't have to consider the <span
< style="font-style: italic;">clone()</span> method. But you still need
< to implement theses callback functions. For a real
< example, I propose you to have a look at what is done for<span
< style="font-style: italic;"> dar</span>'s command line. <span
< style="font-style: italic;">dar</span>'s user interaction is done
< thanks to an object of the <span style="font-style: italic;">user_interaction_callback</span>
< class and three static functions of the module<span
---
> <div style="text-align: justify;">An inherited class from<span style="font-style: italic;">
> user_interaction</span> called <span style="font-weight: bold; font-style: italic;">user_interaction_callback</span>
> provides an implementation of the user interaction based on callback functions.
> This allows you to replace the three interactions methods (pause, warning and
> get_string) by three normal functions of your choice, which must be given to
> the <span style="font-style: italic;">user_interaction_callback</span>'s constructor.
> The <span
> style="font-style: italic;">clone()</span> method is implemented internally,
> leaving only the three callback functions to be implemented. Look at <span
> style="font-style: italic;"> dar</span>'s command line code for a practical example.
> <span
> style="font-style: italic;">dar</span>'s user interaction code is implemented
> using an instance of <span style="font-style: italic;">user_interaction_callback</span>
> and three static functions in the module<span
572,573c533,534
< Just a note however about the <span style="font-style: italic;">contextual</span>
< value present in the arguments of theses callback functions :<br>
---
> Pay atttention to the <span style="font-style: italic;">contextual</span> value
> present in the arguments of theses callback functions :<br>
588c549
< // libdar. But all share the same callback functions<br>
---
> // libdarut all share the same callback functions<br>
649,658c610,617
< <div style="text-align: justify;">Mask are used to define which file
< are to be considered and which are
< not to be considered. Libdar implements masks as several classes that
< all inherit from a pure virtual class that defines the way masks are
< used. This root class is the <span
< style="font-weight: bold; font-style: italic;">class
< mask</span> and provides the <span style="font-style: italic;">is_covered()</span>
< method for libdar to know which files to consider. Here follows the
< different basic masks classes you
< can use to build very complex masks:<br>
---
> <div style="text-align: justify;">Mask are used to define which files will be
> considered and which will not. Libdar implements masks as several classes that
> all inherit from a virtual class that defines the way masks are used. This root
> class is the <span
> style="font-weight: bold; font-style: italic;">class mask</span> and provides
> the <span style="font-style: italic;">is_covered()</span> method which libdar
> uses to determine which files are considered. There are many different basic
> masks classes you can use to build fairly complex masks:<br>
718,720c677,680
< <td style="vertical-align: top;">string matches if it is subdir
< of mask or mask is a subdir of expression<br>
< </td>
---
> <td style="vertical-align: top;"><p>string matches if it is subdirectory
> of mask or is a directory that contains the specified path itself<br>
> </p>
> </td>
760,761c720,721
< // any file beginning by 'A' or by 'a'
< and ending by '~' will be elected by this mask<br>
---
> // any file beginning by 'A' or by 'a'
> and ending by '~' will be selected by this mask<br>
773,774c733,734
< // and any file that has /home/joe as
< subdirectory, that is:<br>
---
> // and any directory that contains /home/joe,
> meaning<br>
777,780c737,740
< // the second argument here too is the
< case sensitivity (so here<br>
< // "/HoMe" will not be elected by
< this mask.<br>
---
> // here, the second argument is also case
> sensitivity (so<br>
> // "/HoMe" will not be selected by
> this mask.<br>
785,786c745,746
< </code><code> // m5 will now match
< only files that are elected by both m2 AND m4</code><br>
---
> </code><code> // m5 will now match only
> files that are selected by both m2 AND m4</code><br>
799,802c759,762
< // but we could do the same with a
< "ou_mask" that realizes the OR operation<br>
< // and we would get an silly equivalent
< of m1 (a mask that matches any files)<br>
---
> // but we could do the same with an "ou_mask"
> and would get a silly<br>
> // counterpart of m1 (a mask that matches
> any files)<br>
808,811c768,771
< // last point, the NOT, AND and OR
< operation can be used recurively :<br>
< </code><code> // even this, is
< possible where two ask are used as reference for each other !</code><br>
---
> // lastly, the NOT, AND and OR operation
> can be used recursively.<br>
> </code><code> // Frankly, it's possible
> to have masks reference eachother!</code><br>
820,822c780,781
< Now that you see a bit more all the power of masks, you must know that
< in
< quite all libdar operations two masks are required: <br>
---
> Now that you've seen the power of these masks, you should know that in libdar
> there are two masks that are required: <br>
824,837c783,793
< <li style="text-align: justify;">The first mask is used against
< filenames, but is not applied to directories, nor it is applied to the
< path part of the filenames. This first mask may be any
< combinaison of the masks seen previously, it will only be applied to
< socket, named pipes, symbolic links, char or block devices, plain
< files, but not to directories as we said. This way you can filter by
< type of file
< you want or don't want to save, restore, list, compaire, compress and
< so on.</li>
< <li style="text-align: justify;">The second mask is applied to any
< file including directories and including the path part of the filename.
< So with it you can prune directories, or in
< the other way restrict the operation to a particula subdirectory, as
< well as to a particular plain file for example.<br>
---
> <li style="text-align: justify;">The first mask is used against the names of
> all files except directories. It is applied solely to the names themselves
> (not the file path). This mask may be any combination of the masks seen previously;
> it will only be applied to socket, named pipes, symbolic links, char or block
> devices, plain files, but again not to directories. This way you can filter
> by file type for save, restore, list, compare, and compress, and other library
> operations.</li>
> <li style="text-align: justify;">The second mask is applied to any file including
> directories, including the path part of the filename. So with it you can prune
> directories, or in any other way restrict the operation to a particular subdirectory,
> as well as to a particular plain file for example.<br>
843,844c799
< Now that we have seen masks and exceptions classes let's start the real
< thing:<br>
---
> Now that we have seen masks and exceptions let's start the real thing:<br>
853,970c808,934
< style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code>
< // creating an archive is simple, it is just<br>
< // calling the "create" constructor of the archive<br>
< // class. It may be used for full or differential<br>
< // archive. But we will see differential later.<br>
< <br>
< // my_arch should have been an object instead of a<br>
< // pointer to an archive object. <br>
< <br>
< libdar::user_interaction_callback dialog =
< libdar::user_interaction_callback(ptr1, ptr2, ptr3);<br>
< // where ptr1, ptr2 and ptr3 are three callback<br>
< // functions.<br>
< libdar::statistics ret;<br>
< // we will see this structure a bit further<br>
< <br>
< libdar::archive *my_arch = <br>
< new <span style="font-weight: bold;">libdar::archive</span>(dialog,
< <br>
< "/home", // saving all under this "root"<br>
< "/tmp", // where the slices will go<br>
< NULL, // we do a full
< backup for now <br>
< libdar::not_mask(simple_mask("*~", true)), <br>
< //
< we don't save the files ending with<br>
< // '~' this does not concern
< directories<br>
< libdar::bool_mask(true), <br>
< //
< all directories and files not rejected <br>
< //
< by the previous mask are saved<br>
< "my_archive", <br>
< //
< the basename of the slices <br>
< "dar", // dar's slice extensions<br>
< true, // we allow slice overwriting<br>
< true, // but ask to be warned in such
< occurence<br>
< false, // we don't want a verbose output<br>
< false, // nor we want to pause between slices<br>
< true, // rejected directory will be
< saved as<br>
< // empty (no directory is
< rejected so<br>
< // here there is no
< importance for that<br>
< // parameter)<br>
< libdar::gzip // the archive will be compressed<br>
< // using gzip <br>
< 9, // at maximum
< compression level <br>
< 0, // no slicing is
< done,<br>
< 0, // so the first slice
< size must also be <br>
< //
< set to zero <br>
< true, // root EA will be saved if present<br>
< true, // user EA too<br>
< "", // no script will be
< executed between<br>
< // slices (as there is no
< slicing) <br>
< libdar::crypto_blowfish, <br>
< //
< the blowfish strong encryption <br>
< //
< will be used<br>
< "", // as the password is
< not given here <br>
< //
< (empty string is not a valid password) <br>
< //
< it will be asked interactively to the<br>
< // user through the dialog<br>
< // user_interaction object<br>
< 20480, // the block of encryption will be<br>
< // 20 kbytes<br>
< libdar::not_mask(libdar::simple_mask("*gz")), <br>
< //
< all files will be compressed except<br>
< // those ending by "gz"<br>
< 800, // file which size is below
< 800 bytes<br>
< // will not be compressed<br>
< false, // all files will be saved whatever is<br>
< // the nodump flag value<br>
< false, // as we make a full backup this <br>
< //
< "ignore_owner" parameter is useless <br>
< 0, // hourshift is
< useless here as we make <br>
< // a
< full backup<br>
< false, // we will make a real archive not a<br>
< // dry-run operation<br>
< true, // dar will set back the access
< time of<br>
< // file it opens, which will
< change the<br>
< // ctime date of theses files
< <br>
< false, // we may change of filesystem if<br>
< // necessary<br>
< ret); // this value is returned by libdar</code><br>
< </td>
< <td
< style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code></code><code>
< // creating an archive is simple, it is just<br>
< // calling the "create" constructor of the archive<br>
< // class. It may be used for full or differential<br>
< // archive. But we will see differential later.<br>
< <br>
< // my_arch should have been an object instead of a<br>
< // pointer to an archive object. <br>
< </code><code><br>
---
> style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><p><code>
> // creating an archive is simple; it is just<br>
> // a matter of calling the "create" constructor<br>
> // of the archive class. It may be used for full or<br>
> // differential archives. We'll see an example of<br>
> // of differential archives later.<br>
> <br>
> // my_arch should have been an object instead of a<br>
> // pointer to an archive object. <br>
> <br>
> libdar::user_interaction_callback dialog = libdar::user_interaction_callback(ptr1,
> ptr2, ptr3);<br>
> // where ptr1, ptr2 and ptr3 are three callback<br>
> // functions.<br>
> libdar::statistics ret;<br>
> // we will see this structure a bit further<br>
> <br>
> libdar::archive *my_arch = <br>
> new <span style="font-weight: bold;">libdar::archive</span>(dialog,
> <br>
> "/home", // saving all under this "root"<br>
> "/tmp", // where the slices will
> go<br>
> NULL, // we do a full
> backup for now <br>
> libdar::not_mask(simple_mask("*~", true)),
> <br>
> //
> we don't save the files ending with<br>
> // '~' this does not concern
> directories<br>
> libdar::bool_mask(true), <br>
> //
> all directories and files not rejected <br>
> //
> by the previous mask are saved<br>
> "my_archive", <br>
> //
> the basename of the slices <br>
> "dar", // dar's slice extensions<br>
> true, // we allow slice overwriting<br>
> true, // but ask to be warned in such
> occurence<br>
> false, // we don't want a verbose output<br>
> false, // nor do we want to pause between slices<br>
> true, // rejected directories will be
> saved as<br>
> // empty (no directory is
> rejected so<br>
> // here there is no importance
> for that<br>
> // parameter)<br>
> libdar::gzip // the archive will be compressed<br>
> // using gzip <br>
> 9, // at maximum compression
> level <br>
> 0, // no slicing is
> done,<br>
> 0, // so the first slice
> size must also be <br>
> //
> set to zero <br>
> true, // root EA will be saved if present<br>
> true, // user EA too<br>
> "", // no script will be
> executed between<br>
> // slices (as there is no
> slicing) <br>
> libdar::crypto_blowfish, <br>
> //
> the blowfish strong encryption <br>
> //
> will be used<br>
> "", // as the password is
> not given here <br>
> //
> (empty string is not a valid password) <br>
> //
> it will be queried interactively<br>
> // through the dialog<br>
> // user_interaction object<br>
> 20480, // the block of encryption will be<br>
> // 20 kbytes<br>
> libdar::not_mask(libdar::simple_mask("*gz")),
> <br>
> //
> all files will be compressed except<br>
> // those ending with "gz"<br>
> 800, // files whose sized is below
> 800 bytes<br>
> // will not be compressed<br>
> false, // all files will be saved regardless
> of<br>
> // the nodump flag value<br>
> false, // as we're making a full backup this
> <br>
> //
> "ignore_owner" parameter is useless <br>
> 0, // hourshift is
> useless here as we're making<br>
> //
> a full backup<br>
> false, // we will make a real archive not a<br>
> // dry-run operation<br>
> true, // dar will set back the access
> time of<br>
> // file it opens, which will
> change the<br>
> // ctime date of theses files
> <br>
> false, // we may cross to other filesystems
> if<br>
> // necessary<br>
> ret); // this value is returned by libdar</code><br>
> </p>
> </td>
> <td
> style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code></code><code>
> // creating an archive is simple; it is just<br>
> // a matter of calling the "create" constructor<br>
> // of the archive class. It may be used for full or<br>
> // differential archives. We'll see an example of<br>
> // of differential archives later.<br>
> <br>
> // my_arch should have been an object instead of a<br>
> // pointer to an archive object. <br>
> </code><code><br>
983c947
< <span style="font-weight: bold;">libdar::create_archive_noexcept</span>(dialog,</span></code><span
---
> <span style="font-weight: bold;">libdar::create_archive_noexcept</span>(dialog,</span></code><span
985,1083c949,1048
< "/home", // saving all under this "root"<br>
< "/tmp", // where the slices will go<br>
< NULL, // we do a full
< backup for now <br>
< libdar::not_mask(simple_mask("*~", true)), <br>
< //
< we don't save the files ending with<br>
< // '~' this does not concern
< directories<br>
< libdar::bool_mask(true), <br>
< //
< all directories and files not rejected <br>
< //
< by the previous mask are saved<br>
< "my_archive", <br>
< //
< the basename of the slices <br>
< "dar", // dar's slice extensions<br>
< true, // we allow slice overwriting<br>
< true, // but ask to be warned in such
< occurence<br>
< false, // we don't want a verbose output<br>
< false, // nor we want to pause between slices<br>
< true, // rejected directory will be
< saved as<br>
< // empty (no directory is
< rejected so<br>
< // here there is no
< importance for that<br>
< // parameter)<br>
< libdar::gzip // the archive will be compressed<br>
< // using gzip <br>
< 9, // at maximum
< compression level <br>
< 0, // no slicing is
< done,<br>
< 0, // so the first slice
< size must also be <br>
< //
< set to zero <br>
< true, // root EA will be saved if present<br>
< true, // user EA too<br>
< "", // no script will be
< executed between<br>
< // slices (as there is no
< slicing) <br>
< libdar::crypto_blowfish, <br>
< //
< the blowfish strong encryption <br>
< //
< will be used<br>
< "", // as the password is
< not given here <br>
< //
< (empty string is not a valid password) <br>
< //
< it will be asked interactively to the<br>
< // user through the dialog<br>
< // user_interaction object<br>
< 20480, // the block of encryption will be<br>
< // 20 kbytes<br>
< libdar::not_mask(libdar::simple_mask("*gz")), <br>
< //
< all files will be compressed except<br>
< // those ending by "gz"<br>
< 800, // file which size is below
< 800 bytes<br>
< // will not be compressed<br>
< false, // all files will be saved whatever is<br>
< // the nodump flag value<br>
< false, // as we make a full backup this <br>
< //
< "ignore_owner" parameter is useless <br>
< 0, // hourshift is
< useless here as we make <br>
< // a
< full backup<br>
< false, // we will make a real archive not a<br>
< // dry-run operation<br>
< true, // dar will set back the access
< time of<br>
< // file it opens, which will
< change the<br>
< // ctime date of theses files
< <br>
< false, // we may change of filesystem if<br>
< // necessary<br>
< ret, // this value is returned by
< libdar<br>
< exception, // thisgives the status of the call<br>
< except_msg); // and in case of error the cause.<br>
< <br>
< if(exception != LIBDAR_NOEXCEPT)<br>
< std::cout << "an error occured: " << except_msg <br>
<
< <<
< std::endl;<br>
< <br>
< </code></span> </td>
---
> "/home", // saving all under this "root"<br>
> "/tmp", // where the slices will
> go<br>
> NULL, // we do a full
> backup for now <br>
> libdar::not_mask(simple_mask("*~", true)), <br>
> //
> we don't save the files ending with<br>
> // '~' this does not concern
> directories<br>
> libdar::bool_mask(true), <br>
> //
> all directories and files not rejected <br>
> //
> by the previous mask are saved<br>
> "my_archive", <br>
> //
> the basename of the slices <br>
> "dar", // dar's slice extensions<br>
> true, // we allow slice overwriting<br>
> true, // but ask to be warned in such occurence<br>
> false, // we don't want a verbose output<br>
> false, // nor do we want to pause between slices<br>
> true, // rejected directories will be saved
> as<br>
> // empty (no directory is rejected
> so<br>
> // here there is no importance
> for that<br>
> // parameter)<br>
> libdar::gzip // the archive will be compressed<br>
> // using gzip <br>
> 9, // at maximum compression
> level <br>
> 0, // no slicing is done,<br>
> 0, // so the first slice size
> must also be <br>
> //
> set to zero <br>
> true, // root EA will be saved if present<br>
> true, // user EA too<br>
> "", // no script will be executed
> between<br>
> // slices (as there is no slicing)
> <br>
> libdar::crypto_blowfish, <br>
> //
> the blowfish strong encryption <br>
> //
> will be used<br>
> "", // as the password is not
> given here <br>
> //
> (empty string is not a valid password) <br>
> //
> it will be queried interactively <br>
> // through the dialog<br>
> // user_interaction object<br>
> 20480, // the block of encryption will be<br>
> // 20 kbytes<br>
> libdar::not_mask(libdar::simple_mask("*gz")),
> <br>
> //
> all files will be compressed except<br>
> // those ending with "gz"<br>
> 800, // files whose size is below
> 800 bytes<br>
> // will not be compressed<br>
> false, // all files will be saved regardless
> of<br>
> // the nodump flag value<br>
> false, // as we're making a full backup this
> <br>
> //
> "ignore_owner" parameter is useless <br>
> 0, // hourshift is useless
> here as we're making<br>
> //
> a full backup<br>
> false, // we will make a real archive not a<br>
> // dry-run operation<br>
> true, // dar will set back the access time
> of<br>
> // file it opens, which will
> change the<br>
> // ctime date of theses files
> <br>
> false, // we may cross to other filesystems if<br>
> // necessary<br>
> ret, // this value is returned by
> libdar<br>
> exception, // this gives the status of the call<br>
> except_msg); // and in case of error the cause.<br>
> <br>
> if(exception != LIBDAR_NOEXCEPT)<br>
> std::cout << "an error occured: " << except_msg <br>
> <<
> std::endl;<br>
> <br>
> </code></span> </td>
1089,1104c1054,1068
< <div style="text-align: justify;">When creating an archive, the created
< archive object can be used only as reference for a isolation or for
< differential backup. You cannot use it for restoration, listing,
< comparison, because the underlying file descriptors are openned in
< write only mode. An implementation which uses file descriptors in
< read-write access is not possible and is not a good idea anyway. Why ?
< Because, for example, if you want to test your just created archive,
< using the just created object would make the testing rely on
< information stored in virtual memory (the archive contents, the data
< location of a file, etc.), not in the file archive. If some corruption
< occured in the file you would not notice it.<br>
< </div>
< <br>
< So to totally complete the archive creation we must destroy the archive
< object we have just created, which have also as consequence to close
< any file descriptor used by the object :<br>
---
> <div style="text-align: justify;">When creating an archive, the created archive
> object can be used only as reference for a isolation or for differential backups.
> You cannot use it for restoration, listing, or comparison, because the underlying
> file descriptors are openned in write only mode. An implementation which uses
> file descriptors in read-write access is not possible and is not a good idea
> anyway. Why? Because, for example, if you want to test the newly created archive,
> using the newly created object would make the test rely on information stored
> in virtual memory (the archive contents, the data location of a file, etc.),
> not on the file archive itself. If some corruption occured in the file you would
> not notice it.<br>
> </div>
> <br>
> So to totally complete the archive creation we must destroy the archive object
> we have just created, which will also close any file descriptors used by the object
> :<br>
1206,1207c1170,1171
< Now that we have openned the archive we can perform all operation on
< it, let's thus start by testing the archive coherence:<br>
---
> Now that we have opened the archive we can perform any operation on it. Let's
> thus start by testing the archive coherence:<br>
1265,1273c1229,1236
< <div style="text-align: justify;">We have tested the archive, but have
< not yet seen the libdar::statistics variable. It has been used to
< create an archive as well as here to test it. This structure
< reports the number of files treated, as well as the number files with
< error and the type of error. You can have a look at the API reference
< guide for more information about the use of different field. Here is an
< example, which relies on the <span style="font-style: italic;"><span
< style="font-weight: bold;">class deci</span> </span>to display the
< value of an infinint variable:<br>
---
> <div style="text-align: justify;">We have tested the archive, but have not yet
> seen the libdar::statistics variable. It can be used when creating an archive
> as well as when testing it. This structure reports the number of files
> treated, as well as the number files with errors and the type of error. You
> can have a look at the API reference guide for more information about the uses
> of different fields. Here is an example, which relies on the <span style="font-style: italic;"><span
> style="font-weight: bold;">class deci</span> </span>to display the value of an
> infinint variable:<br>
1293c1256
< // or much more simple (but totally equivalent):<br>
---
> // or much simpler (but totally equivalent):<br>
1366c1329,1330
< <div style="text-align: justify;">The listing will be done calling the<span
---
> <div style="text-align: justify;">By default the library will complete the listing
> by calling the<span
1368,1379c1332,1342
< style="font-style: italic;">dialog</span> object once for each file to
< list. This may not be very interesting because you will have just a
< string for each file, and it would require some parsing if you would
< like to split the listing in column, or display only filenames first
< and have other information available to the user in another way. The
< solution to this problem is to change the <span
< style="font-style: italic;">user_interaction</span> object.<br>
< <br>
< The <span style="font-style: italic;">user_interaction</span> class
< has a<span style="font-style: italic;"> </span><span
< style="font-weight: bold; font-style: italic;">listing()</span> method
< which provides as much arguments as different information to display:<br>
---
> style="font-style: italic;">dialog</span> object one time for each file listed.
> The warning text will consist of a string for each file with the relavant information
> in columns that would need to be parsed if individual information was desired.
> This may not be appropriate for you and as such there is another way to get
> listing information. This requires a simple reimplementation of the <em>user_interaction</em>
> object.<br>
> <br>
> The <span style="font-style: italic;">user_interaction</span> class has a<span style="font-style: italic;">
> </span><span
> style="font-weight: bold; font-style: italic;">listing()</span> method which
> provides seperate arguments for each piece of information that can be displayed:<br>
1393,1401c1356,1363
< In the <span style="font-style: italic;">user_interaction</span> class
< (a pure virtual class), the <span style="font-style: italic;">listing()</span>
< method is not a pure virtual method, so you are not obliged to
< overwrite it, but it has just an empty implemtation so it does nothing.
< You understand now that, by default, this method is not used. To
< activate it, you must call <span style="font-style: italic;">
< set_use_listing(true) </span>protected method and of course you will
< have to ovewrite the <span style="font-style: italic;">listing()</span>
< method to have a less silly behavior:<br>
---
> In the <span style="font-style: italic;">user_interaction</span> class (a virtual
> class), the <span style="font-style: italic;">listing()</span> method is not
> a pure virtual method, so you are not obliged to overwrite it, but it has just
> an empty implemtation so it does nothing. You understand now that, by default,
> this method is not used. To activate it, you must call <span style="font-style: italic;">
> set_use_listing(true) </span>protected method and of course you will have to
> ovewrite the <span style="font-style: italic;">listing()</span> method to have
> a less silly behavior:<br>
1474,1475c1436,1437
< style="font-style: italic;">op_listing()</span> exactly as we did in
< the simple way, but just replacing the <span
---
> style="font-style: italic;">op_listing()</span> exactly as we did before, only
> replacing the <span
1477,1479c1439,1440
< style="font-style: italic;">my_user_interaction</span> class, would
< make this <span style="font-style: italic;">listing()</span> method
< called for each file to be listed, in place of the <span
---
> style="font-style: italic;">my_user_interaction</span> class. Then this <span style="font-style: italic;">listing()</span>
> method will be called for each file to be listed, in place of the <span
1483,1491c1444,1452
< <div style="text-align: justify;">As seen at the beginning of this
< tutorial too, there is a children class of <span
< style="font-style: italic;">user_interaction</span> based on callback
< functions which is called <span style="font-style: italic;">user_interaction_callback</span>.
< The <span style="font-style: italic;">listing()</span> method must
< also be activated here. This is done automatically when you give a
< callback function to the object, thanks to the <span
< style="font-weight: bold; font-style: italic;">set_listing_callback()</span>
< method :<br>
---
> <div style="text-align: justify;">As seen at the beginning of this tutorial, there
> is a child class of <span
> style="font-style: italic;">user_interaction</span> based on callback functions
> which is called <span style="font-style: italic;">user_interaction_callback</span>.
> The <span style="font-style: italic;">listing()</span> method must also be activated
> here. This is done automatically when you give a callback function to the object,
> thanks to the <span
> style="font-weight: bold; font-style: italic;">set_listing_callback()</span>
> method :<br>
1563,1564c1524,1525
< // will use this <span style="font-style: italic;">dialog
< </span>object for listing the archive contents.<br>
---
> // use this <span style="font-style: italic;">dialog </span>object
> for listing the archive contents.<br>
1573,1575c1534,1536
< comparison is realized by calling the<span
< style="font-weight: bold; font-style: italic;"> op_diff</span> method
< of the <span style="font-style: italic;">class archive</span>.<br>
---
> We can compare file in an archive with the filesystem by calling the<span
> style="font-weight: bold; font-style: italic;"> op_diff</span> method of the
> <span style="font-style: italic;">class archive</span>.<br>
1676c1637
< simple, no ?<br style="font-style: italic;">
---
> Simple, no?<br style="font-style: italic;">
1678c1639
< restoration of files is done by calling the <span
---
> Restoration of files is done by calling the <span
1680,1682c1641,1642
< style="font-weight: bold; font-style: italic;">op_extract</span>
< method of archive class.<br>
< <br>
---
> style="font-weight: bold; font-style: italic;">op_extract</span> method of <em>class
> archive</em>.<br>
1811,1826c1771,1785
< <div style="text-align: justify;">OK, I know, <span
< style="font-style: italic;">catalogue </span>is
< not an english word (one would rather write <span
< style="font-style: italic;">catalog</span>), but that's the name of
< the C++ class used in
< libdar, so we will keep using it here. Note that you don't have to
< directly access to this class.<br>
< </div>
< <br>
< <div style="text-align: justify;">Isolating the catalogue creates a new
< archive that only contains the list of files and their attributes
< (ownership, dates, size, etc.), but no data and no EA are stored in it.
< It is very similar to the same archive one get if he would made a
< differential backup of a filesystem that has not changed since the
< archive of reference. The usage is very similar to the archive
< creation, but it uses a different constructor that has less arguments :<br>
---
> <div style="text-align: justify;">Ok, I know, <span
> style="font-style: italic;">catalogue </span>is not an English word (one would
> rather write <span
> style="font-style: italic;">catalog</span>), but that's the name of the C++ class
> used in libdar, so we will keep using it here. Note that you don't have to directly
> access to this class (if you really don't like French).<br>
> </div>
> <br>
> <div style="text-align: justify;">Isolating the catalogue creates a new archive
> that only contains the list of files and their attributes (ownership, dates,
> size, etc.), but no data and no EA are stored in it. It is very similar to the
> same archive one gets if he makes a differential backup of a filesystem that
> has not changed since the creation of a reference archive. The usage is very
> similar to the archive creation, but it uses a different constructor that has
> less arguments :<br>
1988,2002c1947,1960
< style="font-style: italic;">my_arch</span> is a read-only object
< created by the "read" constructor. You can do any operations with it,
< like file restoration, file comparison, archive testing, as we have
< done in the previous paragraphs. The second archive object is <span
< style="font-style: italic;">my_cat</span> which is a write only
< object. It can only be used as reference for another backup (a
< differential backup) or as a reference for a subsequent catalogue
< isolation (which would just clone the already isolated catalogue
< object, here).<br>
< <br>
< Note, that an isolated catalogue can be tested, compared with
< filesystem, and even you can try to restore files from it. But as there
< is no data associated with files contents, dar will not restore any
< file from it, of course. So for now we will just destroy the extracted
< catalogue object, for all its file descriptors to be closed:<br>
---
> style="font-style: italic;">my_arch</span> is a read-only object created by the
> "read" constructor. You can do any operations with it, like file restoration,
> file comparison, archive testing, as we have done in the previous sections.
> The second archive object is <span
> style="font-style: italic;">my_cat</span> which is a write only object. It can
> only be used as a reference for another backup (a differential backup) or as
> a reference for a subsequent catalogue isolation (which would just clone the
> already isolated catalogue object here).<br>
> <br>
> Note that, if desired, an isolated catalogue can be tested, compared with the
> filesystem, and you can even try to restore files from it. But as there is no
> data associated with the files contents, dar will not restore any files from
> it, of course. So for now we will just destroy the extracted catalogue object,
> so that all its file descriptors are closed:<br>
2034,2035c1992,1993
< and we keep the <span style="font-style: italic;">my_arch</span>
< object for our last operation :<br>
---
> and we keep the <span style="font-style: italic;">my_arch</span> object for
> our last operation:<br>
2038,2045c1996,2002
< <div style="text-align: justify;">This operation is the same as the
< first one we did (archive creation). You have maybe noted that an
< argument was set to <span style="font-style: italic;">NULL</span>,
< here we will give it the value of <span style="font-style: italic;">my_arch
< </span>which means that <span style="font-style: italic;">my_arch</span>
< will become the archive of reference for the archive we will create. If
< we had not destroyed <span style="font-style: italic;">my_cat </span>above,
< we could have been using it in place of <span
---
> <div style="text-align: justify;">This operation is the same as the first one
> we did (archive creation). Perhaps you have noted that an argument was set to
> <span style="font-style: italic;">NULL</span>. Here we will pass it <span style="font-style: italic;">my_arch
> </span>which means that <span style="font-style: italic;">my_arch</span> will
> become the reference archive for the archive we will create. If we had not destroyed
> <span style="font-style: italic;">my_cat </span>above, we could have used it
> in place of <span
2260,2261c2217,2218
< As previously my_other_arch is a write only object that we won't need
< anymore. So we destroy it:<br>
---
> As previously, my_other_arch is a write only object that we won't need anymore.
> So we destroy it:<br>
2295,2296c2252,2253
< So, we are at the end of the tutorial, but still remains an object we
< need to destroy to cleanly release the memory used :<br>
---
> So, we are at the end of the tutorial. We still have an object we need to destroy
> to cleanly release the memory used:<br>
2328,2329c2285,2286
< For more detailed information about the API you have the API reference
< guide, built from source code by Doxygen.<br>
---
> For more detailed information about the API you can build the API documentation
> from the source code using Doxygen.<br>