Bug 34587

<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>

although, the first actually sounds a bit more 'realistic' as kernel.old 
would be a replaceable file, HOWEVER, the 'make install' would mv the 
kernel to kernel.old meaning it would be on the system regardless...

Anyone with more experiance wish to comment, maybe fill me in what to do 
here ;)

-- 
Tom (Darklogik) Rhodes
www.Pittgoth.com Gothic Liberation Front
www.FreeBSD.org  The Power To Serve

On Mon, Feb 04, 2002 at 08:40:04AM -0800, 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>

According to 'DocBook - The Definitive Guide' <command> describes
an executable program or a text of a command.  <replaceable> is listed
as valid content for <command>.

The <medialabel> tag seems similar to <command> (in usage terms) and
the following example is given:

| ... <medialabel>Backup <replaceable>nn</replaceable></medialabel>

Note that <replaceable> and a space are included in the medialabel
element.

>  although, the first actually sounds a bit more 'realistic' as kernel.old 
>  would be a replaceable file, HOWEVER, the 'make install' would mv the 
>  kernel to kernel.old meaning it would be on the system regardless...

Following the Guide, the content of <command> will be restricted to
#PCDATA, Replaceable, or InlineGraphic in DocBook 4.0, leaving
the first example.

>  Anyone with more experiance wish to comment, maybe fill me in what to do 
>  here ;)

Further comments are welcome too.

Martin

-- 
Marxpitn

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/

Comment 4 Giorgos Keramidas 2002-02-11 02:03:26 UTC

State Changed
From-To: open->closed

Fixed in revision 1.75 of file 
doc/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml 
Thanks :)