Date: Wed, 18 Mar 1998 10:02:40 +0000 From: nik@iii.co.uk To: Studded <Studded@dal.net> Cc: Docs Team <FreeBSD-Doc@FreeBSD.ORG> Subject: Re: docbook conversion Message-ID: <19980318100240.53276@iii.co.uk> In-Reply-To: <350EEE0C.792C3D57@dal.net>; from Studded on Tue, Mar 17, 1998 at 01:41:32PM -0800 References: <350EEE0C.792C3D57@dal.net>
index | next in thread | previous in thread | raw e-mail
On Tue, Mar 17, 1998 at 01:41:32PM -0800, Studded wrote:
> Assuming that we want the final product of the doc overhaul
> to be in docbook format
I think we can safely say that that's been decided upon.
> If I understand the thing correctly, it will be easier to cut
> and paste the bits we have into the final format if they are already in
> docbook, yes?
In theory, yes. However, at the moment DocBook and LinuxDoc can't coexist
in the Handbook. If you have submissions to make to the Handbook *now* then
they should be in LinuxDoc.
I don't know how long the conversion process will take to complete, and I
don't want to be a barrier to people who have updates they want to submit
now.
> Also, are plans being laid to convert the rest of the
> docs on the www site too, like the FAQ and tutorials? Or will this be
> fairly simple once we've got a method down for the handbook?
The FAQ should be a natural extension of the Handbook, albeit with a few
more bits of FAQ specific markup. This might be as simple as marking
things up as:
<para role="question">How do I do X?</para>
<para role="answer">Do this, then do that, then do the other.</para>
Or it might get more involved and involve extending DocBook to something
like
<question>
<para>How do I do X?</para>
</question>
<answer>
<para>Do this, then do that, then do the other.</para>
</answer>
The first example can be mechanically converted to the second relatively
simply, so the precise turn this takes isn't important (yet).
As for the tutorials, in an ideal world they'll be converted as well. Of
course, the final call on this is up to the authors of the tutorials.
One of the things this will (should?) depend on is 2 style guides, one for
authors and one for the people doing the markup (some of the time this
will be the same person).
I've started thinking about the markup style guide. Basically, this will
(initially) consist of a series of Q and A explaining which markup should
be used for which type of content.
> Do we really want to make this change before 2.2.6 goes out?
I see no way in which the migration will happen before 2.2.6 goes out.
This is a non-issue.
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
help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19980318100240.53276>