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

[Jiri Vanek]

On 10/25/2014 05:16 PM, Andrew Azores wrote:
> On 10/23/2014 11:53 AM, Jiri Vanek wrote:
>> On 10/20/2014 06:19 PM, Andrew Azores wrote:
>>> 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.
>>>
>> Thank you for suggestions,
>>
>>
>> upodated patch attached. I actually do not care to much if it is
>> included, but get rid of @BOLD_..@ is probably beter way .
>>
>>
>> If this will be approved of denied, I consider work on generator as
>> finished. (excepot soem bug is found) .
>>
>>
>> J.
>
> Hi,
>
> Looks like a reasonable improvement to me. One nit before push: typos/misspellings in
> Messages.properties. You have "RepalcingTextFormatter" instead of " ReplacingTextFormatter" ;)
>
> Thanks,

fixed & pushed :(

J.