Descriptions (was: Examples)
- <quote who="Frugal" when="Wed, 7 Apr 2004 10:56:34 +0100 (BST)">
> <quote who="Keith Davies">[...snip...]
> > On Tue, Apr 06, 2004 at 11:56:32AM +0100, Frugal wrote:
> > >
> > > <description>
> > > <brief>One line desc</brief>
> > > <detailed><h3>Description</h3><p>This is the long desc</p></detailed>
> > Don't embed specific headings in it like this, I think. I can't think
> > of *too* many cases where entities will be complex enough to have their
> > own headings. The few that do would probably be better off with a more
> > generic <h> -- that can be picked up and formatted as needed for
> > whatever level it appears at. For instance, if we were dumping
> > everything to HTML and each class gets its own page, we might make them
> > <h2> (<h3> for nested ones); if they all go on a single page, they might
> > be <h3> or <h4> (with corresponding values for nested ones).
> Like you I can not think of any reason to have headings in a description,Rather than including the "heading" text in the body of the descriptive
> but I can certainly see a use for lists, emphasis etc.
text, it might be more useful to allow multiple descriptions for dividing up
the type of information for an entity. This would allow some OS to display
data with headings based on the sub-division type/kind - such as how feats,
skills, races, classes, &c. are shown in the PHB (e.g. for feats - there is a
brief one-line definition with no header of its own, followed by an optional
Prerequisites section, followed by a required Benefits section, followed by
an optional Special section.
This could be achieved like this, could it not:
<prereq kind="feat" key="feat.point-blank-shot" operator="<"
<description kind="definition">You are skilled at timing and aiming
<description kind="benefit">You can shoot or throw ranged weapons at an
opponent engaged in melee without taking the standard -4 penalty on your
<description kind="special">A character may gain this feat multiple
times. Its effects stack.</description>
Note that, there should not be a need for a specific tag for the
description of feat prerequisites, prestige class requirements, and the like
since the required values can be obtained from the name values of any feats,
variables, &c. mentioned in relevant <prereq ...> tags.
This does assume that there will be <prereq ...> tags for roleplaying
prerequisites, such as the following requirement for the assassin PrC: "The
character must kill someone for no other reason than to join the assassins."
As they're usually noted as "special" that could be used as the kind. E.g.:
<prereq kind="special">The character must kill someone for no other reason
than to join the assassins.</prereq>
> Out of interest what do people thin is the best way to allow an arbitraryI'd be inclined to go with option 2 (include the XHTML schema) but I'd also
> set of tags under a <description> tag ?
> - Explicitly specify which subset of HTML tags we allow?
> - include the XHTML schema and demand that the nested tags are all in the
> xhtml: namespace?
> - Can we even say "allow any valid XML content as a child of this tag and
> do not validate it against the current schema"? and if we can do we want
suggest that any documentation should advise best practices that are more
akin to option 1 (explicitly specify which subset of HTML tags we allow).
That is, technically anything goes, but, for the purposes of separating
content from presentation, only a small subset of tags are actually
Off the cuff, I'd restrict the "recommended HTML tags" to the following:
* CHARACTER: <em>; <strong>; <sub>; <sup>; <cite>;
* BLOCK: <p>; <pre>; <blockquote>;
* LIST: <ul>; <ol>; <li>; <dl>; <dt>; <dd>;
* OTHER: <br>; <a>;
I debated whether or not to include <a> in that list. I'm not really sure
it should be there
Jenni A. M. Merrifield (strawberry @ jamm . com)
Software User Experience Professional
Designing to Requirements and walking on Water is EASY. . .
. . . So long as both are Frozen.