On Sun, Oct 24, 1999 at 08:34:24PM +0100, Daniel Barlow wrote:
> The structure is heavily influenced by what the FreeBSD people have
> done, so start by reading Nik Clayton's previous post to this list at
> http://linuxchix.devin.com/techwriters/1999-Aug/0184.html
Great to know that others are finding our work useful.
> 2) We can't make the packaging system work for us as seamlessly as
> they can, because we have to cater for multiple systems and
> distributions. (This is not just Red Hat Linux ...)
>
> There is a top-level directory /oswg/bin in which people are invited to
> place scripts that will do the appropriate thing on their system to
> turn SGML into HTML or PS or ..., to install manual pages, to
> produce an RPM, whatever.
Split the Makefiles in to common and OS specific files. oswg.docbook.mk,
oswg.redhat-linux.mk, oswg.debian-linux.mk, oswg.freebsd.mk, and so on.
Have the common Makefile examine the output of uname, or similar, and
work out which of the OS specific Makefiles to include. The OS specific
Makefiles contain definitions for the standard installation directories,
programs to use to to do the installing, UIDs and GIDs to install as, and
so on.
> 3) There is no big top-level Makefile. I don't even know if people
> will want to check out the whole repository if they're only working
> on one document, so it may not be appropriate. Discuss.
Can't hurt. It can be as simple as something that just recurses down into
the other directories and runs "make <target>" in there.
> 4) The 'important' file - the main file for the "source form" of the
> document - is the one with the same name as the directory, plus
> appropriate extension. For example, there is the directory
>
> /oswg/en_GB.ISO_8859-1/books/linux-c-programming
>
> When there's a document actually there, it will be
>
> /oswg/en_GB.ISO_8859-1/books/linux-c-programming/linux-c-programming.sgml
IMHO, bad idea. You've already got the name of the file in the directory,
duplicating it doesn't buy you anything. We found it was simpler to use a
common source name (book.sgml or article.sgml). Of course, YMMV.
> 5) Issue not addressed: how to deal with hyperlinks between documents.
> At this point I just want to let people start getting the source
> text in, and have someone else worry about how to hyperlink between
> documents when there are some documents to link between.
Talk to Norm Walsh. As I recall, the correct way to do this is with
OLINK (I'm getting fuzzy on the details here). There's an option in the
stylesheets whichs turns extra-document links in to calls to a CGI script,
which gets passed a parameter which specifies the document's logical name
(instead of its place in the filesystem). The CGI script then redirects
a browser to the right place.
At least, I think that's how it works. I haven't had a chance to look at
it too closely.
N
