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

[Jiri Vanek]

On 10/14/2014 09:02 PM, Jacob Wisor wrote:
> On 10/14/2014 at 05:35 PM, Jiri Vanek wrote:
>> This patch is replacing all usages by @BOLD...@ by html equivalents <b> or </B>
>> (case does not meter, nor do spaces inside)
>>
>> I don't have better idea how to get rid of it:(
>>
>>
>> There was one more note to this - to include some escaping - I'm not going to
>> implement it  until it is needed,
>
> In my experience, this kind of statement is usually a strong indicator of a bad personal attitude to
> work. Your argument can be applied almost every time and everywhere. You are delivering incomplete
> work which is practically useless and in the end causes more problems than solves.
>
>> but if it will be needed, then I would go y
>> this same way - have html escaping in properties, and get rid of it in
>> ReplacingFormatter.
>>
>> The docs looks same with this patch, as they looked before.
>
> :-\ This is a waste of energy because it is no better than before. I will not even try to have a
> look at it.
>
> How about having methods that strip different kinds of formatting and return plain text at runtime.
> E.g.
>
> .SH Man Title
> .br -> stripMan() -> Man Title
>
> or
>
> <h1>XHTML title</h1>/<br/> -> stripXHTML() -> XHTML Title
>
> Are there any problems with this approach, except for the fact that the formatting would need to be
> detected or stored as meta data either in the properties files or in code?
>
> Another approach would be to have plain text and formatted text properties in different name spaces,
> like JavawsParamName.doc.man or JavawsParamName.doc.html for JavawsParamName, or
> doc.html.JavawsParamName (or any other permutation you like, but consistent). Although this would
> "double" or maybe even "triple" some properties, it would at least be a clean approach, consistent,
> and keep all texts in *one* file, which is what you initially wanted to have since you embarked on
> your "Great Documentation Generator Endeavor".
>
> 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...???...


J.