From 1f0fa1587da75d64582ddade2c21efeec3bea8b1 Mon Sep 17 00:00:00 2001 From: "jake%bugzilla.org" <> Date: Fri, 4 Apr 2008 11:46:31 +0000 Subject: The source files for the Bugzilla Guide have long been using the XML version of DocBook but still residing in the sgml/ directory with an extension of .sgml. In an effort to maintain CVS history, the raw files were copied on the CVS server to the xml/ directory and renamed to have .xml for the extension; any checkins before this one did have the .sgml extension. --- docs/en/README.docs | 96 ++++++++++++++++--------- docs/en/xml/Bugzilla-Guide.xml | 42 +++++------ docs/en/xml/about.xml | 151 ++++++++++++++++++++++++--------------- docs/en/xml/administration.xml | 2 +- docs/en/xml/conventions.xml | 2 +- docs/en/xml/gfdl.xml | 6 +- docs/en/xml/glossary.xml | 67 +++++++++++++---- docs/en/xml/index.xml | 3 +- docs/en/xml/installation.xml | 6 +- docs/en/xml/integration.xml | 2 +- docs/en/xml/introduction.xml | 90 +++++++++++++++-------- docs/en/xml/patches.xml | 4 +- docs/en/xml/requiredsoftware.xml | 104 ++++++++++++++------------- docs/en/xml/using.xml | 2 +- 14 files changed, 354 insertions(+), 223 deletions(-) diff --git a/docs/en/README.docs b/docs/en/README.docs index 4ccd7044d..18c4126b8 100644 --- a/docs/en/README.docs +++ b/docs/en/README.docs @@ -3,34 +3,32 @@ You'll find these directories and files here: README.docs # This README file html/ # The compiled HTML docs from SGML sources (do not edit) -sgml/ # The original SGML doc sources (edit these) +xml/ # The original XML 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. + +A note about the XML: + The documentation is written in DocBook 4.1.2, and attempts to adhere +to the LinuxDoc standards everywhere 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. 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. SGML +editing duties, feel free to use any text editor to make the changes. XML is not rocket science -- simply make sure your text appears between appropriate tags (like This is a paragraph) and we'll be fine. If you are making more extensive changes, please ensure you at least validate -your SGML before checking it in with something like: - nsgmls -s Bugzilla-Guide.sgml +your XML before checking it in with something like: + nsgmls -s $JADE_PUB/xml.dcl Bugzilla-Guide.xml - When you validate, please validate the master document (Bugzilla-Guide.sgml) + When you validate, please validate the master document (Bugzilla-Guide.xml) 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 validators do not yet support + The reason these occur is that free sgml/xml validators do not yet support the DTDDECL catalog entries, and I've included DOCTYPE declarations in -entities referenced from Bugzilla-Guide.sgml so these entities can compile +entities referenced from Bugzilla-Guide.xml 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. @@ -39,13 +37,13 @@ documentation. Please address comments and questions to the newsgroup: news://news.mozilla.org/netscape/public/mozilla/webtools . ========== -HOW TO SET UP YOUR OWN SGML EDITING ENVIRONMENT: +HOW TO SET UP YOUR OWN XML EDITING ENVIRONMENT: ========== -Trying to set up an SGML/XML Docbook editing environment the +Trying to set up an XML Docbook editing environment the first time can be a daunting task. I use Linux-Mandrake, in part, because it has a fully-functional -SGML/XML Docbook editing environment included as part of the +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. @@ -62,68 +60,96 @@ rpms: openjade jadetex -docbook-dtd41-sgml +docbook-dtds docbook-style-dsssl -docbook-dtd31-sgml docbook-style-dsssl-doc +docbook-utils xemacs psgml sgml-tools sgml-common -Set up environment: -in your .bashrc add this line (after installing above RPMS): -export SGML_CATALOG_FILES=/etc/sgml/catalog +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. -Download "ldp.dsl" from the Resources page on linuxdoc.org. This is the +Download "ldp.dsl" from the Resources page on tldp.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: - ...and... - Note the difference is the top one points to the HTML docbook stylesheet, and the next one points to the PRINT docbook stylesheet. - You know, this sure looks awful involved. Anyway, once you have this in +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 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 - 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. + 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. ========== NOTES: ========== Here are the commands I use to maintain this documentation. - 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". + You MUST have DocBook 4.1.2 set up correctly in order for this to work. + 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 \ -../sgml/Bugzilla-Guide.sgml +$JADE_PUB/xml.dcl ../xml/Bugzilla-Guide.xml 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 \ -../sgml/Bugzilla-Guide.sgml >Bugzilla-Guide.html +$JADE_PUB/xml.dcl ../xml/Bugzilla-Guide.xml >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" - barnboy@trilobyte.net + mbarnson@sisna.com + + with major edits by Dave Miller based on + experience setting this up on the Landfill test server. diff --git a/docs/en/xml/Bugzilla-Guide.xml b/docs/en/xml/Bugzilla-Guide.xml index a9fcf097a..fd7353e8d 100644 --- a/docs/en/xml/Bugzilla-Guide.xml +++ b/docs/en/xml/Bugzilla-Guide.xml @@ -1,23 +1,23 @@ - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + ] > --> About This Guide @@ -7,14 +7,14 @@
@@ -79,29 +74,27 @@
New Versions - This is the &bzg-ver; version of The Bugzilla Guide. It is so named - to match the current version of Bugzilla. If you are + This is the &bz-ver; version of The Bugzilla Guide. It is so named + to match the current version of Bugzilla. + + If you are reading this from any source other than those below, please check one of these mirrors to make sure you are reading an up-to-date version of the Guide. - This document can be found in the following places: + The newest version of this guide can always be found at bugzilla.org; including + documentation for past releases and the current development version. - - - - bugzilla.org - - - - - The Linux - Documentation Project - - - + The documentation for the most recent stable release of Bugzilla can also + be found at + The Linux Documentation Project. The latest version of this document can always be checked out via CVS. @@ -125,43 +118,87 @@ numerous e-mail and IRC support sessions, and overall excellent contribution to the Bugzilla community: - - Matthew P. Barnson - for the Herculaean task of pulling together the Bugzilla Guide and - shepherding it to 2.14. - - - Terry Weissman - for initially writing Bugzilla and creating the - README upon which the UNIX installation documentation is largely based. - - - Tara Hernandez - for keeping Bugzilla development going - strong after Terry left mozilla.org - - - Dave Lawrence - for providing insight into the key differences between Red Hat's - customized Bugzilla, and being largely responsible for the "Red - Hat Bugzilla" appendix - - - Dawn Endico for - being a hacker extraordinaire and putting up with my incessant - questions and arguments on irc.mozilla.org in #mozwebtools - + + + + + Matthew P. Barnson mbarnson@sisna.com + + for the Herculaean task of pulling together the Bugzilla Guide + and shepherding it to 2.14. + + + + + + Terry Weissman terry@mozilla.org + + for initially writing Bugzilla and creating the README upon + which the UNIX installation documentation is largely based. + + + + + + Tara Hernandez tara@tequilarists.org + + for keeping Bugzilla development going strong after Terry left + mozilla.org and for running landfill. + + + + + + Dave Lawrence dkl@redhat.com + + for providing insight into the key differences between Red + Hat's customized Bugzilla, and being largely responsible for + . + + + + + + Dawn Endico endico@mozilla.org + + for being a hacker extraordinaire and putting up with Matthew's + incessant questions and arguments on irc.mozilla.org in #mozwebtools + + + + + + Jacob Steenhagen jake@bugzilla.org + + for taking over documentation during the 2.17 development + period. + + + + + + Last but not least, all the members of the - netscape.public.mozilla.webtools newsgroup. Without your discussions, insight, suggestions, and patches, this could never have happened. + + newsgroup. Without your discussions, insight, suggestions, and patches, + this could never have happened. Thanks also go to the following people for significant contributions - to this documentation (in no particular order): - - - Zach Liption, Andrew Pearson, Spencer Smith, Eric Hanson, Kevin Brannen, - Ron Teitelbaum, Jacob Steenhagen, Joe Robins, Gervase Markham. + to this documentation (in alphabetical order): + + Andrew Pearson + Ben FrantzDale + Eric Hanson + Gervase Markham + Joe Robins + Kevin Brannen + Ron Teitelbaum + Spencer Smith + Zach Liption + + .
@@ -184,7 +221,7 @@ sgml-local-ecat-files:nil sgml-minimize-attributes:nil sgml-namecase-general:t sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter") +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") sgml-shorttag:t sgml-tag-region-if-active:t End: --> diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml index f04e2b5ce..afe50c789 100644 --- a/docs/en/xml/administration.xml +++ b/docs/en/xml/administration.xml @@ -1632,7 +1632,7 @@ sgml-local-ecat-files:nil sgml-minimize-attributes:nil sgml-namecase-general:t sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter") +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") sgml-shorttag:t sgml-tag-region-if-active:t End: diff --git a/docs/en/xml/conventions.xml b/docs/en/xml/conventions.xml index 5e761d9f4..7e9eb5b04 100644 --- a/docs/en/xml/conventions.xml +++ b/docs/en/xml/conventions.xml @@ -171,7 +171,7 @@ sgml-local-ecat-files:nil sgml-minimize-attributes:nil sgml-namecase-general:t sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter") +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") sgml-shorttag:t sgml-tag-region-if-active:t End: diff --git a/docs/en/xml/gfdl.xml b/docs/en/xml/gfdl.xml index 047646411..ae19501d2 100644 --- a/docs/en/xml/gfdl.xml +++ b/docs/en/xml/gfdl.xml @@ -1,5 +1,5 @@ -
+ GNU Free Documentation License @@ -423,7 +423,7 @@ software license, such as the GNU General Public License, to permit their use in free software.
-
+ + diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml index b9fee2cc8..89dfc224c 100644 --- a/docs/en/xml/installation.xml +++ b/docs/en/xml/installation.xml @@ -1165,7 +1165,7 @@ my $webservergid = '8' look GD. This should go through the motions of downloading the latest version of the GD module, then it will open a shell and drop you into the build - directory. Apply this patch + directory. Apply this patch to the Makefile.PL file (save the patch into a file and use the command patch < patchfile.) @@ -1561,7 +1561,7 @@ at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233. Numerous people have reported that upgrading to version 5.6.1 or higher solved the problem for them. A less involved fix is to apply the patch in . The patch is also - available as a patch file. + available as a patch file.
@@ -1607,7 +1607,7 @@ sgml-local-ecat-files:nil sgml-minimize-attributes:nil sgml-namecase-general:t sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter") +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") sgml-shorttag:t sgml-tag-region-if-active:t End: diff --git a/docs/en/xml/integration.xml b/docs/en/xml/integration.xml index 1b0489fd9..514064d26 100644 --- a/docs/en/xml/integration.xml +++ b/docs/en/xml/integration.xml @@ -93,7 +93,7 @@ sgml-local-ecat-files:nil sgml-minimize-attributes:nil sgml-namecase-general:t sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter") +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") sgml-shorttag:t sgml-tag-region-if-active:t End: diff --git a/docs/en/xml/introduction.xml b/docs/en/xml/introduction.xml index 3968702c6..8b09fe2b5 100644 --- a/docs/en/xml/introduction.xml +++ b/docs/en/xml/introduction.xml @@ -1,39 +1,25 @@ Introduction -
+
What is Bugzilla? Bugzilla is a bug- or issue-tracking system. Bug-tracking systems allow individual or groups of developers effectively to keep track - of outstanding problems with their products. + of outstanding problems with their product. + Bugzilla was originally + written by Terry Weissman in a programming language called TCL, to + replace a rudimentary bug-tracking database used internally by Netscape + Communications. Terry later ported Bugzilla to Perl from TCL, and in Perl + it remains to this day. Most commercial defect-tracking software vendors + at the time charged enormous licensing fees, and Bugzilla quickly became + a favorite of the open-source crowd (with its genesis in the open-source + browser project, Mozilla). It is now the de-facto standard + defect-tracking system against which all others are measured. - - Do we need more here? - -
- -
- Why use a bug-tracking system? - - Those who do not use a bug-tracking system tend to rely on - shared lists, email, spreadsheets and/or Post-It notes to monitor the - status of defects. This procedure - is usually error-prone and tends to cause those bugs judged least - significant by developers to be dropped or ignored. - - Integrated defect-tracking systems make sure that nothing gets - swept under the carpet; they provide a method of creating, storing, - arranging and processing defect reports and enhancement requests. - -
- -
- Why use Bugzilla? - Bugzilla is the leading open-source/free software bug tracking - system. It boasts many advanced features, including: + Bugzilla boasts many advanced features. These include: Powerful searching @@ -68,12 +54,12 @@ - Completely customizable and/or localizable web user - interface + Web, XML, email and console interfaces - Additional XML, email and console interfaces + Completely customisable and/or localisable web user + interface @@ -85,7 +71,34 @@ - +
+ +
+ Why Should We Use Bugzilla? + + For many years, defect-tracking software has remained principally + the domain of large software development houses. Even then, most shops + never bothered with bug-tracking software, and instead simply relied on + shared lists and email to monitor the status of defects. This procedure + is error-prone and tends to cause those bugs judged least significant by + developers to be dropped or ignored. + + These days, many companies are finding that integrated + defect-tracking systems reduce downtime, increase productivity, and raise + customer satisfaction with their systems. Along with full disclosure, an + open bug-tracker allows manufacturers to keep in touch with their clients + and resellers, to communicate about problems effectively throughout the + data management chain. Many corporations have also discovered that + defect-tracking helps reduce costs by providing IT support + accountability, telephone support knowledge bases, and a common, + well-understood system for accounting for unusual system or software + issues. + + But why should + you + + use Bugzilla? + Bugzilla is very adaptable to various situations. Known uses currently include IT support queues, Systems Administration deployment management, chip design and development problem tracking (both @@ -95,7 +108,22 @@ CVS, Bonsai, or Perforce SCM, Bugzilla - provides a powerful, easy-to-use configuration management solution. + provides a powerful, easy-to-use solution to configuration management and + replication problems. + + Bugzilla can dramatically increase the productivity and + accountability of individual employees by providing a documented workflow + and positive feedback for good performance. How many times do you wake up + in the morning, remembering that you were supposed to do + something + today, but you just can't quite remember? Put it in Bugzilla, and you + have a record of it from which you can extrapolate milestones, predict + product versions for integration, and follow the discussion trail + that led to critical decisions. + + Ultimately, Bugzilla puts the power in your hands to improve your + value to your employer or business while providing a usable framework for + your natural attention to detail and knowledge store to flourish.
diff --git a/docs/en/xml/patches.xml b/docs/en/xml/patches.xml index 43f816758..84d83d333 100644 --- a/docs/en/xml/patches.xml +++ b/docs/en/xml/patches.xml @@ -1,4 +1,4 @@ - + Useful Patches and Utilities for Bugzilla @@ -105,7 +105,7 @@ sgml-local-ecat-files:nil sgml-minimize-attributes:nil sgml-namecase-general:t sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter") +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") sgml-shorttag:t sgml-tag-region-if-active:t End: diff --git a/docs/en/xml/requiredsoftware.xml b/docs/en/xml/requiredsoftware.xml index e36b6184a..95988ec83 100644 --- a/docs/en/xml/requiredsoftware.xml +++ b/docs/en/xml/requiredsoftware.xml @@ -1,69 +1,70 @@ - Software Download Links - - All of these sites are current as of April, 2001. Hopefully - they'll stay current for a while. - - - Apache Web Server: http://www.apache.org - Optional web server for Bugzilla, but recommended because of broad user base and support. - - - Bugzilla: - http://www.mozilla.org/projects/bugzilla/ - - - MySQL: http://www.mysql.com/ + + All of these sites are current as of April, 2001. Hopefully they'll + stay current for a while. + + Apache Web Server: + http://www.apache.org + + Optional web server for Bugzilla, but recommended because of broad user + base and support. + + Bugzilla: + + http://www.bugzilla.org/ - - Perl: http://www.perl.org/ + + MySQL: + http://www.mysql.com/ - - CPAN: http://www.cpan.org/ + + Perl: + http://www.perl.org/ - - DBI Perl module: - - ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/DBI/ + + CPAN: + http://www.cpan.org/ - - Data::Dumper module: - - ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/Data/ + + DBI Perl module: + + http://www.cpan.org/modules/by-module/DBI/ - - MySQL related Perl modules: - - ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/Mysql/ + + Data::Dumper module: + + http://www.cpan.org/modules/by-module/Data/ - - TimeDate Perl module collection: - - ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/Date/ + + MySQL related Perl modules: + + http://www.cpan.org/modules/by-module/Mysql/ - - GD Perl module: - - ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/GD/ - Alternately, you should be able to find the latest version of - GD at http://www.boutell.com/gd/ + + TimeDate Perl module collection: + + http://www.cpan.org/modules/by-module/Date/ - - Chart::Base module: - - ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/Chart/ + + GD Perl module: + + http://www.cpan.org/modules/by-module/GD/ + + Alternately, you should be able to find the latest version of GD at + http://www.boutell.com/gd/ - - LinuxDoc Software: - http://www.linuxdoc.org/ - (for documentation maintenance) + + Chart::Base module: + + http://www.cpan.org/modules/by-module/Chart/ + (But remember, Bundle::Bugzilla will install all the modules for you.) + - + diff --git a/docs/en/xml/using.xml b/docs/en/xml/using.xml index a3986c27d..b5dab9d0a 100644 --- a/docs/en/xml/using.xml +++ b/docs/en/xml/using.xml @@ -572,7 +572,7 @@ sgml-local-ecat-files:nil sgml-minimize-attributes:nil sgml-namecase-general:t sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter") +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") sgml-shorttag:t sgml-tag-region-if-active:t End: -- cgit v1.2.3-24-g4f1b