Date: Wed, 11 Mar 1998 15:25:40 +0000 From: nik@iii.co.uk To: Jeremy Lea <reg@shale.csir.co.za> Cc: alexandr@hawk.pearson.udel.edu, Annelise Anderson <andrsn@andrsn.stanford.edu>, freebsd-doc@FreeBSD.ORG Subject: Re: ps2pdf (was: newbies mailing list) Message-ID: <19980311152540.43318@iii.co.uk> In-Reply-To: <19980311170823.64512@shale.csir.co.za>; from Jeremy Lea on Wed, Mar 11, 1998 at 05:08:23PM %2B0200 References: <199803052049.PAA00460@hawk.pearson.udel.edu.> <19980305215748.36179@iii.co.uk> <19980311170823.64512@shale.csir.co.za>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, Mar 11, 1998 at 05:08:23PM +0200, Jeremy Lea wrote:
> On Thu, Mar 05, 1998 at 09:57:48PM +0000, nik@iii.co.uk wrote:
> > In the pipeline. When we've got the translation to DocBook sorted out
> > (which hopefully won't be too far away) it's a (relatively) trivial
> > matter to turn the documentation into a multitude of formats.
> >
> > Watch this space.
>
> Is there going to be any reorganisation of the FAQ and Handbook while this
> transition is in progress?
Short answer:
The physical organisation will probably change slightly (i.e., the location
of the SGML files in the filesystem might move about a bit).
However, for the *immediate* term, the content will stay the same.
> It would seem like the right time to me to start
> messing with the ordering while your changing all the codes and making big
> diffs.
It's actually the wrong time. This is largely to keep things as simple as
possible for the guys doing the Japanese translation of the Handbook
(I'm thinking about the DocBook transformation for the FAQ, but my ideas
there are sketchy at best at the moment, I haven't written them down properly).
Basically, any commits to the handbook/FAQ should either be markup changes
or content changes. But not both in the same commit.
> I printed out the FAQ a while back in the hope of getting down to doing a
> technical/language edit of it (because its smaller than the handbook :), but
> I found that I kept wanting to move chapters around. Is there any published
> statement of purpose for the two documents? What makes them different, what
> should they cover, etc. I would think that the handbook would be a fairly
> static document (excepting big changes in the system :), and the FAQ would
> cover the day to day issues like which hardware is supported/recommended,
> and such things, but it almost seems to be the other way around. I remember
> something from Jordan a while back saying that the handbook was the place
> for activity?
AFAIK, there isn't. Peter da Silva appears to have dropped off the face
of the planet (apologies if you are reading this Peter, but you haven't
responded to any of my e-mails over the past month or so).
> Also, both the FAQ and handbook have statements to the effect that they are
> only for the latest release version and then volumes of text which applies
> to all releases and to current.
True. This is something I'm thinking of addressing at the SGML level, where
content is tagged (or marked, more likely) as being either specific to a
particular set of FreeBSD versions, or version independent. This would
then allow the creation of Handbooks/FAQs that just contain the information
for a particular version of FreeBSD.
The precise implementation of this mechanism is not something I've settled
on yet (in fact, I don't think I've mentioned it here yet, because at the
moment it's just something I'm kicking around at the back of my mind).
> I personally would think that any question which lasts over 6 months in the
> FAQ is stale and should be properly documented somewhere else.
Disagree. It might be there because it is frequently asked. However, I
don't doubt that some of the FAQ answers should probably consist of
This question is answered in section 'x' of the FreeBSD handbook.
with appropriate links.
> In a month or so I should have enough time to get back into the editing
> process. Do you think that the docbook transition will be done by then?
> because I'd rather not do the work twice...
I hope it will be. Right now I'm just waiting for someone from the Japanese
team to get back to me about some issues regarding the DocBook conversion.
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?19980311152540.43318>