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

[Jacob Wisor]

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. ;-)

Jacob