Date: Tue, 15 Dec 1998 00:05:28 +0000 From: Nik Clayton <nik@nothing-going-on.demon.co.uk> To: doc@FreeBSD.ORG Subject: New page for mailing lists / projects / resources Message-ID: <19981215000528.38029@nothing-going-on.org>
next in thread | raw e-mail | index | archive | help
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
<URL:http://www.freebsd.org/~nik/lists/lists.html>;
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
<li><a href="../foo.html">Random resource</a></li>
You *must* put in code like
<li><a href="/lists/foo.html">Random resource</a></li>
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 <body> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19981215000528.38029>