Date: Wed, 15 Sep 1999 23:13:06 +0100 From: Nik Clayton <nik@freebsd.org> To: doc@freebsd.org, ports@freebsd.org Subject: Building a page of installed software docs Message-ID: <19990915231305.A31588@kilt.nothing-going-on.org>
next in thread | raw e-mail | index | archive | help
[ Sent to -doc and -ports, as it's appropriate for both. I'm throwing this
out in the hope that someone's sufficiently intrigued to try implementing
it. I'm a little snowed at the moment. ]
A lot of FreeBSD third party packages include documentation over and above
the traditional manual page, in a variety of formats -- HTML, PS, and so
on.
Does anyone else think it would be useful if 'the system' could
automatically maintain an index page on behalf of the user (say,
/usr/local/share/doc/index.html). This file wouldn't be part of any one
port, but it would include links to all the HTML manuals that have been
installed so far -- it could also include links to the HTML documentation
that's been installed from the FDP.
Some as yet unwritten program could sit in /usr/local/etc/rc.d and rebuild
this file automatically at boot time, or perhaps make it a part of
/etc/periodic/daily*, or something like that? So that the user can just
point their browser at file:/usr/local/share/index.html and quickly
navigate through the installed documentation. This would also need to be
rebuilt when ports/packages are added/removed.
I think this is probably a good idea, but I'm not sure as to the best way to
implement it. This hypothetical rebuild-index.html-from-scratch script
needs to know which files form the 'root' of the documentation for a
particular package. Unfortunately, you can't just say "Anything that's
called 'index.html'", as not all apps follow this convention. For example,
bzip2's manual root is called manual_toc.html, tidy's root is Overview.html,
and so on.
I thought about suggesting an additional Makefile variable, that could list
the name of the installed root file -- that fails for things that aren't
built from the ports tree, such as doc/*, so that's probably out.
A fairly bullet proof approach (I think) would be another file in the port's
pkg/ directory. Maybe a pkg/URLS file that listed (one per line) the URLs
that are useful for this port, and the text of the link that should be used
for that URL.
I'm aware that we already have the WWW: entry in pkg/DESCR, but I'm not sure
that's really extendable to this idea, and it would involve putting more
information in pkg/DESCR which probably doesn't belong there.
Thinking about it, this should probably not be limited to just the HTML
documentation that's installed. There's no reason why bzip2 couldn't
have a pkg/URLS file that looked something like
${PREFIX}/share/doc/bzip2/manual_toc.html:HTML:User manual
${PREFIX}/share/doc/bzip2/manual.ps:PS:User manual
${PREFIX}/share/doc/bzip2/manual.txt:TXT:User manual
which would turn in to
<h3>archivers/bzip2</h3>
<ul>
<li>User Manual [<a href="file:/.../manual_toc.html">HTML</a>]
[<a href="file:/.../manual.txt">TXT</a>]
[<a href="file:/.../manual.ps">PS</a>]</li>
</ul>
The extra flexibility is to cater for ports like Postgres which has
a FAQ (plain text), an admin guide (HTML and PS), a Postgres guide
(HTML and PS), a programmer's guide (HTML and PS), a user's guide, and
so on. That might be entered as
${PREFIX}/share/doc/pgsql/FAQ:TXT:FAQ
${PREFIX}/share/doc/pgsql/admin/admin.ps.gz:PS:Administrator's Guide
${PREFIX}/share/doc/pgsql/admin/index.html:HTML:Administrator's Guide
${PREFIX}/share/doc/pgsql/programmer/index.html:HTML:Programmer's Guide
...
...
That's probably not quite complicated enough, because I haven't considered
what happens when multiple languages and encodings get involved. But it
gives an outline of the sort of thing I'm thinking about.
So, ports team, how feasible is this? I don't think the URLS file needs
to be mandatory, it's just an extra piece of functionality that can
be used if it's present in the port, and ignored if it isn't.
Docs team, any ideas or suggestions for improvements?
And, assuming this is met with broad agreement, is anyone looking for an
interesting project? As I say, I'm not going to get the chance to think
about implementing something like this for 3 or 4 months, and I'm more than
happy for someone to stroll off with this idea and actually do the
implementation work. . .
N
--
[intentional self-reference] can be easily accommodated using a blessed,
non-self-referential dummy head-node whose own object destructor severs
the links.
-- Tom Christiansen in <375143b5@cs.colorado.edu>
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-ports" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990915231305.A31588>