Re: First beta version of the Debian SGML/XML HOWTO

[Adam Di Carlo <adam@onshore.com>]

Comments:

General: 

  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.  So I think you
  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.

  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.  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.

  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.
  For example, regarding debiandoc-sgml, users should file a bug on a
  package; general comments should go to debian-doc@lists.debian.org.
  Likewise, you should talk about the DSSSL list, and the sgml-tools
  list, and the DocBook mail list.

Section "Why this HOWTO? What's in it?":

  The introdocutory paragraph is confusing and hard to read.  The
  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.  This HOWTO explains the Debian SGML
  environments, how to set it up, and how to work with it."

Section "Why specific to Debian?"

  Rather than out-and-out advocacy of Debian, 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.

Section "What is structured documentation?"

  Be careful -- SGML itself does not enforce structural markup as
  opposed to presentational markup.  For instance, the HTML DTD is
  presentational; our own DebianDoc DTD has both presentational and
  structural tags, such as <tt>.  So you need to make the distinction;
  not all SGML is strictly structured.

Section "How does SGML look like?"

  Section title should be "What does SGML look like?"

  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.

Section "References"

     * Other operating systems: this section will list documents
       similar to this HOWTO (I mean practical documents) for
       operating systems other than Debian.

  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.


Section "Tools"

  "nsgmls" is actually the SP suite.  You might also add
  cygnus-stylesheets, which is used in particular by the gnome folks.


I'd be pleased to offer you CVS space in the
cvs.debian.org:/cvs/debian-doc area if you want it.  This would
provide an anonymous-accessible CVS area in a standard location and
autogenerated development copies of the document in the DDP area.

--
.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>