[rfc][icedtea-web] javaws.1 man page update

[Jiri Vanek]

On 08/25/2014 02:50 PM, Jacob Wisor wrote:
> On 08/25/2014 08:33 AM, Jiri Vanek wrote:
>> On 08/24/2014 02:24 AM, Jacob Wisor wrote:
>>> On 08/23/2014 07:58 PM, Andrew Azores wrote:
>>>> Hi,
>>>>
>>>> I looked at `man javaws` for some reason yesterday - no idea what I was looking
>>>> for or why - and thought it could do with some minor improvement. I've fixed a
>>>> few minor typos, improved the phrasing in a few areas, and made it more
>>>> consistent with capitalizing acronyms such as XML, HTML, and JNLP.
>>>>
>>>> Thanks,
>>>
>>> Yes, IcedTea-Web's documentation does indeed need some overhaul. So, thank you
>>> for bringing this up.
>>>
>>> I have proposed translated man pages *last* year but they have been bluntly
>>> dismissed because of
>>> Jiri's idea of generating those from source code. Well, it eludes me to this
>>> day how this could be
>>
>> Not form source. From properties files.
>>
>>> accomplished in a sensible way. I did not say it then but I think it is time
>>> to say it openly now:
>>> Generating sensibly translated documentation from source code is a delusion of
>>> megalomania (without
>>> using any AI or fuzzy logic technology). And to be honest, even if it worked I
>>> really do not see any
>>> benefit to it except for making things more complicated. What could be easier
>>> than editing a bunch
>>> of text files? No, we need to reinvent the wheel for a dubious purpose and
>>> outcome.
>>>
>>> So, here we are today... and nothing has happened, even though Jie Kang was
>>> the last one to touch on
>>> this. :-(
>>
>> The approach was completely wrong and was adding more work rather then saving work.
>> Te idea is that half of the strings in man pages are in  properties fiels. And
>> half whch is not is worthy to add here. If not only to have single place to
>> maintain, but also to enhance help messges from itw itself.
>>
>> for 1.6 Lukas is still assigned, although Jie seems to be working on this. If
>> they will abandon it, ten somebody else will take it. Probably me, as it i my
>> idea. And seems to  be not welcomed one ...
>
> The problem with your idea is that you have failed to explain what kind of work would be saved and

This is fair point - but no one asked - Except Luaks an Jie when they started to hack itw. So i 
explained to them.  Imho this task is good starting task before getting deeper into JNLClasslaoder 
swamp.

> have not proven that any kind of work would get saved. So far, I have not seen any savings in work
> yet. In fact, your idea has not helped documentation quality nor translations either. One year has
> passed and *nothing* has happened although reasonable propositions are at the table. To be honest:
> You are stalling progress on documentation.

Ok. So the judgment is that I will implement it.  To much strings is duplicated between parameters x 
helps and mans.

I hope that once it is done it will help rather then still progress.

Actually right now - the help unlooked  came in form of OptionsParser.  It will can give 
key+expalnation string for selected component. This was in "my mind original design". You can not 
notsee that this is right now duplication among man and help....
>
> Besides, man pages and good documentation go beyond usage syntax. This addition stuff has to go
> somewhere. Oh let me guess, it should go into property files. ??? Yeah, that's the right place to

It depends what do y9u mean by addition stuff. I do not see anything which belongs elsewhere.

> put it. Oh, and far simpler and easier it is to maintain too...
>
>>> To sum it up: Andrew, I would not be surprised if your good and plausible
>>> modifications to the
>>> javaws man page would get dismissed too... because you know, it can be
>>> generated from the source
>>> code... :-\
>>>
>> I have nothing against this. The reason to not have translated  man pages was
>> the maintaining. Would you keep in sync? Would Alexande keep?
>
> Sure, why not? It is no different than localizing messages in property files. When the author of a
> patch which adds or changes functionality updates the English documentation then why should it be
> any more difficult to localize that part of documentation than message property files? Localizers
> just have to update the documentation too. Heck, this is how it has always been!?
>
>> Would we keep the english ones? I have learned from state before ITW 1.5 no one
>> was taking care about man pages:( nor ven about other doeumentation at all...
>
> This may be true but this does not mean that moving documentation from man pages (where it belongs)
> to property files is going to change this. It is a mere technicality. It is human behavior which
> needs to be changed: You add new functionality to the application then document it. You change how
> the program works then document it. Really, it is not that difficult.

I'm afraid it is difficult. Most of the programmers, and especially young and eager ones wonts to 
"do" not to "document". They even do not wont to learn current codebase or approaches, in (theirs) 
best, they will start new project - even inside already established project. Only  if there is some 
voice which tells those "no there is palce where to put doc", "no there is palce better place where 
to pyut it/what to use"  It will not happen. Such an voice may be missing - because it left project, 
because project was forked and origins died or whatever. Even the reason may be that the voice do 
not wont to repeat all the same sentences around and  around  and around.

J.