274173 - The Params that are listed in section 3.1 (parameters) should use a <varlist/>

Status: RESOLVED FIXED

(Bugzilla :: Documentation, defect)

Description

[Jacob Steenhagen]

Section 3.1 in the current tip docs (id="parameters") would be better suited,
IMHO, to using the <varlist/> docbook tag instead of <step/>.

Comment 1

[Shane H. W. Travis]

I'll take this one, as it'll be a good excuse for me to learn about </varlist>. 
(I'm picking up SGML as I go along...)

Meta-issue: This bug was originally a comment in a review of bug 256019, 
labelled as a 'nit'. I think that making a new bug for it was a good idea, 
because it's not really a nit - it's a change. Not a *big* change, mind, but a 
change nonetheless.

My opinion is that it's okay to fix nits as the original bug gets checked in, 
rather than either asking the original submitter to make a new patch or opening 
a new bug against it... as long as they are actually nits. To my mind, 
the 'nit' category includes things like typos and spelling mistakes, 
malformed/unclosed SGML tags, mis-capitalization, spacing/wrap changes, or any 
other situation where the reviewer can make the change with near-to-100% 
certainty that the intent and meaning of the original submitter is not being 
altered. For stuff like that... my feeling is 'mention it, but just fix it on 
checkin'; makes things easier for just about everyone, including the reviewer 
(who doesn't then have to review ANOTHER patch for trivial changes like these).

Anyway, as I said, that's a meta-issue and not really related to this one at 
all.



I know that this position will probably be perceived as inconsistent with my 
earlier 

Comment 2

[Jacob Steenhagen]

In the past I've always used *nit* to mean "This is something I'm gonna mention,
but I'm not gonna withhold review if it's not fixed in a later version or if all
I find if *nits*." Kinda like a short for "I'm being nit-picky here, but..."
type of thing. A spelling error or error in the XML is something that /needs/
(unless it's the the color/colour argument) to be corrected, not something that
may or may not be corrected. If it's a small enough error (and again, no other
glaring errors), then "fix it on checkin" is fine.

I guess it was all a bit of ambiguity about what exactly was meant by *nit* :).
As I simple meant "it may or may not be corrected in the next patch... I don't
really care," I filed a seperate bug about it to indicate that, in fact, may not
was probably the better option.

Comment 3

[Shane H. W. Travis]

Attachment: Doc changes for 2.16

Comment 4

[Shane H. W. Travis]

Attachment: Doc changes for 2.18 and tip

Comment 5

[Colin Ogilvie [:cso]]

Comment on attachment 171783 [details] [diff] [review]
Doc changes for 2.16

I've reviewed this by checking it applies and looking at the patch; I can not
get 2.16 documents to build because they are invalid XML.

Comment 6

[Shane H. W. Travis]

2.16:
Checking in administration.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/administration.xml,v  <--  
administration.xml
new revision: 1.13.2.22; previous revision: 1.13.2.21
done

2.18:
Checking in administration.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/administration.xml,v  <--  
administration.xml
new revision: 1.34.2.9; previous revision: 1.34.2.8
done

Tip:
Checking in administration.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/administration.xml,v  <--  
administration.xml
new revision: 1.45; previous revision: 1.44
done