Date: Fri, 19 Jan 2001 15:53:20 +0000 From: Nik Clayton <nik@freebsd.org> To: Alexander Langer <alex@freebsd.org> Cc: Nik Clayton <nik@freebsd.org>, cvs-committers@freebsd.org, cvs-all@freebsd.org, doc@freebsd.org, nwalsh@nwalsh.com Subject: Re: cvs commit: ports/textproc/dsssl-docbook-modular Makefile ports/textproc/dsssl-docbook-modular/files patch-common_dbl1de.dsl Message-ID: <20010119155319.A48911@canyon.nothing-going-on.org> In-Reply-To: <20010119125752.A56295@cichlids.cichlids.com>; from alex@freebsd.org on Fri, Jan 19, 2001 at 12:57:52PM %2B0100 References: <200101190840.f0J8e7e87294@freefall.freebsd.org> <20010119105051.A47479@canyon.nothing-going-on.org> <20010119125752.A56295@cichlids.cichlids.com>
next in thread | previous in thread | raw e-mail | index | archive | help
I've cc'd Norm Walsh on this -- Norm, perhaps you could suggest a more
elegant approach to the problem? ]
On Fri, Jan 19, 2001 at 12:57:52PM +0100, Alexander Langer wrote:
> Thus spake Nik Clayton (nik@freebsd.org):
>
> > This is actually broken in our customisation layer in the most recent
> > versions of the base stylesheets. Norm re-worked how he did things,
> > which is why the Handbook says things like "WarningDon't do this"
> > instead of "Warning: Don't do this.".
> > Fixing it is on my list of things to do, unless someone beats me to it.
>
> Oh - wait...
> Do you mean this has to be fixed somewhere in *our* doc/ tree?
Sort of.
In an earlier version of Norm's stylesheets, he had a function called
$admonition$ that was used by <note>, <important>, and <tip>.
The $admonition$ function used variables like en-note-label-title-sep to
work out what to put between text like "Note" and the title. So Norm's
stylesheets had things like
(define en-note-label-title-sep ": ")
in them, which is how
<note><para>A test note</para></note>
became
Note: A test note
<warning> and <caution> were handled differently. They had their own
function to draw a box around them (or put them in a table), and do
sundry other bits and pieces. In particular, this style of presentation
meant that the "Warning" and "Caution" label was placed on a separate
line, so there was no need for ':' to separate the two pieces of text.
However, for (I guess) completeness, Norm's sheets still defined the
equivalent en-warning-label-title-sep variable (and it's <caution>
equivalent).
I changed this in our customisation, so that <warning> and <caution>
used the same $admonition$ function, and redefined the
en-warning-label-title-sep and en-caution-label-title-sep variables
appropriately.
All was well.
Then Norm changed how he did things. Instead of using a bunch of
variables, one per (language x element) pair, he created this function
called gentext-label-title-sep (and others in the same style). I
suspect this probably makes the DSSSL processing faster, or something.
The problem with this, from our point of view, is that it's no longer
possible to override a single entry in our customisation. Instead, to
fix <warning> and <caution>, I have to duplicate all of the code from
dbl1en.dsl that defines the en-label-title-sep hash[1] *or* rewrite the
gentext-en-label-title-sep function so that it special cases <warning>
and <caution> before it looks in the en-label-title-sep hash.
Neither of which are particularly clean, so I've sort of ignored the
problem, in the hope that I dream up a better way.
The alternative is to do what you've done, which is patch the
stylesheets as they're installed. That's not really the perfect
approach either, as anyone that tries to formation documentation on
FreeBSD that doesn't use our customisation layer will now find that they
get a spurious ': ' inserted when they use <warning> or <caution>.
Anyway, that's the problem, and we have at least three solutions, none
of which are (IMHO) optimal. Any suggestions for a fourth way?
N
--
Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95.
Telephone line, $24.95 a month. Software, free. USENET transmission,
hundreds if not thousands of dollars. Thinking before posting, priceless.
Somethings in life you can't buy. For everything else, there's MasterCard.
-- Graham Reed, in the Scary Devil Monastery
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010119155319.A48911>