[rfc][icedtea-web] localizable Plugin+settings+fix+cleanup

[Jiri Vanek]

On 09/17/2014 11:17 PM, Jacob Wisor wrote:
> On 17.09.2014 at 04:46 PM, Jiri Vanek wrote:
>>>>      mkdir $$HTML_DOCS_TARGET_DIR ; \
>>>>      mkdir $$PLAIN_DOCS_TARGET_DIR ; \
>>>> -    mkdir -p $$MAN_DOCS_TARGET_DIR ; \
>>>> +    mkdir $$MAN_DOCS_TARGET_DIR ; \
>>>
>>> Why did you remove the "-p" switch? It is probably best to have this switch
>>> almost always on in
>>> scripts to avoid running into errors just because of non-existing parent
>>> directories.
>>
>> I prefer opposite. To not use -p. If some typo seek in, then it can create whole
>> branch in some really strange lcoation...
>>
>> Before this dline created two levels of diretories. So there was -p.Now it does
>> not.
>>
>> however, the
>> -export DOCS_DIR=$(TOP_BUILD_DIR)/icedtea-web-docs
>> +export DOCS_DIR=$(TOP_BUILD_DIR)/icedtea-web-docs/$(FULL_VERSION)
>> ...
>> -    mkdir $(DOCS_DIR) ; \
>> +    mkdir -p $(DOCS_DIR) ; \
>>
>> does.
>>
>> so not "fixed"
>
> Let me set this straight for you: Because my chain of thought is inconsistent, it is actually okay
> to violate the initial premise any time I like to. What kind of thinking is this? :-\
> I am not against or in favor of any switch (or style). They do not really matter as long as they do
> their job. But, what does matter is *consistency*. Inconsistency is no style. So choose either one
> of the styles and stick with them. Stop trying to be philosophical.


What do you see  as inconsistency?
I have one sub directory to  create, no -p. Is there a chain of them, so there appear -p. There is 
no rule for that. If you want rule, set up rule. and adapt Makefile.

>
>>>> +ITWSsynops=command arguments
>>>> +IWSdescL1=is a command line and a GUI program to modify and edit settings
>>>> used by the icedtea-web
>>>> implementation \
>>>> +of at BOLD_OPEN@ javaws @BOLD_CLOSE at and the @BOLD_OPEN at browser plugin at BOLD_CLOSE@.
>>>
>>> Why did you suddenly introduce broken lines or line continuing characters to
>>> Message.properties,
>>> since you have always been strictly against them?
>>
>> You remember, do you? :)) Well its not that I'm 100% against, I like the i18ns
>> and original file keeping same style.
>>
>> Also I don't like cutting on 80chars. Then maybe wee all can throw away our wide
>> monitors... So easily spoken -  here i broke, because it seemed to me more
>> readable.
>
> Again, your deeds and words are inconsistent. By this reasoning there are a lot more messages that
> would benefit from breaking for better readability.
> You are making a mess. Stick to a style.


The only thing I wonted that time IIRC was to keep lines in same state in translations  and in 
original properties. and also if I recall, I was not forcing you to do so, but suggesting it.

I'm really not sure what you are trying to suggest. The people in this project changes. AFAIK at 
least three generations of developers already changed here. If there were some style,  it was lost, 
because each generation made its own.

Again - if you wont rule here, set it, write it and refactor code to actually follow it

I will be happy to follow it.
>
>>> Is "... of at BOLD_OPEN@ javaws @BOLD_CLOSE at and ..." actually correct?
>>>
>>>> +IWSdescL2=If executed without any arguments, it starts up a GUI. Otherwise,
>>>> it tries to do what
>>>> is specified in the argument.
>>>> +IWSdescL3=The command-line allows quickly searching, making a copy of and
>>>> modifying specific
>>>> settings without having to hunt through a UI.
>>>> +IWSexampleL1=Show the GUI editor
>>>> +IWSexampleL2=Resets the value of `{0}` setting.
>>>
>>> Are the "`" characters literals in the man page or markups?
>>
>> copypaste from my summary email:)
>> Originally there were the ' (" ' ") char, however, I noted, then If I put {n}
>> into '' like '{0}' the
>> properties fiel do not evaluate it correctly.  Same for " char and no escaping
>> helped..  So I put
>> here ` char:(
>
> Well then, this is obviously a serious flaw in the implementation of your "Grand Master Plan to

Thats not. Its feature of properties substitution - it handles characters ' or " in this way.  So it 
was not introduced by my changeset. If you won to keep the ' char here. The  solution  is to get rid 
of the (in this changeset intorduced) {0} parameter and keep stick with hard coded value.


Anyway, I just found that the  change from '{0}' to ''{0}'' should  do the trick.  You, as the 
reviewer should point me to this trick, or force me to find the solution, or suggest different 
approach. Not to scold/mock about possible flaw in something a bit unrelated (I guess you will catch 
this word) but i see it like it.


> Generate Documentation from Source Code". :-( There is really *no* *reason* to suddenly and
> arbitrarily forbid certain characters in messages with {n} argument placeholders.

:DD you must be joking in this sentence, are you?

> This is something that should have been fixed before pushing. Really, I am speechless about so much
> ignorance. Again, stop making a mess!

No. It is something what can be tuned on the fly.
>
>> Anyway - no markup mentioned. In original text it was just quoting - making it
>> readable or similar.
>> So it have nothing to do with any markup, and AFAIK all plain, html and man
>> output is ok with it.I
>> will be happy to change it if you dont like it ad know replacement.
>
>>>> +ITWPsynopsL3=@BOLD_OPEN@ Mozzila compliant browsers @BOLD_CLOSE at like
>>>> Firefox, Midori, Epiphany,
>>>> Chrome or Chromium use:
>>>
>>> Spelling! The foundation's name is Mozilla!
>> fixed:(
>>
>>>
>>>> +ITWPsynopsL4=@BOLD_OPEN@ Opera family browsers @BOLD_CLOSE at like Opera use:
>>>
>>> Please be careful when mentioning registered trademark and product names. If
>>> you mention them, you
>>> will probably need to include a statement on their legal status somewhere in
>>> the documentation for
>>> certain jurisdictions. Hence, it is best to avoid them. However, I am also
>>> aware that avoiding them
>>> completely is not always possible. Therefore, I strongly suggest to use the
>>> term "Mozilla
>>> compatible" only, wherever required. "NPAPI compatible" is also acceptable but
>>> far more technical
>>> and probably unknown to most users. "Mozilla compatible" covers all browsers
>>> currently supported by
>>> IcedTea-Web and avoids entanglements with too many entities. Because Mozilla
>>> is also the original
>>> author of the NPAPI, it describes the technical aspect sufficiently enough.
>>> And, although Mozilla is
>>> trademarked as well, the term would nevertheless reduce any legal risks to a
>>> minimum, especially
>>> given the Mozilla foundation's nature and history in free software. Of course,
>>> this does not relieve
>>> us of placing a legal notice in the documentation about Mozilla either, but
>>> reduces any efforts to
>>> just one entity.
>>
>> Ouch that is the long one. What is conclusion? It really was not celar :( I
>> added the"
>
> As is it says. Just stick to a term referring to only one registered trademark or product name. This
> way, it is usually going to be easy to get the proper wording for this trademark or product name by
> looking into the help or about section of the product itself.
>

I'm really not understanding what you wont me to do. I will remove the new sentence and wait for 
lawyer reply.

>> +ITWPtrademarks=All browsers or company names in this section may be subjects of
>> trademarks and/or copyrights.
>
> I am no lawyer but I am sure this sentence will not hold under legal scrutiny. Stop neglecting the
> severity of problems. Start paying attention to actually solving them. And, if you do not know how
> to solve a problem then get advice from somebody who has got the capability.

Ok. Writing to lawyer:)  (really)
>
>>>> [...]
>>>> diff -r e30d71ab91c6
>>>> netx/net/sourceforge/jnlp/util/docprovider/ItwebPluginTextProvider.java
>>>> ---
>>>> a/netx/net/sourceforge/jnlp/util/docprovider/ItwebPluginTextProvider.java
...
>>    - I would like to get rid of of all this @@ markups. And I'm successfully
>> doing so:)
>>    - I Get rid of all except the @bold@, Which I found as necessary evil. But if
>> workaround will be
>> found. I will be most happy to get rid of it.
>>
>>
>> ..end of coopypaste:
>
> So, where is the documentation for all the crap you have introduced again? I can't find it. How is
> anybody supposed to add documentation on a new or altered feature now?

Obviously it snot yet documented, because (obviously)  it is not yet finished.
>
>> Well yes,  Actually exactly this was reason why I rushed with this. Yes this can
>> be improved, but also that can be improved! or that?  But I do not wont to
>> update  so big patch until eternity.
>
> Well, obviously you do not seem to have a sense for the *quality* of a problem and the implications
> it may cause. I am not mentioning stuff that just needs some polishing to shine. I am mentioning
> problems that have implications on other existing code and data, like Messages.properties.
>
>> So I now will be focusing on such a parts which are not considered nice on some
>> ends.
>
> This is totally inefficient. Do this *before* you push! And as already mentioned, it is not about

sorry, but disagree completely.

> polishing stuff to make it shine but about making it work *properly* in the first place.
>
>> The @bold@ substitution, I dont know the perfect cure. Maybe repalce by <b> and
>> </b> which can be repalced to plain or man as is now @bold@ @bold close@ ?
>>
>> Yes I agree, "project specific markup" is not nice. And I'm(will) be working on
>> removal of it.
>>
>> No escaping is now done. And I'm not sure if it is wonted/needed in current
>> state of things.
>> If it will become needed, it will be added.
>
> This is definitely the worst possible approach in software engineering that anyone can think of.

I dont think so. The escaping is not needed now. Why it hsould be needed later? I'mnot going to 
solve possible future bugs (considering that those ar enot introduced by this) I'm going to fix 
documentation flaw which is here for *years*

> Have not you learned anything, like trying to avoiding future problems now? Usually, you will have a
> really hard time fixing existing problems later, when some code or data relies on your crappy base.

Only time will prove this.

>
> Anyway, why the sudden rush to push the "Grand Master Plan to Generate Documentation from Source Code"?

I don't understand that you don't understand. It was big changeset, not affecting any mayor parts, 
but spread across whole ITW.  It was well tested to work with current state of things.  Any further 
adaptations if the tunning will take to long will just destabilize it.

According to nature of the patch, all hints you have - are fixable in runtime. In meantime, it will 
soak well.
>
>> Yes, testing is needed. I wont to add unittests, and also automatic tests by
>> xmllint on resulting html. I don't know how to validate man :( And not sure If I
>> wont validate plain :)
>
> Well, if you do not know how to validate man pages then maybe you should have thought about it
> before pushing?

I was. And I have not found even solid specification of man.  So I did my best. Is it reason to drop 
man support? Maybe...

>
>> One general answer to this.
>> I will be much more happy to hunt minor bugs in this generator, then check till
>> madness three similar -  but based on different sources  - types of
>> documentation. Maybe the current formatters are not perfect (without maybe,...
>> thy are not even pretending to be complex. They are single-purposed ones) but do
>> they job. And I doubt some more text will be added in close or more remote
>> future.
>
> Oh, I am pretty sure we are going to add documentation. Just because of the simple fact that it is
> currently very rudimentary and /explaining/ very little.


>
>> The context of static texts have changed in years only few times, and
>> really only a bit. It was the properties, files and switches which were changed
>> significantly and *always* forgotten to be documented and,. more horribly left
>> also completely outdated.  I really do not wont to check those errors anymore.
>> Rather this.
>
> This may sound like a reasonable or maybe even /noble/ cause but it is no excuse for not thinking a
> proposed solution through before applying it. As I have told you before, it is going to be quite
> difficult to get a

Maybe. But rather this, then the state it was before. Acording to that /noble/ experience I had in 
past years, I would rather give shot to this generator.

 > documentation generator right but you have carelessly swept away all of my
> warnings. The code is definitely in a much worse shape now than it has been before the document

I did not. I'm marking your notes, And I hope to fix most of them.

> generator changeset. IMHO you should pull back the document generator changeset, work it to an
> acceptable shape, and then test it. So what if it could take like a few months and may become quite
> big? Who cares! Just give it a few rfc iterations. But, what is most important is that we get clean
> changesets instead of fixes of fixes to half-baked changesets.

Sorry, but it must be clear that I disagree with this rebuke. Main thing - for such a big changset 
you can not expect one clean hangeset. We already burned our hands doing so. Always at the end, was 
99% of the changset same during a big review, and only few parts were constantly changing. Such an 
parts may be fixed any time, while the rest  of teh changeset may be soaking into project, other 
patches may have benefit from it -and is being constantly tested.


We have at lest 3 months, more correctly I would guess even 6 months before 1.6 release. it is 
plenty of time to improve this. Ad I definitely do not wont to maintain this patch off repo.


Well -let me bring up an example - you have created amazing windows port. Do you wont to push it as 
it is, or close to state where it is, or tune it to perfection and push then?  I think the last  is 
not what you wont to do.


Anyway - except the ' char we ar eno longer discussing this changeset. May I proceed somehow? 
(probably with '' fix. and with resolution from lawyers around.