diff options
Diffstat (limited to 'docs/en')
| -rw-r--r-- | docs/en/README.docs | 90 |
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" |