[rfc][icedtea-web] get rid of custom@@ markup for documentation

[Jiri Vanek]

...
>>>
>>> Yet another approach would be to accept only HTML formatted code in the
>>> property files and have it
>>> converted to man or what ever document format when generated. It should be
>>> pretty easy to strip HTML
>>> tags from strings in Java. ;-)
>>
>> uh... this is exactly what the aptch was doing...???...
>
> No, it does not. This would require a HTML validator, or at least calls for one. If we set out to
> accept only HTML in message property files then we should also have a decent HTML validator test.
> The provided test does not test HTML but some very specific character sequences which /tend/ to be,
> almost by accident, a subset of valid HTML. And although I am not a strong proponent of software
> tests (for various reasons), I can see a great benefit to a proper and complete test in this case
> because we have no other way to enforce proper formatting of property values in message property
> files which in turn makes sure that the document generators will not break. So again, your approach
> to the problem is not holistic.


I really understand your point, but I really do not wont to fall into this kind of complexity. Not 
even from far remote.

The must for anything what will be done is, that proper man is generated from it. Compared to html, 
man supports *really* small number of formatting "elements". So our "html" can support just this 
minimal intersection of elements. So wy not only B?

All the markup is out of properties, the only one which remained is bolding. There is no reason to 
add some other features  unless it is needed.

Another option I have in mind is to have here {0} for opening and {1} for closing. But it seems even 
little bit more stupid.

Rather then support even anything close to html, I would rather get rid of any formatting at all. 
But it seems to me quite unhappy to dont have possibility to do small higlighting.


On contrary, I do not understand why you are standing so strongly against:(

>
>> diff -r df05d1de5af4 netx/net/sourceforge/jnlp/resources/Messages.properties
>> --- a/netx/net/sourceforge/jnlp/resources/Messages.properties    Mon Oct 13 16:05:27 2014 +0200
>> +++ b/netx/net/sourceforge/jnlp/resources/Messages.properties    Tue Oct 14 17:25:36 2014 +0200
>> @@ -270,13 +270,13 @@
>> […]
>> -# policyeditor man (note, spaces (especially the one around @@ markup) are important due to man
>> pages markup)
>> -PEintro= - view and modify security policy settings for @BOLD_OPEN at javaws @BOLD_CLOSE at and the
>> @BOLD_OPEN at browser plugin at BOLD_CLOSE@
>> +# policyeditor man (note, spaces (especially the one around markup) are important due to man
>> pages markup). Only bold  tag is now recognized by RepalcingTextFormatter.
>> +PEintro= - view and modify security policy settings for <B>javaws </B>and the <B>browser plugin</B>
>
> Please keep in mind that HTML is white space agnostic in the sense that it replaces multiple
> consecutive white spaces with one space character (U+0020) in content data before forwarding it to a
> rendering unit (like a browser or a document generator). So documents that rely on multiple
> consecutive white space characters for proper rendering may render content distorted.

I know that. And it dos not meter.

The only thing with is needed to keep in case of  that TAGtext TAG is no space among TAGtext  and 
the space among "text TAG" - because man formatter will do
MANTAG
text[space]
MANTAG

If the space appear before any MANTAG or before text the formatting collapse. More spaces do not meter.
>
>> diff -r df05d1de5af4
>> netx/net/sourceforge/jnlp/util/docprovider/formatters/formatters/ReplacingTextFormatter.java
>> ---
>> a/netx/net/sourceforge/jnlp/util/docprovider/formatters/formatters/ReplacingTextFormatter.java
>> Mon Oct 13 16:05:27 2014 +0200
>> +++
>> b/netx/net/sourceforge/jnlp/util/docprovider/formatters/formatters/ReplacingTextFormatter.java
>> Tue Oct 14 17:25:36 2014 +0200
>> @@ -1,18 +1,25 @@
>>  package net.sourceforge.jnlp.util.docprovider.formatters.formatters;
>>
>> […]
>>
>>  public abstract class ReplacingTextFormatter implements Formatter {
>>
>>      public static String backupVersion;
>> -
>> +    private static final String BOLD_OPEN_REGEX = "<{1}\\s*[Bb]{1}\\s*>{1}";
>> +    public static final Pattern BOLD_OPEN_PATTERN = Pattern.compile(BOLD_OPEN_REGEX);
>> +    private static final String BOLD_CLOSE_REGEX = "<{1}\\s*/{1}\\s*[Bb]{1}\\s*>{1}";
>> +    public static final Pattern BOLD_CLOSE_PATTERN = Pattern.compile(BOLD_CLOSE_REGEX);
>
> Storing static regex pattern Strings *and* compiled Patterns is a waste of memory. A regex pattern

Sure!

> string can always be retrieved from a Pattern object by calling Pattern.pattern(). So you can drop
> the static Strings.
> Besides, I think you do not need the "{1}" quantifiers here. A single character /is/ a single
> character. ;-)

Yah., It is relict when I was plying in it with various reluctant or other the seconds  non-greedy 
quantifiers. Sorry.
>
> Speaking of a HTML validator, I also think that we should be tolerant here and accept empty elements
> here too, like "<br/>" or "<br /> etc. Unless you insist that we accept pure HTML only (and no XHTML).

No. Definitely staying with xtml - if something even nearly similar is done.