Date: Fri, 15 Jan 1999 10:24:37 +0000 From: nclayton@lehman.com To: Jay Nelson <jdn@acp.qiv.com>, nik@FreeBSD.ORG Cc: doc@FreeBSD.ORG Subject: Re: TeX problems; Doc. Proj. needs you! Message-ID: <19990115102437.R18103@lehman.com> In-Reply-To: <Pine.BSF.3.96.990111204450.1490A-100000@acp.qiv.com>; from Jay Nelson on Mon, Jan 11, 1999 at 09:47:00PM -0600 References: <19981107211208.12650@nothing-going-on.org> <Pine.BSF.3.96.990111204450.1490A-100000@acp.qiv.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Hi Jay,
Sorry for the delay, I've been slightly swamped this week. I've cc'd
this to the -doc mailing list, so that other interested parties can
chime in as necessary.
On Mon, Jan 11, 1999 at 09:47:00PM -0600, Jay Nelson wrote:
> I've recently found myself in a position where I needed to learn more
> about SGML and remembered this email, so I thought maybe I could learn
> and do some good at the same time. I'm only concerned with book
> production output, so I've only looked at the TeX portion so far.
OK. Sounds good.
> That's raised a number of questions and some observations. Take the
> observations with a grain of salt, since I'm still not sure what I
> don't know about SGML and DSSSL.
>
> Should we be doing this in TeX or troff? (TeX would be my prefered
> weapon of choice -- but past books, I believe have been done in
> troff.)
At the moment, we can only do this in TeX. You probably already know
this, but this in case. . .
This is because of Jade. Specifically, Jade reads in the document and the
stylesheet. It then produces a formatted version of the document (where
the formatting instructions are internal to Jade). It hands this formatted
version off to whichever Jade backend has been selected, and it is the
responsibility of the backend to convert the Jade formatting instructions
into the instructions used by the backend.
Jade has a number of backends. RTF is built in to it. The TeX backend doesn't
write raw TeX. Instead it writes TeX that makes lots of macro calls that
roughly correspond with the internal Jade format.
The TeX that is written by Jade needs to be processed with a collection of
macros that actually implement the code that Jade calls. Hence the need for
JadeTeX by Sebastien Rahz.
If we were to do this in *roff Jade would need a *roff backend. I believe
Chuck Robey has been looking at this, but the last I spoke to him (about
a week ago) he was still working his way through the Jade source code, and
didn't have anything that could be tested. If you're interested in working
with him on implementing this then let me know.
Currently, we have a small problem with the JadeTeX macros -- they don't
handle some of the constructions in the Handbook. Sebastien has sent me a
new version, which fixes this problem but breaks PDF output. He knows about
this bug, and is working on a fix. If you've got the TeX skills to work on
this as well, please let me know.
> What are the TeX goals? Is this something that Walnut Creek is likely
> to publish and should I use Greg's book as a style guide?
> Specifically, should I convert the Garamond fonts used in "The
> Complete FreeBSD" for use with TeX and possibly troff and stay with
> the modified quarto format?
I don't know if WC is likely to publish it, because they already publish
Greg's book.
I think it's more important that it be easy for the user to download and
print -- this means at least two versions of each format produced (one
at US Letter size, one at A4 size), and available in as many useful formats
as possible (particularly for Windows and Mac users). I'm pretty certain
we've got this covered, with the PDF generation (when it works).
> The generation of one huge TeX file is rather dissatisfying
Not sure I understand this bit.
> and not very practical from a production standpoint.
Not sure. Going from .sgml to .tex to .dvi to .ps takes about 10 minutes on
my 64MB P200, however. . .
> Any problems with breaking it down on a chapter basis? Would this break
> the HTML generation?
It's already broken down into chapters (look in doc/en/handbook), it just
needs a framework so that Jade will process individual chapters. Note that
this breaks when you try and refer to sections in another chapter.
However, I have another, preferred approach to this -- in the long run I
want to break the Handbook out in to a number of separate books, a little
like the Linux HOWTOs (but with more control over their structure).
You'd have handbooks (note: little 'h', not big 'H') of between 30 and
100 pages (or so) with titles like
Read this first
Configuring FreeBSD
Installing Applications
Monitoring and limiting users
Printing
and so on. The idea is that each one is entirely self-contained and repeats
as little information as possible from any other book(let). While this is
not vastly different from what we have at the moment (the new books would
be organised along roughly the same lines as the existing chapters) because
they are books they are more self contained, and it makes it easier to
produce them individually (and therefore download them individually).
These would then comprise the _FreeBSD Documentation Set_.
I've written up a lot more about this which appeared in a thread on the
-doc mailing list. Take a look at
http://www.freebsd.org/~nik/hb/comments.txt
and
http://www.freebsd.org/~nik/hb/new-layout.txt
and
http://www.freebsd.org/~nik/hb/old-layout.txt
This is quite a radical change, and the first thing I intend to tackle when
the Jade issues have been worked out.
> The raw jade output is horrible, and generally, bad bookwork.
Pass. I'm not sufficiently up on TeX to comment.
> Inclusion of an additional style sheet is required to make a decent
> book. I'm not sure where that is best done. So far, I've added the
> redefinitions to freebsd.dsl under the %output.print section, but
> that's not the best place to put specific, local definitions. What do
> you suggest? What is the best way to include local style
> modifications?
If you wanted to override the definitions in freebsd.dsl then create your
own file (local.dsl?) and include freebsd.dsl in the same way that freebsd.dsl
includes Norm's stylesheets.
> I've noticed some failures of either the SGML or the TeX translation
> and, except for some missing end tags, I suspect it's in the TeX
> translation. Should I be looking at the SGML or the instant
> translation files? If the translation files, how do you want any
> changes to them managed?
'instant'? The new Handbook won't be going anywhere near 'instant' and the
transpecs. It's DSSSL all the way.
> I'm not too happy with the LaTeX orientation of the jadetex macros,
> but then I've never liked LateX because it never offered what I
> needed. Do you have a preference between keeping the jadetex macros
> and rewriting the macro package? A rewrite would make the stylesheet
> issue simpler, but would not simplify variations.
"As long as it works" :-) You're probably better off talking to
Sebastien Rahz (<srahz@elsevier.com>) and James Clark (<jjc@jclark.com>)
directly I think.
> The jpja language business is broken in the modular docbook package,
> and, at this point, I haven't figured out how to fix it or make the
> error messages go away. I fact, I doubt I could make it work properly.
> Is anyone working on this?
Jun Kuriyama who wrote them I believe. I think the jpja stuff will be
rolled in to a future release of Norm's stylesheets, so this issue
should sort itself out.
N
--
--+==[ Systems Administrator, Year 2000 Test Lab, Lehman Brothers, Inc. ]==+--
--+==[ 1 Broadgate, London, EC2M 7HA 0171-601-0011 x5514 ]==+--
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?19990115102437.R18103>