Wrapping HTML in templates

[Jouni Heikniemi]

Christian Robottom Reis wrote:

> Jouni's giving me a hard time because I'm reluctant to wrap HTML in
> templates.  I'm trying to figure out what the right way to do this is; it
> isn't as trivial as it seems. This may pass as ironical to people who
> know me for being a strict 72-char wrapper; I just don't think this rule
> applies very well to the whitespace-intolerant nature of HTML, in
> particular, HTML links.

;-) Here are my two cents. But to start off: No, I don't think it's a 
trivial matter, and no, I don't think 80 chars is an überstrict border 
we must obey at all costs. If wrapping results in bizarre code, let's 
ignore it. The rule is there to clean up code, not to promote itself.

However, I disagree with your thoughts on the "whitespace-intolerant 
nature of HTML" - HTML by itself is very whitespace-tolerant, although 
the issue of links expanding to a single whitespace around the actual 
link texts is somewhat problematic. However, wrapping inside the 
elements is not a new concept, and it's one we're already recommending 
in the devguide.

I think the guide's two golden rules on HTML templates are pretty good:

# Indentation - HTML Templates should have a 2-space indent.

# Line Length - You shouldn't extend lines past 80 characters - instead, 
break lines, in the middle of multi-attributed HTML tags if necessary.

>     a) How does one wrap a long link which isn't broken by template
>        statements?
>         <p><a href=query.cgi>Skip all this nonsense, and go back to the query page</a>\n";

Well, this one is easy, since you can just wrap the text. Then again, I 
wouldn't bother in _every_ situation. I think the biggest point here is 
that the non-visible part of the line (assume everything beyond 80 
chars) shouldn't contain surprises. In that particular example, it 
doesn't. I'd have a better feeling about; it _is_ more readable anyway.

   <p><a href="query.cgi">Skip all this nonsense, and go
                          back to the query page</a>



>     b) How does one wrap a long link which *is* broken by template
>        statements?
>        <a href="[% INCLUDE diffurl attachid=attachid %]&headers=[% headers FILTER html %]&context=file">File</a> / 

I am under the impression that we've been developing a practice of 
wrapping before a TT tag. For that example, I prefer

<a href="[% INCLUDE diffurl attachid=attachid %]&headers=
          [% headers FILTER html %]&context=file">File</a> /

>     c) How does one wrap a long HTML statement that includes <a> tags
>        (and therefore doesn't like spurious spacing here and there) such
>        as:

That is difficult. Before I go after your example, let me note you about 
  a couple of different tactics used elsewhere, neither of which I would 
be ready to incorporate into devguide but which might save you at some 
point:

<a href="foo"
    title="bar"
    hreflang="baz"><!--
   -->Link text
   Continues
   Here<!--
--></a>

(that particular demo blows, but you get the idea with SGML comments)

A similar approach:


<a href="foo"
    title="bar"
    hreflang="baz"
   >Link text
   Continues
   Here<!--
--></a>

However, that one's very ill-suited to closing tags, so I think it has 
very limited usability.

> I've tended to use the policy: if a large portion of the line isn't
> wrappable, don't bother with wrapping smaller parts of it unless it
> makes things a lot better. Is that a bad policy?

Perhaps to your surprise, I think it's a good policy. It's just that 
overusing it destroys whatever clarity we've reached by aiming for the 
80 char line length. To look at your example:

>          <td class="file_head" colspan="2"><a href="#" 
>             onclick="return twisty_click(this)">[% 
>                 collapsed ? '(+)' : '(-)' %]</a><input 
>                     type="checkbox" name="[% file.filename FILTER html %]"[% 
>                          collapsed ? '' : ' checked' %] style="display: none"> 

Yes, this is ugly too. It's ugly among other things because you're 
increasing the indentation all the way, so the readability of the actual 
hierarchy suffers. These are some of the cases where SGML commenting the 
linefeed may actually help pretty significantly; it allows you to keep 
indentation in check while preserving at least some wrapping freedom.

One more thing: When facing a hard wrapping problem, I often first cut 
slack on the indentation rules of irrelevant elements to give more 
horizontal space.

Here's a quick shot which goes to one extreme with grouping "irrelevant" 
tags on the same line; that might be pushing it. Also note that you 
usually _can_ have whitespace at the beginning/end of flow/block content 
(like <td>; that's different from inline content like <a>).

<table class="file_table><thead><tr>

   <td class="file_head" colspan="2">

     <a href="#" onclick="return twisty_click(this)">
       [% collapsed ? '(+)' : '(-)' %]</a><!--

  --><input type="checkbox"
            name="[% file.filename FILTER html %]"
            [% collapsed ? '' : ' checked' %]
            style="display: none">

   </td>

</tr></thead></table>


Well, that's not the best I've seen or made, but I think it beats the 
250 char line. There's a lot you could work on, but I think works the 
same as your original example (I can't easily test the interdiff patch 
locally :-() and perhaps more readable. At least you can see the whole 
thing at a glance. What do you think?


Jouni

Ps. Hey, you could avoid using the <!-- --> by starting the latter tag 
with [% "<" %], thus invoking pre_chomp. O:-)