Status

()

Bugzilla
bugzilla.org
P2
normal
RESOLVED FIXED
16 years ago
5 years ago

People

(Reporter: CodeMachine, Assigned: gerv)

Tracking

2.15
Bugzilla 2.20

Details

(Reporter)

Description

16 years ago
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.20701@mozilla.org
(Reporter)

Updated

16 years ago
Priority: -- → P2
Target Milestone: --- → Bugzilla 2.18
(Assignee)

Comment 2

16 years ago
Does this need pushing out? Can't we just decide on something?

Gerv
(Reporter)

Comment 3

16 years ago
Style Rule: Use template comments rather than HTML comments, etc, so the comment
doesn't pass through to the browser and bloat the download.
(Reporter)

Comment 4

16 years ago
Fixing component ...
Assignee: justdave → barnboy
Component: Bugzilla-General → Documentation
(Assignee)

Comment 5

16 years ago
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.
Target Milestone: Bugzilla 2.18 → Bugzilla 2.16

Comment 7

16 years ago
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.
Status: NEW → ASSIGNED
how does that compare to what's already in use?

Comment 9

16 years ago
Guess I'll go need to check out the code on this one, not bothering trying to
resolve it right now.
(Assignee)

Comment 10

16 years ago
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:
<!-- 1.0@bugzilla.org -->

For non-HTML-based (or, all other) templates:
[%# 1.0@bugzilla.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.
Assignee: barnboy → mbarnson
Status: ASSIGNED → NEW
(Assignee)

Comment 15

16 years ago
MattyT: are you going to put this stuff in the Developers Guide? If so, this bug
is yours, not barnboy's :-)

Gerv
(Assignee)

Comment 16

16 years ago
MattyT: ping?

Gerv
(Reporter)

Comment 17

16 years ago
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.
(Assignee)

Comment 18

16 years ago
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
(Reporter)

Comment 19

16 years ago
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.
(Assignee)

Comment 20

16 years ago
> > 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
(Reporter)

Comment 21

16 years ago
You must be looking at different templates than me.

Anyway, nothing more is happening here for 2.16.
Target Milestone: Bugzilla 2.16 → Bugzilla 2.18

Comment 22

16 years ago
I'm not touching this one with a 10-foot pole :)  Tell me what you want, and
I'll change the Guide if necessary.

Comment 23

15 years ago
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 :)
Status: NEW → RESOLVED
Last Resolved: 15 years ago
Resolution: --- → FIXED
(Assignee)

Comment 24

15 years ago
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
.
Status: RESOLVED → REOPENED
Resolution: FIXED → ---
.
Assignee: matthew → matty
Status: REOPENED → NEW
Component: Documentation → bugzilla.org
QA Contact: matty → justdave

Comment 27

15 years ago
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?
Status: NEW → ASSIGNED
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.
Assignee: matty → gerv
Status: ASSIGNED → NEW
*** Bug 120925 has been marked as a duplicate of this bug. ***
Depends on: 140527

Comment 31

14 years ago
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.
Target Milestone: Bugzilla 2.18 → Bugzilla 2.20

Comment 32

14 years ago
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.
(Assignee)

Comment 33

14 years ago
Fair enough :-)

Gerv
Status: NEW → RESOLVED
Last Resolved: 15 years ago14 years ago
Resolution: --- → FIXED
QA Contact: justdave → default-qa
You need to log in before you can comment on or make changes to this bug.