Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S271917AbTGRVQg (ORCPT ); Fri, 18 Jul 2003 17:16:36 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S271883AbTGRVM0 (ORCPT ); Fri, 18 Jul 2003 17:12:26 -0400 Received: from pasmtp.tele.dk ([193.162.159.95]:48388 "EHLO pasmtp.tele.dk") by vger.kernel.org with ESMTP id S271846AbTGRVI4 (ORCPT ); Fri, 18 Jul 2003 17:08:56 -0400 Date: Fri, 18 Jul 2003 23:23:51 +0200 From: Sam Ravnborg To: Linus Torvalds , linux-kernel@vger.kernel.org, Michael Still Subject: Re: [PATCH] docbook: Added support for generating man files Message-ID: <20030718212350.GA5733@mars.ravnborg.org> Mail-Followup-To: Linus Torvalds , linux-kernel@vger.kernel.org, Michael Still References: <20030718204852.GA4443@mars.ravnborg.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20030718204852.GA4443@mars.ravnborg.org> User-Agent: Mutt/1.4.1i Sender: linux-kernel-owner@vger.kernel.org X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 9949 Lines: 322 Hi Linus - please apply. Only docbook relevant changes [with patch this time]. Originally by Michael Still This patch adds two new targets to the docbook makefile -- mandocs, and installmandocs. 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. 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.68/ and http://www.stillhq.com/linux/mandocs/2.5.70/ CREDITS | 8 ++ Documentation/DocBook/Makefile | 30 +++++++++- Makefile | 4 - scripts/makeman | 46 ++++++++++++++++ scripts/split-man | 112 +++++++++++++++++++++++++++++++++++++++++ 5 files changed, 193 insertions(+), 7 deletions(-) diff -Nru a/CREDITS b/CREDITS --- a/CREDITS Fri Jul 18 23:21:44 2003 +++ b/CREDITS Fri Jul 18 23:21:44 2003 @@ -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 -Nru a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile --- a/Documentation/DocBook/Makefile Fri Jul 18 23:21:44 2003 +++ b/Documentation/DocBook/Makefile Fri Jul 18 23:21:44 2003 @@ -20,10 +20,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 installmandocs BOOKS := $(addprefix $(obj)/,$(DOCBOOKS)) sgmldocs: $(BOOKS) @@ -37,10 +38,18 @@ HTML := $(patsubst %.sgml, %.html, $(BOOKS)) htmldocs: $(HTML) +MAN := $(patsubst %.sgml, %.9, $(BOOKS)) +mandocs: $(MAN) + +installmandocs: mandocs + $(MAKEMAN) install Documentation/DocBook/man + ### #External programs used KERNELDOC = scripts/kernel-doc DOCPROC = scripts/docproc +SPLITMAN = $(PERL) $(srctree)/scripts/split-man +MAKEMAN = $(PERL) $(srctree)/scripts/makeman ### # DOCPROC is used for two purposes: @@ -128,6 +137,13 @@ cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi ### +# Rule to generate man files - output is placed in the man subdirectory + +%.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 quiet_cmd_fig2eps = FIG2EPS $@ cmd_fig2eps = fig2dev -Leps $< $@ @@ -157,10 +173,10 @@ # 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)' + @echo ' htmldocs (HTML), mandocs (man pages, use installmandocs to install)' ### -# clean and mrproper as used by the top-level makefile # Temporary files left by various tools clean-files := $(DOCBOOKS) \ $(patsubst %.sgml, %.dvi, $(DOCBOOKS)) \ @@ -171,10 +187,14 @@ $(patsubst %.sgml, %.ps, $(DOCBOOKS)) \ $(patsubst %.sgml, %.pdf, $(DOCBOOKS)) \ $(patsubst %.sgml, %.html, $(DOCBOOKS)) \ - $(patsubst %.fig,%.eps, $(IMG-parportbook)) \ - $(patsubst %.fig,%.png, $(IMG-parportbook)) \ + $(patsubst %.sgml, %.9, $(DOCBOOKS)) \ + $(patsubst %.fig,%.eps, $(IMG-parportbook)) \ + $(patsubst %.fig,%.png, $(IMG-parportbook)) \ $(C-procfs-example) ifneq ($(wildcard $(patsubst %.html,%,$(HTML))),) clean-rule := rm -rf $(wildcard $(patsubst %.html,%,$(HTML))) endif + +#man put files in man subdir - traverse down +subdir- := man/ diff -Nru a/Makefile b/Makefile --- a/Makefile Fri Jul 18 23:21:44 2003 +++ b/Makefile Fri Jul 18 23:21:44 2003 @@ -236,7 +236,7 @@ noconfig_targets := xconfig gconfig menuconfig config oldconfig randconfig \ defconfig allyesconfig allnoconfig allmodconfig \ clean mrproper distclean rpm \ - help tags TAGS cscope sgmldocs psdocs pdfdocs htmldocs \ + help tags TAGS cscope %docs \ checkconfig checkhelp checkincludes RCS_FIND_IGNORE := \( -name SCCS -o -name BitKeeper -o -name .svn -o -name CVS \) -prune -o @@ -830,7 +830,7 @@ # Documentation targets # --------------------------------------------------------------------------- -sgmldocs psdocs pdfdocs htmldocs: scripts/docproc FORCE +%docs: scripts/docproc FORCE $(Q)$(MAKE) $(build)=Documentation/DocBook $@ # Scripts to check various things for consistency diff -Nru a/scripts/makeman b/scripts/makeman --- /dev/null Wed Dec 31 16:00:00 1969 +++ b/scripts/makeman Fri Jul 18 23:21:44 2003 @@ -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] \n"; +} + +if( ! -d "$ARGV[1]" ){ + die "Output directory \"$ARGV[1]\" does not exist\n"; +} + +if($ARGV[0] eq "convert"){ + open LISTING, "grep \"\" $ARGV[2] |"; + while(){ + 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] \n"; +} + +print "Done\n"; diff -Nru a/scripts/split-man b/scripts/split-man --- /dev/null Wed Dec 31 16:00:00 1969 +++ b/scripts/split-man Fri Jul 18 23:21:44 2003 @@ -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 \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(){ + # Starting modes + if(//){ + $mode = 1; + } + elsif(//){ + $mode = 2; + } + elsif(/]*>([^<]*)<.*$/){ + $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 "\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 "9\n"; + } + if(/<\/refentry>/){ + $front =~ s///; + $front =~ s/<\/legalnotice>//; + print REF <About this document +$front + +If you have comments on the formatting of this manpage, then please contact +Michael Still (mikal\@stillhq.com). + + + +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(/<\/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]`; - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/