Re: First beta version of the Debian SGML/XML HOWTO
On Saturday 2 October 1999, at 15 h 12,
Adam Di Carlo <adam@onshore.com> wrote:
> I didn't read all the sections yet but I find it odd that you go
> into how to install the SGML/XML environment prior to launching into
> expositions on how to work with the various DTDs.
I don't understand: there are no real explanations about "how to install the
SGML/XML environment" since I just assume "apt-get install task-sgml".
> should have a brief section, "Installation", which simply instructs
> the user to install the task-sgml package (in potato, that is),
> either via apt-get or dselect.
It exists, at the beginning of the Tools section. Apparently, it can be missed
:-) Note the HOWTO has two versions: the slink one just expand the task-sgml
package.
> I also think you need to add a brief section talking about the
> Debian SGML/XML infrastructure briefly, mentioning sgml-base and the
> "SGML Sub-Policy" contained in that package.
I hesitate: the purpose of the HOWTO is to be practical, so that people can
start as soon as possible. It is intended for people who wish to write a Linux
HOWTO, or to patch a Debian documentation, or to print a DocBook file they
received, not for Debian SGML maintainers or students in markup languages.
Anyway, if someone writes a nice paragraph about the Debian SGML
infrastructure (for slink and for potato), I would be glad to include it.
Otherwise, I'll try to hack something.
> We also need to talk
> about (maybe in a different section?) how install-sgmlcatalog is
> used, the default SGML search paths in Debian, and how the user can
> use install-sgmlcatalog (or manual editing) to install their own
> DTDs and entities under /usr/local.
It is not my top priority, expect may be for the installation of your "own"
DTD (which is a realistic case, while the search paths are invisible, thanks
to the Debian SGML infrastructure). Again, since it is not my priority, I
would be glad if someone else did it.
> My brief perusal of the various DTD-related sections shows me that
> you didn't have any pointers on where to go for more information.
Most are in the section References. But every section about a DTD has at least
a link "To learn more". For DebianDoc, it points toward "Debiandoc-SGML Markup
Manual", in the debiandoc-sgml package.
> For example, regarding debiandoc-sgml, users should file a bug on a
> package; general comments should go to debian-doc@lists.debian.org.
Right.
> Likewise, you should talk about the DSSSL list,
Hmmm, may be a bit complicated?
> and the sgml-tools
> list, and the DocBook mail list.
I point to their respective Web sites, where this info is. Beginners in a
hurry don't want to subscribe to a mailing list to start.
> Section "Why this HOWTO? What's in it?":
>
> The introdocutory paragraph is confusing and hard to read.
That's the problem when you write a documentation in English and you don't
speak english :-)
> section title should perhaps be changed to "Scope and Audience for
> this HOWTO". To the first para of the section, I would add a little
> "Rationale", such as "Setting up an SGML environment is notoriously
> difficult and time-consuming on most systems. Debian, however, has
> worked to solve this problem.
See next paragraph.
> Section "Why specific to Debian?"
>
> Rather than out-and-out advocacy of Debian,
The previous paragraph was advocacy. I just said that Debian is the best Unix.
> you should just point
> out that Debian itself includes an integrated SGML environment, and
> because of that, setting up the system is significantly different in
> Debian than any other OS.
It is different for every system. Debian is no more different from Solaris
than from Windows-NT (I refer only to SGML environment). No, the reason why I
made the HOWTO Debian-specific is very clear, may be not in my words, but in
my head: experience on SGML mailing lists show that it is near to impossible
to provide <emphasis>practical</emphasis> information on SGML, in a
system-independant way ("Add the XML declaration, /usr/lib/sgml/declaration/xml
.decl, to the jade command line. But I don't have this file! Where can I find
it?").
> Section "What is structured documentation?"
>
> Be careful -- SGML itself does not enforce structural markup as
> opposed to presentational markup.
<bold boldness="high">Right</bold>. But I concentrate on one aspect of SGML,
writing structured documentation. I do not talk about the use of XML for data
interchange, for instance.
> You say:
> If it looks like HTML, it is because HTML is theoretically a DTD of SGML.
>
> I would replace "theoretically" with "ostensibly". It's not just
> theoretic, since there *is* an HTML DTD (published by w3o no less).
> The problem is that practically HTML is rarely valid SGML.
As you say. I used "HTML" to mean "The language in which almost all Web pages
are written", not to mean "The language standardized by the W3C".
> Section "References"
...
> Under RedHat, Mark Galassi's "DocWare" stuff, at
> http://sourceware.cygnus.com/docbook-tools/, offers a set of add-ons
> and a guide for RedHat users, I believe.
Added.
> Section "Tools"
>
> "nsgmls" is actually the SP suite.
Recently added.
> You might also add
> cygnus-stylesheets, which is used in particular by the gnome folks.
I do not know them a lot. I will postpone their inclusion until I had time to
examine them.
> I'd be pleased to offer you CVS space in the
> cvs.debian.org:/cvs/debian-doc area if you want it.
I was planning to ask you for that, as soon as the HOWTO is sufficiently
debugged.
--
http://www.debian.org/~bortz/
Reply to: