From: Michael Still <mikal@stillhq.com>
To: linux-kernel@vger.kernel.org, Linus Torvalds <torvalds@transmeta.com>
Subject: Resent [2.5 Patch] Add mandocs and mandocs_install targets (fwd)
Date: Wed, 04 Jun 2003 10:06:04 +1000 [thread overview]
Message-ID: <Pine.LNX.4.30.0306041005440.7218-100000@localhost.localdomain> (raw)
Hey,
this patch adds two new targets to the 2.5 makefiles -- mandocs, and
mandocs_install. The targets require two new perl scripts in the scripts/
directory, but in return we get a series of man pages for kernel
functions, which are installed in man section 9. This is a good thing, as
many programmers expect documentation to be available with man, and
hunting through various PS or PDF documents to find the documentation for
the function you want can be quite frustrating.
The man pages are just extracted from the various existing DocBook SGML
documents, which are generated by kernel-doc. You also need to have
docbook2man installed on your machine.
Note that the two scripts (makeman and split-man) need executable
permissions, and I couldn't work out how to make this happen in a mere
diff. Also please note the formatting is not perfect, but I will tweak
other stuff later with further patches -- this is just an initial
implementation.
Sample output (HTMLised) can be found at
http://www.stillhq.com/linux/mandocs/2.5.70/
Linus, please consider applying.
Thanks,
Mikal
============= PATCH =============
diff -Nur linux-2.5.70/CREDITS linux-2.5.70-mandocs/CREDITS
--- linux-2.5.70/CREDITS 2003-05-27 11:00:44.000000000 +1000
+++ linux-2.5.70-mandocs/CREDITS 2003-05-29 18:45:55.000000000 +1000
@@ -2981,6 +2981,14 @@
S: Sunyvale, CA 94086
S: USA
+N: Michael Still
+E: mikal@stillhq.com
+W: http://www.stillhq.com
+D: Various janitorial patches
+D: mandocs and mandocs_install build targets
+S: (Email me and ask)
+S: Australia
+
N: Henrik Storner
E: storner@image.dk
W: http://www.image.dk/~storner/
diff -Nur linux-2.5.70/Documentation/DocBook/Makefile linux-2.5.70-mandocs/Documentation/DocBook/Makefile
--- linux-2.5.70/Documentation/DocBook/Makefile 2003-05-27 11:00:39.000000000 +1000
+++ linux-2.5.70-mandocs/Documentation/DocBook/Makefile 2003-05-29 19:56:15.000000000 +1000
@@ -19,10 +19,11 @@
# file.tmpl --> file.sgml +--> file.ps (psdocs)
# +--> file.pdf (pdfdocs)
# +--> DIR=file (htmldocs)
+# +--> man/ (mandocs)
###
# The targets that may be used.
-.PHONY: sgmldocs psdocs pdfdocs htmldocs clean mrproper
+.PHONY: sgmldocs psdocs pdfdocs htmldocs mandocs clean mrproper
BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
sgmldocs: $(BOOKS)
@@ -36,10 +37,15 @@
HTML := $(patsubst %.sgml, %.html, $(BOOKS))
htmldocs: $(HTML)
+MAN := $(patsubst %.sgml, %.9, $(BOOKS))
+mandocs: $(MAN)
+
###
#External programs used
KERNELDOC=$(objtree)/scripts/kernel-doc
DOCPROC=$(objtree)/scripts/docproc
+SPLITMAN=$(objtree)/scripts/split-man
+MAKEMAN=$(objtree)/scripts/makeman
###
# DOCPROC is used for two purposes:
@@ -118,6 +124,10 @@
@if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
+%.9: %.sgml
+ $(SPLITMAN) $< $(objtree)/Documentation/DocBook/man "$(VERSION).$(PATCHLEVEL).$(SUBLEVEL)"
+ $(MAKEMAN) convert $(objtree)/Documentation/DocBook/man $<
+
###
# Rules to generate postscripts and PNG imgages from .fig format files
%.eps: %.fig
@@ -142,7 +152,7 @@
# Help targets as used by the top-level makefile
dochelp:
@echo ' Linux kernel internal documentation in different formats:'
- @echo ' sgmldocs (SGML), psdocs (Postscript), pdfdocs (PDF), htmldocs (HTML)'
+ @echo ' sgmldocs (SGML), psdocs (Postscript), pdfdocs (PDF), htmldocs (HTML), mandocs (man pages, use mandocs_install to install)'
###
# clean and mrproper as used by the top-level makefile
@@ -156,6 +166,7 @@
$(patsubst %.sgml, %.ps, $(DOCBOOKS)) \
$(patsubst %.sgml, %.pdf, $(DOCBOOKS)) \
$(patsubst %.sgml, %.html, $(DOCBOOKS)) \
+ $(patsubst %.sgml, %.9, $(DOCBOOKS)) \
$(patsubst %.fig,%.eps, $(IMG-parportbook)) \
$(patsubst %.fig,%.png, $(IMG-parportbook)) \
$(C-procfs-example)
diff -Nur linux-2.5.70/Documentation/DocBook/man/Makefile linux-2.5.70-mandocs/Documentation/DocBook/man/Makefile
--- linux-2.5.70/Documentation/DocBook/man/Makefile 1970-01-01 10:00:00.000000000 +1000
+++ linux-2.5.70-mandocs/Documentation/DocBook/man/Makefile 2003-05-29 20:11:15.000000000 +1000
@@ -0,0 +1,3 @@
+.PHONY: clean
+
+clean-files := *.9.gz *.sgml manpage.links manpage.refs
diff -Nur linux-2.5.70/Makefile linux-2.5.70-mandocs/Makefile
--- linux-2.5.70/Makefile 2003-05-27 11:00:42.000000000 +1000
+++ linux-2.5.70-mandocs/Makefile 2003-05-29 19:26:44.000000000 +1000
@@ -189,6 +189,7 @@
LDFLAGS_MODULE = -r
CFLAGS_KERNEL =
AFLAGS_KERNEL =
+MAKEMAN = scripts/makeman
NOSTDINC_FLAGS = -nostdinc -iwithprefix include
@@ -217,7 +218,7 @@
defconfig allyesconfig allnoconfig allmodconfig \
clean mrproper distclean rpm \
help tags TAGS cscope sgmldocs psdocs pdfdocs htmldocs \
- checkconfig checkhelp checkincludes
+ mandocs mandocs_install checkconfig checkhelp checkincludes
RCS_FIND_IGNORE := \( -name SCCS -o -name BitKeeper -o -name .svn -o -name CVS \) -prune -o
RCS_TAR_IGNORE := --exclude SCCS --exclude BitKeeper --exclude .svn --exclude CVS
@@ -680,7 +681,9 @@
# clean - Delete all intermediate files
#
-clean-dirs += $(addprefix _clean_,$(ALL_SUBDIRS) Documentation/DocBook scripts)
+clean-dirs += $(addprefix _clean_,$(ALL_SUBDIRS) \
+ Documentation/DocBook Documentation/DocBook/man \
+ scripts)
.PHONY: $(clean-dirs) clean archclean mrproper archmrproper distclean
$(clean-dirs):
$(Q)$(MAKE) $(clean)=$(patsubst _clean_%,%,$@)
@@ -816,9 +819,12 @@
# Documentation targets
# ---------------------------------------------------------------------------
-sgmldocs psdocs pdfdocs htmldocs: scripts/docproc FORCE
+sgmldocs psdocs pdfdocs htmldocs mandocs: scripts/docproc FORCE
$(Q)$(MAKE) $(build)=Documentation/DocBook $@
+mandocs_install: mandocs
+ $(MAKEMAN) install Documentation/DocBook/man
+
# Scripts to check various things for consistency
# ---------------------------------------------------------------------------
diff -Nur linux-2.5.70/scripts/makeman linux-2.5.70-mandocs/scripts/makeman
--- linux-2.5.70/scripts/makeman 1970-01-01 10:00:00.000000000 +1000
+++ linux-2.5.70-mandocs/scripts/makeman 2003-05-29 19:45:15.000000000 +1000
@@ -0,0 +1,46 @@
+#!/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);
+
+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($ARGV[0] eq "convert"){
+ open LISTING, "grep \"<refentrytitle>\" $ARGV[2] |";
+ while(<LISTING>){
+ s/<\/.*$//;
+ s/^.*>//;
+ s/\.sgml//;
+ s/struct //;
+ s/typedef //;
+
+ chomp;
+ print "Processing $_\n";
+ system("cd $ARGV[1]; docbook2man $_.sgml; gzip -f $_.9\n");
+ }
+}
+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 -Nur linux-2.5.70/scripts/split-man linux-2.5.70-mandocs/scripts/split-man
--- linux-2.5.70/scripts/split-man 1970-01-01 10:00:00.000000000 +1000
+++ linux-2.5.70-mandocs/scripts/split-man 2003-05-29 20:19:33.000000000 +1000
@@ -0,0 +1,112 @@
+#!/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(/<legalnotice>/){
+ $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 "<!DOCTYPE refentry PUBLIC \"-//Davenport//DTD DocBook V3.0//EN\">\n\n";
+ print REF "$refdata";
+ $refdata = "";
+ }
+
+ # Extraction
+ if($mode == 1){
+ $front = "$front$_";
+ }
+ 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>/){
+ $front =~ s/<legalnotice>//;
+ $front =~ s/<\/legalnotice>//;
+ print REF <<EOF;
+<refsect1><title>About this document</title>
+$front
+<para>
+If you have comments on the formatting of this manpage, then please contact
+Michael Still (mikal\@stillhq.com).
+</para>
+
+<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(/<\/legalnotice>/){
+ $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]`;
reply other threads:[~2003-06-03 23:57 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=Pine.LNX.4.30.0306041005440.7218-100000@localhost.localdomain \
--to=mikal@stillhq.com \
--cc=linux-kernel@vger.kernel.org \
--cc=torvalds@transmeta.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).