From owner-freebsd-doc Mon Dec 14 16:05:54 1998 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id QAA06257 for freebsd-doc-outgoing; Mon, 14 Dec 1998 16:05:54 -0800 (PST) (envelope-from owner-freebsd-doc@FreeBSD.ORG) Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id QAA05916 for ; Mon, 14 Dec 1998 16:05:43 -0800 (PST) (envelope-from nik@nothing-going-on.demon.co.uk) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.8.8/8.8.8) id AAA28295; Tue, 15 Dec 1998 00:05:28 GMT (envelope-from nik) Message-ID: <19981215000528.38029@nothing-going-on.org> Date: Tue, 15 Dec 1998 00:05:28 +0000 From: Nik Clayton To: doc@FreeBSD.ORG Subject: New page for mailing lists / projects / resources Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.89.1i Organization: Nik at home, where there's nothing going on Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org What is this? This is a new structure for presenting some information on the FreeBSD web site. Specifically, it's for mailing lists, projects, and resources. I've often thought that the structure of information on the site could use a little work. In particular, a lot of the development effort for FreeBSD centres around the mailing lists. Yet there's no one place subscribers to each list can go to find useful information. Similarly, the list of FreeBSD projects is organised along similar lines to the mailing lists, but they're not cross-referenced. Finally, there's information that's not directly tied to active projects -- for example, resources concerned with advocating FreeBSD. What I really wanted was, for each list, a single page that contained everything I needed -- all the resources of use to members of the list, a list of projects currently involving list members, recommendations for other lists that subscribers might be interested in, a way to search the list, a way to subscribe, and so on. All on one page. Of course, there are times this isn't appropriate. Sometimes you just want a big list of all the projects, or all the resources. It can be very tedious to have to follow umpteen different links, printing each page. So it was important that (at least some of) the information about each mailing list could be collated together on to one page. This is a snap if your site is coming out of a database. But the FreeBSD site isn't. So I've done this using Perl. What do you do? Go and take a look at and play around. From that page you can choose to view the information in one of three ways; 1. Mailing-list-centric See information about each list. Follow the links to go to a page for each list, where you can search the list, subscribe to the list (not yet functional), and view projects and resource appropriate to members of that list. You also get a list of other lists you might want to subscribe to. 2. Project-centric. See a list of the current known projects, organised by mailing list. 3. Resource-centric See a list of the current known resources, organised by mailing list. Note that a list may not necessarily have any projects or resources associated with it, or it might have one, or both. What now? Is this useful? If so, it'll get committed. If not, it won't. I realise it duplicates some information in the Handbook. In this instance, I'd be fairly happy to have the mailing list information eventually disappear from the Handbook (beyond a note explaining where to look on the website for more information). I've also only done a few lists, and they're incomplete. This is just so that people can play around with the idea, and give me feedback. Most of the links to projects and resources that are on the FreeBSD site won't work, because these files are built with paths assuming they're part of the FreeBSD site, as opposed to being part of my home page. N ------------------------------------------------------------------------ Implementation details lists.tar.gz contains the SGML used to create this, as well as the other scripts. You can download it (from the lists/ directory), and unpack it in a checked out copy of the web site source. You'll need to make a lists/ directory for it though. You can rebuild the HTML by typing "make". You might need to apply execute permissions to build_lpr.pl first. Ignore the top level directory for a moment, and look at the hackers/ directory. Makefile is a fairly standard Makefile. If you've got more than an index file in this directory (see advocacy/ for an example) then the "DOCS=" line will need to be expanded. Otherwise, this is all it needs to do. about.sgml must exist for each list. It's a paragraph or two of description about the list. This will appear on the main list page, as well as the list of all mailing lists. otherlists.sgml is a simple list of other mailing lists the user might be interested in. projects.sgml and resources.sgml are HTML fragments that list the projects and resources appropriate for this list. Note that this HTML will be included in files that appear at two different positions in the tree, so any URLs must be absolute at least as far as the root document. By that I mean you can't put in
  • Random resource
    • You *must* put in code like
  • Random resource
    • otherwise links will break. This shouldn't be a problem, even for mirrors. list.ent defines three entities, list-title, list-name, and list-desc. list-name is the lower case list name (as it would appear in an e-mail address), list-title is mixed case. There's no real reason these are separate. They could also be derived from the directory name. list-desc is a longer description, as appropriate. For example, list-desc for "freebsd-fs" is "Filesystems", which makes more sense when viewed standalone. That's all the files you need to define a mailing list. Notice that there's no index.sgml file in here. This is where things get a little more complicated. index.sgml is generated by the Makefile in this directory (by code in ../list.mk). It just symlinks ../list-index-template.sgml to index.sgml. I'll talk about list-index-template.sgml in a bit. How go back up to the lists/ directory. 4 HTML files are built. index.html is from index.sgml, and is produced in the standard way. lists.sgml, projects.sgml, and resources.sgml are used to produce their respective .html files. These three files are generated by build_lpr.pl, a small Perl script. This script checks that the bare minimum files for list exist. Then it produces the three .sgml files. For lists.sgml, the contents of each lists' about.sgml file are pulled into the lists.sgml file. The same thing happens for projects.sgml and resources.sgml (but using each lists' projects.sgml and resources.sgml file as appropriate). However, these two need to check that the file exists before doing the inclusion, since a list might not have one or both of these files. list-index-template.sgml is the master file for the index.sgml files for each list. The top of this file defines 4 special general entities, and 5 parameter entity. The general entities are 'about', 'projects', 'resources', and 'otherlists'. Each one of these has an associated parameter entity with a "do-" prefix. These are all originally set to "IGNORE". These are then used further down in the of the HTML to determine whether or not the *.sgml files are included or not. These parameter entities may be overridden on the sgmlnorm(1) command line. Code in lists.mk checks to see whether each one of those files exists. If it does, the "-i" option is used to change the "IGNORE" directive to "INCLUDE". In this way, the .sgml files are only included in the lists' index.html file if they already exist. The fifth parameter entity is list.ent, which is pulls in the list.ent file. That's it. It's pretty simple really. -- C.R.F. Consulting -- we're run to make me richer. . . To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message