We need to work out the style guide for templates. In particular, whether we indent to make templates look right, or the source code to look right. Once this is done we need to document it in the hackers' guide.
Let's do both per Gerv's post in n.p.m.webtools. news://news.mozilla.org:119/3BDD9D2C.firstname.lastname@example.org
Does this need pushing out? Can't we just decide on something? Gerv
Style Rule: Use template comments rather than HTML comments, etc, so the comment doesn't pass through to the browser and bloat the download.
Fixing component ...
What I said: "We need to talk about this, because templates are not the same as code. The problem is that it's good to nest tags using indentation, but there are often a large number of levels of tags. Here's what I propose: 2-space indent. Embedded code sections on their own line, in line with outer tags. So: <fred> [% IF foo %] <bar> [% FOREACH x = barney %] <tr> <td> [% x %] </td> <tr> [% END %] [% END %] </fred> I also recommend we turn on PRE_CHOMP in the template initialisation; this prevents us bloating the resulting HTML with a load of whitespace the client is just going to ignore. Combining that with the above indenting scheme happens to produce nicely-formatted resulting source, as well." Do we need to define anything else? I prefer to stick to an 80-char line length; we should certainly define _some_ maximum line length. We might want to add points about using hashes for readability, as Myk recommended for query.cgi. Lastly, we should be allowed to reset the indentation back to zero, if it gets too deep, by using two blank lines: ... <foo> <bar> <baz rel="yaya" href="http://www.a-long-url.com/more-url-text"> <another-tag /> <another-tag /> <tr> <td> Foo! </td> </tr> <another-tag /> </baz> </bar> </foo> ... Gerv
The docs should always be up-to-date when we release. Forgot to exclude Documentation when I mass-retargetted.
I am putting this into the docs as 4-space indent so that there's no disconnect between Perl coding standards and Template coding standards.
how does that compare to what's already in use?
Guess I'll go need to check out the code on this one, not bothering trying to resolve it right now.
A 4-space indent is inappropriate, and the disconnect is intentional. Please read again what I wrote above. In code, multi-levels of indentation indicates logic problems, and makes you lean towards a restructuring. Also, lines of code tend to be long. In HTML, a line can be a single tag, and deep nesting is common. A 4-line indent would cause a great deal of trouble because most of the important code would need to be crammed into the last 30 characters of the line it's on! Also, all my templates (don't know about Myk's, but he backs my views) are 2-space. Gerv
As I said in IRC yesterday: 12:47:30 <myk> i agree with Gerv. first of all, there is no reason to maintain a single indentation standard across totally different kinds of documents just so we can say we have a standard. 12:48:16 <myk> the number of different kinds of documents should dictate the number of standards. 12:49:48 <myk> so there is no conflict at all between the template and Perl code standards... each one expresses the optimal formatting for those kinds of files 12:51:04 <myk> second of all, two-space indents work well for HTML files and HTML templates for the reason already mentioned: there are often numerous levels of indentation. 12:53:26 <myk> also, in my personal opinion, two-space indentation strikes the optimal balance between no indentation and too much indentation, both of which make it difficult to discern the document's structure 12:56:36 <myk> it should also be noted that indentation is not the only mechanism by which the structure of code or markup can be delineated, and we should not treat it as such 12:57:24 <myk> syntax highlighting, code tree generation, and other mechanisms can and should be used in addition to indentation by Bugzilla hackers to help them read the code As with Gerv's templates, all mine are two-space indented, and as far as I know that means all current Bugzilla templates use two-space indentation.
Document template versioning information: For HTML-based templates: <!-- email@example.com --> For non-HTML-based (or, all other) templates: [%# firstname.lastname@example.org %] NOTE: This comment MUST appear as the first line of the file!
major version update -> incompatible change; an old template won't work minor version update -> compatiable change; an older template may not be able to take advantage of new features, but what it had still works.
Barnboy changed his email address and opened a new account instead of having the address changed on his existing one. Reassigning all docs bugs to his new account.
MattyT: are you going to put this stuff in the Developers Guide? If so, this bug is yours, not barnboy's :-) Gerv
MattyT: ping? Gerv
Everything is pretty much within the guide except the indentation policy mentioned on the first line. I didn't document because I disagreed with it and hadn't got around to raising the issue. As far as I know you're the only one who supports it Gerv.
What exactly about the indentation policy don't you like? Every single template in Bugzilla (and there are now over 50) that I am aware of conforms to my suggestions for indentation (2-space etc.) So I'm not alone :-) Gerv
First Line = "... In particular, whether we indent to make templates look right, or the source code to look right." That's what I have a problem with. And no, they aren't all the same style. A quick look shows Myk still uses template-looks-right indentation, even though all my templates are currently on branches I think.
> > In particular, [we need to consider] whether we indent to make templates > > look right, or the source code to look right. > > That's what I have a problem with. You have a problem with me suggesting we consider that question? :-) I suggested an indentation scheme which made the templates look nice, and mentioned in passing that it also produced readable HTML. It doesn't have to be one or the other; we can have both. But I agree template readability is more important than HTML readability - and I chose the scheme I did on that basis. Gerv
You must be looking at different templates than me. Anyway, nothing more is happening here for 2.16.
I'm not touching this one with a 10-foot pole :) Tell me what you want, and I'll change the Guide if necessary.
Changed my mind. Lumped this into the FAQ section so we can get the bug off the boards; if someone later decides to relocate this information, by all means feel free :)
This should not be in the FAQ section of the Bugzilla Guide; in fact, it should not be in the Bugzilla Guide at all. We have a perfectly good Developers' Guide, where developers look for information relating to development. They will not look in the Bugzilla Guide FAQ for details of how to write templates. Please reopen this bug until the information is in the right place :-) Gerv
Hmm... help me out, I'm not seeing a "Developer's Guide" in my CVS checkout of the source or on the bugzilla.org website. What am I missing?
it's in the bugzilla.org website. Try cvs update -dP
This is sitting too long. Looks from the comments we have here that we already have a decision. Someone just needs to put it in place on the website.
*** Bug 120925 has been marked as a duplicate of this bug. ***
Unloved bugs targetted for 2.18 but untouched since 9-15-2003 are being retargeted to 2.20 If you plan to act on one immediately, go ahead and pull it back to 2.18.
After reading the Developer's Guide at http://www.bugzilla.org/developerguide.html, it seems that the information this bug deals with in already in place: # Indentation - HTML Templates should have a 2-space indent.
Fair enough :-) Gerv