Re: Debian Reference
On Sat, Sep 24, 2005 at 01:07:48PM +0900, Osamu Aoki wrote:
> On Wed, Sep 21, 2005 at 12:08:35AM +0100, Antony Gelberg wrote:
> > General:
> > Don't use the word Debian where it's redundant.
Fine. But this implementation may require whole rewrite. --> Low priority.
> > Remove historical points, or move to appendix, too confusing.
Fine. But this implementation may require whole rewrite.
For desription which does not apply on sarge --> high priority
For description which is just not use much anymore --> low priority
> > Highlight need to know / don't need to know.
Fine. But this implementation may require whole rewrite.
> > Some things too wordy, some too concise. If a word isnt needed, get it out.
Fine. But this implementation may require whole rewrite.
> > Order should be order of use e.g. fundamentals, install, the boot
> > process, etc.
This implementation will require whole rewrite.
Besides, I think we need to redefine scope.
install thingy --> release note / install guide
random bug work around note --> now we should move to wiki.debian.org
Pre-requirement: basic Linux/Unix skill
Scope of document: post-installation guide for 2.6 kernel linux system
Outline:
* Preface
- Define terminology and provide pointers to pre-readings
-
* Debian package system overview
- basic idea of debian package
- archive design
stable/testing/unstable difference
* Installation and upgrade of Debian (short text with pointer)
- Limit contents to minimum
* Tutorial
- basic unix command line shell guide
- guide with mc
* Package manupilation commands
(Do not recommend mixed distribution system)
- Basic tools (explain positioning and layered structures)
- tasksel
- dpkg
- dselect (state this is depracated)
- apt-get/apt-cache (state this use needs to be limited)
- aptitude (preferred)
- synaptic
- Extra tools
- apt pinning
- apt-get source
- apt-get build-deps
- auto-apt, ...
- fancy dependency tools
* Basic system management
- Kernel / module / udev configuration
- Network configuration
-
* Backup methods (with CD/DVD)
* Emergency recovery methods
* Application guide
Hmmm... this will be too much. Let's see what you said first.
> > I know Woody is still supported, but move to appendix?
I would say that keep minimumalist update to current documentation for
extreme bug fix and start new XML based document with graphs and tables.
> > 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....)
I think that making these extensive changes are still not good enough.
So why creates too much work. I think we need to work totally rebumped
text. For that, your thoughts are very good base for next version. But
we need to make a new XML version.
> > > 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.
I still think bug fix release is good thing.
Are you familiar with multi lingual XML document project management? I
am not. I am liiking at current installation guide as the good guide.
Reply to: