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