pjs/webtools/bugzilla/docs

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 SGML sources (do not edit)
sgml/		# The original SGML doc sources (edit these)
txt/		# The compiled text docs from SGML sources
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.  SGML
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 SGML before checking it in with something like:
	nsgmls -s Bugzilla-Guide.sgml

  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 validators do not yet support
the DTDDECL catalog entries, and I've included DOCTYPE declarations in
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.

  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 SGML EDITING ENVIRONMENT:
==========

Trying to set up an SGML/XML Docbook editing environment the 
first time can be a daunting task.
I use Linux-Mandrake, in part, because it has a fully-functional
SGML/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-dtd41-sgml
docbook-style-dsssl
docbook-dtd31-sgml
docbook-style-dsssl-doc
xemacs
psgml
sgml-tools
sgml-common

Set up environment:

in your .bashrc add this line (after installing above RPMS):
export SGML_CATALOG_FILES=/etc/sgml/catalog

Download "ldp.dsl" from the Resources page on linuxdoc.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-1.62/html/docbook.dsl" CDATA 
dsssl>
...and...
<!ENTITY docbook.dsl SYSTEM "../dsssl-stylesheets-1.62/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.

  You know, this sure looks awful involved.  Anyway, once you have this in 
place, add to your .bashrc:
export LDP_HOME=/usr/share/sgml/docbook/ldp

  I suggest xemacs for editing your SGML/XML Docbook documents.  The darn
thing just works, and generally includes PSGML mode by default.  You can
download psgml at http://www.sourceforge.net/projects/psgml.

==========
NOTES:
==========

  Here are the commands I use to maintain this documentation.
  You MUST have DocBook 4.1 set up correctly in order for this to work.
  Substitute your own path to "ldp.dsl" for "$LDP_HOME".  Additionally,
  there is now a dependency on "xml.dcl" since we converted the Guide
  to XML.  Note that below, it is hard-coded to
  /usr/share/doc/openjade-1.3/pubtext/xml.dcl.  Modify it to point to
  openjade's xml.dcl on your system.


To create HTML documentation:
bash$ cd html
bash$  jade -t sgml -i html -d $LDP_HOME/ldp.dsl\#html \
/usr/share/doc/openjade-1.3/pubtext/xml.dcl ../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 \
/usr/share/doc/openjade-1.3/pubtext/xml.dcl ../sgml/Bugzilla-Guide.sgml

To create TXT documentation as a single big TXT file:
bash$ cd txt
bash$ lynx -dump -nolist ../html/Bugzilla-Guide.html >Bugzilla-Guide.txt


## Change for XML
There's a small change in how you use Jade now that we've converted the
Bugzilla Guide to XML from SGML.  Now call Jade this way to compile HTML
documentation:

(I need to remove the hard-coded path to xml.dcl for openjade)

Sincerely,
 Matthew P. Barnson
 The Bugzilla "Doc Knight"
 barnboy@trilobyte.net