From 7a2838de3473355d1cd652795241446886f721fb Mon Sep 17 00:00:00 2001 From: "barnboy%trilobyte.net" <> Date: Fri, 4 Apr 2008 11:48:05 +0000 Subject: Last transfer bombed on me. Added Bugzilla Guide as single large HTML and TXT files, and updated README.docs with compiling instructions for the Guide. --- docs/en/README.docs | 132 +++++++++------------------------------------------- 1 file changed, 22 insertions(+), 110 deletions(-) (limited to 'docs/en/README.docs') diff --git a/docs/en/README.docs b/docs/en/README.docs index 18c4126b8..6b5d6ed61 100644 --- a/docs/en/README.docs +++ b/docs/en/README.docs @@ -3,32 +3,34 @@ You'll find these directories and files here: README.docs # This README file html/ # The compiled HTML docs from SGML sources (do not edit) -xml/ # The original XML doc sources (edit these) +sgml/ # The original SGML doc sources (edit these) txt/ # The compiled text docs from SGML sources - -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. +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. 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 +editing duties, feel free to use any text editor to make the changes. SGML 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 XML before checking it in with something like: - nsgmls -s $JADE_PUB/xml.dcl Bugzilla-Guide.xml +your SGML before checking it in with something like: + nsgmls -s Bugzilla-Guide.sgml - When you validate, please validate the master document (Bugzilla-Guide.xml) + When you validate, please validate the master document (Bugzilla-Guide.sgml) 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 reason these occur is that free sgml 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 +entities referenced from Bugzilla-Guide.sgml 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. @@ -36,120 +38,30 @@ point, but for now they are convenient and don't hurt anything. 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: - -...and... - - -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. + You MUST have DocBook 4.1 set up correctly in order for this to work, + but there's only a single REMARK tag that's incompatible with 3.1. + Maybe I'll downgrade to DocBook 3.1 to make your life easier... + Substitute your own path to "ldp.dsl" for "$LDP_HOME". - 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 +../sgml/Bugzilla-Guide.sgml 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 +../sgml/Bugzilla-Guide.sgml >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 based on - experience setting this up on the Landfill test server. + barnboy@trilobyte.net -- cgit v1.2.3-24-g4f1b