Skip to content

bugzilla
bugzilla
Commit 650a2f9f authored by Frédéric Buclin's avatar Frédéric Buclin
Browse files
Options

Bug 423496: Compile the documentation with xmlto + dblatex instead of openjade

r=glob a=LpSolit
parent 5173b6cb
Hide whitespace changes
Inline Side-by-side
Showing with 338 additions and 468 deletions
docs/bugzilla.ent.tmpl 0 → 100644
View file @ 650a2f9f
<!ENTITY bz-ver "4.3">
<!ENTITY bz-date "2011-08-04">
<!ENTITY current-year "2011">
<!ENTITY min-perl-ver "5.8.1">
<!ENTITY landfillbase "http://landfill.bugzilla.org/bugzilla-tip/">
<!ENTITY bzg-bugs "http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla;component=Documentation">
docs/en/README.docs
View file @ 650a2f9f
......@@ -4,152 +4,39 @@ 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)
pdf/ # The compiled PDF 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
The documentation is written in DocBook 4.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.
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
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
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/xml 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
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.
If you need to edit the documentation, 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 <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 by running makedocs.pl.
Thanks for taking the time to read these notes and consulting the
documentation. Please address comments and questions to the newsgroup:
news://news.mozilla.org/netscape/public/mozilla/webtools .
news://news.mozilla.org/mozilla.support.bugzilla.
==========
HOW TO SET UP YOUR OWN XML EDITING ENVIRONMENT:
==========
Trying to set up an XML Docbook editing environment the
first time can be a daunting task.
I use Mandriva Linux, in part, because it has a fully-functional
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.
The following text is taken nearly verbatim from
http://bugzilla.mozilla.org/show_bug.cgi?id=95970, where I gave
these instructions to someone who wanted the greater manageability
maintaining a document in Docbook brings:
This is just off the top of my head, but here goes. Note some of these may
NOT be necessary, but I don't think they hurt anything by being installed.
rpms:
openjade
jadetex
docbook-dtds
docbook-style-dsssl
docbook-style-dsssl-doc
docbook-utils
xemacs
psgml
sgml-tools
sgml-common
If you're getting these from Red Hat, 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 Red Hat Linux 8.0 and 9
and known to work.
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:
<!ENTITY docbook.dsl SYSTEM "../dsssl-stylesheets/html/docbook.dsl" CDATA
dsssl>
...and...
<!ENTITY docbook.dsl SYSTEM "../dsssl-stylesheets/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 Red Hat Linux 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
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.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 \
$JADE_PUB/xml.dcl ../xml/Bugzilla-Guide.xml
All you need to compile the documentation are the xmlto and dblatex
scripts. All major Linux distributions have these packages and so
it's very easy to install them. If these packages are correctly configured,
all required dependencies such as xsltproc and pdftex will be installed
at the same time, and so you don't have to worry about them.
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
Once these applications are installed, all you need to do to compile
the documentation is to run either:
To create TXT documentation as a single big TXT file:
bash$ cd txt
bash$ lynx -dump -nolist ../html/Bugzilla-Guide.html >Bugzilla-Guide.txt
makedocs.pl
to compile the documentation in HTML and text formats only, or:
Sincerely,
Matthew P. Barnson
The Bugzilla "Doc Knight"
mbarnson@sisna.com
makedocs.pl --with-pdf
with major edits by Dave Miller <justdave@syndicomm.com> based on
experience setting this up on the Landfill test server.
to also compile the documentation in PDF format.
docs/en/xml/Bugzilla-Guide.xml
View file @ 650a2f9f
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" [
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % myents SYSTEM "bugzilla.ent">
%myents;
<!-- Include macros -->
<!ENTITY about SYSTEM "about.xml">
<!ENTITY conventions SYSTEM "conventions.xml">
<!ENTITY doc-index SYSTEM "index.xml">
<!ENTITY gfdl SYSTEM "gfdl.xml">
<!ENTITY glossary SYSTEM "glossary.xml">
<!ENTITY installation SYSTEM "installation.xml">
<!ENTITY administration SYSTEM "administration.xml">
<!ENTITY security SYSTEM "security.xml">
<!ENTITY using SYSTEM "using.xml">
<!ENTITY index SYSTEM "index.xml">
<!ENTITY customization SYSTEM "customization.xml">
<!ENTITY troubleshooting SYSTEM "troubleshooting.xml">
<!ENTITY patches SYSTEM "patches.xml">
<!ENTITY modules SYSTEM "modules.xml">
<!-- Things to change for a stable release:
* bz-ver to current stable
* bz-nexver to next stable
* bz-date to the release date
* landfillbase to the branch install
* Remove the BZ-DEVEL comments
- COMPILE DOCS AND CHECKIN -
Also, tag and tarball before completing
* bz-ver to devel version
For a devel release, simple bump bz-ver and bz-date
-->
<!ENTITY bz-ver "4.3">
<!ENTITY bz-nextver "5.0">
<!ENTITY bz-date "2011-08-04">
<!ENTITY current-year "2011">
<!ENTITY landfillbase "http://landfill.bugzilla.org/bugzilla-tip/">
<!ENTITY bz "http://www.bugzilla.org/">
<!ENTITY bzg-bugs "<ulink url='https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&amp;component=Documentation'>Bugzilla Documentation</ulink>">
<!ENTITY mysql "http://www.mysql.com/">
<!ENTITY min-perl-ver "5.8.1">
]>
<!-- Coding standards for this document
* Other than the GFDL, please use the "section" tag instead of "sect1",
......@@ -114,41 +72,37 @@
</bookinfo>
<!-- About This Guide -->
&about;
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="about.xml"/>
<!-- Installing Bugzilla -->
&installation;
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="installation.xml"/>
<!-- Administering Bugzilla -->
&administration;
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="administration.xml"/>
<!-- Securing Bugzilla -->
&security;
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="security.xml"/>
<!-- Using Bugzilla -->
&using;
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="using.xml"/>
<!-- Customizing Bugzilla -->
&customization;
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="customization.xml"/>
<!-- Appendix: Troubleshooting -->
&troubleshooting;
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="troubleshooting.xml"/>
<!-- Appendix: Custom Patches -->
&patches;
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="patches.xml"/>
<!-- Appendix: Manually Installing Perl Modules -->
&modules;
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules.xml"/>
<!-- Appendix: GNU Free Documentation License -->
&gfdl;
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="gfdl.xml"/>
<!-- Glossary -->
&glossary;
<!-- Index -->
&index;
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="glossary.xml"/>
</book>
......
docs/en/xml/about.xml
View file @ 650a2f9f
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
<!ENTITY conventions SYSTEM "conventions.xml"> ] > -->
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % myents SYSTEM "bugzilla.ent">
%myents;
]>
<chapter id="about">
<title>About This Guide</title>
......@@ -190,8 +194,8 @@
</section>
<!-- conventions used here (didn't want to give it a chapter of its own) -->
&conventions;
</chapter>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="conventions.xml" />
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
......
docs/en/xml/administration.xml
View file @ 650a2f9f
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % myents SYSTEM "bugzilla.ent">
%myents;
]>
<chapter id="administration">
<title>Administering Bugzilla</title>
......@@ -24,10 +30,6 @@
deploying a new Bugzilla installation.
</para>
<indexterm>
<primary>checklist</primary>
</indexterm>
<variablelist>
<varlistentry>
......
docs/en/xml/conventions.xml
View file @ 650a2f9f
<!-- <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
<?xml version="1.0"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % myents SYSTEM "bugzilla.ent">
%myents;
]>
<section id="conventions">
<title>Document Conventions</title>
<indexterm zone="conventions">
<primary>conventions</primary>
</indexterm>
<para>This document uses the following conventions:</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Descriptions</entry>
<entry>Appearance</entry>
</row>
</thead>
<tbody>
<row>
<entry>Caution</entry>
<entry>
<caution>
<para>Don't run with scissors!</para>
</caution>
</entry>
</row>
<row>
<entry>Hint or Tip</entry>
<entry>
<tip>
<para>For best results... </para>
</tip>
</entry>
</row>
<row>
<entry>Note</entry>
<entry>
<note>
<para>Dear John...</para>
</note>
</entry>
</row>
<row>
<entry>Warning</entry>
<entry>
<warning>
<para>Read this or the cat gets it.</para>
</warning>
</entry>
</row>
<row>
<entry>File or directory name</entry>
<caution>
<para>This is a caution. Make sure to read this to not be in trouble!</para>
</caution>
<entry>
<filename>filename</filename>
</entry>
</row>
<tip>
<para>This is a hint or tip, especially about some configuration tweaks.</para>
</tip>
<row>
<entry>Command to be typed</entry>
<note>
<para>This is just a note, for your information.</para>
</note>
<entry>
<command>command</command>
</entry>
</row>
<warning>
<para>This is a warning, something you should take care of.</para>
</warning>
<row>
<entry>Application name</entry>
<entry>
<application>application</application>
</entry>
</row>
<row>
<entry>
Normal user's prompt under bash shell</entry>
<entry>bash$</entry>
</row>
<row>
<entry>
Root user's prompt under bash shell</entry>
<entry>bash#</entry>
</row>
<row>
<entry>
Normal user's prompt under tcsh shell</entry>
<entry>tcsh$</entry>
</row>
<row>
<entry>Environment variables</entry>
<para>
A filename or a path to a filename is displayed like this:
<filename>/path/to/filename.ext</filename>
</para>
<entry>
<envar>VARIABLE</envar>
</entry>
</row>
<para>
A command to type in the shell is displayed like this:
<command>command --arguments</command>
</para>
<row>
<entry>Term found in the glossary</entry>
<para>bash$ represents a normal user's prompt under bash shell</para>
<entry>
<glossterm linkend="gloss-bugzilla">Bugzilla</glossterm>
</entry>
</row>
<para>bash# represents a root user's prompt under bash shell</para>
<row>
<entry>Code example</entry>
<para>
A word which is in the glossary will appear like this:
<glossterm linkend="gloss-bugzilla">Bugzilla</glossterm>
</para>
<entry>
<programlisting><sgmltag class="starttag">para</sgmltag>
Beginning and end of paragraph
<sgmltag class="endtag">para</sgmltag></programlisting>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
A sample of code is illustrated like this:
<programlisting>
First Line of Code
Second Line of Code
...
</programlisting>
</para>
<para>
This documentation is maintained in DocBook 4.1.2 XML format.
<para>
This documentation is maintained in DocBook 4.2 XML format.
Changes are best submitted as plain text or XML diffs, attached
to a bug filed in the &bzg-bugs; component.
to a bug filed in the <ulink url="&bzg-bugs;">Bugzilla Documentation</ulink>
component.
</para>
</section>
<!-- Keep this comment at the end of the file
......
docs/en/xml/customization.xml
View file @ 650a2f9f
<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % myents SYSTEM "bugzilla.ent">
%myents;
]>
<chapter id="customization">
<title>Customizing Bugzilla</title>
......@@ -14,7 +20,7 @@
</para>
<para>
See the <ulink url="api/Bugzilla/Extension.html">Bugzilla Extension
See the <ulink url="../html/api/Bugzilla/Extension.html">Bugzilla Extension
documentation</ulink> for information on how to write an Extension.
</para>
</section>
......@@ -391,7 +397,7 @@
<para>
An example of this is the mozilla.org
<ulink url="http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl&amp;format=guided">guided
<ulink url="http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl;format=guided">guided
bug submission form</ulink>. The code for this comes with the Bugzilla
distribution as an example for you to copy. It can be found in the
files
......
docs/en/xml/gfdl.xml
View file @ 650a2f9f
<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % myents SYSTEM "bugzilla.ent">
%myents;
]>
<appendix id="gfdl">
<title>GNU Free Documentation License</title>
......
docs/en/xml/glossary.xml
View file @ 650a2f9f
<!-- <!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook V4.1//EN" > -->
<?xml version="1.0"?>
<!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % myents SYSTEM "bugzilla.ent">
%myents;
]>
<glossary id="glossary">
<glossdiv>
<title>0-9, high ascii</title>
......@@ -42,7 +48,7 @@
<title>Useful Directives when configuring Bugzilla</title>
<varlistentry>
<term><computeroutput><ulink url="http://httpd.apache.org/docs-2.0/mod/core.html#addhandler">AddHandler</ulink></computeroutput></term>
<term><computeroutput><ulink url="http://httpd.apache.org/docs/2.0/mod/mod_mime.html#addhandler">AddHandler</ulink></computeroutput></term>
<listitem>
<para>Tell Apache that it's OK to run CGI scripts.</para>
</listitem>
......
docs/en/xml/installation.xml
View file @ 650a2f9f
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % myents SYSTEM "bugzilla.ent">
%myents;
]>
<chapter id="installing-bugzilla">
<title>Installing Bugzilla</title>
......@@ -169,16 +175,17 @@
<para>Installed Version Test: view the default welcome page at
http://&lt;your-machine&gt;/</para>
<para>You have freedom of choice here, pretty much any web server that
is capable of running <glossterm linkend="gloss-cgi">CGI</glossterm>
scripts will work.
However, we strongly recommend using the Apache web server
(either 1.3.x or 2.x), and
the installation instructions usually assume you are
using it. If you have got Bugzilla working using another web server,
please share your experiences with us by filing a bug in &bzg-bugs;.
<para>
You have freedom of choice here, pretty much any web server that
is capable of running <glossterm linkend="gloss-cgi">CGI</glossterm>
scripts will work.
However, we strongly recommend using the Apache web server
(either 1.3.x or 2.x), and the installation instructions usually assume
you are using it. If you have got Bugzilla working using another web server,
please share your experiences with us by filing a bug in
<ulink url="&bzg-bugs;">Bugzilla Documentation</ulink>.
</para>
<para>
If you don't have Apache and your OS doesn't provide official packages,
visit <ulink url="http://httpd.apache.org/"/>.
......@@ -732,9 +739,9 @@ max_allowed_packet=4M
This can be done by modifying the <filename>/etc/my.cnf</filename>
according to the example below:</para>
<screen> [mysqld]
# Allow small words in full-text indexes
ft_min_word_len=2</screen>
<screen>[mysqld]
# Allow small words in full-text indexes
ft_min_word_len=2</screen>
<para>Rebuilding the indexes can be done based on documentation found at
<ulink url="http://www.mysql.com/doc/en/Fulltext_Fine-tuning.html"/>.
......@@ -770,11 +777,11 @@ max_allowed_packet=4M
</para>
<screen>
<prompt>mysql&gt;</prompt> GRANT SELECT, INSERT,
UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES,
CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.*
TO bugs@localhost IDENTIFIED BY '<replaceable>$db_pass</replaceable>';
<prompt>mysql&gt;</prompt> FLUSH PRIVILEGES;
<prompt>mysql&gt;</prompt> GRANT SELECT, INSERT,
UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES,
CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.*
TO bugs@localhost IDENTIFIED BY '<replaceable>$db_pass</replaceable>';
<prompt>mysql&gt;</prompt> FLUSH PRIVILEGES;
</screen>
</section>
......@@ -796,8 +803,8 @@ max_allowed_packet=4M
</para>
<screen>
<prompt>mysql&gt;</prompt> use <replaceable>$bugs_db</replaceable>
<prompt>mysql&gt;</prompt> ALTER TABLE attachments
<prompt>mysql&gt;</prompt> use <replaceable>$bugs_db</replaceable>
<prompt>mysql&gt;</prompt> ALTER TABLE attachments
AVG_ROW_LENGTH=1000000, MAX_ROWS=20000;
</screen>
......@@ -832,11 +839,11 @@ max_allowed_packet=4M
<para>On most systems, to create the user in PostgreSQL, you will need to
login as the root user, and then</para>
<screen> <prompt>bash#</prompt> su - postgres</screen>
<screen><prompt>bash#</prompt> su - postgres</screen>
<para>As the postgres user, you then need to create a new user: </para>
<screen> <prompt>bash$</prompt> createuser -U postgres -dRSP bugs</screen>
<screen><prompt>bash$</prompt> createuser -U postgres -dRSP bugs</screen>
<para>When asked for a password, provide the password which will be set as
<replaceable>$db_pass</replaceable> in <filename>localconfig</filename>.
......@@ -880,9 +887,9 @@ max_allowed_packet=4M
</para>
<programlisting>
CREATE TABLESPACE bugs
DATAFILE '<replaceable>$path_to_datafile</replaceable>' SIZE 500M
AUTOEXTEND ON NEXT 30M MAXSIZE UNLIMITED
CREATE TABLESPACE bugs
DATAFILE '<replaceable>$path_to_datafile</replaceable>' SIZE 500M
AUTOEXTEND ON NEXT 30M MAXSIZE UNLIMITED
</programlisting>
<para>
......@@ -907,17 +914,17 @@ max_allowed_packet=4M
</para>
<programlisting>
CREATE USER bugs
IDENTIFIED BY "<replaceable>$db_pass</replaceable>"
DEFAULT TABLESPACE bugs
TEMPORARY TABLESPACE TEMP
PROFILE DEFAULT;
-- GRANT/REVOKE ROLE PRIVILEGES
GRANT CONNECT TO bugs;
GRANT RESOURCE TO bugs;
-- GRANT/REVOKE SYSTEM PRIVILEGES
GRANT UNLIMITED TABLESPACE TO bugs;
GRANT EXECUTE ON CTXSYS.CTX_DDL TO bugs;
CREATE USER bugs
IDENTIFIED BY "<replaceable>$db_pass</replaceable>"
DEFAULT TABLESPACE bugs
TEMPORARY TABLESPACE TEMP
PROFILE DEFAULT;
-- GRANT/REVOKE ROLE PRIVILEGES
GRANT CONNECT TO bugs;
GRANT RESOURCE TO bugs;
-- GRANT/REVOKE SYSTEM PRIVILEGES
GRANT UNLIMITED TABLESPACE TO bugs;
GRANT EXECUTE ON CTXSYS.CTX_DDL TO bugs;
</programlisting>
</section>
......@@ -930,8 +937,8 @@ max_allowed_packet=4M
</para>
<programlisting>
SetEnv ORACLE_HOME /u01/app/oracle/product/10.2.0/
SetEnv LD_LIBRARY_PATH /u01/app/oracle/product/10.2.0/lib/
SetEnv ORACLE_HOME /u01/app/oracle/product/10.2.0/
SetEnv LD_LIBRARY_PATH /u01/app/oracle/product/10.2.0/lib/
</programlisting>
<para>
......@@ -1040,12 +1047,12 @@ max_allowed_packet=4M
</para>
<programlisting>
&lt;Directory /var/www/html/bugzilla&gt;
AddHandler cgi-script .cgi
Options +Indexes +ExecCGI
DirectoryIndex index.cgi
AllowOverride Limit FileInfo Indexes
&lt;/Directory&gt;
&lt;Directory /var/www/html/bugzilla&gt;
AddHandler cgi-script .cgi
Options +Indexes +ExecCGI
DirectoryIndex index.cgi
AllowOverride Limit FileInfo Indexes
&lt;/Directory&gt;
</programlisting>
<para>
......@@ -1101,9 +1108,7 @@ max_allowed_packet=4M
(the same one as in the step above):
</para>
<programlisting>
+FollowSymLinks
</programlisting>
<programlisting>+FollowSymLinks</programlisting>
<para>
Without this directive, Apache will not follow symbolic links
......@@ -1142,10 +1147,10 @@ max_allowed_packet=4M
<para>You should also ensure that you have disabled <literal>KeepAlive</literal>
support in your Apache install when utilizing Bugzilla under mod_perl</para>
</warning>
<programlisting>
PerlSwitches -w -T
PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl
PerlSwitches -w -T
PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl
</programlisting>
</step>
......@@ -1521,8 +1526,8 @@ AddType application/rdf+xml .rdf</screen>
and the utilities available to make it easier.
</para>
<para>If you have anything to add or notes for an operating system not
covered, please file a bug in &bzg-bugs;.
<para>If you have anything to add or notes for an operating system not covered,
please file a bug in <ulink url="&bzg-bugs;">Bugzilla Documentation</ulink>.
</para>
<section id="os-win32">
......@@ -1855,13 +1860,11 @@ pid-file=/home/foo/mymysql/the.pid
<para>After your mysqld program is built and any .my.cnf file is
in place, you must initialize the databases (ONCE).</para>
<screen>
<prompt>bash$</prompt>
<command>mysql_install_db</command>
<prompt>bash$</prompt> <command>mysql_install_db</command>
</screen>
<para>Then start the daemon with</para>
<screen>
<prompt>bash$</prompt>
<command>safe_mysql &amp;</command>
<prompt>bash$</prompt> <command>safe_mysql &amp;</command>
</screen>
<para>After you start mysqld the first time, you then connect to
it as "root" and <command>GRANT</command> permissions to other
......@@ -1883,7 +1886,6 @@ pid-file=/home/foo/mymysql/the.pid
</warning>
</section>
</section>
</section>
<section>
......@@ -1897,16 +1899,11 @@ pid-file=/home/foo/mymysql/the.pid
</para>
<screen>
<prompt>bash$</prompt>
<command>wget http://perl.org/CPAN/src/stable.tar.gz</command>
<prompt>bash$</prompt>
<command>tar zvxf stable.tar.gz</command>
<prompt>bash$</prompt>
<command>cd perl-5.8.1</command> (or whatever the version of Perl is called)
<prompt>bash$</prompt>
<command>sh Configure -de -Dprefix=/home/foo/perl</command>
<prompt>bash$</prompt>
<command>make &amp;&amp; make test &amp;&amp; make install</command>
<prompt>bash$</prompt> <command>wget http://perl.org/CPAN/src/stable.tar.gz</command>
<prompt>bash$</prompt> <command>tar zvxf stable.tar.gz</command>
<prompt>bash$</prompt> <command>cd perl-&min-perl-ver;</command>
<prompt>bash$</prompt> <command>sh Configure -de -Dprefix=/home/foo/perl</command>
<prompt>bash$</prompt> <command>make &amp;&amp; make test &amp;&amp; make install</command>
</screen>
<para>
......@@ -1923,7 +1920,7 @@ pid-file=/home/foo/mymysql/the.pid
Installing the Perl modules as a non-root user is accomplished by
running the <filename>install-module.pl</filename>
script. For more details on this script, see
<ulink url="api/install-module.html"><filename>install-module.pl</filename>
<ulink url="../html/api/install-module.html"><filename>install-module.pl</filename>
documentation</ulink>
</para>
</section>
......@@ -2000,10 +1997,12 @@ pid-file=/home/foo/mymysql/the.pid
shell commands after running <command>./checksetup.pl</command>,
every time you run it (or modify <filename>checksetup.pl</filename>
to do them for you via the system() command).
<programlisting> for i in docs graphs images js skins; do find $i -type d -exec chmod o+rx {} \; ; done
for i in jpg gif css js png html rdf xul; do find . -name \*.$i -exec chmod o+r {} \; ; done
find . -name .htaccess -exec chmod o+r {} \;
chmod o+x . data data/webdot</programlisting>
<programlisting>
for i in docs graphs images js skins; do find $i -type d -exec chmod o+rx {} \; ; done
for i in jpg gif css js png html rdf xul; do find . -name \*.$i -exec chmod o+r {} \; ; done
find . -name .htaccess -exec chmod o+r {} \;
chmod o+x . data data/webdot
</programlisting>
Pay particular attention to the number of semicolons and dots.
They are all important. A future version of Bugzilla will
hopefully be able to do this for you out of the box.</para>
......
docs/en/xml/modules.xml
View file @ 650a2f9f
<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % myents SYSTEM "bugzilla.ent">
%myents;
]>
<appendix id="install-perlmodules-manual">
<title>Manual Installation of Perl Modules</title>
......
docs/en/xml/patches.xml
View file @ 650a2f9f
<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % myents SYSTEM "bugzilla.ent">
%myents;
]>
<appendix id="patches" xreflabel="Useful Patches and Utilities for Bugzilla">
<title>Contrib</title>
......
docs/en/xml/security.xml
View file @ 650a2f9f
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % myents SYSTEM "bugzilla.ent">
%myents;
]>
<chapter id="security">
<title>Bugzilla Security</title>
......
docs/en/xml/troubleshooting.xml
View file @ 650a2f9f
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % myents SYSTEM "bugzilla.ent">
%myents;
]>
<appendix id="troubleshooting">
<title>Troubleshooting</title>
......@@ -173,17 +178,17 @@ TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-t
<blockquote>
<literallayout>
urlbase is <ulink url="http://bugzilla.mozilla.org/"/>
cookiepath is /
urlbase is http://bugzilla.mozilla.org/
cookiepath is /
urlbase is <ulink url="http://tools.mysite.tld/bugzilla/"/>
but you have http://tools.mysite.tld/someotherapp/ which shares
authentication with your Bugzilla
cookiepath is /
urlbase is http://tools.mysite.tld/bugzilla/
but you have http://tools.mysite.tld/someotherapp/ which shares
authentication with your Bugzilla
cookiepath is /
</literallayout>
</blockquote>
</example>
<para>On the other hand, if you have more than one Bugzilla running on the
server (some people do - we do on landfill) then you need to have the
cookiepath restricted enough so that the different Bugzillas don't
......@@ -195,11 +200,11 @@ TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-t
<title>Examples of urlbase/cookiepath pairs to restrict the login cookie</title>
<blockquote>
<literallayout>
urlbase is <ulink url="http://landfill.bugzilla.org/bugzilla-tip/"/>
cookiepath is /bugzilla-tip/
urlbase is http://landfill.bugzilla.org/bugzilla-tip/
cookiepath is /bugzilla-tip/
urlbase is <ulink url="http://landfill.bugzilla.org/bugzilla-2.16-branch/"/>
cookiepath is /bugzilla-2.16-branch/
urlbase is http://landfill.bugzilla.org/bugzilla-4.0-branch/
cookiepath is /bugzilla-4.0-branch/
</literallayout>
</blockquote>
</example>
......
docs/en/xml/using.xml
View file @ 650a2f9f
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % myents SYSTEM "bugzilla.ent">
%myents;
]>
<chapter id="using">
<title>Using Bugzilla</title>
......@@ -377,7 +382,7 @@
<title>Lifecycle of a Bugzilla Bug</title>
<mediaobject>
<imageobject>
<imagedata fileref="../images/bzLifecycle.png" scale="66" />
<imagedata fileref="../images/bzLifecycle.png"/>
</imageobject>
</mediaobject>
</figure>
......
docs/makedocs.pl
View file @ 650a2f9f
......@@ -59,8 +59,16 @@ use Bugzilla::Constants qw(DB_MODULE BUGZILLA_VERSION);
my $modules = REQUIRED_MODULES;
my $opt_modules = OPTIONAL_MODULES;
my $template;
{
open(TEMPLATE, '<', 'bugzilla.ent.tmpl')
or die('Could not open bugzilla.ent.tmpl: ' . $!);
local $/;
$template = <TEMPLATE>;
close TEMPLATE;
}
open(ENTITIES, '>', 'bugzilla.ent') or die('Could not open bugzilla.ent: ' . $!);
print ENTITIES '<?xml version="1.0"?>' ."\n\n";
print ENTITIES "$template\n";
print ENTITIES '<!-- Module Versions -->' . "\n";
foreach my $module (@$modules, @$opt_modules)
{
......@@ -89,30 +97,6 @@ foreach my $db (keys %$db_modules) {
close(ENTITIES);
###############################################################################
# Environment Variable Checking
###############################################################################
my ($JADE_PUB, $LDP_HOME, $build_docs);
$build_docs = 1;
if (defined $ENV{JADE_PUB} && $ENV{JADE_PUB} ne '') {
$JADE_PUB = $ENV{JADE_PUB};
}
else {
print "To build 'The Bugzilla Guide', you need to set the ";
print "JADE_PUB environment variable first.\n";
$build_docs = 0;
}
if (defined $ENV{LDP_HOME} && $ENV{LDP_HOME} ne '') {
$LDP_HOME = $ENV{LDP_HOME};
}
else {
print "To build 'The Bugzilla Guide', you need to set the ";
print "LDP_HOME environment variable first.\n";
$build_docs = 0;
}
###############################################################################
# Subs
###############################################################################
......@@ -199,30 +183,15 @@ foreach my $lang (@langs) {
}
make_pod() if $pod_simple;
next unless $build_docs;
chdir 'html';
MakeDocs('separate HTML', "jade -t sgml -i html -d $LDP_HOME/ldp.dsl\#html " .
"$JADE_PUB/xml.dcl ../xml/Bugzilla-Guide.xml");
MakeDocs('big HTML', "jade -V nochunks -t sgml -i html -d " .
"$LDP_HOME/ldp.dsl\#html $JADE_PUB/xml.dcl " .
"../xml/Bugzilla-Guide.xml > Bugzilla-Guide.html");
MakeDocs('big text', "lynx -dump -justify=off -nolist Bugzilla-Guide.html " .
"> ../txt/Bugzilla-Guide.txt");
MakeDocs('separate HTML', 'xmlto -m ../xsl/chunks.xsl -o html html xml/Bugzilla-Guide.xml');
MakeDocs('big HTML', 'xmlto -m ../xsl/nochunks.xsl -o html html-nochunks xml/Bugzilla-Guide.xml');
MakeDocs('big text', 'lynx -dump -justify=off -nolist html/Bugzilla-Guide.html > txt/Bugzilla-Guide.txt');
if (! grep($_ eq "--with-pdf", @ARGV)) {
next;
}
MakeDocs('PDF', "jade -t tex -d $LDP_HOME/ldp.dsl\#print $JADE_PUB/xml.dcl " .
'../xml/Bugzilla-Guide.xml');
chdir '../pdf';
MakeDocs(undef, 'mv ../xml/Bugzilla-Guide.tex .');
MakeDocs(undef, 'pdfjadetex Bugzilla-Guide.tex');
MakeDocs(undef, 'pdfjadetex Bugzilla-Guide.tex');
MakeDocs(undef, 'pdfjadetex Bugzilla-Guide.tex');
MakeDocs(undef, 'rm Bugzilla-Guide.tex Bugzilla-Guide.log Bugzilla-Guide.aux Bugzilla-Guide.out');
MakeDocs('PDF', 'dblatex -p ../xsl/pdf.xsl -o pdf/Bugzilla-Guide.pdf xml/Bugzilla-Guide.xml');
}
docs/style.css
View file @ 650a2f9f
......@@ -21,9 +21,7 @@ body {
background: white;
color: #111;
padding: 0 1em;
margin: 0;
font-family: Verdana, Arial, sans-serif;
font-size: small;
}
a:link, a:active { color: #36415c; }
......@@ -72,10 +70,11 @@ pre, code, tt, kbd, samp {
border: 1px solid #ccc;
}
pre.code {
pre.code, pre.programlisting, pre.screen {
margin-left: 10px;
width: 90%;
padding: 10px;
padding: 0.5em;
background: #eed;
border: 1px solid #ccc;
}
/* Special styles for the Contents page */
......
docs/xsl/bugzilla-docs.xsl 0 → 100644
View file @ 650a2f9f
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<!-- Nicer Filenames -->
<xsl:param name="use.id.as.filename" select="1"/>
<!-- Label sections if they aren't automatically labeled -->
<xsl:param name="section.autolabel" select="1"/>
<xsl:param name="section.label.includes.component.label" select="1"/>
<!-- Table of Contents Depth -->
<xsl:param name="toc.section.depth">2</xsl:param>
<xsl:param name="generate.section.toc.level" select="0"/>
<!-- Show titles of next/previous page -->
<xsl:param name="navig.showtitles">1</xsl:param>
<!-- Tidy up the HTML a bit... -->
<xsl:param name="html.cleanup" select="1"/>
<xsl:param name="make.valid.html" select="1"/>
<xsl:param name="html.stylesheet">../../style.css</xsl:param>
<xsl:param name="highlight.source" select="1"/>
<!-- Use Graphics, specify their Path and Extension -->
<xsl:param name="admon.graphics" select="1"/>
<xsl:param name="admon.graphics.path">../images/</xsl:param>
<xsl:param name="admon.graphics.extension">.gif</xsl:param>
<xsl:param name="admon.textlabel" select="0"/>
<xsl:param name="admon.style">margin-left: 1em; margin-right: 1em</xsl:param>
</xsl:stylesheet>
docs/xsl/chunks.xsl 0 → 100644
View file @ 650a2f9f
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<!-- Include default bugzilla XSL -->
<xsl:include href="bugzilla-docs.xsl"/>
<!-- Set Chunk Specific XSL Params -->
<xsl:param name="chunker.output.doctype-public">-//W3C//DTD HTML 4.01 Transitional//EN</xsl:param>
<xsl:param name="chunker.output.doctype-system">http://www.w3.org/TR/html4/loose.dtd</xsl:param>
<xsl:param name="chunk.section.depth" select="1"/>
<xsl:param name="chunk.first.sections" select="1"/>
<xsl:param name="chunker.output.encoding" select="UTF-8"/>
<xsl:param name="chunk.quietly" select="1"/>
</xsl:stylesheet>
docs/xsl/nochunks.xsl 0 → 100644
View file @ 650a2f9f
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="html" encoding="UTF-8" indent="no"/>
<!-- Include default bugzilla XSL -->
<xsl:include href="bugzilla-docs.xsl"/>
<!-- No other params necessary -->
</xsl:stylesheet>
docs/xsl/pdf.xsl 0 → 100644
View file @ 650a2f9f
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
version="1.0">
<!-- Some layout parameters -->
<xsl:param name="generate.index" select="0"/>
<xsl:param name="doc.collab.show" select="0"/>
<xsl:param name="latex.output.revhistory" select="0"/>
<xsl:param name="doc.lot.show"></xsl:param>
<xsl:param name="latex.encoding">utf8</xsl:param>
<xsl:param name="imagedata.default.scale">pagebound</xsl:param>
<xsl:param name="latex.hyperparam">colorlinks,linkcolor=blue,urlcolor=blue</xsl:param>
<!-- Show <ulink>s as footnotes -->
<xsl:param name="ulink.footnotes" select="1"/>
<xsl:param name="ulink.show" select="1"/>
<!-- Don't use Graphics -->
<xsl:param name="admon.graphics" select="0"/>
<xsl:param name="callout.graphics" select="0"/>
<!-- Make pdflatex shut up about <prompt> and <command> within <programlisting>, -->
<!-- see http://dblatex.sourceforge.net/doc/manual/sec-verbatim.html -->
<xsl:template match="prompt|command" mode="latex.programlisting">
<xsl:param name="co-tagin" select="'&lt;:'"/>
<xsl:param name="rnode" select="/"/>
<xsl:param name="probe" select="0"/>
<xsl:call-template name="verbatim.boldseq">
<xsl:with-param name="co-tagin" select="$co-tagin"/>
<xsl:with-param name="rnode" select="$rnode"/>
<xsl:with-param name="probe" select="$probe"/>
</xsl:call-template>
</xsl:template>
</xsl:stylesheet>
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