Skip to content

R
raspberrypi-kernel

openeuler / raspberrypi-kernel

通知 13
Star 1
Fork 0
R
raspberrypi-kernel
提交 8b0c2d98 编写于 作者: M Martin Waitz 提交者： Linus Torvalds
浏览文件
操作

[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: NMartin Waitz <tali@admingilde.org>
Signed-off-by: NAndrew Morton <akpm@osdl.org>
Signed-off-by: NLinus Torvalds <torvalds@osdl.org>
上级 ac9296f9
隐藏空白更改
内联 并排
Showing with 53 addition and 326 deletion
Documentation/Changes
浏览文件 @ 8b0c2d98
......@@ -357,14 +357,14 @@ Quota-tools
----------
o <http://sourceforge.net/projects/linuxquota/>
Jade
----
o <ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz>
DocBook Stylesheets
-------------------
o <http://nwalsh.com/docbook/dsssl/>
XMLTO XSLT Frontend
-------------------
o <http://cyberelk.net/tim/xmlto/>
Intel P6 microcode
------------------
o <http://www.urbanmyth.org/microcode/>
......
Documentation/DocBook/Makefile
浏览文件 @ 8b0c2d98
......@@ -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 '<a HREF="$(patsubst %.html,%,$(notdir $@))/book1.html"> \
Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
%.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
......
scripts/kernel-doc
浏览文件 @ 8b0c2d98
......@@ -581,8 +581,14 @@ sub output_function_xml(%) {
$id =~ s/[^A-Za-z0-9]/-/g;
print "<refentry>\n";
print "<refentryinfo>\n";
print " <title>LINUX</title>\n";
print " <productname>Kernel Hackers Manual</productname>\n";
print " <date>$man_date</date>\n";
print "</refentryinfo>\n";
print "<refmeta>\n";
print "<refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
print " <refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
print " <manvolnum>9</manvolnum>\n";
print "</refmeta>\n";
print "<refnamediv>\n";
print " <refname>".$args{'function'}."</refname>\n";
......@@ -651,8 +657,14 @@ sub output_struct_xml(%) {
$id =~ s/[^A-Za-z0-9]/-/g;
print "<refentry>\n";
print "<refentryinfo>\n";
print " <title>LINUX</title>\n";
print " <productname>Kernel Hackers Manual</productname>\n";
print " <date>$man_date</date>\n";
print "</refentryinfo>\n";
print "<refmeta>\n";
print "<refentrytitle><phrase id=\"$id\">".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
print " <refentrytitle><phrase id=\"$id\">".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
print " <manvolnum>9</manvolnum>\n";
print "</refmeta>\n";
print "<refnamediv>\n";
print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";
......@@ -729,8 +741,14 @@ sub output_enum_xml(%) {
$id =~ s/[^A-Za-z0-9]/-/g;
print "<refentry>\n";
print "<refentryinfo>\n";
print " <title>LINUX</title>\n";
print " <productname>Kernel Hackers Manual</productname>\n";
print " <date>$man_date</date>\n";
print "</refentryinfo>\n";
print "<refmeta>\n";
print "<refentrytitle><phrase id=\"$id\">enum ".$args{'enum'}."</phrase></refentrytitle>\n";
print " <refentrytitle><phrase id=\"$id\">enum ".$args{'enum'}."</phrase></refentrytitle>\n";
print " <manvolnum>9</manvolnum>\n";
print "</refmeta>\n";
print "<refnamediv>\n";
print " <refname>enum ".$args{'enum'}."</refname>\n";
......@@ -789,8 +807,14 @@ sub output_typedef_xml(%) {
$id =~ s/[^A-Za-z0-9]/-/g;
print "<refentry>\n";
print "<refentryinfo>\n";
print " <title>LINUX</title>\n";
print " <productname>Kernel Hackers Manual</productname>\n";
print " <date>$man_date</date>\n";
print "</refentryinfo>\n";
print "<refmeta>\n";
print "<refentrytitle><phrase id=\"$id\">typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
print " <refentrytitle><phrase id=\"$id\">typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
print " <manvolnum>9</manvolnum>\n";
print "</refmeta>\n";
print "<refnamediv>\n";
print " <refname>typedef ".$args{'typedef'}."</refname>\n";
......
scripts/makeman 已删除 100755 → 0
浏览文件 @ ac9296f9
#!/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] <dir> <file>\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 \"<refentrytitle>\" $ARGV[2] |";
while(<LISTING>){
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
# <!-- BEGINFRONTTAG -->
# <!-- <bookinfo> mode = 1
# <!-- <legalnotice> mode = 2
# <!-- ...GPL or whatever...
# <!-- </legalnotice> mode = 4
# <!-- </bookinfo> mode = 3
# <!-- ENDFRONTTAG -->
#
# ...doco...
# I know that some of the if statements in this while loop are in a funny
# order, but that is deliberate...
while(<INPUT>){
if($mode > 0){
s/<!-- //;
s/ -->//;
s/<docinfo>//i;
s<\/docinfo>//i;
s/^[ \t]*//i;
}
if($mode == 2){
if(/<para>/i){
}
elsif(/<\/para>/i){
$front = "$front.\\\" \n";
}
elsif(/<\/legalnotice>/i){
$mode = 4;
}
elsif(/^[ \t]*$/){
}
else{
$front = "$front.\\\" $_";
}
}
if($mode == 1){
if(/<title>(.*)<\/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";
scripts/split-man 已删除 100755 → 0
浏览文件 @ ac9296f9
#!/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</title>
<para>
This documentation was generated with kernel version $ARGV[2].
</para>
</refsect1>
EOF
}
# For some reason, we title the synopsis twice in the main DocBook
if(! /<title>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]`;
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或