From 650a2f9f5807536ee118ba031622bede7f4e1642 Mon Sep 17 00:00:00 2001 From: Frédéric Buclin Date: Mon, 24 Oct 2011 12:35:48 +0200 Subject: Bug 423496: Compile the documentation with xmlto + dblatex instead of openjade r=glob a=LpSolit --- docs/en/xml/Bugzilla-Guide.xml | 72 ++++------------- docs/en/xml/about.xml | 12 ++- docs/en/xml/administration.xml | 12 +-- docs/en/xml/conventions.xml | 169 +++++++++++----------------------------- docs/en/xml/customization.xml | 12 ++- docs/en/xml/gfdl.xml | 8 +- docs/en/xml/glossary.xml | 10 ++- docs/en/xml/installation.xml | 143 +++++++++++++++++----------------- docs/en/xml/modules.xml | 8 +- docs/en/xml/patches.xml | 8 +- docs/en/xml/security.xml | 7 +- docs/en/xml/troubleshooting.xml | 29 ++++--- docs/en/xml/using.xml | 9 ++- 13 files changed, 212 insertions(+), 287 deletions(-) (limited to 'docs/en/xml') diff --git a/docs/en/xml/Bugzilla-Guide.xml b/docs/en/xml/Bugzilla-Guide.xml index 4265677ed..b20962358 100644 --- a/docs/en/xml/Bugzilla-Guide.xml +++ b/docs/en/xml/Bugzilla-Guide.xml @@ -1,51 +1,9 @@ - - %myents; - - - - - - - - - - - - - - - - - - - - - - - - - - -Bugzilla Documentation"> - - - ]> - -&about; + -&installation; + -&administration; + -&security; + -&using; + -&customization; + -&troubleshooting; + -&patches; + -&modules; + -&gfdl; + -&glossary; - - -&index; - + diff --git a/docs/en/xml/about.xml b/docs/en/xml/about.xml index a6cebe0e0..ffc52e9f9 100644 --- a/docs/en/xml/about.xml +++ b/docs/en/xml/about.xml @@ -1,5 +1,9 @@ - + + + %myents; +]> About This Guide @@ -190,8 +194,8 @@ -&conventions; - + + + + + %myents; +]> + Administering Bugzilla @@ -24,10 +30,6 @@ deploying a new Bugzilla installation. - - checklist - - diff --git a/docs/en/xml/conventions.xml b/docs/en/xml/conventions.xml index 70e6624f7..6a8f8b47e 100644 --- a/docs/en/xml/conventions.xml +++ b/docs/en/xml/conventions.xml @@ -1,144 +1,65 @@ - + + + %myents; +]> +
Document Conventions - - conventions - - This document uses the following conventions: - - - - - Descriptions - - Appearance - - - - - - Caution - - - - Don't run with scissors! - - - - - - Hint or Tip - - - - For best results... - - - - - - Note - - - - Dear John... - - - - - - Warning - - - - Read this or the cat gets it. - - - - - - File or directory name + + This is a caution. Make sure to read this to not be in trouble! + - - filename - - + + This is a hint or tip, especially about some configuration tweaks. + - - Command to be typed + + This is just a note, for your information. + - - command - - + + This is a warning, something you should take care of. + - - Application name - - - application - - - - - - Normal user's prompt under bash shell - - bash$ - - - - - Root user's prompt under bash shell - - bash# - - - - - Normal user's prompt under tcsh shell - - tcsh$ - - - - Environment variables + + A filename or a path to a filename is displayed like this: + /path/to/filename.ext + - - VARIABLE - - + + A command to type in the shell is displayed like this: + command --arguments + - - Term found in the glossary + bash$ represents a normal user's prompt under bash shell - - Bugzilla - - + bash# represents a root user's prompt under bash shell - - Code example + + A word which is in the glossary will appear like this: + Bugzilla + - - para -Beginning and end of paragraph -para - - - - - + + A sample of code is illustrated like this: + +First Line of Code +Second Line of Code +... + + - - This documentation is maintained in DocBook 4.1.2 XML format. + + 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 Bugzilla Documentation + component. -
+ + + %myents; +]> + Customizing Bugzilla @@ -14,7 +20,7 @@ - See the Bugzilla Extension + See the Bugzilla Extension documentation for information on how to write an Extension. @@ -391,7 +397,7 @@ An example of this is the mozilla.org - guided + guided bug submission form. The code for this comes with the Bugzilla distribution as an example for you to copy. It can be found in the files diff --git a/docs/en/xml/gfdl.xml b/docs/en/xml/gfdl.xml index 1d84d1255..0de66acd3 100644 --- a/docs/en/xml/gfdl.xml +++ b/docs/en/xml/gfdl.xml @@ -1,4 +1,10 @@ - + + + %myents; +]> + GNU Free Documentation License diff --git a/docs/en/xml/glossary.xml b/docs/en/xml/glossary.xml index aef3ab395..8d0c0e58d 100644 --- a/docs/en/xml/glossary.xml +++ b/docs/en/xml/glossary.xml @@ -1,4 +1,10 @@ - + + + %myents; +]> + 0-9, high ascii @@ -42,7 +48,7 @@ Useful Directives when configuring Bugzilla - AddHandler + AddHandler Tell Apache that it's OK to run CGI scripts. diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml index e43c567b8..cdff751d4 100644 --- a/docs/en/xml/installation.xml +++ b/docs/en/xml/installation.xml @@ -1,4 +1,10 @@ - + + + %myents; +]> + Installing Bugzilla @@ -169,16 +175,17 @@ Installed Version Test: view the default welcome page at http://<your-machine>/ - You have freedom of choice here, pretty much any web server that - is capable of running CGI - 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;. + + You have freedom of choice here, pretty much any web server that + is capable of running CGI + 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 + Bugzilla Documentation. - + If you don't have Apache and your OS doesn't provide official packages, visit . @@ -732,9 +739,9 @@ max_allowed_packet=4M This can be done by modifying the /etc/my.cnf according to the example below: - [mysqld] - # Allow small words in full-text indexes - ft_min_word_len=2 + [mysqld] +# Allow small words in full-text indexes +ft_min_word_len=2 Rebuilding the indexes can be done based on documentation found at . @@ -770,11 +777,11 @@ max_allowed_packet=4M - mysql> GRANT SELECT, INSERT, - UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES, - CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.* - TO bugs@localhost IDENTIFIED BY '$db_pass'; - mysql> FLUSH PRIVILEGES; +mysql> GRANT SELECT, INSERT, + UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES, + CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.* + TO bugs@localhost IDENTIFIED BY '$db_pass'; +mysql> FLUSH PRIVILEGES; @@ -796,8 +803,8 @@ max_allowed_packet=4M - mysql> use $bugs_db - mysql> ALTER TABLE attachments +mysql> use $bugs_db +mysql> ALTER TABLE attachments AVG_ROW_LENGTH=1000000, MAX_ROWS=20000; @@ -832,11 +839,11 @@ max_allowed_packet=4M On most systems, to create the user in PostgreSQL, you will need to login as the root user, and then - bash# su - postgres + bash# su - postgres As the postgres user, you then need to create a new user: - bash$ createuser -U postgres -dRSP bugs + bash$ createuser -U postgres -dRSP bugs When asked for a password, provide the password which will be set as $db_pass in localconfig. @@ -880,9 +887,9 @@ max_allowed_packet=4M - CREATE TABLESPACE bugs - DATAFILE '$path_to_datafile' SIZE 500M - AUTOEXTEND ON NEXT 30M MAXSIZE UNLIMITED +CREATE TABLESPACE bugs +DATAFILE '$path_to_datafile' SIZE 500M +AUTOEXTEND ON NEXT 30M MAXSIZE UNLIMITED @@ -907,17 +914,17 @@ max_allowed_packet=4M - CREATE USER bugs - IDENTIFIED BY "$db_pass" - 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 "$db_pass" +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; @@ -930,8 +937,8 @@ max_allowed_packet=4M - 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/ @@ -1040,12 +1047,12 @@ max_allowed_packet=4M - <Directory /var/www/html/bugzilla> - AddHandler cgi-script .cgi - Options +Indexes +ExecCGI - DirectoryIndex index.cgi - AllowOverride Limit FileInfo Indexes - </Directory> +<Directory /var/www/html/bugzilla> +AddHandler cgi-script .cgi +Options +Indexes +ExecCGI +DirectoryIndex index.cgi +AllowOverride Limit FileInfo Indexes +</Directory> @@ -1101,9 +1108,7 @@ max_allowed_packet=4M (the same one as in the step above): - - +FollowSymLinks - + +FollowSymLinks Without this directive, Apache will not follow symbolic links @@ -1142,10 +1147,10 @@ max_allowed_packet=4M You should also ensure that you have disabled KeepAlive support in your Apache install when utilizing Bugzilla under mod_perl - + - PerlSwitches -w -T - PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl +PerlSwitches -w -T +PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl @@ -1521,8 +1526,8 @@ AddType application/rdf+xml .rdf and the utilities available to make it easier. - If you have anything to add or notes for an operating system not - covered, please file a bug in &bzg-bugs;. + If you have anything to add or notes for an operating system not covered, + please file a bug in Bugzilla Documentation.
@@ -1855,13 +1860,11 @@ pid-file=/home/foo/mymysql/the.pid After your mysqld program is built and any .my.cnf file is in place, you must initialize the databases (ONCE). - bash$ - mysql_install_db +bash$ mysql_install_db Then start the daemon with - bash$ - safe_mysql & +bash$ safe_mysql & After you start mysqld the first time, you then connect to it as "root" and GRANT permissions to other @@ -1883,7 +1886,6 @@ pid-file=/home/foo/mymysql/the.pid
-
@@ -1897,16 +1899,11 @@ pid-file=/home/foo/mymysql/the.pid - bash$ - wget http://perl.org/CPAN/src/stable.tar.gz - bash$ - tar zvxf stable.tar.gz - bash$ - cd perl-5.8.1 (or whatever the version of Perl is called) - bash$ - sh Configure -de -Dprefix=/home/foo/perl - bash$ - make && make test && make install +bash$ wget http://perl.org/CPAN/src/stable.tar.gz +bash$ tar zvxf stable.tar.gz +bash$ cd perl-&min-perl-ver; +bash$ sh Configure -de -Dprefix=/home/foo/perl +bash$ make && make test && make install @@ -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 install-module.pl script. For more details on this script, see - install-module.pl + install-module.pl documentation
@@ -2000,10 +1997,12 @@ pid-file=/home/foo/mymysql/the.pid shell commands after running ./checksetup.pl, every time you run it (or modify checksetup.pl to do them for you via the system() command). - 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 + +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 + 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. diff --git a/docs/en/xml/modules.xml b/docs/en/xml/modules.xml index 933c9de5b..a578f9f16 100644 --- a/docs/en/xml/modules.xml +++ b/docs/en/xml/modules.xml @@ -1,4 +1,10 @@ - + + + %myents; +]> + Manual Installation of Perl Modules diff --git a/docs/en/xml/patches.xml b/docs/en/xml/patches.xml index 12efb0ca4..e5a6a8c47 100644 --- a/docs/en/xml/patches.xml +++ b/docs/en/xml/patches.xml @@ -1,4 +1,10 @@ - + + + %myents; +]> + Contrib diff --git a/docs/en/xml/security.xml b/docs/en/xml/security.xml index b234dd993..270b8a72c 100644 --- a/docs/en/xml/security.xml +++ b/docs/en/xml/security.xml @@ -1,4 +1,9 @@ - + + + %myents; +]> Bugzilla Security diff --git a/docs/en/xml/troubleshooting.xml b/docs/en/xml/troubleshooting.xml index fff90a9e1..f42436d2e 100644 --- a/docs/en/xml/troubleshooting.xml +++ b/docs/en/xml/troubleshooting.xml @@ -1,4 +1,9 @@ - + + + %myents; +]> Troubleshooting @@ -173,17 +178,17 @@ TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-t
- urlbase is - cookiepath is / +urlbase is http://bugzilla.mozilla.org/ +cookiepath is / - urlbase is - 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 /
- + 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 Examples of urlbase/cookiepath pairs to restrict the login cookie
- urlbase is - cookiepath is /bugzilla-tip/ +urlbase is http://landfill.bugzilla.org/bugzilla-tip/ +cookiepath is /bugzilla-tip/ - urlbase is - cookiepath is /bugzilla-2.16-branch/ +urlbase is http://landfill.bugzilla.org/bugzilla-4.0-branch/ +cookiepath is /bugzilla-4.0-branch/
diff --git a/docs/en/xml/using.xml b/docs/en/xml/using.xml index 6d575c0c1..e832dea7a 100644 --- a/docs/en/xml/using.xml +++ b/docs/en/xml/using.xml @@ -1,4 +1,9 @@ - + + + %myents; +]> Using Bugzilla @@ -377,7 +382,7 @@ Lifecycle of a Bugzilla Bug - + -- cgit v1.2.3-24-g4f1b