Re: Playing with the spec
Hi Nik,
* Nik Clayton <nik@freebsd.org> wrote:
> 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?
We don't care about package management systems. Please read 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/
Everybody uses Makefile. But you have to write them over and over
again. DSSSL uses Scheme, so why don't use sh for the Unix-side of that
problem?
> 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 is our main goal. We need the guys from the distributions for that,
because they are yet packaging this. They know the item. You know it,
too.
> 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.
We want to do exactly that. It doesn't care how the stuff gets on the
machine and where it is - as long as either the locations comply to the
standard or the given locations are defined in the configuration file.
> 2. Describe the process of using these tools to produce a variety of
> different output formats.
We're doing that, although we try to put a simple, but flexible
interface around it. We would like to automate this process as far as
possible.
> 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.")
Yepp. We want to define "default locations" for these. And a default
configuration file (/etc/sgml/sgml.conf), which you won't need, if your
system is fully compliant to that standard. If not, you can change every
single item of the standard from this file (simple sh-variables).
> 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).
Imagine "dbk2 html foo.sgml". "dbk2" is a shellscript, lets call it a
"frontend". It has all file locations of the standard (which isn't there
yet) builtin as default, but reads /etc/sgml/sgml.conf if available. It
also queries the user for the "backend" to use (the "html" in the
example above) and the filename of the SGML-instance (it also has
commandline options). Now it puts all it knows in environment variables
(the file locations (maybe adjusted by that config-file), the parsed
commandline options, etc.), exports the variables (or pipes them over
stdin) and calls the named backend. This backend is a small shell
script, which than has everything needed to call the programms to do its
job, it has not to care anymore about file locations (it uses the
variables).
An example: If I call "dbk2 man foo.sgml", the script calls the
following simple script "man.backend":
# Convert from DocBook to *roff
nsgmls $DB_FILE | sgmlspl $DB_BASE_DIR/docbook-utils-0.2/docbook2man-spec.pl
if [ $? -ne 0 ]
then exit 1
fi
As you see, this doesn't uses DSSSL, it uses perl. A backend for
converting *roff to DocBook RefEntry using rman would also be just one
line. But this works with the same backend-interface and frontend as
this "html.backend":
# Convert from DocBook to HTML
$DB_PARSER -t sgml $DB_ARGUMENTS
if [ $? -ne 0 ]
then exit 1
fi
As you see, all this is very little code. The main script sources a
(optional) configuration file and parses the commandline. It than calls
a backend, that gets everything readily served (via the environment or
stdin, we haven't decided yet), without having to assume anything. This
backend then can call a converter engine (DSSSL, a java-program, a perl
script, whatever), it has everything needed handy. That's applied
documentation. ;-)
The configuration file may contain a lot of entries like
DB_BASE_DIR="/usr/share/sgml"
DB_BACKEND_DIR="$DB_BASE_DIR/docbook-utils-0.2"
DB_PARSER_EXEC="jade"
...
These variable names actually define the standard (their value can be
adjusted to the given system).
> 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.
We are currently writing a first documentation and yes, this is
boring. But we have to write code to test this. If one can write such a
frontend or a backend without knowing anything else than the defined set
of variables, the location of the configuration file and the method of
getting at the variables from the backend, this thing will be worth a
try. And we have a first implemention. ;-)
What we need now: people from the distributions (and FreeBSD) to agree
on a common set of file locations and associated variables. What is
needed and where should it be? They can adjust this later in real life
in their configuration file, but we have to agree to a set of
key/value-pairs first.
Sorry for the long posting,
Jochem
--
Hi! I'm a .signature virus! Copy me into your ~/.signature to help me spread!
Reply to: