screenshot instructions

[Paul W. Frields]

On Wed, 2004-09-01 at 08:20, Dashamir Hoxha wrote:
> On Wednesday 01 September 2004 12:58 pm, Karsten Wade wrote:
> > > * Everything inside a <screen> tag is assumed by default as
> > >   computeroutput, unless otherwise stated.
> >
> > Do you mean by "assumed by default as computeroutput" to mean, whenever
> > you use a <screen/> block, you will be surrounding a <computeroutput/>
> > block unless otherwise stated?
> 
> No, I mean that everything that is not tagged is assumed to be computer
> output. So, there should be no tag <computeroutput> inside a <screen> tag.

I ran into a situation while writing the mirror-tutorial where being
able to differentiate <userinput> from <computeroutput> inside a
<screen> tag would have come in handy. I didn't mention this in my last
e-mail because I thought it muddied the waters.

In a configuration file, frequently a tutorial will ask a user to modify
part of a configuration file, while giving some existing lines, or parts
thereof, for context. It seems to me that being able to delineate one
from the other is a good thing, to wit:

<screen>
  <computeroutput>
# The following line should be changed.
MyVariable = <userinput>NewValue</userinput>
MyVariableContext = default
  </computeroutput>
</screen>

It's possible to use <computeroutput> and <userinput> outside of
<screen>, for example in <para>. I like being able to search for
<screen> to quickly find my example screens that are set off from the
text in the HTML version that I'm reading. I think eliminating <screen>
is a bad thing, and the transforms we're using make <screen> stuff very
readable from a human interface perspective.

> > > * The prompt should be denoted like this: <prompt>bash#</prompt>
> > >   or <prompt>bash$</prompt> (depending on whether it is the root
> > >   or any user).
> >
> > The current usage is to not include a prompt.  Refer to the Note at the
> > bottom of this page:
> >
> > http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-prompt
> >.html
> >
> > Personally, I agree with this from an aesthetic viewpoint.
> >
> > Unless the point is to display the prompt for discussion, it is long and
> > clutters the view, confusing the reader with a big block of text that
> > may not even describe what they are looking at.
> 
> I think that a prompt like 'bash$' or 'bash#' is not confusing and it is even
> helpful. E.g. it makes clear immediatly that what follows is a command
> and whether this command needs to be executed as root or not.

The narrative should make this clear. Doing otherwise is lazy writing,
IMHO.

> > It seems redundant to put a <command> tag inside of a <userinput> tag
> 
> No, I don't mean inside a <userinput> tag, but without it (instead of it).
> A command is actually userinput, but the tag <command> describes it
> better (more specificly) than <userinput>.

> > Tough consensus to reach, apparently.  So much of this is up to style
> > and represents various levels of "correct".
> 
> If a consensus cannot be reached, then I think that it should not be
> included in the guide, or should be included like a suggestion, not
> like a rule that everybody has to follow.

Without having the rules in the Guide to begin with, I wouldn't have
been able to understand how to get started as an author. Remember that
rules don't just cause people to do everything the same way (although
that's very useful); they also make it easier for beginners to
understand how to do things acceptably. 

Or the editor fixes it the way they like, perhaps? "Suggestions" that
are made in place of what should be a rule simply encourage
discontinuity and chaos. This means the process from writing to posting
at &FDPDOCS-URL; will get longer, which is not something to aim for when
&FC; has such a short release cycle. Experts can always deviate
according to taste.

-- 
Paul W. Frields, RHCE