зеркало из https://github.com/mozilla/pjs.git
156 строки
6.1 KiB
Plaintext
156 строки
6.1 KiB
Plaintext
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.
|