Re: Debian Reference
On Wed, Sep 21, 2005 at 12:08:35AM +0100, Antony Gelberg wrote:
> 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.
Good points. But when I consider practical aspects of all the
secondary works, I really can not do these now. (Translation....)
> > 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?
Yes. debian-doc please.
Reply to: