Date: Thu, 5 Nov 1998 20:06:28 +0000 From: Nik Clayton <nik@nothing-going-on.demon.co.uk> To: "Jason C. Wells" <jcwells@u.washington.edu>, FreeBSD-chat <freebsd-chat@FreeBSD.ORG> Subject: Re: Why SGML for docs? Message-ID: <19981105200628.55923@nothing-going-on.org> In-Reply-To: <Pine.BSF.4.05.9811042239450.8286-100000@s8-37-26.student.washington.edu>; from Jason C. Wells on Wed, Nov 04, 1998 at 10:45:45PM -0800 References: <Pine.BSF.4.05.9811042239450.8286-100000@s8-37-26.student.washington.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, Nov 04, 1998 at 10:45:45PM -0800, Jason C. Wells wrote:
> I have seen that FreeBSD makes calls for SGML documentation. I know HTML
> and it is easy and pretty powerful with HTML 4.0 and CSS.
>
> I took a peek and SGML and my hair turned white. My brief look at SGML led
> me to think HTML is pretty good. I don't need to look at SGML. I am happy
> with this small subset.
>
> What makes SGML useful for docs? Is it conversion tools for different
> formats? Is it the power?
You didn't look at SGML, you looked at DocBook. DocBook and HTML are both
languages that are defined using SGML.
DocBook is much more expressive than HTML, allowing it to be more precise,
more consistent, and, when I get the toolchain finished, much more useful
(automatic links to man page CGI scripts, better searching, conversion
to more formats).
For a gentler introduction to DocBook, take a look at
<URL:http://www.freebsd.org/~nik/hb/markup-guide.html>;
which is in the process of being massively expanded and revamped, and
<URL:http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html>;
which is a little more comprehensive. Either way, please stick around.
We need people to climb that learning curve and figure out how to document
it so that the people that come after you find it easier. Critique the
first one above, tell me what does and doesn't make sense.
N
--
C.R.F. Consulting -- we're run to make me richer. . .
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-chat" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19981105200628.55923>