installation guide

[Mark Johnson]

Paul W. Frields wrote:
> On Tue, 2004-09-07 at 17:08, Stuart Ellis wrote:
> 
>>I've started to write a draft of the "Starting the Installation Program"
>>to see how it goes, and hit the first point requiring a screenshot.
>>
>>How should "needs screenshot" be marked ?  Should I put in a screenshot
>>(which can be discarded later), or just put a placeholder ?
> 
> 
> I would put in a comment that looks something like this:
> 
>   <!-- FIXME: screenshot needed, showing anaconda screen for
>        choosing mouse. -->

When I've got a section that needs fixing, I use a

<remark role="FIXME">FIXME: screenshot needed, showing anaconda 
screen for choosing mouse.<remark>

construct (although the role isn't really needed). Then I add the 
following snippet to the CSS stylesheet (we're talking about HTML 
output, right?)

.remark  { color: #0000FF;
            font-weight: bold;
            }

which generates a bold, blue statement, as e.g., can be seen here:

http://debian-xml-sgml.alioth.debian.org/xml-policy/xml-caching-resources.html

And I believe <remark>s need to be wrapped in a <para>s. 
Semantically, remark is recommended specifically for (you guessed 
it) remarks in draft documents, so at least there's some 
consistency. As it says in DocBook: The Defintive Guide:

remark — A remark (or comment) intended for presentation in a draft 
manuscript

I have similar stylesheet snippets for DSSSL print output, but not 
for XSL print output (yet:).

Of course, you can choose any color you wish.

Yet another option for FIXMEs...

HTH.

Cheers,
Mark


-- 
----------------------------------------------------------
Mark Johnson                     <mjohnson at redhat.com>
OS Product Documentation
Engineering, Red Hat, Inc.       <http://www.redhat.com>
Tel: 919.754.4151                Fax: 919.754.3708
GPG fp: DBEA FA3C C46A 70B5 F120  568B 89D5 4F61 C07D E242