Import changeset

Documentation/00-INDEX

+This is a brief list of all the files in ./linux/Documentation and what
+they contain. If you add a documentation file, please list it here in 
+alphabetical order as well, or risk being hunted down like a rabid dog. 
+Note that subdirectories have their own index files too. Please try and
+keep the descriptions small enough to fit on one line.
+							 Thanks -- Paul G.
+
+00-INDEX
+	- this file.
+BUG-HUNTING
+	- brute force method of doing binary search of patches to find bug.
+Changes
+	- list of changes that break older software packages.
+CodingStyle
+	- how the boss likes the C code in the kernel to look.
+Configure.help
+	- text file that is used for help when you run "make config"
+IO-APIC.txt
+	- info on using the enhanced interrupt hardware on SMP boards.
+IO-mapping.txt
+	- how to access I/O mapped memory from within device drivers.
+README.DAC960
+	- info on Mylex DAC960/DAC1100 PCI RAID Controller Driver for Linux
+VGA-softcursor.txt
+	- how to change your VGA cursor from a blinking underscore.
+arm/
+	- directory with info about Linux on the ARM architecture.
+atm.txt
+	- info on Linux ATM support
+binfmt_misc.txt
+	- info on the kernel support for extra binary formats.
+cdrom/
+	- directory with information on the CD-ROM drivers that Linux has.
+computone.txt
+	- info on Computone Intelliport II/Plus Multiport Serial Driver
+cpqarray.txt
+	- info on using Compaq's SMART2 Intelligent Disk Array Controllers.
+devices.tex
+	- LaTeX source listing of all the nodes in /dev/ with major minor #'s
+devices.txt
+	- plain ASCII listing of all the nodes in /dev/ with major minor #'s
+digiboard.txt
+	- info on the Digiboard PC/X{i,e,eve} multiport boards.
+digiepca.txt
+	- info on Digi Intl. {PC,PCI,EISA}Xx and Xem series cards.
+dnotify.txt
+	- info about directory notification in Linux.
+exception.txt
+	- how Linux v2.2 handles exceptions without verify_area etc.
+fb/
+	- directory with info on the frame buffer graphics abstraction layer.
+filesystems/
+	- directory with info on the various filesystems that Linux supports.
+ftape.txt
+	- notes about the floppy tape device driver
+hayes-esp.txt
+	- info on using the Hayes ESP serial driver.
+i386/
+	- directory with info about Linux on the intel ix86 architecture.
+ide.txt
+	- important info for users of ATA devices (IDE/EIDE disks and CD-ROMS)
+initrd.txt
+	- how to use the RAM disk as an initial/temporary root filesystem.
+ioctl-number.txt
+	- how to implement and register device/driver ioctl calls.
+isapnp.txt
+	- info on Linux ISA Plug & Play support
+isdn/
+	- directory with info on the Linux ISDN support, and supported cards.
+java.txt
+	- info on the in-kernel binary support for Java(tm)
+joystick-api.txt
+	- API specification for applications that will be using the joystick.
+joystick-parport.txt 
+	- info on how to hook joysticks/gamepads to the parallel port.
+joystick.txt
+	- info on using joystick devices (and driver) with Linux.
+kbuild/
+	- directory with info about the kernel build process
+kernel-docs.txt
+	- listing of various WWW + books that document kernel internals.
+kernel-parameters.txt
+	- summary listing of command line / boot prompt args for the kernel.
+kmod.txt
+	- info on the kernel module loader/unloader (kerneld replacement).
+locks.txt
+	- info on file locking implementations, flock() vs. fcntl(), etc.
+logo.gif
+	- Full colour GIF image of Linux logo (penguin)
+logo.txt
+	- Info on creator of above logo & site to get additional images from.
+m68k/
+	- directory with info about Linux on Motorola 68k architecture.
+magic-number.txt
+	- list of magic numbers used to mark/protect kernel data structures.
+mandatory.txt
+	- info on the Linux implementation of Sys V mandatory file locking.
+mca.txt
+	- info on supporting Micro Channel Architecture (e.g. PS/2) systems.
+md.txt
+	- info on boot arguments for the multiple devices driver
+memory.txt
+	- info on typical Linux memory problems.
+mkdev.ida
+	- script to make /dev entries for Intelligent Disk Array Controllers.
+modules.txt
+	- short guide on how to make kernel parts into loadable modules
+mtrr.txt
+	- how to use PPro Memory Type Range Registers to increase performance
+nbd.txt
+	- info on a TCP implementation of a network block device.
+networking/
+	- directory with info on various aspects of networking with Linux.
+nfsroot.txt
+	- short guide on setting up a diskless box with NFS root filesystem
+nmi_watchdog.txt
+	- info on NMI watchdog for SMP systems
+oops-tracing.txt
+	- how to decode those nasty internal kernel error dump messages.
+paride.txt
+	- information about the parallel port IDE subsystem.
+parport.txt
+	- how to use the parallel-port driver.
+pci.txt
+	- info on the PCI subsystem for device driver authors
+pcwd-watchdog.txt
+	- info and sample code for using with the PC Watchdog reset card.
+pm.txt
+	- info on Linux power management support
+powerpc/
+	- directory with info on using Linux with the PowerPC.
+proc_usb_info.txt
+	- info on /proc/bus/usb direcory generated for USB devices
+ramdisk.txt
+	- short guide on how to set up and use the RAM disk.
+riscom8.txt
+	- notes on using the RISCom/8 multi-port serial driver.
+rtc.txt
+	- notes on how to use the Real Time Clock (aka CMOS clock) driver.
+scsi-generic.txt
+	- info on the sg driver for generic (non-disk/CD/tape) SCSI devices.
+scsi.txt
+	- short blurb on using SCSI support as a module.
+serial-console.txt
+	- how to set up Linux with a serial line console as the default.
+sgi-visws.txt
+	- short blurb on the SGI Visual Workstations.
+smart-config.txt
+	- description of the Smart Config makefile feature.
+smp.tex
+	- LaTeX document describing implementation of Multiprocessor Linux
+smp.txt
+	- a few more notes on symmetric multi-processing
+sound/
+	- directory with info on sound card support
+specialix.txt
+	- info on hardware/driver for specialix IO8+ multiport serial card.
+spinlocks.txt
+	- info on using spinlocks to provide exclusive access in kernel.
+stallion.txt
+	- info on using the Stallion multiport serial driver.
+svga.txt
+	- short guide on selecting video modes at boot via VGA BIOS.
+sx.txt
+	- info on the Specialix SX/SI multiport serial driver.
+sysctl/
+	- directory with info on the /proc/sys/* files
+sysrq.txt
+	- info on the magic SysRq key
+unicode.txt
+	- info on the Unicode character/font mapping used in Linux.
+video4linux/
+	- directory with info regarding video/TV/radio cards and linux.
+vm/
+	- directory with info on the Linux vm code.
+watchdog.txt
+	- how to auto-reboot Linux if it has "fallen and can't get up". ;-)
+xterm-linux.xpm
+	- XPM image of penguin logo (see logo.txt) sitting on an xterm.
+

Documentation/BUG-HUNTING

+[Sat Mar  2 10:32:33 PST 1996 KERNEL_BUG-HOWTO lm@sgi.com (Larry McVoy)]
+
+This is how to track down a bug if you know nothing about kernel hacking.  
+It's a brute force approach but it works pretty well.
+
+You need:
+
+        . A reproducible bug - it has to happen predictably (sorry)
+        . All the kernel tar files from a revision that worked to the
+          revision that doesn't
+
+You will then do:
+
+        . Rebuild a revision that you believe works, install, and verify that.
+        . Do a binary search over the kernels to figure out which one
+          introduced the bug.  I.e., suppose 1.3.28 didn't have the bug, but 
+          you know that 1.3.69 does.  Pick a kernel in the middle and build
+          that, like 1.3.50.  Build & test; if it works, pick the mid point
+          between .50 and .69, else the mid point between .28 and .50.
+        . You'll narrow it down to the kernel that introduced the bug.  You
+          can probably do better than this but it gets tricky.  
+
+        . Narrow it down to a subdirectory
+
+          - Copy kernel that works into "test".  Let's say that 3.62 works,
+            but 3.63 doesn't.  So you diff -r those two kernels and come
+            up with a list of directories that changed.  For each of those
+            directories:
+
+                Copy the non-working directory next to the working directory
+                as "dir.63".  
+                One directory at time, try moving the working directory to
+                "dir.62" and mv dir.63 dir"time, try 
+
+                        mv dir dir.62
+                        mv dir.63 dir
+                        find dir -name '*.[oa]' -print | xargs rm -f
+
+                And then rebuild and retest.  Assuming that all related
+                changes were contained in the sub directory, this should 
+                isolate the change to a directory.  
+
+                Problems: changes in header files may have occurred; I've
+                found in my case that they were self explanatory - you may 
+                or may not want to give up when that happens.
+
+        . Narrow it down to a file
+
+          - You can apply the same technique to each file in the directory,
+            hoping that the changes in that file are self contained.  
+            
+        . Narrow it down to a routine
+
+          - You can take the old file and the new file and manually create
+            a merged file that has
+
+                #ifdef VER62
+                routine()
+                {
+                        ...
+                }
+                #else
+                routine()
+                {
+                        ...
+                }
+                #endif
+
+            And then walk through that file, one routine at a time and
+            prefix it with
+
+                #define VER62
+                /* both routines here */
+                #undef VER62
+
+            Then recompile, retest, move the ifdefs until you find the one
+            that makes the difference.
+
+Finally, you take all the info that you have, kernel revisions, bug
+description, the extent to which you have narrowed it down, and pass 
+that off to whomever you believe is the maintainer of that section.
+A post to linux.dev.kernel isn't such a bad idea if you've done some
+work to narrow it down.
+
+If you get it down to a routine, you'll probably get a fix in 24 hours.
+
+My apologies to Linus and the other kernel hackers for describing this
+brute force approach, it's hardly what a kernel hacker would do.  However,
+it does work and it lets non-hackers help fix bugs.  And it is cool
+because Linux snapshots will let you do this - something that you can't
+do with vendor supplied releases.
+

Documentation/CodingStyle

+
+		Linux kernel coding style 
+
+This is a short document describing the preferred coding style for the
+linux kernel.  Coding style is very personal, and I won't _force_ my
+views on anybody, but this is what goes for anything that I have to be
+able to maintain, and I'd prefer it for most other things too.  Please
+at least consider the points made here. 
+
+First off, I'd suggest printing out a copy of the GNU coding standards,
+and NOT read it.  Burn them, it's a great symbolic gesture. 
+
+Anyway, here goes:
+
+
+	 	Chapter 1: Indentation
+
+Tabs are 8 characters, and thus indentations are also 8 characters. 
+There are heretic movements that try to make indentations 4 (or even 2!)
+characters deep, and that is akin to trying to define the value of PI to
+be 3. 
+
+Rationale: The whole idea behind indentation is to clearly define where
+a block of control starts and ends.  Especially when you've been looking
+at your screen for 20 straight hours, you'll find it a lot easier to see
+how the indentation works if you have large indentations. 
+
+Now, some people will claim that having 8-character indentations makes
+the code move too far to the right, and makes it hard to read on a
+80-character terminal screen.  The answer to that is that if you need
+more than 3 levels of indentation, you're screwed anyway, and should fix
+your program. 
+
+In short, 8-char indents make things easier to read, and have the added
+benefit of warning you when you're nesting your functions too deep. 
+Heed that warning. 
+
+
+		Chapter 2: Placing Braces
+
+The other issue that always comes up in C styling is the placement of
+braces.  Unlike the indent size, there are few technical reasons to
+choose one placement strategy over the other, but the preferred way, as
+shown to us by the prophets Kernighan and Ritchie, is to put the opening
+brace last on the line, and put the closing brace first, thusly:
+
+	if (x is true) {
+		we do y
+	}
+
+However, there is one special case, namely functions: they have the
+opening brace at the beginning of the next line, thus:
+
+	int function(int x)
+	{
+		body of function
+	}
+
+Heretic people all over the world have claimed that this inconsistency
+is ...  well ...  inconsistent, but all right-thinking people know that
+(a) K&R are _right_ and (b) K&R are right.  Besides, functions are
+special anyway (you can't nest them in C). 
+
+Note that the closing brace is empty on a line of its own, _except_ in
+the cases where it is followed by a continuation of the same statement,
+ie a "while" in a do-statement or an "else" in an if-statement, like
+this:
+
+	do {
+		body of do-loop
+	} while (condition);
+
+and
+
+	if (x == y) {
+		..
+	} else if (x > y) {
+		...
+	} else {
+		....
+	}
+			
+Rationale: K&R. 
+
+Also, note that this brace-placement also minimizes the number of empty
+(or almost empty) lines, without any loss of readability.  Thus, as the
+supply of new-lines on your screen is not a renewable resource (think
+25-line terminal screens here), you have more empty lines to put
+comments on. 
+
+
+		Chapter 3: Naming
+
+C is a Spartan language, and so should your naming be.  Unlike Modula-2
+and Pascal programmers, C programmers do not use cute names like
+ThisVariableIsATemporaryCounter.  A C programmer would call that
+variable "tmp", which is much easier to write, and not the least more
+difficult to understand. 
+
+HOWEVER, while mixed-case names are frowned upon, descriptive names for
+global variables are a must.  To call a global function "foo" is a
+shooting offense. 
+
+GLOBAL variables (to be used only if you _really_ need them) need to
+have descriptive names, as do global functions.  If you have a function
+that counts the number of active users, you should call that
+"count_active_users()" or similar, you should _not_ call it "cntusr()". 
+
+Encoding the type of a function into the name (so-called Hungarian
+notation) is brain damaged - the compiler knows the types anyway and can
+check those, and it only confuses the programmer.  No wonder MicroSoft
+makes buggy programs. 
+
+LOCAL variable names should be short, and to the point.  If you have
+some random integer loop counter, it should probably be called "i". 
+Calling it "loop_counter" is non-productive, if there is no chance of it
+being mis-understood.  Similarly, "tmp" can be just about any type of
+variable that is used to hold a temporary value. 
+
+If you are afraid to mix up your local variable names, you have another
+problem, which is called the function-growth-hormone-imbalance syndrome. 
+See next chapter. 
+
+		
+		Chapter 4: Functions
+
+Functions should be short and sweet, and do just one thing.  They should
+fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
+as we all know), and do one thing and do that well. 
+
+The maximum length of a function is inversely proportional to the
+complexity and indentation level of that function.  So, if you have a
+conceptually simple function that is just one long (but simple)
+case-statement, where you have to do lots of small things for a lot of
+different cases, it's OK to have a longer function. 
+
+However, if you have a complex function, and you suspect that a
+less-than-gifted first-year high-school student might not even
+understand what the function is all about, you should adhere to the
+maximum limits all the more closely.  Use helper functions with
+descriptive names (you can ask the compiler to in-line them if you think
+it's performance-critical, and it will probably do a better job of it
+that you would have done). 
+
+Another measure of the function is the number of local variables.  They
+shouldn't exceed 5-10, or you're doing something wrong.  Re-think the
+function, and split it into smaller pieces.  A human brain can
+generally easily keep track of about 7 different things, anything more
+and it gets confused.  You know you're brilliant, but maybe you'd like
+to understand what you did 2 weeks from now. 
+
+
+		Chapter 5: Commenting
+
+Comments are good, but there is also a danger of over-commenting.  NEVER
+try to explain HOW your code works in a comment: it's much better to
+write the code so that the _working_ is obvious, and it's a waste of
+time to explain badly written code. 
+
+Generally, you want your comments to tell WHAT your code does, not HOW. 
+Also, try to avoid putting comments inside a function body: if the
+function is so complex that you need to separately comment parts of it,
+you should probably go back to chapter 4 for a while.  You can make
+small comments to note or warn about something particularly clever (or
+ugly), but try to avoid excess.  Instead, put the comments at the head
+of the function, telling people what it does, and possibly WHY it does
+it. 
+
+
+		Chapter 6: You've made a mess of it
+
+That's OK, we all do.  You've probably been told by your long-time Unix
+user helper that "GNU emacs" automatically formats the C sources for
+you, and you've noticed that yes, it does do that, but the defaults it
+uses are less than desirable (in fact, they are worse than random
+typing - a infinite number of monkeys typing into GNU emacs would never
+make a good program). 
+
+So, you can either get rid of GNU emacs, or change it to use saner
+values.  To do the latter, you can stick the following in your .emacs file:
+
+(defun linux-c-mode ()
+  "C mode with adjusted defaults for use with the Linux kernel."
+  (interactive)
+  (c-mode)
+  (c-set-style "K&R")
+  (setq c-basic-offset 8))
+
+This will define the M-x linux-c-mode command.  When hacking on a
+module, if you put the string -*- linux-c -*- somewhere on the first
+two lines, this mode will be automatically invoked. Also, you may want
+to add
+
+(setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode)
+                       auto-mode-alist))
+
+to your .emacs file if you want to have linux-c-mode switched on
+automagically when you edit source files under /usr/src/linux.
+
+But even if you fail in getting emacs to do sane formatting, not
+everything is lost: use "indent".
+
+Now, again, GNU indent has the same brain dead settings that GNU emacs
+has, which is why you need to give it a few command line options. 
+However, that's not too bad, because even the makers of GNU indent
+recognize the authority of K&R (the GNU people aren't evil, they are
+just severely misguided in this matter), so you just give indent the
+options "-kr -i8" (stands for "K&R, 8 character indents"). 
+
+"indent" has a lot of options, and especially when it comes to comment
+re-formatting you may want to take a look at the manual page.  But
+remember: "indent" is not a fix for bad programming. 
+
+
+		Chapter 7: Configuration-files
+
+For configuration options (arch/xxx/config.in, and all the Config.in files),
+somewhat different indentation is used.
+
+An indention level of 3 is used in the code, while the text in the config-
+options should have an indention-level of 2 to indicate dependencies. The
+latter only applies to bool/tristate options. For other options, just use
+common sense. An example:
+
+if [ "$CONFIG_EXPERIMENTAL" = "y" ]; then
+   tristate 'Apply nitroglycerine inside the keyboard (DANGEROUS)' CONFIG_BOOM
+   if [ "$CONFIG_BOOM" != "n" ]; then
+      bool '  Output nice messages when you explode' CONFIG_CHEER
+   fi
+fi
+
+Generally, CONFIG_EXPERIMENTAL should surround all options not considered
+stable. All options that are known to trash data (experimental write-
+support for file-systems, for instance) should be denoted (DANGEROUS), other
+Experimental options should be denoted (EXPERIMENTAL).

Documentation/DocBook/Makefile

+BOOKS	:= wanbook.sgml z8530book.sgml mcabook.sgml videobook.sgml \
+	   kernel-api.sgml parportbook.sgml kernel-hacking.sgml \
+	   kernel-locking.sgml via-audio.sgml mousedrivers.sgml sis900.sgml
+
+PS	:=	$(patsubst %.sgml, %.ps, $(BOOKS))
+PDF	:=	$(patsubst %.sgml, %.pdf, $(BOOKS))
+HTML    :=      $(patsubst %.sgml, %, $(BOOKS))
+IMG-parportbook := parport-share.fig parport-multi.fig parport-structure.fig
+EPS-parportbook := $(patsubst %.fig, %.eps, $(IMG-parportbook))
+JPG-parportbook := $(patsubst %.fig, %.jpeg, $(IMG-parportbook))
+
+$(BOOKS): $(TOPDIR)/scripts/docproc
+
+.PHONY:	books ps pdf html clean mrproper
+
+books:	$(BOOKS)
+
+ps:	$(PS)
+
+pdf:	$(PDF)
+
+html:	$(HTML)
+
+%.eps: %.fig
+	-fig2dev -Leps $< $@
+
+%.jpeg: %.fig
+	-fig2dev -Ljpeg $< $@
+
+$(TOPDIR)/scripts/docproc:
+	$(MAKE) -C $(TOPDIR)/scripts docproc
+
+mousedrivers.sgml: mousedrivers.tmpl
+	$(TOPDIR)/scripts/docgen <$< >$@
+
+kernel-hacking.sgml: kernel-hacking.tmpl
+	$(TOPDIR)/scripts/docgen <$< >$@
+
+kernel-locking.sgml: kernel-locking.tmpl
+	$(TOPDIR)/scripts/docgen <$< >$@
+
+wanbook.sgml: wanbook.tmpl $(TOPDIR)/drivers/net/wan/syncppp.c
+	$(TOPDIR)/scripts/docgen $(TOPDIR)/drivers/net/wan/syncppp.c \
+		<wanbook.tmpl >wanbook.sgml
+
+z8530book.sgml: z8530book.tmpl $(TOPDIR)/drivers/net/wan/z85230.c
+	$(TOPDIR)/scripts/docgen $(TOPDIR)/drivers/net/wan/z85230.c \
+		<z8530book.tmpl >z8530book.sgml
+
+via-audio.sgml: via-audio.tmpl $(TOPDIR)/drivers/sound/via82cxxx_audio.c
+	$(TOPDIR)/scripts/docgen $(TOPDIR)/drivers/sound/via82cxxx_audio.c \
+		<via-audio.tmpl >via-audio.sgml
+
+sis900.sgml: sis900.tmpl $(TOPDIR)/drivers/net/sis900.c
+	$(TOPDIR)/scripts/docgen $(TOPDIR)/drivers/net/sis900.c \
+		<sis900.tmpl >sis900.sgml
+
+mcabook.sgml: mcabook.tmpl $(TOPDIR)/arch/i386/kernel/mca.c
+	$(TOPDIR)/scripts/docgen $(TOPDIR)/arch/i386/kernel/mca.c \
+		<mcabook.tmpl >mcabook.sgml
+
+videobook.sgml: videobook.tmpl $(TOPDIR)/drivers/media/video/videodev.c
+	$(TOPDIR)/scripts/docgen $(TOPDIR)/drivers/media/video/videodev.c \
+		<videobook.tmpl >videobook.sgml
+
+APISOURCES :=	$(TOPDIR)/drivers/media/video/videodev.c \
+		$(TOPDIR)/arch/i386/kernel/mca.c \
+		$(TOPDIR)/arch/i386/kernel/mtrr.c \
+		$(TOPDIR)/drivers/char/misc.c \
+		$(TOPDIR)/drivers/net/net_init.c \
+		$(TOPDIR)/drivers/net/8390.c \
+		$(TOPDIR)/drivers/char/serial.c \
+		$(TOPDIR)/drivers/pci/pci.c \
+		$(TOPDIR)/drivers/block/ll_rw_blk.c \
+		$(TOPDIR)/drivers/sound/sound_core.c \
+		$(TOPDIR)/drivers/sound/sound_firmware.c \
+		$(TOPDIR)/drivers/net/wan/syncppp.c \
+		$(TOPDIR)/drivers/net/wan/z85230.c \
+		$(TOPDIR)/drivers/usb/usb.c \
+		$(TOPDIR)/fs/locks.c \
+		$(TOPDIR)/fs/devfs/base.c \
+		$(TOPDIR)/kernel/pm.c \
+		$(TOPDIR)/kernel/ksyms.c \
+		$(TOPDIR)/net/netsyms.c
+ 
+kernel-api.sgml: kernel-api.tmpl $(APISOURCES)
+	$(TOPDIR)/scripts/docgen $(APISOURCES) \
+		<kernel-api.tmpl >kernel-api.sgml
+
+kernel-api-man: $(APISOURCES)
+	@rm -rf $(TOPDIR)/Documentation/man
+	$(TOPDIR)/scripts/kernel-doc -man $^ | \
+		$(PERL) $(TOPDIR)/scripts/split-man $(TOPDIR)/Documentation/man
+
+parportbook: $(JPG-parportbook)
+parportbook.ps: $(EPS-parportbook)
+parportbook.sgml: parportbook.tmpl $(TOPDIR)/drivers/parport/init.c
+	$(TOPDIR)/scripts/docgen $(TOPDIR)/drivers/parport/init.c <$< >$@
+
+DVI	:=	$(patsubst %.sgml, %.dvi, $(BOOKS))
+AUX	:=	$(patsubst %.sgml, %.aux, $(BOOKS))
+TEX	:=	$(patsubst %.sgml, %.tex, $(BOOKS))
+LOG	:=	$(patsubst %.sgml, %.log, $(BOOKS))
+OUT	:=	$(patsubst %.sgml, %.out, $(BOOKS))
+
+clean:
+	-$(RM) core *~
+	-$(RM) $(BOOKS)
+	-$(RM) $(DVI) $(AUX) $(TEX) $(LOG) $(OUT)
+	-$(RM) $(JPG-parportbook) $(EPS-parportbook)
+
+mrproper: clean
+	-$(RM) $(PS) $(PDF)
+	-$(RM) -r $(HTML)
+	-$(RM) .depend
+	-$(RM) $(TOPDIR)/scripts/mkdep-docbook
+
+%.ps : %.sgml
+	@(which db2ps > /dev/null 2>&1) || \
+	 (echo "*** You need to install DocBook stylesheets ***"; \
+	  exit 1)
+	db2ps $<
+
+%.pdf : %.sgml
+	@(which db2pdf > /dev/null 2>&1) || \
+	 (echo "*** You need to install DocBook stylesheets ***"; \
+	  exit 1)
+	db2pdf $<
+
+%:	%.sgml
+	@(which db2html > /dev/null 2>&1) || \
+	 (echo "*** You need to install DocBook stylesheets ***"; \
+	  exit 1)
+	-$(RM) -r $@
+	db2html $<
+	if [ ! -z "$(JPG-$@)" ]; then cp $(JPG-$@) $@; fi
+
+#
+# we could have our own dependency generator
+#
+#
+# .depend: $(TOPDIR)/scripts/mkdep-docbook
+#	$(TOPDIR)/scripts/mkdep-docbook $(wildcard *.tmpl) > .depend
+
+include $(TOPDIR)/Rules.make
+

Documentation/DocBook/kernel-api.tmpl

+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]>
+<book id="LinuxKernelAPI">
+ <bookinfo>
+  <title>The Linux Kernel API</title>
+  
+  <legalnotice>
+   <para>
+     This documentation is free software; you can redistribute
+     it and/or modify it under the terms of the GNU General Public
+     License as published by the Free Software Foundation; either
+     version 2 of the License, or (at your option) any later
+     version.
+   </para>
+      
+   <para>
+     This program is distributed in the hope that it will be
+     useful, but WITHOUT ANY WARRANTY; without even the implied
+     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+     See the GNU General Public License for more details.
+   </para>
+      
+   <para>
+     You should have received a copy of the GNU General Public
+     License along with this program; if not, write to the Free
+     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+     MA 02111-1307 USA
+   </para>
+      
+   <para>
+     For more details see the file COPYING in the source
+     distribution of Linux.
+   </para>
+  </legalnotice>
+ </bookinfo>
+
+<toc></toc>
+  <chapter id="adt">
+     <title>Data Types</title>
+     <sect1><title>Doubly Linked Lists</title>
+!Iinclude/linux/list.h
+     </sect1>
+  </chapter>
+
+  <chapter id="mm">
+     <title>Memory Management in Linux</title>
+     <sect1><title>The Slab Cache</title>
+!Emm/slab.c
+      </sect1>
+  </chapter>
+
+  <chapter id="vfs">
+     <title>The Linux VFS</title>
+     <sect1><title>The Directory Cache</title>
+!Efs/dcache.c
+!Iinclude/linux/dcache.h
+     </sect1>
+     <sect1><title>Inode Handling</title>
+!Efs/inode.c
+!Efs/bad_inode.c
+     </sect1>
+     <sect1><title>Registration and Superblocks</title>
+!Efs/super.c
+     </sect1>
+     <sect1><title>File Locks</title>
+!Efs/locks.c
+!Ifs/locks.c
+     </sect1>
+  </chapter>
+
+  <chapter id="netcore">
+     <title>Linux Networking</title>
+     <sect1><title>Socket Buffer Functions</title>
+!Iinclude/linux/skbuff.h
+!Enet/core/skbuff.c
+     </sect1>
+     <sect1><title>Socket Filter</title>
+!Enet/core/filter.c
+     </sect1>
+  </chapter>
+
+  <chapter id="netdev">
+     <title>Network device support</title>
+     <sect1><title>Driver Support</title>
+!Edrivers/net/net_init.c
+!Enet/core/dev.c
+     </sect1>
+     <sect1><title>8390 Based Network Cards</title>
+!Edrivers/net/8390.c
+     </sect1>
+     <sect1><title>Synchronous PPP</title>
+!Edrivers/net/wan/syncppp.c
+     </sect1>
+  </chapter>
+
+  <chapter id="modload">
+     <title>Module Loading</title>
+!Ekernel/kmod.c
+  </chapter>
+
+  <chapter id="hardware">
+     <title>Hardware Interfaces</title>
+     <sect1><title>Interrupt Handling</title>
+!Iarch/i386/kernel/irq.c
+     </sect1>
+
+     <sect1><title>MTRR Handling</title>
+!Earch/i386/kernel/mtrr.c
+     </sect1>
+     <sect1><title>PCI Support Library</title>
+!Edrivers/pci/pci.c
+     </sect1>
+     <sect1><title>MCA Architecture</title>
+	<sect2><title>MCA Device Functions</title>
+!Earch/i386/kernel/mca.c
+	</sect2>
+	<sect2><title>MCA Bus DMA</title>
+!Iinclude/asm-i386/mca_dma.h
+	</sect2>
+     </sect1>
+  </chapter>
+
+  <chapter id="devfs">
+     <title>The Device File System</title>
+!Efs/devfs/base.c
+  </chapter>
+
+  <chapter id="pmfuncs">
+     <title>Power Management</title>
+!Ekernel/pm.c
+  </chapter>
+
+  <chapter id="blkdev">
+     <title>Block Devices</title>
+!Edrivers/block/ll_rw_blk.c
+  </chapter>
+
+  <chapter id="miscdev">
+     <title>Miscellaneous Devices</title>
+!Edrivers/char/misc.c
+  </chapter>
+
+  <chapter id="viddev">
+     <title>Video4Linux</title>
+!Edrivers/media/video/videodev.c
+  </chapter>
+
+  <chapter id="snddev">
+     <title>Sound Devices</title>
+!Edrivers/sound/sound_core.c
+!Idrivers/sound/sound_firmware.c
+  </chapter>
+
+  <chapter id="usb">
+     <title>USB Devices</title>
+!Edrivers/usb/usb.c
+  </chapter>
+
+  <chapter id="uart16x50">
+     <title>16x50 UART Driver</title>
+!Edrivers/char/serial.c
+  </chapter>
+
+  <chapter id="z85230">
+     <title>Z85230 Support Library</title>
+!Edrivers/net/wan/z85230.c
+  </chapter>
+
+
+</book>

Documentation/DocBook/parport-multi.fig

+#FIG 3.2
+Landscape
+Center
+Inches
+Letter  
+100.00
+Single
+-2
+1200 2
+6 1425 4350 5175 5475
+6 3450 5100 4425 5475
+2 4 0 1 0 7 50 0 -1 0.000 0 0 7 0 0 5
+	 4425 5475 4425 5100 3450 5100 3450 5475 4425 5475
+4 0 0 50 0 0 12 0.0000 4 135 510 3600 5400 Printer\001
+-6
+6 3375 4350 5175 4725
+2 4 0 1 0 7 50 0 -1 0.000 0 0 7 0 0 5
+	 5175 4725 5175 4350 3375 4350 3375 4725 5175 4725
+4 0 0 50 0 0 12 0.0000 4 180 870 3825 4650 Multiplexor\001
+-6
+6 1425 4650 2775 5475
+6 1425 4650 2775 5475
+2 4 0 1 0 7 50 0 -1 0.000 0 0 6 0 0 5
+	 2757 5475 2757 4650 1425 4650 1425 5475 2757 5475
+4 0 0 50 0 0 12 0.0000 4 180 735 1725 5100 Computer\001
+-6
+2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
+	 2775 4875 2700 4875 2700 5025 2775 5025 2775 4875
+2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
+	 2775 5175 2700 5175 2700 5325 2775 5325 2775 5175
+-6
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 2775 4950 3600 4725
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 2775 5250 3450 5325
+-6
+6 3150 2625 4125 3525
+2 4 0 1 0 7 50 0 -1 0.000 0 0 7 0 0 5
+	 4125 3075 4125 2625 3150 2625 3150 3075 4125 3075
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 3675 3075 3675 3525
+4 0 0 50 0 0 12 0.0000 4 135 510 3300 2925 Printer\001
+-6
+6 4275 3450 5250 4350
+2 4 0 1 0 7 50 0 -1 0.000 0 0 7 0 0 5
+	 5250 3900 5250 3450 4275 3450 4275 3900 5250 3900
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 4800 3900 4800 4350
+4 0 0 50 0 0 12 0.0000 4 135 510 4425 3750 Printer\001
+-6
+2 4 0 1 0 7 50 0 -1 0.000 0 0 7 0 0 5
+	 3900 4050 3900 3525 3375 3525 3375 4050 3900 4050
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 3675 4050 3675 4350
+2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
+	 3600 4350 3750 4350 3750 4425 3600 4425 3600 4350
+2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
+	 4725 4350 4875 4350 4875 4425 4725 4425 4725 4350
+4 0 0 50 0 0 12 0.0000 4 135 285 3450 3900 ZIP\001

Documentation/arm/SA1100/Itsy

+Itsy is a research project done by the Western Research Lab, and Systems
+Research Center in Palo Alto, CA. The Itsy project is one of several
+research projects at Compaq that are related to pocket computing.
+
+Itsy support has yet to be fully integrated in this kernel.  Linux 2.0.x
+support is available though.
+
+For more information, see:
+
+	http://www.research.digital.com/wrl/itsy/index.html
+
+