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

[Andrew Azores]

On 10/16/2014 12:13 PM, Jiri Vanek wrote:
> ...
>>>>
>>>> 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:(
>

I don't see the need for anything beyond bolding either, really. Using a 
proper HTML validator would make sense to me if we were to be accepting 
some fairly sized subset of HTML elements, but if it's just a bolding 
tag, that's extreme overkill.

I think saying that this is "almost by accident" a subset of HTML is 
completely fair and actually entirely the point. It's not meant to be 
actual HTML, it's meant to be a minimal and domain specific markup 
language. Just for familiarity's sake, it's made to look like something 
else well-known. This could also be done with Markdown style **bold 
asterisk tag things** or Asciidoc style *single asterisk bold tags*, but 
that's probably a lot more ambiguous to parse than HTML-style bolding.

Thanks,
-- 
Andrew Azores