diff options
Diffstat (limited to 'docs/en/README.docs')
| -rw-r--r-- | docs/en/README.docs | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/docs/en/README.docs b/docs/en/README.docs new file mode 100644 index 000000000..5fdeb8570 --- /dev/null +++ b/docs/en/README.docs @@ -0,0 +1,155 @@ +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. + 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. + + 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 . + +========== +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 Linux-Mandrake, 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 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 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 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 + + 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 + +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 + +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. |