Re: Debian Reference
Osamu Aoki wrote:
> On Sun, Sep 18, 2005 at 04:20:32AM +0100, Antony Gelberg wrote:
>>I'll start with a patch for Chapter 2 to
>>see if we are on the same wavelength. We need to restructure it before
>>we can improve the content.
>
>
> Chapter 2 shares a lot with FAQ in terms of contents. Javi is updating
> it. See mailing list for the details and be aware of it.
>
> This chapter describes a lot of old things which is useful for few
> extreme case. To update it, you need to be very familiar with how
> Debian works and worked. I think you may need a bit more time for that.
> So for now, I strongly limit patch to factual errors.
Fine. I had made some notes before I read your reply, which I'll paste
here for your and Javi's perusal.
General:
Don't use the word Debian where it's redundant.
Remove historical points, or move to appendix, too confusing.
Highlight need to know / don't need to know.
Some things too wordy, some too concise. If a word isnt needed, get it out.
Order should be order of use e.g. fundamentals, install, the boot
process, etc.
I know Woody is still supported, but move to appendix?
1.5 move to 2.1.2
Point out at start of 2, that the Distribution is made up of Packages
and that there are actually several distributions.
2.1 rename to Distribution.
2.1.1,10,14,15 move to new subtopic, 2.1.3, Directory layout. Point out
that this is for advanced users, and apt handles all.
2.1.3-6 move to subtopic of new 2.1.1, Flavours.
2.1.7-9 move to new 2.1.2, Flavour Naming.
2.1.11 remove.
2.1.12 move to where unstable is described. incoming not a distro,
perhaps better explained in 2.2.
2.1.13 move to 2.2.
2.2 rename to Packages. We talk about package internals too soon.
Should be more top-down. Start explaining how to search packages. Then
how to install and remove.
2.2.1 rename to overview, but can stay.
2.2.2 Searching, Installing and removing (when talk about how it knows
what to pull in, refer to Package dependencies). Chapter 6!
2.2.2,5-10 move to new 2.2.3, All about .deb. Emphasizekeywords e.g.
Depends.
2.2.4,11 move to upgrade section
2.2.13 remove? Kind of covered in NMG. If stays, move to new 2.2.4,
Building from source and change first bit to apt-get source.
2.2.14 move to new 2.2.4, Building from source.
2.3 One upgrade section is enough. Filter into chapter 6.
2.4 Can't talk about boot before install.
2.5 Not really a fundamental. Filter into relevant sections and delete
this one.
2.6 This relates to 2.1, perhaps make 2.1.4 or refer to at start of 2.1.
Could also be incorporated into a What Debian Offers / Why Debian in
bullet points. We have About Debian on the www, which is severely limited.
2.7 One kernel section is enough. Filter into chapter 7.
>
> Instead, I suggest you to do bug hunting and issue hunting on chapters
> and thinking how all other needs to be reorganized and how that will be
> achieved:
>
> 3. installation hint.
> - how this can be reorganized without duplicating install masnual.
> 5. Upgrading distribution
> - how can this be made distribution independent
> - avoid overlap with installation and release note.
> 6. Package management
> - Now that aptitude is main tool, we need to carefully update this.
> - Remove all woody/potato things.
> 7. Kernel
> - Rewite this focusing udev/2.6 management (But who knows best?)
> 8. Tips
> - New installation CD is not easy tool for emergency recover.
> Suggest bootable CD alternative
> - im-switch
> - UTF-8
>
> Oh, please read some basics of contributing document at:
>
> http://qref.sourceforge.net/doc/
I'll have a think about the above list and draw up some conclusions this
weekend. Shall we take this to debian-doc or private email from now, r
leave it here?
Reply to: