Skip to content

bugzilla
bugzilla
Commit ac2e474d authored by barnboy%trilobyte.net's avatar barnboy%trilobyte.net
Browse files
Options

Big checkin of docs to resolve every

known outstanding doc bug! Yay release. Still many things to fix. Aren't there always?
parent a07f84f3
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 272 additions and 114 deletions
docs/en/README.docs
View file @ ac2e474d
......@@ -2,33 +2,35 @@ Welcome to the Bugzilla documentation project!
You'll find these directories and files here:
README.docs # This README file
html/ # The compiled HTML docs from XML sources (do not edit)
txt/ # The compiled text docs from XML sources (do not edit)
xml/ # The original XML doc sources (edit these)
A note about the XML:
The documentation is written in DocBook 4.1.2, and attempts to adhere
to the LinuxDoc standards where applicable (http://www.tldp.org).
Please consult "The LDP Author Guide" at tldp.org for details on how
to set up your personal environment for compiling XML files.
html/ # The compiled HTML docs from SGML sources (do not edit)
sgml/ # The original SGML doc sources (edit these)
txt/ # The compiled text docs from SGML sources
ps/ # The compiled PostScript docs from SGML sources
pdf/ # The compiled Adobe PDF docs from SGML sources
A note about SGML:
The documentation is written in DocBook 3.1/4.1 SGML, and attempts to adhere
to the LinuxDoc standards everywhere applicable (http://www.linuxdoc.org).
Please consult "The LDP Author Guide" at linuxdoc.org for details on how
to set up your personal environment for compiling SGML files.
If you need to make corrections to typographical errors, or other minor
editing duties, feel free to use any text editor to make the changes. XML
editing duties, feel free to use any text editor to make the changes. SGML
is not rocket science -- simply make sure your text appears between
appropriate tags (like <para>This is a paragraph</para>) and we'll be fine.
If you are making more extensive changes, please ensure you at least validate
your XML before checking it in with something like:
nsgmls -s $JADE_PUB/xml.dcl Bugzilla-Guide.xml
your SGML before checking it in with something like:
nsgmls -s Bugzilla-Guide.sgml
When you validate, please validate the master document (Bugzilla-Guide.xml)
When you validate, please validate the master document (Bugzilla-Guide.sgml)
as well as the document you edited to ensure there are no critical errors.
The following errors are considered "normal" when validating with nsgmls:
DTDDECL catalog entries are not supported
"DOCTYPE" declaration not allowed in instance
The reason these occur is that free sgml/xml validators do not yet support
The reason these occur is that free sgml validators do not yet support
the DTDDECL catalog entries, and I've included DOCTYPE declarations in
entities referenced from Bugzilla-Guide.xml so these entities can compile
entities referenced from Bugzilla-Guide.sgml so these entities can compile
individually, if necessary. I suppose I ought to comment them out at some
point, but for now they are convenient and don't hurt anything.
......@@ -37,13 +39,13 @@ documentation. Please address comments and questions to the newsgroup:
news://news.mozilla.org/netscape/public/mozilla/webtools .
==========
HOW TO SET UP YOUR OWN XML EDITING ENVIRONMENT:
HOW TO SET UP YOUR OWN SGML EDITING ENVIRONMENT:
==========
Trying to set up an XML Docbook editing environment the
Trying to set up an SGML/XML Docbook editing environment the
first time can be a daunting task.
I use Linux-Mandrake, in part, because it has a fully-functional
XML Docbook editing environment included as part of the
SGML/XML Docbook editing environment included as part of the
distribution CD's. If you have easier instructions for how to
do this for a particular Linux distribution or platform, please
let the team know at the mailing list: mozilla-webtools@mozilla.org.
......@@ -60,96 +62,68 @@ rpms:
openjade
jadetex
docbook-dtds
docbook-dtd41-sgml
docbook-style-dsssl
docbook-dtd31-sgml
docbook-style-dsssl-doc
docbook-utils
xemacs
psgml
sgml-tools
sgml-common
Set up environment:
If you're getting these from RedHat, make sure you get the ones in the
rawhide area. The ones in the 7.2 distribution are too old and don't
include the XML stuff. The packages distrubuted with RedHat 8.0 and 9
and known to work.
in your .bashrc add this line (after installing above RPMS):
export SGML_CATALOG_FILES=/etc/sgml/catalog
Download "ldp.dsl" from the Resources page on tldp.org. This is the
Download "ldp.dsl" from the Resources page on linuxdoc.org. This is the
stylesheet I use to get the HTML and text output. It works well, and has a
nice, consistent look with the rest of the linuxdoc documents. You'll have to
adjust the paths in ldp.dsl at the top of the file to reflect the actual
locations of your docbook catalog files. I created a directory,
/usr/share/sgml/docbook/ldp, and put the ldp.dsl file there. I then edited
ldp.dsl and changed two lines near the top:
<!ENTITY docbook.dsl SYSTEM "../dsssl-stylesheets/html/docbook.dsl" CDATA
<!ENTITY docbook.dsl SYSTEM "../dsssl-stylesheets-1.62/html/docbook.dsl" CDATA
dsssl>
...and...
<!ENTITY docbook.dsl SYSTEM "../dsssl-stylesheets/print/docbook.dsl" CDATA
<!ENTITY docbook.dsl SYSTEM "../dsssl-stylesheets-1.62/print/docbook.dsl" CDATA
dsssl>
Note the difference is the top one points to the HTML docbook stylesheet,
and the next one points to the PRINT docbook stylesheet.
Also note that modifying ldp.dsl doesn't seem to be needed on RedHat 9.
You know, this sure looks awful involved. Anyway, once you have this in
You know, this sure looks awful involved. Anyway, once you have this in
place, add to your .bashrc:
export SGML_CATALOG_FILES=/etc/sgml/catalog
export LDP_HOME=/usr/share/sgml/docbook/ldp
export JADE_PUB=/usr/share/doc/openjade-1.3.1/pubtext
or in .tcshrc:
setenv SGML_CATALOG_FILES /etc/sgml/catalog
setenv LDP_HOME /usr/share/sgml/docbook/ldp
setenv JADE_PUB /usr/share/doc/openjade-1.3.1/pubtext
If you have root access and want to set this up for anyone on your box,
you can add those lines to /etc/profile for bash users and /etc/csh.login
for tcsh users.
Make sure you edit the paths in the above environment variables if those
folders are anywhere else on your system (for example, the openjade version
might change if you get a new version at some point).
I suggest xemacs for editing your XML Docbook documents. The darn
thing just works, and generally includes PSGML mode by default. Not to
mention you can validate the SGML from right within it without having to
remember the command-line syntax for nsgml (not that it's that hard
anyway). If not, you can download psgml at
http://www.sourceforge.net/projects/psgml.
Another good editor is the latest releases of vim and gvim. Vim will
recognize DocBook tags and give them a different color than unreconized tags.
I suggest xemacs for editing your SGML/XML Docbook documents. The darn
thing just works, and generally includes PSGML mode by default. You can
download psgml at http://www.sourceforge.net/projects/psgml.
==========
NOTES:
==========
Here are the commands I use to maintain this documentation.
You MUST have DocBook 4.1.2 set up correctly in order for this to work.
You MUST have DocBook 4.1 set up correctly in order for this to work.
Substitute your own path to "ldp.dsl" for "$LDP_HOME".
These commands can be run all at once using the ./makedocs.pl script.
To create HTML documentation:
bash$ cd html
bash$ jade -t sgml -i html -d $LDP_HOME/ldp.dsl\#html \
$JADE_PUB/xml.dcl ../xml/Bugzilla-Guide.xml
../sgml/Bugzilla-Guide.sgml
To create HTML documentation as a single big HTML file:
bash$ cd html
bash$ jade -V nochunks -t sgml -i html -d $LDP_HOME/ldp.dsl\#html \
$JADE_PUB/xml.dcl ../xml/Bugzilla-Guide.xml >Bugzilla-Guide.html
../sgml/Bugzilla-Guide.sgml >Bugzilla-Guide.html
To create TXT documentation as a single big TXT file:
bash$ cd txt
bash$ lynx -dump -nolist ../html/Bugzilla-Guide.html >Bugzilla-Guide.txt
Sincerely,
Matthew P. Barnson
The Bugzilla "Doc Knight"
mbarnson@sisna.com
with major edits by Dave Miller <justdave@syndicomm.com> based on
experience setting this up on the Landfill test server.
barnboy@trilobyte.net
docs/en/xml/Bugzilla-Guide.xml
View file @ ac2e474d
......@@ -23,7 +23,7 @@
<!ENTITY bz-ver "2.14">
<!ENTITY bz-cvs-ver "2.15">
<!ENTITY bzg-date "August 10, 2001">
<!ENTITY bzg-ver "2.14.0">
<!ENTITY bzg-ver "2.14">
<!ENTITY bzg-cvs-ver "2.15.0">
<!ENTITY bzg-auth "Matthew P. Barnson">
<!ENTITY bzg-auth-email "<email>barnboy@NOSPAM.trilobyte.net</email>">
......@@ -137,15 +137,6 @@ try to avoid clutter and feel free to waste space in the code to make it more re
</affiliation>
</collab>
<editor>
<firstname>I.</firstname>
<surname>Freely</surname>
<othername>P.</othername>
<affiliation>
<address><email>ipfreely@freely.eye-p.net</email></address>
</affiliation>
</editor>
</authorgroup>
<abstract>
......@@ -165,6 +156,12 @@ try to avoid clutter and feel free to waste space in the code to make it more re
professional on operating system upon which you install
Bugzilla.
</para>
<para>
THIS DOCUMENTATION IS MAINTAINED IN DOCBOOK 4.1 SGML FORMAT.
IF YOU WISH TO MAKE CORRECTIONS, PLEASE MAKE THEM IN PLAIN
TEXT OR SGML DIFFS AGAINST THE SOURCE. I CANNOT ACCEPT
ADDITIONS TO THE GUIDE WRITTEN IN HTML!
</para>
</abstract>
......
docs/en/xml/about.xml
View file @ ac2e474d
......@@ -14,11 +14,10 @@
document you see today.
</para>
<para>
Despite the lack of updates, Bugzilla is simply the best piece
of bug-tracking software the world has ever seen. This document
is intended to be the comprehensive guide to the installation,
administration, maintenance, and use of the Bugzilla
bug-tracking system.
Bugzilla is simply the best piece of bug-tracking software the
world has ever seen. This document is intended to be the
comprehensive guide to the installation, administration,
maintenance, and use of the Bugzilla bug-tracking system.
</para>
<para>
This release of the Bugzilla Guide is the
......
docs/en/xml/glossary.xml
View file @ ac2e474d
......@@ -26,9 +26,16 @@
<glossdiv id="gloss_a">
<title>A</title>
<glossentry>
<glossterm>There are no entries for A</glossterm>
<glossterm>Apache</glossterm>
<glossdef>
<para></para>
<para>In this context, Apache is the web server most
commonly used for serving up
<glossterm>Bugzilla</glossterm> pages. Contrary to
popular belief, the apache web server has nothing to do
with the ancient and noble Native American tribe, but
instead derived its name from the fact that it was
<quote>a patchy</quote> version of the original
<acronym>NCSA</acronym> world-wide-web server.</para>
</glossdef>
</glossentry>
</glossdiv>
......@@ -70,8 +77,77 @@
the needs of the organization using it, though.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Bugzilla</glossterm>
<glossdef>
<para>
Bugzilla is the industry-standard bug tracking system. It
is quite popular among Open Source enthusiasts.
</para>
</glossdef>
</glossentry>
</glossdiv>
<glossdiv id="gloss_c">
<title></title>
<glossentry id="gloss_component">
<glossterm>Component</glossterm>
<glossdef>
<para>
A Component is a subsection of a Product. It should be a
narrow category, tailored to your organization. All
Products must contain at least one Component (and, as a
matter of fact, creating a Product with no Components will
create an error in Bugzilla).
</para>
</glossdef>
</glossentry>
<glossentry id="gloss_cpan">
<glossterm><acronym>CPAN</acronym></glossterm>
<glossdef>
<para><acronym>CPAN</acronym> stands for the
<quote>Comprehensive Perl Archive Network</quote>. CPAN
maintains a large number of extremely useful
<glossterm>Perl</glossterm> modules. By themselves, Perl
modules generally do nothing, but when used as part of a
larger program, they provide much-needed algorithms and
functionality.</para>
</glossdef>
</glossentry>
</glossdiv>
<glossdiv id="gloss_d">
<title>D</title>
<glossentry>
<glossterm>daemon</glossterm>
<glossdef>
<para>A daemon is a computer program which runs in the
background. In general, most daemons are started at boot
time via System V init scripts, or through RC scripts on
BSD-based systems. <glossterm>mysqld</glossterm>, the
MySQL server, and <glossterm>apache</glossterm>, a web
server, are generally run as daemons.</para>
</glossdef>
</glossentry>
</glossdiv>
<glossdiv id="gloss_g">
<title></title>
<glossentry>
<glossterm>Groups</glossterm>
<glossdef>
<para>The word <quote>Groups</quote> has a very special
meaning to Bugzilla. Bugzilla's main security mechanism
comes by lumping users into groups, and assigning those
groups certain privileges to
<glossterm>Products</glossterm> and
<glossterm>Components</glossterm> in the
<glossterm>Bugzilla</glossterm> database.</para>
</glossdef>
</glossentry>
</glossdiv>
<glossdiv id="gloss_i">
<title>I</title>
<glossentry id="gloss_infiniteloop">
......@@ -81,7 +157,22 @@
</glossdef>
</glossentry>
</glossdiv>
<glossdiv id="gloss_m">
<title>M</title>
<glossentry>
<glossterm>mysqld</glossterm>
<glossdef>
<para>mysqld is the name of the
<glossterm>daemon</glossterm> for the MySQL database. In
general, it is invoked automatically through the use of
the System V init scripts on GNU/Linux and AT&amp;T System
V-based systems, such as Solaris and HP/UX, or through the
RC scripts on BSD-based systems.</para>
</glossdef>
</glossentry>
</glossdiv>
<glossdiv id="gloss_p">
<title>P</title>
<glossentry>
......@@ -108,6 +199,17 @@
</example>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Perl</glossterm>
<glossdef>
<para>First written by Larry Wall, Perl is a remarkable
program language. It has the benefits of the flexibility
of an interpreted scripting language (such as shell
script), combined with the speed and power of a compiled
language, such as C. <glossterm>Bugzilla</glossterm> is
maintained in Perl.</para>
</glossdef>
</glossentry>
</glossdiv>
<glossdiv id="gloss_q">
......@@ -129,8 +231,8 @@
<glossdiv id="gloss_r">
<title>R</title>
<glossentry>
<glossterm id="gloss_recursion">Recursion</glossterm>
<glossentry id="gloss_recursion" xreflabel="Recursion">
<glossterm>Recursion</glossterm>
<glossdef>
<para>The property of a function looking back at itself for
something. <quote>GNU</quote>, for instance, stands for
......@@ -140,10 +242,52 @@
</glossdef>
</glossentry>
</glossdiv>
<glossdiv id="gloss_s">
<title>S</title>
<glossentry>
<glossterm><acronym>SGML</acronym></glossterm>
<glossdef>
<para><acronym>SGML</acronym> stands for <quote>Standard
Generalized Markup Language</quote>. Created in the
1980's to provide an extensible means to maintain
documentation based upon content instead of presentation,
<acronym>SGML</acronym> has withstood the test of time as
a robust, powerful language.
<glossterm><acronym>XML</acronym></glossterm> is the
<quote>baby brother</quote> of SGML; any valid
<acronym>XML</acronym> document it, by definition, a valid
<acronym>SGML</acronym> document. The document you are
reading is written and maintained in
<acronym>SGML</acronym>, and is also valid
<acronym>XML</acronym> if you modify the Document Type
Definition.</para>
</glossdef>
</glossentry>
</glossdiv>
<glossdiv id="gloss_t">
<title>T</title>
<glossentry id="gloss_target_milestone" xreflabel="Target Milestone">
<glossterm>Target Milestone</glossterm>
<glossdef>
<para>
Target Milestones are Product goals. They are
configurable on a per-Product basis. Most software
development houses have a concept of
<quote>milestones</quote> where the people funding a
project expect certain functionality on certain dates.
Bugzilla facilitates meeting these milestones by giving
you the ability to declare by which milestone a bug will be
fixed, or an enhancement will be implemented.
</para>
</glossdef>
</glossentry>
</glossdiv>
<glossdiv id="gloss_z">
<title>Z</title>
<glossentry>
<glossentry id="zarro-boogs-found" xreflabel="Zarro Boogs Found">
<glossterm>Zarro Boogs Found</glossterm>
<glossdef>
<para>This is the cryptic response sent by Bugzilla when a
......
docs/en/xml/integration.xml
View file @ ac2e474d
......@@ -5,49 +5,59 @@
<chapter id="integration">
<title>Integrating Bugzilla with Third-Party Tools</title>
<section id="bonsai">
<section id="bonsai" xreflabel="Bonsai, the Mozilla automated CVS management system">
<title>Bonsai</title>
<para>We need Bonsai integration information.</para>
<para>Bonsai is a web-based tool for managing <xref
linkend="cvs">
. Using Bonsai, administrators can control open/closed status
of trees, query a fast relational database back-end for change,
branch, and comment information, and view changes made since the
last time the tree was closed. These kinds of changes cause the
engineer responsible to be <quote>on the hook</quote> (include
cool URL link here for Hook policies at mozilla.org). Bonsai
also includes gateways to <xref
linkend="tinderbox"> and Bugzilla </para>
</section>
<section id="cvs">
<section id="cvs" xreflabel="CVS, the Concurrent Versioning System">
<title>CVS</title>
<para>CVS integration is best accomplished, at this point, using the Bugzilla Email Gateway.</para>
<para>CVS integration is best accomplished, at this point, using
the Bugzilla Email Gateway. There have been some files
submitted to allow greater CVS integration, but we need to make
certain that Bugzilla is not tied into one particular software
management package.</para>
<para>
Follow the instructions in the FAQ for enabling Bugzilla e-mail
integration. Ensure that your check-in script sends an email to
your Bugzilla e-mail gateway with the subject of <quote>[Bug
XXXX]</quote>, and you can have CVS check-in comments append
to your Bugzilla bug. If you have your check-in script include
an @resolution field, you can even change the Bugzilla bug
state.
</para>
</section>
<section id="scm">
<section id="scm" xreflabel="Perforce SCM (Fast Software Configuration Management System, a powerful commercial alternative to CVS">
<title>Perforce SCM</title>
<para>
You can find the project page for Bugzilla and Teamtrack Perforce integration at:
<ulink url="http://www.ravenbrook.com/project/p4dti/">
http://www.ravenbrook.com/project/p4dti</ulink>. "p4dti" is now an officially
supported product from Perforce, and you can find the "Perforce Public Depot"
p4dti page at <ulink url="http://public.perforce.com/public/perforce/p4dti/index.html">
http://public.perforce.com/public/perforce/p4dti/index.html</ulink>.
</para>
<para>
Integration of Perforce with Bugzilla, once patches are applied, is fairly seamless. However,
p4dti is a patch against the Bugzilla 2.10 release, not the current 2.12 release. I anticipate
patches for 2.12 will be out shortly. Check the project page regularly for updates, or
take the given patches and patch it manually. p4dti is designed to support multiple defect
trackers, and maintains its own documentation for it. Please consult the pages linked
above for further information.
You can find the project page for Bugzilla and Teamtrack
Perforce integration (p4dti) at: <ulink
url="http://www.ravenbrook.com/project/p4dti/"> http://www.ravenbrook.com/project/p4dti</ulink> . <quote>p4dti</quote> is now an officially supported product from Perforce, and you can find the "Perforce Public Depot" p4dti page at <ulink url="http://public.perforce.com/public/perforce/p4dti/index.html"> http://public.perforce.com/public/perforce/p4dti/index.html</ulink>.
</para>
<para>
Right now, there is no way to synchronize the Bug ID and the Perforce Transaction Number, or
to change the Bug ID to read (PRODUCT).bugID unless you hack it in. Additionally, if you
have synchronization problems, the easiest way to avoid them is to only put the bug
information, comments, etc. into Bugzilla, and not into the Perforce change records.
They will link anyway; merely reference the bug ID fixed in your change description,
and put a comment into Bugzilla
giving the change ID that fixed the Bugzilla bug. It's a process issue, not a technology
question.
Integration of Perforce with Bugzilla, once patches are applied,
is seamless. Perforce replication information will appear below
the comments of each bug. Be certain you have a matching set of
patches for the Bugzilla version you are installing. p4dti is
designed to support multiple defect trackers, and maintains its
own documentation for it. Please consult the pages linked above
for further information.
</para>
</section>
<section id="tinderbox">
<title>Tinderbox</title>
<para>We need Tinderbox integration information</para>
<section id="tinderbox" xreflabel="Tinderbox, the Mozilla automated build management system">
<title>Tinderbox/Tinderbox2</title>
<para>We need Tinderbox integration information.</para>
</section>
</chapter>
......
docs/en/xml/patches.xml
View file @ ac2e474d
......@@ -3,6 +3,40 @@
<appendix id="patches" xreflabel="Useful Patches and Utilities for Bugzilla">
<title>Useful Patches and Utilities for Bugzilla</title>
<para>Are you looking for a way to put your Bugzilla into overdrive? Catch some of the niftiest tricks here in this section.</para>
<section id="rewrite" xreflabel="Apache mod_rewrite magic">
<title>Apache <filename>mod_rewrite</filename> magic</title>
<para>Apache's <filename>mod_rewrite</filename> module lets you do some truly amazing things with URL rewriting. Here are a couple of examples of what you can do.</para>
<orderedlist>
<listitem>
<para>
Make it so if someone types
<computeroutput>http://www.foo.com/12345</computeroutput>,
Bugzilla spits back
http://www.foo.com/show_bug.cgi?id=12345. Try setting up
your VirtualHost section for Bugzilla with a rule like
this:</para>
<programlisting>
<![CDATA[
<VirtualHost 12.34.56.78>
RewriteEngine On
RewriteRule ^/([0-9]+)$ http://foo.bar.com/show_bug.cgi?id=$1 [L,R]
</VirtualHost>
]]>
</programlisting>
</listitem>
<listitem>
<para>There are many, many more things you can do with
mod_rewrite. As time goes on, I will include many more in
the Guide. For now, though, please refer to the mod_rewrite
documentation at <ulink
url="http://www.apache.org">http://www.apache.org</ulink></para>
</listitem>
</orderedlist>
</section>
<section id="setperl" xreflabel="The setperl.csh Utility">
<title>The setperl.csh Utility</title>
<para> You can use the "setperl.csh" utility to quickly and
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment