Date: Fri, 15 May 1998 09:48:48 +0100 From: nik@iii.co.uk To: Sue Blake <sue@welearn.com.au> Cc: doc@FreeBSD.ORG Subject: Re: newbies resources page Message-ID: <19980515094848.64129@iii.co.uk> In-Reply-To: <19980515063350.38176@welearn.com.au>; from Sue Blake on Fri, May 15, 1998 at 06:33:50AM %2B1000 References: <19980505162032.31666@welearn.com.au> <19980514133926.32628@iii.co.uk> <19980514230445.50671@welearn.com.au> <19980514183700.65505@iii.co.uk> <19980515063350.38176@welearn.com.au>
next in thread | previous in thread | raw e-mail | index | archive | help
[ I'm going to cc: this to -doc, since it's probably useful for others
as well ]
On Fri, May 15, 1998 at 06:33:50AM +1000, Sue Blake wrote:
> OK, well here's where I'd got to already, without actually knowing SGML.
> With much determination I found a bunch of likely-looking files at
> ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/www/data/ and grabbed a
> few examples plus anything I didn't recognise as a web page.
>
> It looks like the first ten and last four lines are the same in each
> file.
<snip>
OK. Conceptually, this is how it works.
Each page is an amalgamation of data from at least two sources.
The first source is the page itself, such as 'newbies.sgml'. The second
source is from 'includes.sgml'.
includes.sgml defines a number of SGML entities. You're probably already
familiar with these if you've done any HTML authoring at all. Things
like · (the 'middle dot') or (non-breaking space) are examples
of simple entities that 'expand' into one or two characters.
But entities can be used to represent more than just one or two characters.
They can represent whole swathes of text, or even the contents of a
completely different file.
Looking at newbies.sgml from the top down:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
is the document type declaration. You've probably seen these before. But
note that this one isn't terminated with a '>', but instead continues with
a '['. This is the SGML way of saying that this declaration continues over
multiple lines, and will be terminated by a ']>' somewhere else.
<!ENTITY date "$Date$">
This defines an entity called 'date' which can be used in your document
by putting in the text '&date;'. The value of this entity (at this point)
is the string "$Date$".
"$Date$" is an example of an RCS tag.
As you know, the FreeBSD web site (and source code, and documentation) is
held in a source control system called CVS. CVS in turn uses a set of
programs that go under the general name 'RCS' to do a lot of the grunt
work.
One of RCS' more useful features is the ability to replace certain strings
in the document with specific values when the file is 'checked in' or
'checked out' of the control system. co(1) shows what these are. A look
at that shows that $Date$ will be expanded into the date and time the
file was checked in. This will be used a little later.
<!ENTITY title 'Resources for newbies'>
defines another entity, 'title', and gives it a value. In this case, a
simple string.
<!ENTITY % includes SYSTEM "includes.sgml"> %includes;
defines yet another entity, *and* uses it.
The first bit (up until the '>' character) defines a 'parameter entity';
This is different from the entities we've seen so far, in that it's been
prefixed by a '%' sign. The other entities are called 'general entities'
and are (when used) prefixed by an '&' sign.
The difference between them is as follows: you can use general entities
anywhere in your document *except* the DOCTYPE header. You can only use
parameter entities in the DOCTYPE header.
The use of 'SYSTEM "includes.sgml"' says that the text of this entity
is the entire text of the file 'includes.sgml'.
'%includes;' then means "include the contents of the entity %includes
at this point in the document.
The overall effect when an SGML processor handles this is that the
entire contents of includes.sgml are included right here.
]>
ends the document type declaration.
<!-- $Id$ -->
is another RCS tag. This will expand to the ID of this file (it's name,
when it was last edited, who by and so on) and be placed in an SGML comment
when the file is checked in.
<html>
&header;
This is the standard beginning of an HTML document. We then include the
&header; entity.
At this point you're probably thinking "Hang on, we haven't defined the
&header; entity anywhere in this document."
That's quite correct. But it *is* defined in 'includes.sgml'. Jumping out
of newbies.sgml for a second and looking at includes.sgml, you'll see this
in there:
<!ENTITY header '<head><title>&title;</title></head><BODY
TEXT="#000000" BGCOLOR="#FFFFFF" ALINK="#FFCC33"><IMG
SRC="&base/gifs/bar.gif" ALT="Navigation Bar" WIDTH="565" HEIGHT="33"
BORDER=0 usemap="#bar">
<H1 ALIGN=LEFT><FONT COLOR="#660000">&title;</FONT></H1><br clear=all>
<map name="bar">
...
</map>'>
(I've wrapped it, and removed some of the middle for brevity). As you can
see, this defines a multiline entity called 'header'. What's particularly
interesting is that this uses some other entities as well. You can see
the use of &base; and &title;. Remember that *we* defined the meaning of
&title; earlier on in the header.
So the two source documents (includes.sgml and newbies.sgml) each provide
different bits of the document.
> The bit in the middle is just straight HTML, sometimes in upper but
> more often in lower case, sometimes prefixing URLs with &base and
> sometimes not, and possibly using other cheats found in includes.sgml.
> There's a couple of lines with dollar signs in them which I'm not real
> sure about, but apparently I don't have to touch them.
That's pretty much it. The use of upper or lower case tags is pretty much
personal preference. I prefer lower case (and my editor is configured to
automatically use lower case) so that's what I use. The process of
converting the documents to complete SGML renders all the tags into
uppercase.
And the end of 'newbies.sgml' the '&footer;' reference pulls in the
footer entity, which looks like
<!ENTITY footer '<address>&author;<br>&date;</address>'>
which uses the &date; entity defined right at the start of the document.
> So what I figured was that I could use one of those files as a template,
> initially remove the stuff between dollar signs because it'd be wrong,
> put the level 1 heading in as the title in the third line and fill in my
> own text in the body.
That's pretty much it.
> > I've attached a copy of the SGML source that generates the HTML, so you
> > can see the changes I made.
>
> Now, looking at your attached file here I see some other differences.
> You've gone back to lower case, marked the list items as paragraphs, and
> pushed the indenting around a bit. Why? Anything else I've missed there?
Lower case I explained above. I did change the list items. You had
<li>text text text<p></p></li>
which is probably valid HTML, but isn't 'clean', so I changed it to
<li><p>text text text</p></li>
Technically, when a list item has only one paragraph there is no need
for the 'p' element at all. However, certain browsers will render the
above differently from
<li>text text text</li>
(they insert more white space in the first example than the second). In
the interests of future-proofing the document (what if, at some point,
one of the list items gains a second paragraph -- you would then need
to add 'p' elements to all the others as well) I added them around all
the list items now.
The indenting is pushed around because of my editor, which is set to
follow my personal preferences. I like to indent each new element
2 spaces from its parent element -- in emacs its very easy to have it
automatically reindent the entire document appropriately.
> The main problem that I have so far is that there's no way to see
> what it looks like and check the links when I'm finished, except for
> using a bit of imagination and lots of carefull eyeballing or modifying
> the file slightly to display it in a web browser.
For this you can use CVSup to download the entire web site. This includes
a 'Makefile' which you can use to turn individual pages into HTML with
% make newbies.html
or use it to build a local copy of the entire site with
% make
Hope that helps,
N
--
*DON'T DO THIS*. It is *BAD* engineering. *BAD* engineers
*DESERVE* to be unemployed, living under park benches, and
feeding off of slow moving pigeons
-- Terry Lambert, in comp.unix.bsd.freebsd.misc
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?19980515094848.64129>