Date: Tue, 13 Apr 1999 11:17:50 +0100 From: nclayton@lehman.com To: Jay Nelson <jdn@acp.qiv.com>, Nik Clayton <nik@nothing-going-on.demon.co.uk> Cc: FreeBSD Documenters <doc@FreeBSD.ORG> Subject: Re: How to format handbook (Re: Publishing the FreeBSD handbook) Message-ID: <19990413111750.F14492@lehman.com> In-Reply-To: <Pine.BSF.4.05.9904121813120.1033-100000@acp.qiv.com>; from Jay Nelson on Mon, Apr 12, 1999 at 07:06:30PM -0500 References: <19990412212213.B9344@catkin.nothing-going-on.org> <Pine.BSF.4.05.9904121813120.1033-100000@acp.qiv.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, Apr 12, 1999 at 07:06:30PM -0500, Jay Nelson wrote:
> On Mon, 12 Apr 1999, Nik Clayton wrote:
> [snip]
>
> > 3. Are there plans for any additional content to be "Print version only"?
>
> Some of the obvious in traditional bookwork, besides indices and
> perhaps appendices is the usual front matter (half titles,
> introduction, preface, forward/"how to use this...", etc.,) besides
> table of contents.
I think having this in the on-line and 'regular' print versions is a good
idea as well.
> The problem I'm having now, though, is with the front matter. The
> missing portions are easy to solve, but I can't see how to get roman
> folios
Roman folio?
> or a title page graphic.
<bookinfo> can contain a <graphic>. I don't know if the stylesheets
do anything with it though.
> The <bookinfo> tag appears to be the
> wrapper for everything that is front matter, but I see no dsssl hooks
> that will set the page-number-format correctly on entering <bookinfo>
> or reset it on leaving. Nothing I've tried does the right thing and by
> the time jade outputs TeX, the folios are already fixed as arabic. I
> can also see some of the hooks for graphics, but I haven't been able
> to make them work. Can anyone tell me what I'm missing?
Not sure. Norm Walsh (ndw@nwalsh.com) is your best bet.
> [snip]
>
> >If you want to include that information, you normally include "-ifoo" on
> >the command line of your SGML tools, otherwise they'll ignore it (the
> >default).
> >
> >That's a simplistic approach (in reality you'll probably have a number of
> >entities relating to this printing of the Handbook, turned on or off with
> >one other entity) but that's the basic idea.
>
> How would you handle style sheets with this approach? Lump it all into
> freebsd.dsl or create a wcprint (or some such) version of the modular
> stylesheets?
>
> I agree with Greg. I think a number of things need redoing for
> publication. The default format, as it exists now, is not economical,
> doesn't fit with the style WC has established and would add several
> needless signatures. What WC needs though, wouldn't work very well for
> a pdf or html version. So I think a distinction needs to be made
> between WC's print format and the default. How should the style sheets
> be handled if that distinction is made?
First and foremost, I'm firmly of the opinion that the Doc. Proj. supported
stylesheets should be most useful to the end-user. This means they need to
make it easy for the end-user to get (print) output in USLetter or A4 size
quickly and simply, without needing to make a huge number of changes. If
they can also produce the WC version then that's a bonus.
As we all know, the beauty of the DocBook approach is that the appearance
can be changed, just by changing the stylesheet. You don't need to change
the content at all[1].
At this point, I don't know if Norm Walsh's modular stylesheets are
sufficiently flexible to do everything that would be required for a WC
print of the handbook. This is mostly because I haven't seen anything like
a list of requirements.
I think it's likely that as they stand now, Norm's stylesheets are probably
not suitable. I don't *know* this, I'm just making an assumption. Someone
has to actually try and use them to typeset the book first.
Assuming that they're not suitable, we can do one of two things;
1. Work with Norm to add features we need.
2. Write wc-docbook.dsl which formats DocBook according to WC's style.
I don't know how feasible either of these approaches are. Approach 1 is
the simplest, but I don't know busy Norm is at the moment. I do know that
he's been willing to incorporate changes to the sheet based on my requests
over the last year.
Approach 2 requires someone who knows DSSSL. I don't. What it doesn't
require is anyone currently on -doc to do any work. WC could go out and
hire someone who doesn't even need to see the Handbook (they could just
work from the DocBook DTD) to write it.
[ As an aside -- The LinuxDoc people are also migrating to DocBook, so
it might be in WC's interest to create wc-docbook.dsl anyway, so they
can print lots of the Linux stuff as well ]
I think it's probably a good idea if anyone else interested in this
subscribes to the main DocBook mailing list, davenport@berkshire.net.
I'm pretty certain that "Mechanisms to print books from DocBook source"
is on topic for the list. You'll also get responses from people far
more qualified to talk about this than I am.
N
[1] Almost completely true. You might need to add additional information,
so that the stylesheets can make more intelligent decisions, but you
don't add additional markup that changes the semantics.
So changing "<programlisting>" to "<programlisting width="64">" is OK,
but "<programlisting>" to "<blockquote><programlisting>" is not.
--
--+==[ Systems Administrator, Year 2000 Test Lab, Lehman Brothers, Inc. ]==+--
--+==[ 1 Broadgate, London, EC2M 7HA 0171-601-0011 x5514 ]==+--
--+==[ Year 2000 Testing: It's about time. . . ]==+--
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?19990413111750.F14492>