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

[Jacob Wisor]

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.

>>> +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.

>> 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 Generate Documentation from Source Code". :-( There is really 
*no* *reason* to suddenly and arbitrarily forbid certain characters in messages 
with {n} argument placeholders.
This is something that should have been fixed before pushing. Really, I am 
speechless about so much ignorance. Again, stop making a mess!

> 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.

> +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.

>>> [...]
>>> diff -r e30d71ab91c6
>>> netx/net/sourceforge/jnlp/util/docprovider/ItwebPluginTextProvider.java
>>> ---
>>> a/netx/net/sourceforge/jnlp/util/docprovider/ItwebPluginTextProvider.java
>>> Wed Sep 10
>>> 10:22:46 2014 -0400
>>> +++
>>> b/netx/net/sourceforge/jnlp/util/docprovider/ItwebPluginTextProvider.java
>>> Fri Sep 12
>>> 15:21:39 2014 +0200
>>> @@ -38,6 +38,7 @@
>>>
>>>  import java.io.IOException;
>>>  import net.sourceforge.jnlp.config.PathsAndFiles;
>>> +import net.sourceforge.jnlp.runtime.Translator;
>>>  import net.sourceforge.jnlp.util.docprovider.formatters.formatters.Formatter;
>>
>> Generally speaking, I am really having trouble accepting this kind of custom
>> formatter to
>> IcedTea-Web. Actually, this goes for any project which is not specifically
>> concerned with parsing a
>> well specified language. Unfortunately, most developers greatly underestimate
>> the prerequisites for
>> a properly working formatter. The probability of not getting it right is far
>> greater than one would
>> initially assume. This starts with checking inputs and outputs, goes over
>> properly handling encoded
>> strings, and ends on handling escapes properly. The amount of testing required
>> to get /and/ keep a
>> formatter correct is just enormous. Then, it has to be documented and
>> everybody who wants to add
>> documentation on a new feature that he/she has just implemented is required to
>> (a) know how the
>> documentation generator works and (b) understand its formatting.
>> So ultimately, we should get rid of this formatter and any @TAG@ tags. If you
>> really need formatting
>> tags for man pages then the documentation generator should be able to include
>> them itself
>> automatically. Otherwise, adding documentation becomes unnecessarily difficult
>> and overly complex.
>> It's a pity that you rushed to push the documentation generator...
>>
>
> Fixing all this paragraph is definitely for another changesets.
>
> Copypasted from summary::
>
> the @bold@ whatever@ stuff:
>    - It is placeholder for <b>  and </b> in html or \n.B \n  and /n  in man. Tbh
> Right now I dont know solid workaround
>    - 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?

> 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 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. 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.

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

> 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?

> 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 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 
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.

Jacob