Re: The Debian Way
>>>Mark Small wrote:
>
> Okay, here is my version of the debian way. It is probably full of
> mistakes and stuff, since most of it was written while sitting at my
> win95 box (GASP!). I don't plan on doing anymore work on it, so do with
> it what you will. I GPL'ed it.
Great! That's a start. I would like to contribute.
Just some questions before I start:
o I added some notes to the original version.
Please let me know if it's easier for you
to convert my comments into prober English or if you prefer to
later correct my (bad) English writing. If my help is useless
don't hesitate to let me know.
o Because that's my first try with SGML could some one write a
a recipe how to work with it and translate.
I can figure it out myself and will summerize it then later.
but if someone feels like to fill out the '...' below ... :)
Here's a skeleton. This are the thinks that stopped me from
adding the doc right now and posting it. Nothing checked so
it may be plain wrong!
(IMHO something like that should go into as an appendix of
this (or all?) DDP docs as an appendix to reduce the threshhold
for possible contributions.
--snip--
If you find error or want to add something to this or another DDP document:
Simplest way for you is
cp /usr/share/doc/<package>/<document> <document>.orig
cp <document>.orig <docment>
Add your changes to <document> and send it to the DDP
diff -u <document>.orig <document> | \
mailx -s "<document> corrections" debian-doc@lists.debian.org
??Or should such stuff be send to the BTS??
If you plan to contribute more or it's better to get the
latest copy (maybe it's already fixed?) of a document
cvs .... <document>
edit the SGML document and translate it (point to Stephanes HOWTO)
... Stephanes howto should know it ...
When you are satisfied, send the changes to the DDP Project:
cvsup diff -u <document>.smgl | \
mailx -s "<document> changes" debian-doc@lists.debian.org
Thanks for contributing.
--snap--
>
> I tried adding docbook markup as Stephane suggested, but I haven't had a
> chance to test it. I fully expect any parser to choke on it.
>
> Here ya go:
Below some remarks. As I said let me know if I should formulate them
or ... or ...
> <?xml version="1.0" encoding="utf-8"?>
>
> <!DOCTYPE article PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1//EN"
> "dtd/docbook-xml/docbookx.dtd"[
>
> <!-- New elements -->
>
> <!-- The contents of the debianpackage element is the official name -->
> <!-- The name attribute holds the Debian name, if it's different -->
> <!ELEMENT debianpackage (#PCDATA)>
> <!ATTLIST debianpackage name CDATA #IMPLIED>
> <!ATTLIST debianpackage refserver CDATA #IMPLIED>
> <!ENTITY % local.title.char.mix
> "|debianpackage">
>
> <!ELEMENT debiandoc (#PCDATA)>
> <!ATTLIST debiandoc file CDATA #IMPLIED>
> <!ATTLIST debiandoc text CDATA #IMPLIED>
> <!ENTITY % local.para.char.mix
> "|debiandoc|debianpackage">
>
> <!ELEMENT manpage (#PCDATA)>
>
> <!-- New attributes -->
> <!ENTITY % local.common.attrib
> "debianversionequal CDATA #IMPLIED
> debianversionmin CDATA #IMPLIED
> debianversionmax CDATA #IMPLIED">
>
>
>
> ]>
>
> <article>
> <artheader>
> <title>The Debian Way</title>
> <author>
> <firstname>Mark</firstname>
> <surname>Small</surname>
> </author>
>
> <legalnotice>
> <para>This text is distributed according to the <ulink
> url="http://www.gnu.org/copyleft/gpl.html";>General
> Public License</ulink>.</para>.
Add: Debian has a copy on /usr/share/common-licenses/GPL
No need to connect to the Internet :)
> </legalnotice>
> </artheader>
>
> <sect1>
> <title>About this document</title>
> <para>General infomation about this document</para>
> <sect2>
> <title>Disclaimer</title>
> <para>
> I am not a professional admin. I only have experience
> with one unix/unix-like system: the Debian box in my home. I
> make no claims to the accuracy/safety of this document. Use at
> your own risk.
> </para>
> </sect2>
> <sect2>
> <title>Overview</title>
> <para>
> The purpose of this document is to give a short list of features
> specific to the Debian Gnu/Linux system. After 2 years
> experience with debian I decided that there is a gap in the
> documentation available. Many admins coming from other
> distributions do not know all of the features of debian. Also,
> much of the documnetation out there already is specific to
> another distribution. Here I give a short summary of debian
> features. They should serve as a jumping off point, they'll
> help you know which man pages/docs to look at.
> </para>
> <para>
> This document assumes that you are familiar with unix-like
> systems in general (or are not intimidated).
> </para>
> </sect2>
> </sect1>
> <sect1>
> <title>Features</title>
At the top should be IMHO 2 other thinks
1) Debian special stuff has often their own abbreviations. NMU, ITP, ...
Refer to Joey(??) glossary
2) something about the file system standard. Just some hints like:
Debian conforms the FS???. This mean that you can be sure to always find
in
/etc the configuration files
/usr/share/doc additional information beside man and info pages
/var/log the log files
> <sect2>
> <title>Admin stuff</title>
> <para>
> DPKG handles much of the setup necessary in getting your Debian
> system running. It controls most of your directory tree. If
> you want do stuff outside of DPKG, do it under /usr/local/. All
Add /home
> configuration files are under /etc/. If you find yourself
> playing with files outside of these directories, you may be in
> for a spot of bother later on.
> </para>
> </sect2>
> <sect2>
> <title>Users and groups</title>
> <para>
> By default, every user is in a group by the same name.
Add: Redhat and Suse describe the why and advantages in their installation
books. Add a URL to them. (is it explain also in a debian doc?)
Add: adduser to create new user account versus useradd to manipulate
passwd
Add: Predefined debian group, e.g., floppy, audio, ... to access devices
> </para>
> </sect2>
> <sect2>
> <title>The debian menu system</title>
> <para>
> Debian provides a centralized system for managing the application
> menus that appear in most window managers/desktop environments.
> Most packages contain menu entries that are installed under
> /usr/lib/menu. Don't mess with these files. They will be
> overwritten whenever you upgrade. You can customize these menus
> (system wide) by putting revised/new files under /etc/menu.
Same for add new menu entries
> Users can do their own customizations under ~/.menu/.
> After creating/editing the menu files, run update-menu.
> See /usr(/share)/doc/menu for more information.
DOCBook gurus: what's the markup for manual pages and file. Just
for cut and past :) Would be a pity if they are no Hyperlink later
in HTML output.
> </para>
> </sect2>
> <sect2>
> <title>Apt</title>
Better? use "Installing Software".
> <para>
> Apt is the next generation tool for installing packages on your
> debian system. It allows installation from many sources
> including multiple cdroms. See man apt-cdrom, man sources.list,
> man apt for more info.
> </para>
> <para>
> Lots of people are always willing to write about apt, I'll
> leave details up to them.
Should only mention apt-get and dselect. Refer to FAQ for more details.
Add section about bug reports. Also refer to web access and reportbug tool
> </para>
> </sect2>
> <sect2>
> <title>/etc/alternatives</title>
> <para>
> I don't know enough about this yet to write anything intelligent.
By example, e.g., more/less/most. More details are in FAQ AFAIR.
> </para>
> </sect2>
> <sect2>
> <title>runlevels</title>
"Boot sequence and the runlevels"
> <para>
> Some distributions specify that runlevels 2-6 have specific uses.
> (X, net, etc) Debian does NOT. Customize them as you please.
> The runlevels are controlled by scripts in /etc/rcX.d/ where X is
> the runlevel. These scripts are symlinks to scripts in
> /etc/init.d/.
> Have a look at man update-rc for a good way of managing your
> runlevels.
> </para>
> </sect2>
> <sect2>
> <title>daemons</title>
> <para>
> Sometimes after you reconfigure a daemon, it is necessary to
> restart it in order for the change to take effect. To do this
> type: /etc/init.d/[daemon name] restart. All of the init scripts
> can handle the following commands: start, stop, reload, restart
> (one of these is optional, isn't it?)
> </para>
> </sect2>
> <sect2>
> <title>update-modules</title>
> <para>
> I'll have to check the man page on this one since I have no idea
> what it really is.
Mhmm, I think this should go into it's own section, explaining the debian
solution for 'several packages want to add to one config file':
/etc/modules.conf -> update-modules
/usr/X11R6/lib/X11/fonts/<xxx>/fonts.dir -> update-alias
/etc/mailcap -> update-mime
More?
> </para>
> </sect2>
> <sect2>
> <title>kernel compilation</title>
> <para>
> There is a nice way to compile your kernel under debian. It is
> a package called make-kpkg. It automates a lot of the steps.
> After you are done, if you use loadlin (like me), you will need
> to copy the new kernel image from /boot/vmlinuz-(ver) to your
> dos partition.
> </para>
Add: Package compilation:
apt-get source
#change what you need to change
... build it. how??
# test it
# submit a bug report, so chances find their way upstream
> </sect2>
> <sect2>
> <title>Hardware access</title>
> <para>
> See the debian faq, but in short, you'll have to add users to
> the dip group to let them use ppp, and add them to the audio
> group to let them use sound.
'user and groups' above should point to this.
> </para>
> </sect2>
> <sect2>
> <title>X</title>
> <para>
> ~/.xsession is where config stuff goes if you are using XDM.
> Most debian boxes default to using XDM for X. See the man page.
special is that .xinitrc and .xsession is treated the same. So forget
.xinitrc on Debian, right?
Missing: How to select another window manager, when using startx
(display managers offer a menu to select the window/session manager.
That's the reason why I don't know how to do it :)
> </para>
> </sect2>
> </sect1>
> </article>
Let me know what you think and I will try to find some time over the
weekend.
Achim
--
To me vi is Zen. To use vi is to practice zen. Every command is
a koan. Profound to the user, unintelligible to the uninitiated.
You discover truth everytime you use it.
-- reddy@lion.austin.ibm.com
Reply to: