|
View:
New views
20 Messages
—
Rating Filter:
Alert me
|
|
|
|
|
|
Re: Outdated man page policy?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). > 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). -Allen _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?2009/9/6 Allen Winter <winter@...>:
> 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. Thanks, Raphael _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?Am Sonntag 06 September 2009 20:13:48 schrieb Raphael Kubo da Costa:
> 2009/9/6 Allen Winter <winter@...>: > > 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. > 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. -- Burkhard Lück _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?2009/9/6 Burkhard Lück <lueck@...>:
> Am Sonntag 06 September 2009 20:13:48 schrieb Raphael Kubo da Costa: >> 2009/9/6 Allen Winter <winter@...>: >> > 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. 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! = 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@...> and Raphael Kubo da Costa <kubito@...>. This man page was first written by Lauri Watts <lauri@...> in 2005 for KDE 3.4, and was later updated in 2009 by Raphael Kubo da Costa <kubito@...> _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?On Saturday 12 September 2009 03:37:23 Raphael Kubo da Costa wrote:
> 2009/9/6 Burkhard Lück <lueck@...>: > > Am Sonntag 06 September 2009 20:13:48 schrieb Raphael Kubo da Costa: > >> 2009/9/6 Allen Winter <winter@...>: > >> > 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! Anne -- New to KDE4? - get help from http://userbase.kde.org Just found a cool new feature? Add it to UserBase _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?Am Samstag 12 September 2009 10:04:40 schrieb Anne Wilson:
> On Saturday 12 September 2009 03:37:23 Raphael Kubo da Costa wrote: [...] > > 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. > > If markup your text and commited to trunk. Please proofread it. Btw, entities for your names/emails are not in kdelibs/kdoctools/customization/entities/contributor.entities so far, what about adding them? Thanks a lot for updating the man page. <hint>There is also an index.docbook in kdeutils/doc/ark</hint> > > From a user point of view, this man page is a diamond of unusual clarity. > :-) > > Anne Anne, why do I have to approve all your mails to this list? Seems you use a not subscribed email address for sending the mails, right? -- Burkhard Lück _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?2009/9/13 Burkhard Lück <lueck@...>:
> Am Samstag 12 September 2009 10:04:40 schrieb Anne Wilson: >> On Saturday 12 September 2009 03:37:23 Raphael Kubo da Costa wrote: > [...] >> > 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. >> > > > If markup your text and commited to trunk. > Please proofread it. > Btw, entities for your names/emails are not in > kdelibs/kdoctools/customization/entities/contributor.entities so far, what > about adding them? > > Thanks a lot for updating the man page. > <hint>There is also an index.docbook in kdeutils/doc/ark</hint> Actually, this is where I start getting confused. Is there some article on Techbase or somewhere else with instructions and documentation about these files? Wrt contributor.entities: * When should I have added myself to contributor.entities? * Can I just add a line with my information? I see some blank lines there, so I don't know if I should skip one as well. Wrt index.docbook: * Is there some sort of docbook guide that's easy to understand? Whenever I open a docbook file I feel it's something mere mortals can't understand ;) Cheers. _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?Am Sonntag 13 September 2009 19:15:06 schrieb Raphael Kubo da Costa:
> > Actually, this is where I start getting confused. Is there some > article on Techbase or somewhere else with instructions and > documentation about these files? > http://techbase.kde.org/Projects/Documentation http://l10n.kde.org/docs/ > Wrt contributor.entities: > * When should I have added myself to contributor.entities? When an entity is used more than one time, that happens already in the translations around 15 times. > * Can I just add a line with my information? I see some blank lines > there, so I don't know if I should skip one as well. > The list is sorted by family name, blank lines are used as separator to group the entries with the same first char of the family name. > Wrt index.docbook: > * Is there some sort of docbook guide that's easy to understand? > Whenever I open a docbook file I feel it's something mere mortals > can't understand ;) > That's my feeling opening source files;-) Just write in any format you like,- plain text preferred - because that could be used for the docbooks as for userbase.kde.org. -- Burkhard Lück _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?Burkhard � wrote:
/me wonders why Burkhard's last name is an unprintable character :-) > Am Sonntag 13 September 2009 19:15:06 schrieb Raphael Kubo da Costa: >> Wrt contributor.entities: >> * When should I have added myself to contributor.entities? > > When an entity is used more than one time, that happens already in the > translations around 15 times. Um... really? If so I did it wrong, I thought that was more-or-less the list of authors. (Though, if only for single-point-of-maintenance, I think I would disagree with "more than one time" here...) -- Matthew Please do not quote my e-mail address unobfuscated in message bodies. -- "Microsoft doesn't really care about users." -- Robert Cringely _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?Am Montag 14 September 2009 21:32:57 schrieb Matthew Woehlke:
> Burkhard � wrote: > > /me wonders why Burkhard's last name is an unprintable character :-) > > > Am Sonntag 13 September 2009 19:15:06 schrieb Raphael Kubo da Costa: > >> Wrt contributor.entities: > >> * When should I have added myself to contributor.entities? > > > > When an entity is used more than one time, that happens already in the > > translations around 15 times. > > Um... really? If so I did it wrong, I thought that was more-or-less the > list of authors. (Though, if only for single-point-of-maintenance, I > think I would disagree with "more than one time" here...) > Imaging you would like to write your name with pretty, but sometimes unprintable "ö" instead of "oe", just change the entity in kdelbs. Then each time a documentation and it's translattion is build and installed, this change is spread into all installed files, even into the translations. -- Burkhard Lück _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?Burkhard Lück wrote:
> Am Montag 14 September 2009 21:32:57 schrieb Matthew Woehlke: >> Burkhard � wrote: >>> Am Sonntag 13 September 2009 19:15:06 schrieb Raphael Kubo da Costa: >>>> Wrt contributor.entities: >>>> * When should I have added myself to contributor.entities? >>> When an entity is used more than one time, that happens already in the >>> translations around 15 times. >> Um... really? If so I did it wrong, I thought that was more-or-less the >> list of authors. (Though, if only for single-point-of-maintenance, I >> think I would disagree with "more than one time" here...) >> > Hmm, your entity is in contributor.entities in trunk, so you did it right. > > Imaging you would like to write your name with pretty, but sometimes > unprintable "ö" instead of "oe", just change the entity in kdelbs. > Then each time a documentation and it's translattion is build and installed, > this change is spread into all installed files, even into the translations. Yes, exactly my point. So I am confused, one /should/ add themselves to contributor.entities right away, or wait until their name is used more than once? (Well, if you count translations, I guess there is no such thing as "once"?) (In my case, as a native of that horribly backwards country which bestowed on me the en_US language, I don't even pronounce my last name anywhere close to the "proper German", much less have any desire to spell it Wöhlke¹ :-), which it hasn't been for a few generations at least.) (¹ Wow, that looks odd... ;-) ) -- Matthew Please do not quote my e-mail address unobfuscated in message bodies. -- "Microsoft doesn't really care about users." -- Robert Cringely _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?Am Montag 14 September 2009 22:22:41 schrieb Matthew Woehlke:
> > Yes, exactly my point. So I am confused, one /should/ add themselves to > contributor.entities right away, or wait until their name is used more > than once? (Well, if you count translations, I guess there is no such > thing as "once"?) > You are right, there is no single use for that. So an entity should be added the first time name + mail are used in docbooks. -- Burkhard Lück _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?Burkhard Lück wrote:
> Am Montag 14 September 2009 22:22:41 schrieb Matthew Woehlke: >> Yes, exactly my point. So I am confused, one /should/ add themselves to >> contributor.entities right away, or wait until their name is used more >> than once? (Well, if you count translations, I guess there is no such >> thing as "once"?) >> > You are right, there is no single use for that. > So an entity should be added the first time name + mail are used in docbooks. Okay, good to know. Thanks. -- Matthew Please do not quote my e-mail address unobfuscated in message bodies. -- You're on your own for the pony. -- Richard Hughes, on feature requests _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?2009/9/14 Burkhard Lück <lueck@...>:
> Am Sonntag 13 September 2009 19:15:06 schrieb Raphael Kubo da Costa: >> * Can I just add a line with my information? I see some blank lines >> there, so I don't know if I should skip one as well. >> > The list is sorted by family name, blank lines are used as separator to group > the entries with the same first char of the family name. I see Danny Allen and Albert Astals Cid in the same group as Thorsten Zachmann and other people whose family name begins with "Z". Is this expected? And should I add myself to "C" or "K"? _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?Am Dienstag 15 September 2009 19:30:50 schrieb Raphael Kubo da Costa:
> 2009/9/14 Burkhard Lück <lueck@...>: > > Am Sonntag 13 September 2009 19:15:06 schrieb Raphael Kubo da Costa: > >> * Can I just add a line with my information? I see some blank lines > >> there, so I don't know if I should skip one as well. > > > > The list is sorted by family name, blank lines are used as separator to > > group the entries with the same first char of the family name. > > I see Danny Allen and Albert Astals Cid in the same group as Thorsten > Zachmann and other people whose family name begins with "Z". Is this > expected? > "Please keep the list sorted on the family name" And sinply added their names at the end. > And should I add myself to "C" or "K"? > Uh, good question. but what's your family name? "Kubo da Costa"? I'd say it does not matter ;-) -- Burkhard Lück _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?(Please do not quote my e-mail address unobfuscated in message bodies.)
Burkhard � wrote: > Am Dienstag 15 September 2009 19:30:50 schrieb Raphael Kubo da Costa: >> should I add myself to "C" or "K"? > > Uh, good question. but what's your family name? > "Kubo da Costa"? > > I'd say it does not matter ;-) Well, it should be the first letter of 'surname', no? I assume '<firstname>Raphael</firstname>' is correct. Which is correct for the rest?: 1. <surname>Kubo da Costa</surname> 2. <othername>Kubo</othername><surname>da Costa</surname> 3. <othername>Kubo da</othername><surname>Costa</surname> 4. something else? Note that (2) would mean sorting under 'd' :-). -- Matthew You're on your own for the pony. -- Richard Hughes, on feature requests _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?2009/9/15 Matthew Woehlke <mw_triad@...>:
> (Please do not quote my e-mail address unobfuscated in message bodies.) > > Burkhard � wrote: >> Am Dienstag 15 September 2009 19:30:50 schrieb Raphael Kubo da Costa: >>> should I add myself to "C" or "K"? >> >> Uh, good question. but what's your family name? >> "Kubo da Costa"? >> >> I'd say it does not matter ;-) > > Well, it should be the first letter of 'surname', no? > > I assume '<firstname>Raphael</firstname>' is correct. Which is correct > for the rest?: > > 1. <surname>Kubo da Costa</surname> > 2. <othername>Kubo</othername><surname>da Costa</surname> > 3. <othername>Kubo da</othername><surname>Costa</surname> > 4. something else? > > Note that (2) would mean sorting under 'd' :-). That's something I've never thought of ;) I think everything else besides Raphael can be considered my surname. However, I also think that if I were to publish something I'd probably be indexed as "Costa, Raphael K." or something similar. _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?Am Dienstag 15 September 2009 19:30:50 schrieb Raphael Kubo da Costa:
> I see Danny Allen and Albert Astals Cid in the same group as Thorsten > Zachmann and other people whose family name begins with "Z". Is this > expected? > > And should I add myself to "C" or "K"? Where do you find yourself in the telephonebook? ;) Regards, Michael -- You are always doing something marginal when the boss drops by your desk. _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
|
|
Re: Outdated man page policy?2009/9/15 Michael Skiba <michael@...>:
> Am Dienstag 15 September 2009 19:30:50 schrieb Raphael Kubo da Costa: >> I see Danny Allen and Albert Astals Cid in the same group as Thorsten >> Zachmann and other people whose family name begins with "Z". Is this >> expected? >> >> And should I add myself to "C" or "K"? > > Where do you find yourself in the telephonebook? ;) Still on this matter: I was adding myself to "C", and saw the <othername> tag. Should I add "Kubo da" do <othername> or just add everything after Raphael to surname? _______________________________________________ kde-doc-english mailing list kde-doc-english@... https://mail.kde.org/mailman/listinfo/kde-doc-english |
| Free embeddable forum powered by Nabble | Forum Help |