Scaladoc: Separate HTML from Scala code

While the current approach is pretty messy, I like it because it is unbelievable simple to debug a HTML/CSS problem by looking at some attribute in the HTML source and then searching for it in the IDE.
But I have nothing against the idea of separating the xml stuff a bit ...

Now I've added template.html on my branch.
https://github.com/kzys/scala/commit/bf8ce59bd814d9e91c95ab22e19f0bc25d2...

On Sun, Sep 4, 2011 at 2:58 AM, Simon Ochsenreither
wrote:
> While the current approach is pretty messy, I like it because it is
> unbelievable simple to debug a HTML/CSS problem by looking at some attribute
> in the HTML source and then searching for it in the IDE.
> But I have nothing against the idea of separating the xml stuff a bit ...
>

Thanks. I want to keep simplicity as much as I can. My template engine is
really small and logic-less. It will open up the door for designers to
contribute Scaladoc.

On 9/3/11 9:21 AM, Kato Kazuyoshi wrote:
> In Scaladoc, many HTML written inside Scala code. But it's hard to maintain.
> Then I implemented a small "template engine" and extracted HTML from Scala code.
>
> You can see my branch at GitHub.
> https://github.com/kzys/scala/commits/template

Can anyone comment on what best practices have emerged in general
regarding how one cleanly separates code from markup? The last time I
was working in that medium directly was the 1990s, where we used PHP and
java servlets, and what I do remember is that there were big tradeoffs
being made whatever direction we moved.

This is a language agnostic question.

Regarding your changes, and having already admitted with the foregoing
that I'm no authority, this sort of thing:

+ engine.render(Map(
+ "icon" -> icon,
+ "owner" -> owner,
+ "displayName" -> displayName,
+ "order" -> order,
+ "ancestors" -> ancestors,
+ "constructors" -> constructorsElem,
+ "types" -> types,
+ "abstructValues" -> abstructValues,
+ "concreteValues" -> concreteValues,
+ "deprecatedValues" -> deprecatedValues,
+ "comment" -> memberToCommentHtml(tpl, true)
+ ))

is exactly how I'd imagine going about things, so it looks good to me.
Although I think I'd define it like:

def render(pairs: (String, Any)*)

so I didn't have to throw around Map all the time.

On Tue, Sep 6, 2011 at 3:48 AM, Paul Phillips wrote:
> On 9/3/11 9:21 AM, Kato Kazuyoshi wrote:
>>
>> In Scaladoc, many HTML written inside Scala code. But it's hard to
>> maintain.
>> Then I implemented a small "template engine" and extracted HTML from Scala
>> code.
>>
>> You can see my branch at GitHub.
>> https://github.com/kzys/scala/commits/template
>
> Can anyone comment on what best practices have emerged in general regarding
> how one cleanly separates code from markup? The last time I was working in
> that medium directly was the 1990s, where we used PHP and java servlets, and
> what I do remember is that there were big tradeoffs being made whatever
> direction we moved.
>
> This is a language agnostic question.
>

Well, I've been working on the medium since 2008. I think we have some
choices on how to implement/design a template engine.

1. Simple eval style like Scalate SSP or Play Scala.
2. Introduce a mini language like Liquid
3. Logic-less like Mustache

So I chose 3 because it was easy and I didn't want to design yet another
mini language. But probably we can choose 1 too.

> Regarding your changes, and having already admitted with the foregoing that
> I'm no authority, this sort of thing:
>
> +    engine.render(Map(
> +      "icon" -> icon,
> +      "owner" -> owner,
> +      "displayName" -> displayName,
> +      "order" -> order,
> +      "ancestors" -> ancestors,
> +      "constructors" -> constructorsElem,
> +      "types" -> types,
> +      "abstructValues" -> abstructValues,
> +      "concreteValues" -> concreteValues,
> +      "deprecatedValues" -> deprecatedValues,
> +      "comment" -> memberToCommentHtml(tpl, true)
> +    ))
>
> is exactly how I'd imagine going about things, so it looks good to me.
> Although I think I'd define it like:
>
>  def render(pairs: (String, Any)*)
>
> so I didn't have to throw around Map all the time.
>

Thanks, I will follow your advice.

Any comments? I'm going to merge into trunk tomorrow.

On Tue, Sep 6, 2011 at 10:02 AM, Kato Kazuyoshi
wrote:
> On Tue, Sep 6, 2011 at 3:48 AM, Paul Phillips wrote:
>> On 9/3/11 9:21 AM, Kato Kazuyoshi wrote:
>>>
>>> In Scaladoc, many HTML written inside Scala code. But it's hard to
>>> maintain.
>>> Then I implemented a small "template engine" and extracted HTML from Scala
>>> code.
>>>
>>> You can see my branch at GitHub.
>>> https://github.com/kzys/scala/commits/template
>>
>> Can anyone comment on what best practices have emerged in general regarding
>> how one cleanly separates code from markup? The last time I was working in
>> that medium directly was the 1990s, where we used PHP and java servlets, and
>> what I do remember is that there were big tradeoffs being made whatever
>> direction we moved.
>>
>> This is a language agnostic question.
>>
>
> Well, I've been working on the medium since 2008. I think we have some
> choices on how to implement/design a template engine.
>
> 1. Simple eval style like Scalate SSP or Play Scala.
> 2. Introduce a mini language like Liquid
> 3. Logic-less like Mustache
>
> So I chose 3 because it was easy and I didn't want to design yet another
> mini language. But probably we can choose 1 too.
>
>> Regarding your changes, and having already admitted with the foregoing that
>> I'm no authority, this sort of thing:
>>
>> +    engine.render(Map(
>> +      "icon" -> icon,
>> +      "owner" -> owner,
>> +      "displayName" -> displayName,
>> +      "order" -> order,
>> +      "ancestors" -> ancestors,
>> +      "constructors" -> constructorsElem,
>> +      "types" -> types,
>> +      "abstructValues" -> abstructValues,
>> +      "concreteValues" -> concreteValues,
>> +      "deprecatedValues" -> deprecatedValues,
>> +      "comment" -> memberToCommentHtml(tpl, true)
>> +    ))
>>
>> is exactly how I'd imagine going about things, so it looks good to me.
>> Although I think I'd define it like:
>>
>>  def render(pairs: (String, Any)*)
>>
>> so I didn't have to throw around Map all the time.
>>
>
> Thanks, I will follow your advice.
>
> --
> Kato Kazuyoshi
>

On Fri, Sep 9, 2011 at 2:40 AM, Kato Kazuyoshi <kato.kazuyoshi@gmail.com> wrote:

Any comments? I'm going to merge into trunk tomorrow.

Hi Kato,

Thanks for all the work you put into templates! I think it should definitely go in. :)

There's just one thing that's worth doing before you push into trunk: Could you add a scaladoc testcase that diffs the html pages generated against a reference? That would protect us from accidentally breaking things outside the scope of our commit -- for example templates should generate the exact same output -- you probably verified that by hand, but we should automate it. And this will also be useful in the future, to make sure no change produces unforeseen side effects.

For the check we could use a small but comprehensive example: 2-3 classes, packages, type bounds, manifests, existential types, implicits, links, tags, use cases, package objects for the check. -- the more features tested the better :)

What do you think?


Vlad

On Sat, Sep 10, 2011 at 2:08 AM, Vlad Ureche wrote:
>
> Hi Kato,
>
> Thanks for all the work you put into templates! I think it should definitely
> go in. :)
>
> There's just one thing that's worth doing before you push into trunk: Could
> you add a scaladoc testcase that diffs the html pages generated against a
> reference? That would protect us from accidentally breaking things outside
> the scope of our commit -- for example templates should generate the exact
> same output -- you probably verified that by hand, but we should automate
> it. And this will also be useful in the future, to make sure no change
> produces unforeseen side effects.
>
> For the check we could use a small but comprehensive example: 2-3 classes,
> packages, type bounds, manifests, existential types, implicits, links, tags,
> use cases, package objects for the check. -- the more features tested the
> better :)
>
> What do you think?
>

Thank you. I will add more tests before merge my branch.

Scaladoc had some tests already so I used it for verify my modification.
But the coverage is not so high. I think it's good time to write
comprehensive tests.