summaryrefslogtreecommitdiffstats
path: root/docs/en
diff options
context:
space:
mode:
Diffstat (limited to 'docs/en')
-rw-r--r--docs/en/README.docs90
1 files changed, 82 insertions, 8 deletions
diff --git a/docs/en/README.docs b/docs/en/README.docs
index 6b5d6ed61..b490c83b6 100644
--- a/docs/en/README.docs
+++ b/docs/en/README.docs
@@ -38,29 +38,103 @@ 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 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,
- 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".
+ 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 \
-../sgml/Bugzilla-Guide.sgml
+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 \
-../sgml/Bugzilla-Guide.sgml >Bugzilla-Guide.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"