Split this page into multiple pages, each one with more text explaining

that aspect of the Ports Collection. Remove all the static text from the portindex script and recast it into several SGML files that depend on a common entity file. Add back the alphabetical list of categories that was dropped in the last rework. Add many more references. Add useful left-side selections. Reviewed by: remko, pav, IONut, subdue, many others No objection on: freebsd-www
svn path=/www/; revision=26600
2005-12-15 01:02:28 +00:00 · 2005-12-15 01:02:28 +00:00 · 94a2f728dd · 2020-12-08 03:00:23 +00:00
commit 94a2f728dd
parent 7f6d5164b8
9 changed files with 402 additions and 37 deletions
--- a/en/ports/Makefile
+++ b/en/ports/Makefile
@ -1,4 +1,4 @@
-# $FreeBSD: www/en/ports/Makefile,v 1.44 2005/11/30 22:43:47 pav Exp $
+# $FreeBSD: www/en/ports/Makefile,v 1.45 2005/11/30 22:46:33 pav Exp $

 .if exists(../Makefile.conf)
 .include "../Makefile.conf"
@ -50,8 +50,19 @@ packages.exists:
 	${TOUCH} ${.TARGET}
 .endif

-Makefile.gen: index.sgml .NOTMAIN
+Makefile.gen: categories-alpha.sgml categories-grouped.sgml index.sgml \
+	installing.sgml master-index.sgml references.sgml searching.sgml \
+	statistics.ent updating.sgml .NOTMAIN
 	${ECHO_CMD} DOCS= *.sgml > Makefile.gen
+	${ECHO_CMD} -n "DYNAMIC_DOCS= " >> Makefile.gen
+	${ECHO_CMD} -n " categories-alpha.sgml" >> Makefile.gen
+	${ECHO_CMD} -n " categories-grouped.sgml" >> Makefile.gen
+	${ECHO_CMD} -n " master-index.sgml" >> Makefile.gen
+	${ECHO_CMD} -n " statistics.ent" >> Makefile.gen
+	for categoryfile in ${CATEGORYLIST}; do \
+		${ECHO_CMD} -n " $$categoryfile.sgml" >> Makefile.gen; \
+	done
+	${ECHO_CMD} >> Makefile.gen
 .if defined(NO_TIDY)
 	${ECHO_CMD} NO_TIDY=${NO_TIDY} >> Makefile.gen
 .endif
@ -70,8 +81,16 @@ ports.size:
 	${FETCH} -s ${PORTS_TARGZ_URL} > ${.TARGET}
 .endif

-index.sgml: ${INDEX} categories categories.descriptions packages.exists portindex ports.inc ports.size .NOTMAIN
-	${RM} -f *.sgml
+# this builds: categories-alpha.sgml, categories-grouped.sgml,
+# master-index.sgml, statistics.ent, <category>.sgml
+CATEGORYLIST=`grep "^[a-z]" categories | sed -e s"/,.*//"`
+categories-alpha.sgml: ${INDEX} categories categories.descriptions \
+	packages.exists portindex ports.ent ports.size .NOTMAIN
+	${RM} -f categories-alpha.sgml categories-grouped.sgml \
+		master-index.sgml statistics.ent
+	for categoryfile in ${CATEGORYLIST}; do \
+		rm -f "$$categoryfile.sgml"; \
+	done
 	${PORTINDEX} ${INDEX} ${.CURDIR}

 install: all beforeinstall
@ -86,6 +105,7 @@ beforeinstall:
 .else
 beforeinstall:
 	${SED} -i "" -e 's,HREF="growth,href="http://www.FreeBSD.org/ports/growth,' index.html
+	${SED} -i "" -e 's,HREF="growth,href="http://www.FreeBSD.org/ports/growth,' references.html
 .endif

 .include "${WEB_PREFIX}/share/mk/web.site.mk"
--- a/en/ports/Makefile.inc
+++ b/en/ports/Makefile.inc
@ -1,4 +1,4 @@
-# $FreeBSD: www/en/ports/Makefile.inc,v 1.7 2005/11/15 10:09:26 osa Exp $
+# $FreeBSD: www/en/ports/Makefile.inc,v 1.8 2005/11/30 22:43:47 pav Exp $

 PORTINDEX=	${PERL} ${.CURDIR}/portindex
 INDEX=		INDEX
@ -8,9 +8,9 @@ COOKIE=		${INDEX} Makefile.gen

 CLEANFILES+=	${INDEX} ${INDEX}.bz2
 CLEANFILES+=	packages.exists.temp  packages.exists
-CLEANFILES+= 	${DOCS} 
+CLEANFILES+= 	${DYNAMIC_DOCS} 
 CLEANFILES+=	Makefile.gen
-CLEANFILES+=	ports.size
+CLEANFILES+=	ports.count ports.size

 _ALLINSTALL= packages.exists ${INDEX} categories

--- a/en/ports/index.sgml
+++ b/en/ports/index.sgml
@ -0,0 +1,71 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" [
+<!ENTITY base CDATA '..'>
+<!ENTITY date "$FreeBSD$">
+<!ENTITY title 'About FreeBSD Ports'>
+<!ENTITY % navincludes SYSTEM "../includes.navports.sgml"> %navincludes;
+<!ENTITY % includes SYSTEM "../includes.sgml">
+<!ENTITY % ports.ent SYSTEM "ports.ent">
+<!ENTITY email 'ports'>
+%includes;
+%ports.ent;
+%statistics.ent;
+]>
+<HTML>&header;
+
+&searchform;
+
+<HR>
+
+<P>The FreeBSD Ports and Packages Collection offers a simple way for
+users and administrators to install applications.  There are currently
+<A HREF="growth/status.png"><B>&ports.count;</B></A> ports available.
+</P>
+
+<P>The Ports Collection supports the latest release on the
+<A HREF="&base;/doc/en_US.ISO8859-1/books/faq/introduction.html#CURRENT">
+FreeBSD-CURRENT</A> and
+<A HREF="&base;/doc/en_US.ISO8859-1/books/faq/introduction.html#STABLE">
+FreeBSD-STABLE</A> branches.  Older releases are not
+supported and may or may not work correctly with an up-to-date ports
+collection.  Over time, changes to the ports collection may rely on
+features that are not present in older releases.  Wherever convenient,
+we try not to gratuitously break support for recent releases, but it
+is sometimes unavoidable.  When this occurs, patches contributed by
+the user community to maintain support for older releases will usually
+be committed.
+</P>
+
+<P>Each ``port'' listed here
+contains any patches necessary to make the original application source
+code compile and run on FreeBSD.  Installing an application is as
+simple as downloading the port, unpacking it and typing
+<A HREF="http://www.freebsd.org/cgi/man.cgi?query=make"><TT>make</TT></A>
+in the port directory.  However, the most convenient (and common) method
+is to download the framework for the entire list of ports by installing the
+<!--<A HREF="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/ports/ports.tar.gz">-->
+<A HREF="installing.html">
+entire ports hierarchy</A> at FreeBSD installation time, and then have
+thousands of applications right at your fingertips.
+</P>
+
+<P>
+Each port's <TT>Makefile</TT> automatically fetches the
+application source code, either from a local disk, CDROM or via
+<A HREF="http://www.freebsd.org/cgi/man.cgi?query=ftp"><TT>ftp</TT></A>,
+unpacks it on your system, applies the patches, and compiles.  If
+all went well, a simple <TT>make install</TT> will install the
+application and register it with the package system.</P>
+
+<P>For most ports, a precompiled <TT>package</TT> also exists, saving
+the user the work of having to compile anything at all.  Each port
+contains a link to its corresponding package and you may either simply
+download that file and then run the
+<A HREF="http://www.freebsd.org/cgi/man.cgi?query=pkg_add"><TT>pkg_add</TT></A>
+command
+on it or you can simply grab the link location and hand it straight
+to <TT>pkg_add</TT> since it is capable of accepting FTP URLs as
+well as filenames.</P>
+
+&footer;
+</BODY>
+</HTML>
--- a/en/ports/installing.sgml
+++ b/en/ports/installing.sgml
@ -0,0 +1,30 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" [
+<!ENTITY base CDATA '..'>
+<!ENTITY date "$FreeBSD$">
+<!ENTITY title 'Installing the FreeBSD Ports Collection'>
+<!ENTITY % navincludes SYSTEM "../includes.navports.sgml"> %navincludes;
+<!ENTITY % includes SYSTEM "../includes.sgml">
+<!ENTITY % ports.ent SYSTEM "ports.ent">
+<!ENTITY email 'ports'>
+%includes;
+%ports.ent;
+%statistics.ent;
+]>
+<HTML>&header;
+
+&searchform;
+
+<HR>
+
+<P>If you are installing FreeBSD from CDROM or an ftp site, the
+  <A HREF="&base;/cgi/man.cgi?query=sysinstall"><TT>sysinstall</TT></A>
+  application will allow you to install the Ports Collection directly.</P>
+
+<P>However, if you are not installing using that method, you may
+  <A HREF="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/ports/ports.tar.gz">
+  download the gzipped tarball</A> for the entire ports hierarchy.  The
+  size of the file is &ports.size;.</P>
+
+&footer;
+</BODY>
+</HTML>
--- a/en/ports/portindex
+++ b/en/ports/portindex
@ -1,10 +1,10 @@
 #!/usr/bin/perl -w

-# convert a ports INDEX file to HTML
+# convert a ports INDEX file to SGML files
 #
 # by John Fieber <jfieber@FreeBSD.org>
 # Mon May 13 10:31:58 EST 1996
-# $FreeBSD: www/en/ports/portindex,v 1.54 2005/11/15 10:09:26 osa Exp $
+# $FreeBSD: www/en/ports/portindex,v 1.55 2005/11/29 18:11:47 pav Exp $

 ############################################################

@ -75,13 +75,20 @@ sub header {
 <!ENTITY base CDATA '..'>
 <!ENTITY date  "<em>$today</em>">
 <!ENTITY title '$htext'>
-<!ENTITY blurb  SYSTEM "ports.inc">
-<!ENTITY % navincludes SYSTEM "../includes.navdownload.sgml"> %navincludes;
+<!ENTITY % navincludes SYSTEM "../includes.navports.sgml"> %navincludes;
 <!ENTITY % includes SYSTEM "../includes.sgml">
+<!ENTITY % ports.ent SYSTEM "ports.ent">
 <!ENTITY email 'ports'>
 %includes;
+%ports.ent;
+%statistics.ent;
 ]>
 <html>&header;
+
+&searchform;
+
+<hr>
+
 EOF
 }

@ -168,6 +175,7 @@ sub main {
    my $moutf = new IO::File;
    my $outf = new IO::File;
    my $mindex = new IO::File;
+    my $statistics = new IO::File;

    open(INDEX, $ARGV[0]);
    $portnumber = "0";
@ -267,32 +275,13 @@ sub main {
 	$portnumber++;
    }

-    my $ptgzsize = `cat ports.size 2>/dev/null` || "";
-    if ($ptgzsize =~ /^\d+$/) {
-       $ptgzsize = sprintf("%.0f", $ptgzsize/(1024*1024));
-    } else {
-       warn "Unknown size for ports.tar.gz\n";
-    }
+    # create categories-grouped.sgml and <category>.sgml

-    $moutf->open(">index.sgml");
+    $moutf->open(">categories-grouped.sgml");
+    header($moutf, "FreeBSD Ports Categories Listed By Groups");

-    header($moutf, "FreeBSD Ports");
-#   print $moutf "<!--#include virtual=\"./ports.inc\" -->\n";
-    print $moutf "&blurb;";
    print $moutf <<EOF;
-<HR>
-<H3>Current status</H3>
-<P>There are currently $portnumber ports in the FreeBSD Ports Collection.<BR>
-You may
-<A HREF="$baseFTP/ports.tar.gz">download a gzip'd tar file of all ports</A>
-EOF
-    print $moutf "(about $ptgzsize megabytes)" if ($ptgzsize =~ /^\d+$/);
-    print $moutf <<EOF;
-, view the
-<A HREF=\"master-index.html\">alphabetical list of all ports</A>,
-or browse the ports in the following categories:
-<A NAME=\"categories\"></A>
-</P>
+<A NAME=\"top\"></A>
 EOF

    if ($portnumber eq '0') {
@ -330,7 +319,7 @@ EOF
 	    $d =~ s/##([^#]*)##/$catkey{$1}/g;
 	    print $outf $d;
 	    print $outf "</DL>\n";
-	    footer($outf, "<p></p><A HREF=\"index.html#categories\">Port Categories</A>" .
+	    footer($outf, "<p></p><A HREF=\"#top\">top</A>" .
 		" -- <A HREF=\"master-index.html\">Index</A>");
 	    $outf->close;
 	}
@ -341,13 +330,60 @@ EOF
    footer($moutf, "");
    $moutf->close;

-    # Create the master index file
+    # create categories-alpha.sgml
+
+    $moutf->open(">categories-alpha.sgml");
+    header($moutf, "FreeBSD Ports Categories Listed Alphabetically");
+
+    print $moutf <<EOF;
+<A NAME=\"top\"></A>
+EOF
+
+    if ($portnumber eq '0') {
+      print $moutf "<P>none found</P>\n";
+    } else {
+      print $moutf "<UL>\n";
+      foreach my $key (sort(keys(%stats))) {
+	print $moutf
+	  "<LI><A HREF=\"$key.html\">\u$key</A> <em>($stats{$key})</em>";
+	if ($category_description{$key}{desc}) {
+	  print $moutf " -- " . $category_description{$key}{desc};
+	print $moutf "</LI>\n";
+	}
+      }
+      print $moutf "</UL>\n";
+    }
+
+    footer($moutf, "");
+    $moutf->close;
+
+    # Create master-index.sgml
+
    $mindex->open(">master-index.sgml");
    header($mindex, "FreeBSD Ports Collection Index");
    print $mindex "<P>\n";
    print $mindex sort @master;
    print $mindex "</P>";
-    footer($mindex, "<A HREF=\"index.html#categories\">Port Categories</A>");
+    footer($mindex, "<A HREF=\"#top\">top</A>");
    $mindex->close;
+
+    # Create statistics.ent
+
+    $statistics->open(">statistics.ent");
+
+    # doesn't seem to work:
+    # print $statistics "<!ENTITY date '<em>$today</em>'>\n";
+
+    my $ptgzsize = `cat ports.size 2>/dev/null` || "";
+    if ($ptgzsize =~ /^\d+$/) {
+       $ptgzsize = sprintf("%.0f", $ptgzsize/(1024*1024));
+       print $statistics "<!ENTITY ports.size 'about $ptgzsize megabytes'>\n";
+    } else {
+       warn "Unknown size for ports.tar.gz\n";
+       print $statistics "<!ENTITY ports.size 'several tens of megabytes'>\n";
+    }
+    print $statistics "<!ENTITY ports.count '$portnumber'>\n";
+
+    $statistics->close;
    close(INDEX);
 }
--- a/en/ports/ports.ent
+++ b/en/ports/ports.ent
@ -0,0 +1,26 @@
+<!-- $FreeBSD$ -->
+
+<!ENTITY searchform '<FORM METHOD="GET" ACTION="http://www.FreeBSD.org/cgi/ports.cgi">
+Search ports for:
+<INPUT NAME="query" VALUE="">
+<SELECT NAME="stype">
+<OPTION VALUE="all">All</OPTION>
+<OPTION VALUE="name">Package Name</OPTION>
+<OPTION VALUE="text">Description</OPTION>
+<OPTION VALUE="pkgdescr">Long description</OPTION>
+<OPTION VALUE="maintainer">Maintainer</OPTION>
+<OPTION VALUE="requires">Requires</OPTION>
+</SELECT>
+<INPUT TYPE="submit" VALUE="Submit">
+</FORM>'>
+
+<!ENTITY % statistics.ent SYSTEM "statistics.ent">
+
+<!-- 
+     Local Variables:
+     mode: sgml
+     sgml-indent-data: t
+     sgml-omittag: nil
+     sgml-always-quote-attributes: t
+     End:
+-->
--- a/en/ports/references.sgml
+++ b/en/ports/references.sgml
@ -0,0 +1,90 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" [
+<!ENTITY base CDATA '..'>
+<!ENTITY date "$FreeBSD$">
+<!ENTITY title 'FreeBSD Ports -- References'>
+<!ENTITY % navincludes SYSTEM "../includes.navports.sgml"> %navincludes;
+<!ENTITY % includes SYSTEM "../includes.sgml">
+<!ENTITY % ports.ent SYSTEM "ports.ent">
+<!ENTITY email 'ports'>
+%includes;
+%ports.ent;
+%statistics.ent;
+]>
+<html>&header;
+
+&searchform;
+
+<HR>
+
+<P>To start learning more about ports and packages, see
+  <A HREF="&base;/doc/en_US.ISO8859-1/books/handbook/ports.html">
+  Installing Applications: Packages and Ports</A>, a section of the
+  <A HREF="&base;/doc/en_US.ISO8859-1/books/handbook/index.html">
+  FreeBSD Handbook</A>.
+</P>
+
+<P>The
+  <A HREF="&base;/doc/en_US.ISO8859-1/books/porters-handbook/index.html">
+  Porter's Handbook</A> is the master reference for both creating new
+  ports and maintaining existing ports, including a section on
+  <A HREF="&base;/doc/en_US.ISO8859-1/books/porters-handbook/keeping-up.html">
+  Keeping Up</A>.  It also contains more detail about the topics below, as
+  well as more references for further study.
+</P>
+
+<P>You may also find the following to be useful:</P>
+
+<UL>
+  <LI>The archives of the
+    <A HREF="http://docs.FreeBSD.org/mail/current/freebsd-ports.html">
+    FreeBSD ports mailing list</A>.
+  </LI>
+
+  <LI>The article
+    <A HREF="&base;/doc/en_US.ISO8859-1/articles/contributing-ports/index.html">
+    Contributing to the FreeBSD Ports Collection</A>.
+  </LI>
+
+  <LI>
+    <A HREF="http://www.FreshPorts.org">FreshPorts.org</A> is a
+    valuable tool for further information about individual ports,
+    such as current version, last checkin, and many other useful
+    statistics.  You may subscribe to a mailing list to get the
+    latest information about your favorite ports.
+  </LI>
+
+ <LI>Here is a graph of the
+   <A HREF="growth/status.png">rapid rate of growth</A>
+   of the Ports Collection.</LI>
+
+  <LI>The manual pages for
+    <A HREF="&base;/cgi/man.cgi?query=ftp"><TT>ftp</TT></A>,
+    <A HREF="&base;/cgi/man.cgi?query=pkg_add"><TT>pkg_add</TT></A>, and
+    <A HREF="&base;/cgi/man.cgi?query=ports"><TT>ports</TT></A>.
+  </LI>
+
+  <LI>The
+    <A HREF="http://pointyhat.FreeBSD.org">ports and packages build cluster</A>.
+  </LI>
+
+  <LI>The
+    <A HREF="&base;/www/en/portmgr/">Ports Management Team</A> (portmgr) pages.
+  </LI>
+
+  <LI>The
+    <A HREF="http://cvsweb.FreeBSD.org">
+    Web Interface to the Source Repository</A>
+    allows you to browse the files in the source repository.  Changes
+    that affect the entire port system are now documented in the
+    <A HREF="http://cvsweb.FreeBSD.org/ports/CHANGES">CHANGES</A> file.
+    Changes that affect individual ports are now documented in the
+    <A HREF="http://cvsweb.FreeBSD.org/ports/UPDATING">UPDATING</A> file.
+    However, the definitive answer to any question is undoubtedly to read
+    the source code of <A HREF="http://cvsweb.FreeBSD.org/ports/Mk/bsd.port.mk">
+    bsd.port.mk</A>, and associated files.
+  </LI>
+</UL>
+
+&footer;
+</BODY>
+</HTML>
--- a/en/ports/searching.sgml
+++ b/en/ports/searching.sgml
@ -0,0 +1,40 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" [
+<!ENTITY base CDATA '..'>
+<!ENTITY date "$FreeBSD$">
+<!ENTITY title 'Updating FreeBSD Ports'>
+<!ENTITY % navincludes SYSTEM "../includes.navports.sgml"> %navincludes;
+<!ENTITY % includes SYSTEM "../includes.sgml">
+<!ENTITY % ports.ent SYSTEM "ports.ent">
+<!ENTITY email 'ports'>
+%includes;
+%ports.ent;
+%statistics.ent;
+]>
+<HTML>&header;
+
+&searchform;
+
+<HR>
+
+<P>
+The form above will allow you to search for ports on this site.
+A completed search will take you to a
+<A HREF="&base;/cgi/ports.cgi">more complete search page</A>.
+</P>
+
+<P>However, if you already have the Ports Collection installed on
+your machine, you may also search by changing to the <TT>/usr/ports</TT>
+directory and performing <TT>make search name=</TT><EM>string</EM>.
+See <A HREF="http://cvsweb.FreeBSD.org/ports/Mk/bsd.port.subdir.mk">
+bsd.port.subdir.mk</A> for all the options.
+</P>
+
+<P>
+Another option is to visit
+<A HREF="http://www.FreshPorts.org">FreshPorts.org</A>
+and either browse the site or subscribe to the lists hosted there.
+</P>
+
+&footer;
+</BODY>
+</HTML>
--- a/en/ports/updating.sgml
+++ b/en/ports/updating.sgml
@ -0,0 +1,52 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" [
+<!ENTITY base CDATA '..'>
+<!ENTITY date "$FreeBSD$">
+<!ENTITY title 'Updating FreeBSD Ports'>
+<!ENTITY % navincludes SYSTEM "../includes.navports.sgml"> %navincludes;
+<!ENTITY % includes SYSTEM "../includes.sgml">
+<!ENTITY % ports.ent SYSTEM "ports.ent">
+<!ENTITY email 'ports'>
+%includes;
+%ports.ent;
+%statistics.ent;
+]>
+<HTML>&header;
+
+&searchform;
+
+<HR>
+
+<P>
+The ports listed on these web pages are continually being updated.
+It is strongly recommended that you refresh the entire collection
+together, as many ports depend on other parts of the tree, even
+where that might seem counterintuitive (e.g. <TT>japanese/</TT>.)
+</P>
+
+<P>Changes that affect the entire port system are now documented in the
+<A HREF="http://cvsweb.FreeBSD.org/ports/CHANGES">CHANGES</A> file.
+Changes that affect individual ports are now documented in the
+<A HREF="http://cvsweb.FreeBSD.org/ports/UPDATING">UPDATING</A> file.
+</P>
+
+<P>For more information about new, changed or removed ports/packages,
+or if you wish to search for a specific application to see if it's
+available as a port/package, you may use the form above; alternatively,
+you may wish to visit
+<A HREF="http://www.FreshPorts.org">FreshPorts.org</A>
+and either browse the site or subscribe to the lists hosted there.
+</P>
+
+<P>To learn more about installing and maintaining ports, see
+<A HREF="&base;/doc/en_US.ISO8859-1/books/handbook/ports.html">
+Installing Applications: Packages and Ports</A>, a section of the
+<A HREF="../doc/en_US.ISO8859-1/books/handbook/index.html">
+FreeBSD Handbook</A>; the section of the Porter's Handbook called
+<A HREF="&base;/doc/en_US.ISO8859-1/books/porters-handbook/keeping-up.html">
+Keeping Up</A>; and the
+<A HREF="&base;/cgi/man.cgi?query=ports"><TT>ports manual page</TT></A>.
+</P>
+
+&footer;
+</BODY>
+</HTML>