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

Andrew Azores aazores at redhat.com
Sat Oct 25 15:16:51 UTC 2014

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.


Looks like a reasonable improvement to me. One nit before push: 
typos/misspellings in Messages.properties. You have 
"RepalcingTextFormatter" instead of " ReplacingTextFormatter" ;)

Andrew Azores

More information about the distro-pkg-dev mailing list