Merging the FAQ -> handbook, build time options, proof ofconcept patch

[Tom Rhodes]

On Thu, 2 Dec 2004 19:33:00 -0600 (CST)
Mark Linimon <linimon at lonesome.com> wrote:

> I'm running very short of cycles at the moment so the following is
> pretty rough ...
> 
> Here's my idea for what the FAQ ought to look like once a) the various
> things that Tom is talking about are moved and b) a few more things
> become standalone Articles (e.g. the really nice PPP writeup -- it's
> great, but having it in the middle of the FAQ means that it 1) gets
> buried and 2) makes the FAQ too long for anyone but the most dedicated
> FreeBSD fanatic to make it through).

Ok, so this isn't a "no" vote on my idea, just a "the bigger and
better parts which can can be made into articles or real FAQ should
be handled as such.

I like that except for the fact that we'll have yet another
FAQ which, hopefully, will not become the mess it is.

How about this, we can probably put marked up faq specific
parts into separate files within the chapter directories.  Then,
when building the handbook, either:

'make WITH_FAQ=yes' builds the faq into the handbook;
make WITH_SEPARATE_FAQ=yes builds the FAQ outside the handbook;
'make' just builds the handbook.

This is a LOT of work that would go into that, but I'm sure we/I
can manage; however, if you're thinking of:

Tom moves FAQ entries into handbook with his patch,
Mark + others kill FAQ entries which do not apply to 4, 5 or 6.
The FAQ is reborn and the handbook has mini-FAQ parts for more info.

Then we have another problem.  We still have both the handbook
and FAQ.  My original intention was to move the FAQ items into
the handbook to:

Remove cruft;
get more exposure to the information;
limit what versions we support;
place large amounts of quick and easy q&a parts in relevant chapters.

This still gives us a FAQ, just a better one, I think, which
could be kept more up to date.

> 
> It's still too long by about 2x but it's a damned sight closer.  Most
> of the duplicated material is removed.  All the "what is it/where is
> it/how do I get it" material remains.  Some of the "why is it the way
> it is" information remains but it needs to be reshuffled.
> 
> The Table Of Contents probably ought to be more like
> 
> 1 Introduction 
> 2 Documentation and Support 
> 3 Hardware compatibility 
> 3.1 Architectures and processors 
> 3.2 Peripherals and add-on cards 
> 4 Installation 
> 5 Troubleshooting 
> 6 System Configuration and Administration [fold in Networking, Security]
> 7 Commercial Applications 
> 8 User Applications 
> 9 The X Window System and Virtual Consoles 
> 10 Miscellaneous Questions 
> 11 The FreeBSD Funnies 
> 12 Advanced Topics 
> 13 Acknowledgments 
> Bibliography 
> 
> The prototype is at 
> http://www.lonesome.com/FreeBSD_doc/en_US.ISO8859-1/books/faq/index.html.

This is interesting, I see many of these parts which can be
moved into chapters and other items which would be better as
stand alone.  Oh well, I'll await more comments on what I have
brought to the table.

-- 
Tom Rhodes