Re: Debian Reference
Osamu Aoki wrote:
> 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.
Would you mind if I investigate creation of a new XML version, that we
can work on in parallel with the existing version? I will also look at
how the install guide is managed. I can start to refactor the
Reference, and you / Javi / whomever can filter in changes as and when
ready. I would of course appreciate your input throughout, as I don't
want to go too far down the wrong road.
Reply to: