Date: Wed, 6 Sep 2000 00:25:40 +0100 From: Mark Ovens <marko@freebsd.org> To: doc@freebsd.org Cc: Andrew Boothman <andrew@dogma.freebsd-uk.eu.org> Subject: Ports Documentation Index - the next installment Message-ID: <20000906002540.M254@parish>
next in thread | raw e-mail | index | archive | help
[-- Attachment #1 --]
I've been doing some work on the perl(1) scripts that Andrew Boothman
started sometime ago that create /var/db/pkg/${PORTNAME}/+DOCS for
each installed port and then build an HTML file containing links to
all the installed docs.
The changes I've made are:
1. Improved the weeding out of non-doc files (it uses the
+CONTENTS file).
2. The HTML file now has the ports sorted alphabetically.
3. The HTML file now has an index of all the installed
ports (that have docs) at the top with the port name as a link
(followed by the contents of the +COMMENT file) to the list of
docs, which have a link back to the top.
4. The filename is displayed instead of "Title Unknown" for
non-HTML files (although HTML files that have no
<title></title> tag are still listed as "Title Unknown").
I've attached 3 files:
docsmaker - builds the +DOCS files.
docindex.pl - builds the HTML page from the +DOCS files.
mkindex.sh - A wrapper script to run the other 2 files.
Put them all in the same directory and run mkindex.sh from that
directory (the other 2 files are called as ./<filename>).
The resulting HTML file is /usr/local/share/doc/index.html
I'd appreciate people trying this out on their system (it works fine
with all the ports I have installed on mine) and giving feedback,
suggestions for further features/improvements, any examples of ports
that it doesn't work with, etc.
CAVEATS:
It may or may not included the standard FreeBSD docs
(Handbook, FAQ, etc.) in the HTML file depending on where they
are installed on your system.
I'm just a beginner at perl, so not too many flames about the
code, eh? (Hot Tips and friendly advice accepted :))
There are still some debugging print() statements that
spew out a lot of stuff to STDOUT when docsmaker runs.
--
4.4 - The number of the Beastie
________________________________________________________________
51.44°N FreeBSD - The Power To Serve http://www.freebsd.org
2.057°W My Webpage http://ukug.uk.freebsd.org/~mark
mailto:marko@freebsd.org http://www.radan.com
[-- Attachment #2 --]
#!/usr/bin/perl -w
# Produces a DOCS file for a port
# These 2DOCS files are used by a seperate script
# to generate an list of documentation installed
# by the ports/packages system
# See http://ukug.uk.FreeBSD.org/~andrew/docindex/
# By Andrew Boothman <andrew@cream.org>
# Modified by Mark Ovens <marko@freebsd.org>
# Check we have the correct number of arguments
if ($#ARGV < 1) {
print 'Usage : docsmaker /path/to/+CONTENTS/file ';
print '/path/to/new/+DOCS/file';
print "\n\n";
} else {
# Open the +CONTENTS file
open 'CONTENTS',$ARGV[0] or die "cannot open $ARGV[0]";
open 'DOCS',">$ARGV[1]" or die "cannot open $ARGV[1]";
@contents = <CONTENTS>;
chomp @contents;
close 'CONTENTS';
$doccounter = 0;
foreach(@contents) {
if (substr($_, 0, 4) eq '@cwd') {
$basepath = substr($_, , 5);
print "Base Path now : $basepath\n";
} elsif (substr($_, 0, 5) eq '@name') {
print 'Port Name : '.substr($_, , 6)."\n";
} elsif (substr($_, 0, 1) eq '@') {
next;
} else {
$filetype = isadoc("$basepath/$_");
if ($filetype eq "") {
next;
} # if ($filetype eq "")
if ($filetype eq "html") {
$doccounter++;
print "$basepath/$_...HTML...";
open 'HTMLDOC',"$basepath/$_" or die
"Cannot open $basepath/$_";
$title = '';
until (eof 'HTMLDOC' || $title ne '') {
chomp ($htmlline = <HTMLDOC>);
if ($htmlline =~ /<TITLE/i) {
print "Titled...";
$index = index(lc($htmlline), "<title");
while ($htmlline !~ /<\/TITLE/i) {
chomp($scrap = <HTMLDOC>);
$htmlline = "$htmlline"."$scrap";
} # while
$c = substr($htmlline, $index + 7);
$index = index(lc($c), "</title");
$title = substr($c, 0, $index);
if ($title =~ s/:/-/ > 0) {
print "':' -> '-'...";
} # if ($title =~ s/:/-/ > 0)
} # if ($htmlline =~ /<TITLE/i)
} # until (eof 'HTMLDOC' || $title ne '')
if ($title eq '') {
print "Titling failed...";
$title = "Title Unknown";
} # if ($title eq '')
close 'HTMLDOC';
print DOCS "$title:HTML:$basepath/$_\n";
print "Done!\n";
} else { # if ($filetype eq "html")
$doccounter++;
print("basepath \= $basepath\n");
($temp = $_) =~ s#.*/##;
print (DOCS "$temp:".uc($filetype).":$basepath/$_\n");
} # else
} # else
} # foreach(@contents)
close 'DOCS';
print "\nDocuments put in DOCS file : $doccounter\n\n";
if ($doccounter == 0) {
print 'Removing unused new +DOCS file...';
unlink $ARGV[1];
print "Done!\n";
} # if ($doccounter == 0)
} # MAIN
sub isadoc {
local $_;
# Need the ``?'' with "html" so we get both
# *.html and *.htm
@docs = ("txt", "html?", "ps", "pdf", "texi");
@not_docs = ("bmp", "icon", "gif", "jpg", "xbm", "xpm");
foreach (@not_docs) {
if ($_[0] =~ /\.$_\Z/i) {
return "";
}
}
foreach (@docs) {
if ($_[0] =~ /\.$_\Z/i) {
s/\?$//; # strip the ``?'' from "html?"
return $_;
}
}
}
[-- Attachment #3 --]
#!/usr/bin/perl
# Produces an HTML list of documentation installed by
# the FreeBSD ports system. Intended to be run daily
# from /var/periodic/daily or on startup by rc
# See http://ukug.uk.FreeBSD.org/~andrew/docindex/
# By Andrew Boothman <andrew@cream.org>
# Modified by Mark Ovens <marko@freebsd.org>
# If any documentation has been altered since we last made the index
# then build it again, else don't bother
if (-M '/var/db/pkg' < -M '/usr/local/share/doc/index.html' | -M '/usr/share/doc/en_US.ISO_8859-1/books/handbook/index.html' < -M '/usr/local/share/doc/index.html' | -M '/usr/share/doc/en_US.ISO_8859-1/books/faq/book.html' < -M '/usr/local/share/doc/index.html') {
open INDEXFILE, '>/usr/local/share/doc/index.html';
opendir PORTSDIR, '/var/db/pkg' or die "docindex: Can't open /var/db/pkg";
@allfiles = sort(readdir (PORTSDIR));
closedir 'PORTSDIR';
print INDEXFILE '<HTML>
<HEAD>
<A NAME=top></A>
<TITLE>Installed FreeBSD Documentation</TITLE>
</HEAD>
<BODY>
<H2>Installed FreeBSD Documentation</H2>
<HR>
<H4>Standard FreeBSD Documentation</H4>
<UL>';
# if (-e '/usr/share/doc/handbook/handbook.html') {
if (-e '/usr/share/doc/en_US.ISO_8859-1/books/handbook/index.html') {
print INDEXFILE '<LI>FreeBSD Handbook [<A HREF="/usr/share/doc/en_US.ISO_8859-1/books/handbook/index.html">html</A>]';
};
# if (-e '/usr/share/doc/FAQ/FAQ.html') {
if (-e '/usr/share/doc/en_US.ISO_8859-1/books/faq/book.html') {
print INDEXFILE '<LI>FreeBSD FAQ [<A HREF="/usr/share/doc/en_US.ISO_8859-1/books/faq/book.html">html</A>]';
};
print INDEXFILE '</UL><H4>Installed Documentation from Ports or Packages</H4><UL>';
$i = 0;
$j = 0;
foreach(@allfiles){
# Check if each of the files we've found is a directory
# with the +DOCS file in it
if (-e "/var/db/pkg/$_/+DOCS") {
$comment = "";
if (-e "/var/db/pkg/$_/+COMMENT") {
open COMFILE, "/var/db/pkg/$_/+COMMENT";
$comment = <COMFILE>;
close COMFILE;
}
$index[$i++] = "<LI><A HREF=#$_>$_</A> - $comment\n";
$list[$j++] = "<H2><A NAME\=$_>$_\n</A></H2><UL>";
open 'DOCS',"/var/db/pkg/$_/+DOCS";
@docs = <DOCS>;
close 'DOCS';
chomp @docs;
foreach(@docs) {
@docinfo = split(/:/);
$list[$j++] = "<LI><A HREF=\"$docinfo[2]\">
$docinfo[0]</A> - ($docinfo[1])\n";
};
$list[$j++] = "</UL>";
$list[$j++] = "<A HREF=index.html>Back to index</A>\n";
};
};
$index[$i] = "</UL>\n";
print INDEXFILE @index;
print INDEXFILE @list;
print INDEXFILE "</UL>\n";
$localtime = localtime;
print INDEXFILE "</UL>\n<HR>Last Updated : $localtime</BODY></HTML>";
};
[-- Attachment #4 --]
#! /bin/sh
PKG_DIR=/var/db/pkg
for FILE in `ls ${PKG_DIR}`
do
if [ -f "${PKG_DIR}/${FILE}/+CONTENTS" ];
then
echo ${PKG_DIR}/${FILE}
./docsmaker ${PKG_DIR}/${FILE}/+CONTENTS ${PKG_DIR}/${FILE}/+DOCS
fi
done
# This is just for testing/debugging purposes to force
# docindex.pl to rebuild the index file
rm -f /usr/local/share/doc/index.html
./docindex.pl
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000906002540.M254>