Re: Playing with the spec
Hi guys,
On Fri, Mar 03, 2000 at 09:45:33PM +0100, Jochem Huhmann wrote:
> * gk4@us.ibm.com wrote:
> > Enclosed is a shell script that I used to download and install the
> > sgmltools for Redhat 6.2beta. Also attached are the changes to the
> > makefile I used to build the spec.
>
> See the attached announcement. Please stop hacking on such
> distribution-specific things, there are already too many of these. An
> approach is underway to standardize that once and for all (that is: The
> environment for SGML/DocBook-processing tools on Unix or at least
> Linux).
[ Brief bio: I'm the FreeBSD documentation project manager (sans pointy
hair). I drove the adoption of DocBook by the FDP, created most of the
FreeBSD build infrastructure for it, and have done most of the LinuxDoc
to DocBook conversions. We've been using DocBook for the last 18 months
or so, and have it, and the associated tools, quite nicely integrated in
to the build system. I'm also a member (although not a particularly
active participant) of the SGML Tools mailing list, and the Open Source
Writers Group mailing list. FWIW, I'm also nik@slashdot.org. ]
How do you intend to standardise any of this across such a wide variety
of Unices, each one with its own package management systems, and preferred
locations for configuration files ("/etc/sgml.conf indeed! Everyone knows
it should be /usr/local/etc/sgml.conf!") and so on? Don't forget that not
everyone wants scripts -- a far more BSDish way of doing things (hence my
interest) is Makefiles, and you can see some examples at
http://www.freebsd.org/cgi/cvsweb.cgi/doc/share/sgml/
SGML Tools tried this, and failed.
My point is that we should not be concentrating on trying to build a one
size fits all collection of packages and scripts to handle installation
of all the appropriate bits and pieces, and then drive that installation.
Instead, we should (IMHO) be doing the following:
1. Describe what programs and ancillary files are necessary to do SGML
processing (Jade, DTDs, stylesheets, ...).
This lets the OS package management people (*BSD, RedHat, Debian,
Suse, Sun, ...) do their thing to get the software and support files
installed on the machine.
2. Describe the process of using these tools to produce a variety of
different output formats.
The reader of this description can then look on their own system to
determine where the tools and configuration files have been stored.
("Let's see. I need to find jade(1), and the DSSSL stylesheets. The
docs say I should try /usr/local/bin. Ah, OK, now I've found Jade,
where are the stylesheets? /opt/share? Nope, not there. How about
/usr/local/sgml? Nope, can't find them there either. What about
/usr/local/share/sgml? Ah, there they are.")
3. (Maybe) Produce some simple shell scripts (or make(1) fragments) that
show how these things can all be tied to together to produce a
docbook2html.sh script (or a "docbook2.sh -format html foo.sgml"
script).
I realise that this is almost all documentation, with no coding required,
and that's probably going to turn a lot of you off the whole idea, but I
don't see that we need to do much more.
*Maybe* we need to go one step further:
4. Strongly suggest that any package management system that installs
these tools also installs script(s) called docbook2[html,ps,pdf,...]
that do the appropriate conversion using some default parameters,
and put these scripts in the usual place ("/usr/local/bin/" probably).
We can then tell application writers that ship DocBook documentaiton
(e.g., the Postgresql folks) that their application install procedures
can check for the presence of these docbook2... scripts in the
standard path, and if they find one then they can assume that the
necessary tools have been installed to do the work.
[ Note: s/docbook/$DTD_OF_CHOICE/ if it bothers you. Also note that the
names of scripts in the above are examples only, and can probably
be renamed to something more appropriate as necssary. ]
Does the above make sense?
N
--
If you want to imagine the future, imagine a tennis shoe stamping
on a penguin's face forever.
--- with apologies to George Orwell
Reply to: