Date: Mon, 4 Feb 2002 19:10:02 -0800 (PST) From: Giorgos Keramidas <keramida@ceid.upatras.gr> To: freebsd-doc@freebsd.org Subject: Re: docs/34587: Adding Feedback on the issue Message-ID: <200202050310.g153A2u72664@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/34587; it has been noted by GNATS.
From: Giorgos Keramidas <keramida@ceid.upatras.gr>
To: Tom Rhodes <darklogik@pittgoth.com>
Cc: bug-followup@freebsd.org
Subject: Re: docs/34587: Adding Feedback on the issue
Date: Tue, 5 Feb 2002 05:00:19 +0200
On 2002-02-04 08:40, Tom Rhodes wrote:
> <command>boot <replaceable>kernel.old</replaceable></command>
>
> I just do not really agree with this line, should whitespace be in the
> actual tags, I think someone pointed out to me that no whitespace should
> exsist here. Something better would be:
>
> <command>boot</command> <replaceable>kernel.old</replaceable> or maybe
> <command>boot</command> <filename>kernel.old</filename>
The SGML markup is not a way to describe the 'format' of a document.
It is though something we (as in 'we the SGML fans of the universe')
use to denote the 'structure' of a document.
If you convert the initial SGML to a tree-like structure you'll get:
(outter
(command
"boot"
(whitespace)
(replaceable "kernel.old")))
The second one will be converted to:
(outter
(command "boot")
(whitespace)
(replaceable "kernel.old"))
The first rendering of the SGML entity clearly denotes that
<replaceable> is a "part of <command>".
What you suggest, looks a lot like what a user that reads the text on
screen would do to mark up documents using a WYSIWIG editor. But you
can't tell the computer that the <replaceable> entity is a part of the
<commmand> tag if you use this form of marking up documents. Then you
have lost part of the structural information that the original SGML
markup shows :(
Structure *is* important. Imagine an SGML parser that will swallow
the entire doc/ tree and look for complete <command> entities, and
spit out a shell script that has ALL the examples of the docs, ready
to be copy-pasted to a shell prompt. If you break the structure of
the entities, and <replaceable> is no longer a part of the original
<command> tag, then there is no way for the tool I described to know
where in the text of the document the parameters of the command are.
--
Giorgos Keramidas . . . . . . . . . keramida@{ceid.upatras.gr,freebsd.org}
FreeBSD Documentation Project . . . http://www.freebsd.org/docproj/
FreeBSD: The power to serve . . . . http://www.freebsd.org/
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?200202050310.g153A2u72664>