From ac9296f95228f50d112e6caec3b461fd816de084 Mon Sep 17 00:00:00 2001 From: Jeff Garzik Date: Sun, 1 May 2005 08:59:27 -0700 Subject: [PATCH] DocBook: remove obsolete templates As the author of tulip-user and via-audio docbooks, I can say that they are out of date and should be deleted. Signed-off-by: Martin Waitz Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/DocBook/Makefile | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'Documentation/DocBook/Makefile') diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index a221039ee4c9..393082c7a3a2 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -7,10 +7,9 @@ # list of DOCBOOKS. DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ - kernel-hacking.xml kernel-locking.xml via-audio.xml \ - deviceiobook.xml procfs-guide.xml tulip-user.xml \ - writing_usb_driver.xml scsidrivers.xml sis900.xml \ - kernel-api.xml journal-api.xml lsm.xml usb.xml \ + kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ + procfs-guide.xml writing_usb_driver.xml scsidrivers.xml \ + sis900.xml kernel-api.xml journal-api.xml lsm.xml usb.xml \ gadget.xml libata.xml mtdnand.xml librs.xml ### -- cgit 1.4.1 From 8b0c2d989cc60db1767481386ca912e99807eddb Mon Sep 17 00:00:00 2001 From: Martin Waitz Date: Sun, 1 May 2005 08:59:27 -0700 Subject: [PATCH] DocBook: Use xmlto to process the DocBook files. xmlto uses standared XSLT templates to generate manpages, (x)html pages, and XML FO files which can be processed with passivetex. This is much faster than using jadetex for everything. This patch also reduces the number of kernel-specific scripts that are needed to generate documentation. Signed-off-by: Martin Waitz Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/Changes | 8 +- Documentation/DocBook/Makefile | 42 +++++----- scripts/kernel-doc | 32 ++++++- scripts/makeman | 185 ----------------------------------------- scripts/split-man | 112 ------------------------- 5 files changed, 53 insertions(+), 326 deletions(-) delete mode 100755 scripts/makeman delete mode 100755 scripts/split-man (limited to 'Documentation/DocBook/Makefile') diff --git a/Documentation/Changes b/Documentation/Changes index caa6a5529b6b..57542bc25edd 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -357,14 +357,14 @@ Quota-tools ---------- o -Jade ----- -o - DocBook Stylesheets ------------------- o +XMLTO XSLT Frontend +------------------- +o + Intel P6 microcode ------------------ o diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 393082c7a3a2..a2441fa99c3f 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -41,14 +41,15 @@ MAN := $(patsubst %.xml, %.9, $(BOOKS)) mandocs: $(MAN) installmandocs: mandocs - $(MAKEMAN) install Documentation/DocBook/man + mkdir -p /usr/local/man/man9/ + install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/ ### #External programs used KERNELDOC = scripts/kernel-doc DOCPROC = scripts/basic/docproc -SPLITMAN = $(PERL) $(srctree)/scripts/split-man -MAKEMAN = $(PERL) $(srctree)/scripts/makeman + +#XMLTOFLAGS = --skip-validation ### # DOCPROC is used for two purposes: @@ -95,29 +96,29 @@ $(obj)/procfs-guide.xml: $(C-procfs-example2) # Rules to generate postscript, PDF and HTML # db2html creates a directory. Generate a html file used for timestamp -quiet_cmd_db2ps = DB2PS $@ - cmd_db2ps = db2ps -o $(dir $@) $< +quiet_cmd_db2ps = XMLTO $@ + cmd_db2ps = xmlto ps $(XMLTOFLAGS) -o $(dir $@) $< %.ps : %.xml - @(which db2ps > /dev/null 2>&1) || \ + @(which xmlto > /dev/null 2>&1) || \ (echo "*** You need to install DocBook stylesheets ***"; \ exit 1) $(call cmd,db2ps) -quiet_cmd_db2pdf = DB2PDF $@ - cmd_db2pdf = db2pdf -o $(dir $@) $< +quiet_cmd_db2pdf = XMLTO $@ + cmd_db2pdf = xmlto pdf $(XMLTOFLAGS) -o $(dir $@) $< %.pdf : %.xml - @(which db2pdf > /dev/null 2>&1) || \ + @(which xmlto > /dev/null 2>&1) || \ (echo "*** You need to install DocBook stylesheets ***"; \ exit 1) $(call cmd,db2pdf) -quiet_cmd_db2html = DB2HTML $@ - cmd_db2html = db2html -o $(patsubst %.html,%,$@) $< && \ +quiet_cmd_db2html = XMLTO $@ + cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \ echo ' \ Goto $(patsubst %.html,%,$(notdir $@))

' > $@ %.html: %.xml - @(which db2html > /dev/null 2>&1) || \ + @(which xmlto > /dev/null 2>&1) || \ (echo "*** You need to install DocBook stylesheets ***"; \ exit 1) @rm -rf $@ $(patsubst %.html,%,$@) @@ -125,15 +126,14 @@ quiet_cmd_db2html = DB2HTML $@ @if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \ cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi -### -# Rule to generate man files - output is placed in the man subdirectory - -%.9: %.xml -ifneq ($(KBUILD_SRC),) - $(Q)mkdir -p $(objtree)/Documentation/DocBook/man -endif - $(SPLITMAN) $< $(objtree)/Documentation/DocBook/man "$(VERSION).$(PATCHLEVEL).$(SUBLEVEL)" - $(MAKEMAN) convert $(objtree)/Documentation/DocBook/man $< +quiet_cmd_db2man = XMLTO $@ + cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; gzip -f $(obj)/man/*.9; fi +%.9 : %.xml + @(which xmlto > /dev/null 2>&1) || \ + (echo "*** You need to install DocBook stylesheets ***"; \ + exit 1) + $(call cmd,db2man) + @touch $@ ### # Rules to generate postscripts and PNG imgages from .fig format files diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 62bf9fe50677..0835dc2a8aa9 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -581,8 +581,14 @@ sub output_function_xml(%) { $id =~ s/[^A-Za-z0-9]/-/g; print "\n"; + print "\n"; + print " LINUX\n"; + print " Kernel Hackers Manual\n"; + print " $man_date\n"; + print "\n"; print "\n"; - print "".$args{'function'}."\n"; + print " ".$args{'function'}."\n"; + print " 9\n"; print "\n"; print "\n"; print " ".$args{'function'}."\n"; @@ -651,8 +657,14 @@ sub output_struct_xml(%) { $id =~ s/[^A-Za-z0-9]/-/g; print "\n"; + print "\n"; + print " LINUX\n"; + print " Kernel Hackers Manual\n"; + print " $man_date\n"; + print "\n"; print "\n"; - print "".$args{'type'}." ".$args{'struct'}."\n"; + print " ".$args{'type'}." ".$args{'struct'}."\n"; + print " 9\n"; print "\n"; print "\n"; print " ".$args{'type'}." ".$args{'struct'}."\n"; @@ -729,8 +741,14 @@ sub output_enum_xml(%) { $id =~ s/[^A-Za-z0-9]/-/g; print "\n"; + print "\n"; + print " LINUX\n"; + print " Kernel Hackers Manual\n"; + print " $man_date\n"; + print "\n"; print "\n"; - print "enum ".$args{'enum'}."\n"; + print " enum ".$args{'enum'}."\n"; + print " 9\n"; print "\n"; print "\n"; print " enum ".$args{'enum'}."\n"; @@ -789,8 +807,14 @@ sub output_typedef_xml(%) { $id =~ s/[^A-Za-z0-9]/-/g; print "\n"; + print "\n"; + print " LINUX\n"; + print " Kernel Hackers Manual\n"; + print " $man_date\n"; + print "\n"; print "\n"; - print "typedef ".$args{'typedef'}."\n"; + print " typedef ".$args{'typedef'}."\n"; + print " 9\n"; print "\n"; print "\n"; print " typedef ".$args{'typedef'}."\n"; diff --git a/scripts/makeman b/scripts/makeman deleted file mode 100755 index db3af647ee17..000000000000 --- a/scripts/makeman +++ /dev/null @@ -1,185 +0,0 @@ -#!/usr/bin/perl - -use strict; - -## Copyright (C) Michael Still (mikal@stillhq.com) -## Released under the terms of the GNU GPL -## -## A script to make or install the manpages extracted by split-man -## -## Arguements: $1 -- the word "convert" or "install" -## $2 -- the directory containing the SGML files for the manpages -## $3 -- the filename which contained the sgmldoc output -## (I need this so I know which manpages to convert) - -my($LISTING, $GENERATED, $INPUT, $OUTPUT, $front, $mode, $filename, $tmpdir); - -if($ARGV[0] eq ""){ - die "Usage: makeman [convert | install]

\n"; -} - -if( ! -d "$ARGV[1]" ){ - die "Output directory \"$ARGV[1]\" does not exist\n"; -} - -if($ENV{"TMPDIR"} ne ""){ - $tmpdir = $ENV{"TMPDIR"}; -} -else{ - $tmpdir = "/tmp"; -} - -if($ARGV[0] eq "convert"){ - open LISTING, "grep \"\" $ARGV[2] |"; - while(){ - s/<\/.*$//; - s/^.*>//; - s/\.sgml//; - s/struct //; - s/typedef //; - - chomp; - $filename = $_; - print "Processing $filename\n"; - - # Open the input file to extract the front matter, generate the man page, - # and open it, and the rearrange everything until it is happy - open INPUT, "< $ARGV[1]/$filename.sgml"; - $front = ""; - $mode = 0; - - # The modes used here are: - # mode = 0 - # - # - # - # ...doco... - - # I know that some of the if statements in this while loop are in a funny - # order, but that is deliberate... - while(){ - if($mode > 0){ - s///; - s///i; - s<\/docinfo>//i; - s/^[ \t]*//i; - } - - if($mode == 2){ - if(//i){ - } - elsif(/<\/para>/i){ - $front = "$front.\\\" \n"; - } - elsif(/<\/legalnotice>/i){ - $mode = 4; - } - elsif(/^[ \t]*$/){ - } - else{ - $front = "$front.\\\" $_"; - } - } - - if($mode == 1){ - if(/(.*)<\/title>/i){ - $front = "$front.\\\" This documentation was generated from the book titled \"$1\", which is part of the Linux kernel source.\n.\\\" \n"; - } - elsif(/<legalnotice>/i){ - $front = "$front.\\\" This documentation comes with the following legal notice:\n.\\\" \n"; - $mode = 2; - } - - elsif(/<author>/i){ - $front = "$front.\\\" Documentation by: "; - } - elsif(/<firstname>(.*)<\/firstname>/i){ - $front = "$front$1 "; - } - elsif(/<surname>(.*)<\/surname>/i){ - $front = "$front$1 "; - } - elsif(/<email>(.*)<\/email>/i){ - $front = "$front($1)"; - } - elsif(/\/author>/i){ - $front = "$front\n"; - } - - elsif(/<copyright>/i){ - $front = "$front.\\\" Documentation copyright: "; - } - elsif(/<holder>(.*)<\/holder>/i){ - $front = "$front$1 "; - } - elsif(/<year>(.*)<\/year>/i){ - $front = "$front$1 "; - } - elsif(/\/copyright>/i){ - $front = "$front\n"; - } - - elsif(/^[ \t]*$/ - || /<affiliation>/i - || /<\/affiliation>/i - || /<address>/i - || /<\/address>/i - || /<authorgroup>/i - || /<\/authorgroup>/i - || /<\/legalnotice>/i - || /<date>/i - || /<\/date>/i - || /<edition>/i - || /<\/edition>/i - || /<pubdate>/i - || /<\/pubdate>/i){ - } - else{ - print "Unknown tag in manpage conversion: $_"; - } - } - - if($mode == 0){ - if(/<bookinfo>/i){ - $mode = 1; - } - } - - if($mode == 4){ - if(/<\/bookinfo>/i){ - $mode = 3; - } - } - } - close INPUT; - - system("cd $ARGV[1]; docbook2man $filename.sgml; mv $filename.9 $tmpdir/$$.9\n"); - open GENERATED, "< $tmpdir/$$.9"; - open OUTPUT, "> $ARGV[1]/$filename.9"; - - print OUTPUT "$front"; - print OUTPUT ".\\\" For comments on the formatting of this manpage, please contact Michael Still <mikal\@stillhq.com>\n\n"; - while(<GENERATED>){ - print OUTPUT "$_"; - } - close OUTPUT; - close GENERATED; - - system("gzip -f $ARGV[1]/$filename.9\n"); - unlink("$tmpdir/$$.9"); - } -} -elsif($ARGV[0] eq "install"){ - system("mkdir -p /usr/local/man/man9/; install $ARGV[1]/*.9.gz /usr/local/man/man9/"); -} -else{ - die "Usage: makeman [convert | install] <dir> <file>\n"; -} - -print "Done\n"; diff --git a/scripts/split-man b/scripts/split-man deleted file mode 100755 index 03897fe6a75d..000000000000 --- a/scripts/split-man +++ /dev/null @@ -1,112 +0,0 @@ -#!/usr/bin/perl - -use strict; - -## Copyright (C) Michael Still (mikal@stillhq.com) -## Released under the terms of the GNU GPL -## -## Hoon through the specified DocBook SGML file, and split out the -## man pages. These can then be processed into groff format, and -## installed if desired... -## -## Arguements: $1 -- the name of the sgml file -## $2 -- the directory to put the generated SGML files in -## $3 -- kernel version - -my($SGML, $REF, $front, $refdata, $mode, $filename); - -if(($ARGV[0] eq "") || ($ARGV[1] eq "") || ($ARGV[2] eq "")){ - die "Usage: split-man <sgml file> <output dir> <kernel version>\n"; -} - -open SGML, "< $ARGV[0]" or die "Could not open input file \"$ARGV[0]\"\n"; -if( ! -d "$ARGV[1]" ){ - die "Output directory \"$ARGV[1]\" does not exist\n"; -} - -# Possible modes: -# 0: Looking for input I care about -# 1: Inside book front matter -# 2: Inside a refentry -# 3: Inside a refentry, and we know the filename - -$mode = 0; -$refdata = ""; -$front = ""; -while(<SGML>){ - # Starting modes - if(/<bookinfo>/ || /<docinfo>/){ - $mode = 1; - } - elsif(/<refentry>/){ - $mode = 2; - } - elsif(/<refentrytitle><phrase[^>]*>([^<]*)<.*$/){ - $mode = 3; - $filename = $1; - - $filename =~ s/struct //; - $filename =~ s/typedef //; - - print "Found manpage for $filename\n"; - open REF, "> $ARGV[1]/$filename.sgml" or - die "Couldn't open output file \"$ARGV[1]/$filename.sgml\": $!\n"; - print REF <<EOF; -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> - -<!-- BEGINFRONTTAG: The following is front matter for the parent book --> -$front -<!-- ENDFRONTTAG: End front matter --> - -$refdata -EOF - $refdata = ""; - } - - # Extraction - if($mode == 1){ - chomp $_; - $front = "$front<!-- $_ -->\n"; - } - elsif($mode == 2){ - $refdata = "$refdata$_"; - } - elsif($mode == 3){ - # There are some fixups which need to be applied - if(/<\/refmeta>/){ - print REF "<manvolnum>9</manvolnum>\n"; - } - if(/<\/refentry>/){ - print REF <<EOF; -<refsect1><title>About this document - -This documentation was generated with kernel version $ARGV[2]. - - -EOF - } - - # For some reason, we title the synopsis twice in the main DocBook - if(! /Synopsis<\/title>/){ - if(/<refentrytitle>/){ - s/struct //; - s/typedef //; - } - - print REF "$_"; - } - } - - # Ending modes - if(/<\/bookinfo>/ || /<\/docinfo>/){ - $mode = 0; - } - elsif(/<\/refentry>/){ - $mode = 0; - close REF; - } -} - -# And make sure we don't process this unnessesarily -$ARGV[0] =~ s/\.sgml/.9/; -`touch $ARGV[0]`; -- cgit 1.4.1 From 2948e57d94bd2d2fb6d4e89d89f0bd0ddaee0513 Mon Sep 17 00:00:00 2001 From: Martin Waitz <tali@admingilde.org> Date: Sun, 1 May 2005 08:59:27 -0700 Subject: [PATCH] Docbook: use custom stylesheet With the custom stylesheet, functions are rendered using ANSI-C syntax and xmlto is a bit quieter. Signed-off-by: Martin Waitz <tali@admingilde.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org> --- Documentation/DocBook/Makefile | 3 ++- Documentation/DocBook/stylesheet.xsl | 5 +++++ 2 files changed, 7 insertions(+), 1 deletion(-) create mode 100644 Documentation/DocBook/stylesheet.xsl (limited to 'Documentation/DocBook/Makefile') diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index a2441fa99c3f..39c87666db31 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -49,7 +49,8 @@ installmandocs: mandocs KERNELDOC = scripts/kernel-doc DOCPROC = scripts/basic/docproc -#XMLTOFLAGS = --skip-validation +XMLTOFLAGS = -m Documentation/DocBook/stylesheet.xsl +#XMLTOFLAGS += --skip-validation ### # DOCPROC is used for two purposes: diff --git a/Documentation/DocBook/stylesheet.xsl b/Documentation/DocBook/stylesheet.xsl new file mode 100644 index 000000000000..e14c21dda403 --- /dev/null +++ b/Documentation/DocBook/stylesheet.xsl @@ -0,0 +1,5 @@ +<?xml version="1.0" encoding="UTF-8"?> +<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0"> +<param name="chunk.quietly">1</param> +<param name="funcsynopsis.style">ansi</param> +</stylesheet> -- cgit 1.4.1 From 4fa35166c540073a2c6e450683c776f68e8b5569 Mon Sep 17 00:00:00 2001 From: Martin Waitz <tali@admingilde.org> Date: Sun, 1 May 2005 08:59:28 -0700 Subject: [PATCH] DocBook: fix html link The start page for each book has changed from book1.html to index.html. Update our generated links acocrdingly. Signed-off-by: Martin Waitz <tali@admingilde.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org> --- Documentation/DocBook/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/DocBook/Makefile') diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 39c87666db31..83bcb0ae0917 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -115,7 +115,7 @@ quiet_cmd_db2pdf = XMLTO $@ quiet_cmd_db2html = XMLTO $@ cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \ - echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/book1.html"> \ + echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \ Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@ %.html: %.xml -- cgit 1.4.1 From fd4a3244941ed74fffc24b64857977270e6f64e2 Mon Sep 17 00:00:00 2001 From: Sam Ravnborg <sam@ravnborg.org> Date: Sun, 1 May 2005 08:59:28 -0700 Subject: [PATCH] docbook: Tell users to install xmlto, not stylesheets We have at least two users which were confused by these messages, myself included. Signed-off-by: Alexey Dobriyan <adobriyan@mail.ru> Signed-off-by: Sam Ravnborg <sam@ravnborg.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org> --- Documentation/DocBook/Makefile | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation/DocBook/Makefile') diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 83bcb0ae0917..e69b3d2e7884 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -101,7 +101,7 @@ quiet_cmd_db2ps = XMLTO $@ cmd_db2ps = xmlto ps $(XMLTOFLAGS) -o $(dir $@) $< %.ps : %.xml @(which xmlto > /dev/null 2>&1) || \ - (echo "*** You need to install DocBook stylesheets ***"; \ + (echo "*** You need to install xmlto ***"; \ exit 1) $(call cmd,db2ps) @@ -109,7 +109,7 @@ quiet_cmd_db2pdf = XMLTO $@ cmd_db2pdf = xmlto pdf $(XMLTOFLAGS) -o $(dir $@) $< %.pdf : %.xml @(which xmlto > /dev/null 2>&1) || \ - (echo "*** You need to install DocBook stylesheets ***"; \ + (echo "*** You need to install xmlto ***"; \ exit 1) $(call cmd,db2pdf) @@ -120,7 +120,7 @@ quiet_cmd_db2html = XMLTO $@ %.html: %.xml @(which xmlto > /dev/null 2>&1) || \ - (echo "*** You need to install DocBook stylesheets ***"; \ + (echo "*** You need to install xmlto ***"; \ exit 1) @rm -rf $@ $(patsubst %.html,%,$@) $(call cmd,db2html) @@ -131,7 +131,7 @@ quiet_cmd_db2man = XMLTO $@ cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; gzip -f $(obj)/man/*.9; fi %.9 : %.xml @(which xmlto > /dev/null 2>&1) || \ - (echo "*** You need to install DocBook stylesheets ***"; \ + (echo "*** You need to install xmlto ***"; \ exit 1) $(call cmd,db2man) @touch $@ -- cgit 1.4.1