Commit e2701603 authored by Linus Torvalds's avatar Linus Torvalds
Browse files

Merge tag 'docs-for-linus' of git://git.lwn.net/linux-2.6 

Pull documentation updates from Jonathan Corbet:
 "There's been a fair amount going on in the docs tree this time around,
  including:

   - Support for reproducible document builds, from Ben Hutchings and
     company.

   - The ability to automatically generate cross-reference links within
     a single DocBook book and embedded descriptions for large
     structures.  From Danilo Cesar Lemes de Paula.

   - A new document on how to add a system call from David Drysdale.

   - Chameleon bus documentation from Johannes Thumshirn.

  ...plus the usual collection of improvements, typo fixes, and more"

* tag 'docs-for-linus' of git://git.lwn.net/linux-2.6: (39 commits)
  Documentation, add kernel-parameters.txt entry for dis_ucode_ldr
  Documentation/x86: Rename IRQSTACKSIZE to IRQ_STACK_SIZE
  Documentation/Intel-IOMMU.txt: Modify definition of DRHD
  docs: update HOWTO for 3.x -> 4.x versioning
  kernel-doc: ignore unneeded attribute information
  scripts/kernel-doc: Adding cross-reference links to html documentation.
  DocBook: Fix non-determinstic installation of duplicate man pages
  Documentation: minor typo fix in mailbox.txt
  Documentation: describe how to add a system call
  doc: Add more workqueue functions to the documentation
  ARM: keystone: add documentation for SoCs and EVMs
  scripts/kernel-doc Allow struct arguments documentation in struct body
  SubmittingPatches: remove stray quote character
  Revert "DocBook: Avoid building man pages repeatedly and inconsistently"
  Documentation: Minor changes to men-chameleon-bus.txt
  Doc: fix trivial typo in SubmittingPatches
  MAINTAINERS: Direct Documentation/DocBook/media properly
  Documentation: installed man pages don't need to be executable
  fix Evolution submenu name in email-clients.txt
  Documentation: Add MCB documentation
  ...
parents 22629b6d ce14c583

Documentation/CodingStyle

+0 −2
Original line number Diff line number Diff line
@@ -929,13 +929,11 @@ The C Programming Language, Second Edition 
by Brian W. Kernighan and Dennis M. Ritchie.

Prentice Hall, Inc., 1988.

ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).

URL: http://cm.bell-labs.com/cm/cs/cbook/



The Practice of Programming

by Brian W. Kernighan and Rob Pike.

Addison-Wesley, Inc., 1999.

ISBN 0-201-61586-X.

URL: http://cm.bell-labs.com/cm/cs/tpop/



GNU manuals - where in compliance with K&R and this text - for cpp, gcc,

gcc internals and indent, all available from http://www.gnu.org/manual/

Documentation/DocBook/Makefile

+36 −17
Original line number Diff line number Diff line
@@ -56,14 +56,17 @@ htmldocs: $(HTML) 


MAN := $(patsubst %.xml, %.9, $(BOOKS))

mandocs: $(MAN)

	find $(obj)/man -name '*.9' | xargs gzip -f

	find $(obj)/man -name '*.9' | xargs gzip -nf



installmandocs: mandocs

	mkdir -p /usr/local/man/man9/

	install $(obj)/man/*.9.gz /usr/local/man/man9/

	find $(obj)/man -name '*.9.gz' -printf '%h %f\n' | \

		sort -k 2 -k 1 | uniq -f 1 | sed -e 's: :/:' | \

		xargs install -m 644 -t /usr/local/man/man9/



###

#External programs used

KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref

KERNELDOC       = $(srctree)/scripts/kernel-doc

DOCPROC         = $(objtree)/scripts/docproc
@@ -89,7 +92,7 @@ define rule_docproc 
        ) > $(dir $@).$(notdir $@).cmd

endef



%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE

%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE

	$(call if_changed_rule,docproc)



# Tell kbuild to always build the programs
@@ -140,7 +143,20 @@ quiet_cmd_db2html = HTML $@ 
		echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \

		$(patsubst %.html,%,$(notdir $@))</a><p>' > $@



%.html:	%.xml

###

# Rules to create an aux XML and .db, and use them to re-process the DocBook XML

# to fill internal hyperlinks

       gen_aux_xml = :

 quiet_gen_aux_xml = echo '  XMLREF  $@'

silent_gen_aux_xml = :

%.aux.xml: %.xml

	@$($(quiet)gen_aux_xml)

	@rm -rf $@

	@(cat $< | egrep "^<refentry id" | egrep -o "\".*\"" | cut -f 2 -d \" > $<.db)

	@$(KERNELDOCXMLREF) -db $<.db $< > $@

.PRECIOUS: %.aux.xml



%.html:	%.aux.xml

	@(which xmlto > /dev/null 2>&1) || \

	 (echo "*** You need to install xmlto ***"; \

	  exit 1)
@@ -150,12 +166,12 @@ quiet_cmd_db2html = HTML $@ 
            cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi



quiet_cmd_db2man = MAN     $@

      cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; fi

      cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man/$(*F) $< ; fi

%.9 : %.xml

	@(which xmlto > /dev/null 2>&1) || \

	 (echo "*** You need to install xmlto ***"; \

	  exit 1)

	$(Q)mkdir -p $(obj)/man

	$(Q)mkdir -p $(obj)/man/$(*F)

	$(call cmd,db2man)

	@touch $@
@@ -218,6 +234,9 @@ clean-files := $(DOCBOOKS) \ 
	$(patsubst %.xml, %.pdf,     $(DOCBOOKS)) \

	$(patsubst %.xml, %.html,    $(DOCBOOKS)) \

	$(patsubst %.xml, %.9,       $(DOCBOOKS)) \

	$(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \

	$(patsubst %.xml, %.xml.db,  $(DOCBOOKS)) \

	$(patsubst %.xml, %.xml,     $(DOCBOOKS)) \

	$(index)



clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man

Documentation/DocBook/device-drivers.tmpl

+1 −0
Original line number Diff line number Diff line
@@ -66,6 +66,7 @@ 
!Ekernel/time/hrtimer.c

     </sect1>

     <sect1><title>Workqueues and Kevents</title>

!Iinclude/linux/workqueue.h

!Ekernel/workqueue.c

     </sect1>

     <sect1><title>Internal Functions</title>

Documentation/DocBook/stylesheet.xsl

+1 −0
Original line number Diff line number Diff line
@@ -5,6 +5,7 @@ 
<param name="funcsynopsis.tabular.threshold">80</param>

<param name="callout.graphics">0</param>

<!-- <param name="paper.type">A4</param> -->

<param name="generate.consistent.ids">1</param>

<param name="generate.section.toc.level">2</param>

<param name="use.id.as.filename">1</param>

</stylesheet>

Documentation/HOWTO

+14 −14
Original line number Diff line number Diff line
@@ -218,16 +218,16 @@ The development process 
Linux kernel development process currently consists of a few different

main kernel "branches" and lots of different subsystem-specific kernel

branches.  These different branches are:

  - main 3.x kernel tree

  - 3.x.y -stable kernel tree

  - 3.x -git kernel patches

  - main 4.x kernel tree

  - 4.x.y -stable kernel tree

  - 4.x -git kernel patches

  - subsystem specific kernel trees and patches

  - the 3.x -next kernel tree for integration tests

  - the 4.x -next kernel tree for integration tests



3.x kernel tree

4.x kernel tree

-----------------

3.x kernels are maintained by Linus Torvalds, and can be found on

kernel.org in the pub/linux/kernel/v3.x/ directory.  Its development

4.x kernels are maintained by Linus Torvalds, and can be found on

kernel.org in the pub/linux/kernel/v4.x/ directory.  Its development

process is as follows:

  - As soon as a new kernel is released a two weeks window is open,

    during this period of time maintainers can submit big diffs to
@@ -262,20 +262,20 @@ mailing list about kernel releases: 
	released according to perceived bug status, not according to a

	preconceived timeline."



3.x.y -stable kernel tree

4.x.y -stable kernel tree

---------------------------

Kernels with 3-part versions are -stable kernels. They contain

relatively small and critical fixes for security problems or significant

regressions discovered in a given 3.x kernel.

regressions discovered in a given 4.x kernel.



This is the recommended branch for users who want the most recent stable

kernel and are not interested in helping test development/experimental

versions.



If no 3.x.y kernel is available, then the highest numbered 3.x

If no 4.x.y kernel is available, then the highest numbered 4.x

kernel is the current stable kernel.



3.x.y are maintained by the "stable" team <stable@vger.kernel.org>, and

4.x.y are maintained by the "stable" team <stable@vger.kernel.org>, and

are released as needs dictate.  The normal release period is approximately

two weeks, but it can be longer if there are no pressing problems.  A

security-related problem, instead, can cause a release to happen almost
@@ -285,7 +285,7 @@ The file Documentation/stable_kernel_rules.txt in the kernel tree 
documents what kinds of changes are acceptable for the -stable tree, and

how the release process works.



3.x -git patches

4.x -git patches

------------------

These are daily snapshots of Linus' kernel tree which are managed in a

git repository (hence the name.) These patches are usually released
@@ -317,9 +317,9 @@ revisions to it, and maintainers can mark patches as under review, 
accepted, or rejected.  Most of these patchwork sites are listed at

http://patchwork.kernel.org/.



3.x -next kernel tree for integration tests

4.x -next kernel tree for integration tests

---------------------------------------------

Before updates from subsystem trees are merged into the mainline 3.x

Before updates from subsystem trees are merged into the mainline 4.x

tree, they need to be integration-tested.  For this purpose, a special

testing repository exists into which virtually all subsystem trees are

pulled on an almost daily basis:

CRA Git | Maintained and supported by SUSTech CRA and CCSE