Date: Tue, 17 Mar 1998 09:31:37 +0000 From: nik@iii.co.uk To: Studded <Studded@dal.net> Cc: doc@FreeBSD.ORG, "Jordan K. Hubbard" <jkh@time.cdrom.com> Subject: Re: Documentation plan - handbook, etc. Message-ID: <19980317093137.48803@iii.co.uk> In-Reply-To: <350E3B8A.F440FBD0@dal.net>; from Studded on Tue, Mar 17, 1998 at 12:59:54AM -0800 References: <350CF5E6.5DD147F5@dal.net> <7061.890049804@time.cdrom.com> <19980316153125.64380@iii.co.uk> <350E3B8A.F440FBD0@dal.net>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, Mar 17, 1998 at 12:59:54AM -0800, Studded wrote:
> nik@iii.co.uk wrote:
> > There's about to be a considerable amount of time and effort invested
> > in migrating the Handbook from the LinuxDoc DTD to the DocBook DTD, and
> > a large chunk of work has already gone into making sure that this can
> > be done without affecting the current content.
>
> Ok, so am I to understand that the work hasn't actually commenced?
Yes and no.
- I have the tools.
- I've done several tests with the whole handbook.
- I've written up the plan for how the conversion will be handled, and
solicited comment about it on the -doc mailing list.
- I've talked with (and am talking with) some of the people who do the
translations of the Handbook, to make sure that the conversion will not
cause them undue problems.
- I'm sorting out some final wrinkles with regard to the TeX conversion.
About the only thing that's causing me grief at the moment is the TeX
conversion. Once I get that sorted (which will hopefully be a couple of
days) then I'll do the conversion and the commits it requires. I imagine
I'll be doing that this weekend.
> There was considerable discussion about the direction the docs should
> take on -questions less than a week ago and I never saw any firm
> statements regarding "This is what we will do," so I thought the debate
> was still open to be framed.
Probably because I (and others) missed it. I tend to skim -questions,
only looking for 'make world' related stuff. Also, if the discussion
happened over a weekend I won't see it until Monday.
> > Go to your favourite list archive and read back through it for the past
> > month or 2 (alternatively, mail me at nik@nothing-going-on.demon.co.uk and
> > I'll forward you my own archives).
>
> I tried the archive at the www site and TMK there's no way to search
> specifying dates. I tried "february and 1998" but only got a few
> letters, none of which applied to the topic at hand.
I'll forward you the appropriate messages. It may take me a couple of days
to find them all.
> > Probably the best thing to do would be for you to go through the existing
> > content in the Handbook (at a fairly high level) and see if the ordering
> > of the chapters can be improved, or whether or not you think some of the
> > information should be pulled out and made into its own section (or subsumed
> > into another, or whatever).
>
> Actually the *first* question that needs to be answered is what do we
> want to end up with. You can't make a good plan without a goal in mind.
> What was the consensus as to what the end product should be?
"Better than the current one". I don't recall there being a firm consensus,
except that "Something should be done."
I believe it's recognised that some of the content needs reordering, some
of the sections could be merged, some of the tutorials should be pulled
into the main body of the Handbook, and so on.
However, to the best of my knowledge, no one's (recently) read the Handbook
cover to cover and come back to the list saying "Here's a report of all
the things I noticed with the Handbook that are inconsistent, wrong, or
just don't feel quite right. This is how I think we fix them."
> 1. What are the benefits of docbook vs. linuxbook? (Other than getting
> "linux" out of our stuff, which I'm all for. :)
It's got nothing to do with the name.
DocBook is a much more expressive DTD, allowing you to markup things up
more precisely. This makes properly marked up content more useful.
For an example of DocBook markup, go to
<URL:http://www.nothing-going-on.demon.co.uk/FreeBSD/>;
and follow the SGML links.
> 2. Will the final product allow the user to generate docs in multiple
> formats? The ones I'm most intersted in are http, pdf, ps and straight
> text.
Yes. Off the top of my head the conversion process will allow HTML, PDF,
PS, plain ASCII and RTF. Right *now*, I don't fully understand the method
necessary to turn DocBook mark up into TeX. Once it's in TeX it can then
be converted to PS and PDF (via DVI).
> 3. What came of the discussion on making the final product easily
> printable by the user? I really think that this would increase the
> value of the final product tremendously.
I followed the discussion and fully agree with it.
> I think that if you're serious about moving it into a new format the
> best bet would be to make concrete plans on the final format and kill
> all the birds with one shotgun blast. :)
I have done. I'll find the appropriate message and forward it to you.
> Finally, where can I get good info on sgml? I have the stuff installed
> and I've built the docs on my machine but the man page is a bit thin.
<URL:http://www.sil.org/sgml/sgml.html>;
is the SGML/XML page, which covers the entirety of SGML.
<URL:http://www.oreilly.com/davenport/>;
is the page for the Davenport group, who maintain the DocBook DTD.
<URL:http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html>;
is an introduction to DocBook.
<URL:http://fallout.campusview.indiana.edu/~jfieber/docbook/>;
is John Fieber's page of DocBook information, resources and examples.
N
--
Work: nik@iii.co.uk | FreeBSD + Perl + Apache
Rest: nik@nothing-going-on.demon.co.uk | Remind me again why we need
Play: nik@freebsd.org | Microsoft?
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?19980317093137.48803>