[rfc][icedtea-web] javaws -version flag

[Jiri Vanek]

On 03/06/2014 05:52 PM, Omair Majid wrote:
> * Jiri Vanek<jvanek at redhat.com>  [2014-03-06 11:29]:
>> On 03/06/2014 05:15 PM, Omair Majid wrote:
>>> * Jiri Vanek<jvanek at redhat.com>   [2014-03-06 11:14]:
>>>> I dont think it is worthy. The current man pages are really *outdated* :(
>>>
>>> I don't follow. If the pages are outdated, shouldn't we fix that by
>>> updating them? Are we abandoning the man pages?
>>>
>>
>> Yes we should. Only the good will is missing.
>
> Abandoning man pages for 'good will'? I don't follow. If anything, we
> make things harder for users.

No. You misunderstood me completely. The will to maintain them is missing. I 100% agree that they are necessary.
>
>>   First half of previous 8 months I was ignoring them willingly,
>>   because I hoped to have the generated ones prepared for 1.5.
>
> I don't know if generated ones are the magic bullet you think they are.
> Either way you have to write the documentation. And some parts of the
> documentation don't belong in code. Still, generated or not, we need
> some place where users can find documentation.

100% yes, and the man pages are th way to go.


They may be the magic bullet if I fulfil my idea.

Some of the content will be reused from -help (especially the cmd switches). They will be easily localisable  from properties, and also runtiem help will be possible to generate from them.
Defintly the way to go. Also I think the maintainability  will be much better.

>
>> But this task was moved to 1.6 due to new D-I-D attributes
>
> I would like to think that features are not considered 'complete' unless
> they are documented.

I would guess the urls in error messgaes and hints in news are ok. And those exists. What else do you recommend?
>
>> Also you may note - icedtea=web man page is missing (it is jsut copy
>> of current (outdated) javaws.1)
>
> I thought only the commands themselves have man pages. There is no
> command named `icedtea-web` so there is no man page for it.
> There is no man page for `mercurial` either, but there is for `hg`.
>
> Where is this copy of javaws.1? I don't see it in our repo, and I don't
> see it when I `make install`.

Right. Right now there is only javaws.1 Imho two more are misisng. And manpage for "package name" is good recomandation. It can be jsut see javaws + expalinig alternatives, or something more general. Also it may be spec patch only.
>
>> , itw-settings manpage is missing - and
>> it is HUGE man page, and newly policyeditor is missing.
>
> For self-explanatory GUIs, I am not sure we need detailed man pages.
> They mostly make sense for command line programs that take lots of

Self expalantory???  The itw-settings have incredible cmd line support!

For policieditor we may argue, but at least mentioning that it have --help (again, same with man page => generate) and the only argument expected is filename.

> arguments and/or options so the options and arguments are properly
> documented. Aside from the basics ('run itw-settings using the command
> itw-settings', 'itw-settings allows you to modify setings graphically',
> 'file bugs at this bug tracker', 'config files are located here'), what
> else do we need?
>

Well this with config files is good idea. Another good reason for generated mn pages (as defautls are in source codes)

>> For javaws x icedtea-web man page see a bug in bugzilla. I have jsut
>> spend 10 minutes by trying to connect to bugzilal without sucess[1]
>
> It's a private bug, but when I do log in, I don't actually see anything,
> just your comment saying that you have linked icedtea-web.1 to javaws.1.
> I think that's not ideal because:
>
> - Man pages document binaries rather than packages
> - You are completely leaving out the plugin :(


hmhmh.. Well thats true. Then the few lines above "see javaws + expalinig alternatives" + "and plugin" may be a solution here.



J.