Commit 52b3f239 authored by Jonathan Corbet's avatar Jonathan Corbet

Docs: clean up some DocBook loose ends

There were a few bits and pieces left over from the now-disused DocBook
toolchain; git rid of them.
Reported-by: default avatarMarkus Heiser <markus.heiser@darmarit.de>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 61ca5fd1
......@@ -118,7 +118,6 @@ defkeymap.c
devlist.h*
devicetable-offsets.h
dnotify_test
docproc
dslm
dtc
elf2ecoff
......
#
# Pandoc doesn't grok <function> or <structname>, so convert them
# ahead of time.
#
# Use the following escapes to pass through pandoc:
# $bq = "`"
# $lt = "<"
# $gt = ">"
#
s%<function>\([^<(]\+\)()</function>%:c:func:$bq\1()$bq%g
s%<function>\([^<(]\+\)</function>%:c:func:$bq\1()$bq%g
s%<structname>struct *\([^<]\+\)</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g
s%struct <structname>\([^<]\+\)</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g
s%<structname>\([^<]\+\)</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g
#
# Wrap docproc directives in para and code blocks.
#
s%^\(!.*\)$%<para><code>DOCPROC: \1</code></para>%
#
# Unescape.
#
s/$bq/`/g
s/$lt/</g
s/$gt/>/g
#
# pandoc thinks that both "_" needs to be escaped. Remove the extra
# backslashes.
#
s/\\_/_/g
#
# Unwrap docproc directives.
#
s/^``DOCPROC: !E\(.*\)``$/.. kernel-doc:: \1\n :export:/
s/^``DOCPROC: !I\(.*\)``$/.. kernel-doc:: \1\n :internal:/
s/^``DOCPROC: !F\([^ ]*\) \(.*\)``$/.. kernel-doc:: \1\n :functions: \2/
s/^``DOCPROC: !P\([^ ]*\) \(.*\)``$/.. kernel-doc:: \1\n :doc: \2/
s/^``DOCPROC: \(!.*\)``$/.. WARNING: DOCPROC directive not supported: \1/
#
# Trim trailing whitespace.
#
s/[[:space:]]*$//
......@@ -4135,8 +4135,7 @@ M: Jonathan Corbet <corbet@lwn.net>
L: linux-doc@vger.kernel.org
S: Maintained
F: Documentation/
F: scripts/docproc.c
F: scripts/kernel-doc*
F: scripts/kernel-doc
X: Documentation/ABI/
X: Documentation/devicetree/
X: Documentation/acpi
......
......@@ -1467,7 +1467,6 @@ $(help-board-dirs): help-%:
DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs linkcheckdocs
PHONY += $(DOC_TARGETS)
$(DOC_TARGETS): scripts_basic FORCE
$(Q)$(MAKE) $(build)=scripts build_docproc
$(Q)$(MAKE) $(build)=Documentation $@
else # KBUILD_EXTMOD
......
......@@ -7,7 +7,6 @@ pnmtologo
unifdef
ihex2fw
recordmcount
docproc
check-lc_ctype
sortextable
asn1_compiler
......
......@@ -6,7 +6,6 @@
# pnmttologo: Convert pnm files to logo files
# conmakehash: Create chartable
# conmakehash: Create arrays for initializing the kernel console tables
# docproc: Used in Documentation/
HOST_EXTRACFLAGS += -I$(srctree)/tools/include
......@@ -28,14 +27,12 @@ HOSTLOADLIBES_extract-cert = -lcrypto
always := $(hostprogs-y) $(hostprogs-m)
# The following hostprogs-y programs are only build on demand
hostprogs-y += unifdef docproc
hostprogs-y += unifdef
# These targets are used internally to avoid "is up to date" messages
PHONY += build_unifdef build_docproc
PHONY += build_unifdef
build_unifdef: $(obj)/unifdef
@:
build_docproc: $(obj)/docproc
@:
subdir-$(CONFIG_MODVERSIONS) += genksyms
subdir-y += mod
......
This diff is collapsed.
#!/usr/bin/perl -w
use strict;
## Copyright (C) 2015 Intel Corporation ##
# ##
## This software falls under the GNU General Public License. ##
## Please read the COPYING file for more information ##
#
#
# This software reads a XML file and a list of valid interal
# references to replace Docbook tags with links.
#
# The list of "valid internal references" must be one-per-line in the following format:
# API-struct-foo
# API-enum-bar
# API-my-function
#
# The software walks over the XML file looking for xml tags representing possible references
# to the Document. Each reference will be cross checked against the "Valid Internal Reference" list. If
# the referece is found it replaces its content by a <link> tag.
#
# usage:
# kernel-doc-xml-ref -db filename
# xml filename > outputfile
# read arguments
if ($#ARGV != 2) {
usage();
}
#Holds the database filename
my $databasefile;
my @database;
#holds the inputfile
my $inputfile;
my $errors = 0;
my %highlights = (
"<function>(.*?)</function>",
"\"<function>\" . convert_function(\$1, \$line) . \"</function>\"",
"<structname>(.*?)</structname>",
"\"<structname>\" . convert_struct(\$1) . \"</structname>\"",
"<funcdef>(.*?)<function>(.*?)</function></funcdef>",
"\"<funcdef>\" . convert_param(\$1) . \"<function>\$2</function></funcdef>\"",
"<paramdef>(.*?)<parameter>(.*?)</parameter></paramdef>",
"\"<paramdef>\" . convert_param(\$1) . \"<parameter>\$2</parameter></paramdef>\"");
while($ARGV[0] =~ m/^-(.*)/) {
my $cmd = shift @ARGV;
if ($cmd eq "-db") {
$databasefile = shift @ARGV
} else {
usage();
}
}
$inputfile = shift @ARGV;
sub open_database {
open (my $handle, '<', $databasefile) or die "Cannot open $databasefile";
chomp(my @lines = <$handle>);
close $handle;
@database = @lines;
}
sub process_file {
open_database();
my $dohighlight;
foreach my $pattern (keys %highlights) {
$dohighlight .= "\$line =~ s:$pattern:$highlights{$pattern}:eg;\n";
}
open(FILE, $inputfile) or die("Could not open $inputfile") or die ("Cannot open $inputfile");
foreach my $line (<FILE>) {
eval $dohighlight;
print $line;
}
}
sub trim($_)
{
my $str = $_[0];
$str =~ s/^\s+|\s+$//g;
return $str
}
sub has_key_defined($_)
{
if ( grep( /^$_[0]$/, @database)) {
return 1;
}
return 0;
}
# Gets a <function> content and add it a hyperlink if possible.
sub convert_function($_)
{
my $arg = $_[0];
my $key = $_[0];
my $line = $_[1];
$key = trim($key);
$key =~ s/[^A-Za-z0-9]/-/g;
$key = "API-" . $key;
# We shouldn't add links to <funcdef> prototype
if (!has_key_defined($key) || $line =~ m/\s+<funcdef/i) {
return $arg;
}
my $head = $arg;
my $tail = "";
if ($arg =~ /(.*?)( ?)$/) {
$head = $1;
$tail = $2;
}
return "<link linkend=\"$key\">$head</link>$tail";
}
# Converting a struct text to link
sub convert_struct($_)
{
my $arg = $_[0];
my $key = $_[0];
$key =~ s/(struct )?(\w)/$2/g;
$key =~ s/[^A-Za-z0-9]/-/g;
$key = "API-struct-" . $key;
if (!has_key_defined($key)) {
return $arg;
}
my ($head, $tail) = split_pointer($arg);
return "<link linkend=\"$key\">$head</link>$tail";
}
# Identify "object *" elements
sub split_pointer($_)
{
my $arg = $_[0];
if ($arg =~ /(.*?)( ?\* ?)/) {
return ($1, $2);
}
return ($arg, "");
}
sub convert_param($_)
{
my $type = $_[0];
my $keyname = convert_key_name($type);
if (!has_key_defined($keyname)) {
return $type;
}
my ($head, $tail) = split_pointer($type);
return "<link linkend=\"$keyname\">$head</link>$tail";
}
# DocBook links are in the API-<TYPE>-<STRUCT-NAME> format
# This method gets an element and returns a valid DocBook reference for it.
sub convert_key_name($_)
{
#Pattern $2 is optional and might be uninitialized
no warnings 'uninitialized';
my $str = $_[0];
$str =~ s/(const|static)? ?(struct)? ?([a-zA-Z0-9_]+) ?(\*|&)?/$2 $3/g ;
# trim
$str =~ s/^\s+|\s+$//g;
# spaces and _ to -
$str =~ s/[^A-Za-z0-9]/-/g;
return "API-" . $str;
}
sub usage {
print "Usage: $0 -db database filename\n";
print " xml source file(s) > outputfile\n";
exit 1;
}
# starting point
process_file();
if ($errors) {
print STDERR "$errors errors\n";
}
exit($errors);
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment