1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
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.
|
