273519 - The bz-devel ENTITY is not valid XML

Status: RESOLVED FIXED

(Bugzilla :: Documentation, defect, P2)

Description

[Jacob Steenhagen]

As pointed out in bug 265995, the use of and entity to exclude certain text is
not valid in XML (which means it's also not part of the DocBook 4 spec). I'm
rather attached to it, so removing it is something I'm reluctant to do.

Comment 1

[Dave Miller [:justdave]]

Heh, I just replied to the checkin message from bug 265995 on the developers
list before I saw this.  Here's what I wrote:

Let's complete the process.  Let's figure out what's being conditionally changed
based on that and unconditionally display it on the trunk, and remove it on the
branches.  And let's get it documented with our "what to do as we prepare for a
release" as to what needs to be removed in the release versions.

Comment 2

[Colin Ogilvie [:cso]]

Is that not what my original patch proposed, or do you mean something different ?

Comment 3

[Jacob Steenhagen]

Because of my abuse of this entity, what was there is no longer sufficient. I
like to use this entity to enter things inline so that with or without them, the
sentence is still gramatically correct. That is certainly more difficult using a
seperate entity for each use.

I, too, am curious as to what you meant, Dave. Were you thinking something like
what's in the patch on bug 265995? Or something different like:

text, blah, blah, this is new for the 2.18 release
<!-- REMOVE FOR RELEASE --> and first appeared in 2.17.4<!-- /REMOVE -->.

Or something completely different?

Comment 4

[Dave Miller [:justdave]]

either one of those would work for me.  What I actually had in mind was
something more like the latter.  Just write it out like we would (in place, no
entity) if it's a development release, and after we branch for a release, we
just change the wording on the branch to no longer imply the development stuff.

Comment 5

[Jacob Steenhagen]

Attachment: Patch for 2.18

Obviously 2.18 will never again be a development version, so arbitrarily
pulling out all the bz-devel section won't hurt a thing for that branch :).

Comment 6

[Jacob Steenhagen]

Dave: Do you want this to block 2.18?

Also, I think maybe a syntax that used:

<!-- BZ-DEVEL --> This was fixed in 2.19.1 <!-- /BZ-DEVEL -->

is probably the best bet. Then we could grep for BZ-DEVEL in the branch before a
release.

Comment 7

[Dave Miller [:justdave]]

(In reply to comment #6)
> Dave: Do you want this to block 2.18?

Sure.

> <!-- BZ-DEVEL --> This was fixed in 2.19.1 <!-- /BZ-DEVEL -->

Yes, I like that.

Comment 8

[Shane H. W. Travis]

Comment on attachment 169080 [details] [diff] [review]
Patch for 2.18

Jake probably (almost certainly) knows more about these tags and their use than
me, so I just checked for spelling, grammar, punctuation, etc. Since this patch
is mostly deletions, there's not much to look at. :)  r+

Comment 9

[Jacob Steenhagen]

Bug 275595 submitted to cover removing this from the tip.

Checking in Bugzilla-Guide.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/Bugzilla-Guide.xml,v  <-- 
Bugzilla-Guide.xml
new revision: 1.37.2.8; previous revision: 1.37.2.7
done
Checking in about.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/about.xml,v  <--  about.xml
new revision: 1.16.2.3; previous revision: 1.16.2.2
done
Checking in installation.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/installation.xml,v  <-- 
installation.xml
new revision: 1.72.2.14; previous revision: 1.72.2.13
done
Checking in troubleshooting.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/troubleshooting.xml,v  <-- 
troubleshooting.xml
new revision: 1.2.2.2; previous revision: 1.2.2.1
done