267873 - FAQ overhaul

Status: RESOLVED FIXED

(Bugzilla :: Documentation, defect, P2)

Description

[Shane H. W. Travis]

Alright... so I'm looking in the FAQ, and I find one thing wrong. Was going to 
bug it, but then there were some more. I'm taking this one myself; these are 
all fairly small, so I've got them all in a single bug to keep track of them 
and just do one large FAQ update instead of a lot of little ones.

Feedback appreciated/requested where the assignee is notably clueless. :)

----------
A.1.2. How do I get commercial support for Bugzilla? 

http://bugzilla.org/consulting.html is a list of people and companies who have 
asked us to list them as consultants for Bugzilla. 
----------
Link should be: http://www.bugzilla.org/support/consulting.html


----------
A.1.6. Why doesn't Bugzilla offer this or that feature or compatibility with 
this other tracking software? 

You can help the project along by either hacking a patch yourself that supports 
the functionality you require, or else submitting a "Request for Enhancement" 
(RFE) using the bug submission interface at bugzilla.mozilla.org. 
----------
This seems wrong: wouldn't one submit a bug notmally, and just set the severity 
to 'Enhancement'?

----------
A.1.9. My perl is not located at /usr/bin/perl, is there an easy way to change 
it everywhere it needs to be changed? 

Yes, the following bit of perl magic will change all the shebang lines. Be sure 
to change /usr/local/bin/perl to your path to the perl binary. 

----------
Is there a reason it says /usr/bin/perl in the A, and /usr/local/bin/perl in 
the text? If they should be the same, which one should prevail?

Also, Dave's comment in bug 221693: "However, the command-line given there 
won't work on Windows unless you have cygwin."


----------
A.1.11. Does bugzilla run under mod_perl? 

At present, no. This is being worked on.
----------
It is? Where? I looked for mod_perl in the summary and comments of every open 
or resolved bug, and came up with Zarro Boogs. If there is a bug posted for 
this, we should enter it here; if not, we should stop lying to people. :-)

----------
A.2.7. Has anyone converted Bugzilla to another language to be used in other 
countries? Is it localizable? 

Yes. For more information including available translated templates, see 
http://www.bugzilla.org/download.html#localizations. The admin interfaces are 
still not included in these translated templates and is therefore still English 
only.
----------
'is'/'are' agreement.


----------
A.2.9. Does Bugzilla provide record locking when there is simultaneous access 
to the same bug? Does the second person get a notice that the bug is in use or 
how are they notified? 
A.2.11. Can users be on the system while a backup is in progress? 
A.2.12. How can I update the code and the database using CVS? 
A.2.16. Why do users have to log in every time they access a page? This affects 
everyone who accesses my Bugzilla. (If this only affects some of your users, 
see the next FAQ item.) 
A.2.17. Why do users have to log in every time they access a page? This only 
seems to affect some of my Bugzilla's users, others stay logged in. 
----------
These don't seem like 'Managerial' questions to me... at least, I've seldom had 
managers who had the level of technical expertise from the get-go to ask these 
sorts of questions. They seem more like Administrator FAQs, but there's no 
section for that; maybe one should be created and all these rounded up into it?

--- NEW ---
A.2.??. We don't like referring to problems as 'bugs'. Can we change that?

Yes! As of Bugzilla 2.18, it is a simple matter to change the word 'bug' into 
whatever word/phrase is used by your organization. See the documentation on 
Customization for more details.
-----------
(this is a *big* PHB issue, and probably one of the first things that most 
people are asked to customize. Yay for these variables!)

General question: Any suggestions for anything new that could go under section 
3. Bugzilla Security? Should we have something in here about groups?



----------
A.4.1. I have a user who doesn't want to receive any more email from Bugzilla. 
How do I stop it entirely for this user? 

The user should be able to set this in user email preferences (uncheck all 
boxes)
----------
'Should be able to'? Are there situations where they cannot?


----------
A.4.3. I want whineatnews.pl to whine at something other than new and reopened 
bugs. How do I do it? 

Try Klaas Freitag's excellent patch for "whineatassigned" functionality. You 
can find it in bug 6679. This patch is against an older version of Bugzilla, so 
you must apply the diffs manually. 
----------
6679 is ancient, and anyways has been resolved as a dupe of 185090, which has 
been marked RESOLVED and checked into the trunk with a milestone of 2.20. Any 
suggestions as to how this FAQ should be updated in light of this information?


----------
A.4.4. How do I set up the email interface to submit/change bugs via email? 

You can find an updated README.mailif file in the contrib/ directory of your 
Bugzilla distribution that walks you through the setup. 
----------
I thought everything regarding mail in the contrib directory was ancient and 
out of date; is that not so for this README? Or was it 'updated' when the FAQ 
was written, but the answer has rotted in the mean time?


----------
A.5.3. I want to manually edit some entries in my database. How? 

... Personal favorites of the Bugzilla team are phpMyAdmin and MySQL Control 
Center.
----------
MySQL Control Center link returns 404. Anyone have a new link?


----------
6. Bugzilla and Win32
----------
I don't know *anything* about running Bugzilla on Windows, and am not even 
qualified to tell if the answers to all these FAQs still hold true. Anyone want 
to give them the once-over and let me know?

A.6.1 should at least have a smiley on it...
Also, see attachment #145618 [details] [diff] [review] for Bug 239852 for some new words to add to this A.


----------
A.7.2. The query page is very confusing. Isn't there a simpler way to query? 

The interface was simplified by a UI designer for 2.16. Further suggestions for 
improvement are welcome, but we won't sacrifice power for simplicity. 
----------
Should there be a reference to the 'Find a specific bug' feature here?


----------
A.7.3. I'm confused by the behavior of the "accept" button in the Show Bug 
form. Why doesn't it assign the bug to me when I accept it? 
----------
Patches are from 2000 -- pre-templates and bitrotted to hell and back. Anything 
new to put here?

----------
A.8.1. What kind of style should I use for templatization? 
----------
Doesn't this properly belong in the Developer's guide? Is it *really* a FAQ?


---- NEW ----
bug 162060 and bug 156174 both discuss adding a FAQ for 'usevotes' 
and 'useconfirm'... not quite sure which section it should go in, though.
-------------

Comment 1

[GavinS]

re: mod_perl

Work is slowly taking place to remove global variables, use $cgi, and use DBI,
which are all sort of helping mod_perl, I think. (as well as being good for
other reasons)

re: admin template localisations.

1/2 are templatised now, but it's still probably not worth updating the FAQ
entry until they all are

Comment 2

[Dave Miller [:justdave]]

There's been some talk about getting the FAQ in a more-visible and
easier-to-update spot on the website, too, isntead of being buried in the docs.

wonder if this would be an appropriate time to do it? :)

Comment 3

[Jacob Steenhagen]

These all look like good updates to me... just need to find the time to make
them a part of the docs.

Dave: You could always just provide a more visible link on the website into the
docs. Unless you also mean adding things like searchability and a different style.

Comment 4

[Shane H. W. Travis]

Jake: discussion in IRC revealed that Dave was contemplating removing the FAQ 
from the docs completely, and making a single document with any version-
specific answers noted therein. This would be done in plain HTML in a style 
congruent with the rest of the front site, and would probably go somewhere 
obvious like http://www.bugzilla.org/docs/faq.html (or somesuch).

(Dave, feel free to correct me if I'm misrepresenting you here...)

I think it's a laudable idea, but outside the scope of this particular bug, 
which is just about getting it up-to-date with new information and removing the 
really old and crusty stuff (or at least making it obvious that it's really old 
and crusty). Dave, you want to open a new bug for that specific idea? Would be 
worth noting so it doesn't get lost...

As to 'getting to it'... don't worry about it, Jake. I've assigned it to myself 
(I guess I should accept it, eh?) and I'm working on it as time permits. Should 
have a first cut by the end of the week, I'm hoping.

Comment 5

[Max Kanat-Alexander]

  The mod_perl bug is bug 87406.

> A.4.1. I have a user who doesn't want to receive any more email from Bugzilla. 
> How do I stop it entirely for this user?

You'll also want to mention that you can put their email address in data/nomail.

> 6679 is ancient, and anyways has been resolved as a dupe of 185090, which has 
> been marked RESOLVED and checked into the trunk with a milestone of 2.20. Any 
> suggestions as to how this FAQ should be updated in light of this information?

  How about "Yes! Since Bugzilla 2.20, there is a very advanced bug notification
feature that allows each individual user to customize which notifications they
would like to receive."

> I thought everything regarding mail in the contrib directory was ancient and 
> out of date; is that not so for this README? Or was it 'updated' when the FAQ 
> was written, but the answer has rotted in the mean time?

  justdave has been working on a new email submission interface -- you might
want to ask him about it.

> MySQL Control Center link returns 404. Anyone have a new link?

  http://www.mysql.com/products/mysqlcc/

> Should there be a reference to the 'Find a specific bug' feature here?

  AbsoLUTEly. The only reason there isn't is that that's new to 2.18.

Comment 6

[:glob ✱]

I've created Bug 272886 to track moving the FAQ out of the documentation.

Comment 7

[Dave Miller [:justdave]]

(In reply to comment #5)
> > I thought everything regarding mail in the contrib directory was ancient and 
> > out of date; is that not so for this README? Or was it 'updated' when the
> > FAQ was written, but the answer has rotted in the mean time?
> 
>   justdave has been working on a new email submission interface -- you might
> want to ask him about it.

Actually, I haven't been.  That was employer-sponsored by my previous employer,
and they decided to write their own bug tracker rather than add stuff to
Bugzilla before we got anywhere with it.

The stuff is contrib has been being kept relatively up-to-date, and it still
works.  But it's a major hack, and it's not very user-friendly.

Comment 8

[Shane H. W. Travis]

Attachment: Doc changes for 2.18 and tip

Here we go boys and girls... it's a biggie. In addition to the textual changes
made above, I have also replaced all tabs with spaces and formatted the
document correctly. This makes for a LARGE patch file, meaning that nobody will
want to review it. :(

2.18/tip patch only; I'm not going to do a 2.16 patch because now that it's
(relatively) up-to-date I think that we SHOULD look at making it more prominent
somehow, so we can just use this version as the starting point for that.

Comment 9

[:glob ✱]

nit: "somebody with reasonable UNIX or Perl skills to handle"

you don't need unix skills to install bugzilla, as windows is now a supported
platform.

"Remove Windows. Install Linux. Install Bugzilla. The boss will never know the
difference. B^)"

while this is funny, can we remove this?  it's not very professional.

"In IIS, you do this by adding *.cgi to the App Mappings with the
<path>\perl.exe %s %s as the executable."

this should be:

  <perl path>\perl.exe -x<bugzilla path> -wT "%s"
  eg.  c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s"

Comment 10

[Jacob Steenhagen]

(In reply to comment #9)
> nit: "somebody with reasonable UNIX or Perl skills to handle"
> 
> you don't need unix skills to install bugzilla, as windows is now a supported
> platform.

reasonable perl skills and a familiarity with the operating system Bugzilla will
be running on?

> "Remove Windows. Install Linux. Install Bugzilla. The boss will never know the
> difference. B^)"
> 
> while this is funny, can we remove this?  it's not very professional.
 
We don't have to be professional all the time :). What we should do is add
something along the lines of "Seriously though, see <xref linkend="os-win32"/>
for detailed instructions."

Comment 11

[:glob ✱]

> reasonable perl skills and a familiarity with the operating system
> Bugzilla will be running on?

yup

> We don't have to be professional all the time :). What we should do is add
> something along the lines of "Seriously though, see <xref linkend="os-win32"/>
> for detailed instructions."

and yup

Comment 12

[Jacob Steenhagen]

Comment on attachment 168098 [details] [diff] [review]
Doc changes for 2.18 and tip

In the process of reviewing this patch I noticed a few things that could
probably be said better or moved to a different section of the guide. It
wouldn't suprise me if you found the same while writing it :). So, if the only
change being made was to white space, I tried to withold that comment (I'm sure
I didn't succeed the whole time).


faq-general-compare
  There's a sentence here that mentions an opinion of "the author." This should
probably be changed to something like the Orignal author or specifically state
that it's Mathew Barnson's opinion. After all, "the author" is now "The
Bugzilla Team."
  Do we still have a competitor's section? I'm pretty sure that got yanked
sometime in the past year.

faq-general-perlpath
  What if the perl path isn't /usr/bin/perl or /usr/local/bin/perl? This
question applies anytime the path to perl is something other than
/usr/bin/perl, not only when it's /usr/local/bin/perl
  There is the phrase "to get around this restriction." Is the perl path really
a restriction?
  *nit* Also, this would probably be better off as part of the installation
instructions than as an FAQ item... it is, after all, an installation issue.
And since the path was changed to no longer be include bonsaitools, this
question isn't asked nearly as frequently :).

faq-phb-client
  *nit* We could even say that it's all web based using standards or some
such... though a PHB probably doesn't even know what a standard is ;).

faq-admin-cvsupdate
  Making an excepting to my "no comments on spacing only" statement, there is
already a section in the guide about upgrading via CVS (as well as other
options). This should either by pulled from the FAQ or at least linked
appropriatly.

faq-admin-cvsupdate
faq-admin-reloginSome
  These are now troubleshooting items istead of FAQ's.

faq-nt
  *nit* I'm actually wondering if we should even still keep this section. It
seems it may be better to move all the information here into either
installation or troubleshooting (as appropriate). But I digress, that's not
what we're doing here :).


Well, that's pretty much it. I there are other changes that would make the FAQ
better, but those can be saved for later as it's not false information. If a
comment is prepended with *nit*, it means that review will not be denied
because of that issue.

Comment 13

[Shane H. W. Travis]

Attachment: Doc changes for 2.18 and tip, try #2

* added the mod_perl bug reference from comment #5 (missed it the first time)
* Made changes to satisfy Byron, as per comment #9 and comment #10. ;-)
* updated faq-email-testing with new information for 2.18

Responding to Jake (comment #12)

> So, if the only
> change being made was to white space, I tried to withold that comment 

If there is information that is factually inaccurate or in need of update, do
not hesitate to comment here. This is a general FAQ overhaul for 2.18, and I'd
like to catch as many of those things as possible.

Moving stuff to other sections of the guide... yeah, leave that for other bugs;
I'm just trying to be through *as far as the FAQ goes* in this bug.


> faq-general-compare
>   There's a sentence here that mentions an opinion of "the author." 

Reworded.

>   Do we still have a competitor's section? 

No. It's in the 2.16 docs. I left in the challenge to have commercial
bug-trackers send us a comparison, but removed reference to that section.

> faq-general-perlpath
>   What if the perl path isn't /usr/bin/perl or /usr/local/bin/perl? 

There was text there to cover that event; I've reworded it to make clearer.


>   There is the phrase "to get around this restriction." Is the perl path
really
> a restriction?

Word removed.


>   *nit* Also, this would probably be better off as part of the installation
> instructions than as an FAQ item... it is, after all, an installation issue.

Agreed in principle... but I'm not moving it as part of this bug. Eat the
sandwich one bite at a time...


> faq-phb-client
>   *nit* We could even say that it's all web based using standards or some
> such... though a PHB probably doesn't even know what a standard is ;).

Even if this is not 100% accurate, IMHO it's accurate *enough*. Having said
that, if it bugs you and you want to write up a sentence, I'll add it as part
of this bug.


> faq-admin-cvsupdate

Link added to <xref linkend="upgrade-cvs"/>. I agree that this would work
better in that section, but IMHO these instructions are better than those.
Amalgamating the two could be part of the next FAQ-bug ('remove things that
aren't FAQs any more').


> faq-admin-cvsupdate
> faq-admin-reloginSome
>   These are now troubleshooting items istead of FAQ's.

Removed reloginSome and reloginEveryone (I assume this was a typo...)



> faq-nt
>   *nit* I'm actually wondering if we should even still keep this section.

Worthy of discussion. File a bug. :)


> Well, that's pretty much it. I there are other changes that would make the
FAQ
> better, but those can be saved for later as it's not false information.

As I said, this is the "Global 2.18 FAQ Update for Accuracy And Completeness"
bug... so if you've got stuff that needs adding, new pieces of information,
stuff that you know that I don't, etc... let me have it; I'm happy to add it.
(That goes for everyone reading this.)

(The "Global 2.18 FAQ Upate for Reorganization and Categorization" is down the
hall, third door on your left... so take all those complaints there please. :)

Comment 14

[Jacob Steenhagen]

(In reply to comment #13)
> If there is information that is factually inaccurate or in need of update, do
> not hesitate to comment here. This is a general FAQ overhaul for 2.18, and I'd
> like to catch as many of those things as possible.

I didn't notice anything factually inacurate and withhold comment on it, but
next time I look trough this I'll try and actually look with an eye for general
updates, too :). Though any such instances will be nits and if that's all I find
I won't withhold r= for it.

> Moving stuff to other sections of the guide... yeah, leave that for other bugs;
> I'm just trying to be through *as far as the FAQ goes* in this bug.

Strangely enough, I agree. ;)

> > faq-phb-client
> >   *nit* We could even say that it's all web based using standards or some
> > such... though a PHB probably doesn't even know what a standard is ;).
> 
> Even if this is not 100% accurate, IMHO it's accurate *enough*. Having said
> that, if it bugs you and you want to write up a sentence, I'll add it as part
> of this bug.

I suppose if I really cared that much I'd have not marked it as a nit. If
something comes into my mind as I'm doing the next review I'll put it in.

> > faq-admin-cvsupdate
> 
> Link added to <xref linkend="upgrade-cvs"/>. I agree that this would work
> better in that section, but IMHO these instructions are better than those.
> Amalgamating the two could be part of the next FAQ-bug ('remove things that
> aren't FAQs any more').

Ya, integrating the two can certainly be its own bug.

> > faq-admin-cvsupdate
> > faq-admin-reloginSome
> >   These are now troubleshooting items istead of FAQ's.
> 
> Removed reloginSome and reloginEveryone (I assume this was a typo...)

Sure was

> > faq-nt
> >   *nit* I'm actually wondering if we should even still keep this section.
> 
> Worthy of discussion. File a bug. :)

OK, how about bug 274116?

I'll try and get this reviewed at work tonight.

Comment 15

[Jacob Steenhagen]

Umm, I'll learn how to type numbers w/out dyslexia taking over someday.

I meant bug 274166.

Comment 16

[Jacob Steenhagen]

Comment on attachment 168439 [details] [diff] [review]
Doc changes for 2.18 and tip, try #2

Only a couple non-nits :)

faq-general-support
> +            is a list of companies and individuals who have asked us to list them

*nit* Is more than 80 chars

faq-general-maintainers
> +            A 
> +      <ulink url="http://www.bugzilla.org/developers/profiles.html">core team</ulink>,
>        led by Dave Miller ([e-mail]).

*nit* spacing here isn't fixed.

faq-general-compare
> +            in touch. In the experience of Matthew Barnson (the original
> +            author of this FAQ), though, Bugzilla offers superior

*nit* I probably would have said "[...]experience of the original author,
Matthew Barnson, Bugzilla [...]"

General Comment: [e-mail] is an alias for justdave, right?
Perhaps it should be a mailing list??

faq-general-bzmissing
> +            Why doesn't Bugzilla offer this or that feature or compatibility
> +            with this other tracking software?

*nit* The wording of that question seems a little funky, but I'm not sure how
to reword it while still maintaining the meaning.

> +            and will stay there until Someone With Authority looks it

*nit* Is "Someone With Authority" really capitilazation worthy? It goes against
normal capatilization rules (proper name, begining of sentence, title)
seemingly without purpose.

> +            read the <ulink url="http://www.bugzilla.org/docs/developer.html">Developers' Guide</ulink>
> +            and <ulink url="http://www.bugzilla.org/docs/contributor.html">Contributors' Guide</ulink>

General Comment: Do these guides have some kinda of text preparing the new
contributor for possible disappointment? I'm not talking about a "we suck at
reviews" type of comment, but something that explains that often reviewers are
quite picky about how patches are done.

faq-general-mysql
>             There is currently work in progress to make Bugzilla work on
>             PostgreSQL and Sybase in the default distribution. You can track

Is this work still ongoing? I'm pretty sure Sybase isn't being actively worked
on anymore for Zippy (could be wrong). Wasn't Red Hat working on PostgreSQL
back when 2.17.1 came out? Has that gone anywhere?

faq-general-perlpath

I didn't see text in there that specified what to do if your target path isn't
/usr/local/bin/perl and the question in general is worded very much as if
that's the only possibility. On the flip side, somebody who has perl in a very
strange location (like /usr/bonsaitools/bin/perl was) can probably figure out
how to adapt thta command on their own.

faq-phb-priorities
> +            Does Bugzilla allow us to define our own priorities and levels? Do we
> +            have complete freedom to change the labels of fields and format of them, and

*nit* These lines don't wrap at 80 characters.

faq-phb-reporting
> +            Does Bugzilla provide any reporting features, metrics, graphs, etc? You

*nit* Doesn't wrap at 80 chars

faq-phb-email
> +            Is there email notification and if so, what do you see when you get an
*nit* Doesn't wrap at 80 chars. I'll stop talking about that now, though :)

faq-phb-reports

The answer to this question is very terse. We have the reporting stuff
documented, don't we? If so, we should provide a link to that section. Same
goes for the CSV/Excel stuff. If not, we should have bugs for that :).

faq-phb-cost

*nit* Perhaps we can elaberate on that simple 'no.' Something like: No,
Bugzilla, as well as the suport software needed to run it, can all be
downloaded and used for free. Followed by the MySQL bit.

faq-phb-renameBugs
> +            See the documentation on Customization for more details.

Can we do an <xref/> on this?

faq-admin-midair
> +            detection, and offers the offending user a choice of options to

*nit* Offending user sounds kinda harsh. Latter committer, perhaps? Or maybe
not, sounds kinda foreign, almost. Perhaps a breif description of what a midair
collision is. Maybe even as a seperate question. As an aside, I seem to
remember some people being really concerned seeing that error message in late
2001 :).

faq-admin-livebackup
It talks about if your database is small, but not if it's large. Perhaps we
should mention what to do in that case (database replicating, back up from
read-only mirror.

faq-email-mailif

Is this mailif known to work with 2.18? If not, we should probably mention
that.

faq-email-sendmailnow
> +            literal>off</literal>. Sites with application>sendmail</application>

Looks like we're missing a couple of <'s here.

> +            version 8.12 (or higher) should leave this <literal>on</literal>, as 
> +            they will not see any performance benefit.

I didn't know that... cool :).

faq-db-permissions

I'm not sure if I mentioned this one before or not, but we tell people in two
different places how to do something horrible (start MySQL w/out grant
permissions). While the $100 bill joke in the other one is funnier, this one
seems to be more complete and actually answers a question that might be a
reason for doing this. I think we should consider removing the other one.

faq-hacking-templatestyle

There's a developer's guide on the web page with this information, isn't there?
We should point people in that direct (if we even keep the question at all).

faq-hacking-patches

Same thing with this information. These policies and procedures should really
only be in one place and while I personally don't mind it being in the guide,
if it's going to be on the webpage instead, we should point people in that
direction.

If either one of the above have information that isn't on the web page, I'd
settle for a bug that request integration :).

Also, I was just noticing while doing this that we don't seem to have system
requirements. Do we even know what these are? I mean, I suppose any machine
that will run MySQL and Apache will run a small bugzilla installation, but what
about a mid-sized one? Do we have any guidelines we can give at all? OK, so
this should probably also be a seperate bug :P.

Comment 17

[Dave Miller [:justdave]]

(In reply to comment #16)
>faq-general-mysql
>>             There is currently work in progress to make Bugzilla work on
>>             PostgreSQL and Sybase in the default distribution. You can track
>
>Is this work still ongoing? I'm pretty sure Sybase isn't being actively worked
>on anymore for Zippy (could be wrong). Wasn't Red Hat working on PostgreSQL
>back when 2.17.1 came out? Has that gone anywhere?

Sybase support is no longer being worked on.  Even if it happens, it's VERY
unlikely to work without the end-user-company having to stick a few developers
on making several manual changes.  Sybase is just NOT very standards-compliant,
despite all the hype, and way too much had to be changed to make it work (like
moving half of the application logic into stored procedures to get any kind of
decent performance out of it).

We do actually have people semi-active on getting it working with Oracle again
though, and there are other folks besides RedHat assisting with Postgres now.

Comment 18

[Shane H. W. Travis]

Attachment: Doc changes for 2.18 and tip, try #3

* Rigid adherence to 80-character limit, save where it was not possible
    due to URLs and whatnot.
* Removed faq-db-oracle, and integrated that information with faq-general-mysql

* Updated faq-general-mysql with new Sybase non-compatibility info from Dave
    in comment #17
* Fixed most of the nits

Some specifics:

(In reply to comment #16)
> faq-general-perlpath
> I didn't see text in there that specified what to do if your target path
isn't
> /usr/local/bin/perl ...

<para>
  <note>
    If your perl path is something else again, just follow the
    above examples and replace
    <filename>/usr/local/bin/perl</filename> with your own perl path.
  </note>
</para> 	   

Not sure how much more clear I can be than that. :-)


> faq-phb-reports
> The answer to this question is very terse. We have the reporting stuff
> documented, don't we?

Sort of. Given the complexity of reports, that section could probably stand to
be fleshed out more. For now, though, included an xref to it.


> faq-phb-cost
> *nit* Perhaps we can elaberate on that simple 'no.'

Done.


> faq-phb-renameBugs
> > +		 See the documentation on Customization for more details.
> Can we do an <xref/> on this?

Done.


> faq-admin-midair
> > +		 detection, and offers the offending user a choice of options
to
> *nit* Offending user sounds kinda harsh. 

Reworded.


> As an aside, I seem to remember some people being really concerned
> seeing that error message in late 2001 :)

bug 177993: I just got those 2002 changes into the documentation last month.


> faq-email-mailif
> Is this mailif known to work with 2.18? If not, we should probably mention
> that.

No idea. I asked in my initial post, and have received no answer. Barring new
info, I leave it as it is.


> > faq-email-sendmailnow
> I didn't know that... cool :).

New info from Dave. I updated params.cgi as well in bug 273483.


> faq-db-permissions
> I'm not sure if I mentioned this one before or not, but we tell people in two

> different places how to do something horrible (start MySQL w/out grant
> permissions). While the $100 bill joke in the other one is funnier, this one
> seems to be more complete and actually answers a question that might be a
> reason for doing this. I think we should consider removing the other one.

IMHO, your new warning is enough to make people take notice.


> faq-hacking-templatestyle
> There's a developer's guide on the web page with this information, isn't
> there? We should point people in that direct (if we even keep the question at

> all).
> 
> faq-hacking-patches
> Same thing with this information.

Again, see my original comments/question, where I asked this same thing.

The only thing from the 'templatestyle' entry that isn't in
http://www.bugzilla.org/docs/developer.html#templates is the PRE_CHOMP bit; the
example there is taken verbatim from here.

The patches writeup is a little different from
http://www.bugzilla.org/docs/contributor.html#submitting-patches, in that it
makes mention of the newsgroup. Not sure that this is enough to warrant opening
a new bug against it vs. just deleting the section, though.


> If either one of the above have information that isn't on the web page, I'd
> settle for a bug that request integration :).

Make the call, I can live with it either way.


> Also, I was just noticing while doing this that we don't seem to have system
> requirements. ... OK, so this should probably also be a seperate bug :P.

So he *can* be taught! ;) :) :D


One iteration closer, and should be just about done this time.

Comment 19

[Jacob Steenhagen]

Comment on attachment 168725 [details] [diff] [review]
Doc changes for 2.18 and tip, try #3


faq-phb-reporting
> +            <xref linkend="reporting">Reports and Charts</xref> section.

*nit* Overall I like the |<xref linkend="reporting"/>| style that would output
|Section 6.10|. It may be less obvious what the section is titled (it'd be nice
if the HTML DocBook stylesheets would put that <title/> in a title= attribute
of the <a/> tag, but I digress), but it makes it easier to find in version of
the documentation that don't include hyperlinks (like plain text and printed).
Besides, the context should be enough to know that Section 6.10 must be about
reports and charts. Also, if you avoid the word "section" this will continue to
make sence should one day "Reports and Charts" be moved to a chapter or
appendix as DocBook would automagically substitute the correct word.

Only a *nit*, assuming it applies and compiles OK (I'm not near my docbook
setup right now), r=jake. I'll check it in when I get back to my room this
afternoon. I'll also file bugs for the other issues that are deffered (unless
somebody beats me to it :).

Comment 20

[Shane H. W. Travis]

(In reply to comment #19)

> *nit* Overall I like the |<xref linkend="reporting"/>| style that would output
> |Section 6.10|. 

I figured someone had to - it was all over the documentation. :)

It creates errors in (my current setup of) 'onsgmls' though because that tool 
says that there's no end link for the first xref. 

That's a minor thing, though. My main reason for doing it this way is that I 
think I misunderstood how it was being substituted. I'd swear that I went to 
look what it did on a page, and it didn't put |Section 6.10|... but instead 
replaced it with the words "Reports and Charts" (for example). My worry was 
that someone would change this title at some point, and mess up the context ()
and grammar) elsewhere in the docs.

> Also, if you avoid the word "section" this will continue to
> make sence should one day "Reports and Charts" be moved to a chapter or
> appendix as DocBook would automagically substitute the correct word.

I agree, and now that I know how it works better than I did, I agree with your 
usage above. If you're feeling ambitious, feel free to change those on checkin 
back to your preferred style; won't bother me none any more.


> Only a *nit*, assuming it applies and compiles OK

Should; as I said, it went through 'onsgmls -s' with no more errors than the 
original faq.xml.

I should probably install docbook one of these days...

Comment 21

[Jacob Steenhagen]

As it turns out, I was wrong about this element. It turns out the my suggested
syntax is the only valid way to use <xref/> as the element must remain empty:
http://www.docbook.org/tdg/en/html/xref.html. So, I fixed all those instances
and checked it in.

I'm not sure what would have made your test place "Reports and Charts" instead
of Section 6.10. I mean, if we had used an XRefLabel in that section, then it
would do that. But there isn't one on the reports section.

FYI, if you wish to link using custom text (which is needed in some cases, but
not most, IMHO), you can use the <link> tag.

Now to file those seperate issues :).

Comment 22

[Jacob Steenhagen]

OK, new bugs filed:

Bug 274872 - Perl path from comment 12
Bug 274874 - CVS Upgrading instructions from comment 12
Bug 274879 - Developer's guides from comment 16
Bug 274880 - System Requirements from comment 16

OK, I think I got 'em all :)