Date: Sun, 1 Oct 2000 17:47:12 -0700 From: Brooks Davis <brooks@one-eyed-alien.net> To: Neil Blakey-Milner <nbm@mithrandr.moria.org> Cc: doc@freebsd.org Subject: Re: Making the handbook easier to use (part one) Message-ID: <20001001174712.A27211@Odin.AC.HMC.Edu> In-Reply-To: <20000929031023.A99079@mithrandr.moria.org>; from nbm@mithrandr.moria.org on Fri, Sep 29, 2000 at 03:10:24AM %2B0200 References: <20000929031023.A99079@mithrandr.moria.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Fri, Sep 29, 2000 at 03:10:24AM +0200, Neil Blakey-Milner wrote:
> The attached patch removes the scary bits that are
> contrib/chapter.sgml's contributor list and replaces it with a
> simple-to-use name|address to prevent messups and generally make it more
> the way I like it.
>
> I'm not sure what the rest of you think, but this is a test of making
> the handbook content easier to manipulate without docbook knowledge,
> possibly even easy to manipulate from a script. While this technique
> will probably work best with the web site, there are a few places in the
> doc tree that might benefit from this.
I don't buy the ease of contribution argument. The problem is that this
sort of thing seems like it's only going to work in cases like this one
where the learning curve is something like 5-10 seconds for anyone who's
ever used HTML before. I mean, there's nothing at all complicated about
(choosing a random entry from the list):
<listitem>
<para>Adam Baran <email>badam@mw.mil.pl</email></para>
</listitem>
I just can't see how this change eases the barriers to contribution.
On the other hand, I see two potential viable arguments for this change.
First, having the list in the actual chapter file seems bad to me in
that it makes editing the non-list text difficult. It seems that long
lists should be in their own files regardless of the issue of format.
Second, this non-SGML format is easier to keep in order with standard
tools like sort(1).
-- Brooks
--
Any statement of the form "X is the one, true Y" is FALSE.
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?20001001174712.A27211>