[kde-doc-english] Outdated man page policy?

[Raphael Kubo da Costa]

2009/9/6 Burkhard Lück <lueck at hube-lueck.de>:
> Am Sonntag 06 September 2009 20:13:48 schrieb Raphael Kubo da Costa:
>> 2009/9/6 Allen Winter <winter at kde.org>:
>> > On Saturday 05 September 2009 5:56:30 pm Raphael Kubo da Costa wrote:
>> >> Hi there,
>> >>
>> >> I'm one of the Ark maintainers, and while looking at bug 206284, it
>> >> came to my attention that there is a man page for ark which was
>> >> written in 2005 and has never been updated. I was thinking of removing
>> >> it altogether, as it is likely not to be kept up-to-date.
>> >>
>> >> I tried to look for some kind of policy for this over Techbase, but
>> >> didn't find anything. So my question is whether I can freely remove
>> >> that man page from kdeutils/doc/ark or if it should remain there, even
>> >> if not up-to-date and likely to confuse some users (besides, not many
>> >> KDE applications seem to have man pages).
>> >
>> > Raphael,
>> >
>> > I think we have general policy that "no documentation is better than
>> > wrong documentation".
>> >
>> > Personally, I like man pages and wish we had at least basic man pages for
>> > all the apps. But if don't want to support a man page for Ark, then
>> > certainly you should remove the old, outdated file(s).
>>
>> Hi, Allen,
>>
>> Is it up to the application's maintainer to keep the man page and
>> other pieces of documentation updated, or is there any way the doc
>> team can help me? I could try to update the man page, but I've never
>> done anything related to DocBook, nor do I think I'll remember to do
>> that very often.
>>
> Raphael,
> just send some plain text with an updated man page, I can markup it quickly to
> docbook and move it into svn documentation and into the i18n tool chain.
>
> You don't need to deal with docbook.

Hi there,

Sorry for taking so long to answer. I'm finally attaching an updated man page.

I'm not sure if the language is as friendly as possible, so feel free
to edit it (or add/remove sections if necessary). I also merged the
Authors and Author section. Also feel free to add yourself to the
Authors list.

When you're done, please let me know to close the bug report.

Thanks!
-------------- next part --------------
= NAME =
ark - KDE Archiving tool


= SYNOPSYS =
ark [-b [-a] [-e]] [-c [-f suffix] [-p] [-t file]]
    [-d] [-o directory]


= DESCRIPTION =
Ark is a program for managing various compressed file formats within
KDE. Archives can be viewed, extracted, created and modified with Ark.
The program can handle various formats such as tar, gzip, bzip2, zip
and rar (when the appropriate libraries or command-line programs are
installed).


= OPERATION MODES =
Ark can be used either as a stand-alone GUI program as well as a
command-line program in order to perform some specific tasks.

If invoked without the -b (--batch) or -c (--add) options, Ark is started
as a normal GUI program.

When the -b (--batch) option is used, Ark can be used to extract the
contents of one or more files directly from the command-line, without
launching its GUI.

When the -c (--add) option is used, Ark prompts for files that should
be added to a new archive or to an existing archive.


= OPTIONS =
 -d, --dialog               Show a dialog for specifying the options for a batch or add operation.
 -o, --destination <directory> Default the extraction directory to <directory>. If not passed, the current path is used.

Options for adding files
  -c, --add                 Query the user for an archive filename and add specified files to it. Quit when finished.
  -t, --add-to <filename>   Add the specified files to 'filename'. Create archive if it does not exist. Quit when finished.
  -p, --changetofirstpath   Change the current dir to the first entry and add all other entries relative to this one.
  -f, --autofilename <suffix> Automatically choose a filename, with the selected suffix (for example rar, tar.gz, zip or any other supported types)

Options for batch extraction:
  -b, --batch               Use the batch interface instead of the usual dialog. This option is implied if more than one url is specified.
  -e, --autodestination     The destination argument will be set to the path of the first file supplied.
  -a, --autosubfolder       Archive contents will be read, and if detected to not be a single folder archive, a subfolder by the name of the archive will be created.


= EXAMPLES =
ark --batch archive.tar.bz2
Will extract archive.tar.bz2 into the current directory without showing any GUI.

ark -b -d archive.tar.bz2 archive2.zip
Will first show an extraction options dialog and then extract both archive.tar.bz2 and archive2.zip into the directory chosen in the dialog.

ark --add-to my-archive.zip photo1.jpg text.txt
Will create my-archive.zip if does not exist and then add photo1.jpg and text.txt to it.


= AUTHORS =
Ark is currently maintained by Harald Hvaal <haraldhv at stud.ntnu.no> and Raphael Kubo da Costa <kubito at gmail.com>.

This man page was first written by Lauri Watts <lauri at kde.org> in 2005 for KDE 3.4, and was later updated in 2009 by Raphael Kubo da Costa <kubito at gmail.com>